Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,6 +1,12 @@
 {
- "current": "55ced50",
+ "current": "c9ad659 (c9ad659)",
  "releases": [
+  {
+   "version": "v29",
+   "sha": "55ced50",
+   "date": "2026-08-18",
+   "subject": "v29: the build staging has been running since 2026-08-18 (55ced50)."
+  },
   {
    "version": "v28",
    "sha": "2793e4b",

VERSION

@@ -1 +1 @@
-55ced50
+c9ad659 (c9ad659)

api/ai_review.py

@@ -56,7 +56,9 @@ PROVIDERS = [
     # labels it already has in front of it.
     {"name": "anthropic", "env": "ANTHROPIC_API_KEY", "shape": "anthropic",
      "url": "https://api.anthropic.com/v1/messages",
-     "model": "claude-haiku-4-5"},
+     # ⚠ AN ENV LEVER, NOT A NEW DEFAULT (W36-T35): haiku stays the choice for the reasons above,
+     # and a deployment whose side rungs are out of credit can raise the tier without a release.
+     "model": os.environ.get("AIOS_AI_REVIEW_ANTHROPIC_MODEL") or "claude-haiku-4-5"},
 ]
 ANTHROPIC_VERSION = "2023-06-01"
 TIMEOUT_SECONDS = float(os.environ.get("AIOS_AI_REVIEW_TIMEOUT") or 20)
@@ -277,13 +279,23 @@ MAX_DRAFT_ACTIONS = 12          # a draft a person reads in one screen; the engi
 MAX_PROMPT_CHARS = 2000
 
 
-def flow_providers():
-    """The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off."""
-    pin = (os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
+def flow_providers(pin=None):
+    """The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off.
+
+    ⭐ `pin` IS ASK D-18 (2026-08-18): the Agent chat's model toggle must configure something, and
+    the draft door used to read `prompt` off the body and nothing else — so the key the client sent
+    was accepted and dropped, and the picker was a control over nothing.
+    ⚠ AN UNKNOWN OR UNCONFIGURED PIN FALLS BACK TO THE LADDER rather than refusing. A model the
+    ladder stopped offering must not turn every later draft into an error; the caller is told which
+    rung actually answered, which is the honest half.
+    """
     by_name = {p["name"]: p for p in PROVIDERS}
-    order = [pin] if pin else list(FLOW_PROVIDER_ORDER)
-    return [by_name[n] for n in order
+    live = [n for n in FLOW_PROVIDER_ORDER
             if n in by_name and (os.environ.get(by_name[n]["env"]) or "").strip()]
+    wanted = str(pin or os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
+    if wanted and wanted in live:
+        return [by_name[wanted]]
+    return [by_name[n] for n in live]
 
 
 def flow_schema(kinds, trigger_keys, table_keys):
@@ -421,7 +433,7 @@ def _flow_from_tool_call(obj):
 
 
 def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeout=None,
-               st=None, user=""):
+               st=None, user="", model=None):
     """A sentence -> `(draft, refusal_sentence, provider)`. ⛔ NOTHING IS SAVED HERE.
 
     Exactly one of `draft` and `refusal_sentence` is truthy — the same contract
@@ -456,7 +468,7 @@ def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeou
         draft, refusal = _flow_from_tool_call(chat(messages, tools))
         return draft, refusal, "injected"
 
-    provs = flow_providers()
+    provs = flow_providers(model)
     if not provs:
         # ⛔ SAY SO. An AI feature that silently does nothing is indistinguishable from one that was
         # never built [[flag-shipped-without-its-writer]].
@@ -464,30 +476,53 @@ def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeou
                       "be drafted from a description yet"), None
     tmo = float(timeout or TIMEOUT_SECONDS)
     problems = []
+    import providers as _prov
     for p in provs:
-        if p["shape"] != "openai":
-            # Anthropic's tool transport differs; it stays on the ladder for `decide()` and is
-            # SKIPPED here rather than half-supported. Named in `problems` so it is not invisible.
-            problems.append(f"{p['name']}: tool calls are not wired for this shape")
-            continue
+        # ⭐⭐ W36-T35 / R4 — THE OWNER QUOTED THIS LINE BACK AT US. It used to read
+        # `problems.append(f"{p['name']}: tool calls are not wired for this shape")` and `continue`,
+        # so the sentence *"anthropic: tool calls are not wired for this shape"* appeared under the
+        # Agent module verbatim. R4: *"Anthropic becomes the tool-calling path that always works."*
+        # It is wired now, through the ONE wire in `providers`, and it matters more than it looks:
+        # every side rung on this account is refusing today (cerebras 402, groq 404, openrouter
+        # 402), so without this branch the drafter cannot answer at all.
+        # ⚠ NO `effort` ON THIS DOOR — `output_config.effort` errors on Haiku 4.5, the tier this
+        # ladder runs. The parameter is the caller's to send, which is why the wire takes it.
         try:
-            r = requests.post(p["url"], timeout=tmo,
-                              headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
-                                       "Content-Type": "application/json"},
-                              json={"model": p["model"], "messages": messages, "tools": tools,
-                                    "tool_choice": "required", "temperature": 0.1,
-                                    "max_tokens": 1500})
+            if p["shape"] == "anthropic":
+                req = _prov.anthropic_request(
+                    model=p["model"], key=os.environ[p["env"]].strip(), system=None,
+                    messages=messages, tools=tools, max_tokens=1500, tool_choice="required")
+                r = requests.post(req["url"], timeout=tmo,
+                                  headers=req["headers"], json=req["json"])
+            else:
+                r = requests.post(p["url"], timeout=tmo,
+                                  headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
+                                           "Content-Type": "application/json"},
+                                  json={"model": p["model"], "messages": messages, "tools": tools,
+                                        "tool_choice": "required", "temperature": 0.1,
+                                        "max_tokens": 1500})
         except Exception as e:                                    # noqa: BLE001
             problems.append(f"{p['name']}: {type(e).__name__}")
             continue
         if r.status_code != 200:
-            problems.append(f"{p['name']}: HTTP {r.status_code}")
+            # ⛔ A SENTENCE, NOT `HTTP 402` (R4's third clause). The owner read the status codes off
+            # this very door. `refusal_sentence` also decides whether this was a CREDIT failure, and
+            # the memo makes the next turn SKIP the empty account instead of paying for it again.
+            if _prov.is_credit_failure(r.status_code, r.text):
+                _prov.mark_no_credit(p["name"])
+            problems.append(_prov.refusal_sentence(p["name"], r.status_code, r.text))
             continue
         try:
             body = r.json()
-            calls = (((body.get("choices") or [{}])[0].get("message") or {})
-                     .get("tool_calls") or [])
-            args = json.loads(calls[0]["function"]["arguments"]) if calls else None
+            if p["shape"] == "anthropic":
+                _text, args, _refused = _prov.anthropic_read(body)
+                if _refused:
+                    problems.append(f"{p['name']}: {_refused}")
+                    continue
+            else:
+                calls = (((body.get("choices") or [{}])[0].get("message") or {})
+                         .get("tool_calls") or [])
+                args = json.loads(calls[0]["function"]["arguments"]) if calls else None
         except Exception as e:                                    # noqa: BLE001
             problems.append(f"{p['name']}: unreadable answer ({type(e).__name__})")
             continue

api/automation_engine.py

@@ -9219,6 +9219,36 @@ ACTION_CATALOG = [
      "ready": True,
      "detail": "Assemble this month's statements and park them for review. Nothing is sent until "
                "somebody opens the batch and clicks Send"},
+    # ⭐⭐ WAVE 36 · W36-T39 — D-277 CLOSED THE WAY THAT ROW ITSELF RECOMMENDED: *"an
+    # `ACTION_CATALOG` row with `menu: false` — one line, reusing the door R18 built this same wave
+    # to keep the five web kinds readable but unofferable. (a) looks right; it is E's file."*
+    #
+    # ⛔ THE DEFECT WAS A KIND IN NO CATALOG ON EITHER SIDE. `routes_automation._field_agent_rows`
+    # emits `flow.actions[0].kind == "ai_enrich"` for every AI-enrichment column in the tenant, and
+    # that string appeared ZERO times here and ZERO times in `aios-web/web/src/automation/`. The
+    # builder resolves a stored step's caption with `catalog.find(c => c.kind === a.kind)` and falls
+    # back to `a.kind`, so a field agent opened in the Agents module showed a RAW TOKEN.
+    #
+    # ⚠ `menu: False`, NEVER `ready: False`. `ready: False` renders as "coming soon" — a promise —
+    # and `clean_actions` refuses the kind outright, which would 400 the synthetic row the moment
+    # anything validated it. `menu: False` is the exact shape R18 built: withheld from the picker,
+    # still resolvable as a caption, still valid.
+    # ⛔ AND IT IS NOT ADDABLE BY HAND ON PURPOSE. An enrichment belongs to a COLUMN; the automation
+    # canvas is not where one is created, which is why `patch_automation` already refuses a
+    # `field:` id with "change its prompt, model or schedule on the column itself".
+    # ⭐⭐ AND A THIRD INSTANCE, FOUND BY W36-T39's OWN GATE ON ITS FIRST RUN. `_odoo_sync_row`
+    # emits `flow.actions[0].kind == "odoo_sync"` for the connector's synthetic schedule agent, and
+    # that kind was in no catalog either — the same raw token on the same screen as D-277, one row
+    # down. Two known instances were enough to justify the check; the check then produced a third
+    # nobody had booked, which is the difference between a gate and a regression test.
+    {"kind": "odoo_sync", "label": "Sync from Odoo", "group": "Connected",
+     "ready": True, "menu": False,
+     "detail": "Pull the connected Odoo databases on a schedule. Configured on the connector, not "
+               "here"},
+    {"kind": "ai_enrich", "label": "Enrich this column with AI", "group": "Connected",
+     "ready": True, "menu": False,
+     "detail": "Fill an AI column for the records this flow walks. Configured on the column, not "
+               "here"},
     {"kind": "slack", "label": "Send Slack message", "group": "Connected", "ready": False,
      "detail": "Needs the Slack connector"},
     # ── 4. ADVANCED LOGIC ────────────────────────────────────────────────────────────────────
@@ -9306,6 +9336,33 @@ def _tenant_may_use(kind, rt):
     return True if gate is None else bool(rt is not None and gate(rt))
 
 
+def catalog_kinds():
+    """Every action kind this module knows about — the LABEL vocabulary.
+
+    ⭐ D-277's WHOLE LESSON IN ONE SENTENCE: the client resolves a stored step's caption out of the
+    catalog and falls back to the raw kind token, so a kind the server can EMIT and the catalog
+    does not carry is a token on somebody's screen. This is the set that must cover every kind any
+    server path can put into a `flow.actions` entry, whether or not a person may add it.
+    """
+    return frozenset(str(row.get("kind") or "") for row in ACTION_CATALOG)
+
+
+def configurable_kinds():
+    """The kinds a PERSON may add from the picker, and must therefore be able to configure.
+
+    ⭐⭐ W36-T39 — THE CONTRACT BETWEEN THE TWO TREES, DERIVED AND NEVER LISTED. `ready` alone is
+    the wrong set: the five `web_*` kinds are ready and `menu: False` (R18), and `ai_enrich` is
+    ready and `menu: False` (D-277) — all six are real, runnable, captioned, and unofferable. What
+    a client must be able to CONFIGURE is exactly what a person can ADD.
+
+    ⛔ DERIVED FROM THE CATALOG, so a new row joins the contract by existing. A hand-kept list
+    would be a third copy of the vocabulary, and the two copies this ticket exists to reconcile
+    were already one too many.
+    """
+    return frozenset(str(row.get("kind") or "") for row in ACTION_CATALOG
+                     if row.get("ready") and row.get("menu", True) is not False)
+
+
 def action_catalog(rt=None):
     """The catalog as the wire carries it — a copy, because a caller that mutated the module
     constant would change every later reader's answer.
@@ -10831,6 +10888,32 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print
                         "and nothing was sent.")
                 counts["webBlocked"] += 1
                 continue
+            elif kind == "odoo_sync":
+                # Same refusal, same reason as the arm below: a catalog row with no arm is walked,
+                # counted, and reports success having done nothing. The connector owns this sync.
+                if "odoo_sync_not_run_here" not in web_notes:
+                    web_notes.append("odoo_sync_not_run_here")
+                    log("[aios-auto] odoo_sync: the Odoo pull runs on the connector's own "
+                        "schedule, not from this canvas. Nothing was done")
+                counts["webBlocked"] += 1
+                continue
+            elif kind == "ai_enrich":
+                # ⛔⛔ A REFUSAL ARM, AND IT EXISTS FOR THE REASON THE `send_statement` ARM ABOVE
+                # STATES: `_walk` has no terminal `else`, so a catalog row whose arm is missing is
+                # walked, COUNTED, reports the run `ok` and writes nothing — a step somebody
+                # configured that succeeds at doing nothing. Adding the row (D-277) without this
+                # arm would have opened exactly that window.
+                # ⚠ AND THE REFUSAL IS THE TRUTH, not a stub. An AI column is filled by
+                # `ai_enrich`, driven from the column's own editor; the synthetic agent row this
+                # kind appears in is DERIVED from that column and is never stored, so nothing
+                # reaches here through the ordinary path. If something ever does, it must say so
+                # rather than report success.
+                if "ai_enrich_not_run_here" not in web_notes:
+                    web_notes.append("ai_enrich_not_run_here")
+                    log("[aios-auto] ai_enrich: an AI column is filled from the column's own "
+                        "editor, not from this canvas. Nothing was done")
+                counts["webBlocked"] += 1
+                continue
             elif kind == "ai_agent":
                 # ⭐⭐ W33-T56 (owner item 7, ruling R3) — THE FUZZY STEP, AT RUN TIME.
                 #

api/connectors_tt.py

@@ -1,568 +1,568 @@
-"""connectors_tt.py — the TIKTOK connector (wave 29 · item 7 · DEBT D-9 · rulings R1 + R2).
-
-Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
-automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
-exists at all rather than another thousand lines inside the engine.
-
-⛔ **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema — 40 profile / 43
-post / 17 comment fields, each with the vendor's own type, description and `pii` flag — was read
-live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
-`.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
-close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
-name below reads through a candidate list it is because the vendor has two names for one fact
-(`biography`/`signature`, `region`/`country`), never because the name is uncertain.
-
-⛔ **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned —
-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 `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 — 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.
-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
-     envelope keys (`timestamp`, `input`) that no metadata call mentions;
-  2. that a declared field POPULATES — Bright Data's Instagram Reels *declares* `views: number`
-     and delivers an account-grain wrong number (§4e). **Declared is not delivered**, and the one
-     TikTok claim that matters most (`play_count`) is exactly a declaration.
-"""
-from __future__ import annotations
-
-import automation_engine as engine
-# ⚠ 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_scrape,
-)
-
-# ---------------------------------------------------------------------------------------------
-# THE DATASETS
-# ---------------------------------------------------------------------------------------------
-# ⚠ CATALOGUE PRESENCE IS NOT ENTITLEMENT — the same finding Instagram produced. `GET
-# /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
-# full field list, and the two DISCOVERY halves answer **404 for our key**:
-#   `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
-# ⇒ TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
-# does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
-TT_DS_PROFILES = "gd_l1villgoiiidt09ci"       # TikTok - Profiles. 40 fields, 152,000,000 records
-TT_DS_POSTS = "gd_lu702nij2f790tmv9h"         # TikTok - Posts. 43 fields
-TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k"      # TikTok - Comments. 17 fields
-
-#: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
-#: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
-TT_POST_TYPE_VIDEO = "video"
-TT_POST_TYPE_CONTENT = "content"
-
-#: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
-#: beside the dataset ids because it is the same class of vendor fact.
-#: ⚠ ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
-#: string from `_PROFILE_RULES` (contract C2, E's half) — this exists for the connector's own
-#: batch calls, and the gate asserts the two agree rather than trusting that they do.
-TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
-
-
-def tt_profile_url(handle):
-    """`nurilab` → `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
-    h = str(handle or "").strip().lstrip("@")
-    return TT_PROFILE_URL.format(handle=h) if h else ""
-
-
-# ---------------------------------------------------------------------------------------------
-# THE FIELD MAPS
-# ---------------------------------------------------------------------------------------------
-# Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
-# in `automation_engine`. The rules they all obey, stated once:
-#
-#   * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
-#     so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
-#     returns `None` (never 0) when nothing matches, which is what makes that possible.
-#   * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
-#     rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
-#   * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
-#     vendor's side is preserved rather than silently discarded while our column model catches up.
-#   * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
-#     (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
-#     ride in `source_payload` where they make no claim.
-
-
-def _tt_str(node, *names):
-    """The first non-empty string among `names`, or None when the vendor sent nothing.
-
-    ⛔ `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest —
-    an empty string written into a cell claims "we looked and it is empty".
-    """
-    v = _first(node, *names)
-    if v is None:
-        return None
-    s = str(v).strip()
-    return s or None
-
-
-def _tt_pct(node, *names):
-    """A vendor 0–1 engagement fraction → our stored 0–100 percentage, or None.
-
-    ⛔ THE ×100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
-    the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` —
-    measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
-    """
-    v = _first(node, *names)
-    if v is None:
-        return None
-    out = engine._pct100(v)
-    return out or None
-
-
-def _tt_day(node, *names):
-    """A vendor stamp → `YYYY-MM-DD`, or None. Our `date` columns store a day."""
-    v = _first(node, *names)
-    if v is None:
-        return None
-    return engine._day(v) or None
-
-
-def _drop_blanks(row):
-    """The one place a mapped row loses its `None`s — see the BLANK MEANS NOT READ rule above."""
-    return {k: v for k, v in row.items() if v is not None and v != ""}
-
-
-def normalize_profile(node, handle=""):
-    """A TikTok Profiles row → the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
-
-    ⚠ TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
-      * `biography` is PRIMARY and `signature` the FALLBACK — the probe measured `signature`
-        populated on 85% of rows and they carry the same text;
-      * `region` is PRIMARY and `country` the FALLBACK — `region` is the one with a documented
-        two-letter-ISO description, `country` has no description at all.
-    ⚠ `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
-    `ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
-    only count of its kind the dataset offers.
-    """
-    node = node if isinstance(node, dict) else {}
-    account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
-    return _drop_blanks({
-        "platform": engine.PLATFORM_TIKTOK,
-        "handle": account,
-        "full_name": _tt_str(node, "nickname"),
-        "tt_id": _tt_str(node, "id"),
-        "profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
-        "bio": _tt_str(node, "biography", "signature"),
-        "external_url": _bd_first_url(_first(node, "bio_link")),
-        "verified": _bd_flag(node, "is_verified"),
-        "is_private": _bd_flag(node, "is_private"),
-        # ⚠ APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
-        # on their own description. It is the closest thing TikTok has to Instagram's
-        # `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent — so
-        # the approximation only ever fills a cell the vendor actually answered.
-        "is_business": _bd_flag(node, "is_commerce_user"),
-        "followers": _ig_int(_first(node, "followers")),
-        "following": _ig_int(_first(node, "following")),
-        "posts_count": _ig_int(_first(node, "videos_count")),
-        # ⚠ `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
-        # nulls). It is not a post-level number and it is not our `likes` column, which is why it
-        # is stored under a different name.
-        "likes_received": _ig_int(_first(node, "likes")),
-        "avg_engagement": _tt_pct(node, "awg_engagement_rate"),
-        "like_engagement": _tt_pct(node, "like_engagement_rate"),
-        "comment_engagement": _tt_pct(node, "comment_engagement_rate"),
-        "country_code": _tt_str(node, "region", "country"),
-        "region": _tt_str(node, "region"),
-        "predicted_lang": _tt_str(node, "predicted_lang"),
-        # ⚠ ACCOUNT AGE, NOT A MEASUREMENT STAMP — `create_time` on a profile is when the ACCOUNT
-        # was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
-        # which is why the append law dates a snapshot by when WE read it.
-        "account_created_at": _tt_day(node, "create_time"),
-        "source_payload": _bd_source_payload(node),
-    })
-
-
-def tt_post_type(node):
-    """A TikTok post row → one of OUR three type options, or None.
-
-    ⛔ THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
-    `"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
-    vendor's token would fail `_clean_field`'s option check on the way in and would put an
-    untranslated API word in front of a user on the way out.
-
-    So: `video` is `video`, and `content` — TikTok's photo-mode post — is `image`, EXCEPT when the
-    row carries more than one `carousel_images` entry, which is what a carousel IS on either
-    network. ⚠ The multi-image branch is decided from the IMAGES, never from the type token: the
-    token cannot express it, so inferring `carousel` from the word would be inventing a fact.
-    ⚠ An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
-    that is exactly what would make the wrong default invisible).
-    """
-    raw = str((node or {}).get("post_type") or "").strip().lower()
-    if raw == TT_POST_TYPE_VIDEO:
-        return "video"
-    if raw != TT_POST_TYPE_CONTENT:
-        return None
-    images = (node or {}).get("carousel_images")
-    return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
-
-
-def normalize_post(node):
-    """A TikTok Posts row → the `ut_tt_posts` cell shape. None when it carries no identity.
-
-    ⛔ THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
-    Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
-    fact — `play_count` IS the count TikTok displays under a video — so it maps to `views` and
-    `ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
-    manufacture a second measurement that a rollup could average or double-count, which is a worse
-    outcome than the missing column it would paper over.
-
-    ⚠ `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
-    the probe measured them as the same shape. That equality is what lets the comments→posts link
-    join with NO normaliser, which the Instagram side never had.
-    ⚠ `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
-    ⚠ `commerce_info` is a business/commerce LOCATION per its own description — cities and
-    countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
-    no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
-    """
-    node = node if isinstance(node, dict) else {}
-    shortcode = _tt_str(node, "shortcode", "post_id")
-    if not shortcode:
-        return None
-    return _drop_blanks({
-        "platform": engine.PLATFORM_TIKTOK,
-        "shortcode": shortcode,
-        # ⛔⛔ `account_id`, NOT `profile_username` — MEASURED on a real Posts row 2026-08-12.
-        # The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
-        # @handle (`"d1na_th"`) — the same field `normalize_profile` already reads for `handle`, so
-        # one name means one thing across both corpora. Reading the display name silently broke the
-        # only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
-        # NOTHING, so a person could not filter posts by creator and a rollup would count zero.
-        # ⚠ NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
-        # different fact, and filling a join key with it is worse than leaving it blank — a blank
-        # is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
-        # The URL is the honest second source: it carries the handle by construction.
-        "influencer_key": (_tt_str(node, "account_id")
-                           or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
-        "posted_at": _tt_day(node, "create_time"),
-        "type": tt_post_type(node),
-        "caption": _tt_str(node, "description"),
-        "url": _tt_str(node, "url"),
-        "hashtags": _bd_list(node, "hashtags"),
-        "tagged_location": _tt_str(node, "commerce_info"),
-        "views": _ig_int(_first(node, "play_count")),
-        "likes": _ig_int(_first(node, "digg_count")),
-        "comments": _ig_int(_first(node, "comment_count")),
-        "shares": _ig_int(_first(node, "num_share_count")),
-        "saves": _ig_int(_first(node, "collect_count")),
-        "video_duration": _ig_int(_first(node, "video_duration")),
-        "source_payload": _bd_source_payload(node),
-    })
-
-
-def normalize_comment(node):
-    """A TikTok Comments row → the `ut_tt_comments` cell shape. None without a comment id.
-
-    ⚠ THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
-    `replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
-    `source_payload`. Reading the array's length instead would be a second, disagreeing answer to
-    a question the vendor already answers — and it would disagree, because a page of replies is not
-    all of them.
-    ⚠ `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
-    text and needs defensive parsing. It still goes through `_tt_day` — one date path, so a vendor
-    that changes its mind cannot change ours.
-    ⚠ The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
-    PII) stay in `source_payload` and are promoted to no column, which is the same posture the
-    Instagram comment schema takes for the same D-24 reason.
-    """
-    node = node if isinstance(node, dict) else {}
-    comment_key = _tt_str(node, "comment_id")
-    if not comment_key:
-        return None
-    return _drop_blanks({
-        "platform": engine.PLATFORM_TIKTOK,
-        "comment_key": comment_key,
-        "shortcode": _tt_str(node, "post_id"),
-        # ⭐⭐ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
-        # vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
-        # primary first, so a row carrying the rich form is not silently served the plain one.
-        # ⛔ The commenter's identity is deliberately NOT promoted — see `TT_COMMENT_FIELDS`.
-        "text": _tt_str(node, "comment_text", "comment_text_only"),
-        "commented_at": _tt_day(node, "date_created"),
-        "likes": _ig_int(_first(node, "num_likes")),
-        "replies": _ig_int(_first(node, "num_replies")),
-        "source_payload": _bd_source_payload(node),
-    })
-
-
-#: ⭐ The three maps, addressable by name — so a gate (and the runners in T04-T06) can walk them
-#: rather than naming three functions, and so adding a fourth dataset is one entry.
-TT_NORMALIZERS = {
-    "tt_profile": normalize_profile,
-    "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. `top_videos` rides the PROFILE row
-    we have already bought, so the posts read is a scrape of links 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.
-
-    ⛔⛔ CORRECTED 2026-08-12 — THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
-    array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
-    read `/datasets/{id}/metadata` — a DATASET description — and the phrase quoted was the field's
-    `ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
-    (measured below), so the reader built against the quoted sentence found nothing, forever, in
-    silence. ⭐ The transferable half: *"the probe measured X"* and *"the probe read a declaration
-    of X"* are different claims, and prose cannot be told apart by a reader downstream — which is
-    why the correction names the method, not just the value.
-
-    ⚠ `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 []:
-        # ⛔⛔ MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
-        # `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
-        # live handle returns **19 DICTS**, keyed
-        # `video_url · video_id · playcount · diggcount · commentcount · share_count ·
-        #  favorites_count · create_date · cover_image`.
-        # The docstring above cites the $0 probe as having "measured" permalinks — it had not, and
-        # could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
-        # so in terms (*"what $0 cannot buy … the real ROW shape … that a declared field
-        # POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
-        # declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
-        # the first. [[reachable-is-not-the-same-as-built]]
-        # ⇒ The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
-        # list on every real profile — post capture could not have worked for anybody, and the
-        # T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
-        # written from a schema tests the schema.
-        # ⚠ `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
-        # because it costs nothing and is what a future corpus revision would most likely use. The
-        # bare-string branch stays for the same reason — this widens what is ACCEPTED and invents
-        # nothing: a shape that yields no `http…` value still degrades to "no posts", exactly as
-        # before, rather than to a URL built out of a guess.
-        # ⚠ `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
-        # whichever array happened to be longer is how one creator's window silently differs from
-        # another's, and that reasoning is unchanged by this correction.
-        if isinstance(item, dict):
-            u = str(item.get("video_url") or item.get("url") or "").strip()
-        else:
-            u = 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 ""}
+"""connectors_tt.py — the TIKTOK connector (wave 29 · item 7 · DEBT D-9 · rulings R1 + R2).
+
+Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
+automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
+exists at all rather than another thousand lines inside the engine.
+
+⛔ **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema — 40 profile / 43
+post / 17 comment fields, each with the vendor's own type, description and `pii` flag — was read
+live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
+`.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
+close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
+name below reads through a candidate list it is because the vendor has two names for one fact
+(`biography`/`signature`, `region`/`country`), never because the name is uncertain.
+
+⛔ **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned —
+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 `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 — 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.
+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
+     envelope keys (`timestamp`, `input`) that no metadata call mentions;
+  2. that a declared field POPULATES — Bright Data's Instagram Reels *declares* `views: number`
+     and delivers an account-grain wrong number (§4e). **Declared is not delivered**, and the one
+     TikTok claim that matters most (`play_count`) is exactly a declaration.
+"""
+from __future__ import annotations
+
+import automation_engine as engine
+# ⚠ 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_scrape,
+)
+
+# ---------------------------------------------------------------------------------------------
+# THE DATASETS
+# ---------------------------------------------------------------------------------------------
+# ⚠ CATALOGUE PRESENCE IS NOT ENTITLEMENT — the same finding Instagram produced. `GET
+# /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
+# full field list, and the two DISCOVERY halves answer **404 for our key**:
+#   `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
+# ⇒ TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
+# does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
+TT_DS_PROFILES = "gd_l1villgoiiidt09ci"       # TikTok - Profiles. 40 fields, 152,000,000 records
+TT_DS_POSTS = "gd_lu702nij2f790tmv9h"         # TikTok - Posts. 43 fields
+TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k"      # TikTok - Comments. 17 fields
+
+#: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
+#: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
+TT_POST_TYPE_VIDEO = "video"
+TT_POST_TYPE_CONTENT = "content"
+
+#: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
+#: beside the dataset ids because it is the same class of vendor fact.
+#: ⚠ ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
+#: string from `_PROFILE_RULES` (contract C2, E's half) — this exists for the connector's own
+#: batch calls, and the gate asserts the two agree rather than trusting that they do.
+TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
+
+
+def tt_profile_url(handle):
+    """`nurilab` → `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
+    h = str(handle or "").strip().lstrip("@")
+    return TT_PROFILE_URL.format(handle=h) if h else ""
+
+
+# ---------------------------------------------------------------------------------------------
+# THE FIELD MAPS
+# ---------------------------------------------------------------------------------------------
+# Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
+# in `automation_engine`. The rules they all obey, stated once:
+#
+#   * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
+#     so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
+#     returns `None` (never 0) when nothing matches, which is what makes that possible.
+#   * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
+#     rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
+#   * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
+#     vendor's side is preserved rather than silently discarded while our column model catches up.
+#   * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
+#     (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
+#     ride in `source_payload` where they make no claim.
+
+
+def _tt_str(node, *names):
+    """The first non-empty string among `names`, or None when the vendor sent nothing.
+
+    ⛔ `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest —
+    an empty string written into a cell claims "we looked and it is empty".
+    """
+    v = _first(node, *names)
+    if v is None:
+        return None
+    s = str(v).strip()
+    return s or None
+
+
+def _tt_pct(node, *names):
+    """A vendor 0–1 engagement fraction → our stored 0–100 percentage, or None.
+
+    ⛔ THE ×100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
+    the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` —
+    measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
+    """
+    v = _first(node, *names)
+    if v is None:
+        return None
+    out = engine._pct100(v)
+    return out or None
+
+
+def _tt_day(node, *names):
+    """A vendor stamp → `YYYY-MM-DD`, or None. Our `date` columns store a day."""
+    v = _first(node, *names)
+    if v is None:
+        return None
+    return engine._day(v) or None
+
+
+def _drop_blanks(row):
+    """The one place a mapped row loses its `None`s — see the BLANK MEANS NOT READ rule above."""
+    return {k: v for k, v in row.items() if v is not None and v != ""}
+
+
+def normalize_profile(node, handle=""):
+    """A TikTok Profiles row → the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
+
+    ⚠ TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
+      * `biography` is PRIMARY and `signature` the FALLBACK — the probe measured `signature`
+        populated on 85% of rows and they carry the same text;
+      * `region` is PRIMARY and `country` the FALLBACK — `region` is the one with a documented
+        two-letter-ISO description, `country` has no description at all.
+    ⚠ `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
+    `ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
+    only count of its kind the dataset offers.
+    """
+    node = node if isinstance(node, dict) else {}
+    account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
+    return _drop_blanks({
+        "platform": engine.PLATFORM_TIKTOK,
+        "handle": account,
+        "full_name": _tt_str(node, "nickname"),
+        "tt_id": _tt_str(node, "id"),
+        "profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
+        "bio": _tt_str(node, "biography", "signature"),
+        "external_url": _bd_first_url(_first(node, "bio_link")),
+        "verified": _bd_flag(node, "is_verified"),
+        "is_private": _bd_flag(node, "is_private"),
+        # ⚠ APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
+        # on their own description. It is the closest thing TikTok has to Instagram's
+        # `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent — so
+        # the approximation only ever fills a cell the vendor actually answered.
+        "is_business": _bd_flag(node, "is_commerce_user"),
+        "followers": _ig_int(_first(node, "followers")),
+        "following": _ig_int(_first(node, "following")),
+        "posts_count": _ig_int(_first(node, "videos_count")),
+        # ⚠ `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
+        # nulls). It is not a post-level number and it is not our `likes` column, which is why it
+        # is stored under a different name.
+        "likes_received": _ig_int(_first(node, "likes")),
+        "avg_engagement": _tt_pct(node, "awg_engagement_rate"),
+        "like_engagement": _tt_pct(node, "like_engagement_rate"),
+        "comment_engagement": _tt_pct(node, "comment_engagement_rate"),
+        "country_code": _tt_str(node, "region", "country"),
+        "region": _tt_str(node, "region"),
+        "predicted_lang": _tt_str(node, "predicted_lang"),
+        # ⚠ ACCOUNT AGE, NOT A MEASUREMENT STAMP — `create_time` on a profile is when the ACCOUNT
+        # was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
+        # which is why the append law dates a snapshot by when WE read it.
+        "account_created_at": _tt_day(node, "create_time"),
+        "source_payload": _bd_source_payload(node),
+    })
+
+
+def tt_post_type(node):
+    """A TikTok post row → one of OUR three type options, or None.
+
+    ⛔ THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
+    `"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
+    vendor's token would fail `_clean_field`'s option check on the way in and would put an
+    untranslated API word in front of a user on the way out.
+
+    So: `video` is `video`, and `content` — TikTok's photo-mode post — is `image`, EXCEPT when the
+    row carries more than one `carousel_images` entry, which is what a carousel IS on either
+    network. ⚠ The multi-image branch is decided from the IMAGES, never from the type token: the
+    token cannot express it, so inferring `carousel` from the word would be inventing a fact.
+    ⚠ An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
+    that is exactly what would make the wrong default invisible).
+    """
+    raw = str((node or {}).get("post_type") or "").strip().lower()
+    if raw == TT_POST_TYPE_VIDEO:
+        return "video"
+    if raw != TT_POST_TYPE_CONTENT:
+        return None
+    images = (node or {}).get("carousel_images")
+    return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
+
+
+def normalize_post(node):
+    """A TikTok Posts row → the `ut_tt_posts` cell shape. None when it carries no identity.
+
+    ⛔ THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
+    Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
+    fact — `play_count` IS the count TikTok displays under a video — so it maps to `views` and
+    `ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
+    manufacture a second measurement that a rollup could average or double-count, which is a worse
+    outcome than the missing column it would paper over.
+
+    ⚠ `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
+    the probe measured them as the same shape. That equality is what lets the comments→posts link
+    join with NO normaliser, which the Instagram side never had.
+    ⚠ `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
+    ⚠ `commerce_info` is a business/commerce LOCATION per its own description — cities and
+    countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
+    no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
+    """
+    node = node if isinstance(node, dict) else {}
+    shortcode = _tt_str(node, "shortcode", "post_id")
+    if not shortcode:
+        return None
+    return _drop_blanks({
+        "platform": engine.PLATFORM_TIKTOK,
+        "shortcode": shortcode,
+        # ⛔⛔ `account_id`, NOT `profile_username` — MEASURED on a real Posts row 2026-08-12.
+        # The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
+        # @handle (`"d1na_th"`) — the same field `normalize_profile` already reads for `handle`, so
+        # one name means one thing across both corpora. Reading the display name silently broke the
+        # only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
+        # NOTHING, so a person could not filter posts by creator and a rollup would count zero.
+        # ⚠ NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
+        # different fact, and filling a join key with it is worse than leaving it blank — a blank
+        # is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
+        # The URL is the honest second source: it carries the handle by construction.
+        "influencer_key": (_tt_str(node, "account_id")
+                           or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
+        "posted_at": _tt_day(node, "create_time"),
+        "type": tt_post_type(node),
+        "caption": _tt_str(node, "description"),
+        "url": _tt_str(node, "url"),
+        "hashtags": _bd_list(node, "hashtags"),
+        "tagged_location": _tt_str(node, "commerce_info"),
+        "views": _ig_int(_first(node, "play_count")),
+        "likes": _ig_int(_first(node, "digg_count")),
+        "comments": _ig_int(_first(node, "comment_count")),
+        "shares": _ig_int(_first(node, "num_share_count")),
+        "saves": _ig_int(_first(node, "collect_count")),
+        "video_duration": _ig_int(_first(node, "video_duration")),
+        "source_payload": _bd_source_payload(node),
+    })
+
+
+def normalize_comment(node):
+    """A TikTok Comments row → the `ut_tt_comments` cell shape. None without a comment id.
+
+    ⚠ THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
+    `replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
+    `source_payload`. Reading the array's length instead would be a second, disagreeing answer to
+    a question the vendor already answers — and it would disagree, because a page of replies is not
+    all of them.
+    ⚠ `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
+    text and needs defensive parsing. It still goes through `_tt_day` — one date path, so a vendor
+    that changes its mind cannot change ours.
+    ⚠ The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
+    PII) stay in `source_payload` and are promoted to no column, which is the same posture the
+    Instagram comment schema takes for the same D-24 reason.
+    """
+    node = node if isinstance(node, dict) else {}
+    comment_key = _tt_str(node, "comment_id")
+    if not comment_key:
+        return None
+    return _drop_blanks({
+        "platform": engine.PLATFORM_TIKTOK,
+        "comment_key": comment_key,
+        "shortcode": _tt_str(node, "post_id"),
+        # ⭐⭐ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
+        # vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
+        # primary first, so a row carrying the rich form is not silently served the plain one.
+        # ⛔ The commenter's identity is deliberately NOT promoted — see `TT_COMMENT_FIELDS`.
+        "text": _tt_str(node, "comment_text", "comment_text_only"),
+        "commented_at": _tt_day(node, "date_created"),
+        "likes": _ig_int(_first(node, "num_likes")),
+        "replies": _ig_int(_first(node, "num_replies")),
+        "source_payload": _bd_source_payload(node),
+    })
+
+
+#: ⭐ The three maps, addressable by name — so a gate (and the runners in T04-T06) can walk them
+#: rather than naming three functions, and so adding a fourth dataset is one entry.
+TT_NORMALIZERS = {
+    "tt_profile": normalize_profile,
+    "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. `top_videos` rides the PROFILE row
+    we have already bought, so the posts read is a scrape of links 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.
+
+    ⛔⛔ CORRECTED 2026-08-12 — THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
+    array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
+    read `/datasets/{id}/metadata` — a DATASET description — and the phrase quoted was the field's
+    `ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
+    (measured below), so the reader built against the quoted sentence found nothing, forever, in
+    silence. ⭐ The transferable half: *"the probe measured X"* and *"the probe read a declaration
+    of X"* are different claims, and prose cannot be told apart by a reader downstream — which is
+    why the correction names the method, not just the value.
+
+    ⚠ `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 []:
+        # ⛔⛔ MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
+        # `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
+        # live handle returns **19 DICTS**, keyed
+        # `video_url · video_id · playcount · diggcount · commentcount · share_count ·
+        #  favorites_count · create_date · cover_image`.
+        # The docstring above cites the $0 probe as having "measured" permalinks — it had not, and
+        # could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
+        # so in terms (*"what $0 cannot buy … the real ROW shape … that a declared field
+        # POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
+        # declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
+        # the first. [[reachable-is-not-the-same-as-built]]
+        # ⇒ The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
+        # list on every real profile — post capture could not have worked for anybody, and the
+        # T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
+        # written from a schema tests the schema.
+        # ⚠ `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
+        # because it costs nothing and is what a future corpus revision would most likely use. The
+        # bare-string branch stays for the same reason — this widens what is ACCEPTED and invents
+        # nothing: a shape that yields no `http…` value still degrades to "no posts", exactly as
+        # before, rather than to a URL built out of a guess.
+        # ⚠ `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
+        # whichever array happened to be longer is how one creator's window silently differs from
+        # another's, and that reasoning is unchanged by this correction.
+        if isinstance(item, dict):
+            u = str(item.get("video_url") or item.get("url") or "").strip()
+        else:
+            u = 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

@@ -85,6 +85,8 @@ import routes_slack  # noqa: E402  (wave 33 R4/C2 — Manage agent + the Slack d
 import routes_starred  # noqa: E402  (wave 35 R4/C2/C3/C5 — the star; E's router, E's line)
 import routes_usage  # noqa: E402  (wave 35 R9/C7 — the AI usage meter; E's router, E's line)
 import routes_feedback  # noqa: E402  (wave 35 R8/C6 — feedback to the operator plane; E's router)
+import routes_agent_harness  # noqa: E402  (wave 36 R8/C4 — the agent harness store; E's router)
+import routes_script_views  # noqa: E402  (wave 36 R3/R10/C3 — script Views; E's router)
 from core import grid_events  # noqa: E402
 # D-315 / D-305 (2026-08-18) — the two store REFUSALS get their own app-level handlers below.
 # ⚠ Neither is a `StoreUnavailable` subclass, on purpose: routes that degrade a store outage into a
@@ -376,6 +378,23 @@ app.include_router(routes_usage.router)       # R9 / C7 — GET /usage, the one
 # POST is any authenticated session's own act, the GET is `is_platform_admin` only. Mounting it does
 # not widen anything a tenant admin can reach — `verify_api` proves that by having one try.
 app.include_router(routes_feedback.router)    # R8 / C6 — feedback to the operator plane
+# ⭐⭐ WAVE 36 (R8 / C4) — THE AGENT HARNESS FILE STORE, mounted in the SAME change that created
+# `routes_agent_harness.py`. Eighth consecutive wave in which this block is the artefact the
+# protocol nearly loses; `verify_web_agent::section_w36_harness` asserts this path in
+# `app.openapi()["paths"]` and CALLS the route, because mounted is not callable (D-107).
+# ⚠ Placement, as for every line above: ABOVE `app.mount("/", _AppStatic(...), html=True)` at the
+# end of this file, or a GET answers 404 and a PUT answers 405 while every gate stays green.
+# ⛔ ITS PATHS SIT UNDER `/agents/{id}/...`, WHICH `routes_slack` ALSO SERVES — and that is safe
+# rather than lucky: a FastAPI path parameter never spans a `/`, so `/agents/{agent_id}` cannot
+# match `/agents/x/harness`. The two routers share a prefix and no route.
+app.include_router(routes_agent_harness.router)  # R8 / C4 — versioned agent harness files
+# ⭐⭐ WAVE 36 (R3 / R10 / C3) — THE SCRIPT VIEW, owner item 6. Mounted in the SAME change that
+# created `routes_script_views.py`; `verify_script_views.py` asserts both of its paths in
+# `app.openapi()["paths"]` AND calls them, and its NC comments this line out.
+# ⛔ ITS RUN DOOR SPAWNS A SUBPROCESS AND IS A PLAIN `def`, so FastAPI runs it in the threadpool.
+# Mounting it does not put a ten-second wait anywhere near the event loop; the router's own header
+# says why that is not a style choice.
+app.include_router(routes_script_views.router)   # R3 / R10 / C3 — code-script database Views
 
 
 # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)

api/providers.py

@@ -124,7 +124,7 @@ PROVIDERS: dict[str, Provider] = {
                 "likes + comments + shares + saves, and play_count inline (DECLARED "
                 "no-empties-or-zeros, UNPROVEN until one live pull)"),
             "tt_comments": Capability(True, _COST_BRIGHTDATA,
-                                      "separate paid dataset, opt-in — 17 fields"),
+                                      "separate paid dataset, opt-in: 17 fields"),
         }),
     "apify": Provider(
         key="apify", label="Apify", key_env="AIOS_APIFY_KEY",
@@ -132,7 +132,7 @@ PROVIDERS: dict[str, Provider] = {
             # ⭐ MEASURED 2026-08-08 against the public Reels grid: `videoPlayCount` 137,684 and
             # 299,493 vs a browser-read ground truth of 134K-137K and 299K. Exact.
             "ig_post_views": Capability(True, _COST_APIFY,
-                                        "videoPlayCount — matches Instagram's displayed views"),
+                                        "videoPlayCount, matches Instagram's displayed views"),
             "ig_post_metrics": Capability(True, _COST_APIFY, "likes + comments (fallback)"),
             "ig_profile": Capability(True, _COST_APIFY, "profile fields (fallback)"),
         }),
@@ -240,12 +240,12 @@ def run(capability, work, satisfied=None, log=None):
         secs = round(time.time() - started, 2)
         if note:
             attempts.append(Attempt(provider.key, False, note, 0, secs))
-            log(f"  {provider.label}: {note} — falling through")
+            log(f"  {provider.label}: {note}, falling through")
             continue
         if not ok(result):
             attempts.append(Attempt(provider.key, False, "answered without the field asked for",
                                     0, secs))
-            log(f"  {provider.label}: answered, but not with what was asked for — falling through")
+            log(f"  {provider.label}: answered, but not with what was asked for, falling through")
             last = result if last is None else last
             continue
         attempts.append(Attempt(provider.key, True, "", _count(result), secs))
@@ -282,6 +282,323 @@ def wire():
     }
 
 
+
+
+# ═══════════════════ WAVE 36 · W36-T35 (ruling R4, contract C5) — THE LLM LADDER ════════════════
+#
+# Owner item 4, verbatim (2026-08-18): *"I'm also getting errors everywhere when I want to use the
+# assisntant: 'the assistant could not be reached just now (openrouter: HTTP 402)' and 'cerebras:
+# HTTP 402; groq: HTTP 404; openrouter: HTTP 402; anthropic: tool calls are not wired for this
+# shape'."*
+#
+# ⭐⭐ R4 IS THREE CLAUSES AND THEY LAND IN THREE DIFFERENT PLACES. (1) Anthropic becomes the
+# tool-calling path that always works — a WIRE, in `routes_query`. (2) A provider with no credit is
+# SKIPPED rather than tried — a memo, `mark_no_credit` below. (3) No raw `HTTP 402` ever reaches a
+# screen — a SENTENCE, `refusal_sentence` below. The declaration here is what the first two read.
+#
+# ⚠ WHY A SECOND REGISTRY RATHER THAN ROWS IN `PROVIDERS` ABOVE. A scraping provider is
+# `(key_env, caps)` and is billed per RECORD; an LLM provider is `(env, url, model, wire)` and is
+# billed per TOKEN. Folding them into one dict would mean four fields that are meaningless for half
+# the rows and an `estimate()` that answers $0.00 for anything LLM-shaped. What they SHARE is the
+# thing worth sharing: `Capability`, so "MEASURED INCAPABLE" means exactly the same thing on both
+# sides, and `llm_chain()` refuses an incapable row exactly as `chain()` does.
+#
+# ⛔ THE DECLARATION IS THE POINT (staged item 3). `_FAILED_GEN` in `routes_query` is a REGEX that
+# recovers a tool call out of a provider's 400 — the evidence that guessing at capability failed.
+# A row that says `llm_tool_calling: Capability(False, …)` is never offered for a tool-calling
+# turn at all, so the guess never has to be made.
+
+#: How long a provider stays skipped after it tells us it is out of credit. ⚠ A MEMO, NOT A FACT:
+#: the balance can be topped up at any moment, so this expires rather than latching. Fifteen
+#: minutes is long enough that a chat session does not re-pay the timeout on every turn, and short
+#: enough that a top-up is picked up without a restart.
+CREDIT_COOLDOWN_S = float(os.environ.get("AIOS_CREDIT_COOLDOWN_S") or 900)
+
+#: `{provider name: unix ts when the memo expires}`. ⚠ PROCESS-LOCAL AND DELIBERATELY SO — it is a
+#: latency optimisation, not a billing record. A second container learns the same thing from its
+#: own first 402, and neither one can be wrong for longer than the cooldown.
+_NO_CREDIT: dict[str, float] = {}
+
+
+@dataclass(frozen=True)
+class LlmProvider:
+    """One chat-completions endpoint, and what it is DECLARED able to do."""
+    name: str
+    label: str
+    env: str
+    url: str
+    model: str
+    #: `openai` = the OpenAI-compatible `/chat/completions` shape. `anthropic` = the Messages API,
+    #: which is a different body, a different auth header and a different result shape.
+    wire: str
+    caps: dict = field(default_factory=dict)
+
+    def configured(self) -> bool:
+        return bool((os.environ.get(self.env) or "").strip())
+
+    def can(self, capability: str) -> bool:
+        cap = self.caps.get(capability)
+        return bool(cap and cap.capable and self.configured())
+
+
+#: ⭐ ORDER IS THE LADDER, AND ANTHROPIC IS FIRST BECAUSE OF R4. `routes_query`'s old comment put
+#: cerebras first *"because this path needs tool calling and cerebras carries this account's
+#: tool-capable model"* — R4 replaces that premise: Anthropic is the tool-calling path that always
+#: works, and the others are the cheap seats it falls through to.
+LLM_PROVIDERS: dict[str, LlmProvider] = {
+    "anthropic": LlmProvider(
+        name="anthropic", label="Anthropic", env="ANTHROPIC_API_KEY",
+        url="https://api.anthropic.com/v1/messages",
+        # ⚠ Claude Opus 5, $5 / $25 per million tokens (2026-06 list). Override per deployment with
+        # `AIOS_ANTHROPIC_MODEL` — the id is read at call time, so a cheaper tier
+        # (`claude-sonnet-5`, $3 / $15) is an environment change, not a release.
+        model=os.environ.get("AIOS_ANTHROPIC_MODEL") or "claude-opus-5",
+        wire="anthropic",
+        caps={
+            # ⭐ MEASURED, and it is the whole of R4's first clause: the Messages API answers with a
+            # typed `tool_use` content block carrying parsed `input`. There is nothing to recover
+            # out of a 400 and no regex in the path — which is exactly what `_FAILED_GEN` exists to
+            # apologise for on the other wire.
+            "llm_tool_calling": Capability(True, 0.0,
+                                           "typed tool_use content block; no text recovery path"),
+            "llm_chat": Capability(True, 0.0, "Messages API"),
+            "llm_json_mode": Capability(True, 0.0, "output_config.format, schema-constrained"),
+        }),
+    "cerebras": LlmProvider(
+        name="cerebras", label="Cerebras", env="CEREBRAS_API_KEY",
+        url="https://api.cerebras.ai/v1/chat/completions",
+        model="gpt-oss-120b", wire="openai",
+        caps={
+            "llm_tool_calling": Capability(True, 0.0,
+                                           "DECLARED, not measured: this account's tool-capable "
+                                           "model per the wave-32 ladder note"),
+            "llm_chat": Capability(True, 0.0, "OpenAI-compatible"),
+            "llm_json_mode": Capability(True, 0.0, "response_format json_object"),
+        }),
+    "groq": LlmProvider(
+        name="groq", label="Groq", env="GROQ_API_KEY",
+        url="https://api.groq.com/openai/v1/chat/completions",
+        model="llama-3.3-70b-versatile", wire="openai",
+        caps={
+            "llm_tool_calling": Capability(True, 0.0,
+                                           "DECLARED, not measured. ⚠ `routes_query._FAILED_GEN` "
+                                           "exists because SOME provider on this wire answers 400 "
+                                           "with the call in `failed_generation`; the repo never "
+                                           "recorded which. Flip this to False the day it is"),
+            "llm_chat": Capability(True, 0.0, "OpenAI-compatible"),
+            "llm_json_mode": Capability(True, 0.0, "response_format json_object"),
+        }),
+    "openrouter": LlmProvider(
+        name="openrouter", label="OpenRouter", env="OPENROUTER_API_KEY",
+        url="https://openrouter.ai/api/v1/chat/completions",
+        model="openai/gpt-4o-mini", wire="openai",
+        caps={
+            "llm_tool_calling": Capability(True, 0.0, "DECLARED, not measured"),
+            "llm_chat": Capability(True, 0.0, "OpenAI-compatible"),
+            "llm_json_mode": Capability(True, 0.0, "response_format json_object"),
+        }),
+}
+
+LLM_DEFAULT_ORDER = ("anthropic", "cerebras", "groq", "openrouter")
+
+
+def mark_no_credit(name, seconds=None):
+    """Remember that `name` said it is out of credit, so the next turn SKIPS it (R4).
+
+    ⛔ THE SECOND CLAUSE OF R4 IS "SKIPPED, NOT TRIED", and without a memo there is nowhere for
+    that to live: a stateless ladder re-tries the empty account on every single turn, pays its
+    round trip, and shows the reader a longer error each time. This is that memo.
+    """
+    _NO_CREDIT[str(name)] = time.time() + float(
+        CREDIT_COOLDOWN_S if seconds is None else seconds)
+    return _NO_CREDIT[str(name)]
+
+
+def no_credit(name):
+    """Is this provider inside its out-of-credit cooldown? Expiry is checked, never assumed."""
+    until = _NO_CREDIT.get(str(name))
+    if not until:
+        return False
+    if time.time() >= until:
+        _NO_CREDIT.pop(str(name), None)
+        return False
+    return True
+
+
+def clear_credit_memo(name=None):
+    """Forget one memo, or all of them. For a gate, and for an operator after a top-up."""
+    if name is None:
+        _NO_CREDIT.clear()
+    else:
+        _NO_CREDIT.pop(str(name), None)
+
+
+def llm_chain(capability="llm_tool_calling"):
+    """The provider order for `capability` — declaration first, credit memo second.
+
+    Three filters, in this order, and each removes a DIFFERENT kind of row:
+      1. `can()`  — declared capable AND configured. An incapable row is never offered, so a
+                    turn cannot be spent discovering it (the `chain()` rule, one layer up).
+      2. `no_credit()` — R4's skip. A provider that told us its balance is empty is passed over
+                    until the memo expires.
+      3. the ORDER itself, overridable with `AIOS_LLM_ORDER` (`anthropic,groq`) so a deployment
+         can be moved off a vendor without a release — the same clause `AIOS_PROVIDER_ORDER`
+         carries for the scraping side.
+    """
+    raw = (os.environ.get("AIOS_LLM_ORDER") or "").strip()
+    names = [x.strip() for x in raw.split(",") if x.strip()] or list(LLM_DEFAULT_ORDER)
+    return [LLM_PROVIDERS[n] for n in names
+            if n in LLM_PROVIDERS and LLM_PROVIDERS[n].can(capability) and not no_credit(n)]
+
+
+#: What an HTTP status MEANS, in words a person can act on. ⛔⛔ R4's THIRD CLAUSE LIVES HERE AND
+#: IT IS NOT COSMETIC: `HTTP 402` on a screen tells a reader nothing they can do, and the owner
+#: quoted it back at us twice. Every sentence names the VENDOR and the ACTION.
+_STATUS_WORDS = {
+    401: "{label} would not accept our key",
+    403: "{label} would not accept our key",
+    402: "{label} is out of credit",
+    404: "{label} does not offer the model we asked it for",
+    408: "{label} took too long",
+    413: "the question was too long for {label}",
+    429: "{label} is rate limiting us right now",
+}
+
+#: Substrings that mean "no money" on a wire that does not use 402. ⚠ Anthropic answers a spent
+#: balance with a 400 or 403 carrying a message, not with a status code of its own, so this is the
+#: one place a body has to be read. It is a LOWERCASE substring test on the vendor's own words and
+#: it only ever decides whether to SKIP a provider, never whether to trust one.
+_CREDIT_WORDS = ("credit balance", "insufficient credit", "insufficient_quota", "out of credit",
+                 "quota exceeded", "billing", "payment required", "add credits")
+
+
+def is_credit_failure(status, body=""):
+    """Did this response mean "the account is empty"? Status first, then the vendor's own words."""
+    if int(status or 0) == 402:
+        return True
+    if int(status or 0) not in (400, 403, 429):
+        return False
+    return any(word in str(body or "").lower() for word in _CREDIT_WORDS)
+
+
+def refusal_sentence(name, status, body=""):
+    """One provider's failure, as a SENTENCE. Never a bare status code, never a vendor stack trace.
+
+    ⚠ THE BODY IS READ AND NEVER QUOTED. A provider's error body can carry an account id, a key
+    prefix or an internal trace; the only thing taken out of it is the yes/no answer to "is this a
+    credit problem", and what reaches the caller is this module's own wording.
+    """
+    label = (LLM_PROVIDERS.get(str(name)) or LlmProvider(name, str(name), "", "", "", "")).label
+    if is_credit_failure(status, body):
+        return f"{label} is out of credit"
+    code = int(status or 0)
+    if code in _STATUS_WORDS:
+        return _STATUS_WORDS[code].format(label=label)
+    if 500 <= code <= 599:
+        return f"{label} is having trouble at their end"
+    return f"{label} did not answer"
+
+
+# ═══════════ THE ANTHROPIC WIRE, ONCE (W36-T35 / ASK D-18, ruling R4) ═══════════════════════════
+#
+# ⛔⛔ TWO DOORS IN THIS PRODUCT CALL ANTHROPIC AND THEY MUST NOT EACH LEARN THE MESSAGES API.
+# `routes_query._call_model` (the Assistant and Query) and `ai_review.draft_flow` (the automation
+# drafter) both need it, and the owner quoted an error from EACH of them in one breath:
+# *"the assistant could not be reached just now (openrouter: HTTP 402)"* and *"anthropic: tool
+# calls are not wired for this shape"*. Two implementations of one wire is
+# [[one-question-two-normalizers]] before a line is written, so the wire lives here, beside the
+# ladder that declares the rung.
+#
+# FOUR THINGS THE OPENAI-COMPATIBLE SHAPE GETS WRONG, each a 400 on its own:
+#   1. the system prompt is a TOP-LEVEL field, not a `{"role": "system"}` message
+#   2. a tool is `{name, description, input_schema}` FLAT, not nested under `function`
+#   3. `temperature` and friends are REMOVED on the current model family
+#   4. `tool_choice` is an OBJECT (`{"type": "auto"}` / `{"type": "any"}`), not a string
+#
+# ⚠ AND ONE THING THAT IS NOT A SHAPE: `effort` is model-gated. `output_config.effort` errors on
+# Haiku 4.5, so it is a PARAMETER here and the caller decides — the drafter runs on haiku and omits
+# it, the assistant runs on the Opus tier and sends it.
+
+#: The Messages API version header. A DATE that pins the WIRE FORMAT, never a model.
+ANTHROPIC_VERSION = "2023-06-01"
+
+
+def anthropic_request(*, model, key, system, messages, tools, max_tokens,
+                      tool_choice="auto", effort=None):
+    """`{url, headers, json}` for one Messages API call. Pure: reads no environment, sends nothing.
+
+    `messages` is the OpenAI-shaped list this product already builds; the `system` turns are lifted
+    out of it, because that is where this API wants them. `tools` is the OpenAI-shaped tool list,
+    re-addressed rather than re-derived, so a schema change happens in one place.
+    """
+    system_text = "\n\n".join(str(m.get("content") or "") for m in messages
+                              if m.get("role") == "system")
+    if system:
+        system_text = (system_text + "\n\n" + str(system)).strip() if system_text else str(system)
+    turns = [{"role": ("assistant" if m.get("role") == "assistant" else "user"),
+              "content": str(m.get("content") or "")}
+             for m in messages if m.get("role") != "system" and str(m.get("content") or "").strip()]
+    body = {
+        "model": str(model),
+        "max_tokens": int(max_tokens),
+        "system": system_text,
+        "messages": turns,
+        "tools": [{"name": t["function"]["name"],
+                   "description": t["function"]["description"],
+                   "input_schema": t["function"]["parameters"]} for t in (tools or [])],
+        "tool_choice": {"type": "any" if tool_choice in ("required", "any") else "auto"},
+    }
+    if effort:
+        body["output_config"] = {"effort": str(effort)}
+    return {"url": LLM_PROVIDERS["anthropic"].url,
+            "headers": {"x-api-key": str(key),
+                        "anthropic-version": ANTHROPIC_VERSION,
+                        "content-type": "application/json"},
+            "json": body}
+
+
+def anthropic_read(body):
+    """`(text, tool_input, refusal)` out of a Messages API answer.
+
+    ⛔ `stop_reason` IS CHECKED BEFORE `content` IS READ. A safety decline answers **HTTP 200** with
+    `stop_reason: "refusal"` and an empty or partial `content`, so code that indexes `content[0]`
+    unconditionally breaks on exactly the turn a person most needs explained.
+    ⭐ AND THE TOOL CALL ARRIVES PARSED. `tool_use.input` is already a dict — no `json.loads`, and
+    no regex recovering a call out of a 400, which is what the other wire needs.
+    """
+    body = body if isinstance(body, dict) else {}
+    if str(body.get("stop_reason") or "") == "refusal":
+        return "", None, "the assistant declined to answer that one"
+    blocks = [b for b in (body.get("content") or []) if isinstance(b, dict)]
+    text = " ".join(str(b.get("text") or "") for b in blocks if b.get("type") == "text").strip()
+    calls = [b for b in blocks if b.get("type") == "tool_use"]
+    got = calls[0].get("input") if calls else None
+    return text, (got if isinstance(got, dict) else None), None
+
+
+def llm_status(capability="llm_tool_calling"):
+    """Per provider: configured, declared-capable, in cooldown, and WHY — contract C5's payload.
+
+    ⭐ ONE LIST, ONE DOOR. The Assistant's model picker and the Agent chat's toggle (W36-T34) read
+    THIS, so a model offered in one place cannot be missing from the other, and neither can offer a
+    provider the ladder would refuse to call [[permitted-is-not-answerable]].
+    """
+    rows = []
+    for name in LLM_DEFAULT_ORDER:
+        p = LLM_PROVIDERS[name]
+        cap = p.caps.get(capability)
+        rows.append({
+            "provider": p.name, "label": p.label, "model": p.model, "wire": p.wire,
+            "configured": p.configured(),
+            "toolCalling": bool((p.caps.get("llm_tool_calling") or Capability(False)).capable),
+            "jsonMode": bool((p.caps.get("llm_json_mode") or Capability(False)).capable),
+            "capable": bool(cap and cap.capable),
+            "outOfCredit": no_credit(name),
+            "note": (cap.note if cap else ""),
+        })
+    return rows
+
+
 # =============================================================================================
 # THE CANONICAL SCHEMA — owner ruling 2026-08-08:
 #   *"standardize the schema between Bright Data and APIfy so we keep using the same pre-set

api/routes_agent_harness.py

@@ -0,0 +1,455 @@
+"""routes_agent_harness.py — CONTRACT C4: the agent's HARNESS, kept as versioned files.
+
+Owner item 3, verbatim (2026-08-18): *"This new module under agent is supposed to host any file
+pertaining to the agent skills, router etc. So we build a user can build a custom harness for each
+agent through the chat interface."*
+
+    GET    /api/v1/agents/{id}/harness                      the file LIST (no bodies)
+    GET    /api/v1/agents/{id}/harness?path=…               one file: current body + its versions
+    GET    /api/v1/agents/{id}/harness?path=…&version=N     one older body, verbatim
+    PUT    /api/v1/agents/{id}/harness                      write a NEW version of one file
+    DELETE /api/v1/agents/{id}/harness?path=…               drop a file and its history
+
+⭐⭐ **R8 IS THE WHOLE SHAPE: BOTH PRINCIPALS WRITE, AND NOTHING IS EVER OVERWRITTEN.** A write
+appends a version; a roll-back is a write of an older body (`restoredFrom`), never a delete. So the
+history is a record of what happened rather than of what somebody last wanted it to look like.
+
+⛔ **R8 IS DELIBERATELY NOT R9.** An agent-authored ACTION's configuration is agent-only (item 8,
+`routes_automation`); a harness file is not. Do not copy this file's posture over there or that
+one's over here — the two rulings differ on purpose and they sit one screen apart in the product.
+
+⚠ **`author` IS THE SESSION, `authorKind` IS THE PROVENANCE, AND THEY ARE DIFFERENT FACTS.** Every
+write through this router is made BY a signed-in administrator, so `author` is stamped from the
+session and can never be supplied by the caller. `authorKind` says whether the BODY was drafted by
+a person or by the agent in the chat — a claim the client is entitled to make, because both are
+permitted (R8) and so nothing is bought by forging it. `record_version()` below is the server-side
+door the automation engine uses when the agent writes with no session at all; that one stamps the
+agent's own id as the author, which is the only case where `author` is not a username.
+
+⛔ **THE VERSION LIST IS CAPPED AND THE CAP IS REPORTED, NEVER SILENT.** `MAX_VERSIONS` versions of
+one file are kept; past that the OLDEST are dropped and the count of what was dropped rides in
+`trimmed` on every payload that mentions the file, so a reader can see that the history is partial
+rather than infer that the file was only ever saved twice. This is the tenant document, which is
+already 28.6 MB on tenant #0 and is deep-copied on every read: an unbounded per-agent history is
+a store-sized leak with a UI in front of it.
+"""
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Body, Depends
+
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+#: The tenant's harness files: `{agent_id: {path: file_record}}`. A per-tenant bucket, so it rides
+#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace — the same rule
+#: `routes_slack.AGENTS_KEY` follows for the agent records these hang off.
+HARNESS_KEY = "agent_harness"
+
+#: One body. Generous for a skill or a router file and far under the point where a single write
+#: would move the tenant document measurably. A larger body is a REFUSAL at the door, not a
+#: truncation: a silently truncated skill file is a harness that does not do what its text says.
+MAX_BODY_BYTES = 128 * 1024
+
+#: Files per agent. A refusal, not a trim — creating the 65th file is a different act from saving
+#: the 101st version of one, and only the second can be a routine consequence of ordinary editing.
+MAX_FILES = 64
+
+#: Versions kept per file. Past this the oldest go and `trimmed` counts them (see the header).
+MAX_VERSIONS = 100
+
+MAX_PATH = 200
+
+#: What a path may contain. ⛔ THIS IS NOT A FILESYSTEM PATH AND NOTHING HERE EVER TOUCHES A DISK —
+#: the "files" are keys in a store bucket. The character rule exists so the key is displayable, is
+#: safe to put in a URL, and cannot carry a traversal sequence that would look meaningful to a
+#: future reader who assumes it IS a filesystem path. Fail-closed on the character set, not on a
+#: list of forbidden sequences: an allow-list cannot be walked around by a spelling.
+_PATH_OK = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-/")
+
+AUTHOR_KINDS = ("user", "agent")
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _all(rt):
+    """`{agent_id: {path: record}}` for one tenant. `{}` on any failure — an unreadable bucket must
+    degrade to "this agent has no harness files", never to a 500 on the pane that lists them."""
+    try:
+        found = rt.get(HARNESS_KEY) or {}
+    except Exception:                                                        # noqa: BLE001
+        return {}
+    return found if isinstance(found, dict) else {}
+
+
+def _files(rt, agent_id):
+    found = _all(rt).get(str(agent_id))
+    return found if isinstance(found, dict) else {}
+
+
+#: What kind of principal an id names. `None` = this tenant has no agent with that id.
+#:
+#: ⛔⛔ THERE ARE TWO AGENT REGISTRIES IN THIS PRODUCT AND THE FIRST DRAFT OF THIS FILE KNEW ONLY
+#: ONE (ASK D-5, 2026-08-18). `routes_slack._agents` is the per-Slack-channel permission wall under
+#: Manage users. The **Agents module** the owner's item 3 is about is the AUTOMATION surface —
+#: `Shell.tsx` mounts `<Lazily surface="Agents"><AutomationSurface /></Lazily>`, and
+#: `AutomationDetail`'s `panelTabs` is literally the `Properties | Run history` strip R7 adds
+#: "Harness" to. Keyed on the Slack bucket alone, every `GET/PUT /agents/{id}/harness` from that
+#: tab would have answered **404 no_agent**: whole, gate-green and dead on arrival
+#: [[reachable-is-not-the-same-as-built]]. Verified independently before acting, not taken on
+#: report: `surface="Agents"` mounts `AutomationSurface`, and `ManageAgentPane` contains ZERO
+#: occurrences of Canvas, Properties, Run history or panelTabs.
+#:
+#: ⭐ ONE STORE, BOTH PRINCIPALS — never a second bucket keyed by surface. The owner's "agent
+#: skills, router" files in two places is the parallel code path item 13 exists to refuse.
+AGENT_SLACK = "slack"
+AGENT_AUTOMATION = "automation"
+
+
+def agent_kind(rt, agent_id):
+    """Which registry holds this id — `AGENT_SLACK`, `AGENT_AUTOMATION`, or `None`.
+
+    ⚠ A SYNTHETIC ROW IS NOT AN AGENT FOR THIS PURPOSE. `field:` and `system:` ids are DERIVED at
+    read time from a column definition or a connector schedule; they have no stored home, so a
+    harness file hung off one is an orphan the moment the column changes. `patch_automation`
+    already refuses those ids for the neighbouring reason, and this refuses them by simply not
+    finding them — `all_definitions` holds stored automations only.
+    """
+    import routes_slack
+    aid = str(agent_id or "")
+    if isinstance(routes_slack._agents(rt).get(aid), dict):
+        return AGENT_SLACK
+    import automation_engine as engine
+    try:
+        known = engine.all_definitions(rt) or {}
+    except Exception:                                                        # noqa: BLE001
+        return None
+    return AGENT_AUTOMATION if aid in known else None
+
+
+def _known_agent(rt, agent_id):
+    """Does this tenant have an agent with this id, in EITHER registry?"""
+    return agent_kind(rt, agent_id) is not None
+
+
+def agent_wall(session, agent_id):
+    """404 for an unknown id, else apply the wall THAT PRINCIPAL'S OWN SURFACE applies.
+
+    ⛔⛔ ONE DOOR, TWO WALLS, AND THAT IS NOT A SECOND CODE PATH — it is the refusal to invent a
+    THIRD wall. A Slack channel agent is administered under Manage users and every `/agents/*` door
+    in `routes_slack` is `admin_gate`; an automation lives in the Agents module and every door in
+    `routes_automation` is `module_gate("automation")`. A harness file is configuration OF the
+    agent it hangs off, so it is reached by whoever may already configure that agent. Picking one
+    of the two walls for both would either lock the Agents module's own users out of a tab the
+    owner asked for, or hand the Slack permission wall to anyone with an automation grant.
+    """
+    kind = agent_kind(session.runtime, agent_id)
+    if kind is None:
+        raise err(404, "no_agent", "there is no agent with that id in this workspace")
+    if kind == AGENT_SLACK:
+        import core.perms as perms
+        if not perms.is_admin(session.user):
+            raise err(403, "forbidden", "administrators only")
+    else:
+        session.require("automation")
+    return kind
+
+
+def normalize_path(raw):
+    """THE path rule, in ONE place. Returns the cleaned path, or `None` if it is not acceptable.
+
+    ⛔⛔ ONE RULE, TWO DOORS, AND THAT IS WHY THIS IS A FUNCTION RATHER THAN TWO IF-BLOCKS. There
+    are two ways into this store — the HTTP route (which must answer 400) and `record_version()`
+    (which must raise `ValueError`, having no response to put a status into). Written twice, the
+    two copies are [[one-question-two-normalizers]] waiting to happen: the first weakening of one
+    copy is invisible because the other still refuses, so nothing goes red and the wall is now
+    half there. Written once, a change to the rule is felt at both doors and by the gate.
+    """
+    path = str(raw or "").strip().strip("/")
+    if not path or len(path) > MAX_PATH:
+        return None
+    if set(path) - _PATH_OK or ".." in path or "//" in path:
+        return None
+    return path
+
+
+def _clean_path(raw):
+    """`normalize_path` at the HTTP door, where a refusal is a 400 with a reason."""
+    path = normalize_path(raw)
+    if path is None:
+        if not str(raw or "").strip().strip("/"):
+            raise err(400, "no_path", "a harness file needs a path, for example skills/router.md")
+        if len(str(raw)) > MAX_PATH:
+            raise err(400, "path_too_long", f"a harness path is at most {MAX_PATH} characters")
+        raise err(400, "bad_path",
+                  "a harness path may use letters, digits, dot, dash, underscore and / only")
+    return path
+
+
+def _blank(path, author, author_kind):
+    return {"path": path, "versions": [], "trimmed": 0,
+            "created": _now(), "createdBy": author, "createdKind": author_kind}
+
+
+def _append(record, body, author, author_kind, restored_from=None):
+    """Append ONE version to a file record, in place, and report what was trimmed.
+
+    The version NUMBER is monotonic and survives trimming — it counts writes, not stored entries.
+    A version list whose numbers restart at 1 after a trim would make two different bodies share a
+    name, and `restoredFrom` would then point at whichever one happened to be in the window.
+    """
+    # ⚠ A NEW LIST, NEVER `versions.append(...)` ON THE STORED ONE. `update()` hands the callback
+    # the live document and may run it more than once; appending in place would then stack two
+    # copies of the same version into the history on a retry.
+    prior = record.get("versions") if isinstance(record.get("versions"), list) else []
+    last = max((int(v.get("version") or 0) for v in prior if isinstance(v, dict)), default=0)
+    entry = {"version": last + 1, "body": body, "author": author, "authorKind": author_kind,
+             "created": _now(), "bytes": len(body.encode("utf-8"))}
+    if restored_from:
+        entry["restoredFrom"] = int(restored_from)
+    versions = [*prior, entry]
+    dropped = max(0, len(versions) - MAX_VERSIONS)
+    if dropped:
+        versions = versions[dropped:]
+    record["versions"] = versions
+    record["trimmed"] = int(record.get("trimmed") or 0) + dropped
+    return entry
+
+
+def _head(record):
+    """The newest version of a file record, or `None` for a record with no versions at all."""
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    return versions[-1] if versions else None
+
+
+def _row(record):
+    """One file, as the LIST door reports it: everything except the bodies.
+
+    ⚠ NO BODY, AND THAT IS THE POINT. A list door that carried every version of every file would
+    ship the whole harness on every pane render; the Harness tab lists first and opens one file
+    second, which is exactly the shape this answers.
+    """
+    head = _head(record) or {}
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    return {"path": record.get("path") or "",
+            "version": int(head.get("version") or 0),
+            "bytes": int(head.get("bytes") or 0),
+            "author": head.get("author") or record.get("createdBy") or "",
+            "authorKind": head.get("authorKind") or record.get("createdKind") or "user",
+            "updated": head.get("created") or record.get("created") or "",
+            "created": record.get("created") or "",
+            "versions": len(versions),
+            "trimmed": int(record.get("trimmed") or 0)}
+
+
+def _version_rows(record):
+    """The history of one file, newest first, WITHOUT the bodies.
+
+    A body per version is what makes a diff possible, and it is also what makes this payload big:
+    100 versions of a 128 KB file is 12 MB. The client asks for the two bodies it is diffing
+    (`?path=…&version=N`), which is two round trips for a diff and none for a history list.
+    """
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    out = []
+    for entry in reversed(versions):
+        if not isinstance(entry, dict):
+            continue
+        row = {"version": int(entry.get("version") or 0),
+               "author": entry.get("author") or "",
+               "authorKind": entry.get("authorKind") or "user",
+               "created": entry.get("created") or "",
+               "bytes": int(entry.get("bytes") or 0)}
+        if entry.get("restoredFrom"):
+            row["restoredFrom"] = int(entry["restoredFrom"])
+        out.append(row)
+    return out
+
+
+def _limits():
+    """The caps, IN the payload, so a client can say "this file is full" before a write fails.
+
+    ⚠ A limit the client cannot see is a limit the user meets as an error. `trimmed` reports the
+    one cap that acts without refusing; these report the three that refuse.
+    """
+    return {"maxBodyBytes": MAX_BODY_BYTES, "maxFiles": MAX_FILES,
+            "maxVersions": MAX_VERSIONS, "maxPath": MAX_PATH}
+
+
+# ── the write door the SERVER uses (no session) ────────────────────────────────────────────────
+def record_version(runtime, agent_id, path, body, author="", author_kind="agent",
+                   restored_from=None):
+    """Write one version from INSIDE the server — the agent's own half of R8.
+
+    ⭐ THIS IS THE FUNCTION, NOT THE ROUTE, THAT MAKES "editable by BOTH the user and the agent"
+    true. An agent acting inside an automation run holds no session and no cookie; if its only way
+    to write were the HTTP door it would have to borrow a person's identity, and the authorship
+    column would then be a record of who was logged in rather than of what wrote the file.
+
+    Returns the appended entry. Raises nothing the caller cannot handle: an unknown agent is a
+    `ValueError`, because a server-side caller has no HTTP response to put a 404 into.
+    """
+    agent_id = str(agent_id or "")
+    if not _known_agent(runtime, agent_id):
+        raise ValueError(f"no agent {agent_id!r} in this workspace")
+    path = normalize_path(path)
+    if path is None:
+        raise ValueError("that is not an acceptable harness path")
+    body = str(body or "")
+    if len(body.encode("utf-8")) > MAX_BODY_BYTES:
+        raise ValueError("harness body is over the size limit")
+    kind = author_kind if author_kind in AUTHOR_KINDS else "agent"
+    author = str(author or agent_id)
+    # ⛔ THE FILE-COUNT CEILING IS CHECKED HERE, NOT INSIDE `_set`. An exception raised inside a
+    # store `update` callback propagates out of a half-run read-modify-write, and the one thing a
+    # refusal must never do is leave the caller unsure whether the write happened.
+    existing = _files(runtime, agent_id)
+    if path not in existing and len(existing) >= MAX_FILES:
+        raise ValueError(f"this agent already has {MAX_FILES} harness files")
+    appended = {}
+
+    def _set(cur):
+        cur = dict(cur or {})
+        files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
+        record = dict(files[path]) if isinstance(files.get(path), dict) else _blank(path, author, kind)
+        appended.clear()
+        appended.update(_append(record, body, author, kind, restored_from))
+        files[path] = record
+        cur[agent_id] = files
+        return cur
+
+    runtime.update(HARNESS_KEY, _set, flush="sync")
+    return appended
+
+
+# ── the routes ────────────────────────────────────────────────────────────────────────────────
+@router.get("/agents/{agent_id}/harness")
+def get_harness(agent_id: str, path: str = "", version: int = 0,
+                session: Session = Depends(require_session)):
+    """The list, one file, or one older body — decided by the query string (C4).
+
+    ⚠ ADMIN-GATED LIKE EVERY OTHER AGENT DOOR (`routes_slack`), and for a stronger reason than
+    consistency: a harness file is what the agent is INSTRUCTED to do, so writing one is closer to
+    editing a permission than to editing a document.
+    """
+    agent_id = str(agent_id or "")
+    agent_wall(session, agent_id)
+    files = _files(session.runtime, agent_id)
+    if not path:
+        rows = [_row(rec) for _p, rec in sorted(files.items()) if isinstance(rec, dict)]
+        return {"agent": agent_id, "files": rows, "limits": _limits()}
+
+    wanted = _clean_path(path)
+    record = files.get(wanted)
+    if not isinstance(record, dict):
+        raise err(404, "no_file", f"this agent has no harness file at {wanted}")
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    if version:
+        for entry in versions:
+            if isinstance(entry, dict) and int(entry.get("version") or 0) == int(version):
+                return {"agent": agent_id, **_row(record), "body": entry.get("body") or "",
+                        "atVersion": int(version), "history": _version_rows(record),
+                        "limits": _limits()}
+        # ⛔ A TRIMMED VERSION IS A NAMED REFUSAL, NOT A 404 SHAPED LIKE A TYPO. The client asked
+        # for something that existed and no longer does, and telling it apart from a bad number is
+        # the difference between "roll back to v3" failing loudly and failing as if v3 never was.
+        trimmed = int(record.get("trimmed") or 0)
+        if trimmed and int(version) <= trimmed:
+            raise err(410, "version_trimmed",
+                      f"version {int(version)} is older than the {MAX_VERSIONS} versions kept "
+                      f"for this file, and its body is gone")
+        raise err(404, "no_version", f"this file has no version {int(version)}")
+    head = _head(record) or {}
+    return {"agent": agent_id, **_row(record), "body": head.get("body") or "",
+            "atVersion": int(head.get("version") or 0), "history": _version_rows(record),
+            "limits": _limits()}
+
+
+@router.put("/agents/{agent_id}/harness")
+def put_harness(agent_id: str, body: dict = Body(default=None),
+                session: Session = Depends(require_session)):
+    """Write a NEW version of one harness file. `{path, body, authorKind?, restoredFrom?}` (C4).
+
+    ⛔ THERE IS NO OVERWRITE HERE AND THERE IS NO EDIT-IN-PLACE. R8's "every version kept" is not a
+    UI affordance; it is this function refusing to have a code path that replaces a body. A
+    roll-back arrives as an ordinary write carrying `restoredFrom`, so the history records that
+    somebody went back rather than pretending the intervening versions never happened.
+    """
+    agent_id = str(agent_id or "")
+    agent_wall(session, agent_id)
+    body = body if isinstance(body, dict) else {}
+    path = _clean_path(body.get("path"))
+    text = body.get("body")
+    if not isinstance(text, str):
+        raise err(400, "no_body", "a harness file needs a body, even an empty one")
+    if len(text.encode("utf-8")) > MAX_BODY_BYTES:
+        raise err(413, "body_too_long",
+                  f"a harness file is at most {MAX_BODY_BYTES // 1024} KB; this one is larger")
+
+    # ⚠ THE CALLER DECLARES THE PROVENANCE AND THE SERVER STAMPS THE IDENTITY. `authorKind` is a
+    # claim about who WROTE the text (the person, or the agent in the chat panel); `author` is the
+    # session and is never read off the request. Nothing is bought by forging the first — both
+    # principals may write (R8) — and everything would be bought by forging the second.
+    kind = str(body.get("authorKind") or "user").strip().lower()
+    if kind not in AUTHOR_KINDS:
+        raise err(400, "bad_author_kind", "authorKind is either user or agent")
+    restored = body.get("restoredFrom")
+    try:
+        restored = int(restored) if restored else None
+    except (TypeError, ValueError):
+        raise err(400, "bad_version", "restoredFrom must be a version number")
+
+    files = _files(session.runtime, agent_id)
+    if path not in files and len(files) >= MAX_FILES:
+        raise err(409, "too_many_files",
+                  f"this agent already has {MAX_FILES} harness files; delete one to add another")
+    try:
+        record_version(session.runtime, agent_id, path, text,
+                       author=session.uname, author_kind=kind, restored_from=restored)
+    except ValueError as exc:
+        raise err(400, "refused", str(exc))
+
+    fresh = _files(session.runtime, agent_id).get(path)
+    if not isinstance(fresh, dict) or not _head(fresh):
+        # The store took the write and did not record it. A 200 here would tell an administrator
+        # their skill file was saved when it was not — the shape `routes_slack` refuses too.
+        raise err(503, "store_unavailable", "the harness file was NOT saved")
+    head = _head(fresh)
+    return {"agent": agent_id, **_row(fresh), "body": head.get("body") or "",
+            "atVersion": int(head.get("version") or 0), "history": _version_rows(fresh),
+            "limits": _limits()}
+
+
+@router.delete("/agents/{agent_id}/harness")
+def delete_harness(agent_id: str, path: str = "", session: Session = Depends(require_session)):
+    """Drop one harness file AND its history.
+
+    ⚠ THIS IS NOT THE THING R8 FORBIDS. R8 forbids a ROLL-BACK implemented as a delete — losing
+    versions as a side effect of an edit. Deleting a file is a person deciding the file should not
+    exist, which is a different act with a different button, and a store with no way to remove a
+    file is one where a typo'd path is permanent.
+    """
+    agent_id = str(agent_id or "")
+    agent_wall(session, agent_id)
+    wanted = _clean_path(path)
+    if wanted not in _files(session.runtime, agent_id):
+        raise err(404, "no_file", f"this agent has no harness file at {wanted}")
+
+    def _set(cur):
+        cur = dict(cur or {})
+        files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
+        files.pop(wanted, None)
+        # An agent with no harness files leaves NO key behind. An empty dict per agent id is how a
+        # bucket accumulates a row for every agent anybody ever opened the tab on.
+        if files:
+            cur[agent_id] = files
+        else:
+            cur.pop(agent_id, None)
+        return cur
+
+    session.runtime.update(HARNESS_KEY, _set, flush="sync")
+    return {"agent": agent_id, "deleted": wanted,
+            "files": [_row(rec) for _p, rec in sorted(_files(session.runtime, agent_id).items())
+                      if isinstance(rec, dict)],
+            "limits": _limits()}

api/routes_alerts.py

@@ -1,668 +1,668 @@
-"""routes_alerts.py — the Alerts module (wave 20, owner item 25, contract C-ALERT).
-
-    GET    /api/v1/alerts                  -> {alerts:[...]}
-    POST   /api/v1/alerts                  <- {viewId, topic, label?}
-    DELETE /api/v1/alerts/{alert_id}
-    POST   /api/v1/alerts/{alert_id}/run   -> evaluate now (the pane's manual refresh)
-    GET    /api/v1/notifications           -> {unread, items:[...]}
-    POST   /api/v1/notifications/read      <- {ids:[...]|null, read?:bool}
-
-The semantics — an alert is a view plus a remembered matched set, a notification is a NEW
-ENTRANT, and the first evaluation seeds silently — live in `core.alerts` with the reasoning.
-This file owns the two things a route must: WHO may do it, and HOW the view gets evaluated.
-
-⭐ **THE EVALUATION RUNS AS THE ALERT'S OWNER, NOT AS THE CALLER.** `_run_alert` builds the pool
-for `rec['owner']`, never for whoever tripped the write hook. Any other choice leaks: a
-full-access admin editing a cell would otherwise evaluate a BU-scoped user's alert over the whole
-book, and the notification would name customers that user may not see — a permission leak wearing
-a notification's clothes. The owner's own scope is the only correct basis for their alert.
-
-⚠ **AN ALERT IS NOT A SECOND READ PATH.** It resolves rows through the same
-`routes_customers.grid_assembly` / `routes_tables.ut_assembly` the grid uses, so a row that an
-alert can see is by construction a row its owner could open. Re-implementing the filter here
-would be a second definition of "matches", and those two would drift.
-"""
-import re
-
-from fastapi import APIRouter, Body, Depends
-
-import core.alerts as alerts
-from deps import Session, err, require_session
-
-router = APIRouter(prefix="/api/v1")
-
-#: The alert-bearing surfaces. `ut_` tables are admitted by prefix, like everywhere else.
-_TOPICS = ("customer", "product")
-
-# ── ⭐⭐ WAVE 32 · T20 · CONTRACT C3 — THE INBOX SHAPE, DERIVED ON READ ────────────────────────
-#
-# `GET /notifications` gains `subject`, `kind` and `target` per item (`read` was always there).
-#
-# ⛔ DERIVED, NEVER STORED, AND THAT IS THE WHOLE OF WHY THIS WAVE EXISTS. Stamping the three
-# keys onto the record at write time would give them to notifications minted AFTER the deploy and
-# to nothing else — every notification already sitting in every tenant's inbox would open nothing,
-# and the feature would be correct in the source and absent from the product
-# ([[a-migration-that-runs-on-the-next-write]], D-201). A read-side derivation reaches a
-# notification queued last month. It also keeps the store shape out of `core/alerts.py`, which is
-# another lane's file this wave — but that is the convenience, not the reason.
-#
-# ⚠ TWO PRODUCERS WRITE TWO SHAPES into one inbox, and the vocabulary below is what tells them
-# apart. `_queue` (a record ENTERED a watched view) sets `topic`+`viewId`. `notify()` sets
-# `topic='automation'` and puts the producer's key in `alertId`, leaving `viewId` empty. Deciding
-# here means the client branches on ONE field instead of re-deriving the same split.
-#
-# ⛔ **D-101 IS CLOSED HERE, BY SUBTRACTION.** There was a THIRD shape — `kind='automation_review'`
-# + `autoId`, a card arriving at a review stage — and its producer `notify_review` was deleted by
-# W27/R3 with the review lanes. `automation_engine.py`'s own tombstone (search `notify_review`)
-# records the 2026-08-12 sweep: **no `.py` file anywhere produces one**, while the client branch,
-# its route and three gate legs stayed fully alive. D-101's exit condition is *"the client review
-# branch is deleted in the same change as any remaining residue, OR `notify_review` gains its real
-# caller"* — the residue is zero, so the branch goes. It is not carried into the Inbox: a stored
-# review notification (if any survives in a tenant from the wave-23 era) derives as an ordinary
-# `alert` with no target, i.e. an honest unclickable row, which is correct — the board it pointed
-# at was deleted two waves ago.
-
-#: C3's `kind` vocabulary. Plain strings on the wire — the client must never union over them
-#: (alertsModel's wave-9 law: a client union turns "the server grew a kind" into a dropped row).
-NOTIF_KIND_ALERT = "alert"
-NOTIF_KIND_AUTOMATION = "automation"
-NOTIF_KIND_SHARE = "share"
-
-#: C3's `target.module` vocabulary, and the automation sub-selection.
-TARGET_MODULE_DATABASE = "database"
-TARGET_MODULE_AUTOMATION = "automation"
-TARGET_TAB_RUNS = "runs"
-
-#: The topic `notify()` carries for a SHARE (W32-T28 writes it; nothing does yet, and a kind with
-#: no producer is a string that reads as a feature — the reason this constant is named here and
-#: cited from `routes_shares` rather than typed twice).
-SHARE_TOPIC = "share"
-
-#: `core.alerts.notify`'s default topic for a run outcome. Mirrors `inboxModel.AUTOMATION_TOPIC`.
-AUTOMATION_TOPIC = "automation"
-
-_UT_TOPIC = re.compile(r"ut_[A-Za-z0-9_]+\Z")
-
-
-def route_for_topic(topic):
-    """A grid SCOPE key -> the registry route that renders it, or None.
-
-    ⛔ THE SAME TABLE AS `alertsModel.routeForTopic`, and the parity is GATED
-    (`verify_alerts.py`'s vocabulary scan) rather than trusted. The two built-ins are the only
-    pair that differ — the registry names the surface (`customer_data`) while the grid names the
-    scope (`customer`) — so a topic passed through as a route sends every click to a page that
-    does not exist. `None` for anything else: a target this product cannot resolve must be ABSENT
-    rather than plausible, because an absent target renders as a row that does not pretend to be
-    clickable, and a wrong one renders as a click that silently goes nowhere.
-    """
-    t = str(topic or "").strip()
-    if t == "customer":
-        return "customer_data"
-    if t == "product":
-        return "product_data"
-    if _UT_TOPIC.match(t):
-        return t
-    return None
-
-
-def _refusal_code(exc):
-    """The `error.code` an `HTTPException` raised by `deps.err()` carries, or `""`.
-
-    ⭐ W32-T22. Four refusals travel up the assembly chain — `unknown_table` (404), `forbidden`
-    (403), `window_required` (409) and `store_not_ready` (503) — and each already names its own
-    cause. Anything that reduces all four to one word is throwing away the only information the
-    reader could have acted on. Returns `""` for a plain exception, so a caller can tell
-    "refused, and here is why" apart from "broke, and we do not know why".
-    """
-    detail = getattr(exc, "detail", None)
-    if isinstance(detail, dict):
-        inner = detail.get("error")
-        if isinstance(inner, dict):
-            return str(inner.get("code") or "")
-    return ""
-
-
-def notification_view(item):
-    """One STORED notification -> the shape the Inbox renders. PURE, and total.
-
-    Never raises and never drops a row: an item it cannot classify comes back as an `alert` with
-    no `target`, which the client renders as an unclickable row rather than hiding. An inbox that
-    silently omits what it does not understand is the one failure a reader cannot detect.
-    """
-    if not isinstance(item, dict):
-        return item
-    topic = str(item.get("topic") or "").strip()
-    alert_id = str(item.get("alertId") or "").strip()
-
-    # ⛔ THE ID TEST IS HALF OF EVERY BRANCH, and it is the load-bearing half. A row whose topic
-    # says `automation` but whose producer key never arrived (a truncated payload, a server
-    # mid-deploy) would otherwise be handed a target naming NOTHING — a click that appears to work
-    # and silently does not, which is this repo's most-repeated failure shape. Failing the test
-    # drops it to the `alert` branch, where `route_for_topic` refuses out loud by answering None.
-    if topic == AUTOMATION_TOPIC and alert_id:
-        kind = NOTIF_KIND_AUTOMATION
-        target = {"module": TARGET_MODULE_AUTOMATION, "id": alert_id, "tab": TARGET_TAB_RUNS}
-    elif topic == SHARE_TOPIC and alert_id:
-        # ⭐ W32-T28: the sharer writes `key=<the ROUTE to open>` and, for a shared VIEW,
-        # `row_id=<the view to select>`.
-        #
-        # ⛔ `key` IS ALREADY A ROUTE, NOT A RAW OBJECT ID, and the first version of this got it
-        # wrong in a way worth recording: a shared VIEW put the VIEW's id in `alertId`, so the
-        # target read `{module: "database", id: "view_42"}` — an instruction to open a database
-        # called `view_42`. It looked right in the payload and would have opened nothing. The
-        # producer resolves the object to its topic and hands over the route; this branch only
-        # shapes what it is given.
-        kind = NOTIF_KIND_SHARE
-        row_id = str(item.get("rowId") or "").strip()
-        target = {"module": TARGET_MODULE_DATABASE, "id": alert_id,
-                  **({"tab": row_id} if row_id else {})}
-    else:
-        kind = NOTIF_KIND_ALERT
-        route = route_for_topic(topic)
-        view_id = str(item.get("viewId") or "").strip()
-        target = None if route is None else (
-            {"module": TARGET_MODULE_DATABASE, "id": route,
-             **({"tab": view_id} if view_id else {})})
-
-    # The email split: `subject` is the HEADER (what this is about — the alert, the automation,
-    # the database), `label` stays the BODY (what happened — the record that entered, the run
-    # summary). They were one field, which is why a notification read as a sentence with no
-    # sender and the pane could not be laid out like mail.
-    subject = str(item.get("alertLabel") or "").strip() or str(item.get("label") or "").strip()
-    # ⚠ `kind` is OVERWRITTEN, not merged. There was one stored value (`automation_review`) and it
-    # is D-101's dead one; leaving it through would give the client two vocabularies for one
-    # question, which is the defect this wave's item 6 is about in a different file.
-    # ⭐⭐ W33-T28 (owner: "the Inbox reads like email") — THE SENDER, WHICH DID NOT EXIST.
-    #
-    # ⛔ A `verifier` reading the finished wave-32 surface found that the row's sender POSITION was
-    # occupied by `kindLabel(n.kind)` — the literals "Alert" / "Automation" / "Shared with you" —
-    # i.e. a CATEGORY standing where a who belongs, and no sender field anywhere on the wire, in
-    # the model or in the markup. Mail has a from. This is it.
-    #
-    # ⚠ IT IS DERIVED HERE, NOT STORED, FOR EVERY KIND BUT ONE — and the exception is the point.
-    # An alert firing and an automation landing rows have no person behind them; their honest
-    # sender is the machine that did it, named as the thing the reader recognises. A SHARE has a
-    # real person, and only the producer knows who: `routes_shares.py` writes it as `actor` and
-    # this reads it back. ⛔ It is NOT parsed out of the body prose ("<name> shared this with
-    # you") — a sender recovered by regexing a sentence breaks the first time the sentence is
-    # reworded, and it would break silently, in the header.
-    #
-    # ⚠ FALLS BACK, NEVER BLANK. A share queued BEFORE `actor` existed has none, and a row with an
-    # empty from column reads as a broken inbox rather than as an old notification.
-    actor = str(item.get("actor") or "").strip()
-    if kind == NOTIF_KIND_SHARE:
-        sender = actor or "A teammate"
-    elif kind == NOTIF_KIND_AUTOMATION:
-        # ⛔ "Agents", not "Automation" (W34-T40, corrected at QA 2026-08-17). The client's
-        # `senderOf` already falls back to `AGENTS_MODULE_LABEL` — but `if (sent) return sent`
-        # runs FIRST, so this server literal won and every actor-less automation notification
-        # showed the retired module name in the inbox's From column.
-        sender = actor or "Agents"
-    else:
-        sender = actor or "Alerts"
-    out = {**item, "read": bool(item.get("read")), "kind": kind,
-           "subject": subject or "Notification", "sender": sender}
-    if target is not None:
-        out["target"] = target
-    return out
-
-
-def inbox_view(box):
-    """`core.alerts.inbox()`'s answer, with every item put through {@link notification_view}.
-
-    ⚠ `unread` IS NOT RECOUNTED. It is the ACCOUNT's number and `items` is one page of it; a
-    recount here would make the badge a function of whatever this page happened to include, which
-    is the exact defect `alertsModel.parseInbox`'s own header records from the other side.
-    """
-    if not isinstance(box, dict):
-        return box
-    items = box.get("items")
-    if not isinstance(items, list):
-        return box
-    # ⭐⭐ W33-T28 / D-208 — THE SERVER'S CLOCK RIDES WITH THE PAGE, and it is what lets the client
-    # render a mail-shaped stamp ("09:41" today, "Aug 12" beyond) instead of `2026-08-13 09:41`.
-    #
-    # ⛔ THE CLIENT MUST NOT READ ITS OWN CLOCK, which is D-208's exit condition word for word and
-    # is why this key exists rather than a `new Date()` in the browser. `at` is sent as UTC WITH
-    # its offset (D-18) precisely so every reader sees the same instant; deciding "is this today?"
-    # against a browser clock would re-introduce the drift the offset exists to remove — a reader a
-    # day ahead being told an event happened tomorrow [[date-window-vocabulary]]. Both operands
-    # now come from the same machine.
-    # ⚠ Same funnel as the enrichment, so the read door and the mark-read door cannot disagree —
-    # the note two lines up records what happened last time only one of them was enriched.
-    return {**box, "now": alerts._now_iso(),
-            "items": [notification_view(n) for n in items]}
-
-
-def _view_by_id(g, view_id):
-    """One saved view out of an assembly, by id. `None` when there is no such view.
-
-    ⛔⛔ W33-T29 (owner: *"Alert me about new records"* answering "Something went wrong") — THIS
-    FUNCTION EXISTS BECAUSE TWO CALL SITES BOTH WROTE `(g.get("views") or {}).get(view_id)`, AND
-    `g["views"] IS A LIST`. `aios_grid.views_from_defs` returns `[{...}]`, `workspace_wire` passes
-    it straight out and both `ut_assembly` and `grid_assembly` return it unchanged — so `.get` on
-    it raises `AttributeError`, and `views_from_defs` always returns at least one element, so the
-    `or {}` never fires. **It raised on EVERY call, on every topic, since wave 20.**
-
-    ⛔ AND THE TWO SITES FAILED DIFFERENTLY, WHICH IS WHY ONLY ONE WAS EVER REPORTED. In
-    `_require_filtered_view` the raise lands ABOVE the handler's own `try`, so it leaves as a bare
-    FastAPI 500 and the client's `errorMessage` turns any 5xx into *"Something went wrong on our
-    side"* — the exact sentence the owner reported (D-107's shape, again: an attribute error above
-    the guard arrives as plain text rather than as our envelope). In `_evaluate` the identical
-    line is swallowed by `/notifications`' `except Exception: continue`, so **every stored
-    view-alert was silently dropped from the Inbox** and nobody had anything to report at all.
-    One expression, one loud symptom and one silent one.
-
-    ⚠ SO IT IS A FUNCTION, NOT TWO FIXED LINES. Two copies of "find the view" is what let one site
-    be discussed for three waves while its twin went unnoticed [[one-question-two-normalizers]].
-
-    ⚠ It accepts a dict too, and that is not defensive noise: `verify_alerts`' door fixture was
-    keyed `{id: view}` — which is precisely why the gate was green while production raised on
-    every call. The fixture is moving to the production shape in this same change, and tolerating
-    both here means a caller that legitimately holds one cannot resurrect the bug.
-    """
-    want = str(view_id or "")
-    if not want:
-        return None
-    views = (g or {}).get("views")
-    if isinstance(views, dict):
-        found = views.get(want)
-        return found if isinstance(found, dict) else None
-    if not isinstance(views, list):
-        return None
-    for v in views:
-        if isinstance(v, dict) and str(v.get("id") or "") == want:
-            return v
-    return None
-
-
-def _topic_or_400(raw):
-    topic = str(raw or "").strip().lower()
-    if topic.startswith("ut_") or topic in _TOPICS:
-        return topic
-    raise err(400, "bad_topic", f"topic must be one of {', '.join(_TOPICS)} or a ut_ table")
-
-
-def _owner_session(session: Session, owner: str):
-    """A `Session` for the alert's OWNER (see the module note on why the owner, not the caller).
-
-    ⚠ `Session` exposes `uname`/`admin` as PROPERTIES derived from `user`, not as fields — so an
-    owner session is built by swapping the `user` RECORD and letting both derive themselves. An
-    earlier version passed `uname=`/`admin=` to the constructor, which would have raised on the
-    first write hook of the wave; the properties are the single definition of who a session is,
-    and going around them is how a session with an admin flag and a non-admin record exists.
-
-    Returns None when the owner is gone or deactivated — their alerts then stop evaluating rather
-    than evaluating as somebody else, which is the fail-closed direction.
-    """
-    import core.users as users
-
-    if str(owner) == str(session.uname):
-        return session
-    rec = (users.registry() or {}).get(str(owner))
-    if not isinstance(rec, dict) or not rec.get("active", True):
-        return None
-    # `_public` is THE definition of what a session may know about its own account (never a hash
-    # or a salt) — the same one `routes_auth` uses. Building the dict by hand here would be a
-    # second definition, and the one that leaks is always the copy.
-    return Session(tenant=session.tenant, user=users._public(str(owner), rec),
-                   claims=session.claims, runtime=session.runtime)
-
-
-def _evaluate(session: Session, rec: dict, assemblies=None):
-    """Resolve `rec`'s view over its topic AS THE ALERT'S OWNER, then fold the result in.
-
-    ⭐⭐ W31-T24 — `assemblies` IS A PER-REQUEST MEMO, KEYED `(topic, owner)`, and it is the whole
-    of this ticket's server half. `/notifications` re-evaluates EVERY alert inline on read and each
-    one built a FULL assembly — the pool, the workspace, `rows_from_pool` over every row. Two
-    alerts on one view built that table twice; ten built it ten times. Nothing dedupes them,
-    because each `_evaluate` was a closed call.
-    ⚠ `(topic, owner)` and not `topic`: the assembly is built as the alert's OWNER (see the module
-    note — evaluating a BU-scoped user's alert on a full-access admin's pool is a permission leak
-    wearing a notification's clothes), so two owners on one topic are two DIFFERENT tables and
-    must never share an entry. Getting that key wrong is the one way this optimisation could leak.
-    ⚠ Passing nothing keeps the old behaviour exactly, which is what the create/run doors want:
-    they evaluate ONE alert and a memo for a single call is pure overhead.
-    """
-    import aios_grid
-    from harness import filter_eval
-
-    owner_sess = _owner_session(session, rec.get("owner"))
-    if owner_sess is None:
-        return {"skipped": "owner_unavailable"}
-    topic = str(rec.get("topic") or "")
-    memo_key = (topic, str(owner_sess.uname))
-    g = assemblies.get(memo_key) if isinstance(assemblies, dict) else None
-    if g is None:
-        try:
-            if topic.startswith("ut_"):
-                from routes_tables import ut_assembly
-                # ⛔ `consume_corrections=False`, and the default was a REAL BUG, not a tidy-up.
-                # `ut_assembly` defaults it True, so every `/notifications` read CONSUMED the
-                # one-shot field-name correction acks for every `ut_` topic that has an alert —
-                # taking them from the `/workspace` refresh that exists to show them to the person
-                # who made the edit. The customer branch below has always passed False; this one
-                # inherited a default nobody re-read. An inbox poll must never consume a one-shot.
-                g = ut_assembly(owner_sess, topic,
-                                storage_key=f"{owner_sess.tenant}:{topic}:{owner_sess.uname}",
-                                consume_corrections=False)
-            else:
-                from routes_customers import grid_assembly
-                g = grid_assembly(owner_sess, scope=topic, consume_corrections=False)
-        except Exception as e:                              # noqa: BLE001
-            # ⭐ W32-T22 — SKIPPING IS FINE HERE; SKIPPING ANONYMOUSLY IS NOT. This one must not
-            # raise (one bad alert cannot empty an inbox), so unlike `_require_filtered_view` it
-            # keeps a blanket catch — but it now reports the refusal's OWN code where there is
-            # one. `type(e).__name__` said `HTTPException` for four different causes, and
-            # `lastError` is the only place a user ever learns why an alert stopped firing.
-            #
-            # ⚠ `with_rows=True` STAYS on this path, deliberately: unlike the create door, an
-            # evaluation genuinely needs the rows to run the filter over. So an alert on a
-            # read-through grid is created (T22) and then skips at evaluation with
-            # `window_required` naming why — which is D-184's remaining half, and it is a
-            # SENTENCE now rather than silence.
-            return {"skipped": _refusal_code(e) or "unavailable", "detail": type(e).__name__}
-        if isinstance(assemblies, dict):
-            assemblies[memo_key] = g
-
-    view = _view_by_id(g, rec.get("viewId"))
-    if not isinstance(view, dict):
-        # Deleted, or un-shared out from under the alert. Say so on the RECORD rather than
-        # deleting the alert: an alert that silently vanishes is indistinguishable from one that
-        # never fires, and the user cannot debug what is not there.
-        return {"skipped": "view_missing"}
-
-    # The SAME row build the grid and `/customers` use — `rows_from_pool` is what puts derived
-    # and overlay values on a row. Evaluating a filter against raw pool dicts would silently
-    # never match any condition on a user-created or measure column.
-    #
-    # ⛔⛔ AND "THE SAME ROW BUILD" WAS NOT TRUE, WHICH MADE EVERY ALERT ON A `ut_*` DATABASE BLIND
-    # TO IMPORTED DATA. Found by a verifier driving one real assembly through both paths.
-    #
-    # `routes_tables.table_rows` — the grid the person is looking at — merges the DEFINITION rows
-    # underneath the overlay ("base first, overlay wins"; that merge is itself the fix for owner
-    # item 3, *"it all got reseted"*). `_evaluate` is a second copy of that read and never got it:
-    # it handed `ws['overlays']` to `rows_from_pool` raw, so for a `ut_*` table every base cell
-    # evaluated as BLANK. Measured on one assembly, same view, same rows:
-    #     rows_src        state='unpaid' / 'paid'
-    #     _evaluate saw   state=''       / ''          ⇐ every base cell blank
-    #     the GRID saw    state='unpaid' / 'paid'
-    # so `state eq unpaid` matched NOTHING while the view showed one row, and `state isEmpty`
-    # matched EVERYTHING while the view showed none. **The alert did not merely miss rows — it
-    # inverted.** End to end: a row whose value arrived by import, automation, paste or the create
-    # door never fired; only a value typed as a hand EDIT did.
-    #
-    # ⚠ Scope, so nobody widens the fix past its cause: materialised `ut_*` tables are hit;
-    # `customer`/`product` are not (their fields are `source: "odoo"` and read off `rows_src`);
-    # `ut_odoo_*` never reaches here (`with_rows=True` refuses first and returns
-    # `skipped: window_required`).
-    # ⛔ ORDER IS LOAD-BEARING AND IS THE GRID'S: base underneath, overlay ON TOP. Inverting it
-    # would let a stale definition value shadow an edit the user has just made — the same defect
-    # `table_rows`' own note records, arriving from the other side.
-    _ov = (g.get("ws") or {}).get("overlays") or {}
-    _merged = {}
-    for _r in g["rows_src"]:
-        _pid = str(_r.get("pid"))
-        _cells = {k: v for k, v in _r.items() if k != "pid"}
-        _o = _ov.get(_pid)
-        if isinstance(_o, dict):
-            _cells.update(_o)
-        _merged[_pid] = _cells
-    rows = aios_grid.rows_from_pool(g["rows_src"], g["fields"], _merged,
-                                    derived=g.get("derived"))
-    config = view.get("config") or view
-    ctx = filter_eval.EvalCtx(
-        cohort_sets={str(k): {str(p) for p in (v.get("memberPids") or ())}
-                     for k, v in (g.get("lists") or {}).items() if isinstance(v, dict)},
-        measure_sets=g.get("measure_sets") or {},
-        today=g.get("today"))
-    pids = filter_eval.visible_pids(config.get("filters") or [], rows, g["fields"], ctx,
-                                    member_pids=config.get("memberPids"))
-    labels = {str(r.get("pid")): str(r.get("name") or r.get("pid")) for r in rows}
-    return alerts.evaluate(rec.get("id"), [str(p) for p in pids],
-                           labels=labels, partial=False, st=session.runtime)
-
-
-@router.get("/alerts")
-def list_alerts(session: Session = Depends(require_session)):
-    return {"alerts": alerts.list_alerts(user=session.uname, is_admin=session.admin,
-                                         st=session.runtime)}
-
-
-@router.post("/alerts")
-def create_alert(body: dict = Body(default=None), session: Session = Depends(require_session)):
-    body = body or {}
-    view_id = str(body.get("viewId") or "").strip()
-    if not view_id:
-        raise err(400, "bad_view", "an alert needs the id of the view it watches")
-    topic = _topic_or_400(body.get("topic"))
-    _require_filtered_view(session, topic, view_id)
-    import uuid
-    aid = f"al_{uuid.uuid4().hex[:12]}"
-    rec = alerts.create(aid, view_id=view_id, topic=topic, owner=session.uname,
-                        label=body.get("label") or "", st=session.runtime)
-    # SEED IMMEDIATELY, so the alert starts from "everything currently matching is old news".
-    # Deferring this to the first write hook would mean the next edit announces the whole view.
-    outcome = _evaluate(session, rec)
-    return {"alert": {**rec, "seeded": True}, "first": outcome}
-
-
-def _require_filtered_view(session: Session, topic: str, view_id: str):
-    """400 unless `view_id` exists on `topic` AND actually narrows something.
-
-    ⛔ AN ALERT ON AN UNFILTERED VIEW IS SILENTLY INCAPABLE OF ALERTING, which is worse than one
-    that is refused. `filter_eval` treats an inactive tree as "no narrowing, every row shows"
-    (`visible_pids`'s own rule), so such an alert seeds with the entire table and can never see an
-    entrant again — there is nothing left to enter. The owner's words are *"when a Record gets
-    into that Filter's criteria"*: no criteria, no alert, and said at creation rather than
-    discovered by never being notified.
-
-    `is_rule_active` is the SAME activeness predicate the engine and the column tints use — a
-    half-typed rule is not a filter, and this must agree with what actually narrows or it would
-    accept a view whose one rule the engine then ignores.
-
-    ⭐⭐ WAVE 32 · T22 (owner item 17) — THIS FUNCTION WAS THE ERROR. Two defects, stacked, and
-    the second one hid the first.
-
-    (1) **IT ASKED FOR EVERY ROW OF A TABLE IT NEVER LOOKS AT.** The only thing read below is
-        `g["views"]`. `ut_assembly` defaults `with_rows=True`, so creating an alert on a
-        read-through grid built the whole pool — and `scoped_pool` refuses that with
-        `409 window_required` over 963,783 rows, exactly as it is supposed to. `with_rows=False`
-        (W31-T20's flag, built for precisely this) answers the same question with `scoped_pids`,
-        runs the SAME `_defn_or_refuse` wall, and does not refuse. **That is D-184's create half,
-        closed** — an alert on a read-through grid can now be made at all.
-    (2) **A BLANKET `except Exception` TURNED EVERY NAMED REFUSAL INTO A 503.** `HTTPException`
-        is an `Exception`, so `404 unknown_table`, `403 forbidden`, `409 window_required` and
-        `503 store_not_ready` — four refusals that each say what is wrong — were all replaced by
-        *"the table is unavailable — try again in a moment"*. ⛔ AND THAT SENTENCE NEVER REACHED
-        A USER EITHER: `alertsApi.errorMessage` discards the text of any status ≥ 500 by design
-        (a 5xx body is the server's internals), substituting *"Something went wrong on our
-        side."* — which is the owner's screenshot, word for word. A knowable cause returned as a
-        5xx is invisible by construction, so re-wording the 503 could never have fixed this.
-    ⚠ The except is narrowed, not deleted: an UNEXPECTED failure is still a 503, because that is
-    honest. What it may no longer do is catch a refusal that already knows its own name.
-    """
-    from fastapi import HTTPException
-
-    from harness import filter_eval
-
-    try:
-        if topic.startswith("ut_"):
-            from routes_tables import ut_assembly
-            # ⚠ `consume_corrections=False` — the customer branch has always passed it and this
-            # one inherited a default nobody re-read. Creating an alert must not eat the one-shot
-            # field-name correction acks belonging to the `/workspace` refresh that exists to show
-            # them to the person who made the edit. Same defect `_evaluate`'s header records.
-            g = ut_assembly(session, topic,
-                            storage_key=f"{session.tenant}:{topic}:{session.uname}",
-                            consume_corrections=False, with_rows=False)
-        else:
-            from routes_customers import grid_assembly
-            g = grid_assembly(session, scope=topic, consume_corrections=False)
-    except HTTPException:
-        raise                                               # it already names its own cause
-    except Exception as e:                                  # noqa: BLE001
-        # Genuinely unexpected. Still a 503, and now it carries the exception TYPE — without it,
-        # the one path that reaches this branch is also the one path with nothing to debug from.
-        raise err(503, "unavailable",
-                  f"the table could not be read ({type(e).__name__}) — try again in a moment")
-    view = _view_by_id(g, view_id)
-    if not isinstance(view, dict):
-        raise err(404, "no_view", "that view does not exist on this table")
-    nodes, _conj = filter_eval.tree_parts((view.get("config") or view).get("filters") or [])
-
-    # ⛔⛔ WAVE 33 · T29 — **CORRECTION: THE BLOCK BELOW IS TRUE ABOUT THE CODE AND FALSE ABOUT
-    # PRODUCTION, AND IT MUST BE READ SECOND.** It claims the missing-argument `TypeError` "IS
-    # owner item 17" — the owner's *"Something went wrong"*. It was not, and it could not have
-    # been: at `cbcf005`, the build the owner was using, the dict-read on `views` sat ~10 lines
-    # ABOVE this call and raised `AttributeError` on EVERY request, so the walk never reached the
-    # leaf and the arity bug was unreachable. `_view_by_id`'s own header records that fix.
-    #
-    # ⚠ WHY THE STALE PARAGRAPH STAYS RATHER THAN GETTING DELETED: the arity bug was real, the
-    # fix was right, and the three reasons it hid are the most transferable thing in this file.
-    # What was wrong is only its CLAIM TO BE THE CAUSE. Two comment blocks in one function each
-    # naming themselves as the origin of the same screenshot are mutually exclusive, and the next
-    # reader believes whichever they meet first — which is why this correction sits above rather
-    # than below. Caught by a verifier that read the SHIPPED file at the deployed commit instead
-    # of the working tree. [[grep-output-is-not-source]]
-    #
-    # ⛔⛔ WAVE 32 · T22 — **THE CALL BELOW WAS MISSING AN ARGUMENT** (and wave 32 believed, wrongly,
-    # that this was owner item 17 — see the correction directly above).
-    #
-    # `is_rule_active(rule, columns)` takes TWO parameters (`harness/filter_sql.py`; every other
-    # caller in the repo passes both). This one passed ONE, so the moment the walk reached a LEAF
-    # rule it raised `TypeError: is_rule_active() missing 1 required positional argument`.
-    #
-    # ⚠ READ WHAT THAT MEANS BEFORE FIXING ANYTHING ELSE: the walk only reaches a leaf when the
-    # view HAS a condition — and a view with a condition is the only kind an alert is allowed on.
-    # A view with no filters yields an empty `nodes`, so `_any_active` returns False without ever
-    # calling this, and the reader gets the honest 400 `no_filter`. **So the only path that
-    # worked was the refusal path: "Alert me about new records" had never once created an alert
-    # on a filtered view.** ⛔ And the raise lands OUTSIDE the `try` above, so it was not even the
-    # 503 — it was a bare FastAPI 500, which `alertsApi.errorMessage` renders as *"Something went
-    # wrong on our side. Try again in a moment."*, the owner's screenshot word for word.
-    #
-    # ⚠ THREE THINGS HID IT, and they are worth more than the fix. (1) Python does not check
-    # arity until the line RUNS, and this line runs only on the success path of a feature whose
-    # every test exercised its refusals. (2) The `no_filter` 400 above it is a real, correct,
-    # well-tested refusal, so the door looked alive. (3) `verify_alerts.py` asserts the refusal
-    # (`no_filter` reaches the user) and the transport — never a creation. A gate can be green,
-    # thorough and honest about everything except the one path the feature exists for.
-    #
-    # `_columns_map` is the DEFINITION of fields -> the membership set `is_rule_active` looks a
-    # column up in; building a second dict here would be a second answer to one question, which
-    # is this wave's other headline defect in a different file. Its leading underscore is a real
-    # smell and is BOOKED (PENDING, mailbox/C.md) rather than worked around.
-    columns = filter_eval._columns_map(g.get("fields") or [])
-
-    def _any_active(ns):
-        for n in ns or ():
-            if isinstance(n, dict) and isinstance(n.get("children"), list):
-                if _any_active(n["children"]):
-                    return True
-            elif filter_eval.is_rule_active(n, columns):
-                return True
-        return False
-
-    if not _any_active(nodes):
-        raise err(400, "no_filter",
-                  "this view has no active filter, so no record can ever ENTER it — add a "
-                  "condition to the view first, then create the alert")
-
-
-@router.delete("/alerts/{alert_id}")
-def delete_alert(alert_id: str, session: Session = Depends(require_session)):
-    rec = next((r for r in alerts.list_alerts(st=session.runtime)
-                if str(r.get("id")) == str(alert_id)), None)
-    if rec is None:
-        raise err(404, "no_alert", "that alert does not exist")
-    if str(rec.get("owner")) != str(session.uname) and not session.admin:
-        raise err(403, "not_yours", "only the alert's owner (or an administrator) can delete it")
-    alerts.delete(alert_id, st=session.runtime)
-    return {"ok": True}
-
-
-@router.post("/alerts/{alert_id}/run")
-def run_alert(alert_id: str, session: Session = Depends(require_session)):
-    rec = next((r for r in alerts.list_alerts(user=session.uname, is_admin=session.admin,
-                                              st=session.runtime)
-                if str(r.get("id")) == str(alert_id)), None)
-    if rec is None:
-        raise err(404, "no_alert", "that alert does not exist")
-    return _evaluate(session, rec)
-
-
-@router.get("/notifications")
-def notifications(session: Session = Depends(require_session)):
-    """The inbox — RE-EVALUATED on read, which is a deliberate design choice.
-
-    ⭐ A-S1-2 RESOLVED THE OTHER WAY, and the reason is structural rather than a shortcut. The
-    plan was a push hook: the automation engine calls `after_write` when it lands rows. But
-    `run_async` runs on a BACKGROUND THREAD with no `Session` in scope, and an alert must be
-    evaluated as its OWNER (see `_evaluate`) — so a push hook would have to mint a session inside
-    a worker thread from a tenant runtime, which is exactly the kind of ad-hoc identity
-    construction that leaks scope.
-
-    Pulling on read has none of that: the caller IS a session, the assemblies are already
-    scope-cached, and the user cannot observe the difference — an inbox is only ever read by
-    someone opening it. The cost is that a notification is minted when you LOOK rather than when
-    the row landed, so the `at` stamp is detection time, not arrival time.
-
-    `after_write` stays exported for the day the engine can hand over a real identity.
-
-    ⭐⭐ W31-T24 — ONE ASSEMBLY PER (TOPIC, OWNER), NOT ONE PER ALERT.
-    ⛔ MEASURED FIRST, AND THE MEASUREMENT CORRECTS AN EARLIER READING OF IT. This route is
-    **20 ms in-process and 3,280 ms live** on tenant #0 — but tenant #0 has **ZERO alerts**
-    (censused 2026-08-12), so the 20 ms is an EMPTY LOOP and says nothing at all about what the
-    re-evaluation costs. The live 3,280 ms is the two store reads either side of that loop. So the
-    body below is not slow today; it is UNEXERCISED, and every alert a tenant creates adds a whole
-    grid assembly to an inbox poll. The memo turns O(alerts) into O(distinct topic × owner), which
-    is the difference between "fine" and "three seconds per alert" the day somebody uses the
-    feature. ⚠ Making the read cheap by evaluating LESS is the obvious wrong fix and is not what
-    this does: every alert is still evaluated, against the same rows, in the same order.
-    """
-    assemblies = {}
-    for rec in alerts.list_alerts(user=session.uname, is_admin=False, st=session.runtime):
-        try:
-            _evaluate(session, rec, assemblies=assemblies)
-        except Exception:                                   # noqa: BLE001
-            continue                                        # one bad alert must not empty the pane
-    # ⭐ W32-T20 (C3): every item leaves through `inbox_view`, so a notification queued before
-    # this wave carries a `target` too. See `notification_view`'s header for why it is derived.
-    return inbox_view(alerts.inbox(session.uname, st=session.runtime))
-
-
-@router.post("/notifications/read")
-def read_notifications(body: dict = Body(default=None),
-                       session: Session = Depends(require_session)):
-    body = body or {}
-    ids = body.get("ids")
-    if ids is not None and not isinstance(ids, list):
-        raise err(400, "bad_ids", "ids must be a list, or null to mark every notification")
-    # ⚠ THE SAME ENRICHMENT ON BOTH DOORS. `mark_read` returns a fresh inbox, and the Inbox
-    # module re-renders from it — an un-enriched answer here would strip `target` off every row
-    # the moment somebody marked one read, i.e. the feature would work until first use.
-    return inbox_view(alerts.mark_read(session.uname, ids, read=bool(body.get("read", True)),
-                                       st=session.runtime))
-
-
-def after_write(session: Session, topic_key: str):
-    """THE WRITE HOOK — call after a write that could change what a view matches.
-
-    Exported as a plain function (not a route) so `core.grid_events`' callers and S2's automation
-    upserts reach it the same way. It never raises: an alert evaluation failing must not fail the
-    edit that triggered it.
-
-    ⭐ W31-T24 — it shares `/notifications`' memo shape for the same reason: a write that changes
-    one view can trip several alerts on the SAME topic, and each would otherwise rebuild the table.
-    ⚠ STILL ZERO PRODUCTION CALLERS (W31-T24 confirmed it; the route docstring above says why the
-    push hook was resolved the other way). Booked rather than wired: minting a session inside the
-    engine's worker thread is the ad-hoc identity construction this file exists to avoid.
-    """
-    try:
-        assemblies = {}
-        return alerts.after_write(topic_key, st=session.runtime,
-                                  runner=lambda rec: _evaluate(session, rec,
-                                                               assemblies=assemblies))
-    except Exception:                                       # noqa: BLE001
-        return {"evaluated": 0}
+"""routes_alerts.py — the Alerts module (wave 20, owner item 25, contract C-ALERT).
+
+    GET    /api/v1/alerts                  -> {alerts:[...]}
+    POST   /api/v1/alerts                  <- {viewId, topic, label?}
+    DELETE /api/v1/alerts/{alert_id}
+    POST   /api/v1/alerts/{alert_id}/run   -> evaluate now (the pane's manual refresh)
+    GET    /api/v1/notifications           -> {unread, items:[...]}
+    POST   /api/v1/notifications/read      <- {ids:[...]|null, read?:bool}
+
+The semantics — an alert is a view plus a remembered matched set, a notification is a NEW
+ENTRANT, and the first evaluation seeds silently — live in `core.alerts` with the reasoning.
+This file owns the two things a route must: WHO may do it, and HOW the view gets evaluated.
+
+⭐ **THE EVALUATION RUNS AS THE ALERT'S OWNER, NOT AS THE CALLER.** `_run_alert` builds the pool
+for `rec['owner']`, never for whoever tripped the write hook. Any other choice leaks: a
+full-access admin editing a cell would otherwise evaluate a BU-scoped user's alert over the whole
+book, and the notification would name customers that user may not see — a permission leak wearing
+a notification's clothes. The owner's own scope is the only correct basis for their alert.
+
+⚠ **AN ALERT IS NOT A SECOND READ PATH.** It resolves rows through the same
+`routes_customers.grid_assembly` / `routes_tables.ut_assembly` the grid uses, so a row that an
+alert can see is by construction a row its owner could open. Re-implementing the filter here
+would be a second definition of "matches", and those two would drift.
+"""
+import re
+
+from fastapi import APIRouter, Body, Depends
+
+import core.alerts as alerts
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+#: The alert-bearing surfaces. `ut_` tables are admitted by prefix, like everywhere else.
+_TOPICS = ("customer", "product")
+
+# ── ⭐⭐ WAVE 32 · T20 · CONTRACT C3 — THE INBOX SHAPE, DERIVED ON READ ────────────────────────
+#
+# `GET /notifications` gains `subject`, `kind` and `target` per item (`read` was always there).
+#
+# ⛔ DERIVED, NEVER STORED, AND THAT IS THE WHOLE OF WHY THIS WAVE EXISTS. Stamping the three
+# keys onto the record at write time would give them to notifications minted AFTER the deploy and
+# to nothing else — every notification already sitting in every tenant's inbox would open nothing,
+# and the feature would be correct in the source and absent from the product
+# ([[a-migration-that-runs-on-the-next-write]], D-201). A read-side derivation reaches a
+# notification queued last month. It also keeps the store shape out of `core/alerts.py`, which is
+# another lane's file this wave — but that is the convenience, not the reason.
+#
+# ⚠ TWO PRODUCERS WRITE TWO SHAPES into one inbox, and the vocabulary below is what tells them
+# apart. `_queue` (a record ENTERED a watched view) sets `topic`+`viewId`. `notify()` sets
+# `topic='automation'` and puts the producer's key in `alertId`, leaving `viewId` empty. Deciding
+# here means the client branches on ONE field instead of re-deriving the same split.
+#
+# ⛔ **D-101 IS CLOSED HERE, BY SUBTRACTION.** There was a THIRD shape — `kind='automation_review'`
+# + `autoId`, a card arriving at a review stage — and its producer `notify_review` was deleted by
+# W27/R3 with the review lanes. `automation_engine.py`'s own tombstone (search `notify_review`)
+# records the 2026-08-12 sweep: **no `.py` file anywhere produces one**, while the client branch,
+# its route and three gate legs stayed fully alive. D-101's exit condition is *"the client review
+# branch is deleted in the same change as any remaining residue, OR `notify_review` gains its real
+# caller"* — the residue is zero, so the branch goes. It is not carried into the Inbox: a stored
+# review notification (if any survives in a tenant from the wave-23 era) derives as an ordinary
+# `alert` with no target, i.e. an honest unclickable row, which is correct — the board it pointed
+# at was deleted two waves ago.
+
+#: C3's `kind` vocabulary. Plain strings on the wire — the client must never union over them
+#: (alertsModel's wave-9 law: a client union turns "the server grew a kind" into a dropped row).
+NOTIF_KIND_ALERT = "alert"
+NOTIF_KIND_AUTOMATION = "automation"
+NOTIF_KIND_SHARE = "share"
+
+#: C3's `target.module` vocabulary, and the automation sub-selection.
+TARGET_MODULE_DATABASE = "database"
+TARGET_MODULE_AUTOMATION = "automation"
+TARGET_TAB_RUNS = "runs"
+
+#: The topic `notify()` carries for a SHARE (W32-T28 writes it; nothing does yet, and a kind with
+#: no producer is a string that reads as a feature — the reason this constant is named here and
+#: cited from `routes_shares` rather than typed twice).
+SHARE_TOPIC = "share"
+
+#: `core.alerts.notify`'s default topic for a run outcome. Mirrors `inboxModel.AUTOMATION_TOPIC`.
+AUTOMATION_TOPIC = "automation"
+
+_UT_TOPIC = re.compile(r"ut_[A-Za-z0-9_]+\Z")
+
+
+def route_for_topic(topic):
+    """A grid SCOPE key -> the registry route that renders it, or None.
+
+    ⛔ THE SAME TABLE AS `alertsModel.routeForTopic`, and the parity is GATED
+    (`verify_alerts.py`'s vocabulary scan) rather than trusted. The two built-ins are the only
+    pair that differ — the registry names the surface (`customer_data`) while the grid names the
+    scope (`customer`) — so a topic passed through as a route sends every click to a page that
+    does not exist. `None` for anything else: a target this product cannot resolve must be ABSENT
+    rather than plausible, because an absent target renders as a row that does not pretend to be
+    clickable, and a wrong one renders as a click that silently goes nowhere.
+    """
+    t = str(topic or "").strip()
+    if t == "customer":
+        return "customer_data"
+    if t == "product":
+        return "product_data"
+    if _UT_TOPIC.match(t):
+        return t
+    return None
+
+
+def _refusal_code(exc):
+    """The `error.code` an `HTTPException` raised by `deps.err()` carries, or `""`.
+
+    ⭐ W32-T22. Four refusals travel up the assembly chain — `unknown_table` (404), `forbidden`
+    (403), `window_required` (409) and `store_not_ready` (503) — and each already names its own
+    cause. Anything that reduces all four to one word is throwing away the only information the
+    reader could have acted on. Returns `""` for a plain exception, so a caller can tell
+    "refused, and here is why" apart from "broke, and we do not know why".
+    """
+    detail = getattr(exc, "detail", None)
+    if isinstance(detail, dict):
+        inner = detail.get("error")
+        if isinstance(inner, dict):
+            return str(inner.get("code") or "")
+    return ""
+
+
+def notification_view(item):
+    """One STORED notification -> the shape the Inbox renders. PURE, and total.
+
+    Never raises and never drops a row: an item it cannot classify comes back as an `alert` with
+    no `target`, which the client renders as an unclickable row rather than hiding. An inbox that
+    silently omits what it does not understand is the one failure a reader cannot detect.
+    """
+    if not isinstance(item, dict):
+        return item
+    topic = str(item.get("topic") or "").strip()
+    alert_id = str(item.get("alertId") or "").strip()
+
+    # ⛔ THE ID TEST IS HALF OF EVERY BRANCH, and it is the load-bearing half. A row whose topic
+    # says `automation` but whose producer key never arrived (a truncated payload, a server
+    # mid-deploy) would otherwise be handed a target naming NOTHING — a click that appears to work
+    # and silently does not, which is this repo's most-repeated failure shape. Failing the test
+    # drops it to the `alert` branch, where `route_for_topic` refuses out loud by answering None.
+    if topic == AUTOMATION_TOPIC and alert_id:
+        kind = NOTIF_KIND_AUTOMATION
+        target = {"module": TARGET_MODULE_AUTOMATION, "id": alert_id, "tab": TARGET_TAB_RUNS}
+    elif topic == SHARE_TOPIC and alert_id:
+        # ⭐ W32-T28: the sharer writes `key=<the ROUTE to open>` and, for a shared VIEW,
+        # `row_id=<the view to select>`.
+        #
+        # ⛔ `key` IS ALREADY A ROUTE, NOT A RAW OBJECT ID, and the first version of this got it
+        # wrong in a way worth recording: a shared VIEW put the VIEW's id in `alertId`, so the
+        # target read `{module: "database", id: "view_42"}` — an instruction to open a database
+        # called `view_42`. It looked right in the payload and would have opened nothing. The
+        # producer resolves the object to its topic and hands over the route; this branch only
+        # shapes what it is given.
+        kind = NOTIF_KIND_SHARE
+        row_id = str(item.get("rowId") or "").strip()
+        target = {"module": TARGET_MODULE_DATABASE, "id": alert_id,
+                  **({"tab": row_id} if row_id else {})}
+    else:
+        kind = NOTIF_KIND_ALERT
+        route = route_for_topic(topic)
+        view_id = str(item.get("viewId") or "").strip()
+        target = None if route is None else (
+            {"module": TARGET_MODULE_DATABASE, "id": route,
+             **({"tab": view_id} if view_id else {})})
+
+    # The email split: `subject` is the HEADER (what this is about — the alert, the automation,
+    # the database), `label` stays the BODY (what happened — the record that entered, the run
+    # summary). They were one field, which is why a notification read as a sentence with no
+    # sender and the pane could not be laid out like mail.
+    subject = str(item.get("alertLabel") or "").strip() or str(item.get("label") or "").strip()
+    # ⚠ `kind` is OVERWRITTEN, not merged. There was one stored value (`automation_review`) and it
+    # is D-101's dead one; leaving it through would give the client two vocabularies for one
+    # question, which is the defect this wave's item 6 is about in a different file.
+    # ⭐⭐ W33-T28 (owner: "the Inbox reads like email") — THE SENDER, WHICH DID NOT EXIST.
+    #
+    # ⛔ A `verifier` reading the finished wave-32 surface found that the row's sender POSITION was
+    # occupied by `kindLabel(n.kind)` — the literals "Alert" / "Automation" / "Shared with you" —
+    # i.e. a CATEGORY standing where a who belongs, and no sender field anywhere on the wire, in
+    # the model or in the markup. Mail has a from. This is it.
+    #
+    # ⚠ IT IS DERIVED HERE, NOT STORED, FOR EVERY KIND BUT ONE — and the exception is the point.
+    # An alert firing and an automation landing rows have no person behind them; their honest
+    # sender is the machine that did it, named as the thing the reader recognises. A SHARE has a
+    # real person, and only the producer knows who: `routes_shares.py` writes it as `actor` and
+    # this reads it back. ⛔ It is NOT parsed out of the body prose ("<name> shared this with
+    # you") — a sender recovered by regexing a sentence breaks the first time the sentence is
+    # reworded, and it would break silently, in the header.
+    #
+    # ⚠ FALLS BACK, NEVER BLANK. A share queued BEFORE `actor` existed has none, and a row with an
+    # empty from column reads as a broken inbox rather than as an old notification.
+    actor = str(item.get("actor") or "").strip()
+    if kind == NOTIF_KIND_SHARE:
+        sender = actor or "A teammate"
+    elif kind == NOTIF_KIND_AUTOMATION:
+        # ⛔ "Agents", not "Automation" (W34-T40, corrected at QA 2026-08-17). The client's
+        # `senderOf` already falls back to `AGENTS_MODULE_LABEL` — but `if (sent) return sent`
+        # runs FIRST, so this server literal won and every actor-less automation notification
+        # showed the retired module name in the inbox's From column.
+        sender = actor or "Agents"
+    else:
+        sender = actor or "Alerts"
+    out = {**item, "read": bool(item.get("read")), "kind": kind,
+           "subject": subject or "Notification", "sender": sender}
+    if target is not None:
+        out["target"] = target
+    return out
+
+
+def inbox_view(box):
+    """`core.alerts.inbox()`'s answer, with every item put through {@link notification_view}.
+
+    ⚠ `unread` IS NOT RECOUNTED. It is the ACCOUNT's number and `items` is one page of it; a
+    recount here would make the badge a function of whatever this page happened to include, which
+    is the exact defect `alertsModel.parseInbox`'s own header records from the other side.
+    """
+    if not isinstance(box, dict):
+        return box
+    items = box.get("items")
+    if not isinstance(items, list):
+        return box
+    # ⭐⭐ W33-T28 / D-208 — THE SERVER'S CLOCK RIDES WITH THE PAGE, and it is what lets the client
+    # render a mail-shaped stamp ("09:41" today, "Aug 12" beyond) instead of `2026-08-13 09:41`.
+    #
+    # ⛔ THE CLIENT MUST NOT READ ITS OWN CLOCK, which is D-208's exit condition word for word and
+    # is why this key exists rather than a `new Date()` in the browser. `at` is sent as UTC WITH
+    # its offset (D-18) precisely so every reader sees the same instant; deciding "is this today?"
+    # against a browser clock would re-introduce the drift the offset exists to remove — a reader a
+    # day ahead being told an event happened tomorrow [[date-window-vocabulary]]. Both operands
+    # now come from the same machine.
+    # ⚠ Same funnel as the enrichment, so the read door and the mark-read door cannot disagree —
+    # the note two lines up records what happened last time only one of them was enriched.
+    return {**box, "now": alerts._now_iso(),
+            "items": [notification_view(n) for n in items]}
+
+
+def _view_by_id(g, view_id):
+    """One saved view out of an assembly, by id. `None` when there is no such view.
+
+    ⛔⛔ W33-T29 (owner: *"Alert me about new records"* answering "Something went wrong") — THIS
+    FUNCTION EXISTS BECAUSE TWO CALL SITES BOTH WROTE `(g.get("views") or {}).get(view_id)`, AND
+    `g["views"] IS A LIST`. `aios_grid.views_from_defs` returns `[{...}]`, `workspace_wire` passes
+    it straight out and both `ut_assembly` and `grid_assembly` return it unchanged — so `.get` on
+    it raises `AttributeError`, and `views_from_defs` always returns at least one element, so the
+    `or {}` never fires. **It raised on EVERY call, on every topic, since wave 20.**
+
+    ⛔ AND THE TWO SITES FAILED DIFFERENTLY, WHICH IS WHY ONLY ONE WAS EVER REPORTED. In
+    `_require_filtered_view` the raise lands ABOVE the handler's own `try`, so it leaves as a bare
+    FastAPI 500 and the client's `errorMessage` turns any 5xx into *"Something went wrong on our
+    side"* — the exact sentence the owner reported (D-107's shape, again: an attribute error above
+    the guard arrives as plain text rather than as our envelope). In `_evaluate` the identical
+    line is swallowed by `/notifications`' `except Exception: continue`, so **every stored
+    view-alert was silently dropped from the Inbox** and nobody had anything to report at all.
+    One expression, one loud symptom and one silent one.
+
+    ⚠ SO IT IS A FUNCTION, NOT TWO FIXED LINES. Two copies of "find the view" is what let one site
+    be discussed for three waves while its twin went unnoticed [[one-question-two-normalizers]].
+
+    ⚠ It accepts a dict too, and that is not defensive noise: `verify_alerts`' door fixture was
+    keyed `{id: view}` — which is precisely why the gate was green while production raised on
+    every call. The fixture is moving to the production shape in this same change, and tolerating
+    both here means a caller that legitimately holds one cannot resurrect the bug.
+    """
+    want = str(view_id or "")
+    if not want:
+        return None
+    views = (g or {}).get("views")
+    if isinstance(views, dict):
+        found = views.get(want)
+        return found if isinstance(found, dict) else None
+    if not isinstance(views, list):
+        return None
+    for v in views:
+        if isinstance(v, dict) and str(v.get("id") or "") == want:
+            return v
+    return None
+
+
+def _topic_or_400(raw):
+    topic = str(raw or "").strip().lower()
+    if topic.startswith("ut_") or topic in _TOPICS:
+        return topic
+    raise err(400, "bad_topic", f"topic must be one of {', '.join(_TOPICS)} or a ut_ table")
+
+
+def _owner_session(session: Session, owner: str):
+    """A `Session` for the alert's OWNER (see the module note on why the owner, not the caller).
+
+    ⚠ `Session` exposes `uname`/`admin` as PROPERTIES derived from `user`, not as fields — so an
+    owner session is built by swapping the `user` RECORD and letting both derive themselves. An
+    earlier version passed `uname=`/`admin=` to the constructor, which would have raised on the
+    first write hook of the wave; the properties are the single definition of who a session is,
+    and going around them is how a session with an admin flag and a non-admin record exists.
+
+    Returns None when the owner is gone or deactivated — their alerts then stop evaluating rather
+    than evaluating as somebody else, which is the fail-closed direction.
+    """
+    import core.users as users
+
+    if str(owner) == str(session.uname):
+        return session
+    rec = (users.registry() or {}).get(str(owner))
+    if not isinstance(rec, dict) or not rec.get("active", True):
+        return None
+    # `_public` is THE definition of what a session may know about its own account (never a hash
+    # or a salt) — the same one `routes_auth` uses. Building the dict by hand here would be a
+    # second definition, and the one that leaks is always the copy.
+    return Session(tenant=session.tenant, user=users._public(str(owner), rec),
+                   claims=session.claims, runtime=session.runtime)
+
+
+def _evaluate(session: Session, rec: dict, assemblies=None):
+    """Resolve `rec`'s view over its topic AS THE ALERT'S OWNER, then fold the result in.
+
+    ⭐⭐ W31-T24 — `assemblies` IS A PER-REQUEST MEMO, KEYED `(topic, owner)`, and it is the whole
+    of this ticket's server half. `/notifications` re-evaluates EVERY alert inline on read and each
+    one built a FULL assembly — the pool, the workspace, `rows_from_pool` over every row. Two
+    alerts on one view built that table twice; ten built it ten times. Nothing dedupes them,
+    because each `_evaluate` was a closed call.
+    ⚠ `(topic, owner)` and not `topic`: the assembly is built as the alert's OWNER (see the module
+    note — evaluating a BU-scoped user's alert on a full-access admin's pool is a permission leak
+    wearing a notification's clothes), so two owners on one topic are two DIFFERENT tables and
+    must never share an entry. Getting that key wrong is the one way this optimisation could leak.
+    ⚠ Passing nothing keeps the old behaviour exactly, which is what the create/run doors want:
+    they evaluate ONE alert and a memo for a single call is pure overhead.
+    """
+    import aios_grid
+    from harness import filter_eval
+
+    owner_sess = _owner_session(session, rec.get("owner"))
+    if owner_sess is None:
+        return {"skipped": "owner_unavailable"}
+    topic = str(rec.get("topic") or "")
+    memo_key = (topic, str(owner_sess.uname))
+    g = assemblies.get(memo_key) if isinstance(assemblies, dict) else None
+    if g is None:
+        try:
+            if topic.startswith("ut_"):
+                from routes_tables import ut_assembly
+                # ⛔ `consume_corrections=False`, and the default was a REAL BUG, not a tidy-up.
+                # `ut_assembly` defaults it True, so every `/notifications` read CONSUMED the
+                # one-shot field-name correction acks for every `ut_` topic that has an alert —
+                # taking them from the `/workspace` refresh that exists to show them to the person
+                # who made the edit. The customer branch below has always passed False; this one
+                # inherited a default nobody re-read. An inbox poll must never consume a one-shot.
+                g = ut_assembly(owner_sess, topic,
+                                storage_key=f"{owner_sess.tenant}:{topic}:{owner_sess.uname}",
+                                consume_corrections=False)
+            else:
+                from routes_customers import grid_assembly
+                g = grid_assembly(owner_sess, scope=topic, consume_corrections=False)
+        except Exception as e:                              # noqa: BLE001
+            # ⭐ W32-T22 — SKIPPING IS FINE HERE; SKIPPING ANONYMOUSLY IS NOT. This one must not
+            # raise (one bad alert cannot empty an inbox), so unlike `_require_filtered_view` it
+            # keeps a blanket catch — but it now reports the refusal's OWN code where there is
+            # one. `type(e).__name__` said `HTTPException` for four different causes, and
+            # `lastError` is the only place a user ever learns why an alert stopped firing.
+            #
+            # ⚠ `with_rows=True` STAYS on this path, deliberately: unlike the create door, an
+            # evaluation genuinely needs the rows to run the filter over. So an alert on a
+            # read-through grid is created (T22) and then skips at evaluation with
+            # `window_required` naming why — which is D-184's remaining half, and it is a
+            # SENTENCE now rather than silence.
+            return {"skipped": _refusal_code(e) or "unavailable", "detail": type(e).__name__}
+        if isinstance(assemblies, dict):
+            assemblies[memo_key] = g
+
+    view = _view_by_id(g, rec.get("viewId"))
+    if not isinstance(view, dict):
+        # Deleted, or un-shared out from under the alert. Say so on the RECORD rather than
+        # deleting the alert: an alert that silently vanishes is indistinguishable from one that
+        # never fires, and the user cannot debug what is not there.
+        return {"skipped": "view_missing"}
+
+    # The SAME row build the grid and `/customers` use — `rows_from_pool` is what puts derived
+    # and overlay values on a row. Evaluating a filter against raw pool dicts would silently
+    # never match any condition on a user-created or measure column.
+    #
+    # ⛔⛔ AND "THE SAME ROW BUILD" WAS NOT TRUE, WHICH MADE EVERY ALERT ON A `ut_*` DATABASE BLIND
+    # TO IMPORTED DATA. Found by a verifier driving one real assembly through both paths.
+    #
+    # `routes_tables.table_rows` — the grid the person is looking at — merges the DEFINITION rows
+    # underneath the overlay ("base first, overlay wins"; that merge is itself the fix for owner
+    # item 3, *"it all got reseted"*). `_evaluate` is a second copy of that read and never got it:
+    # it handed `ws['overlays']` to `rows_from_pool` raw, so for a `ut_*` table every base cell
+    # evaluated as BLANK. Measured on one assembly, same view, same rows:
+    #     rows_src        state='unpaid' / 'paid'
+    #     _evaluate saw   state=''       / ''          ⇐ every base cell blank
+    #     the GRID saw    state='unpaid' / 'paid'
+    # so `state eq unpaid` matched NOTHING while the view showed one row, and `state isEmpty`
+    # matched EVERYTHING while the view showed none. **The alert did not merely miss rows — it
+    # inverted.** End to end: a row whose value arrived by import, automation, paste or the create
+    # door never fired; only a value typed as a hand EDIT did.
+    #
+    # ⚠ Scope, so nobody widens the fix past its cause: materialised `ut_*` tables are hit;
+    # `customer`/`product` are not (their fields are `source: "odoo"` and read off `rows_src`);
+    # `ut_odoo_*` never reaches here (`with_rows=True` refuses first and returns
+    # `skipped: window_required`).
+    # ⛔ ORDER IS LOAD-BEARING AND IS THE GRID'S: base underneath, overlay ON TOP. Inverting it
+    # would let a stale definition value shadow an edit the user has just made — the same defect
+    # `table_rows`' own note records, arriving from the other side.
+    _ov = (g.get("ws") or {}).get("overlays") or {}
+    _merged = {}
+    for _r in g["rows_src"]:
+        _pid = str(_r.get("pid"))
+        _cells = {k: v for k, v in _r.items() if k != "pid"}
+        _o = _ov.get(_pid)
+        if isinstance(_o, dict):
+            _cells.update(_o)
+        _merged[_pid] = _cells
+    rows = aios_grid.rows_from_pool(g["rows_src"], g["fields"], _merged,
+                                    derived=g.get("derived"))
+    config = view.get("config") or view
+    ctx = filter_eval.EvalCtx(
+        cohort_sets={str(k): {str(p) for p in (v.get("memberPids") or ())}
+                     for k, v in (g.get("lists") or {}).items() if isinstance(v, dict)},
+        measure_sets=g.get("measure_sets") or {},
+        today=g.get("today"))
+    pids = filter_eval.visible_pids(config.get("filters") or [], rows, g["fields"], ctx,
+                                    member_pids=config.get("memberPids"))
+    labels = {str(r.get("pid")): str(r.get("name") or r.get("pid")) for r in rows}
+    return alerts.evaluate(rec.get("id"), [str(p) for p in pids],
+                           labels=labels, partial=False, st=session.runtime)
+
+
+@router.get("/alerts")
+def list_alerts(session: Session = Depends(require_session)):
+    return {"alerts": alerts.list_alerts(user=session.uname, is_admin=session.admin,
+                                         st=session.runtime)}
+
+
+@router.post("/alerts")
+def create_alert(body: dict = Body(default=None), session: Session = Depends(require_session)):
+    body = body or {}
+    view_id = str(body.get("viewId") or "").strip()
+    if not view_id:
+        raise err(400, "bad_view", "an alert needs the id of the view it watches")
+    topic = _topic_or_400(body.get("topic"))
+    _require_filtered_view(session, topic, view_id)
+    import uuid
+    aid = f"al_{uuid.uuid4().hex[:12]}"
+    rec = alerts.create(aid, view_id=view_id, topic=topic, owner=session.uname,
+                        label=body.get("label") or "", st=session.runtime)
+    # SEED IMMEDIATELY, so the alert starts from "everything currently matching is old news".
+    # Deferring this to the first write hook would mean the next edit announces the whole view.
+    outcome = _evaluate(session, rec)
+    return {"alert": {**rec, "seeded": True}, "first": outcome}
+
+
+def _require_filtered_view(session: Session, topic: str, view_id: str):
+    """400 unless `view_id` exists on `topic` AND actually narrows something.
+
+    ⛔ AN ALERT ON AN UNFILTERED VIEW IS SILENTLY INCAPABLE OF ALERTING, which is worse than one
+    that is refused. `filter_eval` treats an inactive tree as "no narrowing, every row shows"
+    (`visible_pids`'s own rule), so such an alert seeds with the entire table and can never see an
+    entrant again — there is nothing left to enter. The owner's words are *"when a Record gets
+    into that Filter's criteria"*: no criteria, no alert, and said at creation rather than
+    discovered by never being notified.
+
+    `is_rule_active` is the SAME activeness predicate the engine and the column tints use — a
+    half-typed rule is not a filter, and this must agree with what actually narrows or it would
+    accept a view whose one rule the engine then ignores.
+
+    ⭐⭐ WAVE 32 · T22 (owner item 17) — THIS FUNCTION WAS THE ERROR. Two defects, stacked, and
+    the second one hid the first.
+
+    (1) **IT ASKED FOR EVERY ROW OF A TABLE IT NEVER LOOKS AT.** The only thing read below is
+        `g["views"]`. `ut_assembly` defaults `with_rows=True`, so creating an alert on a
+        read-through grid built the whole pool — and `scoped_pool` refuses that with
+        `409 window_required` over 963,783 rows, exactly as it is supposed to. `with_rows=False`
+        (W31-T20's flag, built for precisely this) answers the same question with `scoped_pids`,
+        runs the SAME `_defn_or_refuse` wall, and does not refuse. **That is D-184's create half,
+        closed** — an alert on a read-through grid can now be made at all.
+    (2) **A BLANKET `except Exception` TURNED EVERY NAMED REFUSAL INTO A 503.** `HTTPException`
+        is an `Exception`, so `404 unknown_table`, `403 forbidden`, `409 window_required` and
+        `503 store_not_ready` — four refusals that each say what is wrong — were all replaced by
+        *"the table is unavailable — try again in a moment"*. ⛔ AND THAT SENTENCE NEVER REACHED
+        A USER EITHER: `alertsApi.errorMessage` discards the text of any status ≥ 500 by design
+        (a 5xx body is the server's internals), substituting *"Something went wrong on our
+        side."* — which is the owner's screenshot, word for word. A knowable cause returned as a
+        5xx is invisible by construction, so re-wording the 503 could never have fixed this.
+    ⚠ The except is narrowed, not deleted: an UNEXPECTED failure is still a 503, because that is
+    honest. What it may no longer do is catch a refusal that already knows its own name.
+    """
+    from fastapi import HTTPException
+
+    from harness import filter_eval
+
+    try:
+        if topic.startswith("ut_"):
+            from routes_tables import ut_assembly
+            # ⚠ `consume_corrections=False` — the customer branch has always passed it and this
+            # one inherited a default nobody re-read. Creating an alert must not eat the one-shot
+            # field-name correction acks belonging to the `/workspace` refresh that exists to show
+            # them to the person who made the edit. Same defect `_evaluate`'s header records.
+            g = ut_assembly(session, topic,
+                            storage_key=f"{session.tenant}:{topic}:{session.uname}",
+                            consume_corrections=False, with_rows=False)
+        else:
+            from routes_customers import grid_assembly
+            g = grid_assembly(session, scope=topic, consume_corrections=False)
+    except HTTPException:
+        raise                                               # it already names its own cause
+    except Exception as e:                                  # noqa: BLE001
+        # Genuinely unexpected. Still a 503, and now it carries the exception TYPE — without it,
+        # the one path that reaches this branch is also the one path with nothing to debug from.
+        raise err(503, "unavailable",
+                  f"the table could not be read ({type(e).__name__}) — try again in a moment")
+    view = _view_by_id(g, view_id)
+    if not isinstance(view, dict):
+        raise err(404, "no_view", "that view does not exist on this table")
+    nodes, _conj = filter_eval.tree_parts((view.get("config") or view).get("filters") or [])
+
+    # ⛔⛔ WAVE 33 · T29 — **CORRECTION: THE BLOCK BELOW IS TRUE ABOUT THE CODE AND FALSE ABOUT
+    # PRODUCTION, AND IT MUST BE READ SECOND.** It claims the missing-argument `TypeError` "IS
+    # owner item 17" — the owner's *"Something went wrong"*. It was not, and it could not have
+    # been: at `cbcf005`, the build the owner was using, the dict-read on `views` sat ~10 lines
+    # ABOVE this call and raised `AttributeError` on EVERY request, so the walk never reached the
+    # leaf and the arity bug was unreachable. `_view_by_id`'s own header records that fix.
+    #
+    # ⚠ WHY THE STALE PARAGRAPH STAYS RATHER THAN GETTING DELETED: the arity bug was real, the
+    # fix was right, and the three reasons it hid are the most transferable thing in this file.
+    # What was wrong is only its CLAIM TO BE THE CAUSE. Two comment blocks in one function each
+    # naming themselves as the origin of the same screenshot are mutually exclusive, and the next
+    # reader believes whichever they meet first — which is why this correction sits above rather
+    # than below. Caught by a verifier that read the SHIPPED file at the deployed commit instead
+    # of the working tree. [[grep-output-is-not-source]]
+    #
+    # ⛔⛔ WAVE 32 · T22 — **THE CALL BELOW WAS MISSING AN ARGUMENT** (and wave 32 believed, wrongly,
+    # that this was owner item 17 — see the correction directly above).
+    #
+    # `is_rule_active(rule, columns)` takes TWO parameters (`harness/filter_sql.py`; every other
+    # caller in the repo passes both). This one passed ONE, so the moment the walk reached a LEAF
+    # rule it raised `TypeError: is_rule_active() missing 1 required positional argument`.
+    #
+    # ⚠ READ WHAT THAT MEANS BEFORE FIXING ANYTHING ELSE: the walk only reaches a leaf when the
+    # view HAS a condition — and a view with a condition is the only kind an alert is allowed on.
+    # A view with no filters yields an empty `nodes`, so `_any_active` returns False without ever
+    # calling this, and the reader gets the honest 400 `no_filter`. **So the only path that
+    # worked was the refusal path: "Alert me about new records" had never once created an alert
+    # on a filtered view.** ⛔ And the raise lands OUTSIDE the `try` above, so it was not even the
+    # 503 — it was a bare FastAPI 500, which `alertsApi.errorMessage` renders as *"Something went
+    # wrong on our side. Try again in a moment."*, the owner's screenshot word for word.
+    #
+    # ⚠ THREE THINGS HID IT, and they are worth more than the fix. (1) Python does not check
+    # arity until the line RUNS, and this line runs only on the success path of a feature whose
+    # every test exercised its refusals. (2) The `no_filter` 400 above it is a real, correct,
+    # well-tested refusal, so the door looked alive. (3) `verify_alerts.py` asserts the refusal
+    # (`no_filter` reaches the user) and the transport — never a creation. A gate can be green,
+    # thorough and honest about everything except the one path the feature exists for.
+    #
+    # `_columns_map` is the DEFINITION of fields -> the membership set `is_rule_active` looks a
+    # column up in; building a second dict here would be a second answer to one question, which
+    # is this wave's other headline defect in a different file. Its leading underscore is a real
+    # smell and is BOOKED (PENDING, mailbox/C.md) rather than worked around.
+    columns = filter_eval._columns_map(g.get("fields") or [])
+
+    def _any_active(ns):
+        for n in ns or ():
+            if isinstance(n, dict) and isinstance(n.get("children"), list):
+                if _any_active(n["children"]):
+                    return True
+            elif filter_eval.is_rule_active(n, columns):
+                return True
+        return False
+
+    if not _any_active(nodes):
+        raise err(400, "no_filter",
+                  "this view has no active filter, so no record can ever ENTER it — add a "
+                  "condition to the view first, then create the alert")
+
+
+@router.delete("/alerts/{alert_id}")
+def delete_alert(alert_id: str, session: Session = Depends(require_session)):
+    rec = next((r for r in alerts.list_alerts(st=session.runtime)
+                if str(r.get("id")) == str(alert_id)), None)
+    if rec is None:
+        raise err(404, "no_alert", "that alert does not exist")
+    if str(rec.get("owner")) != str(session.uname) and not session.admin:
+        raise err(403, "not_yours", "only the alert's owner (or an administrator) can delete it")
+    alerts.delete(alert_id, st=session.runtime)
+    return {"ok": True}
+
+
+@router.post("/alerts/{alert_id}/run")
+def run_alert(alert_id: str, session: Session = Depends(require_session)):
+    rec = next((r for r in alerts.list_alerts(user=session.uname, is_admin=session.admin,
+                                              st=session.runtime)
+                if str(r.get("id")) == str(alert_id)), None)
+    if rec is None:
+        raise err(404, "no_alert", "that alert does not exist")
+    return _evaluate(session, rec)
+
+
+@router.get("/notifications")
+def notifications(session: Session = Depends(require_session)):
+    """The inbox — RE-EVALUATED on read, which is a deliberate design choice.
+
+    ⭐ A-S1-2 RESOLVED THE OTHER WAY, and the reason is structural rather than a shortcut. The
+    plan was a push hook: the automation engine calls `after_write` when it lands rows. But
+    `run_async` runs on a BACKGROUND THREAD with no `Session` in scope, and an alert must be
+    evaluated as its OWNER (see `_evaluate`) — so a push hook would have to mint a session inside
+    a worker thread from a tenant runtime, which is exactly the kind of ad-hoc identity
+    construction that leaks scope.
+
+    Pulling on read has none of that: the caller IS a session, the assemblies are already
+    scope-cached, and the user cannot observe the difference — an inbox is only ever read by
+    someone opening it. The cost is that a notification is minted when you LOOK rather than when
+    the row landed, so the `at` stamp is detection time, not arrival time.
+
+    `after_write` stays exported for the day the engine can hand over a real identity.
+
+    ⭐⭐ W31-T24 — ONE ASSEMBLY PER (TOPIC, OWNER), NOT ONE PER ALERT.
+    ⛔ MEASURED FIRST, AND THE MEASUREMENT CORRECTS AN EARLIER READING OF IT. This route is
+    **20 ms in-process and 3,280 ms live** on tenant #0 — but tenant #0 has **ZERO alerts**
+    (censused 2026-08-12), so the 20 ms is an EMPTY LOOP and says nothing at all about what the
+    re-evaluation costs. The live 3,280 ms is the two store reads either side of that loop. So the
+    body below is not slow today; it is UNEXERCISED, and every alert a tenant creates adds a whole
+    grid assembly to an inbox poll. The memo turns O(alerts) into O(distinct topic × owner), which
+    is the difference between "fine" and "three seconds per alert" the day somebody uses the
+    feature. ⚠ Making the read cheap by evaluating LESS is the obvious wrong fix and is not what
+    this does: every alert is still evaluated, against the same rows, in the same order.
+    """
+    assemblies = {}
+    for rec in alerts.list_alerts(user=session.uname, is_admin=False, st=session.runtime):
+        try:
+            _evaluate(session, rec, assemblies=assemblies)
+        except Exception:                                   # noqa: BLE001
+            continue                                        # one bad alert must not empty the pane
+    # ⭐ W32-T20 (C3): every item leaves through `inbox_view`, so a notification queued before
+    # this wave carries a `target` too. See `notification_view`'s header for why it is derived.
+    return inbox_view(alerts.inbox(session.uname, st=session.runtime))
+
+
+@router.post("/notifications/read")
+def read_notifications(body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    body = body or {}
+    ids = body.get("ids")
+    if ids is not None and not isinstance(ids, list):
+        raise err(400, "bad_ids", "ids must be a list, or null to mark every notification")
+    # ⚠ THE SAME ENRICHMENT ON BOTH DOORS. `mark_read` returns a fresh inbox, and the Inbox
+    # module re-renders from it — an un-enriched answer here would strip `target` off every row
+    # the moment somebody marked one read, i.e. the feature would work until first use.
+    return inbox_view(alerts.mark_read(session.uname, ids, read=bool(body.get("read", True)),
+                                       st=session.runtime))
+
+
+def after_write(session: Session, topic_key: str):
+    """THE WRITE HOOK — call after a write that could change what a view matches.
+
+    Exported as a plain function (not a route) so `core.grid_events`' callers and S2's automation
+    upserts reach it the same way. It never raises: an alert evaluation failing must not fail the
+    edit that triggered it.
+
+    ⭐ W31-T24 — it shares `/notifications`' memo shape for the same reason: a write that changes
+    one view can trip several alerts on the SAME topic, and each would otherwise rebuild the table.
+    ⚠ STILL ZERO PRODUCTION CALLERS (W31-T24 confirmed it; the route docstring above says why the
+    push hook was resolved the other way). Booked rather than wired: minting a session inside the
+    engine's worker thread is the ad-hoc identity construction this file exists to avoid.
+    """
+    try:
+        assemblies = {}
+        return alerts.after_write(topic_key, st=session.runtime,
+                                  runner=lambda rec: _evaluate(session, rec,
+                                                               assemblies=assemblies))
+    except Exception:                                       # noqa: BLE001
+        return {"evaluated": 0}

api/routes_automation.py

@@ -14,6 +14,7 @@ trigger becomes a public one — the same class of mistake as an empty-200 permi
 import os
 import re
 import time
+from datetime import datetime, timezone
 
 from fastapi import APIRouter, Body, Depends, Header, Request
 
@@ -53,7 +54,7 @@ MODULE = "automation"
 _GATE = module_gate(MODULE)
 
 
-def _wire(defn, tenant):
+def _wire(defn, tenant, rt=None):
     """One automation, as the client reads it. `running` is PROCESS state, never store state —
     see the engine header on why a persisted 'running' is a permanent lock."""
     live = engine.running(tenant, defn.get("id"))
@@ -141,6 +142,16 @@ def _wire(defn, tenant):
         # back. What needs the target database's schema (an enrich binding resolved by the profile
         # FLAG) stays a run-time refusal — see `ACTION_REQUIRED`'s note.
         "unconfigured": engine.unconfigured_actions(defn),
+        # ⭐⭐ WAVE 36 · W36-T38 (owner item 8 / R9) — WHICH ACTIONS AN AGENT BUILT.
+        # `{action_id: {agent, agentName, created, by}}`, empty for an ordinary automation.
+        # ⛔ THE CONFIG IS NOT HIDDEN AND MUST NOT BE. R9 is a WRITE rule: the client uses this to
+        # draw a lock and explain who owns the step, never to withhold what the step does — an
+        # automation nobody can audit is worse than one nobody can edit.
+        # ⚠ `rt=None` YIELDS `{}` RATHER THAN OMITTING THE KEY, so a caller that forgets the
+        # runtime produces "nothing is agent-owned" (a visible, wrong-but-safe answer) instead of
+        # an absent prop the client silently reads as undefined
+        # [[flag-shipped-without-its-writer]].
+        "agentActions": (_agent_marks(rt).get(str(defn.get("id") or "")) or {}) if rt else {},
     }
 
 
@@ -243,7 +254,7 @@ def _field_agent_rows(session):
             # — the exact way `awaitingResults` shipped inert for a whole wave. Passing the
             # synthetic DEFINITION through the same function makes them identical by
             # construction; only `system` is stamped afterwards, because no stored row has it.
-            row = _wire(defn_syn, session.tenant)
+            row = _wire(defn_syn, session.tenant, rt=session.runtime)
             row["system"] = SYSTEM_FIELD_AGENT
             out.append(row)
     return out
@@ -334,7 +345,7 @@ def _odoo_sync_row(session, detail=False):
                               "config": {"connector": "odoo", "every": every,
                                          "frozen": frozen}}]},
     }
-    row = _wire(defn, session.tenant)
+    row = _wire(defn, session.tenant, rt=session.runtime)
     row["system"] = SYSTEM_ODOO_SYNC
     # ⛔ THE SENTENCE IS OVERRIDDEN, AND IT IS A FIX RATHER THAN A PREFERENCE. `compose_sentence`
     # speaks the automation vocabulary — it builds "When <cron phrase>, run N actions" out of
@@ -745,7 +756,7 @@ def list_automations(session: Session = Depends(_GATE)):
             pass
         _STATEMENTS_SEEDED.add(session.tenant)
     defs = engine.all_definitions(session.runtime)
-    items = [_wire(d, session.tenant) for _, d in
+    items = [_wire(d, session.tenant, rt=session.runtime) for _, d in
              sorted(defs.items(), key=lambda kv: (kv[1].get("name") or "").lower())]
     # ⭐⭐ WAVE 34 · CONTRACT C3 (W34-T48) — field agents join the list as SYNTHETIC rows.
     # ⚠ MERGED AND RE-SORTED, not appended in a block at the end. R13 asks for a field agent to be
@@ -1133,6 +1144,17 @@ def draft_automation(body: dict = Body(default=None), session: Session = Depends
     prompt = str((body or {}).get("prompt") or "").strip()
     if not prompt:
         raise err(400, "no_prompt", "type what you want the automation to do")
+    # ⭐⭐ ASK D-18 (2026-08-18) — THE KEY THE CLIENT SENDS IS NOW READ. This door took `prompt` off
+    # the body and nothing else, so the Agent chat's model toggle (W36-T34) was a control that
+    # configured nothing: the value was accepted and dropped, which is the shape three tickets in
+    # this wave already tripped over. D held T34 rather than mark a picker BUILT while its value
+    # stopped at the browser, and was right to.
+    # ⚠ UNKNOWN OR UNCONFIGURED FALLS BACK TO THE LADDER, never refuses (D-18's asked-for posture,
+    # and C5's everywhere else): a model the ladder stops offering must not turn every later draft
+    # into an error. The response already names the rung that ANSWERED, which is the honest half.
+    _model = str((body or {}).get("model") or "").strip().lower()
+    if _model in ("", "auto"):
+        _model = None
     # ⚠ THE TENANT'S OWN TABLES, THROUGH THE EXISTING WALL. `automation_tables` applies `may_open`
     # per table, so the model is shown exactly the databases this caller may already see and cannot
     # name one they were not granted — the permission wall re-used, never a second one built beside
@@ -1170,6 +1192,7 @@ def draft_automation(body: dict = Body(default=None), session: Session = Depends
         # sites, this one has a real person behind it: somebody typed the sentence, so `user` is
         # the caller rather than the automation's owner.
         st=session.runtime, user=getattr(session, "uname", "") or "",
+        model=_model,
         chat=_DRAFT_CHAT[0])
     if refusal or not draft:
         raise err(400, "draft_refused", refusal or "no automation could be drafted from that")
@@ -1263,6 +1286,244 @@ def draft_automation(body: dict = Body(default=None), session: Session = Depends
             "provider": provider, "dropped": dropped, "notes": _notes, "saved": False}
 
 
+# ══════════════════ WAVE 36 · W36-T38 (owner item 8, ruling R9) — AGENT-AUTHORED ACTIONS ══════
+#
+# Owner, verbatim (2026-08-18): *"Create the ability for an automation agent to create any
+# 'Action' under the Canvas, so its configuration can only be touched by the agent. Be it a tool a
+# script etc. We need to really guardrail the reach of this script."*
+#
+# ⭐⭐ R9 IS A **WRITE** RULE, NOT A VISIBILITY RULE, and the ticket says so in as many words: the
+# user MAY read an agent-authored action's configuration and MAY delete it; what they may not do
+# is hand-edit it. Hiding a config from the person whose workspace it runs in is a different
+# product, and a worse one — nobody can audit what they cannot see.
+#
+# ⛔ AND IT IS ENFORCED AT THE DOOR, NEVER IN A `disabled` ATTRIBUTE. `routes_automation` already
+# carries that lesson for a different control; a client-side lock is a suggestion, and the whole
+# point of R9 is that the agent's configuration stays coherent with what the agent believes it
+# built.
+#
+# ⚠ WHY THE MARK IS A SEPARATE BUCKET RATHER THAN A KEY ON THE ACTION. `clean_actions` builds every
+# action KEY BY KEY from an allowlist and drops anything it does not recognise (D-75) — so a
+# marker stored inside the action would be silently erased on the next save, and the wall would
+# quietly stop existing with every gate still green. This is an ANNOTATION layer keyed by
+# `(automation id, action id)`; the configuration itself stays where it always was, in the
+# automation, with exactly one writer.
+AGENT_ACTIONS_KEY = "automation_agent_actions"
+
+#: Ids this door mints. ⚠ It must match `clean_actions`' `act_[a-z0-9_]{1,32}` or the engine
+#: re-mints it and the annotation points at an action that no longer carries that id.
+_AGENT_ACTION_PREFIX = "act_ag"
+
+
+def _agent_marks(rt):
+    """`{auto_id: {action_id: mark}}` for one tenant. `{}` on any failure — an unreadable
+    annotation must degrade to "nothing is agent-owned", never to a 500 on the automations rail.
+
+    ⛔ AND "DEGRADE TO NOTHING IS OWNED" IS THE SAFE DIRECTION HERE, which is worth stating because
+    it usually is not. The wall this feeds protects the AGENT's coherence, not the tenant's data: a
+    lost mark lets a person edit a config they own anyway, in their own workspace, on a step they
+    could always have deleted outright. A wall that failed CLOSED would instead make an automation
+    permanently unsavable because one annotation read timed out.
+    """
+    try:
+        found = rt.get(AGENT_ACTIONS_KEY) or {}
+    except Exception:                                                        # noqa: BLE001
+        return {}
+    return found if isinstance(found, dict) else {}
+
+
+def _flat_actions(actions, out=None, depth=0):
+    """Every action in a flow, INCLUDING the ones nested inside a group's arms.
+
+    ⚠ NESTED ACTIONS ARE THE ONES THIS MUST NOT MISS. `unconfigured_actions` walks them for the
+    same reason: a step inside an If/then branch is exactly the one a person cannot see, and a
+    wall that only looked at the top level would leave the agent's own nested step editable.
+    """
+    out = [] if out is None else out
+    if depth > 6 or not isinstance(actions, list):
+        return out
+    for action in actions:
+        if not isinstance(action, dict):
+            continue
+        out.append(action)
+        for key in ("then", "else", "actions"):
+            _flat_actions(action.get(key), out, depth + 1)
+    return out
+
+
+def _flow_actions(defn):
+    return _flat_actions(((defn or {}).get("flow") or {}).get("actions") or [])
+
+
+def _same_action(left, right, rt):
+    """Do these two actions carry the SAME kind and configuration?
+
+    ⛔ COMPARED AFTER `clean_actions`, ON BOTH SIDES, and that is the difference between a wall and
+    a nuisance. The stored action has already been through the cleaner; a client round-trip has
+    not, so it may carry a key order, a blank string or a dropped condition that means nothing.
+    Comparing raw shapes would refuse an edit that changes nothing, and a wall that fires on a
+    no-op is one an operator learns to route around [[one-question-two-normalizers]].
+    """
+    def _clean(action):
+        cleaned, error = engine.clean_actions([dict(action or {}, id="act_1")], rt=rt)
+        if error or not cleaned:
+            return None
+        one = dict(cleaned[0])
+        one.pop("id", None)
+        return one
+
+    a, b = _clean(left), _clean(right)
+    return a is not None and a == b
+
+
+def _agent_owned_guard(session, auto_id, body):
+    """R9 AT THE DOOR: a user may not change an agent-authored action's kind or configuration.
+
+    Three outcomes, and the middle one is the ruling:
+      * the action is ABSENT from the incoming flow  -> a DELETE, and R9 allows it
+      * the action is present and CHANGED            -> **409**, naming the action and the agent
+      * the action is present and identical          -> nothing happens, so an ordinary save of a
+                                                        flow that merely CONTAINS an agent action
+                                                        is not refused
+    """
+    marks = _agent_marks(session.runtime).get(str(auto_id)) or {}
+    if not isinstance(marks, dict) or not marks:
+        return
+    incoming = (body or {}).get("flow")
+    if not isinstance(incoming, dict) or "actions" not in incoming:
+        return
+    stored = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
+    was = {str(a.get("id") or ""): a for a in _flow_actions(stored)}
+    now = {str(a.get("id") or ""): a
+           for a in _flat_actions(incoming.get("actions") or [])}
+    for action_id, mark in marks.items():
+        action_id = str(action_id)
+        if action_id not in now or action_id not in was:
+            continue                                    # removed, or never stored: not an EDIT
+        if _same_action(was[action_id], now[action_id], session.runtime):
+            continue
+        who = str((mark or {}).get("agentName") or (mark or {}).get("agent") or "an agent")
+        raise err(409, "agent_owned",
+                  f"this step was built by {who} and only {who} can change how it is set up. "
+                  f"You can read it, and you can delete it, but it cannot be edited by hand")
+
+
+def _prune_marks(session, auto_id):
+    """Drop annotations whose action is gone, and the whole entry when the automation is.
+
+    ⚠ CALLED AFTER EVERY WRITE, because the alternative is an annotation bucket that only ever
+    grows: a mark on a deleted action would keep refusing an id nobody can see, and a mark on a
+    deleted automation would sit in the tenant document forever.
+    """
+    auto_id = str(auto_id)
+
+    def _set(cur):
+        cur = dict(cur or {})
+        marks = cur.get(auto_id)
+        if not isinstance(marks, dict):
+            cur.pop(auto_id, None)
+            return cur
+        defn = (engine.all_definitions(session.runtime) or {}).get(auto_id)
+        if defn is None:
+            cur.pop(auto_id, None)
+            return cur
+        alive = {str(a.get("id") or "") for a in _flow_actions(defn)}
+        kept = {k: v for k, v in marks.items() if str(k) in alive}
+        if kept:
+            cur[auto_id] = kept
+        else:
+            cur.pop(auto_id, None)
+        return cur
+
+    session.runtime.update(AGENT_ACTIONS_KEY, _set, flush="sync")
+
+
+@router.post("/automations/{auto_id}/agent-actions")
+def agent_author_action(auto_id: str, body: dict = Body(default=None),
+                        session: Session = Depends(_GATE)):
+    """THE AGENT'S DOOR: add or replace one Action under the Canvas, marked agent-owned (R9).
+
+        {agent: "<agent id>", action: {kind, config, when?, id?}}
+          -> {automation, actionId, agent}
+
+    ⛔ THE ACTION GOES THROUGH `clean_actions` LIKE EVERY OTHER ONE, and that is what "guardrail
+    the reach of this script" means in code: an agent cannot invent a config key, cannot name a
+    kind that is not in the catalog, and cannot reach a kind this tenant is not entitled to. The
+    agent gets a different WALL on editing, never a wider vocabulary.
+
+    ⛔ AND IT CANNOT AUTHOR A KIND THAT IS NOT BUILT. `run_script` is `ready: False` in the
+    catalog, so `clean_actions` refuses it here exactly as it refuses it for a person — see this
+    lane's mailbox for why the script ARM is booked rather than half-built: a per-row script
+    contract and a client card are both missing, and a step that reports success and does nothing
+    is the failure this repo has already paid for.
+
+    ⚠ THE AGENT ID IS CHECKED AGAINST THE TENANT'S OWN AGENTS. A mark naming an agent that does
+    not exist would refuse every future edit with a sentence naming nobody.
+    """
+    import routes_slack                                                      # noqa: PLC0415
+
+    body = body if isinstance(body, dict) else {}
+    agent_id = str(body.get("agent") or "").strip()
+    agent = routes_slack._agents(session.runtime).get(agent_id)
+    if not isinstance(agent, dict):
+        raise err(404, "no_agent", "there is no agent with that id in this workspace")
+    action = body.get("action")
+    if not isinstance(action, dict) or not str(action.get("kind") or "").strip():
+        raise err(400, "no_action", "an action needs a kind")
+
+    defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id))
+    if defn is None:
+        raise err(404, "unknown_automation", "no automation with that id")
+    if str(defn.get("system") or "").strip():
+        raise err(409, "system_agent", engine.system_agent_refusal(str(defn["system"])))
+
+    existing = list(((defn.get("flow") or {}).get("actions") or []))
+    taken = {str(a.get("id") or "") for a in _flat_actions(existing)}
+    action_id = str(action.get("id") or "").strip()
+    if not action_id or action_id not in taken:
+        n = 1
+        while f"{_AGENT_ACTION_PREFIX}{n}" in taken:
+            n += 1
+        action_id = f"{_AGENT_ACTION_PREFIX}{n}"
+    fresh = dict(action, id=action_id)
+
+    # ⚠ VALIDATED BEFORE ANYTHING IS WRITTEN, so a refusal leaves the automation exactly as it was.
+    checked, error = engine.clean_actions([fresh], rt=session.runtime)
+    if error or not checked:
+        raise err(400, "invalid_action", error or "that action could not be built")
+
+    replaced = False
+    for i, one in enumerate(existing):
+        if isinstance(one, dict) and str(one.get("id") or "") == action_id:
+            existing[i], replaced = fresh, True
+            break
+    if not replaced:
+        existing.append(fresh)
+
+    notes = []
+    updated, error = engine.patch(session.runtime, str(auto_id),
+                                  {"flow": {**(defn.get("flow") or {}), "actions": existing}},
+                                  username=session.uname, notes=notes)
+    if error:
+        raise err(400, "invalid_automation", error)
+
+    def _set(cur):
+        cur = dict(cur or {})
+        marks = dict(cur.get(str(auto_id)) or {})
+        marks[action_id] = {"agent": agent_id,
+                            "agentName": str(agent.get("label") or agent.get("channelName")
+                                             or agent_id),
+                            "created": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+                            "by": session.uname}
+        cur[str(auto_id)] = marks
+        return cur
+
+    session.runtime.update(AGENT_ACTIONS_KEY, _set, flush="sync")
+    _prune_marks(session, auto_id)
+    return {"automation": _wire(updated, session.tenant, rt=session.runtime),
+            "actionId": action_id, "agent": agent_id, "notes": notes}
+
+
 @router.get("/automations/{auto_id}")
 def get_automation(auto_id: str, session: Session = Depends(_GATE)):
     """One automation, by id.
@@ -1295,7 +1556,7 @@ def get_automation(auto_id: str, session: Session = Depends(_GATE)):
     defn = engine.all_definitions(session.runtime).get(str(auto_id))
     if defn is None:
         raise err(404, "unknown_automation", "no automation with that id")
-    return {"automation": _wire(defn, session.tenant)}
+    return {"automation": _wire(defn, session.tenant, rt=session.runtime)}
 
 
 @router.post("/automations")
@@ -1317,7 +1578,7 @@ def create_automation(body: dict = Body(default=None), session: Session = Depend
                                 notes=_notes)
     if error:
         raise err(400, "invalid_automation", error)
-    return {"automation": _wire(defn, session.tenant), "notes": _notes}
+    return {"automation": _wire(defn, session.tenant, rt=session.runtime), "notes": _notes}
 
 
 @router.patch("/automations/{auto_id}")
@@ -1339,6 +1600,10 @@ def patch_automation(auto_id: str, body: dict = Body(default=None),
         return _patch_odoo_sync(session, body or {})
     # D-75, same channel as `create` above — an EDIT is where this matters most, because the
     # person has just typed the thing that gets dropped.
+    # ⛔⛔ W36-T38 / R9 — THE AGENT-OWNED WALL, AT THE DOOR, BEFORE ANY WRITE. A `disabled`
+    # attribute in the builder is a suggestion; this is the refusal. It permits a DELETE of the
+    # step and permits an ordinary save of a flow that merely contains one.
+    _agent_owned_guard(session, auto_id, body or {})
     _notes = []
     defn, error = engine.patch(session.runtime, auto_id, body or {}, username=session.uname,
                                notes=_notes)
@@ -1346,7 +1611,10 @@ def patch_automation(auto_id: str, body: dict = Body(default=None),
         raise err(400 if error != "no such automation" else 404,
                   "invalid_automation" if error != "no such automation" else "unknown_automation",
                   error)
-    return {"automation": _wire(defn, session.tenant), "notes": _notes}
+    # An action the user removed takes its annotation with it, or the mark outlives its subject
+    # and refuses an id nobody can see.
+    _prune_marks(session, auto_id)
+    return {"automation": _wire(defn, session.tenant, rt=session.runtime), "notes": _notes}
 
 
 @router.delete("/automations/{auto_id}")
@@ -1384,6 +1652,9 @@ def delete_automation(auto_id: str, session: Session = Depends(_GATE)):
     if _sys:
         raise err(409, "system_agent", engine.system_agent_refusal(_sys))
     engine.remove(session.runtime, auto_id)
+    # R9's other half: the user MAY delete an agent-authored step, and deleting the whole
+    # automation takes its annotations with it rather than stranding them in the document.
+    _prune_marks(session, auto_id)
     return {"deleted": str(auto_id)}
 
 
@@ -1439,7 +1710,7 @@ def toggle_automation_node(auto_id: str, node_id: str, session: Session = Depend
         raise err(404 if error == "no such automation" else 400,
                   "unknown_automation" if error == "no such automation" else "node_not_toggleable",
                   error)
-    return {"automation": _wire(defn, session.tenant)}
+    return {"automation": _wire(defn, session.tenant, rt=session.runtime)}
 
 
 @router.post("/automations/{auto_id}/hook/{token}")

api/routes_grid.py

@@ -1000,3 +1000,84 @@ def grid_events_route(body: dict = Body(default=None),
     # `pool_cache` after an `overlay_patch`, which threw away an expensive Odoo pull to refresh
     # data that was never in it.
     return out
+
+
+# ── CONTRACT C1 (W36-T20): THE REGISTRY TOPICS' ROW READERS ───────────────────────────────────
+# ⭐⭐ R6 — *"EVERY database gets the same permission logic, always."* `core.perm_scope.scoped_table`
+# is the ONE door to any database's rows, and it cannot import a topic's pool builder: `core` never
+# imports up (`platform/ARCHITECTURE.md`) and these pools are built by `modules/` + `aios_grid`
+# behind this layer's per-tenant cache. So the app layer DECLARES its readers, exactly as
+# `routes_odoo_tables` declares connected tables to `user_tables.register_connected`.
+#
+# ⛔ REGISTERED HERE RATHER THAN IN `routes_customers`/`routes_products` because those two files
+# are outside wave 36's lane-C fence. The readers themselves are three lines each and call the
+# SAME `_pool_for` + `derive_pool_scope` pair those routes call, so there is no second pool and no
+# second scope derivation — only a second CALLER of the one that exists.
+#
+# ⚠ AND THE TOPIC ROUTES STILL HAVE THEIR OWN DOOR TODAY. Contract C1 says `apply_row_scope` +
+# `visible_fields` "move behind" `scoped_table`; moving `routes_customers.grid_assembly` and
+# `routes_products.scoped_pool` is booked as a PENDING row (mailbox/C.md, C-1) rather than done
+# here, because neither file is in this fence. What ships now is the arm the wave is load-bearing
+# on — every `ut_*` database, plus E's sandbox — and a topic arm that is REAL rather than stubbed,
+# so `scoped_table`'s topic leg is exercised by the product instead of only by a gate.
+def _topic_rt(st, module):
+    """The tenant runtime a topic pool must be built against, or a REPORTED refusal.
+
+    ⛔ A topic pool is per TENANT (`rt.pool_cache`), so `st=None` cannot be resolved to "the
+    default" without picking a tenant at random — which on this box is tenant #0's PRODUCTION
+    data. Standing rule 1's second sentence: say why, and say what to do instead.
+    """
+    if st is None:
+        import core.perm_scope as perm_scope
+        raise perm_scope.Unresolvable(
+            subject="rows", effect="unreadable",
+            cause=f"'{module}' is a registry topic whose pool is built per tenant and no tenant "
+                  f"runtime was passed",
+            recommendation="pass the session's runtime as `st=`. A topic pool cannot be "
+                           "resolved without knowing which tenant is asking")
+    return st
+
+
+def _customer_rows(table_key, user, st):
+    """`(fields, rows)` for the customer topic — the SAME derivation `_team_agent` uses."""
+    import aios_grid
+    import core.perm_scope as perm_scope
+    from routes_customers import _pool_for
+
+    rt = _topic_rt(st, table_key)
+    team_id, agent = perm_scope.derive_pool_scope(user, table_key)
+    return list(aios_grid.FIELDS), _pool_for(rt, team_id, agent)
+
+
+def _product_rows(table_key, user, st):
+    """`(fields, rows)` for the product topic. `consolidated=` follows the derived scope, so a
+    BU-pinned reader gets that BU's field contract rather than the consolidated one."""
+    import core.perm_scope as perm_scope
+    from routes_products import _pool_for, pd_fields
+
+    rt = _topic_rt(st, table_key)
+    team_id, _agent = perm_scope.derive_pool_scope(user, table_key)
+    return pd_fields(consolidated=team_id is None), _pool_for(rt, team_id)
+
+
+def _register_topic_rows():
+    """Declare both topic readers to C1. Called at import; returns the registered key set.
+
+    ⚠ THE KEYS ARE LITERALS AND THE ROUTE IMPORTS ARE INSIDE THE READERS, on purpose: this runs at
+    module import, and `from routes_products import MODULE` here would pull a sibling router in
+    before its own imports have settled. Every other cross-router reference in this file is lazy
+    for the same reason. The literals are held to their sources by `verify_scopes`, so they cannot
+    drift into naming a topic that does not exist.
+    """
+    import core.perm_scope as perm_scope
+
+    perm_scope.register_rows(_customer_rows, MODULE)
+    return perm_scope.register_rows(_product_rows, _PRODUCT_MODULE)
+
+
+#: ⚠ `_`-prefixed, because three functions in this file already bind the name `PRODUCT_MODULE`
+#: LOCALLY from `routes_products`. A module-level twin of that spelling would read as the same
+#: thing and be a different one — [[constant-two-features-share]] waiting to happen.
+_PRODUCT_MODULE = "product_data"
+
+_C1_ROW_SOURCES = _register_topic_rows()

api/routes_oauth.py

@@ -1,114 +1,114 @@
-"""routes_oauth.py — the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
-
-Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
-shapes and status codes here; every decision that could be wrong lives in the module a gate
-can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
-so the day a second provider lands here is the day nothing in this file changes.
-
-MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
-`main.py`, and `routes_automation` is already included there — so this router rides inside it
-(`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
-alters no path.
-
-⚠ THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
-screen** — it is a top-level navigation the client reaches by `<a href>`, never JSON. The
-callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
-`oauth_connect.safe_next`), so the user lands where they left — connected or not, whatever
-went wrong rides in the query string; a dead-end error page where the app used to be reads as
-"the product broke", not "the connect failed".
-"""
-import os
-
-from fastapi import APIRouter, Depends, Request
-from fastapi.responses import RedirectResponse
-
-import oauth_connect
-from deps import Session, err, require_session
-
-router = APIRouter(prefix="/oauth")
-
-
-def _redirect_uri(request: Request, provider: str) -> str:
-    """The redirect URI this deployment registers at the provider — env-pinned when the
-    container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
-    the request. MUST match a console-registered URI verbatim, so it is computed in exactly
-    one place.
-
-    ⭐ WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
-    the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
-    the request-derived fallback below is effectively dev-only.
-    ⛔ THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
-    this returns is where the provider sends the user BACK, and the session cookie is host-only
-    (`aios_session.py:114-117`, no `domain=`) — so a callback base that disagrees with the host
-    the user actually browsed plants the session on the wrong hostname and they return logged
-    out. Moving the app to a new hostname means moving this value AND re-registering the
-    resulting URI in the provider console; one without the other fails closed.
-    Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
-    base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
-    if not base:
-        base = f"{request.url.scheme}://{request.url.netloc}"
-    return f"{base}/api/v1/oauth/{provider}/callback"
-
-
-@router.get("/status")
-def oauth_status(session: Session = Depends(require_session)):
-    """C5's status shape for the SESSION user, one entry per registry provider:
-    `{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
-    `ready` reads through."""
-    return oauth_connect.status(session.runtime, session.uname)
-
-
-def _offered_or_404(provider: str):
-    """⛔⛔ W32-T14 / OWNER ITEM 12 / R6 — A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
-
-    The owner pasted the failure this replaces: clicking Connect on the Google card answered
-    `503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error — it is that the flow is
-    not offered at all, so the honest status is the one for a URL that does not exist. `404`
-    rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
-    coming back until somebody pays for CASA verification (D-45, ~$540–1,800/yr).
-
-    ⚠ Every door in this router goes through it, START included, because the JSON the owner saw
-    came from the start route and a guard on one leg is a guard on one leg.
-    """
-    if not oauth_connect.offered(provider):
-        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
-
-
-@router.get("/{provider}/start")
-def oauth_start(provider: str, request: Request, next: str = "",
-                session: Session = Depends(require_session)):
-    """302 to the provider's consent screen (A3 — a navigation, never JSON). `?next=` is the
-    RELATIVE path the callback returns the browser to; it rides inside the single-use state,
-    sanitised, so the round trip cannot be steered off-origin."""
-    _offered_or_404(provider)
-    url, problem = oauth_connect.start(provider, session.uname,
-                                       _redirect_uri(request, provider), next_path=next)
-    if problem:
-        raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
-    return RedirectResponse(url, status_code=302)
-
-
-@router.get("/{provider}/callback")
-def oauth_callback(provider: str, request: Request,
-                   session: Session = Depends(require_session),
-                   state: str = "", code: str = "", error: str = ""):
-    """The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
-    the browser back to the state's return path — connected or not (see module header)."""
-    _offered_or_404(provider)
-    if error:
-        home = "/#/"
-        return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
-    email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
-    sep = "&" if "?" in home else "?"
-    if problem:
-        return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
-    return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
-
-
-@router.post("/{provider}/disconnect")
-def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
-    _offered_or_404(provider)
-    if oauth_connect.provider_def(provider) is None:
-        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
-    oauth_connect.disconnect(session.runtime, session.uname, provider)
-    return {"disconnected": provider}
+"""routes_oauth.py — the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
+
+Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
+shapes and status codes here; every decision that could be wrong lives in the module a gate
+can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
+so the day a second provider lands here is the day nothing in this file changes.
+
+MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
+`main.py`, and `routes_automation` is already included there — so this router rides inside it
+(`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
+alters no path.
+
+⚠ THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
+screen** — it is a top-level navigation the client reaches by `<a href>`, never JSON. The
+callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
+`oauth_connect.safe_next`), so the user lands where they left — connected or not, whatever
+went wrong rides in the query string; a dead-end error page where the app used to be reads as
+"the product broke", not "the connect failed".
+"""
+import os
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import RedirectResponse
+
+import oauth_connect
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/oauth")
+
+
+def _redirect_uri(request: Request, provider: str) -> str:
+    """The redirect URI this deployment registers at the provider — env-pinned when the
+    container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
+    the request. MUST match a console-registered URI verbatim, so it is computed in exactly
+    one place.
+
+    ⭐ WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
+    the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
+    the request-derived fallback below is effectively dev-only.
+    ⛔ THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
+    this returns is where the provider sends the user BACK, and the session cookie is host-only
+    (`aios_session.py:114-117`, no `domain=`) — so a callback base that disagrees with the host
+    the user actually browsed plants the session on the wrong hostname and they return logged
+    out. Moving the app to a new hostname means moving this value AND re-registering the
+    resulting URI in the provider console; one without the other fails closed.
+    Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
+    base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
+    if not base:
+        base = f"{request.url.scheme}://{request.url.netloc}"
+    return f"{base}/api/v1/oauth/{provider}/callback"
+
+
+@router.get("/status")
+def oauth_status(session: Session = Depends(require_session)):
+    """C5's status shape for the SESSION user, one entry per registry provider:
+    `{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
+    `ready` reads through."""
+    return oauth_connect.status(session.runtime, session.uname)
+
+
+def _offered_or_404(provider: str):
+    """⛔⛔ W32-T14 / OWNER ITEM 12 / R6 — A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
+
+    The owner pasted the failure this replaces: clicking Connect on the Google card answered
+    `503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error — it is that the flow is
+    not offered at all, so the honest status is the one for a URL that does not exist. `404`
+    rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
+    coming back until somebody pays for CASA verification (D-45, ~$540–1,800/yr).
+
+    ⚠ Every door in this router goes through it, START included, because the JSON the owner saw
+    came from the start route and a guard on one leg is a guard on one leg.
+    """
+    if not oauth_connect.offered(provider):
+        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
+
+
+@router.get("/{provider}/start")
+def oauth_start(provider: str, request: Request, next: str = "",
+                session: Session = Depends(require_session)):
+    """302 to the provider's consent screen (A3 — a navigation, never JSON). `?next=` is the
+    RELATIVE path the callback returns the browser to; it rides inside the single-use state,
+    sanitised, so the round trip cannot be steered off-origin."""
+    _offered_or_404(provider)
+    url, problem = oauth_connect.start(provider, session.uname,
+                                       _redirect_uri(request, provider), next_path=next)
+    if problem:
+        raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
+    return RedirectResponse(url, status_code=302)
+
+
+@router.get("/{provider}/callback")
+def oauth_callback(provider: str, request: Request,
+                   session: Session = Depends(require_session),
+                   state: str = "", code: str = "", error: str = ""):
+    """The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
+    the browser back to the state's return path — connected or not (see module header)."""
+    _offered_or_404(provider)
+    if error:
+        home = "/#/"
+        return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
+    email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
+    sep = "&" if "?" in home else "?"
+    if problem:
+        return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
+    return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
+
+
+@router.post("/{provider}/disconnect")
+def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
+    _offered_or_404(provider)
+    if oauth_connect.provider_def(provider) is None:
+        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
+    oauth_connect.disconnect(session.runtime, session.uname, provider)
+    return {"disconnected": provider}

api/routes_records.py

@@ -1,211 +1,211 @@
-"""Record detail routes: durable comments, scoped to the caller's book — ON EVERY DATABASE.
-
-⭐ WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
-customer-shaped wall bolted to the module import line: `_in_book` asked
-`routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
-typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
-panel answered "that customer is not in your book" — the owner's report. The dangerous half is
-the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
-is filed against somebody's customer where the whole team can read it.
-
-THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
-events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
-per scope — the GRANT and the ROW SET — by asking that topic's own route, never by re-deriving
-one here:
-
-    customer / cohort   `routes_customers.allowed_pids` behind the `customer_data` grant
-    product             `routes_products.scoped_pool` behind the `product_data` grant
-    ut_<slug>           `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
-                        (404 unknown / 403 not yours — a user table has no module grant).
-                        ⭐ W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` — the pool builds every
-                        ROW to derive a pid set this module discards, and RAISES 409 on a
-                        read-through grid past one window, which is why the record drawer painted
-                        an error page on `ut_odoo_gl_lines`.
-
-⚠ THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
-section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
-another session's gate mid-wave — the WALL is the query parameter, not the word.
-
-⚠ NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
-shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
-400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
-the same reason: a typo served as `customer` answers a question nobody asked).
-"""
-from fastapi import APIRouter, Body, Depends, Query
-
-from deps import Session, err, require_session
-
-router = APIRouter(prefix="/api/v1")
-
-#: The customer topic's two names — one book, two surfaces (the Cohort page is the customer table
-#: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
-_CUSTOMER_SCOPES = ("", "customer", "cohort")
-
-
-def _scope_or_400(raw):
-    scope = str(raw or "customer").strip().lower()
-    if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
-        return "customer" if scope in _CUSTOMER_SCOPES else scope
-    raise err(400, "bad_scope",
-              "scope must be customer, cohort, product or a ut_ database — refusing to guess")
-
-
-def _pool_or_refuse(session: Session, scope: str):
-    """The pids this session may attach comments to ON THIS DATABASE — grant wall included.
-
-    Returns **`(pids, unbounded)`** — a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
-    so a caller who may not open the surface never learns anything about the row they asked about.
-
-    ⛔ `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
-    one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
-    `frozenset()` for both — see the branch below.
-    ⚠ THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
-    do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
-    that REPLACES this function with its own lambda. A gate's test double is a caller
-    ([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
-    bare frozenset and the section died on `ValueError: too many values to unpack` — no tally, no
-    failing name. Change the shape here and that double changes with it.
-    """
-    if scope == "product":
-        from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
-
-        session.require(PRODUCT_MODULE)
-        pids, _team, _rows, _fields = scoped_pool(session)
-        # ⚠ `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
-        # after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
-        # a `TypeError` — a 500 on every product comment — while both other branches worked. A
-        # return shape is a contract even when the function is private.
-        return (pids, False)
-    if scope.startswith("ut_"):
-        # No module grant exists for a user table — `_defn_or_refuse` inside `scoped_pids` IS
-        # the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
-        # rows routes do.
-        #
-        # ⭐⭐ W33-T03 / D-183 — `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
-        # `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
-        # a read-through grid larger than one window it RAISES `409 window_required`. So opening the
-        # record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page — for a panel
-        # that renders comments about ONE row it already has. `scoped_pids` answers the identical
-        # question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
-        # W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
-        # used to become openable on those two grids.
-        from routes_tables import scoped_pids
-
-        limits = []
-        pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
-        # ⛔ AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
-        # how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
-        # database with no rows and for a read-through grid too big to enumerate — it distinguishes
-        # them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
-        # from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
-        # is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
-        # ⚠ ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
-        # THE TENANT IS THE UNIT — `scoped_pool` itself carries "no per-row owner filter; the
-        # table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
-        # `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
-        return (pids, bool(limits))
-    from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
-
-    session.require(CUSTOMER_MODULE)
-    return (frozenset(allowed_pids(session)), False)
-
-
-def _in_book(pid, session, scope):
-    pids, unbounded = _pool_or_refuse(session, scope)
-    if unbounded:
-        # The table wall passed and the row set is larger than this process will enumerate. Said
-        # out loud rather than silently admitting: R6's second sentence is that a limit which
-        # cannot be removed gets REPORTED, and this is the one place the report has no envelope to
-        # ride in.
-        print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) — "
-              f"admitting on the table wall alone, per D-72")
-        return
-    if pid not in pids:
-        # 403, not 404: the record may exist, but this session may not inspect it.
-        raise err(403, "out_of_scope", "that record is not in your book")
-
-
-def _unavailable():
-    return err(
-        503,
-        "store_unavailable",
-        "record comments are temporarily unavailable — no change was saved",
-    )
-
-
-# ⭐ WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments — comments hang off a RECORD
-# in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
-# wall was always the query param). The old path stays as an ALIAS because the shipped client
-# still calls it; verify_api pins the canonical path AND that the alias answers, so removing
-# the alias later is a decision, never an accident.
-@router.get("/records/{pid}/comments")
-@router.get("/customers/{pid}/comments")
-def comments(pid: int, scope: str = Query(default="customer"),
-             session: Session = Depends(require_session)):
-    from core import record_comments
-
-    scope = _scope_or_400(scope)
-    _in_book(pid, session, scope)
-    try:
-        rows = record_comments.list_comments(session.runtime, pid, scope=scope)
-    except record_comments.CommentsUnavailable:
-        raise _unavailable()
-    return {"comments": rows}
-
-
-@router.post("/records/{pid}/comments", status_code=201)
-@router.post("/customers/{pid}/comments", status_code=201)
-def create_comment(
-    pid: int,
-    body: dict = Body(default=None),
-    scope: str = Query(default="customer"),
-    session: Session = Depends(require_session),
-):
-    from core import record_comments
-
-    scope = _scope_or_400(scope)
-    _in_book(pid, session, scope)
-    try:
-        comment = record_comments.add_comment(
-            session.runtime,
-            pid,
-            (body or {}).get("body"),
-            session.uname,
-            session.user.get("name") or session.uname,
-            scope=scope,
-        )
-    except ValueError as exc:
-        raise err(400, "bad_comment", str(exc))
-    except record_comments.CommentsUnavailable:
-        raise _unavailable()
-    return {"comment": comment}
-
-
-@router.delete("/records/{pid}/comments/{comment_id}")
-@router.delete("/customers/{pid}/comments/{comment_id}")
-def remove_comment(
-    pid: int,
-    comment_id: str,
-    scope: str = Query(default="customer"),
-    session: Session = Depends(require_session),
-):
-    from core import record_comments
-
-    scope = _scope_or_400(scope)
-    _in_book(pid, session, scope)
-    try:
-        deleted = record_comments.delete_comment(
-            session.runtime,
-            pid,
-            comment_id,
-            session.uname,
-            admin=session.admin,
-            scope=scope,
-        )
-    except record_comments.CommentForbidden:
-        raise err(403, "comment_forbidden", "only the author may delete this comment")
-    except record_comments.CommentsUnavailable:
-        raise _unavailable()
-    if not deleted:
-        raise err(404, "comment_not_found", "that comment no longer exists")
-    return {"ok": True, "id": comment_id}
+"""Record detail routes: durable comments, scoped to the caller's book — ON EVERY DATABASE.
+
+⭐ WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
+customer-shaped wall bolted to the module import line: `_in_book` asked
+`routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
+typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
+panel answered "that customer is not in your book" — the owner's report. The dangerous half is
+the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
+is filed against somebody's customer where the whole team can read it.
+
+THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
+events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
+per scope — the GRANT and the ROW SET — by asking that topic's own route, never by re-deriving
+one here:
+
+    customer / cohort   `routes_customers.allowed_pids` behind the `customer_data` grant
+    product             `routes_products.scoped_pool` behind the `product_data` grant
+    ut_<slug>           `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
+                        (404 unknown / 403 not yours — a user table has no module grant).
+                        ⭐ W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` — the pool builds every
+                        ROW to derive a pid set this module discards, and RAISES 409 on a
+                        read-through grid past one window, which is why the record drawer painted
+                        an error page on `ut_odoo_gl_lines`.
+
+⚠ THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
+section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
+another session's gate mid-wave — the WALL is the query parameter, not the word.
+
+⚠ NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
+shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
+400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
+the same reason: a typo served as `customer` answers a question nobody asked).
+"""
+from fastapi import APIRouter, Body, Depends, Query
+
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+#: The customer topic's two names — one book, two surfaces (the Cohort page is the customer table
+#: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
+_CUSTOMER_SCOPES = ("", "customer", "cohort")
+
+
+def _scope_or_400(raw):
+    scope = str(raw or "customer").strip().lower()
+    if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
+        return "customer" if scope in _CUSTOMER_SCOPES else scope
+    raise err(400, "bad_scope",
+              "scope must be customer, cohort, product or a ut_ database — refusing to guess")
+
+
+def _pool_or_refuse(session: Session, scope: str):
+    """The pids this session may attach comments to ON THIS DATABASE — grant wall included.
+
+    Returns **`(pids, unbounded)`** — a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
+    so a caller who may not open the surface never learns anything about the row they asked about.
+
+    ⛔ `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
+    one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
+    `frozenset()` for both — see the branch below.
+    ⚠ THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
+    do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
+    that REPLACES this function with its own lambda. A gate's test double is a caller
+    ([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
+    bare frozenset and the section died on `ValueError: too many values to unpack` — no tally, no
+    failing name. Change the shape here and that double changes with it.
+    """
+    if scope == "product":
+        from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
+
+        session.require(PRODUCT_MODULE)
+        pids, _team, _rows, _fields = scoped_pool(session)
+        # ⚠ `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
+        # after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
+        # a `TypeError` — a 500 on every product comment — while both other branches worked. A
+        # return shape is a contract even when the function is private.
+        return (pids, False)
+    if scope.startswith("ut_"):
+        # No module grant exists for a user table — `_defn_or_refuse` inside `scoped_pids` IS
+        # the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
+        # rows routes do.
+        #
+        # ⭐⭐ W33-T03 / D-183 — `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
+        # `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
+        # a read-through grid larger than one window it RAISES `409 window_required`. So opening the
+        # record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page — for a panel
+        # that renders comments about ONE row it already has. `scoped_pids` answers the identical
+        # question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
+        # W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
+        # used to become openable on those two grids.
+        from routes_tables import scoped_pids
+
+        limits = []
+        pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
+        # ⛔ AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
+        # how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
+        # database with no rows and for a read-through grid too big to enumerate — it distinguishes
+        # them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
+        # from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
+        # is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
+        # ⚠ ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
+        # THE TENANT IS THE UNIT — `scoped_pool` itself carries "no per-row owner filter; the
+        # table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
+        # `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
+        return (pids, bool(limits))
+    from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
+
+    session.require(CUSTOMER_MODULE)
+    return (frozenset(allowed_pids(session)), False)
+
+
+def _in_book(pid, session, scope):
+    pids, unbounded = _pool_or_refuse(session, scope)
+    if unbounded:
+        # The table wall passed and the row set is larger than this process will enumerate. Said
+        # out loud rather than silently admitting: R6's second sentence is that a limit which
+        # cannot be removed gets REPORTED, and this is the one place the report has no envelope to
+        # ride in.
+        print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) — "
+              f"admitting on the table wall alone, per D-72")
+        return
+    if pid not in pids:
+        # 403, not 404: the record may exist, but this session may not inspect it.
+        raise err(403, "out_of_scope", "that record is not in your book")
+
+
+def _unavailable():
+    return err(
+        503,
+        "store_unavailable",
+        "record comments are temporarily unavailable — no change was saved",
+    )
+
+
+# ⭐ WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments — comments hang off a RECORD
+# in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
+# wall was always the query param). The old path stays as an ALIAS because the shipped client
+# still calls it; verify_api pins the canonical path AND that the alias answers, so removing
+# the alias later is a decision, never an accident.
+@router.get("/records/{pid}/comments")
+@router.get("/customers/{pid}/comments")
+def comments(pid: int, scope: str = Query(default="customer"),
+             session: Session = Depends(require_session)):
+    from core import record_comments
+
+    scope = _scope_or_400(scope)
+    _in_book(pid, session, scope)
+    try:
+        rows = record_comments.list_comments(session.runtime, pid, scope=scope)
+    except record_comments.CommentsUnavailable:
+        raise _unavailable()
+    return {"comments": rows}
+
+
+@router.post("/records/{pid}/comments", status_code=201)
+@router.post("/customers/{pid}/comments", status_code=201)
+def create_comment(
+    pid: int,
+    body: dict = Body(default=None),
+    scope: str = Query(default="customer"),
+    session: Session = Depends(require_session),
+):
+    from core import record_comments
+
+    scope = _scope_or_400(scope)
+    _in_book(pid, session, scope)
+    try:
+        comment = record_comments.add_comment(
+            session.runtime,
+            pid,
+            (body or {}).get("body"),
+            session.uname,
+            session.user.get("name") or session.uname,
+            scope=scope,
+        )
+    except ValueError as exc:
+        raise err(400, "bad_comment", str(exc))
+    except record_comments.CommentsUnavailable:
+        raise _unavailable()
+    return {"comment": comment}
+
+
+@router.delete("/records/{pid}/comments/{comment_id}")
+@router.delete("/customers/{pid}/comments/{comment_id}")
+def remove_comment(
+    pid: int,
+    comment_id: str,
+    scope: str = Query(default="customer"),
+    session: Session = Depends(require_session),
+):
+    from core import record_comments
+
+    scope = _scope_or_400(scope)
+    _in_book(pid, session, scope)
+    try:
+        deleted = record_comments.delete_comment(
+            session.runtime,
+            pid,
+            comment_id,
+            session.uname,
+            admin=session.admin,
+            scope=scope,
+        )
+    except record_comments.CommentForbidden:
+        raise err(403, "comment_forbidden", "only the author may delete this comment")
+    except record_comments.CommentsUnavailable:
+        raise _unavailable()
+    if not deleted:
+        raise err(404, "comment_not_found", "that comment no longer exists")
+    return {"ok": True, "id": comment_id}

api/routes_script_views.py

@@ -0,0 +1,329 @@
+"""routes_script_views.py — CONTRACT C3: a database View that is a PYTHON SCRIPT (R3 / R5 / R10).
+
+Owner item 6, verbatim (2026-08-18): *"Add code script as an interface (database View) so a user
+can build whatever they want through the Agent chat interface. be able to create any dashboard
+they want. User should have the ability to see the code AND the dashboard output of course… Limit
+the code script View per database… Any agent can add into more AI script, so we can see different
+versions or different things the AI code for us."*
+
+    GET    /api/v1/script-views?database=K      the views bound to ONE database
+    POST   /api/v1/script-views                 create one   {database, name?, source}
+    GET    /api/v1/script-views/{id}            one view, its source and its history
+    PUT    /api/v1/script-views/{id}            a NEW VERSION of the source
+    DELETE /api/v1/script-views/{id}            drop it
+    POST   /api/v1/script-views/{id}/run        run it  ->  {ok, spec | error, stdout, ms}
+
+⭐⭐ **R3 IS "SCOPED, NOT CAPPED", AND THE TWO HALVES POINT OPPOSITE WAYS.** *Scoped*: a view may
+read ONLY the database it lives in, and a script that names another database is REFUSED with a
+message naming both. *Not capped*: there is **no limit on how many script views a database may
+carry**, because that is how an agent offers three attempts and the owner picks one. So nothing
+below counts views. What IS bounded is what makes them big — one source is capped, and one view's
+edit history is capped and REPORTS what it dropped.
+
+⛔ **THE RUN IS THE CALLER'S, NEVER THE AUTHOR'S (R5).** `script_sandbox.run_view` is handed
+`session.user`, so a script written by an administrator and opened by a scoped analyst reads the
+ANALYST's rows. The author decides what the code does; the reader decides what it can see.
+⚠ And the reverse case is safe rather than lucky: a narrowly-scoped author cannot write a script
+that exfiltrates anything, because the only thing a script can return is a render spec drawn on
+the screen of the person who ran it. There is no network, no file and no second reader.
+
+⛔ **`run` IS `def`, NOT `async def`.** It waits on a subprocess for up to ten seconds; as a
+coroutine that would block the event loop for every other request in the container. FastAPI runs a
+plain `def` in the threadpool, which is what makes one slow script one slow REQUEST.
+"""
+import threading
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Body, Depends
+
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+#: The tenant's script views: `{id: record}`. Per tenant, so it rides `runtime.store_key`.
+VIEWS_KEY = "script_views"
+
+MAX_NAME = 80
+MAX_SOURCE_BYTES = 128 * 1024
+
+#: Edit history per view. ⚠ NOT a cap on the NUMBER of views (R3 forbids that) — a cap on how far
+#: back ONE view's source is kept. Past this the oldest go and `trimmed` counts them, so a reader
+#: can see the history is partial instead of concluding the view was only ever saved twice.
+MAX_HISTORY = 40
+
+#: ⛔ HOW MANY SCRIPTS MAY BE RUNNING IN THIS CONTAINER AT ONCE, and it is a REPORTED refusal
+#: rather than a queue. Each run is a real subprocess with a ten-second wall clock; without this,
+#: holding down refresh forks until the box gives up, and the tenant's ONE FastAPI process is what
+#: gives up. A 429 that says so is honest; an unbounded fork is not.
+MAX_CONCURRENT_RUNS = 4
+_RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _all(rt):
+    """`{id: record}` for one tenant. `{}` on any failure — an unreadable bucket must degrade to
+    "this database has no script views", never to a 500 on the view rail."""
+    try:
+        found = rt.get(VIEWS_KEY) or {}
+    except Exception:                                                        # noqa: BLE001
+        return {}
+    return found if isinstance(found, dict) else {}
+
+
+def _database_ok(session, database):
+    """Does this database EXIST, and may this caller read it? Answered by C1, never by a list.
+
+    ⛔ `perm_scope.may_read` ALONE IS NOT ENOUGH and the reason is easy to miss: it answers True
+    for an ADMIN on any key at all, including one no database answers to. So a create validated
+    with `may_read` would let an administrator bind a view to a typo and leave an orphan nothing
+    can ever run. `scoped_fields` is the cheap half of C1 (a `ut_*` definition, no rows) and it
+    RAISES `UnknownTable`, which is exactly the question being asked.
+    """
+    import core.perm_scope as perm_scope
+    try:
+        perm_scope.scoped_fields(session.user, database, st=session.runtime)
+    except perm_scope.UnknownTable:
+        raise err(404, "no_database", f"there is no database '{database}' in this workspace")
+    except perm_scope.Denied:
+        raise err(403, "forbidden", f"your account may not read '{database}'")
+    except perm_scope.Unresolvable as exc:
+        # The database is real and cannot be served under this call's constraints. Standing rule
+        # 1's second sentence: report the cause and the recommendation, never a bare refusal.
+        raise err(409, "unresolvable", str(exc)) from None
+
+
+def _clean_source(raw):
+    source = str(raw or "")
+    if not source.strip():
+        raise err(400, "no_source", "a script view needs some code")
+    if len(source.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
+        raise err(413, "source_too_long",
+                  f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of code")
+    return source
+
+
+def _row(rec, *, source=False):
+    """One view as the list door reports it. ⚠ NO SOURCE unless asked: the rail lists names."""
+    out = {"id": rec.get("id") or "", "database": rec.get("database") or "",
+           "name": rec.get("name") or "", "author": rec.get("author") or "",
+           "version": int(rec.get("version") or 1),
+           "created": rec.get("created") or "", "updated": rec.get("updated") or "",
+           "versions": len(rec.get("history") or []) + 1,
+           "trimmed": int(rec.get("trimmed") or 0)}
+    if source:
+        out["source"] = rec.get("source") or ""
+        out["history"] = [{"version": int(h.get("version") or 0), "author": h.get("author") or "",
+                           "created": h.get("created") or "",
+                           "bytes": len(str(h.get("source") or "").encode("utf-8", "replace"))}
+                          for h in reversed(rec.get("history") or []) if isinstance(h, dict)]
+    return out
+
+
+def _limits():
+    return {"maxSourceBytes": MAX_SOURCE_BYTES, "maxName": MAX_NAME,
+            "maxHistory": MAX_HISTORY, "maxConcurrentRuns": MAX_CONCURRENT_RUNS,
+            # ⭐ SAID OUT LOUD, because R3's "not capped" half is the one a reader assumes wrong.
+            "maxViewsPerDatabase": None}
+
+
+def _put(session, view_id, mutate):
+    """Read-modify-write ONE view, synchronously — the client re-reads the rail immediately."""
+    def _set(cur):
+        cur = dict(cur or {})
+        nxt = mutate(cur.get(view_id) if isinstance(cur.get(view_id), dict) else None)
+        if nxt is None:
+            cur.pop(view_id, None)
+        else:
+            cur[view_id] = nxt
+        return cur
+
+    session.runtime.update(VIEWS_KEY, _set, flush="sync")
+
+
+def _mine_or_admin(session, rec):
+    """Who may EDIT or DELETE a view: its author, or an administrator.
+
+    ⚠ RUNNING IS A DIFFERENT QUESTION and deliberately wider — anybody who may read the database
+    may run any view on it, under their OWN scope. That is the whole of "so we can see different
+    versions or different things the AI code for us": a colleague's attempt is worth nothing if
+    only its author can open it.
+    """
+    if session.admin or str(rec.get("author") or "") == session.uname:
+        return
+    raise err(403, "forbidden", "only the author or an administrator can change this script view")
+
+
+# ── the routes ────────────────────────────────────────────────────────────────────────────────
+@router.get("/script-views")
+def list_script_views(database: str = "", session: Session = Depends(require_session)):
+    """Every script view bound to ONE database, newest first. `database` is required."""
+    key = str(database or "").strip()
+    if not key:
+        raise err(400, "no_database", "name the database whose script views you want")
+    _database_ok(session, key)
+    rows = [_row(rec) for rec in _all(session.runtime).values()
+            if isinstance(rec, dict) and str(rec.get("database") or "") == key]
+    rows.sort(key=lambda r: (r["created"], r["id"]), reverse=True)
+    return {"database": key, "views": rows, "limits": _limits()}
+
+
+@router.post("/script-views")
+def create_script_view(body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    """Create one. ⛔ THE SOURCE IS CHECKED BEFORE IT IS STORED, not first at run time.
+
+    A script view that cannot be run is a broken feature the reader discovers by pressing a button,
+    and the agent that wrote it is long gone by then. `check_source` is pure and costs no process,
+    so the refusal arrives while the author still has the code in front of them.
+    """
+    import secrets                                                           # noqa: PLC0415
+    import core.script_sandbox as sandbox                                    # noqa: PLC0415
+
+    body = body if isinstance(body, dict) else {}
+    database = str(body.get("database") or "").strip()
+    if not database:
+        raise err(400, "no_database", "a script view is bound to one database")
+    _database_ok(session, database)
+    source = _clean_source(body.get("source"))
+    refusal = sandbox.check_source(source)
+    if refusal is not None:
+        raise err(400, refusal.code, refusal.message)
+
+    view_id = "sv_" + secrets.token_urlsafe(9)
+    rec = {"id": view_id, "database": database,
+           "name": " ".join(str(body.get("name") or "Script view").split())[:MAX_NAME],
+           "source": source, "author": session.uname, "version": 1,
+           "created": _now(), "updated": _now(), "history": [], "trimmed": 0}
+    _put(session, view_id, lambda _prior: rec)
+    fresh = _all(session.runtime).get(view_id)
+    if not isinstance(fresh, dict):
+        # The store took the write and did not record it. A 200 here would tell the author their
+        # script was saved when it was not.
+        raise err(503, "store_unavailable", "the script view was NOT created")
+    return {"view": _row(fresh, source=True), "limits": _limits()}
+
+
+@router.get("/script-views/{view_id}")
+def get_script_view(view_id: str, session: Session = Depends(require_session)):
+    """One view WITH its source and its edit history. Owner item 6's *"see the code"* half."""
+    rec = _all(session.runtime).get(str(view_id))
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    _database_ok(session, str(rec.get("database") or ""))
+    return {"view": _row(rec, source=True), "limits": _limits()}
+
+
+@router.put("/script-views/{view_id}")
+def update_script_view(view_id: str, body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    """A NEW VERSION of one view's source. The prior source is KEPT, never replaced in place."""
+    import core.script_sandbox as sandbox                                    # noqa: PLC0415
+
+    view_id = str(view_id)
+    rec = _all(session.runtime).get(view_id)
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    _mine_or_admin(session, rec)
+    body = body if isinstance(body, dict) else {}
+    source = _clean_source(body.get("source"))
+    refusal = sandbox.check_source(source)
+    if refusal is not None:
+        raise err(400, refusal.code, refusal.message)
+
+    def _mutate(prior):
+        prior = dict(prior or rec)
+        history = list(prior.get("history") or [])
+        history.append({"version": int(prior.get("version") or 1),
+                        "source": prior.get("source") or "",
+                        "author": prior.get("author") or "", "created": prior.get("updated") or ""})
+        dropped = max(0, len(history) - MAX_HISTORY)
+        prior["history"] = history[dropped:] if dropped else history
+        prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
+        prior["source"] = source
+        prior["version"] = int(prior.get("version") or 1) + 1
+        prior["updated"] = _now()
+        if body.get("name"):
+            prior["name"] = " ".join(str(body["name"]).split())[:MAX_NAME]
+        return prior
+
+    _put(session, view_id, _mutate)
+    fresh = _all(session.runtime).get(view_id)
+    if not isinstance(fresh, dict):
+        raise err(503, "store_unavailable", "the new version was NOT saved")
+    return {"view": _row(fresh, source=True), "limits": _limits()}
+
+
+@router.delete("/script-views/{view_id}")
+def delete_script_view(view_id: str, session: Session = Depends(require_session)):
+    view_id = str(view_id)
+    rec = _all(session.runtime).get(view_id)
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    _mine_or_admin(session, rec)
+    _put(session, view_id, lambda _prior: None)
+    return {"deleted": view_id}
+
+
+@router.post("/script-views/{view_id}/run")
+def run_script_view(view_id: str, body: dict = Body(default=None),
+                    session: Session = Depends(require_session)):
+    """CONTRACT C3's run door: `{ok, spec | error, stdout, ms}`.
+
+    ⛔ `spec` IS A DESCRIPTION THE CLIENT DRAWS. It is never HTML and never text the browser
+    executes — the sandbox refuses a spec carrying an `html`, `script`, `src`, `href` or `on*` key
+    before this function ever sees it, so a renderer cannot be talked into running something by a
+    script that was itself perfectly well behaved.
+
+    ⛔ AND IT IS PLAIN `def`, NOT `async def` — see this module's header. A ten-second subprocess
+    wait on the event loop is a ten-second outage for the whole container.
+    """
+    import core.script_sandbox as sandbox                                    # noqa: PLC0415
+
+    rec = _all(session.runtime).get(str(view_id))
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    database = str(rec.get("database") or "")
+    # A DRAFT run: the editor sends unsaved code so the author can try it before committing to it.
+    # It is checked exactly as a stored one is, because "unsaved" is not a permission.
+    draft = (body or {}).get("source") if isinstance(body, dict) else None
+    source = _clean_source(draft) if draft else str(rec.get("source") or "")
+    # ⚠ NO `_database_ok` CALL HERE. `run_view` asks C1 the identical question a line later, and
+    # asking twice builds a registry topic's pool twice. The three refusals are translated below
+    # instead, which is the same wall reached through the same door.
+
+    if not _RUN_SLOTS.acquire(blocking=False):
+        raise err(429, "busy",
+                  f"{MAX_CONCURRENT_RUNS} script views are already running on this server. "
+                  f"Try again in a moment")
+    try:
+        out = sandbox.run_view(session.user, database, source, st=session.runtime)
+    finally:
+        _RUN_SLOTS.release()
+
+    # ⛔ C1'S THREE REFUSALS ARE HTTP STATUSES, NOT `ok:false`. "You may not read this database"
+    # answered 200 would be a permission decision the client has to go looking for, and every
+    # other door in this app answers 403 for it. Everything BELOW this line is a well-formed
+    # request whose ANSWER is that the script did not produce a view — that is a 200 with
+    # `ok:false`, the shape `routes_web_agent.test` already uses for the same reason.
+    if out.get("code") == "unknown_table":
+        raise err(404, "no_database", out.get("message") or f"there is no database '{database}'")
+    if out.get("code") == "denied":
+        raise err(403, "forbidden", out.get("message") or "your account may not read that database")
+    if out.get("code") == "unresolvable":
+        refusal = err(409, "unresolvable", out.get("message") or "these rows cannot be served")
+        refusal.detail["error"]["limit"] = out.get("limit") or {}
+        raise refusal
+
+    answer = {"ok": bool(out.get("ok")), "spec": out.get("spec"),
+              "stdout": out.get("stdout") or "", "truncated": bool(out.get("truncated")),
+              "ms": int(out.get("ms") or 0), "code": out.get("code") or "",
+              # ⭐ `caps` RIDES ON THE ANSWER (standing rule 1). On a POSIX host all three limits
+              # were applied; on a Windows host the memory and CPU ones were not, and a screen
+              # that claims an enforcement which did not happen is the failure the rule is about.
+              "caps": out.get("caps") or {}}
+    if not answer["ok"]:
+        answer["error"] = out.get("message") or "the script view did not produce a view"
+    return answer

api/routes_shares.py

@@ -1,393 +1,393 @@
-"""routes_shares.py — the manage-access surface (wave 20, owner ruling R10, contract C-SHARE).
-
-    GET  /api/v1/share/{kind}/{oid}      -> {owner, entries:[{user,role}], mayAdminister, people}
-    PUT  /api/v1/share/{kind}/{oid}      <- {entries:[{user,role}]}   (REPLACES the set)
-    GET  /api/v1/share/mine              -> {view:[id], folder:[id], database:[id]}
-
-`kind` ∈ view | folder | database. Roles are `view` | `edit` — the same two words the view rail
-already speaks, now extended to folders and databases so there is ONE vocabulary in the UI
-(R10: "the same picker views use").
-
-⛔ **RE-SHARING IS THE OWNER'S, AND THAT IS ENFORCED HERE, NOT IN THE CLIENT.** `PUT` requires
-`shares.may_administer` (owner or admin). A collaborator with `edit` may change an object's
-CONTENT and may not change who else can reach it — otherwise anyone you shared a view with could
-widen it to everyone, or grant themselves ownership and lock you out. The client greys the editor
-for non-administrators; that is a courtesy, and this check is the wall.
-
-⚠ **THE GRANT NEVER WIDENS PAST THE MODULE WALL — ON A GOVERNED MODULE.** `*` ("everyone") means
-every account that can already open the surface: `require_session` plus the topic's own gate run
-first, and for `customer_data` / `product_data` the receiver's own row scope and hidden-field
-closure run BEFORE any foreign view is merged. Sharing there can only narrow-or-equal the set that
-could already reach the data ([[aios-permissioning]]).
-
-⛔⛔ **AND THAT SENTENCE IS FALSE FOR `kind='database'`, WHICH IS WHY IT NOW SAYS "ON A GOVERNED
-MODULE" (W32-T26, audit S-8).** `routes_admin._PERM_MODULES` is `("customer_data","product_data")`
-and `_clean_perms` **400s** on anything else, so **no row filter and no hidden field can even be
-DECLARED for a `ut_*` database** — `routes_tables.py` makes zero `perm_scope` calls and passes
-`hidden_keys=frozenset()`. There is no module wall behind a user table for a grant to be bounded
-by: **this registry IS the wall.** So a `database` grant is ALL-OR-NOTHING — every row, every
-column — and an `*` database grant admits every account in the tenant to all of it.
-That is a real capability, deliberately kept; what was wrong was a docstring promising a second
-wall that does not exist for this kind. Scoping user tables is booked, not done
-(`waves/wave32/sharing-audit.md` S-8).
-
-⚠ **TWO SYSTEMS ANSWER "IS THIS SHARED", AND THEY ARE NOT THE SAME ONE (audit S-4).** THIS
-registry decides who appears in *"Shared with me"* and who may re-share. **`table_store.is_shared`
-— the view's own `permissions` — is what actually decides who may OPEN a view.** A grant here
-whose object is invisible under that one is a row in a list that opens a refusal, which is what
-made item 18 worth auditing. `_entries_or_400` closes the common cause (a name nobody has), but
-the two vocabularies are still two.
-"""
-from fastapi import APIRouter, Body, Depends
-
-import core.shares as shares
-import core.users as users
-from deps import Session, err, require_session
-# ⭐ W32-T28 (C3) — the SHARE notification's topic word, imported from the module that CLASSIFIES
-# it (`routes_alerts.notification_view`) rather than typed again here. The producer and the
-# reader agreeing about one string is the whole difference between an Inbox row that opens the
-# shared database and one that is quietly unclickable.
-from routes_alerts import SHARE_TOPIC as _SHARE_TOPIC
-
-router = APIRouter(prefix="/api/v1")
-
-
-def _kind_or_400(raw):
-    try:
-        return shares._check_kind(raw)
-    except ValueError as e:
-        raise err(400, "bad_kind", str(e))
-
-
-# ── ⭐⭐ WAVE 32 · T26 (owner item 18, ruling R12) — THE WALL THIS FILE SAID IT HAD ─────────────
-#
-# `put_share`'s comment used to justify the first-claim rule with *"reaching this route at all
-# means passing the surface's own wall"*. **There was no such wall.** `kind` and `oid` are free
-# strings off the URL and the only dependency was `require_session`, so any signed-in account
-# could `PUT` a grant on an id it had never seen. Because the 403 sat behind `if rec["owner"]`,
-# an object with no grant record skipped the check entirely and the caller was stamped OWNER —
-# sticky, so **the real creator was then refused on their own view, permanently.** Driven, not
-# argued: `waves/wave32/sharing-audit.md` S-1 carries the four-step transcript.
-#
-# ⚠ AND IT WAS SILENT ON BOTH SIDES. The claimant does not even see the object in their own
-# "Shared with me" (`shared_with` excludes what you own), so nothing appears anywhere until the
-# victim next opens the dialog.
-
-#: The built-in grid topics. A view or folder lives in `{topic}_table_workspace`, and the share
-#: route is not told which topic — so resolving one means asking each.
-_BUILTIN_TOPICS = ("customer", "product")
-
-
-def _topics(session):
-    """Every topic whose workspace could hold a view or folder for this tenant.
-
-    ⚠ `all_defs`, never `all_tables` — the latter is the whole 28.6 MB row payload (~703 ms on
-    tenant #0) to answer a question about KEYS (D-185).
-    """
-    try:
-        import core.user_tables as ut
-        return (*_BUILTIN_TOPICS, *(ut.all_defs(st=session.runtime) or {}))
-    except Exception:                                       # noqa: BLE001
-        return _BUILTIN_TOPICS
-
-
-def _owns_object(session, kind, oid):
-    """May this caller CLAIM an object that has no grant record yet — i.e. do they own it?
-
-    ⛔ THIS GUARDS THE CLAIM, NOT THE READ, AND THAT IS DELIBERATE. Resolving a view means asking
-    each topic's workspace in turn, which is N store reads; making every share call pay that
-    would put a loop on a route the manage-access dialog opens. The dangerous path is the one
-    where a caller is about to be stamped OWNER of something nobody owns — so the resolution runs
-    exactly there, and the common path (a record exists, `may_administer` decides) is untouched.
-    """
-    if session.admin:
-        return True
-    if kind == "database":
-        # ⚠ `may_open` is THE resolver for a user table (its own docstring says so) and already
-        # admits creator, admin, or a `database` grantee. Re-implementing "who owns a table"
-        # here would be the second definition this wave keeps finding.
-        try:
-            import core.user_tables as ut
-            return bool(ut.may_open(oid, session.uname, is_admin=session.admin,
-                                    st=session.runtime))
-        except Exception:                                   # noqa: BLE001
-            return False
-    try:
-        import core.table_store as table_store
-    except Exception:                                       # noqa: BLE001
-        return False
-    for topic in _topics(session):
-        try:
-            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
-            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
-        except Exception:                                   # noqa: BLE001
-            continue
-        if hit:
-            # `find_view`/`find_folder` answer `(owner_username, …)`. The claim belongs to the
-            # person whose personal stratum holds it — anybody else reaching this line is
-            # exactly the case S-1 describes.
-            return str(hit[0]) == str(session.uname)
-    return False
-
-
-def _can_see_object(session, kind, oid):
-    """May this caller READ an object's grant list — i.e. can they reach the object at all?
-
-    ⛔⛔ THIS IS DELIBERATELY WIDER THAN {@link _owns_object}, AND CONFLATING THE TWO IS A
-    REGRESSION I SHIPPED AND CAUGHT. The first version of T26 guarded BOTH doors with the
-    ownership test, which reads sensibly and is wrong for the read, because **`find_view` searches
-    PERSONAL STRATA ONLY** (its own docstring says so). So a view living in alice's stratum with
-    `permissions.edit = "collaborative"` and no grant record yet — a view bob **can open and edit
-    in the grid** — answered `404` when bob opened its manage-access dialog. Measured before
-    fixing: `table_store._may_see(view, "bob") is True` while `GET /share/view/vc` said
-    `404 no_object`.
-    ⚠ THAT IS THE AUDIT'S OWN S-4 BITING THE AUDIT'S OWN FIX: two systems answer "is this shared",
-    and the wall consulted the grant registry (system A) plus stratum ownership, never the view's
-    `permissions` (system B) — which is the one that actually decides who may OPEN it.
-    ⚠ And it hides the ANSWER, not just the editor. `ViewSidebar`'s Share row is deliberately not
-    gated on edit rights because *"hiding the row from everyone else would hide the ANSWER too —
-    'who has this?' is a fair question for anyone the view was shared with"*. A 404 there tells a
-    legitimate collaborator their view does not exist.
-
-    ⛔ THE CLAIM KEEPS THE NARROW TEST. Being able to SEE an object must not let you become its
-    owner — that is S-1, and widening this predicate onto `put_share` would re-open it.
-    """
-    if _owns_object(session, kind, oid):
-        return True
-    if kind != "view":
-        # A folder carries no per-object visibility flag of its own, and a database's `may_open`
-        # (inside `_owns_object`) already admits grantees. Nothing wider to ask.
-        return False
-    try:
-        import core.table_store as table_store
-        for topic in _topics(session):
-            hit = table_store.make(f"{topic}_table_workspace", st=session.runtime).find_view(oid)
-            if hit:
-                return bool(table_store._may_see(hit[1] if len(hit) > 1 else {},
-                                                 session.uname, is_admin=session.admin))
-    except Exception:                                       # noqa: BLE001
-        return False
-    return False
-
-
-def _entries_or_400(session, entries):
-    """Validate a grant list against the tenant's REAL, ACTIVE accounts — and refuse BY NAME.
-
-    ⛔ `core.shares._clean_entries` silently drops junk, and its docstring argues that correctly:
-    a UI mid-save must not lose the whole list to one malformed row. **But it validates the SHAPE
-    of a string and the role word — never that the user EXISTS, is ACTIVE, or is in this tenant**,
-    so a typo'd name is stored, reported as a successful save, and never reaches anybody. The
-    sharer believes the person has access. That is item 18's plain reading.
-    ⚠ The correct population is computed THREE FUNCTIONS BELOW and served to the picker
-    (`_people`). One route, two populations, and the write door was the permissive one.
-    ⚠ `*` (everyone) is not a user and is admitted deliberately — it is R10's vocabulary for
-    "every account that can already open the surface".
-    """
-    known = {p["username"].strip().lower() for p in _people(session.tenant)}
-    unknown = []
-    for e in entries or ():
-        if not isinstance(e, dict):
-            continue
-        user = str(e.get("user") or "").strip().lower()
-        if user and user != shares.EVERYONE and user not in known:
-            unknown.append(user)
-    if unknown:
-        raise err(400, "unknown_people",
-                  "no active account in this workspace is named "
-                  + ", ".join(sorted(set(unknown)))
-                  + " — nothing was shared. Pick people from the list rather than typing a name.")
-
-
-@router.get("/share/mine")
-def my_shares(session: Session = Depends(require_session)):
-    """Everything shared WITH me, by kind — the "Shared with me" rail section (R10).
-
-    Registered before `/share/{kind}/{oid}` so the literal path wins the match; FastAPI resolves
-    in declaration order and `mine` would otherwise be read as a `kind`, answering 400 for a URL
-    that is not malformed at all.
-    """
-    return shares.shared_with(session.uname, st=session.runtime)
-
-
-@router.get("/share/{kind}/{oid}")
-def get_share(kind: str, oid: str, session: Session = Depends(require_session)):
-    kind = _kind_or_400(kind)
-    rec = shares.grants(kind, oid, st=session.runtime)
-    role = shares.role_for(kind, oid, session.uname, is_admin=session.admin, st=session.runtime)
-    may_admin = shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
-                                      st=session.runtime)
-    # ⭐ W32-T26 (audit S-3) — A STRANGER LEARNS NOTHING. This route used to answer for ANY id:
-    # who owns it, everyone it is granted to, and the tenant's whole username↔name directory —
-    # to any signed-in session, about objects it cannot open. Now a caller with no role on an
-    # object must prove they can reach it, and gets a 404 otherwise: the same answer a
-    # non-existent id gives, so the route cannot be used to probe which ids are real.
-    # ⚠ `role is None` is the cheap pre-test, so the N-topic resolution below runs only for a
-    # caller who has no relationship with the object at all.
-    if role is None and not _can_see_object(session, kind, oid):
-        raise err(404, "no_object", "no such item, or it is not shared with this account")
-    return {
-        **rec,
-        "role": role,
-        "mayAdminister": may_admin,
-        # ⚠ WAVE 21 (C1 identity fix): grant entries BIND on USERNAMES, so the picker must carry
-        # them. `assignable_people` serves bare display names because `user`-kind CELLS store
-        # display names — that list's shape cannot change without migrating cell values — so
-        # this route serves objects of its own. Existing grants that were written as lowercased
-        # display names are normalised by the wave-21 cleanup script.
-        # ⭐ W32-T26 (audit S-3) — the roster is the EDITOR's data, so it rides only for a caller
-        # who may open the editor. A read-only grantee gets the grant list (their fair question is
-        # "who else has this?") and not a directory of every account in the workspace.
-        "people": _people(session.tenant) if may_admin else [],
-    }
-
-
-def _people(tenant):
-    """[{username, name}] for this tenant — same population as `assignable_people`, with the
-    BINDING identity alongside the display one."""
-    try:
-        reg = users.registry() or {}
-    except Exception:
-        return []
-    want = str(tenant or '').strip().lower()
-    out = []
-    for uname, u in reg.items():
-        if not isinstance(u, dict) or u.get('active') is False:
-            continue
-        if want and str(u.get('tenant') or 'royal-imports').strip().lower() != want:
-            continue
-        out.append({"username": str(uname), "name": str(u.get('name') or uname)})
-    return sorted(out, key=lambda p: p["name"].lower())
-
-
-@router.put("/share/{kind}/{oid}")
-def put_share(kind: str, oid: str, body: dict = Body(default=None),
-              session: Session = Depends(require_session)):
-    kind = _kind_or_400(kind)
-    body = body or {}
-    rec = shares.grants(kind, oid, st=session.runtime)
-    # An object with NO grant record yet has no owner — the first person to share it claims it.
-    # That is safe because reaching this route at all means passing the surface's own wall, and
-    # the alternative (refusing until somebody seeds an owner) would make a brand-new folder
-    # unshareable by the person who just made it.
-    if rec["owner"]:
-        if not shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
-                                     st=session.runtime):
-            raise err(403, "not_owner",
-                      "only the owner of this item (or an administrator) can change who it is "
-                      "shared with")
-    # ⛔⛔ W32-T26 (audit S-1) — THE CLAIM NOW HAS A PRECONDITION. An object with no grant record
-    # is still claimed by the first person to share it — that rule is right, and refusing until
-    # somebody seeds an owner would make a brand-new folder unshareable by the person who just
-    # made it. What was missing is the half the old comment ASSERTED and the code never did: the
-    # claimant has to be able to reach the object. Without this, any signed-in account could
-    # stamp itself owner of an id it had never seen and lock the real creator out for good.
-    elif not _owns_object(session, kind, oid):
-        raise err(404, "no_object", "no such item, or it is not shared with this account")
-    entries = body.get("entries")
-    if not isinstance(entries, list):
-        raise err(400, "bad_entries",
-                  "entries must be a list of {user, role} — send [] to un-share, which is how "
-                  "revoking is expressed")
-    _entries_or_400(session, entries)
-    out = shares.set_grants(kind, oid, entries, owner=rec["owner"] or session.uname,
-                            st=session.runtime)
-    _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
-    return out
-
-
-def _notify_new_grantees(session, kind, oid, before, after):
-    """⭐⭐ W32-T28 (owner item 18's last clause, contract C3) — tell the RECEIVER, in their Inbox.
-
-    Owner item 18 ends *"being shared a database notifies the receiver"*. Until now sharing was
-    silent: the grant landed in a rail section the receiver had to notice on their own, which is
-    why "I shared it with you" and "I never saw it" were both true.
-
-    ⛔ WRITTEN ON THE SHARE, NEVER POLLED. `/notifications` re-evaluates view-ALERTS on read
-    because an alert is a live question about rows; a share is an EVENT that happened once, and
-    polling for it would mean re-deriving "was this new?" on every inbox open — the diff below
-    only exists here, at the moment the set changes.
-
-    ⚠ ONLY THE NEWLY ADDED. `PUT` REPLACES the whole entry set (revoking is expressed by absence),
-    so every save re-sends everyone who was already there. Diffing against `before` is what stops
-    a rename or a role change from ringing the bell for people whose access did not change.
-    ⚠ `*` IS NOT NOTIFIED: there is no user to name, and minting one notification per account in
-    the tenant on a single click is a broadcast nobody asked for. The rail still shows it.
-    ⚠ IT NEVER RAISES. A notification that fails must not fail the share that triggered it — the
-    grant is the user's actual intent, and `core.alerts.notify` writes with `flush='async'`.
-    """
-    try:
-        was = {e.get("user") for e in (before or ()) if isinstance(e, dict)}
-        fresh = [str(e.get("user")) for e in (after or ())
-                 if isinstance(e, dict) and e.get("user") not in was
-                 and e.get("user") != shares.EVERYONE]
-        if not fresh:
-            return
-        import core.alerts as alerts
-
-        label, route, view_id = _object_ref(session, kind, oid)
-        if not route:
-            # ⛔ NO ROUTE, NO NOTIFICATION — the receiver would get a row that opens nothing, and
-            # `notification_view` would have to invent a target. Silence is the honest answer
-            # here; the rail still shows the grant under "Shared with me".
-            return
-        sharer = str(session.user.get("name") or session.uname)
-        for user in fresh:
-            # ⚠ THE SHAPE IS `routes_alerts.notification_view`'s SHARE BRANCH, and the two must
-            # agree or the Inbox row is unclickable: `topic` selects the branch and `key` becomes
-            # `alertId`, which that branch reads as the id to open. Both constants are IMPORTED
-            # from there rather than typed again — one vocabulary, one owner.
-            # ⭐⭐ W33-T28 (`ASK C-14`, answered) — `actor` IS THE SENDER, AND IT IS THE ONLY WAY
-            # THE INBOX CAN NAME ONE. An alert and an automation have no person behind them and
-            # are honestly named by their machine; a SHARE has a real person, and only this call
-            # site knows who. ⛔ It is passed as its OWN field rather than recovered from the
-            # `detail` prose below: a sender parsed out of "<name> shared this with you" breaks
-            # the first time the sentence is reworded, silently, in the header
-            # [[grep-output-is-not-source]]. The prose stays as the body; this is the From.
-            alerts.notify(user, label, topic=_SHARE_TOPIC, key=route, row_id=view_id,
-                          detail=f"{sharer} shared this with you", actor=sharer,
-                          st=session.runtime)
-    except Exception:                                       # noqa: BLE001
-        return
-
-
-def _object_ref(session, kind, oid):
-    """`(label, route, view_id)` — what to CALL the shared thing, and where it OPENS.
-
-    ⛔ THE ROUTE IS RESOLVED HERE, NOT SHAPED IN THE CONSUMER, AND THE FIRST VERSION GOT IT
-    WRONG: it put the raw `oid` in the notification's key, so a shared VIEW produced
-    `target: {module: "database", id: "view_42"}` — an instruction to open a database named
-    `view_42`. It read perfectly in the payload and would have opened nothing. **A view is not
-    addressable on its own; it is a SELECTION inside a topic's grid**, so the pair is what has to
-    travel. Caught by looking at the notification the driver actually produced, not by reading
-    the code back.
-
-    ⚠ `label` never falls back to a raw id. A notification headed `ut_leads_3f2a` tells the
-    receiver nothing they can act on, and the id is already in the target.
-    ⚠ An unresolvable object answers `route=None`, and the caller then sends NOTHING rather than
-    a row that opens nowhere.
-    """
-    try:
-        if kind == "database":
-            import core.user_tables as ut
-            defn = (ut.all_defs(st=session.runtime) or {}).get(str(oid)) or {}
-            # A user table IS its own route key in both vocabularies (`route_for_topic`).
-            return (str(defn.get("label") or "").strip() or "A database", str(oid), "")
-        import core.table_store as table_store
-        from routes_alerts import route_for_topic
-        for topic in _topics(session):
-            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
-            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
-            if not hit:
-                continue
-            route = route_for_topic(topic)
-            if not route:
-                break
-            row = hit[1] if len(hit) > 1 else {}
-            name = str((row or {}).get("name") or "").strip()
-            # ⚠ Only a VIEW carries a selection. A folder is a rail grouping, so the target opens
-            # the grid and stops there rather than naming a view the receiver did not get.
-            return (name or ("A view" if kind == "view" else "A folder"),
-                    route, str(oid) if kind == "view" else "")
-    except Exception:                                       # noqa: BLE001
-        pass
-    return ({"view": "A view", "folder": "A folder"}.get(kind, "An item"), None, "")
+"""routes_shares.py — the manage-access surface (wave 20, owner ruling R10, contract C-SHARE).
+
+    GET  /api/v1/share/{kind}/{oid}      -> {owner, entries:[{user,role}], mayAdminister, people}
+    PUT  /api/v1/share/{kind}/{oid}      <- {entries:[{user,role}]}   (REPLACES the set)
+    GET  /api/v1/share/mine              -> {view:[id], folder:[id], database:[id]}
+
+`kind` ∈ view | folder | database. Roles are `view` | `edit` — the same two words the view rail
+already speaks, now extended to folders and databases so there is ONE vocabulary in the UI
+(R10: "the same picker views use").
+
+⛔ **RE-SHARING IS THE OWNER'S, AND THAT IS ENFORCED HERE, NOT IN THE CLIENT.** `PUT` requires
+`shares.may_administer` (owner or admin). A collaborator with `edit` may change an object's
+CONTENT and may not change who else can reach it — otherwise anyone you shared a view with could
+widen it to everyone, or grant themselves ownership and lock you out. The client greys the editor
+for non-administrators; that is a courtesy, and this check is the wall.
+
+⚠ **THE GRANT NEVER WIDENS PAST THE MODULE WALL — ON A GOVERNED MODULE.** `*` ("everyone") means
+every account that can already open the surface: `require_session` plus the topic's own gate run
+first, and for `customer_data` / `product_data` the receiver's own row scope and hidden-field
+closure run BEFORE any foreign view is merged. Sharing there can only narrow-or-equal the set that
+could already reach the data ([[aios-permissioning]]).
+
+⛔⛔ **AND THAT SENTENCE IS FALSE FOR `kind='database'`, WHICH IS WHY IT NOW SAYS "ON A GOVERNED
+MODULE" (W32-T26, audit S-8).** `routes_admin._PERM_MODULES` is `("customer_data","product_data")`
+and `_clean_perms` **400s** on anything else, so **no row filter and no hidden field can even be
+DECLARED for a `ut_*` database** — `routes_tables.py` makes zero `perm_scope` calls and passes
+`hidden_keys=frozenset()`. There is no module wall behind a user table for a grant to be bounded
+by: **this registry IS the wall.** So a `database` grant is ALL-OR-NOTHING — every row, every
+column — and an `*` database grant admits every account in the tenant to all of it.
+That is a real capability, deliberately kept; what was wrong was a docstring promising a second
+wall that does not exist for this kind. Scoping user tables is booked, not done
+(`waves/wave32/sharing-audit.md` S-8).
+
+⚠ **TWO SYSTEMS ANSWER "IS THIS SHARED", AND THEY ARE NOT THE SAME ONE (audit S-4).** THIS
+registry decides who appears in *"Shared with me"* and who may re-share. **`table_store.is_shared`
+— the view's own `permissions` — is what actually decides who may OPEN a view.** A grant here
+whose object is invisible under that one is a row in a list that opens a refusal, which is what
+made item 18 worth auditing. `_entries_or_400` closes the common cause (a name nobody has), but
+the two vocabularies are still two.
+"""
+from fastapi import APIRouter, Body, Depends
+
+import core.shares as shares
+import core.users as users
+from deps import Session, err, require_session
+# ⭐ W32-T28 (C3) — the SHARE notification's topic word, imported from the module that CLASSIFIES
+# it (`routes_alerts.notification_view`) rather than typed again here. The producer and the
+# reader agreeing about one string is the whole difference between an Inbox row that opens the
+# shared database and one that is quietly unclickable.
+from routes_alerts import SHARE_TOPIC as _SHARE_TOPIC
+
+router = APIRouter(prefix="/api/v1")
+
+
+def _kind_or_400(raw):
+    try:
+        return shares._check_kind(raw)
+    except ValueError as e:
+        raise err(400, "bad_kind", str(e))
+
+
+# ── ⭐⭐ WAVE 32 · T26 (owner item 18, ruling R12) — THE WALL THIS FILE SAID IT HAD ─────────────
+#
+# `put_share`'s comment used to justify the first-claim rule with *"reaching this route at all
+# means passing the surface's own wall"*. **There was no such wall.** `kind` and `oid` are free
+# strings off the URL and the only dependency was `require_session`, so any signed-in account
+# could `PUT` a grant on an id it had never seen. Because the 403 sat behind `if rec["owner"]`,
+# an object with no grant record skipped the check entirely and the caller was stamped OWNER —
+# sticky, so **the real creator was then refused on their own view, permanently.** Driven, not
+# argued: `waves/wave32/sharing-audit.md` S-1 carries the four-step transcript.
+#
+# ⚠ AND IT WAS SILENT ON BOTH SIDES. The claimant does not even see the object in their own
+# "Shared with me" (`shared_with` excludes what you own), so nothing appears anywhere until the
+# victim next opens the dialog.
+
+#: The built-in grid topics. A view or folder lives in `{topic}_table_workspace`, and the share
+#: route is not told which topic — so resolving one means asking each.
+_BUILTIN_TOPICS = ("customer", "product")
+
+
+def _topics(session):
+    """Every topic whose workspace could hold a view or folder for this tenant.
+
+    ⚠ `all_defs`, never `all_tables` — the latter is the whole 28.6 MB row payload (~703 ms on
+    tenant #0) to answer a question about KEYS (D-185).
+    """
+    try:
+        import core.user_tables as ut
+        return (*_BUILTIN_TOPICS, *(ut.all_defs(st=session.runtime) or {}))
+    except Exception:                                       # noqa: BLE001
+        return _BUILTIN_TOPICS
+
+
+def _owns_object(session, kind, oid):
+    """May this caller CLAIM an object that has no grant record yet — i.e. do they own it?
+
+    ⛔ THIS GUARDS THE CLAIM, NOT THE READ, AND THAT IS DELIBERATE. Resolving a view means asking
+    each topic's workspace in turn, which is N store reads; making every share call pay that
+    would put a loop on a route the manage-access dialog opens. The dangerous path is the one
+    where a caller is about to be stamped OWNER of something nobody owns — so the resolution runs
+    exactly there, and the common path (a record exists, `may_administer` decides) is untouched.
+    """
+    if session.admin:
+        return True
+    if kind == "database":
+        # ⚠ `may_open` is THE resolver for a user table (its own docstring says so) and already
+        # admits creator, admin, or a `database` grantee. Re-implementing "who owns a table"
+        # here would be the second definition this wave keeps finding.
+        try:
+            import core.user_tables as ut
+            return bool(ut.may_open(oid, session.uname, is_admin=session.admin,
+                                    st=session.runtime))
+        except Exception:                                   # noqa: BLE001
+            return False
+    try:
+        import core.table_store as table_store
+    except Exception:                                       # noqa: BLE001
+        return False
+    for topic in _topics(session):
+        try:
+            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
+            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
+        except Exception:                                   # noqa: BLE001
+            continue
+        if hit:
+            # `find_view`/`find_folder` answer `(owner_username, …)`. The claim belongs to the
+            # person whose personal stratum holds it — anybody else reaching this line is
+            # exactly the case S-1 describes.
+            return str(hit[0]) == str(session.uname)
+    return False
+
+
+def _can_see_object(session, kind, oid):
+    """May this caller READ an object's grant list — i.e. can they reach the object at all?
+
+    ⛔⛔ THIS IS DELIBERATELY WIDER THAN {@link _owns_object}, AND CONFLATING THE TWO IS A
+    REGRESSION I SHIPPED AND CAUGHT. The first version of T26 guarded BOTH doors with the
+    ownership test, which reads sensibly and is wrong for the read, because **`find_view` searches
+    PERSONAL STRATA ONLY** (its own docstring says so). So a view living in alice's stratum with
+    `permissions.edit = "collaborative"` and no grant record yet — a view bob **can open and edit
+    in the grid** — answered `404` when bob opened its manage-access dialog. Measured before
+    fixing: `table_store._may_see(view, "bob") is True` while `GET /share/view/vc` said
+    `404 no_object`.
+    ⚠ THAT IS THE AUDIT'S OWN S-4 BITING THE AUDIT'S OWN FIX: two systems answer "is this shared",
+    and the wall consulted the grant registry (system A) plus stratum ownership, never the view's
+    `permissions` (system B) — which is the one that actually decides who may OPEN it.
+    ⚠ And it hides the ANSWER, not just the editor. `ViewSidebar`'s Share row is deliberately not
+    gated on edit rights because *"hiding the row from everyone else would hide the ANSWER too —
+    'who has this?' is a fair question for anyone the view was shared with"*. A 404 there tells a
+    legitimate collaborator their view does not exist.
+
+    ⛔ THE CLAIM KEEPS THE NARROW TEST. Being able to SEE an object must not let you become its
+    owner — that is S-1, and widening this predicate onto `put_share` would re-open it.
+    """
+    if _owns_object(session, kind, oid):
+        return True
+    if kind != "view":
+        # A folder carries no per-object visibility flag of its own, and a database's `may_open`
+        # (inside `_owns_object`) already admits grantees. Nothing wider to ask.
+        return False
+    try:
+        import core.table_store as table_store
+        for topic in _topics(session):
+            hit = table_store.make(f"{topic}_table_workspace", st=session.runtime).find_view(oid)
+            if hit:
+                return bool(table_store._may_see(hit[1] if len(hit) > 1 else {},
+                                                 session.uname, is_admin=session.admin))
+    except Exception:                                       # noqa: BLE001
+        return False
+    return False
+
+
+def _entries_or_400(session, entries):
+    """Validate a grant list against the tenant's REAL, ACTIVE accounts — and refuse BY NAME.
+
+    ⛔ `core.shares._clean_entries` silently drops junk, and its docstring argues that correctly:
+    a UI mid-save must not lose the whole list to one malformed row. **But it validates the SHAPE
+    of a string and the role word — never that the user EXISTS, is ACTIVE, or is in this tenant**,
+    so a typo'd name is stored, reported as a successful save, and never reaches anybody. The
+    sharer believes the person has access. That is item 18's plain reading.
+    ⚠ The correct population is computed THREE FUNCTIONS BELOW and served to the picker
+    (`_people`). One route, two populations, and the write door was the permissive one.
+    ⚠ `*` (everyone) is not a user and is admitted deliberately — it is R10's vocabulary for
+    "every account that can already open the surface".
+    """
+    known = {p["username"].strip().lower() for p in _people(session.tenant)}
+    unknown = []
+    for e in entries or ():
+        if not isinstance(e, dict):
+            continue
+        user = str(e.get("user") or "").strip().lower()
+        if user and user != shares.EVERYONE and user not in known:
+            unknown.append(user)
+    if unknown:
+        raise err(400, "unknown_people",
+                  "no active account in this workspace is named "
+                  + ", ".join(sorted(set(unknown)))
+                  + " — nothing was shared. Pick people from the list rather than typing a name.")
+
+
+@router.get("/share/mine")
+def my_shares(session: Session = Depends(require_session)):
+    """Everything shared WITH me, by kind — the "Shared with me" rail section (R10).
+
+    Registered before `/share/{kind}/{oid}` so the literal path wins the match; FastAPI resolves
+    in declaration order and `mine` would otherwise be read as a `kind`, answering 400 for a URL
+    that is not malformed at all.
+    """
+    return shares.shared_with(session.uname, st=session.runtime)
+
+
+@router.get("/share/{kind}/{oid}")
+def get_share(kind: str, oid: str, session: Session = Depends(require_session)):
+    kind = _kind_or_400(kind)
+    rec = shares.grants(kind, oid, st=session.runtime)
+    role = shares.role_for(kind, oid, session.uname, is_admin=session.admin, st=session.runtime)
+    may_admin = shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
+                                      st=session.runtime)
+    # ⭐ W32-T26 (audit S-3) — A STRANGER LEARNS NOTHING. This route used to answer for ANY id:
+    # who owns it, everyone it is granted to, and the tenant's whole username↔name directory —
+    # to any signed-in session, about objects it cannot open. Now a caller with no role on an
+    # object must prove they can reach it, and gets a 404 otherwise: the same answer a
+    # non-existent id gives, so the route cannot be used to probe which ids are real.
+    # ⚠ `role is None` is the cheap pre-test, so the N-topic resolution below runs only for a
+    # caller who has no relationship with the object at all.
+    if role is None and not _can_see_object(session, kind, oid):
+        raise err(404, "no_object", "no such item, or it is not shared with this account")
+    return {
+        **rec,
+        "role": role,
+        "mayAdminister": may_admin,
+        # ⚠ WAVE 21 (C1 identity fix): grant entries BIND on USERNAMES, so the picker must carry
+        # them. `assignable_people` serves bare display names because `user`-kind CELLS store
+        # display names — that list's shape cannot change without migrating cell values — so
+        # this route serves objects of its own. Existing grants that were written as lowercased
+        # display names are normalised by the wave-21 cleanup script.
+        # ⭐ W32-T26 (audit S-3) — the roster is the EDITOR's data, so it rides only for a caller
+        # who may open the editor. A read-only grantee gets the grant list (their fair question is
+        # "who else has this?") and not a directory of every account in the workspace.
+        "people": _people(session.tenant) if may_admin else [],
+    }
+
+
+def _people(tenant):
+    """[{username, name}] for this tenant — same population as `assignable_people`, with the
+    BINDING identity alongside the display one."""
+    try:
+        reg = users.registry() or {}
+    except Exception:
+        return []
+    want = str(tenant or '').strip().lower()
+    out = []
+    for uname, u in reg.items():
+        if not isinstance(u, dict) or u.get('active') is False:
+            continue
+        if want and str(u.get('tenant') or 'royal-imports').strip().lower() != want:
+            continue
+        out.append({"username": str(uname), "name": str(u.get('name') or uname)})
+    return sorted(out, key=lambda p: p["name"].lower())
+
+
+@router.put("/share/{kind}/{oid}")
+def put_share(kind: str, oid: str, body: dict = Body(default=None),
+              session: Session = Depends(require_session)):
+    kind = _kind_or_400(kind)
+    body = body or {}
+    rec = shares.grants(kind, oid, st=session.runtime)
+    # An object with NO grant record yet has no owner — the first person to share it claims it.
+    # That is safe because reaching this route at all means passing the surface's own wall, and
+    # the alternative (refusing until somebody seeds an owner) would make a brand-new folder
+    # unshareable by the person who just made it.
+    if rec["owner"]:
+        if not shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
+                                     st=session.runtime):
+            raise err(403, "not_owner",
+                      "only the owner of this item (or an administrator) can change who it is "
+                      "shared with")
+    # ⛔⛔ W32-T26 (audit S-1) — THE CLAIM NOW HAS A PRECONDITION. An object with no grant record
+    # is still claimed by the first person to share it — that rule is right, and refusing until
+    # somebody seeds an owner would make a brand-new folder unshareable by the person who just
+    # made it. What was missing is the half the old comment ASSERTED and the code never did: the
+    # claimant has to be able to reach the object. Without this, any signed-in account could
+    # stamp itself owner of an id it had never seen and lock the real creator out for good.
+    elif not _owns_object(session, kind, oid):
+        raise err(404, "no_object", "no such item, or it is not shared with this account")
+    entries = body.get("entries")
+    if not isinstance(entries, list):
+        raise err(400, "bad_entries",
+                  "entries must be a list of {user, role} — send [] to un-share, which is how "
+                  "revoking is expressed")
+    _entries_or_400(session, entries)
+    out = shares.set_grants(kind, oid, entries, owner=rec["owner"] or session.uname,
+                            st=session.runtime)
+    _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
+    return out
+
+
+def _notify_new_grantees(session, kind, oid, before, after):
+    """⭐⭐ W32-T28 (owner item 18's last clause, contract C3) �� tell the RECEIVER, in their Inbox.
+
+    Owner item 18 ends *"being shared a database notifies the receiver"*. Until now sharing was
+    silent: the grant landed in a rail section the receiver had to notice on their own, which is
+    why "I shared it with you" and "I never saw it" were both true.
+
+    ⛔ WRITTEN ON THE SHARE, NEVER POLLED. `/notifications` re-evaluates view-ALERTS on read
+    because an alert is a live question about rows; a share is an EVENT that happened once, and
+    polling for it would mean re-deriving "was this new?" on every inbox open — the diff below
+    only exists here, at the moment the set changes.
+
+    ⚠ ONLY THE NEWLY ADDED. `PUT` REPLACES the whole entry set (revoking is expressed by absence),
+    so every save re-sends everyone who was already there. Diffing against `before` is what stops
+    a rename or a role change from ringing the bell for people whose access did not change.
+    ⚠ `*` IS NOT NOTIFIED: there is no user to name, and minting one notification per account in
+    the tenant on a single click is a broadcast nobody asked for. The rail still shows it.
+    ⚠ IT NEVER RAISES. A notification that fails must not fail the share that triggered it — the
+    grant is the user's actual intent, and `core.alerts.notify` writes with `flush='async'`.
+    """
+    try:
+        was = {e.get("user") for e in (before or ()) if isinstance(e, dict)}
+        fresh = [str(e.get("user")) for e in (after or ())
+                 if isinstance(e, dict) and e.get("user") not in was
+                 and e.get("user") != shares.EVERYONE]
+        if not fresh:
+            return
+        import core.alerts as alerts
+
+        label, route, view_id = _object_ref(session, kind, oid)
+        if not route:
+            # ⛔ NO ROUTE, NO NOTIFICATION — the receiver would get a row that opens nothing, and
+            # `notification_view` would have to invent a target. Silence is the honest answer
+            # here; the rail still shows the grant under "Shared with me".
+            return
+        sharer = str(session.user.get("name") or session.uname)
+        for user in fresh:
+            # ⚠ THE SHAPE IS `routes_alerts.notification_view`'s SHARE BRANCH, and the two must
+            # agree or the Inbox row is unclickable: `topic` selects the branch and `key` becomes
+            # `alertId`, which that branch reads as the id to open. Both constants are IMPORTED
+            # from there rather than typed again — one vocabulary, one owner.
+            # ⭐⭐ W33-T28 (`ASK C-14`, answered) — `actor` IS THE SENDER, AND IT IS THE ONLY WAY
+            # THE INBOX CAN NAME ONE. An alert and an automation have no person behind them and
+            # are honestly named by their machine; a SHARE has a real person, and only this call
+            # site knows who. ⛔ It is passed as its OWN field rather than recovered from the
+            # `detail` prose below: a sender parsed out of "<name> shared this with you" breaks
+            # the first time the sentence is reworded, silently, in the header
+            # [[grep-output-is-not-source]]. The prose stays as the body; this is the From.
+            alerts.notify(user, label, topic=_SHARE_TOPIC, key=route, row_id=view_id,
+                          detail=f"{sharer} shared this with you", actor=sharer,
+                          st=session.runtime)
+    except Exception:                                       # noqa: BLE001
+        return
+
+
+def _object_ref(session, kind, oid):
+    """`(label, route, view_id)` — what to CALL the shared thing, and where it OPENS.
+
+    ⛔ THE ROUTE IS RESOLVED HERE, NOT SHAPED IN THE CONSUMER, AND THE FIRST VERSION GOT IT
+    WRONG: it put the raw `oid` in the notification's key, so a shared VIEW produced
+    `target: {module: "database", id: "view_42"}` — an instruction to open a database named
+    `view_42`. It read perfectly in the payload and would have opened nothing. **A view is not
+    addressable on its own; it is a SELECTION inside a topic's grid**, so the pair is what has to
+    travel. Caught by looking at the notification the driver actually produced, not by reading
+    the code back.
+
+    ⚠ `label` never falls back to a raw id. A notification headed `ut_leads_3f2a` tells the
+    receiver nothing they can act on, and the id is already in the target.
+    ⚠ An unresolvable object answers `route=None`, and the caller then sends NOTHING rather than
+    a row that opens nowhere.
+    """
+    try:
+        if kind == "database":
+            import core.user_tables as ut
+            defn = (ut.all_defs(st=session.runtime) or {}).get(str(oid)) or {}
+            # A user table IS its own route key in both vocabularies (`route_for_topic`).
+            return (str(defn.get("label") or "").strip() or "A database", str(oid), "")
+        import core.table_store as table_store
+        from routes_alerts import route_for_topic
+        for topic in _topics(session):
+            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
+            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
+            if not hit:
+                continue
+            route = route_for_topic(topic)
+            if not route:
+                break
+            row = hit[1] if len(hit) > 1 else {}
+            name = str((row or {}).get("name") or "").strip()
+            # ⚠ Only a VIEW carries a selection. A folder is a rail grouping, so the target opens
+            # the grid and stops there rather than naming a view the receiver did not get.
+            return (name or ("A view" if kind == "view" else "A folder"),
+                    route, str(oid) if kind == "view" else "")
+    except Exception:                                       # noqa: BLE001
+        pass
+    return ({"view": "A view", "folder": "A folder"}.get(kind, "An item"), None, "")

api/routes_slack.py

@@ -229,7 +229,10 @@ def slack_creds(rt):
 def _summary(agent, modules):
     """One sentence per agent for the list row — computed here, because the alternative is one
     round trip per row to fill one cell (the same reason `AdminUser.access` exists)."""
-    governed = [m for m in modules if m.get("enforced")]
+    # ⭐ W36-T22 / C2 — every listed database is governed now; the `enforced` flag it used to
+    # filter on is DELETED, and `m.get("enforced")` would have gone silently falsy here and
+    # summarised every agent as "" (no databases at all).
+    governed = list(modules)
     perms = agent.get("perms") or {}
     open_n = sum(1 for m in governed if (perms.get(m["key"]) or {}).get("access"))
     if not governed:
@@ -304,16 +307,26 @@ def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
     if not isinstance(a, dict):
         raise err(404, "no_such_agent", "no agent with that id")
     modules = routes_admin._perm_modules(session)
-    enforced = [m["key"] for m in modules if m.get("enforced")]
+    # ⭐⭐ W36-T22 / C2 — EVERY listed database, `ut_*` included. ⛔ THIS IS WHY THE FLAG'S
+    # DELETION IS NOT A ONE-FILE CHANGE: `m.get("enforced")` on a row that no longer carries the
+    # key is None, so this list would have been EMPTY and the channel perms editor would have
+    # governed ZERO databases while looking entirely correct. A Slack channel is a principal of
+    # the SAME wall (`verify_perm_scope` section H) and gets the same catalogue.
+    governed = [m["key"] for m in modules]
     stored = a.get("perms") or {}
     principal = agent_principal(a)
     import core.perm_scope as perm_scope
     perms_out = {}
-    for k in enforced:
+    for k in governed:
         e = stored.get(k)
+        # ⛔ W36-T22 — `may_read`, the same evaluator the read door uses, for the reason spelled
+        # out at `routes_admin.get_perms`. ⚠ It answers DIFFERENTLY here and correctly so: a
+        # channel agent is not a person with a share, so a `ut_*` key it has not been granted
+        # defaults CLOSED — which is the fail-closed direction for a bot, and the same answer the
+        # table routes would give it.
         perms_out[k] = e if isinstance(e, dict) else {
-            "access": bool(perm_scope.may_access(principal, k)), "filter": None,
-            "hiddenFields": []}
+            "access": bool(perm_scope.may_read(principal, k, st=session.runtime)),
+            "filter": None, "hiddenFields": []}
     return {"id": str(agent_id), "channel": a.get("channel") or "",
             "channelName": a.get("channelName") or "", "label": a.get("label") or "",
             "active": a.get("active", True) is not False,
@@ -326,7 +339,8 @@ def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
             # the "Everything (admin)" state for a principal that cannot have it.
             "is_admin": False,
             "modules": modules,
-            "fields_by_module": {k: routes_admin._module_fields(k) for k in enforced}}
+            "fields_by_module": {k: routes_admin._module_fields(k, session=session)
+                                 for k in governed}}
 
 
 @router.put("/agents/{agent_id}/perms")
@@ -341,14 +355,16 @@ def put_channel_agent_perms(agent_id: str, body: dict = Body(default=None),
         raise err(400, "empty_patch", "no perms to save")
     mods = routes_admin._perm_modules(session)
     # ⭐ THE SAME `_clean_perms`, NOT A COPY OF IT. It refuses a filter this module cannot
-    # evaluate, refuses a hiddenFields key that names nothing, refuses an unenforced `ut_*` key,
-    # and refuses a BU condition the pushdown cannot read. Every one of those is exactly as true
-    # for a channel as for a person, and a second validator here is a second place for one of
-    # them to go missing.
+    # evaluate, refuses a hiddenFields key that names nothing, and refuses a BU condition the
+    # pushdown cannot read. Every one of those is exactly as true for a channel as for a person,
+    # and a second validator here is a second place for one of them to go missing.
+    # ⚠ CORRECTED W36-T22: this list used to end "refuses an unenforced `ut_*` key". That refusal
+    # is DELETED — W36-T21 armed the wall over every database, so there is no unenforced key left
+    # to refuse, and a comment naming a rule that no longer exists is how the next wave re-derives
+    # it ([[two-gates-can-assert-opposite-things]]).
     cleaned = routes_admin._clean_perms(
         body.get("perms"),
-        enforced_keys={m["key"] for m in mods if m.get("enforced")},
-        listed_keys={m["key"] for m in mods}) or {}
+        governed_keys={m["key"] for m in mods}, session=session) or {}
 
     import core.perm_scope as perm_scope
 

api/routes_statements.py

@@ -129,9 +129,14 @@ def preview(body: dict = Body(default=None), session: Session = Depends(_gate)):
     subject = (t.get("subject") or cs.DEFAULT_SUBJECT)
     try:
         subject = subject.format(customer=row["Customer"], company=cs.COMPANY, month=month)
-    except (KeyError, IndexError):
+    except Exception:                                                     # noqa: BLE001
         # An unknown placeholder is the user's typo, not a 500. Show the template verbatim so they
         # can see what they typed rather than getting an opaque error.
+        # ⛔ W36-T42: THIS CAUGHT THREE OF THE WAYS `str.format` FAILS AND THERE ARE MORE.
+        # `{customer` is a ValueError, `{customer.x}` an AttributeError, `{customer:%Y}` a
+        # TypeError, and every one of them is the same user mistake this branch was written for.
+        # Naming a subset of the exception types turns a typo in the OTHER half into a 500 on the
+        # one screen somebody opens to avoid mailing 200 people the wrong thing.
         pass
     return {
         "html": cs.render_statement_html(row, t.get("intro") or cs.DEFAULT_INTRO,
@@ -153,7 +158,31 @@ def send(body: dict = Body(default=None), session: Session = Depends(_gate)):
     names = [str(n) for n in (body.get("customers") or []) if str(n).strip()]
     if not names:
         raise err(400, "bad_request", "name at least one customer")
-    override = (body.get("overrideTo") or "").strip() or None
+    # ⛔⛔ W36-T42 / D-299 — A DECLARED TEST SEND WITH NO ADDRESS REFUSES. IT DOES NOT BECOME A
+    # REAL ONE. This read `(body.get("overrideTo") or "").strip() or None`, so a caller who sent
+    # `overrideTo: ""` (the field left blank, the state not yet typed into, a trimmed-away space)
+    # got a REAL statement mailed to the debtor's own address, reported back as `test: false`. On
+    # the one route in this product that is allowed to write to Odoo, the difference between a
+    # rehearsal and mailing a live customer was one empty string.
+    #
+    # ⭐ THE DISCRIMINATOR IS THE CALLER'S DECLARATION, NOT THE VALUE. A body with no `overrideTo`
+    # key and no `test` flag is the PRODUCTION send, and refusing that would delete the feature
+    # D-299 exists to preserve. What can be refused is a caller who SAID this is a test: the key
+    # being present, or `test: true`, is that statement, and an empty address beside it is the
+    # mistake. So both spellings of "absent" are covered: the key present and blank, and `test`
+    # asserted with no key at all.
+    #
+    # ⚠ THIS IS THE SECOND OF THREE WALLS AND THE ONLY ONE A PAYLOAD CANNOT ROUTE AROUND.
+    # `automationApi.testSendStatement` refuses an empty address before the request is built, and
+    # SAFE_MODE refuses an address outside the allow-list inside `queue_statement`. The client
+    # wall is bypassable by construction (anything can POST); this one is not.
+    declared_test = ("overrideTo" in body) or bool(body.get("test"))
+    override = str(body.get("overrideTo") or "").strip()
+    if declared_test and not override:
+        raise err(400, "no_override_address",
+                  "a test send needs the address to send the test to. Without one this would "
+                  "mail the customer's own address, which is the opposite of a test")
+    override = override or None
     if override and len(names) != 1:
         raise err(400, "bad_request", "a test send takes exactly one customer")
     t = body.get("templates") or {}

api/routes_web_agent.py

@@ -22,10 +22,11 @@ admin-gated, because it spends money and because D-51 §5's authorisation postur
 the tenant is authorised to use, at their instruction") is not something an ordinary member
 should be able to commit the tenant to.
 
-⛔ THIS ROUTER IS NOT MOUNTED YET. `main.py` belongs to another lane this wave, so the one
-`app.include_router(routes_web_agent.router)` line is a cross-fence ask — and
-`verify_web_agent.py` FAILS until it lands, deliberately: three finished routers once shipped
-404-dead behind entirely green gates, and a gate that tolerates it is how that happens twice.
+⭐ MOUNTED, and the gate is what says so rather than this sentence: `main.py:80` imports it and
+`main.py:316` includes it, and `verify_web_agent.py` asserts the route answers rather than trusting
+either line. This paragraph read "NOT MOUNTED YET" for a whole wave after the mount landed, which
+is the same class of stale claim as a green gate on a router nobody wired: three finished routers
+once shipped 404-dead behind entirely green gates, and prose is not the control that stops it.
 """
 from fastapi import APIRouter, Body, Depends
 

platform/core/perm_scope.py

@@ -122,6 +122,19 @@ def hidden_keys(user, module, fields):
     ⚠ This runs on every assembly, so it is a fixpoint over a handful of custom fields, not a
     graph library. `MAX_PASSES` bounds a reference cycle the client would refuse to evaluate
     anyway; without it a self-referential pair would spin here.
+
+    ⭐⭐ W36-T21 — AND A ROLLUP IS THE SAME LEAK ONE MECHANISM OVER, which matters now that this
+    closure runs on the `ut_*` databases rather than only on the two registry topics. A rollup
+    names a LINK COLUMN OF THIS TABLE (`rollup.link`) and aggregates a field on the table that
+    link points at — so `ut_odoo_customers.ar_outstanding` is *"sum `residual` over the invoices
+    this row links to"*. Hide `invoices` and keep `ar_outstanding` and the reader still learns
+    what the hidden link contains, in aggregate; the three outcomes are exactly the three the
+    formula argument above enumerates, and only "strip both" is coherent. Verified against the
+    real declarations (`odoo_relational.customer_fields`) rather than assumed: every rollup there
+    is either `{'link': <a link column on THIS table>, 'field': <a column on the TARGET table>}`
+    or a `source` topic aggregate, so `rollup.link` is the ONE same-table reference a rollup makes
+    and `rollup.field` is deliberately not treated as one — it names another database's column,
+    which has its own wall.
     """
     e = entry(user, module)
     if perms.is_admin(user) or not e:
@@ -137,6 +150,9 @@ def hidden_keys(user, module, fields):
         expr = f.get('formula')
         if isinstance(expr, str) and expr:
             refs[f['key']] = {m.strip() for m in _FORMULA_REF.findall(expr) if m.strip()}
+        link = (f.get('rollup') or {}).get('link') if isinstance(f.get('rollup'), dict) else None
+        if isinstance(link, str) and link.strip():
+            refs.setdefault(f['key'], set()).add(link.strip())
 
     MAX_PASSES = 12
     for _ in range(MAX_PASSES):
@@ -452,3 +468,336 @@ def _group_dba_team(group):
         if vals <= allowed:
             return tid
     return None
+
+
+# ── C1: THE ONE DOOR TO ANY DATABASE'S ROWS (wave 36, W36-T20) ────────────────────────────────
+#: ⭐⭐ OWNER RULING R6, AND IT IS WHY THIS SECTION EXISTS AT ALL: *"EVERY database gets the same
+#: permission logic, always"* — per-user field visibility AND row filtration on every database
+#: carrying a unique id, whatever created it, with a NEW database inheriting it by construction
+#: rather than by a list somebody maintains.
+#:
+#: ⛔ THE PRODUCT HAD TWO PERMISSION SYSTEMS AND ONLY ONE WAS ARMED. Everything above this line
+#: walls the REGISTRY topics (`customer_data`, `product_data`) and is called only from the topic
+#: assemblies. Every OTHER database is a `ut_*` table walled by `user_tables.may_open` alone —
+#: creator, admin, or a `core.shares` grant — which is a BINARY door: you see all 31,418 rows of
+#: `ut_odoo_invoices` or none of them. `perms.tenant_governable_modules`' docstring booked this
+#: work in as many words (*"Arming `perm_scope` over `ut_*` … booked, not faked"*), and owner
+#: item 11 is that booking coming due.
+#:
+#: ⚠ AND THE PREMISE THE GRILL GOT WRONG, because the fix depends on it: those databases are NOT
+#: user-created. Ten of them (`ut_odoo_invoices`, `…_orders`, `…_agents`, `…_accounts`, `…_bills`,
+#: `…_vendors`, `…_order_lines`, `…_gl_lines`, `…_customers`, `…_products`) are generated by the
+#: KEYCHAIN connector (`aios-web/api/odoo_relational.py`). **`ut_` is a storage prefix, not a
+#: statement about origin**, and a wall keyed off it was reading a naming artefact as a security
+#: boundary.
+#:
+#: ⛔⛔ THE TWO QUESTIONS STAY TWO QUESTIONS. `may_open` answers *"IF you see this database"* and
+#: is untouched by this section; C1 answers *"WHICH rows and fields"*. `may_read` below COMPOSES
+#: them — it calls `may_open`, it does not reimplement it — because merging them is how this
+#: codebase got two ideas of who owns a table once already (`user_tables.may_open`'s own wave-20
+#: note). One resolver per question, asked in order.
+
+
+class UnknownTable(LookupError):
+    """No database in this tenant answers to that key.
+
+    ⛔ RAISED, NEVER RETURNED AS AN EMPTY LIST (contract C1). An empty list reads as *"this
+    database is empty"* — indistinguishable from a real empty table, and the caller least able to
+    notice is the one that wanted rows. This repo has shipped that exact silent-empty answer
+    before (`user_tables.all_defs`' own correction note; [[empty-answer-vs-unfinished-answer]]).
+    """
+
+
+class Denied(PermissionError):
+    """This principal may not read this database at all. The IF question, answered by `may_read`."""
+
+
+class Unresolvable(RuntimeError):
+    """The rows exist and cannot be served under this call's constraints — R6's SECOND SENTENCE.
+
+    ⭐ STANDING RULE 1 IS TWO SENTENCES AND THE SECOND IS THE HALF THAT GETS DROPPED: *"if there
+    is lag or it can't be done, you need to explicitly tell me why and recommend a fix"*. So a
+    limit that genuinely cannot be removed is REPORTED with its cause and a recommendation, never
+    silently enforced as a short answer. Carries the same four keys
+    `routes_tables._PID_SCOPE_LIMIT` already puts on the wire, so a route can hand this straight
+    to a client without a second vocabulary ([[one-question-two-normalizers]]).
+    """
+
+    def __init__(self, subject, effect, cause, recommendation):
+        self.subject, self.effect = subject, effect
+        self.cause, self.recommendation = cause, recommendation
+        super().__init__(f"{subject}: {effect}. {cause}. {recommendation}")
+
+    def as_limit(self):
+        """The dict shape `routes_tables` puts in an assembly's `limits` list."""
+        return {"subject": self.subject, "effect": self.effect,
+                "cause": self.cause, "recommendation": self.recommendation}
+
+
+#: Row readers DECLARED by the app layer, keyed by EXACT database key.
+#: `reader(table_key, user, st) -> (fields, rows)`.
+#:
+#: ⛔ WHY A REGISTRY AND NOT AN IMPORT. `core` never imports up (`platform/ARCHITECTURE.md`), and
+#: a registry TOPIC's rows are built by `modules/` + `aios_grid` behind an API-layer pool cache
+#: (`routes_customers._pool_for`), which is two layers above this file. Same idiom `user_tables`
+#: already uses for exactly this reason — `register_connected`, `register_read_through`,
+#: `ROW_HOOKS`: *"`core` never imports up, so the app tells this layer rather than being
+#: interrogated by it."*
+_ROW_SOURCES = {}
+
+#: THE reader for a read-through `ut_*` grid — one reader, because there is one mirror.
+#: `reader(table_key, field_keys, st) -> rows`.
+_MIRROR_READER = None
+
+
+def register_rows(reader, *table_keys):
+    """Declare who reads a NAMED database's rows. Returns the registered key set.
+
+    ⚠ The return value is the registrar's own answer on purpose: a public function whose only
+    caller is a `verify_*.py` file is a feature no user can reach, and this repo has a gate that
+    says so ([[reachable-is-not-the-same-as-built]]). Routing the read door through the write
+    door's return keeps one construction site of the set instead of two.
+    """
+    for key in table_keys:
+        k = str(key or '').strip()
+        if k:
+            _ROW_SOURCES[k] = reader
+    return frozenset(_ROW_SOURCES)
+
+
+def register_mirror(reader):
+    """Declare THE reader for read-through `ut_*` grids (`routes_tables._read_through_rows`)."""
+    global _MIRROR_READER
+    _MIRROR_READER = reader
+    return _MIRROR_READER is not None
+
+
+#: ⛔ `row_sources()` IS DELETED (W36-T24 / owner item 13), AND THE REASON IS THE ONE THIS WAVE
+#: KEEPS FINDING. It returned `frozenset(_ROW_SOURCES)` under a docstring calling itself *"The ONE
+#: list to read"* — and `register_rows` ALREADY returns exactly that, which is the same idiom
+#: `user_tables.register_connected_prefix` uses and the same reason: routing the read door through
+#: the write door's return keeps ONE construction site of the set. A second accessor beside it is a
+#: parallel path with nothing of its own to say, and it shipped with no caller outside `verify_*.py`
+#: — the shape that is whole, correct and unreachable ([[artifact-with-no-importer]]; reported by
+#: the integrator's `web_reachability` pass, `mailbox/A.md` A-43). The registrar's return is the
+#: read: `routes_grid._C1_ROW_SOURCES` is that value, held where it is registered.
+
+
+def _ut():
+    import core.user_tables as user_tables
+    return user_tables
+
+
+def may_read(user, table_key, st=None):
+    """May this principal read `table_key` AT ALL — the IF question, on EVERY database.
+
+    ⛔ COMPOSED, NOT RE-DERIVED, and the order is the whole rule:
+
+      1. an admin reads everything (break-glass — `deps._user_for` hands back a hardcoded master
+         dict on a store outage and it will never carry a `perms` block);
+      2. an EXPLICIT stored `access: false` DENIES, on any database. This is the toggle owner
+         item 11 asks for, and it is a **deny-only overlay**: it may revoke a database the wall
+         below would admit, and it may never grant one that wall refuses;
+      3. a `ut_*` database defers to `user_tables.may_open` — creator, admin, or a `core.shares`
+         grant — UNMODIFIED. W36-T21: *"`may_open` still decides IF the database is visible."*
+      4. anything else is a registry topic and defers to `may_access` above.
+
+    ⛔⛔ WHY ABSENCE MUST NOT DENY ON A `ut_*` KEY, which is the opposite of what leg 4 does.
+    `may_access` reads migrated-and-undeclared as DENY — correct for a topic, because
+    `routes_admin` writes an entry for every governable topic on every save. ⚠ NO `ut_*` ENTRY WAS
+    STORABLE AT ALL UNTIL W36-T22 — `_clean_perms` refused the key with `unenforced_module` — so
+    every record migrated before this wave carries no entry for any of them, and reading that
+    absence as a decision would revoke all ten keychain databases from every migrated account the
+    moment this arms. That is not R6, it is an outage. Leg 3 therefore asks the wall that HAS been
+    answering rather than the marker that has not, and it keeps being right AFTER the flag's
+    deletion: an admin who has never opened the editor for a database has still not decided
+    anything about it.
+
+    ⛔⛔ PASS THE **PUBLIC** RECORD, NOT THE ONE OUT OF `users.json`. Leg 3 needs a username, and a
+    stored record is keyed BY username in that bucket and does not carry one INSIDE it — only
+    `core.users._public(uname, rec)` puts it there, which is what `deps.Session.user` holds. Hand
+    this the raw record and `may_open` gets a `None` viewer and fail-closes, so every `ut_*`
+    database reads as DENIED for an account that can open all of them. It fails in the SAFE
+    direction and is silently wrong, which is the worst pair to debug — it cost two call sites in
+    one afternoon: a gate double, and `routes_admin.get_perms`' own fix for this very outage.
+    """
+    if perms.is_admin(user):
+        return True
+    e = entry(user, table_key)
+    if e is not None and not bool(e.get('access', True)):
+        return False
+    key = str(table_key or '')
+    if key.startswith(_ut().KEY_PREFIX):
+        return bool(_ut().may_open(key, (user or {}).get('username'), False, st=st))
+    return may_access(user, table_key)
+
+
+def wall_declared(user, table_key):
+    """Is a ROW or FIELD narrowing declared for this principal on this database?
+
+    ⛔ THE QUESTION A DOOR ASKS BEFORE SERVING ROWS IT CANNOT SCOPE. `perms.py` warned that a
+    stored `ut_*` wall would be INERT — *"the editor would say DENY, the table routes would keep
+    serving, and nothing anywhere would say so"*. A route that cannot apply C1 must therefore
+    REFUSE for a principal this returns True for, rather than serve the whole database. False for
+    an admin (they bypass the wall entirely) and for any record with no entry, so a door asking
+    this pays nothing and changes nothing for everybody who has no wall.
+    """
+    if perms.is_admin(user):
+        return False
+    e = entry(user, table_key)
+    if not e:
+        return False
+    return bool(e.get('filter')) or bool(e.get('hiddenFields'))
+
+
+def row_scope_applies(user, table_key):
+    """Does a permanent ROW filter narrow this principal on this database?
+
+    ⚠ `wall_declared`'s narrower half, and it exists so a rows-free caller can SKIP building rows
+    it would only need in order to filter them. `routes_tables.scoped_pids` is that caller: its
+    whole point is that the pid set costs no row pass, and paying for one on every database
+    switch — for every account, walled or not — would undo W30-T30 to enforce a rule that applies
+    to almost nobody. Asked here rather than spelled out at the call site, so there is ONE
+    statement of when the row wall bites ([[one-question-two-normalizers]]).
+    """
+    if perms.is_admin(user):
+        return False
+    return bool((entry(user, table_key) or {}).get('filter'))
+
+
+def scoped_table(user, table_key, st=None, ctx=None):
+    """⭐⭐ CONTRACT C1 — the rows of ANY database, already field-stripped and row-filtered for
+    `user`. Registry topic or `ut_*`; there is no third kind and no per-database branch.
+
+        rows = scoped_table(user, 'ut_odoo_invoices')          # a keychain database
+        rows = scoped_table(user, 'customer_data')             # a registry topic
+
+    `user` is a user RECORD (the dict `deps.Session.user` carries), not a username — the whole
+    wall is a pure function of that record. BOTH arguments are positional and REQUIRED: a caller
+    that forgets the principal must not run, because the only thing a defaulted one could mean is
+    "unscoped", which is the widening direction.
+
+    ⛔ FAIL-CLOSED, THREE WAYS, AND EACH IS A DIFFERENT EXCEPTION so a caller can answer with the
+    right status instead of guessing: `UnknownTable` (no such database — never an empty list),
+    `Denied` (the IF question said no), `Unresolvable` (the rows cannot be served and here is
+    why — standing rule 1's second sentence).
+
+    ⚠ NO CAP. A connected source is read THROUGH the mirror in full (standing rule 1); the only
+    thing that stops it is a population that exceeds one materialisation window, and that arrives
+    as `Unresolvable` carrying its cause and a recommendation rather than as a short answer.
+
+    ⭐ E's SCRIPT SANDBOX HOLDS NO SECOND PATH TO THE STORE (wiring W1), which is why this is
+    THE door rather than A door: everything a sandboxed script may read, it reads here, under the
+    CALLING user's scope (R5).
+    """
+    _fields, rows = _scoped(user, table_key, st=st, ctx=ctx)
+    return rows
+
+
+def scoped_fields(user, table_key, st=None):
+    """The COLUMNS of any database this principal may see — C1's other half.
+
+    ⛔ IT IS NOT A CONVENIENCE, IT IS THE SECOND WIRE. `strip_row`'s own note above says it: the
+    field list and the row payload are two different wires, and narrowing one without the other
+    leaves the value sitting where anything can read it. A caller that must render a scoped table
+    needs both, and E cannot read a `ut_*` definition to learn its columns — the sandbox has no
+    second path to the store (W1). So both come from here, off one wall.
+
+    ⚠ On a `ut_*` database this reads the DEFINITION only — the projection, no rows (D-213). On a
+    registry topic it goes through the registered reader, which builds that topic's pool; the
+    pool is cached per scope on the tenant runtime, so it is a cache hit next to `scoped_table`.
+    """
+    fields, _rows = _scoped(user, table_key, st=st, ctx=None, want_rows=False)
+    return fields
+
+
+def _scoped(user, table_key, st=None, ctx=None, want_rows=True):
+    """`(fields, rows)` — ONE evaluator behind both public doors, so they cannot disagree."""
+    key = str(table_key or '').strip()
+    if not key:
+        raise UnknownTable('a database key is required. This door will not guess which database '
+                           'was meant')
+    if not may_read(user, key, st=st):
+        raise Denied(f"this account may not read '{key}'")
+    fields, rows = _read(key, user, st, want_rows)
+    # THE FIELD WALL — a TRANSITIVE closure, so hiding a column also hides every formula computed
+    # FROM it. Resolved ONCE and used for both wires; see `hidden_keys` for why a set difference
+    # is the wrong shape here.
+    hide = hidden_keys(user, key, fields)
+    if not want_rows:
+        return (visible_fields(fields, user, key) if hide else fields), []
+    # THE ROW WALL — `permits()`, so a permanent filter this evaluator cannot answer DENIES
+    # rather than being ignored. Evaluated against the UNSTRIPPED contract on purpose: a
+    # permanent filter may name a column the reader is not allowed to SEE, and dropping the
+    # predicate would widen the read rather than narrow it.
+    rows = apply_row_scope(rows, user, key, fields, ctx)
+    if hide:
+        fields = visible_fields(fields, user, key)
+        rows = [strip_row(r, hide) for r in rows]
+    return fields, rows
+
+
+def _read(table_key, user, st, want_rows=True):
+    """`(fields, rows)` BEFORE the wall — the app layer's reader, or core's own for a `ut_*`."""
+    reader = _ROW_SOURCES.get(table_key)
+    if reader is not None:
+        fields, rows = reader(table_key, user, st)
+        return list(fields or ()), list(rows or ())
+    ut = _ut()
+    if not table_key.startswith(ut.KEY_PREFIX):
+        # ⛔ A TOPIC WITH NO REGISTERED READER IS UNKNOWN, NOT EMPTY. In a process that never
+        # imported the API layer this is the honest answer: nothing here can build that pool.
+        raise UnknownTable(f"no database named '{table_key}' in this workspace, and no reader "
+                           f"is registered for it")
+    return _read_user_table(table_key, st, want_rows)
+
+
+def _read_user_table(table_key, st, want_rows=True):
+    """core's OWN reader for a `ut_*` database. Answers with NO registrar, deliberately.
+
+    ⭐ WHY IT LIVES IN `core` RATHER THAN BEING REGISTERED LIKE THE TOPICS, and it is the same
+    argument that seeds `user_tables._CONNECTED_PREFIXES` rather than registering it: a cold
+    process — E's sandbox subprocess, a worker, a gate — that never imported an API route still
+    owes the right answer for `ut_odoo_invoices`. A registrar-only design would raise there, and
+    the sandbox is exactly such a process.
+
+    ⚠ THE WALL IS ANSWERED ON A PROJECTION AND THE ROWS ARE NOT. `lend_defs` serves definitions
+    without the 28.6 MB of rows (D-213), which is every read this function makes when
+    `want_rows` is false; a projected document RAISES on `rows` rather than answering empty, so
+    the materialised arm below takes the whole read explicitly.
+    """
+    ut = _ut()
+    lent = ut.lend_defs(st)
+    defn = ut.get(table_key, st=lent)
+    if not defn:
+        raise UnknownTable(f"no database named '{table_key}'")
+    fields = [dict(f) for f in (defn.get('fields') or [])]
+    if not want_rows:
+        return fields, []
+    if not ut.materialises(table_key, st=st, defn=defn):
+        # A read-through grid stores no rows here — they live in the mirror, and reading
+        # `defn['rows']` would find an empty dict and serve an EMPTY GRID: correct-looking,
+        # wrong, and silent.
+        if _MIRROR_READER is None:
+            raise Unresolvable(
+                subject='rows', effect='unreadable',
+                cause=(f"'{table_key}' is served read-through from the connector mirror and no "
+                       f'mirror reader is registered in this process'),
+                recommendation=('call `perm_scope.register_mirror(...)` from the app layer before '
+                                'reading a read-through database, or read it through the API'))
+        keys = {f['key'] for f in fields if f.get('key')}
+        return fields, list(_MIRROR_READER(table_key, keys, st) or ())
+    whole = ut.get(table_key, st=st)
+    if whole is None:
+        # Deleted between the wall and here. The same refusal, not an empty table.
+        raise UnknownTable(f"no database named '{table_key}'")
+    field_keys = {f['key'] for f in fields if f.get('key')}
+    rows = []
+    for rid, row in (whole.get('rows') or {}).items():
+        if not str(rid).isdigit():
+            continue
+        r = {k: v for k, v in (row or {}).items() if k in field_keys}
+        r['pid'] = int(rid)
+        rows.append(r)
+    rows.sort(key=lambda r: r['pid'])
+    return fields, rows

platform/core/perms.py

@@ -269,19 +269,29 @@ def tenant_governable_modules(runtime, topics, ut_entries=()):
                    in; this function is the only place the tenant is applied.
     `ut_entries` — this tenant's own `ut_*` databases, in `user_tables.nav_entries` shape.
 
-    Returns `[{'key', 'label', 'enforced'}]`.
-
-    ⛔⛔ `enforced` IS THE HONEST HALF AND IT IS NOT DECORATION. `perm_scope` walls the REGISTRY
-    topics — `grid_assembly` calls `may_access`, `visible_fields` and `apply_row_scope` on every
-    read. It is never consulted for a `ut_*` database: `routes_tables`' visibility is
-    `user_tables.may_open` (creator, admin, or a `core.shares` grant) and there is no module
-    grant in that path at all. So a stored `ut_*` wall would be INERT — the editor would say
-    DENY, the table routes would keep serving, and nothing anywhere would say so. That is the
-    same class as the empty-dropdown defect (wave 26 item 24): a control that answers when it
-    cannot. The database is LISTED, because the owner asked to see every database; the wall is
-    declared unenforced, and `routes_admin::_clean_perms` REFUSES to store one against it rather
-    than accepting a rule nobody applies. Arming `perm_scope` over `ut_*` is a change to
-    `routes_tables`/`user_tables` (lane A's fence) — booked, not faked.
+    Returns `[{'key', 'label'}]`.
+
+    ⭐⭐ WAVE 36 (W36-T22 / CONTRACT C2 / OWNER RULING R6) — **`enforced` IS DELETED, NOT DEFAULTED
+    TO `True`.** This docstring carried the paragraph that booked the work, and it read:
+
+        *"`perm_scope` walls the REGISTRY topics … It is never consulted for a `ut_*` database …
+        So a stored `ut_*` wall would be INERT — the editor would say DENY, the table routes would
+        keep serving, and nothing anywhere would say so … Arming `perm_scope` over `ut_*` is a
+        change to `routes_tables`/`user_tables` — booked, not faked."*
+
+    That change is W36-T21 and it has landed: `perm_scope.scoped_table` is the ONE door to any
+    database's rows, `routes_tables` applies the row filter and the hidden-field closure on every
+    `ut_*` read, and a door that cannot apply them REFUSES rather than serving the lot. So there
+    is no longer a second class of database for the flag to distinguish, and **a flag that is
+    always true is a lie with a green gate behind it** — which is why C2 says DELETE rather than
+    default. Owner item 11, verbatim: *"EVERY database should be able to be toggleable by admin …
+    Everything that is a database with Unique ID, is always going to be configurable with regards
+    to Fields, and Filtration per User. Make this infrastructure robust. And always true when we
+    want to onboard more databases into our App."*
+
+    ⚠ AND THE LIST STAYS DERIVED. Topics come from the registry, `ut_*` from the tenant's own
+    `nav_entries` — so a database created after this wave is governable with no code change and no
+    list edit. That is the half of R6 a flag could never have delivered.
     """
     out = []
     for t in topics or ():
@@ -293,20 +303,23 @@ def tenant_governable_modules(runtime, topics, ut_entries=()):
         # "Odoo products") would have moved one of them and left the permission editor showing the
         # old name with nothing to notice.
         label = (t.get('label') or registry.BY_KEY.get(key, {}).get('label') or key)
-        out.append({'key': key, 'label': label, 'enforced': True})
+        out.append({'key': key, 'label': label})
     seen = {r['key'] for r in out}
     for e in ut_entries or ():
         key = str((e or {}).get('key') or '').strip()
         if not key or key in seen:
             continue
         seen.add(key)
-        out.append({'key': key, 'label': (e.get('label') or key), 'enforced': False})
+        out.append({'key': key, 'label': (e.get('label') or key)})
     return out
 
 
-def enforced_module_keys(modules):
-    """The subset of `governable_modules`' answer a permission block may actually be stored for."""
-    return {m['key'] for m in (modules or ()) if m.get('enforced')}
+#: ⛔ `enforced_module_keys` IS DELETED (W36-T22 / C2), NOT NEUTERED TO "every governable key".
+#: It read `{m['key'] for m in modules if m.get('enforced')}`, so with the flag gone it would
+#: answer the EMPTY SET and `_clean_perms` would refuse every module — and "fix" it by returning
+#: everything is a function whose answer no longer depends on its argument, i.e. the always-true
+#: flag wearing a different costume. Its one caller (`routes_admin._enforced_keys`) goes with it;
+#: what replaces both is the module list itself, which is the only list there is now.
 
 
 def landing_page(user):

platform/core/script_sandbox.py

@@ -0,0 +1,519 @@
+"""core/script_sandbox.py — WAVE 36 (R5 / R10, contract C1): running a tenant's OWN Python.
+
+Owner item 6: *"Add code script as an interface (database View) so a user can build whatever they
+want through the Agent chat interface."* Item 8: *"We need to really guardrail the reach of this
+script. So let's really grill this down."* R10 ruled it SERVER-SIDE PYTHON after the trade was
+stated, so this file is the guardrail, and one engine serves both items.
+
+════════════════════════════════════════════════════════════════════════════════════════════════
+⛔⛔ THE ONE PARAGRAPH TO READ BEFORE CHANGING ANYTHING HERE.
+
+In-process CPython cannot deliver two of this ticket's clauses. An AST allow-list plus a curated
+namespace stops import, file, network and environment access — but it **cannot cap memory and
+cannot interrupt a runaway loop**, because a `while True:` in the same interpreter is not a slow
+request, it is the tenant's ONE FastAPI process gone. So the script runs in a **SUBPROCESS**:
+`resource.setrlimit` for address space and CPU, a hard wall-clock kill from the parent, and the
+allow-list inside. Neither half is sufficient; both are load-bearing.
+
+⭐ AND THE SUBPROCESS RECEIVES **ROWS, NEVER A STORE**. The parent calls C1's `scoped_table` under
+the CALLING user's record and serialises the result; the child imports nothing from this repo and
+holds no credential, no runtime and no store handle. Wiring W1 ("the sandbox has no second store
+path") is then true by CONSTRUCTION rather than by discipline, and it is checkable: the child
+reports its own `sys.modules`, and no `core.*` name may appear in it.
+
+⛔ NEVER A BLACKLIST. Every rule below is an ALLOW-LIST — a set of node types, a set of attribute
+names, a dict of builtins. A blacklist of dangerous spellings is bypassable by construction, and
+the bypass is usually one string method away (`"{0.__class__}".format(x)` performs its attribute
+lookup inside `format`, so there is no `ast.Attribute` node to refuse).
+════════════════════════════════════════════════════════════════════════════════════════════════
+
+The two layers, and they refuse DIFFERENT things on purpose:
+
+  1. `check_source()` — a pure function over source text. Refuses a construct the language offers
+     and this sandbox does not: `import`, `class`, `with`, `async`, `yield`, `global`, and every
+     attribute name outside `ALLOWED_ATTRS`.
+  2. `SANDBOX_BUILTINS` — the names that resolve at all. `__import__`, `open`, `eval`, `exec`,
+     `compile`, `getattr`, `globals`, `vars` and `type` are simply absent, so a source that gets
+     past layer 1 still finds nothing to call.
+
+⚠ THAT DUPLICATION IS DELIBERATE AND IT CHANGES HOW THE GATE MUST BE WRITTEN. `import os` is
+refused twice, so a negative control that drops ONE layer sees the other refuse and reports
+green — the shape that already cost this wave one missed control in `routes_agent_harness`. So
+each layer is tested AT ITS OWN BOUNDARY: `check_source()` is called directly on source strings,
+and `run()` is driven end to end. An NC drops one entry from one frozenset and the matching
+boundary goes red.
+"""
+import ast
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+#: Wall clock, enforced by the PARENT with a kill. The one cap that works on every platform.
+DEFAULT_TIMEOUT_S = 10.0
+
+#: Address space for the child (`RLIMIT_AS`). POSIX only — see `run()`'s `caps` report.
+DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024
+
+#: CPU seconds for the child (`RLIMIT_CPU`). POSIX only. Deliberately above the wall clock: the
+#: wall-clock kill is the primary control and this is the backstop for a child that stops being
+#: reachable. A CPU limit BELOW the timeout would make every slow script look like a CPU refusal.
+DEFAULT_CPU_SECONDS = 15
+
+#: What the script may print, in bytes. `print` is a curated builtin writing to a capped buffer,
+#: and the child's real stdout goes to DEVNULL — so a script cannot fill a pipe, and anything
+#: that escaped far enough to write to fd 1 has nowhere for it to land.
+MAX_STDOUT_BYTES = 64 * 1024
+
+#: The serialised ROW payload handed to the child. ⛔ A REFUSAL, NEVER A TRUNCATION (standing rule
+#: 1): a short answer from a data tool is a wrong answer that looks right. Over this, `run()`
+#: returns a named limit carrying its cause and a recommendation.
+MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
+
+#: The emitted spec. A render spec is a description of a picture; one larger than this is data
+#: pretending to be a description.
+MAX_SPEC_BYTES = 2 * 1024 * 1024
+
+MAX_SOURCE_BYTES = 128 * 1024
+
+
+# ═══════���══════════════════════════════════════════════ LAYER 1 — the AST allow-list ═══════════
+#: Every `ast` node class a script may contain. ⛔ THE ABSENCES ARE THE POLICY: `Import` /
+#: `ImportFrom` (no module reaches the script), `ClassDef` (a class body is a namespace with its
+#: own scoping rules and buys a data script nothing), `With` (a context manager is `__enter__`
+#: by another spelling), `Global` / `Nonlocal` (rebinding the sandbox's own names), and every
+#: `Async*` / `Await` / `Yield` form (this engine is synchronous; a coroutine that is never
+#: awaited is a silent no-op that looks like a working script).
+ALLOWED_NODES = frozenset("""
+Module Expr Assign AugAssign AnnAssign NamedExpr Return Pass Break Continue Delete Assert Raise
+If For While Try TryStar ExceptHandler FunctionDef Lambda arguments arg keyword
+BoolOp BinOp UnaryOp IfExp Dict Set List Tuple Starred Subscript Slice Compare Call Attribute Name
+Constant JoinedStr FormattedValue ListComp SetComp DictComp GeneratorExp comprehension
+Load Store Del
+And Or Not Invert UAdd USub
+Add Sub Mult Div FloorDiv Mod Pow LShift RShift BitOr BitXor BitAnd MatMult
+Eq NotEq Lt LtE Gt GtE Is IsNot In NotIn
+""".split())
+
+#: Every attribute name a script may READ or CALL. ⛔⛔ THIS IS THE LOAD-BEARING SET, and it is
+#: an allow-list of NAMES rather than a refusal of dunders, because the interesting escapes are
+#: ordinary-looking: `f.__globals__` on any function reaches the runner's own module namespace,
+#: `e.__traceback__.tb_frame.f_globals` reaches it from an exception handler, and `().__class__`
+#: reaches `object.__subclasses__`. None of those names is here, and neither is any name this
+#: sandbox has not been asked for.
+#: ⚠ `format` IS ABSENT DELIBERATELY. `"{0.__class__}".format(x)` performs the attribute lookup
+#: INSIDE `str.format`, where no `ast.Attribute` node exists for layer 1 to see. f-strings are
+#: fine — `f"{x.__class__}"` compiles to a real `Attribute` node and is refused.
+ALLOWED_ATTRS = frozenset("""
+append extend insert pop remove clear sort reverse copy count index
+keys values items get setdefault update
+add discard union intersection difference issubset issuperset
+join split rsplit splitlines strip lstrip rstrip lower upper title capitalize casefold
+replace startswith endswith find rfind zfill ljust rjust center partition removeprefix removesuffix
+isdigit isalpha isalnum isspace isupper islower isnumeric
+real imag numerator denominator
+""".split())
+
+
+class Refused(Exception):
+    """A named refusal: `code` for a caller to branch on, `message` for a person to read."""
+
+    def __init__(self, code, message):
+        self.code, self.message = code, message
+        super().__init__(f"{code}: {message}")
+
+
+def _attr_ok(name):
+    """An attribute name passes only if it is on the list AND is not private.
+
+    ⚠ THE SECOND TEST IS NOT A BLACKLIST — it narrows an allow-list that already excludes every
+    private name. It is here so that adding a name to `ALLOWED_ATTRS` cannot open a dunder by
+    accident, which is the one edit a future reader is most likely to make in a hurry.
+    """
+    return name in ALLOWED_ATTRS and not name.startswith("_")
+
+
+def check_source(source):
+    """LAYER 1. Return a `Refused` for source this sandbox will not run, or `None`.
+
+    ⭐ PURE, AND THAT IS WHAT MAKES IT TESTABLE AT ITS OWN BOUNDARY. It reads no file, spawns no
+    process and touches no store, so a gate can hand it a hundred hostile strings for free and an
+    NC can drop one entry from one frozenset and watch exactly this function change its answer.
+    """
+    text = str(source or "")
+    if len(text.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
+        return Refused("source_too_long",
+                       f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of source")
+    try:
+        tree = ast.parse(text)
+    except SyntaxError as exc:
+        return Refused("syntax", f"line {exc.lineno or 0}: {exc.msg}")
+
+    for node in ast.walk(tree):
+        kind = type(node).__name__
+        if kind not in ALLOWED_NODES:
+            return Refused("refused_construct",
+                           f"line {getattr(node, 'lineno', 0)}: this sandbox does not run "
+                           f"{_english(kind)}")
+        if isinstance(node, ast.Attribute) and not _attr_ok(node.attr):
+            return Refused("refused_attribute",
+                           f"line {getattr(node, 'lineno', 0)}: the attribute "
+                           f"'{node.attr}' is not available inside a script view")
+        # ⛔ A NAME may not be private either. `_` prefixed names are the runner's own, and a
+        # script that could bind one could shadow the machinery it runs on top of.
+        if isinstance(node, ast.Name) and node.id.startswith("_"):
+            return Refused("reserved_name",
+                           f"line {getattr(node, 'lineno', 0)}: names starting with an "
+                           f"underscore are reserved by the sandbox")
+        if isinstance(node, (ast.FunctionDef, ast.arg, ast.ExceptHandler)) and str(
+                getattr(node, "name", None) or getattr(node, "arg", "") or "").startswith("_"):
+            return Refused("reserved_name",
+                           f"line {getattr(node, 'lineno', 0)}: names starting with an "
+                           f"underscore are reserved by the sandbox")
+        if isinstance(node, ast.keyword) and str(node.arg or "").startswith("_"):
+            return Refused("reserved_name",
+                           f"line {getattr(node, 'lineno', 0)}: keyword arguments starting with "
+                           f"an underscore are reserved by the sandbox")
+    return None
+
+
+_ENGLISH = {
+    "Import": "an import", "ImportFrom": "an import", "ClassDef": "a class definition",
+    "With": "a with block", "AsyncWith": "a with block", "AsyncFor": "an async loop",
+    "AsyncFunctionDef": "an async function", "Await": "await", "Yield": "yield",
+    "YieldFrom": "yield from", "Global": "a global statement", "Nonlocal": "a nonlocal statement",
+    "Match": "a match statement",
+}
+
+
+def _english(kind):
+    return _ENGLISH.get(kind, f"a {kind} expression")
+
+
+# ══════════════════════════════════════════ LAYER 2 — the namespace, and the child program ═════
+#: The builtins a script may reach, BY NAME. Everything else is a `NameError` in the child.
+#: ⛔ THE ABSENCES, again, are the policy: `__import__` `open` `eval` `exec` `compile` `input`
+#: `getattr` `setattr` `delattr` `globals` `locals` `vars` `dir` `type` `super` `object` `help`
+#: `exit` `breakpoint` `memoryview` `id`. Several are harmless on their own; each one is a step
+#: on a published escape, and none has ever been asked for by a script that shapes rows.
+#: ⚠ THE EXCEPTION CLASSES ARE HERE BECAUSE `try:` IS, and a `try` block whose `except` clause
+#: cannot name what it catches is a construct that reads as supported and is not. They are safe
+#: for the same reason everything else is: `Exception.__subclasses__` needs an attribute this
+#: sandbox does not allow, so a class object in the namespace is a leaf, not a doorway.
+SANDBOX_BUILTIN_NAMES = (
+    "abs all any bool bytes callable chr dict divmod enumerate filter float frozenset hash hex "
+    "int isinstance issubclass iter len list map max min next oct ord pow range repr reversed "
+    "round set slice sorted str sum tuple zip True False None "
+    "Exception ValueError TypeError KeyError IndexError ZeroDivisionError ArithmeticError "
+    "AttributeError StopIteration OverflowError"
+).split()
+
+#: The literal program the child runs. It is TEXT rather than a module because the child must
+#: import nothing from this repo: a module would be found on `sys.path` and would drag `core`
+#: with it, which is exactly the second store path W1 forbids.
+#: ⚠ Every name in here is underscore-prefixed and layer 1 refuses a script from binding one, so
+#: the runner's own machinery cannot be shadowed by the source it executes.
+_RUNNER = r'''
+import json as _json, os as _os, sys as _sys
+
+_pay = _json.loads(open(_sys.argv[1], "r", encoding="utf-8").read())
+_out = {"ok": False, "code": "not_run", "message": "the script did not run",
+        "stdout": "", "spec": None, "caps": {"wallClock": True, "memory": False, "cpu": False}}
+
+# ── the caps this platform can actually apply, reported either way (standing rule 1) ──────────
+try:
+    import resource as _res
+    _mem = int(_pay["memoryBytes"])
+    _res.setrlimit(_res.RLIMIT_AS, (_mem, _mem))
+    _out["caps"]["memory"] = True
+    _cpu = int(_pay["cpuSeconds"])
+    _res.setrlimit(_res.RLIMIT_CPU, (_cpu, _cpu))
+    _out["caps"]["cpu"] = True
+except Exception:
+    # `resource` is POSIX only. The wall-clock kill in the parent still applies, and `caps` says
+    # which of the three held, never a silent partial.
+    pass
+
+_printed = []
+_spent = [0]
+_LIMIT = int(_pay["maxStdout"])
+
+
+def _print(*_a, **_k):
+    _text = (_k.get("sep") or " ").join(str(_x) for _x in _a) + (_k.get("end") or "\n")
+    _room = _LIMIT - _spent[0]
+    if _room > 0:
+        _printed.append(_text[:_room])
+        _spent[0] += len(_text)
+
+
+class _Refusal(Exception):
+    """The SANDBOX refusing, as distinct from the SCRIPT failing.
+
+    Without its own class these arrive as `ValueError`, indistinguishable from a `ValueError` the
+    script raised itself, and the answer then says "refused" about an ordinary bug in the tenant's
+    own code. Two different facts, two different codes.
+    """
+
+
+_emitted = []
+
+
+def _emit(_spec):
+    if not isinstance(_spec, dict):
+        raise _Refusal("emit() takes a view spec, which is a dictionary")
+    if _emitted:
+        raise _Refusal("emit() was already called; a script view emits exactly one view")
+    _emitted.append(_spec)
+
+
+_rows = _pay["rows"]
+_fields = _pay["fields"]
+_bound = _pay["table"]
+
+
+def _scoped_table(_table=None):
+    if _table is not None and str(_table) != _bound:
+        raise _Refusal(
+            "this script view is bound to the database '" + _bound + "' and asked for '"
+            + str(_table) + "'. A script view reads its own database only")
+    return [dict(_r) for _r in _rows]
+
+
+def _scoped_fields():
+    return [dict(_f) for _f in _fields]
+
+
+_ns = {"__builtins__": {_n: __builtins__[_n] if isinstance(__builtins__, dict)
+                        else getattr(__builtins__, _n)
+                        for _n in _pay["builtins"]}}
+_ns["__builtins__"]["print"] = _print
+_ns["print"] = _print
+_ns["emit"] = _emit
+_ns["scoped_table"] = _scoped_table
+_ns["scoped_fields"] = _scoped_fields
+_ns["table"] = _bound
+
+try:
+    exec(compile(_pay["source"], "<script view>", "exec"), _ns)
+    if not _emitted:
+        _out.update(ok=False, code="no_view",
+                    message="the script finished without calling emit(spec)")
+    else:
+        _out.update(ok=True, code="", message="", spec=_emitted[0])
+except _Refusal as _e:
+    _out.update(ok=False, code="refused", message=str(_e)[:400])
+except MemoryError:
+    _out.update(ok=False, code="memory",
+                message="the script used more memory than a script view is allowed")
+except NameError as _e:
+    _out.update(ok=False, code="refused_name",
+                message=str(_e)[:200] + ". A script view may use only the names the sandbox "
+                                        "provides")
+except BaseException as _e:
+    _out.update(ok=False, code="error",
+                message=type(_e).__name__ + ": " + str(_e)[:400])
+
+_out["stdout"] = "".join(_printed)
+_out["truncated"] = _spent[0] > _LIMIT
+# ⭐ THE PROBE: what this child actually had. The PARENT strips it unless it was asked for, so a
+# production run never carries it and a gate can still prove that no `core.*` module and no
+# secret-shaped environment key was ever inside this process.
+# ⚠ SNAPSHOTTED AFTER `exec`, and `os` is imported at the TOP so this list does not depend on
+# dict-literal evaluation order. The first draft called `__import__("os")` inside this very
+# expression, so whether `os` appeared depended on which value Python built first: a probe whose
+# contents move with an unrelated edit is a probe a gate cannot assert against.
+_out["probe"] = {"modules": sorted(_sys.modules), "env": sorted(_os.environ)}
+open(_sys.argv[2], "w", encoding="utf-8").write(_json.dumps(_out, default=str))
+'''
+
+
+def _child_env():
+    """The child's WHOLE environment. An allow-list of two keys, and neither is a credential.
+
+    ⛔ NOT `os.environ.copy()` MINUS SOMETHING. A subtractive environment ships every key nobody
+    thought to name: `HF_TOKEN`, `ODOO_PASSWORD`, `ANTHROPIC_API_KEY` and whatever the next
+    connector adds. The three names below are here because Python will not start on Windows
+    without them; on Linux this returns `{}` and the child runs with no environment at all.
+    """
+    env = {}
+    for name in ("SystemRoot", "SYSTEMROOT", "WINDIR"):
+        if os.environ.get(name):
+            env[name] = os.environ[name]
+    return env
+
+
+def run(source, rows, fields, table_key, *, timeout_s=DEFAULT_TIMEOUT_S,
+        memory_bytes=DEFAULT_MEMORY_BYTES, cpu_seconds=DEFAULT_CPU_SECONDS, probe=False):
+    """Run ONE script over rows that are ALREADY scoped. Returns C3's envelope plus `caps`.
+
+        {ok, code, message, spec, stdout, truncated, ms, caps: {wallClock, memory, cpu}}
+
+    ⛔ THIS FUNCTION NEVER TOUCHES A STORE, AND THAT IS THE POINT: it takes rows. `run_view()`
+    below is the door that fetches them through C1; keeping the two apart is what lets a gate
+    drive the sandbox with no tenant, no runtime and no credential anywhere in the process.
+
+    ⚠ `caps` IS PART OF THE ANSWER, NOT DEBUG OUTPUT. On Windows `resource` does not exist, so
+    the memory and CPU limits are NOT applied and this says so. A caller that reports `ok:true`
+    without reading `caps` is claiming an enforcement that did not happen (standing rule 1).
+    """
+    started = time.monotonic()
+    refusal = check_source(source)
+    if refusal is not None:
+        return _refusal(refusal.code, refusal.message, started)
+
+    payload = {"source": str(source or ""), "rows": rows, "fields": fields,
+               "table": str(table_key or ""), "builtins": SANDBOX_BUILTIN_NAMES,
+               "maxStdout": MAX_STDOUT_BYTES, "memoryBytes": int(memory_bytes),
+               "cpuSeconds": int(cpu_seconds)}
+    try:
+        blob = json.dumps(payload, default=str)
+    except (TypeError, ValueError) as exc:
+        return _refusal("bad_rows", f"these rows cannot be handed to a script ({exc})", started)
+    if len(blob.encode("utf-8", "replace")) > MAX_PAYLOAD_BYTES:
+        # ⛔ REPORTED, NOT TRUNCATED (standing rule 1's second sentence): cause and recommendation,
+        # in the words the owner asked for, rather than a quietly short answer.
+        return _refusal(
+            "payload_too_large",
+            f"this database's rows are larger than the {MAX_PAYLOAD_BYTES // (1024 * 1024)} MB a "
+            f"script view can be handed at once. Narrow the view with a filter, or raise the "
+            f"sandbox payload limit for this deployment", started)
+
+    with tempfile.TemporaryDirectory(prefix="aios-script-") as work:
+        pay_path = Path(work) / "payload.json"
+        res_path = Path(work) / "result.json"
+        pay_path.write_text(blob, encoding="utf-8")
+        # `-I` isolates the interpreter (no PYTHON* env, no user site), `-S` skips site-packages,
+        # and the program arrives on STDIN so there is no file for anything to import it as.
+        # ⛔ `-X utf8` AND AN EXPLICIT `encoding` ARE NOT TIDINESS. Without them this pipe is
+        # encoded with the parent's locale codec, which on this Windows box is cp1252: the runner
+        # text below cannot be represented in it and `subprocess.run` died with
+        # `UnicodeEncodeError` before the child ever started. A sandbox whose behaviour depends on
+        # the operator's locale is a sandbox with two behaviours. `-I` implies `-E`, so
+        # `PYTHONUTF8` in the environment could not have carried this, it has to be a flag.
+        argv = [sys.executable, "-I", "-S", "-X", "utf8", "-", str(pay_path), str(res_path)]
+        try:
+            done = subprocess.run(
+                argv, input=_RUNNER, text=True, encoding="utf-8", errors="replace",
+                cwd=work, env=_child_env(),
+                stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout_s)
+        except subprocess.TimeoutExpired:
+            return _refusal("timeout",
+                            f"the script ran longer than {timeout_s:g} seconds and was stopped",
+                            started)
+        except OSError as exc:
+            return _refusal("no_sandbox",
+                            f"a script view could not be started on this deployment ({exc})",
+                            started)
+
+        if not res_path.is_file():
+            # The child died without writing an answer: an rlimit signal, an OOM kill, or a crash.
+            # ⚠ NAMED BY ITS RETURN CODE rather than reported as a generic failure — a memory kill
+            # and a bug in this file must not read identically to an operator.
+            return _refusal(*_died(done), started)
+        try:
+            out = json.loads(res_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            return _refusal("unreadable", f"the script's answer could not be read ({exc})",
+                            started)
+
+    out["ms"] = int((time.monotonic() - started) * 1000)
+    if out.get("ok"):
+        spec_error = _check_spec(out.get("spec"))
+        if spec_error:
+            out.update(ok=False, code="bad_spec", message=spec_error, spec=None)
+    if not probe:
+        out.pop("probe", None)
+    return out
+
+
+def _died(done):
+    """`(code, message)` for a child that produced no answer."""
+    rc = done.returncode
+    tail = " ".join((done.stderr or "").split())[-300:]
+    if rc in (-9, 137):
+        return "memory", "the script was stopped for using too much memory"
+    if rc in (-24, 152):
+        return "timeout", "the script used more processor time than a script view is allowed"
+    return "crashed", f"the script view engine stopped without an answer{': ' + tail if tail else ''}"
+
+
+def _refusal(code, message, started):
+    return {"ok": False, "code": code, "message": message, "spec": None, "stdout": "",
+            "truncated": False, "ms": int((time.monotonic() - started) * 1000),
+            "caps": {"wallClock": True, "memory": False, "cpu": False}}
+
+
+def _check_spec(spec):
+    """C3: a spec is a DESCRIPTION the client draws. Never HTML, never a script, never a URL.
+
+    ⛔ THE CHECK IS ON THE KEYS, NOT ON THE STRING CONTENTS. Scanning values for `<script>` is a
+    blacklist and would pass `<SCR` + `IPT>`; refusing a spec that carries an `html`, `script`,
+    `src` or `onclick` key refuses the SHAPE that would let a renderer be talked into executing
+    something. The vocabulary of legal `kind`s is the ROUTE's business (W36-T37) — this is the
+    floor every caller gets whether or not the route above it remembers.
+    """
+    if not isinstance(spec, dict):
+        return "the script emitted something that is not a view spec"
+    try:
+        blob = json.dumps(spec)
+    except (TypeError, ValueError):
+        return "the emitted view spec is not something the client can be sent"
+    if len(blob.encode("utf-8", "replace")) > MAX_SPEC_BYTES:
+        return (f"the emitted view spec is over {MAX_SPEC_BYTES // (1024 * 1024)} MB. A view spec "
+                f"describes a picture; it is not where the rows go")
+    banned = {"html", "innerhtml", "script", "src", "srcdoc", "href", "style", "onclick", "onload"}
+    found = sorted(k for k in _keys_of(spec) if str(k).lower() in banned)
+    if found:
+        return (f"a view spec may not carry {', '.join(found)}. The client DRAWS a spec, so a "
+                f"markup or URL key would be a script by another name")
+    return None
+
+
+def _keys_of(value, depth=0):
+    """Every key anywhere in a nested spec. Bounded, so a deep structure cannot spin this."""
+    if depth > 12:
+        return
+    if isinstance(value, dict):
+        for key, sub in value.items():
+            yield key
+            yield from _keys_of(sub, depth + 1)
+    elif isinstance(value, (list, tuple)):
+        for sub in value:
+            yield from _keys_of(sub, depth + 1)
+
+
+# ══════════════════════════════════════════════ THE DOOR — C1 is the ONLY way to a row ═════════
+def run_view(user, table_key, source, st=None, **kw):
+    """Fetch through C1 under `user`'s scope, then run the script over what came back (R5).
+
+    ⭐⭐ THE FETCH HAPPENS IN THE PARENT AND ONLY ROWS CROSS INTO THE CHILD. That is wiring W1
+    made structural: the child has no runtime to ask, no store handle to open and no credential
+    to use, so "a script cannot read what its caller cannot read" is not a rule anybody has to
+    keep — there is no second path for it to be broken through.
+
+    ⛔ C1'S THREE EXCEPTIONS ARE ANSWERED, NEVER SWALLOWED. `UnknownTable`, `Denied` and
+    `Unresolvable` mean three different things to a person; collapsing them into "no rows" is the
+    silent-empty answer C1 was written to make impossible. `Unresolvable.as_limit()` is handed
+    through in the words it was raised with — standing rule 1's second sentence, verbatim.
+    """
+    import core.perm_scope as perm_scope
+
+    key = str(table_key or "")
+    try:
+        rows = perm_scope.scoped_table(user, key, st=st)
+        fields = perm_scope.scoped_fields(user, key, st=st)
+    except perm_scope.UnknownTable as exc:
+        return _refusal("unknown_table", str(exc) or f"there is no database '{key}'",
+                        time.monotonic())
+    except perm_scope.Denied as exc:
+        return _refusal("denied", str(exc) or "this account may not read that database",
+                        time.monotonic())
+    except perm_scope.Unresolvable as exc:
+        out = _refusal("unresolvable", str(exc), time.monotonic())
+        out["limit"] = exc.as_limit()
+        return out
+    return run(source, rows, fields, key, **kw)

platform/core/shares.py

@@ -57,18 +57,26 @@ KINDS = ('view', 'folder', 'database')
 #:     the sentence holds. `require_session` plus the topic's own gate run first, and the
 #:     receiver's row scope and hidden-field closure are applied BEFORE any foreign view is
 #:     merged, so a grant can only narrow-or-equal what that account could already reach.
-#:   * `kind='database'` on a `ut_*` table — **THE SENTENCE IS FALSE AND THIS REGISTRY IS THE
-#:     ONLY WALL.** `routes_admin._PERM_MODULES` is `("customer_data", "product_data")` and
-#:     `_clean_perms` 400s anything else, so no row filter and no hidden field can even be
-#:     DECLARED for a user table; `routes_tables.py` makes zero `perm_scope` calls and passes
-#:     `hidden_keys=frozenset()`. A `database` grant is therefore ALL-OR-NOTHING — every row,
-#:     every column — and an `*` database grant admits every account in the tenant to all of it.
+#:   * `kind='database'` on a `ut_*` table — ⭐⭐ **THE SENTENCE HOLDS HERE TOO NOW, AND THAT IS
+#:     W36-T21 / OWNER RULING R6 (audit S-8, CLOSED).** It did not until wave 36, and the reason
+#:     is worth keeping: `routes_admin._clean_perms` 400'd any key outside
+#:     `("customer_data", "product_data")`, so no row filter and no hidden field could even be
+#:     DECLARED for a user table, `routes_tables.py` made zero `perm_scope` calls, and it passed
+#:     `hidden_keys=frozenset()`. A `database` grant was therefore ALL-OR-NOTHING — every row,
+#:     every column — and this registry was the only wall behind it.
 #:
-#: ⚠ THAT IS A REAL CAPABILITY, DELIBERATELY KEPT, not a hole to plug in passing. What was wrong
-#: was a docstring promising a second wall that does not exist for this kind; scoping user tables
-#: is booked (S-8), not done. `routes_shares.py`'s module docstring says the same thing at the
-#: OTHER door — the audit's fix is "say so at both", and one door saying it is how the next reader
-#: gets the confident half [[one-question-two-normalizers]].
+#: ⭐ WHAT CHANGED: `perm_scope.scoped_table` (contract C1) is the ONE door to any database's
+#: rows. `routes_tables` applies the permanent filter before `pids` is taken and the transitive
+#: hidden-field closure after `workspace_wire`, on EVERY `ut_*` read — the same code that walls
+#: `customer_data` — and a door that cannot apply them REFUSES rather than serving the lot. So a
+#: `database` grant is once again bounded by a second wall: it decides WHETHER an account reaches
+#: the database, and C1 decides WHICH rows and columns it then sees. An `*` grant still admits
+#: every account in the tenant, and each of them still only sees what their own wall allows.
+#:
+#: ⚠ `routes_shares.py`'s module docstring carries the OLD sentence at the other door and is in
+#: no wave-36 fence — the audit's own fix was "say so at both", so one of the two is now stale.
+#: Booked in `mailbox/C.md` (C-14) rather than edited across a fence
+#: [[two-gates-can-assert-opposite-things]].
 EVERYONE = '*'
 
 ROLES = ('view', 'edit')

platform/core/table_store.py

@@ -1,618 +1,746 @@
-"""The generic per-user TABLE WORKSPACE store — the persistence half of the table-page factory.
-
-One durable store key holds one table OBJECT's per-user Airtable-style state:
-
-    {username: {'views':    {view_id: SavedView},
-                'fields':   {field_key: Field},        # notes + custom_ + measure_ strata
-                'overlays': {str(pid): {field_key: value}}}}
-
-`make(table_key)` returns the six operations a table page's host loop needs, closed over that
-key. The Customer table's ops (`modules/customer_data.py`, key 'customer_table_workspace') are
-these exact functions — the logic MOVED here 2026-07-27 so that duplicating the Customer table
-pattern to a new object is a registry row + a config, not a copy of the store plumbing
-(owner directive: the table-page factory).
-
-A LIST (membership/formula semantics) is deliberately a different store from a VIEW
-(presentation/query state) — see modules/customer_data.py's customer_lists key.
-"""
-import core.store as store
-
-#: Wave-9 I17 — the SHARED bucket. Views whose permissions make them visible to anyone but
-#: their creator live here instead of in a personal workspace, under a key that cannot collide
-#: with a username (usernames come from core/users.py and are never dunder-wrapped; `is_shared`
-#: guards it anyway). ONE HOME PER VIEW, never both: a view moved to personal is REMOVED from
-#: here, and a view shared is removed from its creator's workspace. Two homes would mean two
-#: divergent copies the moment either was edited.
-SHARED_KEY = '__shared__'
-
-
-def _may_see(view, viewer, is_admin=False):
-    """Visibility for ONE shared view, fail-closed.
-
-    'collaborative' = everyone who can already open the module (the caller has gated that).
-    'users'         = the named users, plus the creator, plus admins — an admin who could not
-                      see a view could not administer it either.
-    Anything unrecognised returns False rather than defaulting open: an unreadable permission
-    must never widen access ([[aios-permissioning]] — no fail-open defaults).
-    """
-    if not isinstance(view, dict):
-        return False
-    if view.get('createdBy') == viewer or is_admin:
-        return True
-    perms = view.get('permissions') or {}
-    edit = perms.get('edit')
-    if edit == 'collaborative':
-        return True
-    if edit == 'users':
-        return viewer in set(perms.get('users') or ())
-    return False                      # 'personal', absent, or junk
-
-
-def _may_edit(view, viewer, is_admin=False):
-    """Who may WRITE a shared view. Same set as visibility today — the owner's item asks 'who
-    can edit' and lists who 'can have access', i.e. seeing and editing are one grant. Kept as a
-    separate function so they can diverge (a future read-only share) without hunting callers."""
-    return _may_see(view, viewer, is_admin)
-
-
-def _may_administer(view, viewer, is_admin=False):
-    """Who may change a view's PERMISSIONS, or delete it: the creator or an admin ONLY.
-
-    Deliberately narrower than _may_edit. If a collaborator could rewrite `permissions` they
-    could grant themselves sole ownership of somebody else's view, or quietly widen a
-    users-scoped view to everyone — the classic privilege-escalation-by-edit hole.
-    """
-    if not isinstance(view, dict):
-        return False
-    return bool(is_admin) or view.get('createdBy') == viewer
-
-
-def is_shared(view):
-    """A view belongs in the shared bucket when its permissions reach beyond its creator."""
-    return ((view or {}).get('permissions') or {}).get('edit') in ('collaborative', 'users')
-
-
-def source_override_is_empty(payload):
-    """Does this stored definition of a SOURCE (non-custom) column carry any user state?
-
-    A cleared note on an immutable source field returns to the canonical schema instead of
-    leaving a meaningless override row. Custom fields remain even with an empty note — and so
-    does a PRESET field carrying a measure-window override (wave-2 item 8), a DISPLAY-format
-    override (wave-5 item 10), and, since W29-T83, a COLUMN SUMMARY.
-
-    ⛔ EVERY CLAUSE IS A SETTING A USER MADE, and each one omitted is a setting that silently
-    stops surviving a session. `agg` was missing: choosing Average on Customer's `Overdue days`
-    built an override whose only content was that summary, so this rule threw the whole row away
-    on write while the menu went on reading "Summary: Average" from the client's own optimistic
-    copy until the next login — a discarded WRITE wearing the face of a failed read
-    ([[lost-write-looks-like-failed-read]]). Measured on `bac40c2`; a `ut_*` table, which stores
-    its definitions through another door entirely, kept it.
-
-    ⚠ ONE RULE, TWO CALLERS — here and `grid_events`' store-less fallback. Two copies of a
-    discard rule is how one of them keeps a write the other bins ([[one-evaluator-per-question]]).
-    ⚠ A CLEARED summary still drops the row, which is the intent: with nothing else set, the
-    column goes back to whatever the contract declares for it.
-    """
-    payload = payload or {}
-    if payload.get('custom'):
-        return False
-    return (not str(payload.get('note') or '').strip()
-            and not isinstance(payload.get('measure'), dict)
-            and not isinstance(payload.get('format'), dict)
-            and not str(payload.get('agg') or '').strip())
-
-
-def _unique_name(wanted, existing, *, fallback='Untitled', max_len=120):
-    """Allocate one human-facing name inside a store.update transaction.
-
-    Keys/ids remain structural identity.  Names compare case-insensitively after collapsing
-    whitespace, because those variants are indistinguishable in the UI.  This helper belongs
-    in the store layer: allocating from a pre-write snapshot lets two concurrent requests both
-    choose the same free name before either write lands.
-    """
-    limit = max(1, int(max_len))
-
-    def _clean(value):
-        return ' '.join(str(value or '').split())
-
-    base = (_clean(wanted) or _clean(fallback) or 'Untitled')[:limit].rstrip()
-    taken = {_clean(value).casefold() for value in existing if _clean(value)}
-    if base.casefold() not in taken:
-        return base
-    index = 2
-    while True:
-        suffix = f' {index}'
-        stem = base[:max(0, limit - len(suffix))].rstrip()
-        candidate = f'{stem}{suffix}' if stem else str(index)[-limit:]
-        if candidate.casefold() not in taken:
-            return candidate
-        index += 1
-
-
-class TableStore:
-    """The six store operations for one table object's workspace, closed over its store key.
-
-    `st` (wave 18, C3-UT) is the STORE HANDLE — anything exposing `get(name)` /
-    `update(name, fn, flush=)`. Default = `core.store` (tenant #0, every existing caller,
-    zero behaviour change). The API passes the session's `TenantRuntime`, whose accessors
-    apply the tenant prefix / repo binding — which is what makes a user table created by a
-    Nurilab admin land in Nurilab's store instead of Royal's.
-    """
-
-    def __init__(self, table_key, st=None):
-        self.table_key = table_key
-        self._st = st if st is not None else store
-
-    @property
-    def st(self):
-        """The bound store handle — for SIBLING registries (core/shares) that must read the
-        same tenant's buckets this workspace lives in (wave 21, C1)."""
-        return self._st
-
-    def find_view(self, view_id):
-        """`(owner_username, view)` for a view living in ANY personal stratum, else None.
-
-        ⭐ Wave 21 (item 9, C1): the R10 grant registry names bare ids, so projecting a granted
-        view means locating the OWNER's record inside this topic's bucket. Personal strata
-        only — the `__shared__` bucket has its own read path (`shared_views`), and serving one
-        view from two finders is how two copies drift."""
-        vid = str(view_id or '').strip()
-        if not vid:
-            return None
-        try:
-            data = self._st.get(self.table_key) or {}
-        except Exception:
-            return None
-        for username, ws in data.items():
-            if username == SHARED_KEY or not isinstance(ws, dict):
-                continue
-            v = (ws.get('views') or {}).get(vid)
-            if isinstance(v, dict):
-                return str(username), dict(v)
-        return None
-
-    def find_folder(self, folder_id):
-        """`(owner_username, folder_row, {view_id: view})` for a VIEWS folder living in any
-        personal stratum, else None. `find_view`'s sibling, and here for the same reason.
-
-        ⭐ D-37 (wave 20's R10 remainder, closed 2026-08-05): the grant registry accepts kind
-        `folder` and has since wave 20, but only the VIEW kind was ever projected — so "share
-        this folder with Karen" recorded a row, listed under Shared with me, and put nothing on
-        Karen's screen. Projecting a folder means two lookups the view path does not need: WHO
-        owns it, and WHICH views are filed in it. Folder membership lives in the owner's
-        `itemFolders` map (item id -> folder id), never on the view record, so the views are
-        found by asking that map rather than by reading a list off the folder.
-
-        Views only (`folders['views']`): the cohort surface has its own store and its own
-        sharing question, and answering both here would make one function mean two things.
-        """
-        fid = str(folder_id or '').strip()
-        if not fid:
-            return None
-        try:
-            data = self._st.get(self.table_key) or {}
-        except Exception:
-            return None
-        for username, ws in data.items():
-            if username == SHARED_KEY or not isinstance(ws, dict):
-                continue
-            rows = (ws.get('folders') or {}).get('views') or []
-            hit = next((f for f in rows
-                        if isinstance(f, dict) and str(f.get('id') or '') == fid), None)
-            if not hit:
-                continue
-            # ⚠ `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, …}`) —
-            # reading item ids off the top level finds the surface names instead and matches
-            # nothing, so the projection silently returns an EMPTY folder and the feature looks
-            # exactly as broken as it was before the fix. Caught by this change's own gate,
-            # which is the entire argument for writing one.
-            placed = (ws.get('itemFolders') or {}).get('views') or {}
-            views = ws.get('views') or {}
-            inside = {str(vid): dict(v) for vid, v in views.items()
-                      if isinstance(v, dict) and str(placed.get(str(vid)) or '') == fid}
-            return str(username), dict(hit), inside
-        return None
-
-    # ---------------------------------------------------------------- read
-    def workspace(self, username, consume_corrections=True):
-        """One user's durable workspace: always the full three-strata shape."""
-        try:
-            data = self._st.get(self.table_key) or {}
-            ws = data.get(username, {}) or {}
-            # A collision acknowledgement is protocol state, not part of a field definition.
-            # Consume it with the first fresh workspace payload after the correcting write,
-            # then splice a bounded copy into that payload only.  Keeping it out of `fields`
-            # prevents an old request id surviving forever and overriding a later rename.
-            corrections = {}
-            if consume_corrections and ws.get('fieldCorrections'):
-                def _take(current):
-                    current_ws = current.get(username) or {}
-                    pending = current_ws.get('fieldCorrections') or {}
-                    corrections.update({
-                        str(key)[:80]: dict(value)
-                        for key, value in pending.items()
-                        if isinstance(value, dict)
-                    })
-                    current_ws.pop('fieldCorrections', None)
-                    return current
-
-                data = self._st.update(self.table_key, _take, flush='async')
-                ws = (data or {}).get(username, {}) or {}
-        except Exception:
-            ws = {}
-            corrections = {}
-        fields = {
-            key: dict(value) if isinstance(value, dict) else value
-            for key, value in (ws.get('fields') or {}).items()
-        }
-        for key, ack in corrections.items():
-            field = fields.get(key)
-            accepted_label = str(ack.get('label') or '')[:120]
-            requested_label = str(ack.get('labelCorrectedFrom') or '')[:120]
-            correction_id = str(ack.get('labelCorrectionId') or '')[:180]
-            # A newer field write clears/replaces the pending ack in the SAME transaction.
-            # The label check is an extra belt against ever attaching a stale ack to a newer
-            # definition if a future store implementation weakens that ordering.
-            if (isinstance(field, dict) and accepted_label
-                    and str(field.get('label') or '') == accepted_label
-                    and requested_label and correction_id):
-                field['labelCorrectedFrom'] = requested_label
-                field['labelCorrectionId'] = correction_id
-        out = {
-            'views': dict(ws.get('views') or {}),
-            'fields': fields,
-            'overlays': dict(ws.get('overlays') or {}),
-            # wave-8 I11 (C4): folders over the saved views / cohorts sidebars. A FOURTH
-            # stratum rather than a key on each item — see aios_grid.clean_folders for why
-            # (a cohort lives in another store, and filing is an organising act, not part of
-            # what a view is). Absent for every workspace saved before this wave, which is
-            # exactly "no folders yet".
-            'folders': dict(ws.get('folders') or {}),
-            'itemFolders': dict(ws.get('itemFolders') or {}),
-        }
-        # 2026-07-31 (owner item 3): WHERE THE USER LEFT OFF survives a new browser. The
-        # client's localStorage copy wins when present; this is the server's answer for a
-        # fresh profile, which used to fall all the way to the system default view.
-        if ws.get('activeViewId'):
-            out['activeViewId'] = str(ws['activeViewId'])
-        # Wave 2026-08-02 (C-LAYOUT): the per-user record-detail field order. A fifth
-        # stratum, absent until the user first reorders — exactly "default order".
-        if isinstance(ws.get('recordLayout'), dict):
-            out['recordLayout'] = dict(ws['recordLayout'])
-        return out
-
-    # ---------------------------------------------------------------- write
-    def _update(self, username, change):
-        def _up(data):
-            ws = data.setdefault(username, {})
-            ws.setdefault('views', {})
-            ws.setdefault('fields', {})
-            ws.setdefault('overlays', {})
-            ws.setdefault('folders', {})
-            ws.setdefault('itemFolders', {})
-            change(ws)
-            return data
-        # flush='async' (wave-7 W3): this is THE hot path — every autosaved filter tweak,
-        # column note and typed overlay cell lands here inside the component round-trip, and
-        # the historical synchronous hub commit cost seconds per edit. The mutation applies to
-        # the in-process cache (read-your-writes for every subsequent render); the hub write
-        # coalesces in the background. Registry/auth writes elsewhere stay flush='sync'.
-        return self._st.update(self.table_key, _up, flush='async')
-
-    def rename_choice_values(self, username, change):
-        """Apply an arbitrary workspace rewrite (wave 20, item 15 / C-RENAME).
-
-        ⚠ NAMED FOR ITS ONE CALLER RATHER THAN EXPOSED AS A GENERIC `mutate`, deliberately. A
-        public "do anything to the workspace" method is an invitation to put write logic in
-        callers instead of here, and every OTHER method on this class exists precisely because
-        that logic belongs in one place. Renaming a choice is the one operation that must touch
-        three strata AT ONCE — the field's `choices`, the cells in `overlays`, and the views that
-        filter or colour by the old value — inside a SINGLE transaction, because a rename that
-        updated the cells and not the filters would leave a saved view matching nothing.
-
-        `change(ws)` receives the whole workspace with every stratum pre-created (see `_update`).
-        """
-        return self._update(username, change)
-
-    def save_active_view(self, username, view_id):
-        """Remember which view this user last opened (owner item 3, 2026-07-31).
-
-        Presentation state, not authorisation: the READ side re-validates the id against what
-        the caller may actually see, so a stale or foreign id degrades to the default view
-        rather than granting anything. Stored per user like every other stratum.
-        """
-        vid = str(view_id or '').strip()[:120]
-        if not vid or username == SHARED_KEY:
-            return
-
-        def _set(ws):
-            ws['activeViewId'] = vid
-        self._update(username, _set)
-
-    def save_record_layout(self, username, order):
-        """The per-user RECORD-DETAIL field order (wave 2026-08-02, C-LAYOUT).
-
-        Presentation state for ONE surface — the record modal. Deliberately not view config:
-        the owner's ask is per-user, not per-view, and it must never reorder grid columns.
-        The event handler validated keys against the live field set; the wire re-validates at
-        serve time (aios_grid.workspace_wire), so a deleted field cannot outlive itself here.
-        An empty order clears the stratum back to "default order".
-        """
-        if username == SHARED_KEY:
-            return
-        clean, seen = [], set()
-        for key in (order or [])[:200]:
-            key = str(key or '').strip()[:80]
-            if key and key not in seen:
-                seen.add(key)
-                clean.append(key)
-
-        def _set(ws):
-            if clean:
-                ws['recordLayout'] = {'order': clean}
-            else:
-                ws.pop('recordLayout', None)
-
-        self._update(username, _set)
-
-    def save_folders(self, username, folders, item_folders):
-        """Replace the folder stratum wholesale (wave-8 I11).
-
-        Wholesale rather than per-folder because the caller has ALREADY validated the complete
-        picture through aios_grid.clean_folders / clean_item_folders, and those two are
-        interdependent: a placement is only legal while its folder exists, so committing them
-        separately would leave a window where a reader sees an item filed into a folder that is
-        not there yet. One write, one consistent state.
-        """
-        def _set(ws):
-            ws['folders'] = dict(folders or {})
-            ws['itemFolders'] = dict(item_folders or {})
-        self._update(username, _set)
-
-    def save_view_order(self, username, order):
-        """⭐ WAVE-27 item 5 (contract C7) — this user's own ORDER for the views rail.
-
-        Wholesale, like `save_folders` above and for the same reason: the client sends the full
-        list it is looking at, not a delta, because a partial order cannot say where an UNNAMED
-        view went.
-
-        ⛔ PER USER, and it belongs in this stratum rather than on the view records themselves.
-        `aios_grid`'s own folder note argues it out for placements and every word applies: an
-        arrangement is a per-user ORGANISING act, not part of what a view IS — so keeping it out
-        of the view config means duplicating, sharing or exporting a view does not drag one
-        person's rail position along with it. It also means a SHARED view can sit in a different
-        place for each person who can see it, which is the only coherent answer once two people
-        share one view.
-
-        An empty list CLEARS the arrangement (back to server order) rather than storing `[]`.
-        """
-        def _set(ws):
-            clean = []
-            seen = set()
-            for vid in (order or []):
-                vid = str(vid).strip()[:120]
-                if vid and vid not in seen:
-                    seen.add(vid)
-                    clean.append(vid)
-            if clean:
-                ws['viewOrder'] = clean
-            else:
-                ws.pop('viewOrder', None)
-        self._update(username, _set)
-
-    def shared_views(self, viewer, is_admin=False):
-        """Every SHARED view this viewer may see, by id (wave-9 I17).
-
-        Read-only and independent of the viewer's own workspace: the caller merges. Returns
-        only what `_may_see` allows, so a caller cannot accidentally render somebody else's
-        personal view by forgetting to filter.
-        """
-        try:
-            bucket = ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}).get('views') or {}
-        except Exception:
-            return {}
-        return {vid: dict(v) for vid, v in bucket.items()
-                if _may_see(v, viewer, is_admin)}
-
-    def shared_view(self, view_id):
-        """One shared view RAW — no visibility filter. For authorisation decisions only: a
-        caller must know a view exists and who owns it before it can decide whether the actor
-        may touch it. Never hand the result to a renderer without checking `_may_see`."""
-        try:
-            return ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}
-                    ).get('views', {}).get(str(view_id))
-        except Exception:
-            return None
-
-    def save_view(self, username, view, shared=None, reserved_names=(), is_admin=False):
-        """Upsert a SavedView into its ONE home — personal workspace or the shared bucket.
-
-        `shared` defaults to reading the view's own permissions (`is_shared`). Whichever home
-        it lands in, the view is REMOVED from the other, so a view can never exist as two
-        copies that diverge on the next edit.
-
-        ⚠ AUTHORISATION IS THE CALLER'S JOB and must happen BEFORE this is called — this layer
-        moves data and does not know who is asking. `_cl_handle_one` is the wall.
-        """
-        view_id = str((view or {}).get('id') or '').strip()
-        if not view_id:
-            raise ValueError('view id is required')
-        if username == SHARED_KEY:
-            raise ValueError('reserved username')
-        to_shared = is_shared(view) if shared is None else bool(shared)
-        requested = dict(view)
-        accepted = {}
-
-        def _up(data):
-            # View names are tenant-global: every personal workspace plus the shared bucket.
-            # This deliberately includes views the actor cannot see.  The only disclosed fact
-            # is that a display name is already taken, while the categorical "no duplicate
-            # view names" contract remains true when a personal view is later shared.
-            names = list(reserved_names or ())
-            for workspace in data.values():
-                if not isinstance(workspace, dict):
-                    continue
-                names.extend(
-                    value.get('name')
-                    for candidate_id, value in (workspace.get('views') or {}).items()
-                    if candidate_id != view_id and isinstance(value, dict)
-                )
-            payload = dict(requested)
-            payload['name'] = _unique_name(payload.get('name'), names)
-            accepted.clear()
-            accepted.update(payload)
-            if to_shared:
-                bucket = data.setdefault(SHARED_KEY, {})
-                bucket.setdefault('views', {})[view_id] = payload
-                # it may have lived in the creator's workspace before being shared
-                owner = data.get(payload.get('createdBy') or username) or {}
-                (owner.get('views') or {}).pop(view_id, None)
-            else:
-                ws = data.setdefault(username, {})
-                ws.setdefault('views', {})[view_id] = payload
-                (data.get(SHARED_KEY, {}).get('views') or {}).pop(view_id, None)
-            return data
-
-        self._st.update(self.table_key, _up, flush='async')
-        return dict(accepted)
-
-    def delete_view(self, username, view_id):
-        """Delete a custom/list view override. The system all-rows view is guarded by caller.
-
-        Removes from BOTH homes: the caller has already authorised the delete, and leaving a
-        stale copy in the other bucket would resurrect the view on the next read.
-        """
-        vid = str(view_id)
-
-        def _up(data):
-            (data.get(username, {}).get('views') or {}).pop(vid, None)
-            (data.get(SHARED_KEY, {}).get('views') or {}).pop(vid, None)
-            return data
-
-        self._st.update(self.table_key, _up, flush='async')
-
-    def save_field(self, username, field, reserved_names=(), correction_id=None):
-        """Persist a column note or a user-created (custom_/measure_) field definition."""
-        key = str((field or {}).get('key') or '').strip()
-        if not key:
-            raise ValueError('field key is required')
-        requested = dict(field)
-        accepted = {}
-
-        def _save(ws):
-            names = list(reserved_names or ())
-            names.extend(
-                value.get('label')
-                for candidate_key, value in (ws.get('fields') or {}).items()
-                if candidate_key != key and isinstance(value, dict)
-            )
-            payload = dict(requested)
-            payload.pop('labelCorrectedFrom', None)
-            payload.pop('labelCorrectionId', None)
-            requested_label = ' '.join(
-                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
-            payload['label'] = _unique_name(requested_label, names)
-            corrections = ws.setdefault('fieldCorrections', {})
-            corrections.pop(key, None)
-            if payload['label'] != requested_label and correction_id:
-                corrections[key] = {
-                    'label': payload['label'],
-                    'labelCorrectedFrom': requested_label,
-                    'labelCorrectionId': str(correction_id)[:180],
-                }
-            if not corrections:
-                ws.pop('fieldCorrections', None)
-            accepted.clear()
-            accepted.update(payload)
-            if source_override_is_empty(payload):
-                ws['fields'].pop(key, None)
-            else:
-                ws['fields'][key] = payload
-
-        self._update(username, _save)
-        return dict(accepted)
-
-    def duplicate_field(self, username, source_key, new_key, field,
-                        reserved_names=(), correction_id=None):
-        """Clone a user-created field in ONE store transaction (wave-5 item 1): the new
-        definition plus — for `custom_` overlay sources only — every stored cell value under
-        the source key. One transaction, because a def without its values (or values without a
-        def) is exactly the orphan state delete_field exists to prevent, in reverse.
-        The caller validated both keys (same created stratum) and stamped the clone's
-        createdBy; this layer only moves data."""
-        source_key = str(source_key or '').strip()
-        new_key = str(new_key or '').strip()
-        if not source_key or not new_key or source_key == new_key:
-            raise ValueError('duplicate_field needs two distinct keys')
-        requested = dict(field)
-        accepted = {}
-
-        def _dup(ws):
-            names = list(reserved_names or ())
-            names.extend(
-                value.get('label')
-                for candidate_key, value in (ws.get('fields') or {}).items()
-                if candidate_key != new_key and isinstance(value, dict)
-            )
-            payload = dict(requested)
-            payload.pop('labelCorrectedFrom', None)
-            payload.pop('labelCorrectionId', None)
-            requested_label = ' '.join(
-                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
-            payload['label'] = _unique_name(requested_label, names)
-            corrections = ws.setdefault('fieldCorrections', {})
-            corrections.pop(new_key, None)
-            if payload['label'] != requested_label and correction_id:
-                corrections[new_key] = {
-                    'label': payload['label'],
-                    'labelCorrectedFrom': requested_label,
-                    'labelCorrectionId': str(correction_id)[:180],
-                }
-            if not corrections:
-                ws.pop('fieldCorrections', None)
-            accepted.clear()
-            accepted.update(payload)
-            ws['fields'][new_key] = payload
-            if source_key.startswith('custom_'):
-                for row in ws['overlays'].values():
-                    if isinstance(row, dict) and source_key in row:
-                        row[new_key] = row[source_key]
-
-        self._update(username, _dup)
-        return dict(accepted)
-
-    def delete_field(self, username, key):
-        """Delete a USER-CREATED field definition outright (owner gap closed 2026-07-27).
-
-        Only the created strata ever reach here (`custom_` overlay fields, `measure_` formula
-        columns — the caller enforces the prefix). The stored overlay VALUES for the key are
-        scrubbed with it: a deleted column's cells must not linger as orphan data that would
-        silently resurface if the key were ever reused. Views referencing the key self-heal on
-        their next autosave (an unknown colId is dropped) — the rule every stale key rides.
-        """
-        key = str(key or '').strip()
-        if not key:
-            return
-
-        def _drop(ws):
-            ws['fields'].pop(key, None)
-            for row in ws['overlays'].values():
-                if isinstance(row, dict):
-                    row.pop(key, None)
-
-        self._update(username, _drop)
-
-    def patch_overlay(self, username, pid, updates):
-        """Patch only the external editable stratum; never writes to the source system."""
-        clean = dict(updates or {})
-        if not clean:
-            return
-
-        def _patch(ws):
-            ws['overlays'].setdefault(str(int(pid)), {}).update(clean)
-
-        self._update(username, _patch)
-
-
-def make(table_key, st=None):
-    return TableStore(table_key, st=st)
+"""The generic per-user TABLE WORKSPACE store — the persistence half of the table-page factory.
+
+One durable store key holds one table OBJECT's per-user Airtable-style state:
+
+    {username: {'views':    {view_id: SavedView},
+                'fields':   {field_key: Field},        # notes + custom_ + measure_ strata
+                'overlays': {str(pid): {field_key: value}}}}
+
+`make(table_key)` returns the six operations a table page's host loop needs, closed over that
+key. The Customer table's ops (`modules/customer_data.py`, key 'customer_table_workspace') are
+these exact functions — the logic MOVED here 2026-07-27 so that duplicating the Customer table
+pattern to a new object is a registry row + a config, not a copy of the store plumbing
+(owner directive: the table-page factory).
+
+A LIST (membership/formula semantics) is deliberately a different store from a VIEW
+(presentation/query state) — see modules/customer_data.py's customer_lists key.
+"""
+import core.store as store
+
+#: Wave-9 I17 — the SHARED bucket. Views whose permissions make them visible to anyone but
+#: their creator live here instead of in a personal workspace, under a key that cannot collide
+#: with a username (usernames come from core/users.py and are never dunder-wrapped; `is_shared`
+#: guards it anyway). ONE HOME PER VIEW, never both: a view moved to personal is REMOVED from
+#: here, and a view shared is removed from its creator's workspace. Two homes would mean two
+#: divergent copies the moment either was edited.
+SHARED_KEY = '__shared__'
+
+#: ⭐⭐ W36-T25 — THE COLUMN SUMMARY IS THE DATABASE'S, NOT ONE ACCOUNT'S.
+#:
+#: Owner item 1, second half, verbatim: *"When i filter Avi on my computer sum works for the Sales
+#: last 365 days column but not when my colleague filter it — The sum of the field is not showing
+#: at the bottom even when i zoom out. It only works on my screen??"* Measured while scouting it:
+#: `save_field` writes the WHOLE field payload into `data[username]`, so a column summary — which
+#: is a statement about the COLUMN, identical for every reader by construction — was stored once
+#: per account. Set it, and the totals row exists for you and for nobody else. `computeAggs` then
+#: paints no totals row at all for the colleague (`showTotals` is false when no field carries an
+#: `agg`), which is exactly "not showing at the bottom".
+#:
+#: ⛔ ONLY `agg` MOVES, AND THE LINE IS NOT ARBITRARY. Width, column order, the note, the display
+#: format and every `custom_`/`measure_` definition stay per user, because each of those is a
+#: statement about how ONE PERSON reads the column. "Sum this column" is a statement about what
+#: the column MEANS, and two accounts disagreeing about it is the defect, not a preference.
+#:
+#: ⚠ IT LIVES IN THE `__shared__` MEMBER OF THIS SAME BUCKET rather than in
+#: `core/shared_overlay.py`'s `<key>__shared` document, and the reason is transactional: a summary
+#: is written by the same `save_field` call that writes the note beside it, and the two must land
+#: or fail together. `__shared__` is already this store's tenant-wide member (shared VIEWS live
+#: there) and is guarded against colliding with a username by `is_shared` and by `core/users.py`'s
+#: never-dunder rule, so there is no second bucket, no second flush and no second failure mode.
+SHARED_FIELD_KEYS = ('agg',)
+
+
+def _may_see(view, viewer, is_admin=False):
+    """Visibility for ONE shared view, fail-closed.
+
+    'collaborative' = everyone who can already open the module (the caller has gated that).
+    'users'         = the named users, plus the creator, plus admins — an admin who could not
+                      see a view could not administer it either.
+    Anything unrecognised returns False rather than defaulting open: an unreadable permission
+    must never widen access ([[aios-permissioning]] — no fail-open defaults).
+    """
+    if not isinstance(view, dict):
+        return False
+    if view.get('createdBy') == viewer or is_admin:
+        return True
+    perms = view.get('permissions') or {}
+    edit = perms.get('edit')
+    if edit == 'collaborative':
+        return True
+    if edit == 'users':
+        return viewer in set(perms.get('users') or ())
+    return False                      # 'personal', absent, or junk
+
+
+def _may_edit(view, viewer, is_admin=False):
+    """Who may WRITE a shared view. Same set as visibility today — the owner's item asks 'who
+    can edit' and lists who 'can have access', i.e. seeing and editing are one grant. Kept as a
+    separate function so they can diverge (a future read-only share) without hunting callers."""
+    return _may_see(view, viewer, is_admin)
+
+
+def _may_administer(view, viewer, is_admin=False):
+    """Who may change a view's PERMISSIONS, or delete it: the creator or an admin ONLY.
+
+    Deliberately narrower than _may_edit. If a collaborator could rewrite `permissions` they
+    could grant themselves sole ownership of somebody else's view, or quietly widen a
+    users-scoped view to everyone — the classic privilege-escalation-by-edit hole.
+    """
+    if not isinstance(view, dict):
+        return False
+    return bool(is_admin) or view.get('createdBy') == viewer
+
+
+def is_shared(view):
+    """A view belongs in the shared bucket when its permissions reach beyond its creator."""
+    return ((view or {}).get('permissions') or {}).get('edit') in ('collaborative', 'users')
+
+
+def _shared_fields(data):
+    """The tenant-wide field stratum of one workspace document — `{field_key: {'agg': …}}`.
+
+    ⚠ TOTAL AND FAIL-SOFT: a document written before W36-T25 has no `__shared__` member at all,
+    and one written by a future version may have something else in it. Either way this answers an
+    empty mapping rather than raising, because the caller is a READ that must still serve the
+    workspace — a column with no summary is the state every column was in yesterday.
+    """
+    shared = (data or {}).get(SHARED_KEY)
+    fields = (shared or {}).get('fields') if isinstance(shared, dict) else None
+    return fields if isinstance(fields, dict) else {}
+
+
+def split_shared(payload):
+    """`(per_user, shared)` — one field payload divided at the strata boundary.
+
+    ⭐ W36-T25. `shared` carries only `SHARED_FIELD_KEYS` that are actually SET; `per_user` is the
+    payload without them. Split HERE rather than at each write door so the three doors that store
+    a field (`save_field`, `duplicate_field`, and the delete that must clear it) cannot come apart
+    about where a summary lives — which is the whole reason this module exists rather than being
+    copied per topic.
+    """
+    payload = dict(payload or {})
+    shared = {}
+    for key in SHARED_FIELD_KEYS:
+        value = str(payload.pop(key, '') or '').strip()
+        if value:
+            shared[key] = value
+    return payload, shared
+
+
+def source_override_is_empty(payload):
+    """Does this stored definition of a SOURCE (non-custom) column carry any user state?
+
+    A cleared note on an immutable source field returns to the canonical schema instead of
+    leaving a meaningless override row. Custom fields remain even with an empty note — and so
+    does a PRESET field carrying a measure-window override (wave-2 item 8), a DISPLAY-format
+    override (wave-5 item 10), and, since W29-T83, a COLUMN SUMMARY.
+
+    ⛔ EVERY CLAUSE IS A SETTING A USER MADE, and each one omitted is a setting that silently
+    stops surviving a session. `agg` was missing: choosing Average on Customer's `Overdue days`
+    built an override whose only content was that summary, so this rule threw the whole row away
+    on write while the menu went on reading "Summary: Average" from the client's own optimistic
+    copy until the next login — a discarded WRITE wearing the face of a failed read
+    ([[lost-write-looks-like-failed-read]]). Measured on `bac40c2`; a `ut_*` table, which stores
+    its definitions through another door entirely, kept it.
+
+    ⚠ ONE RULE, TWO CALLERS — here and `grid_events`' store-less fallback. Two copies of a
+    discard rule is how one of them keeps a write the other bins ([[one-evaluator-per-question]]).
+    ⚠ A CLEARED summary still drops the row, which is the intent: with nothing else set, the
+    column goes back to whatever the contract declares for it.
+    """
+    payload = payload or {}
+    if payload.get('custom'):
+        return False
+    return (not str(payload.get('note') or '').strip()
+            and not isinstance(payload.get('measure'), dict)
+            and not isinstance(payload.get('format'), dict)
+            and not str(payload.get('agg') or '').strip())
+
+
+def _unique_name(wanted, existing, *, fallback='Untitled', max_len=120):
+    """Allocate one human-facing name inside a store.update transaction.
+
+    Keys/ids remain structural identity.  Names compare case-insensitively after collapsing
+    whitespace, because those variants are indistinguishable in the UI.  This helper belongs
+    in the store layer: allocating from a pre-write snapshot lets two concurrent requests both
+    choose the same free name before either write lands.
+    """
+    limit = max(1, int(max_len))
+
+    def _clean(value):
+        return ' '.join(str(value or '').split())
+
+    base = (_clean(wanted) or _clean(fallback) or 'Untitled')[:limit].rstrip()
+    taken = {_clean(value).casefold() for value in existing if _clean(value)}
+    if base.casefold() not in taken:
+        return base
+    index = 2
+    while True:
+        suffix = f' {index}'
+        stem = base[:max(0, limit - len(suffix))].rstrip()
+        candidate = f'{stem}{suffix}' if stem else str(index)[-limit:]
+        if candidate.casefold() not in taken:
+            return candidate
+        index += 1
+
+
+class TableStore:
+    """The six store operations for one table object's workspace, closed over its store key.
+
+    `st` (wave 18, C3-UT) is the STORE HANDLE — anything exposing `get(name)` /
+    `update(name, fn, flush=)`. Default = `core.store` (tenant #0, every existing caller,
+    zero behaviour change). The API passes the session's `TenantRuntime`, whose accessors
+    apply the tenant prefix / repo binding — which is what makes a user table created by a
+    Nurilab admin land in Nurilab's store instead of Royal's.
+    """
+
+    def __init__(self, table_key, st=None):
+        self.table_key = table_key
+        self._st = st if st is not None else store
+
+    @property
+    def st(self):
+        """The bound store handle — for SIBLING registries (core/shares) that must read the
+        same tenant's buckets this workspace lives in (wave 21, C1)."""
+        return self._st
+
+    def find_view(self, view_id):
+        """`(owner_username, view)` for a view living in ANY personal stratum, else None.
+
+        ⭐ Wave 21 (item 9, C1): the R10 grant registry names bare ids, so projecting a granted
+        view means locating the OWNER's record inside this topic's bucket. Personal strata
+        only — the `__shared__` bucket has its own read path (`shared_views`), and serving one
+        view from two finders is how two copies drift."""
+        vid = str(view_id or '').strip()
+        if not vid:
+            return None
+        try:
+            data = self._st.get(self.table_key) or {}
+        except Exception:
+            return None
+        for username, ws in data.items():
+            if username == SHARED_KEY or not isinstance(ws, dict):
+                continue
+            v = (ws.get('views') or {}).get(vid)
+            if isinstance(v, dict):
+                return str(username), dict(v)
+        return None
+
+    def find_folder(self, folder_id):
+        """`(owner_username, folder_row, {view_id: view})` for a VIEWS folder living in any
+        personal stratum, else None. `find_view`'s sibling, and here for the same reason.
+
+        ⭐ D-37 (wave 20's R10 remainder, closed 2026-08-05): the grant registry accepts kind
+        `folder` and has since wave 20, but only the VIEW kind was ever projected — so "share
+        this folder with Karen" recorded a row, listed under Shared with me, and put nothing on
+        Karen's screen. Projecting a folder means two lookups the view path does not need: WHO
+        owns it, and WHICH views are filed in it. Folder membership lives in the owner's
+        `itemFolders` map (item id -> folder id), never on the view record, so the views are
+        found by asking that map rather than by reading a list off the folder.
+
+        Views only (`folders['views']`): the cohort surface has its own store and its own
+        sharing question, and answering both here would make one function mean two things.
+        """
+        fid = str(folder_id or '').strip()
+        if not fid:
+            return None
+        try:
+            data = self._st.get(self.table_key) or {}
+        except Exception:
+            return None
+        for username, ws in data.items():
+            if username == SHARED_KEY or not isinstance(ws, dict):
+                continue
+            rows = (ws.get('folders') or {}).get('views') or []
+            hit = next((f for f in rows
+                        if isinstance(f, dict) and str(f.get('id') or '') == fid), None)
+            if not hit:
+                continue
+            # ⚠ `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, …}`) —
+            # reading item ids off the top level finds the surface names instead and matches
+            # nothing, so the projection silently returns an EMPTY folder and the feature looks
+            # exactly as broken as it was before the fix. Caught by this change's own gate,
+            # which is the entire argument for writing one.
+            placed = (ws.get('itemFolders') or {}).get('views') or {}
+            views = ws.get('views') or {}
+            inside = {str(vid): dict(v) for vid, v in views.items()
+                      if isinstance(v, dict) and str(placed.get(str(vid)) or '') == fid}
+            return str(username), dict(hit), inside
+        return None
+
+    # ---------------------------------------------------------------- read
+    def workspace(self, username, consume_corrections=True):
+        """One user's durable workspace: always the full three-strata shape."""
+        try:
+            data = self._st.get(self.table_key) or {}
+            ws = data.get(username, {}) or {}
+            # A collision acknowledgement is protocol state, not part of a field definition.
+            # Consume it with the first fresh workspace payload after the correcting write,
+            # then splice a bounded copy into that payload only.  Keeping it out of `fields`
+            # prevents an old request id surviving forever and overriding a later rename.
+            corrections = {}
+            if consume_corrections and ws.get('fieldCorrections'):
+                def _take(current):
+                    current_ws = current.get(username) or {}
+                    pending = current_ws.get('fieldCorrections') or {}
+                    corrections.update({
+                        str(key)[:80]: dict(value)
+                        for key, value in pending.items()
+                        if isinstance(value, dict)
+                    })
+                    current_ws.pop('fieldCorrections', None)
+                    return current
+
+                data = self._st.update(self.table_key, _take, flush='async')
+                ws = (data or {}).get(username, {}) or {}
+        except Exception:
+            data = {}
+            ws = {}
+            corrections = {}
+        fields = {
+            key: dict(value) if isinstance(value, dict) else value
+            for key, value in (ws.get('fields') or {}).items()
+        }
+        # ⭐⭐ W36-T25 — THE TENANT-WIDE COLUMN SUMMARY, MERGED OVER THIS USER'S STRATUM.
+        # ⛔ IT MUST BE ABLE TO CREATE AN ENTRY, not only decorate one, and that is the whole
+        # reason this is a merge rather than a lookup: the colleague who never touched the column
+        # has NO per-user record for it, so a decorate-only pass would have left them with exactly
+        # the blank totals row the owner reported. `aios_grid.workspace_wire` reads `meta['agg']`
+        # off whatever is here, base column or custom one alike.
+        for key, shared in _shared_fields(data).items():
+            agg = str((shared or {}).get('agg') or '').strip()
+            if not agg:
+                continue
+            entry = fields.get(key)
+            fields[key] = {**entry, 'agg': agg} if isinstance(entry, dict) else {'agg': agg}
+        for key, ack in corrections.items():
+            field = fields.get(key)
+            accepted_label = str(ack.get('label') or '')[:120]
+            requested_label = str(ack.get('labelCorrectedFrom') or '')[:120]
+            correction_id = str(ack.get('labelCorrectionId') or '')[:180]
+            # A newer field write clears/replaces the pending ack in the SAME transaction.
+            # The label check is an extra belt against ever attaching a stale ack to a newer
+            # definition if a future store implementation weakens that ordering.
+            if (isinstance(field, dict) and accepted_label
+                    and str(field.get('label') or '') == accepted_label
+                    and requested_label and correction_id):
+                field['labelCorrectedFrom'] = requested_label
+                field['labelCorrectionId'] = correction_id
+        out = {
+            'views': dict(ws.get('views') or {}),
+            'fields': fields,
+            'overlays': dict(ws.get('overlays') or {}),
+            # wave-8 I11 (C4): folders over the saved views / cohorts sidebars. A FOURTH
+            # stratum rather than a key on each item — see aios_grid.clean_folders for why
+            # (a cohort lives in another store, and filing is an organising act, not part of
+            # what a view is). Absent for every workspace saved before this wave, which is
+            # exactly "no folders yet".
+            'folders': dict(ws.get('folders') or {}),
+            'itemFolders': dict(ws.get('itemFolders') or {}),
+        }
+        # 2026-07-31 (owner item 3): WHERE THE USER LEFT OFF survives a new browser. The
+        # client's localStorage copy wins when present; this is the server's answer for a
+        # fresh profile, which used to fall all the way to the system default view.
+        if ws.get('activeViewId'):
+            out['activeViewId'] = str(ws['activeViewId'])
+        # Wave 2026-08-02 (C-LAYOUT): the per-user record-detail field order. A fifth
+        # stratum, absent until the user first reorders — exactly "default order".
+        if isinstance(ws.get('recordLayout'), dict):
+            out['recordLayout'] = dict(ws['recordLayout'])
+        return out
+
+    # ---------------------------------------------------------------- write
+    def _update(self, username, change, shared=None):
+        """Apply `change(ws)` to this user's stratum, and `shared(shared_fields)` to the
+        tenant-wide one, in ONE transaction.
+
+        ⭐ W36-T25 — `shared` IS A SECOND CALLBACK RATHER THAN A SECOND `update`, and that is the
+        whole reason it exists here instead of at the caller. `save_field` writes a note (per
+        user) and a column summary (tenant-wide) from ONE payload; two transactions would let the
+        summary land while the note did not, and the store's own commit is asynchronous, so the
+        window is real rather than theoretical. One `update`, one flush, one failure mode.
+        """
+        def _up(data):
+            ws = data.setdefault(username, {})
+            ws.setdefault('views', {})
+            ws.setdefault('fields', {})
+            ws.setdefault('overlays', {})
+            ws.setdefault('folders', {})
+            ws.setdefault('itemFolders', {})
+            change(ws)
+            if shared is not None:
+                shared(data.setdefault(SHARED_KEY, {}).setdefault('fields', {}))
+            return data
+        # flush='async' (wave-7 W3): this is THE hot path — every autosaved filter tweak,
+        # column note and typed overlay cell lands here inside the component round-trip, and
+        # the historical synchronous hub commit cost seconds per edit. The mutation applies to
+        # the in-process cache (read-your-writes for every subsequent render); the hub write
+        # coalesces in the background. Registry/auth writes elsewhere stay flush='sync'.
+        return self._st.update(self.table_key, _up, flush='async')
+
+    def rename_choice_values(self, username, change):
+        """Apply an arbitrary workspace rewrite (wave 20, item 15 / C-RENAME).
+
+        ⚠ NAMED FOR ITS ONE CALLER RATHER THAN EXPOSED AS A GENERIC `mutate`, deliberately. A
+        public "do anything to the workspace" method is an invitation to put write logic in
+        callers instead of here, and every OTHER method on this class exists precisely because
+        that logic belongs in one place. Renaming a choice is the one operation that must touch
+        three strata AT ONCE — the field's `choices`, the cells in `overlays`, and the views that
+        filter or colour by the old value — inside a SINGLE transaction, because a rename that
+        updated the cells and not the filters would leave a saved view matching nothing.
+
+        `change(ws)` receives the whole workspace with every stratum pre-created (see `_update`).
+        """
+        return self._update(username, change)
+
+    def save_active_view(self, username, view_id):
+        """Remember which view this user last opened (owner item 3, 2026-07-31).
+
+        Presentation state, not authorisation: the READ side re-validates the id against what
+        the caller may actually see, so a stale or foreign id degrades to the default view
+        rather than granting anything. Stored per user like every other stratum.
+        """
+        vid = str(view_id or '').strip()[:120]
+        if not vid or username == SHARED_KEY:
+            return
+
+        def _set(ws):
+            ws['activeViewId'] = vid
+        self._update(username, _set)
+
+    def save_record_layout(self, username, order):
+        """The per-user RECORD-DETAIL field order (wave 2026-08-02, C-LAYOUT).
+
+        Presentation state for ONE surface — the record modal. Deliberately not view config:
+        the owner's ask is per-user, not per-view, and it must never reorder grid columns.
+        The event handler validated keys against the live field set; the wire re-validates at
+        serve time (aios_grid.workspace_wire), so a deleted field cannot outlive itself here.
+        An empty order clears the stratum back to "default order".
+        """
+        if username == SHARED_KEY:
+            return
+        clean, seen = [], set()
+        for key in (order or [])[:200]:
+            key = str(key or '').strip()[:80]
+            if key and key not in seen:
+                seen.add(key)
+                clean.append(key)
+
+        def _set(ws):
+            if clean:
+                ws['recordLayout'] = {'order': clean}
+            else:
+                ws.pop('recordLayout', None)
+
+        self._update(username, _set)
+
+    def save_folders(self, username, folders, item_folders):
+        """Replace the folder stratum wholesale (wave-8 I11).
+
+        Wholesale rather than per-folder because the caller has ALREADY validated the complete
+        picture through aios_grid.clean_folders / clean_item_folders, and those two are
+        interdependent: a placement is only legal while its folder exists, so committing them
+        separately would leave a window where a reader sees an item filed into a folder that is
+        not there yet. One write, one consistent state.
+        """
+        def _set(ws):
+            ws['folders'] = dict(folders or {})
+            ws['itemFolders'] = dict(item_folders or {})
+        self._update(username, _set)
+
+    def save_view_order(self, username, order):
+        """⭐ WAVE-27 item 5 (contract C7) — this user's own ORDER for the views rail.
+
+        Wholesale, like `save_folders` above and for the same reason: the client sends the full
+        list it is looking at, not a delta, because a partial order cannot say where an UNNAMED
+        view went.
+
+        ⛔ PER USER, and it belongs in this stratum rather than on the view records themselves.
+        `aios_grid`'s own folder note argues it out for placements and every word applies: an
+        arrangement is a per-user ORGANISING act, not part of what a view IS — so keeping it out
+        of the view config means duplicating, sharing or exporting a view does not drag one
+        person's rail position along with it. It also means a SHARED view can sit in a different
+        place for each person who can see it, which is the only coherent answer once two people
+        share one view.
+
+        An empty list CLEARS the arrangement (back to server order) rather than storing `[]`.
+        """
+        def _set(ws):
+            clean = []
+            seen = set()
+            for vid in (order or []):
+                vid = str(vid).strip()[:120]
+                if vid and vid not in seen:
+                    seen.add(vid)
+                    clean.append(vid)
+            if clean:
+                ws['viewOrder'] = clean
+            else:
+                ws.pop('viewOrder', None)
+        self._update(username, _set)
+
+    def shared_views(self, viewer, is_admin=False):
+        """Every SHARED view this viewer may see, by id (wave-9 I17).
+
+        Read-only and independent of the viewer's own workspace: the caller merges. Returns
+        only what `_may_see` allows, so a caller cannot accidentally render somebody else's
+        personal view by forgetting to filter.
+        """
+        try:
+            bucket = ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}).get('views') or {}
+        except Exception:
+            return {}
+        return {vid: dict(v) for vid, v in bucket.items()
+                if _may_see(v, viewer, is_admin)}
+
+    def shared_view(self, view_id):
+        """One shared view RAW — no visibility filter. For authorisation decisions only: a
+        caller must know a view exists and who owns it before it can decide whether the actor
+        may touch it. Never hand the result to a renderer without checking `_may_see`."""
+        try:
+            return ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}
+                    ).get('views', {}).get(str(view_id))
+        except Exception:
+            return None
+
+    def save_view(self, username, view, shared=None, reserved_names=(), is_admin=False):
+        """Upsert a SavedView into its ONE home — personal workspace or the shared bucket.
+
+        `shared` defaults to reading the view's own permissions (`is_shared`). Whichever home
+        it lands in, the view is REMOVED from the other, so a view can never exist as two
+        copies that diverge on the next edit.
+
+        ⚠ AUTHORISATION IS THE CALLER'S JOB and must happen BEFORE this is called — this layer
+        moves data and does not know who is asking. `_cl_handle_one` is the wall.
+        """
+        view_id = str((view or {}).get('id') or '').strip()
+        if not view_id:
+            raise ValueError('view id is required')
+        if username == SHARED_KEY:
+            raise ValueError('reserved username')
+        to_shared = is_shared(view) if shared is None else bool(shared)
+        requested = dict(view)
+        accepted = {}
+
+        def _up(data):
+            # View names are tenant-global: every personal workspace plus the shared bucket.
+            # This deliberately includes views the actor cannot see.  The only disclosed fact
+            # is that a display name is already taken, while the categorical "no duplicate
+            # view names" contract remains true when a personal view is later shared.
+            names = list(reserved_names or ())
+            for workspace in data.values():
+                if not isinstance(workspace, dict):
+                    continue
+                names.extend(
+                    value.get('name')
+                    for candidate_id, value in (workspace.get('views') or {}).items()
+                    if candidate_id != view_id and isinstance(value, dict)
+                )
+            payload = dict(requested)
+            payload['name'] = _unique_name(payload.get('name'), names)
+            accepted.clear()
+            accepted.update(payload)
+            if to_shared:
+                bucket = data.setdefault(SHARED_KEY, {})
+                bucket.setdefault('views', {})[view_id] = payload
+                # it may have lived in the creator's workspace before being shared
+                owner = data.get(payload.get('createdBy') or username) or {}
+                (owner.get('views') or {}).pop(view_id, None)
+            else:
+                ws = data.setdefault(username, {})
+                ws.setdefault('views', {})[view_id] = payload
+                (data.get(SHARED_KEY, {}).get('views') or {}).pop(view_id, None)
+            return data
+
+        self._st.update(self.table_key, _up, flush='async')
+        return dict(accepted)
+
+    def delete_view(self, username, view_id):
+        """Delete a custom/list view override. The system all-rows view is guarded by caller.
+
+        Removes from BOTH homes: the caller has already authorised the delete, and leaving a
+        stale copy in the other bucket would resurrect the view on the next read.
+        """
+        vid = str(view_id)
+
+        def _up(data):
+            (data.get(username, {}).get('views') or {}).pop(vid, None)
+            (data.get(SHARED_KEY, {}).get('views') or {}).pop(vid, None)
+            return data
+
+        self._st.update(self.table_key, _up, flush='async')
+
+    def save_field(self, username, field, reserved_names=(), correction_id=None):
+        """Persist a column note or a user-created (custom_/measure_) field definition.
+
+        ⭐⭐ W36-T25 — THE COLUMN SUMMARY GOES TO THE TENANT-WIDE STRATUM, EVERYTHING ELSE STAYS
+        PER USER, in ONE transaction. See `SHARED_FIELD_KEYS` above for the owner's report and for
+        why the line falls where it does. The returned `accepted` still carries the summary: the
+        caller is echoing back the field it just stored, and dropping a key from that echo would
+        tell the client its write was refused ([[read-path-cannot-witness-write-path]]).
+        """
+        key = str((field or {}).get('key') or '').strip()
+        if not key:
+            raise ValueError('field key is required')
+        requested = dict(field)
+        accepted = {}
+
+        def _save(ws):
+            names = list(reserved_names or ())
+            names.extend(
+                value.get('label')
+                for candidate_key, value in (ws.get('fields') or {}).items()
+                if candidate_key != key and isinstance(value, dict)
+            )
+            payload = dict(requested)
+            payload.pop('labelCorrectedFrom', None)
+            payload.pop('labelCorrectionId', None)
+            requested_label = ' '.join(
+                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
+            payload['label'] = _unique_name(requested_label, names)
+            corrections = ws.setdefault('fieldCorrections', {})
+            corrections.pop(key, None)
+            if payload['label'] != requested_label and correction_id:
+                corrections[key] = {
+                    'label': payload['label'],
+                    'labelCorrectedFrom': requested_label,
+                    'labelCorrectionId': str(correction_id)[:180],
+                }
+            if not corrections:
+                ws.pop('fieldCorrections', None)
+            accepted.clear()
+            accepted.update(payload)
+            # ⭐⭐ W36-T25 — SPLIT AFTER the label allocation and the correction bookkeeping, so
+            # both still see the whole payload, and BEFORE the per-user write.
+            mine, shared_now = split_shared(payload)
+            shared_write.clear()
+            shared_write.update(shared_now)
+            # ⚠ EMPTINESS IS JUDGED ON THE PER-USER HALF. A source column whose ONLY state was a
+            # summary now has no per-user state at all, and leaving an `{}` override behind is the
+            # meaningless row `source_override_is_empty` exists to prevent.
+            if source_override_is_empty(mine):
+                ws['fields'].pop(key, None)
+            else:
+                ws['fields'][key] = mine
+
+        shared_write = {}
+
+        def _share(shared_fields):
+            # ⛔ A CLEARED SUMMARY MUST REMOVE THE ROW, not leave an empty one: `workspace` treats
+            # any entry it finds as a live tenant-wide summary, so an `{'agg': ''}` husk would be
+            # skipped today and become a resurrection hazard the moment the read grows a second
+            # shared key. Absence is the only honest spelling of "nobody set one".
+            if shared_write:
+                shared_fields[key] = {**(shared_fields.get(key) or {}), **shared_write}
+            else:
+                shared_fields.pop(key, None)
+
+        self._update(username, _save, shared=_share)
+        return dict(accepted)
+
+    def duplicate_field(self, username, source_key, new_key, field,
+                        reserved_names=(), correction_id=None):
+        """Clone a user-created field in ONE store transaction (wave-5 item 1): the new
+        definition plus — for `custom_` overlay sources only — every stored cell value under
+        the source key. One transaction, because a def without its values (or values without a
+        def) is exactly the orphan state delete_field exists to prevent, in reverse.
+        The caller validated both keys (same created stratum) and stamped the clone's
+        createdBy; this layer only moves data."""
+        source_key = str(source_key or '').strip()
+        new_key = str(new_key or '').strip()
+        if not source_key or not new_key or source_key == new_key:
+            raise ValueError('duplicate_field needs two distinct keys')
+        requested = dict(field)
+        accepted = {}
+
+        def _dup(ws):
+            names = list(reserved_names or ())
+            names.extend(
+                value.get('label')
+                for candidate_key, value in (ws.get('fields') or {}).items()
+                if candidate_key != new_key and isinstance(value, dict)
+            )
+            payload = dict(requested)
+            payload.pop('labelCorrectedFrom', None)
+            payload.pop('labelCorrectionId', None)
+            requested_label = ' '.join(
+                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
+            payload['label'] = _unique_name(requested_label, names)
+            corrections = ws.setdefault('fieldCorrections', {})
+            corrections.pop(new_key, None)
+            if payload['label'] != requested_label and correction_id:
+                corrections[new_key] = {
+                    'label': payload['label'],
+                    'labelCorrectedFrom': requested_label,
+                    'labelCorrectionId': str(correction_id)[:180],
+                }
+            if not corrections:
+                ws.pop('fieldCorrections', None)
+            accepted.clear()
+            accepted.update(payload)
+            # ⭐ W36-T25: a CLONE carries the original's summary, and a summary is the database's
+            # (see `SHARED_FIELD_KEYS`). Storing it per user here would give the clone a different
+            # residency from every other column — one door out of three disagreeing about where a
+            # thing lives is how `save_field` and this function drift.
+            mine, shared_now = split_shared(payload)
+            shared_write.clear()
+            shared_write.update(shared_now)
+            ws['fields'][new_key] = mine
+            if source_key.startswith('custom_'):
+                for row in ws['overlays'].values():
+                    if isinstance(row, dict) and source_key in row:
+                        row[new_key] = row[source_key]
+
+        shared_write = {}
+
+        def _share(shared_fields):
+            if shared_write:
+                shared_fields[new_key] = {**(shared_fields.get(new_key) or {}), **shared_write}
+            else:
+                shared_fields.pop(new_key, None)
+
+        self._update(username, _dup, shared=_share)
+        return dict(accepted)
+
+    def delete_field(self, username, key):
+        """Delete a USER-CREATED field definition outright (owner gap closed 2026-07-27).
+
+        Only the created strata ever reach here (`custom_` overlay fields, `measure_` formula
+        columns — the caller enforces the prefix). The stored overlay VALUES for the key are
+        scrubbed with it: a deleted column's cells must not linger as orphan data that would
+        silently resurface if the key were ever reused. Views referencing the key self-heal on
+        their next autosave (an unknown colId is dropped) — the rule every stale key rides.
+
+        ⭐⭐ W36-T25 — AND THE TENANT-WIDE SUMMARY GOES WITH IT, for exactly the reason the
+        paragraph above gives about cells: an orphan `agg` under a deleted key is state nobody can
+        see and nobody can clear, and it would attach itself to the next column that happens to
+        take the key back. ⚠ This is the ONE stratum a per-user delete may reach across accounts,
+        and it is safe because the summary was never this user's to begin with — deleting the
+        COLUMN is a tenant-wide act already.
+        """
+        key = str(key or '').strip()
+        if not key:
+            return
+
+        def _drop(ws):
+            ws['fields'].pop(key, None)
+            for row in ws['overlays'].values():
+                if isinstance(row, dict):
+                    row.pop(key, None)
+
+        self._update(username, _drop, shared=lambda shared_fields: shared_fields.pop(key, None))
+
+    def patch_overlay(self, username, pid, updates):
+        """Patch only the external editable stratum; never writes to the source system."""
+        clean = dict(updates or {})
+        if not clean:
+            return
+
+        def _patch(ws):
+            ws['overlays'].setdefault(str(int(pid)), {}).update(clean)
+
+        self._update(username, _patch)
+
+
+def make(table_key, st=None):
+    return TableStore(table_key, st=st)

platform/harness/meta_store.py

@@ -1,521 +1,521 @@
-"""meta_store.py — the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
-
-    python platform/harness/meta_store.py --sync                 pull into tenant #0's mirror
-    python platform/harness/meta_store.py --sync --tenant gtmlab
-    python platform/harness/meta_store.py --status               what is in the mirror now
-
-⛔ WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
-hardwired to XML-RPC — it does `import core.odoo as O` and speaks `search_read` — so no amount of
-spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
-per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
-delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
-store with two loaders, not two stores.**
-
-⭐ THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
-the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
-`XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
-`Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
-different first hop.
-
-⚠ EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
-carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
-  Ad Account 45 · Campaign 35 · Ad Set 54 · Ad 36 · Creative 58 · Insights 57
-⛔ AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
-came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
-nothing going red — which is exactly the "do not drop any column" instruction, broken silently.
-The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
-
-⚠ `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
-answers `403 (#200) Requires business_management permission`, which this token does not carry. One
-column of 285. R6's second sentence — a limit that cannot be removed gets stated with its cause.
-
-⛔ IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
-larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
-(W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
-"""
-import argparse
-import json
-import os
-import sys
-import time
-import urllib.error
-import urllib.parse
-import urllib.request
-from pathlib import Path
-
-_HERE = Path(__file__).resolve().parent
-if str(_HERE.parent) not in sys.path:
-    sys.path.insert(0, str(_HERE.parent))
-
-from harness import datastore                                    # noqa: E402
-
-GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
-GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
-
-#: Numeric columns, by name. Everything else is VARCHAR — including ids (see the header) and
-#: including anything Graph returns as a nested object, which is stored as compact JSON text.
-_INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
-        "inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
-        "account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
-        "min_daily_budget", "min_campaign_group_spend_cap"}
-_DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
-        "inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
-        "daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
-        "daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
-        "lifetime_spend_cap", "lifetime_imps"}
-
-#: ⭐ THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
-#: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
-#: the grid links in `meta_relational`.
-ACCOUNT_FIELDS = (
-    "account_id account_status age amount_spent balance business_city business_country_code "
-    "business_name business_state business_street business_street2 business_zip capabilities "
-    "created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
-    "has_migrated_permissions id io_number is_attribution_spec_system_default "
-    "is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
-    "is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
-    "name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
-    "timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
-).split()
-
-CAMPAIGN_FIELDS = (
-    "account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
-    "campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
-    "created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
-    "last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
-    "promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
-    "special_ad_category special_ad_category_country spend_cap start_time status stop_time "
-    "topline_id updated_time"
-).split()
-
-ADSET_FIELDS = (
-    "account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
-    "bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
-    "campaign_active_time campaign_attribution campaign_id configured_status created_time "
-    "creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
-    "effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
-    "issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
-    "lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
-    "optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
-    "rf_prediction_id source_adset source_adset_id start_time status targeting "
-    "targeting_optimization_types time_based_ad_rotation_id_blocks "
-    "time_based_ad_rotation_intervals updated_time use_new_app_click"
-).split()
-
-AD_FIELDS = (
-    "account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
-    "adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
-    "conversion_domain created_time creative demolink_hash display_sequence effective_status "
-    "engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
-    "preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
-    "tracking_and_conversion_with_defaults tracking_specs updated_time"
-).split()
-
-CREATIVE_FIELDS = (
-    "account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
-    "branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
-    "category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
-    "destination_set_id dynamic_ad_voice effective_authorization_category "
-    "effective_instagram_media_id effective_object_story_id enable_direct_install "
-    "enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
-    "instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
-    "link_deep_link_url link_destination_display_url link_og_id link_url "
-    "messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
-    "object_type object_url place_page_set_id platform_customizations playable_asset_id "
-    "portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
-    "template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
-    "use_page_actor_override video_id"
-).split()
-
-INSIGHT_FIELDS = (
-    "account_currency account_id account_name action_values actions ad_id ad_name adset_id "
-    "adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
-    "clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
-    "cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
-    "date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
-    "impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
-    "optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
-    "social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
-    "video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
-    "video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
-    "video_play_actions video_thruplay_watched_actions website_purchase_roas"
-).split()
-
-#: table -> (graph edge on the account | None, measured fields, parent column)
-SPECS = {
-    "meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
-    "meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
-    "meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
-    "meta_ads": ("ads", AD_FIELDS, "adset_id"),
-    "meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
-}
-
-#: The daily Insights grain (R2). One row per (ad, day) — the id is synthesised because Insights
-#: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
-INSIGHTS_TABLE = "meta_insights_daily"
-INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
-
-#: ⛔ INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
-#: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
-#: — Graph's way of saying the synchronous query is too heavy (the async report-run API is the
-#: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
-#: page 25 answer 200. So the window is walked in slices with every column intact:
-#:   57 fields · ad level · 7d · limit 25   -> 200, 25 rows
-#:   57 fields · account level · 7d          -> 200, 7 rows
-#: ⚠ Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over —
-#: it drops columns R2 requires, and it does so invisibly.
-INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
-INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
-INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
-
-
-def _slices(days, size):
-    """[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
-    from datetime import date, timedelta
-    end = date.today()
-    start = end - timedelta(days=max(1, days) - 1)
-    out, cur = [], start
-    while cur <= end:
-        stop = min(cur + timedelta(days=max(1, size) - 1), end)
-        out.append((cur.isoformat(), stop.isoformat()))
-        cur = stop + timedelta(days=1)
-    return out
-
-#: ⚠ A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
-#: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
-#: not a row cap on a connected source (R6 forbids that) — it is a runaway guard, and reaching it
-#: is reported as a problem, never absorbed.
-MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
-PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
-
-
-class MetaError(RuntimeError):
-    """A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
-
-
-def token():
-    """The Meta token from the environment or gitignored `platform/.env`; "" when absent.
-
-    ⚠ Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
-    `platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
-    (`core` never imports up). Fifteen lines is the price of that boundary.
-    """
-    tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
-    if tok:
-        return tok.strip()
-    env = _HERE.parent / ".env"
-    if env.exists():
-        for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
-            if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
-                _, _, v = line.partition("=")
-                return v.strip().strip('"').strip("'")
-    return ""
-
-
-def _get(path, tok, **params):
-    params["access_token"] = tok
-    url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
-    req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
-    try:
-        with urllib.request.urlopen(req, timeout=120) as r:
-            return json.loads(r.read().decode("utf-8", "replace"))
-    except urllib.error.HTTPError as e:
-        try:
-            msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
-                   ).get("message") or ""
-        except Exception:
-            msg = ""
-        raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
-    except Exception as e:
-        raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
-
-
-#: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
-#: why it cannot be treated as "the server is broken, give up".
-_TOO_MUCH = "reduce the amount of data"
-
-#: ⛔ THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
-#: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
-#: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" — the
-#: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
-#: ⚠ It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
-#: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
-#: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
-_RATE_LIMITED = "too many calls"
-_RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
-_RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
-
-
-def _walk(path, tok, log, **params):
-    """Every page of an edge, paged by CURSOR under our own parameters.
-
-    ⛔ IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
-    first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
-    you're asking for"**, the retry at limit=25 succeeds — and then `next` carries the ORIGINAL
-    limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
-    Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
-
-    ⭐ It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
-    silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
-    every column per row.
-
-    -> (rows, hit_page_cap)
-    """
-    out, pages = [], 0
-    limit = int(params.pop("limit", None) or PAGE)
-    after, waited = None, 0
-    while True:
-        call = dict(params, limit=limit)
-        if after:
-            call["after"] = after
-        try:
-            body = _get(path, tok, **call)
-        except MetaError as e:
-            if _TOO_MUCH in str(e) and limit > 5:
-                limit = max(5, limit // 4)
-                log(f"    page too heavy for /{path} - retrying at limit={limit} "
-                    f"(a payload ceiling, not a row cap; every column is still asked for)")
-                continue
-            if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
-                waited += 1
-                log(f"    rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
-                    f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
-                time.sleep(_RATE_WAIT)
-                continue
-            if _RATE_LIMITED in str(e).lower():
-                log(f"    !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
-                    f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
-                    f"limit is per ad account and persists for minutes. Fix: re-run "
-                    f"`--sync --only <table>` later; the upsert is idempotent.")
-                return out, True
-            raise
-        out.extend(body.get("data") or [])
-        pages += 1
-        after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
-        has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
-        if not has_next:
-            return out, False
-        if pages >= MAX_PAGES:
-            log(f"    !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
-                f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
-                f"window with META_INSIGHTS_DAYS.")
-            return out, True
-
-
-def _cell(value):
-    """One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
-    being dropped: R2 says every field the API returns, and `targeting` is a field."""
-    if value is None or isinstance(value, (str, int, float, bool)):
-        return value
-    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
-
-
-def _coltype(name, rows=None):
-    """The DuckDB type for one column — decided by the DATA when there is data, by the name only
-    as a fallback.
-
-    ⛔ THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
-    `cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
-    action-type objects** on the Insights edge:
-        [{"action_type":"outbound_click","value":"1.459854"}]
-    Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
-    '[{...}]' to DOUBLE` — after five entity tables had already been written, so the sync looked
-    like it worked and then blew up on the last table.
-    ⭐ Same principle the field CATALOG is built on, applied one layer down: **ask the response,
-    do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
-    that is what `_cell` stores; anything else falls back to the measured name hints.
-    """
-    if rows:
-        seen, kinds = 0, set()
-        for r in rows:
-            v = r.get(name)
-            if v is None or v == "":
-                continue
-            kinds.add("json" if isinstance(v, (list, dict)) else
-                      "bool" if isinstance(v, bool) else
-                      "int" if isinstance(v, int) else
-                      "float" if isinstance(v, float) else "str")
-            seen += 1
-            if seen >= 200:
-                break
-        if kinds:
-            if "json" in kinds or "str" in kinds:
-                return "VARCHAR"                              # a JSON blob, or a numeric STRING
-            if kinds <= {"int", "bool"}:
-                return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
-            return "DOUBLE"
-    if name in _INT:
-        return "BIGINT"
-    if name in _DBL:
-        return "DOUBLE"
-    return "VARCHAR"                                          # ids included — see the header
-
-
-def _ensure(con, table, fields, rows=None):
-    """Create or widen the table, with every column typed from `rows` when they are available.
-
-    ⚠ AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
-    column in place, and this table is DERIVED data that can be re-pulled in minutes — so a type
-    disagreement drops and recreates rather than limping on with a column that refuses every
-    insert. The alternative is a mirror that is permanently unwritable for one bad guess.
-    """
-    want = {f: _coltype(f, rows) for f in fields}
-    have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
-    if have:
-        clash = [f for f, ty in want.items() if f in have and have[f] != ty
-                 and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
-        if clash:
-            con.execute(f"DROP TABLE {table}")
-            have = {}
-    if not have:
-        cols = ", ".join(f"{f} {want[f]}" for f in fields)
-        con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
-                    if "id" not in fields else
-                    f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
-        return
-    for f in fields:
-        if f not in have:
-            con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
-
-
-def _upsert(con, table, fields, rows):
-    """Delete-then-insert by id — the same idempotence `datastore._upsert` gives the Odoo half, so
-    a re-sync updates in place and can never append a second copy of the same object."""
-    if not rows:
-        return 0
-    cols = list(fields)
-    ids = [str(r.get("id") or "") for r in rows]
-    q = ",".join("?" for _ in ids)
-    con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
-    con.executemany(
-        f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
-        [[_cell(r.get(c)) for c in cols] for r in rows])
-    return len(rows)
-
-
-def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
-    """Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
-
-    Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
-    exactly as `odoo_relational.refresh` is.
-    """
-    tok = tok or token()
-    # ⛔ THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME — and the difference cost a
-    # live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
-    # `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
-    # imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
-    # that trips the per-ad-account rate limit and never finishes. The comment beside that call
-    # claimed a short window the code could not deliver.
-    # ⭐ The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
-    # makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
-    days = int(insights_days or INSIGHTS_DAYS)
-    report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
-    if not tok:
-        report["problems"].append(
-            "META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
-            "was pulled. This is a missing CREDENTIAL, not a missing capability.")
-        return report
-
-    path = datastore.path_for(tenant_key)
-    if Path(datastore.DB_PATH) != Path(path):
-        datastore.use_path(path)
-    con = datastore.connect()
-    log(f"  mirror: {Path(path).name}")
-
-    accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
-    report["accounts"] = [a.get("id") for a in accts]
-    if not accts:
-        report["problems"].append("the token reaches no ad accounts")
-        return report
-
-    # ── the five entity levels ────────────────────────────────────────────────────────────────
-    for table, (edge, fields, _parent) in SPECS.items():
-        rows, capped = [], False
-        for acct in accts:
-            aid = acct["id"]
-            if edge is None:
-                rows.append(_get(aid, tok, fields=",".join(fields)))
-            else:
-                got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
-                rows.extend(got)
-                capped = capped or hit
-        _ensure(con, table, fields, rows)
-        n = _upsert(con, table, fields, rows)
-        total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
-        report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
-        log(f"  {table:<20} pulled {n:>6}   mirror total {total:>6}"
-            + ("   !! PAGE CAP HIT" if capped else ""))
-        if capped:
-            report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
-
-    # ── the daily Insights grain ──────────────────────────────────────────────────────────────
-    if insights:
-        rows, capped = [], False
-        for acct in accts:
-            for since, until in _slices(days, INSIGHTS_SLICE):
-                got, hit = _walk(f"{acct['id']}/insights", tok, log,
-                                 fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
-                                 time_increment="1", limit=INSIGHTS_PAGE,
-                                 time_range=json.dumps({"since": since, "until": until}))
-                rows.extend(got)
-                capped = capped or hit
-        # ⛔ Insights rows carry no id. The key must be STABLE across runs or every re-sync
-        # appends a second copy of the same day — so it is composed from the grain itself.
-        for r in rows:
-            r["id"] = ":".join(str(r.get(k) or "") for k in
-                               (f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
-        fields = ["id"] + INSIGHT_FIELDS
-        _ensure(con, INSIGHTS_TABLE, fields, rows)
-        n = _upsert(con, INSIGHTS_TABLE, fields, rows)
-        total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
-        report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
-        log(f"  {INSIGHTS_TABLE:<20} pulled {n:>6}   mirror total {total:>6}"
-            + ("   !! PAGE CAP HIT" if capped else ""))
-
-    con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
-                ["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
-                 sum(t["in_mirror"] for t in report["tables"].values()),
-                 time.strftime("%Y-%m-%d %H:%M:%S")])
-    return report
-
-
-def status(tenant_key="royal-imports"):
-    """What is in the mirror right now, per table. Never fetches."""
-    path = datastore.path_for(tenant_key)
-    if Path(datastore.DB_PATH) != Path(path):
-        datastore.use_path(path)
-    out = {}
-    con = datastore.connect()
-    for table in list(SPECS) + [INSIGHTS_TABLE]:
-        try:
-            out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
-        except Exception:
-            out[table] = None                                 # table absent = never synced
-    return out
-
-
-def main(argv=None):
-    ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
-    ap.add_argument("--sync", action="store_true")
-    ap.add_argument("--status", action="store_true")
-    ap.add_argument("--tenant", default="royal-imports")
-    ap.add_argument("--no-insights", action="store_true")
-    ap.add_argument("--insights-days", type=int, default=None,
-                    help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
-    a = ap.parse_args(argv)
-    if a.status:
-        for k, v in status(a.tenant).items():
-            print(f"  {k:<20} {'(never synced)' if v is None else v}")
-        return 0
-    if not a.sync:
-        ap.print_help()
-        return 2
-    rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
-    for p in rep["problems"]:
-        print("  PROBLEM:", p)
-    print(f"  accounts: {len(rep['accounts'])}   tables: {len(rep['tables'])}")
-    return 1 if rep["problems"] else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+"""meta_store.py — the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
+
+    python platform/harness/meta_store.py --sync                 pull into tenant #0's mirror
+    python platform/harness/meta_store.py --sync --tenant gtmlab
+    python platform/harness/meta_store.py --status               what is in the mirror now
+
+⛔ WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
+hardwired to XML-RPC — it does `import core.odoo as O` and speaks `search_read` — so no amount of
+spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
+per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
+delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
+store with two loaders, not two stores.**
+
+⭐ THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
+the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
+`XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
+`Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
+different first hop.
+
+⚠ EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
+carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
+  Ad Account 45 · Campaign 35 · Ad Set 54 · Ad 36 · Creative 58 · Insights 57
+⛔ AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
+came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
+nothing going red — which is exactly the "do not drop any column" instruction, broken silently.
+The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
+
+⚠ `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
+answers `403 (#200) Requires business_management permission`, which this token does not carry. One
+column of 285. R6's second sentence — a limit that cannot be removed gets stated with its cause.
+
+⛔ IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
+larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
+(W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
+"""
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+if str(_HERE.parent) not in sys.path:
+    sys.path.insert(0, str(_HERE.parent))
+
+from harness import datastore                                    # noqa: E402
+
+GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
+GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
+
+#: Numeric columns, by name. Everything else is VARCHAR — including ids (see the header) and
+#: including anything Graph returns as a nested object, which is stored as compact JSON text.
+_INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
+        "inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
+        "account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
+        "min_daily_budget", "min_campaign_group_spend_cap"}
+_DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
+        "inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
+        "daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
+        "daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
+        "lifetime_spend_cap", "lifetime_imps"}
+
+#: ⭐ THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
+#: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
+#: the grid links in `meta_relational`.
+ACCOUNT_FIELDS = (
+    "account_id account_status age amount_spent balance business_city business_country_code "
+    "business_name business_state business_street business_street2 business_zip capabilities "
+    "created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
+    "has_migrated_permissions id io_number is_attribution_spec_system_default "
+    "is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
+    "is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
+    "name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
+    "timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
+).split()
+
+CAMPAIGN_FIELDS = (
+    "account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
+    "campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
+    "created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
+    "last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
+    "promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
+    "special_ad_category special_ad_category_country spend_cap start_time status stop_time "
+    "topline_id updated_time"
+).split()
+
+ADSET_FIELDS = (
+    "account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
+    "bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
+    "campaign_active_time campaign_attribution campaign_id configured_status created_time "
+    "creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
+    "effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
+    "issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
+    "lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
+    "optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
+    "rf_prediction_id source_adset source_adset_id start_time status targeting "
+    "targeting_optimization_types time_based_ad_rotation_id_blocks "
+    "time_based_ad_rotation_intervals updated_time use_new_app_click"
+).split()
+
+AD_FIELDS = (
+    "account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
+    "adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
+    "conversion_domain created_time creative demolink_hash display_sequence effective_status "
+    "engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
+    "preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
+    "tracking_and_conversion_with_defaults tracking_specs updated_time"
+).split()
+
+CREATIVE_FIELDS = (
+    "account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
+    "branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
+    "category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
+    "destination_set_id dynamic_ad_voice effective_authorization_category "
+    "effective_instagram_media_id effective_object_story_id enable_direct_install "
+    "enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
+    "instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
+    "link_deep_link_url link_destination_display_url link_og_id link_url "
+    "messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
+    "object_type object_url place_page_set_id platform_customizations playable_asset_id "
+    "portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
+    "template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
+    "use_page_actor_override video_id"
+).split()
+
+INSIGHT_FIELDS = (
+    "account_currency account_id account_name action_values actions ad_id ad_name adset_id "
+    "adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
+    "clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
+    "cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
+    "date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
+    "impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
+    "optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
+    "social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
+    "video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
+    "video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
+    "video_play_actions video_thruplay_watched_actions website_purchase_roas"
+).split()
+
+#: table -> (graph edge on the account | None, measured fields, parent column)
+SPECS = {
+    "meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
+    "meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
+    "meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
+    "meta_ads": ("ads", AD_FIELDS, "adset_id"),
+    "meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
+}
+
+#: The daily Insights grain (R2). One row per (ad, day) — the id is synthesised because Insights
+#: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
+INSIGHTS_TABLE = "meta_insights_daily"
+INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
+
+#: ⛔ INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
+#: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
+#: — Graph's way of saying the synchronous query is too heavy (the async report-run API is the
+#: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
+#: page 25 answer 200. So the window is walked in slices with every column intact:
+#:   57 fields · ad level · 7d · limit 25   -> 200, 25 rows
+#:   57 fields · account level · 7d          -> 200, 7 rows
+#: ⚠ Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over —
+#: it drops columns R2 requires, and it does so invisibly.
+INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
+INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
+INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
+
+
+def _slices(days, size):
+    """[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
+    from datetime import date, timedelta
+    end = date.today()
+    start = end - timedelta(days=max(1, days) - 1)
+    out, cur = [], start
+    while cur <= end:
+        stop = min(cur + timedelta(days=max(1, size) - 1), end)
+        out.append((cur.isoformat(), stop.isoformat()))
+        cur = stop + timedelta(days=1)
+    return out
+
+#: ⚠ A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
+#: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
+#: not a row cap on a connected source (R6 forbids that) — it is a runaway guard, and reaching it
+#: is reported as a problem, never absorbed.
+MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
+PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
+
+
+class MetaError(RuntimeError):
+    """A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
+
+
+def token():
+    """The Meta token from the environment or gitignored `platform/.env`; "" when absent.
+
+    ⚠ Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
+    `platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
+    (`core` never imports up). Fifteen lines is the price of that boundary.
+    """
+    tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
+    if tok:
+        return tok.strip()
+    env = _HERE.parent / ".env"
+    if env.exists():
+        for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
+            if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
+                _, _, v = line.partition("=")
+                return v.strip().strip('"').strip("'")
+    return ""
+
+
+def _get(path, tok, **params):
+    params["access_token"] = tok
+    url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
+    req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
+    try:
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return json.loads(r.read().decode("utf-8", "replace"))
+    except urllib.error.HTTPError as e:
+        try:
+            msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
+                   ).get("message") or ""
+        except Exception:
+            msg = ""
+        raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
+    except Exception as e:
+        raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
+
+
+#: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
+#: why it cannot be treated as "the server is broken, give up".
+_TOO_MUCH = "reduce the amount of data"
+
+#: ⛔ THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
+#: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
+#: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" — the
+#: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
+#: ⚠ It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
+#: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
+#: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
+_RATE_LIMITED = "too many calls"
+_RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
+_RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
+
+
+def _walk(path, tok, log, **params):
+    """Every page of an edge, paged by CURSOR under our own parameters.
+
+    ⛔ IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
+    first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
+    you're asking for"**, the retry at limit=25 succeeds — and then `next` carries the ORIGINAL
+    limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
+    Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
+
+    ⭐ It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
+    silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
+    every column per row.
+
+    -> (rows, hit_page_cap)
+    """
+    out, pages = [], 0
+    limit = int(params.pop("limit", None) or PAGE)
+    after, waited = None, 0
+    while True:
+        call = dict(params, limit=limit)
+        if after:
+            call["after"] = after
+        try:
+            body = _get(path, tok, **call)
+        except MetaError as e:
+            if _TOO_MUCH in str(e) and limit > 5:
+                limit = max(5, limit // 4)
+                log(f"    page too heavy for /{path} - retrying at limit={limit} "
+                    f"(a payload ceiling, not a row cap; every column is still asked for)")
+                continue
+            if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
+                waited += 1
+                log(f"    rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
+                    f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
+                time.sleep(_RATE_WAIT)
+                continue
+            if _RATE_LIMITED in str(e).lower():
+                log(f"    !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
+                    f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
+                    f"limit is per ad account and persists for minutes. Fix: re-run "
+                    f"`--sync --only <table>` later; the upsert is idempotent.")
+                return out, True
+            raise
+        out.extend(body.get("data") or [])
+        pages += 1
+        after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
+        has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
+        if not has_next:
+            return out, False
+        if pages >= MAX_PAGES:
+            log(f"    !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
+                f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
+                f"window with META_INSIGHTS_DAYS.")
+            return out, True
+
+
+def _cell(value):
+    """One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
+    being dropped: R2 says every field the API returns, and `targeting` is a field."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def _coltype(name, rows=None):
+    """The DuckDB type for one column — decided by the DATA when there is data, by the name only
+    as a fallback.
+
+    ⛔ THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
+    `cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
+    action-type objects** on the Insights edge:
+        [{"action_type":"outbound_click","value":"1.459854"}]
+    Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
+    '[{...}]' to DOUBLE` — after five entity tables had already been written, so the sync looked
+    like it worked and then blew up on the last table.
+    ⭐ Same principle the field CATALOG is built on, applied one layer down: **ask the response,
+    do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
+    that is what `_cell` stores; anything else falls back to the measured name hints.
+    """
+    if rows:
+        seen, kinds = 0, set()
+        for r in rows:
+            v = r.get(name)
+            if v is None or v == "":
+                continue
+            kinds.add("json" if isinstance(v, (list, dict)) else
+                      "bool" if isinstance(v, bool) else
+                      "int" if isinstance(v, int) else
+                      "float" if isinstance(v, float) else "str")
+            seen += 1
+            if seen >= 200:
+                break
+        if kinds:
+            if "json" in kinds or "str" in kinds:
+                return "VARCHAR"                              # a JSON blob, or a numeric STRING
+            if kinds <= {"int", "bool"}:
+                return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
+            return "DOUBLE"
+    if name in _INT:
+        return "BIGINT"
+    if name in _DBL:
+        return "DOUBLE"
+    return "VARCHAR"                                          # ids included — see the header
+
+
+def _ensure(con, table, fields, rows=None):
+    """Create or widen the table, with every column typed from `rows` when they are available.
+
+    ⚠ AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
+    column in place, and this table is DERIVED data that can be re-pulled in minutes — so a type
+    disagreement drops and recreates rather than limping on with a column that refuses every
+    insert. The alternative is a mirror that is permanently unwritable for one bad guess.
+    """
+    want = {f: _coltype(f, rows) for f in fields}
+    have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
+    if have:
+        clash = [f for f, ty in want.items() if f in have and have[f] != ty
+                 and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
+        if clash:
+            con.execute(f"DROP TABLE {table}")
+            have = {}
+    if not have:
+        cols = ", ".join(f"{f} {want[f]}" for f in fields)
+        con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
+                    if "id" not in fields else
+                    f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
+        return
+    for f in fields:
+        if f not in have:
+            con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
+
+
+def _upsert(con, table, fields, rows):
+    """Delete-then-insert by id — the same idempotence `datastore._upsert` gives the Odoo half, so
+    a re-sync updates in place and can never append a second copy of the same object."""
+    if not rows:
+        return 0
+    cols = list(fields)
+    ids = [str(r.get("id") or "") for r in rows]
+    q = ",".join("?" for _ in ids)
+    con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
+    con.executemany(
+        f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
+        [[_cell(r.get(c)) for c in cols] for r in rows])
+    return len(rows)
+
+
+def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
+    """Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
+
+    Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
+    exactly as `odoo_relational.refresh` is.
+    """
+    tok = tok or token()
+    # ⛔ THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME — and the difference cost a
+    # live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
+    # `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
+    # imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
+    # that trips the per-ad-account rate limit and never finishes. The comment beside that call
+    # claimed a short window the code could not deliver.
+    # ⭐ The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
+    # makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
+    days = int(insights_days or INSIGHTS_DAYS)
+    report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
+    if not tok:
+        report["problems"].append(
+            "META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
+            "was pulled. This is a missing CREDENTIAL, not a missing capability.")
+        return report
+
+    path = datastore.path_for(tenant_key)
+    if Path(datastore.DB_PATH) != Path(path):
+        datastore.use_path(path)
+    con = datastore.connect()
+    log(f"  mirror: {Path(path).name}")
+
+    accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
+    report["accounts"] = [a.get("id") for a in accts]
+    if not accts:
+        report["problems"].append("the token reaches no ad accounts")
+        return report
+
+    # ── the five entity levels ────────────────────────────────────────────────────────────────
+    for table, (edge, fields, _parent) in SPECS.items():
+        rows, capped = [], False
+        for acct in accts:
+            aid = acct["id"]
+            if edge is None:
+                rows.append(_get(aid, tok, fields=",".join(fields)))
+            else:
+                got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
+                rows.extend(got)
+                capped = capped or hit
+        _ensure(con, table, fields, rows)
+        n = _upsert(con, table, fields, rows)
+        total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
+        report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
+        log(f"  {table:<20} pulled {n:>6}   mirror total {total:>6}"
+            + ("   !! PAGE CAP HIT" if capped else ""))
+        if capped:
+            report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
+
+    # ── the daily Insights grain ──────────────────────────────────────────────────────────────
+    if insights:
+        rows, capped = [], False
+        for acct in accts:
+            for since, until in _slices(days, INSIGHTS_SLICE):
+                got, hit = _walk(f"{acct['id']}/insights", tok, log,
+                                 fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
+                                 time_increment="1", limit=INSIGHTS_PAGE,
+                                 time_range=json.dumps({"since": since, "until": until}))
+                rows.extend(got)
+                capped = capped or hit
+        # ⛔ Insights rows carry no id. The key must be STABLE across runs or every re-sync
+        # appends a second copy of the same day — so it is composed from the grain itself.
+        for r in rows:
+            r["id"] = ":".join(str(r.get(k) or "") for k in
+                               (f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
+        fields = ["id"] + INSIGHT_FIELDS
+        _ensure(con, INSIGHTS_TABLE, fields, rows)
+        n = _upsert(con, INSIGHTS_TABLE, fields, rows)
+        total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
+        report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
+        log(f"  {INSIGHTS_TABLE:<20} pulled {n:>6}   mirror total {total:>6}"
+            + ("   !! PAGE CAP HIT" if capped else ""))
+
+    con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
+                ["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
+                 sum(t["in_mirror"] for t in report["tables"].values()),
+                 time.strftime("%Y-%m-%d %H:%M:%S")])
+    return report
+
+
+def status(tenant_key="royal-imports"):
+    """What is in the mirror right now, per table. Never fetches."""
+    path = datastore.path_for(tenant_key)
+    if Path(datastore.DB_PATH) != Path(path):
+        datastore.use_path(path)
+    out = {}
+    con = datastore.connect()
+    for table in list(SPECS) + [INSIGHTS_TABLE]:
+        try:
+            out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
+        except Exception:
+            out[table] = None                                 # table absent = never synced
+    return out
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
+    ap.add_argument("--sync", action="store_true")
+    ap.add_argument("--status", action="store_true")
+    ap.add_argument("--tenant", default="royal-imports")
+    ap.add_argument("--no-insights", action="store_true")
+    ap.add_argument("--insights-days", type=int, default=None,
+                    help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
+    a = ap.parse_args(argv)
+    if a.status:
+        for k, v in status(a.tenant).items():
+            print(f"  {k:<20} {'(never synced)' if v is None else v}")
+        return 0
+    if not a.sync:
+        ap.print_help()
+        return 2
+    rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
+    for p in rep["problems"]:
+        print("  PROBLEM:", p)
+    print(f"  accounts: {len(rep['accounts'])}   tables: {len(rep['tables'])}")
+    return 1 if rep["problems"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

platform/model/topics/odoo_accounts.yml

@@ -1,60 +1,60 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_accounts
-label: "Odoo GL accounts"
-entity: account.account
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_accounts
-subject: "odoo:account.account"
-grain: "one row per GL account in the chart of accounts"
-scope:
-  population: "every account.account record (192 measured)"
-store:
-  table: account_account
-  alias: a
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-  dims:
-    account_type: {label: "Account type"}
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: account_code
-    label: "Code"
-    type: text
-    kind: data
-  - key: account_name
-    label: "Account"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `account.account` id. Also this row's id."
-  - key: account_type
-    label: "Type"
-    type: select
-    kind: data
-  - key: is_expense
-    label: "Expense account"
-    type: checkbox
-    kind: data
-    means: "Ticked for the expense family - the same predicate the semantic layer's gl_lines topic uses, so this column and that topic cannot disagree."
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-
-ai_context: >
-  The chart of accounts — the registry gl_lines posts against.
-  Use it to resolve an account code to a name or a type.
-  ⚠ `is_expense` is a DERIVED boolean standing in for Odoo's five-value `internal_group` (asset/liability/equity/income/expense), which the mirror does not yet carry.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_accounts
+label: "Odoo GL accounts"
+entity: account.account
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_accounts
+subject: "odoo:account.account"
+grain: "one row per GL account in the chart of accounts"
+scope:
+  population: "every account.account record (192 measured)"
+store:
+  table: account_account
+  alias: a
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+  dims:
+    account_type: {label: "Account type"}
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: account_code
+    label: "Code"
+    type: text
+    kind: data
+  - key: account_name
+    label: "Account"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `account.account` id. Also this row's id."
+  - key: account_type
+    label: "Type"
+    type: select
+    kind: data
+  - key: is_expense
+    label: "Expense account"
+    type: checkbox
+    kind: data
+    means: "Ticked for the expense family - the same predicate the semantic layer's gl_lines topic uses, so this column and that topic cannot disagree."
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+
+ai_context: >
+  The chart of accounts — the registry gl_lines posts against.
+  Use it to resolve an account code to a name or a type.
+  ⚠ `is_expense` is a DERIVED boolean standing in for Odoo's five-value `internal_group` (asset/liability/equity/income/expense), which the mirror does not yet carry.

platform/model/topics/odoo_agents.yml

@@ -1,59 +1,59 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_agents
-label: "Odoo agents"
-entity: res.partner
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_agents
-subject: "odoo:res.partner.agent"
-grain: "one row per sales agent"
-scope:
-  population: "a UNION of two disagreeing sources — partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
-  why_union: "measured 2026-08-09: 16 carry commission lines, 17 carry the flag, and the union is 19 — either source alone silently drops real agents"
-store:
-  table: res_partner
-  alias: p
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: agent
-    label: "Agent"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `res.partner` id. Also this row's id."
-  - key: agent_id
-    label: "Odoo agent id"
-    type: int
-    kind: data
-  - key: flagged
-    label: "Flagged in Odoo"
-    type: checkbox
-    kind: data
-    means: "Ticked = `res.partner.agent` is set. Unticked agents were found by their commission lines instead - both are real, which is why this table is the union of the two."
-  - key: commissioned
-    label: "Has commission lines"
-    type: checkbox
-    kind: data
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-
-ai_context: >
-  The sales-agent registry.
-  `flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
-  For an agent's BOOK use sales_lines/commission_lines with the agent dim.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_agents
+label: "Odoo agents"
+entity: res.partner
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_agents
+subject: "odoo:res.partner.agent"
+grain: "one row per sales agent"
+scope:
+  population: "a UNION of two disagreeing sources — partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
+  why_union: "measured 2026-08-09: 16 carry commission lines, 17 carry the flag, and the union is 19 — either source alone silently drops real agents"
+store:
+  table: res_partner
+  alias: p
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: agent
+    label: "Agent"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `res.partner` id. Also this row's id."
+  - key: agent_id
+    label: "Odoo agent id"
+    type: int
+    kind: data
+  - key: flagged
+    label: "Flagged in Odoo"
+    type: checkbox
+    kind: data
+    means: "Ticked = `res.partner.agent` is set. Unticked agents were found by their commission lines instead - both are real, which is why this table is the union of the two."
+  - key: commissioned
+    label: "Has commission lines"
+    type: checkbox
+    kind: data
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+
+ai_context: >
+  The sales-agent registry.
+  `flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
+  For an agent's BOOK use sales_lines/commission_lines with the agent dim.

platform/model/topics/odoo_bills.yml

@@ -1,86 +1,86 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_bills
-label: "Odoo vendor bills"
-entity: account.move
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_bills
-subject: "odoo:account.move.vendor"
-grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
-scope:
-  population: "move_type in (in_invoice, in_refund) AND state = posted"
-  signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
-store:
-  table: account_move
-  alias: m
-  date_col: "m.invoice_date"
-  dims:
-    vendor: {label: "Vendor"}
-    payment_state: {label: "Payment state"}
-    move_type: {label: "Document type"}
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: bill_no
-    label: "Bill"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `account.move` id. Also this row's id."
-  - key: vendor
-    label: "Vendor"
-    type: text
-    kind: data
-  - key: vendor_id
-    label: "Odoo vendor id"
-    type: int
-    kind: data
-  - key: invoice_date
-    label: "Bill date"
-    type: date
-    kind: data
-  - key: due_date
-    label: "Due date"
-    type: date
-    kind: data
-  - key: amount_untaxed
-    label: "Billed $"
-    type: currency
-    kind: data
-  - key: residual
-    label: "Outstanding $"
-    type: currency
-    kind: data
-  - key: payment_state
-    label: "Payment state"
-    type: select
-    kind: data
-  - key: move_type
-    label: "Document"
-    type: select
-    kind: data
-  - key: vendor_link
-    label: "Vendor record"
-    type: link
-    kind: link
-    to_grid: ut_odoo_vendors
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-
-ai_context: >
-  Vendor bills at DOCUMENT grain — the payables side of account_move.
-  Use it for AP questions.
-  ⚠ The census found `ref` (the VENDOR's own invoice number), `journal_id` and `currency_id` populated in Odoo and absent from the mirror, so they cannot be answered from here yet.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_bills
+label: "Odoo vendor bills"
+entity: account.move
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_bills
+subject: "odoo:account.move.vendor"
+grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
+scope:
+  population: "move_type in (in_invoice, in_refund) AND state = posted"
+  signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
+store:
+  table: account_move
+  alias: m
+  date_col: "m.invoice_date"
+  dims:
+    vendor: {label: "Vendor"}
+    payment_state: {label: "Payment state"}
+    move_type: {label: "Document type"}
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: bill_no
+    label: "Bill"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `account.move` id. Also this row's id."
+  - key: vendor
+    label: "Vendor"
+    type: text
+    kind: data
+  - key: vendor_id
+    label: "Odoo vendor id"
+    type: int
+    kind: data
+  - key: invoice_date
+    label: "Bill date"
+    type: date
+    kind: data
+  - key: due_date
+    label: "Due date"
+    type: date
+    kind: data
+  - key: amount_untaxed
+    label: "Billed $"
+    type: currency
+    kind: data
+  - key: residual
+    label: "Outstanding $"
+    type: currency
+    kind: data
+  - key: payment_state
+    label: "Payment state"
+    type: select
+    kind: data
+  - key: move_type
+    label: "Document"
+    type: select
+    kind: data
+  - key: vendor_link
+    label: "Vendor record"
+    type: link
+    kind: link
+    to_grid: ut_odoo_vendors
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+
+ai_context: >
+  Vendor bills at DOCUMENT grain — the payables side of account_move.
+  Use it for AP questions.
+  ⚠ The census found `ref` (the VENDOR's own invoice number), `journal_id` and `currency_id` populated in Odoo and absent from the mirror, so they cannot be answered from here yet.

platform/model/topics/odoo_customers.yml

@@ -1,213 +1,213 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_customers
-label: "Odoo customers"
-entity: res.partner
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: customer_data
-subject: "odoo:res.partner"
-grain: "one row per customer in tenant #0's scoped book — a REGISTRY, not a dated event stream. Identity is the Odoo `res.partner` id (the row's `pid` IS that id)."
-scope:
-  population: "the customer book `modules/customer_data.pool()` builds; the grid's own contract states it as one row per customer who ordered in the last 24 months"
-  identity: "the Odoo res.partner id — exposed as the `partner_id` column (W33-T43) and used as the row pid, so there is ONE id per row and no second one"
-  merged: "W33-T44 retired `ut_odoo_customers`, which presented this same subject. This topic describes the SURVIVING database, `customer_data`, which keeps its store bucket so no saved view, grant, cohort or formula moved"
-  no_date: "a registry has no date dimension; ask sales_lines or customer_invoices for anything time-windowed about a customer"
-store:
-  table: res_partner
-  alias: p
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-  dims:
-    agent: {label: "Sales agent"}
-    state: {label: "State"}
-    country: {label: "Country"}
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: customer
-    label: "Customer"
-    type: text
-    kind: data
-    means: "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
-  - key: partner_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The Odoo res.partner id — this row's identity, and the key every Odoo document joins on. W33-T43 / owner item 12: 'One unique ID per database always.' It is DERIVED rather than read off the pool row because a customer row's pid IS the partner id, so the value is already on every row and a second copy in the pool would be a second source for one fact."
-  - key: odoo_status
-    label: "Odoo record"
-    type: status
-    kind: data
-    means: "Whether this customer still exists in Odoo. Archived means deleted there."
-  - key: agent
-    label: "Agent"
-    type: text
-    kind: data
-    means: "The sales agent who owns this account."
-  - key: dba
-    label: "DBA"
-    type: select
-    kind: data
-    means: "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
-  - key: salesperson
-    label: "Salesperson"
-    type: text
-    kind: data
-    means: "Who keyed in most of this customer's orders — not the Agent, who owns the account."
-  - key: street
-    label: "Street"
-    type: text
-    kind: data
-    means: "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
-    kind: data
-    means: "Second address line (suite, unit, floor) on the customer's Odoo address."
-  - key: city
-    label: "City"
-    type: text
-    kind: data
-    means: "City on the customer's Odoo address."
-  - key: state
-    label: "State"
-    type: text
-    kind: data
-    means: "State or province on the customer's Odoo address."
-  - key: country
-    label: "Country"
-    type: text
-    kind: data
-    means: "Country on the customer's Odoo address."
-  - key: zip
-    label: "ZIP"
-    type: text
-    kind: data
-    means: "Postal code on the customer's Odoo address."
-  - key: customer_since
-    label: "Customer since"
-    type: date
-    kind: data
-    means: "When this customer was first set up in Odoo."
-  - key: tags
-    label: "Tags"
-    type: text
-    kind: data
-    means: "Odoo labels on this customer, comma-separated."
-  - key: pricelist
-    label: "Price list"
-    type: text
-    kind: data
-    means: "The price list this customer buys on."
-  - key: payment_terms
-    label: "Payment terms"
-    type: text
-    kind: data
-    means: "Payment terms on this customer's account — Net 30, for example."
-  - key: last_order
-    label: "Last order"
-    type: date
-    kind: data
-    means: "Date of the most recent confirmed order."
-  - key: overdue_days
-    label: "Overdue days"
-    type: int
-    kind: data
-    means: "How many days late this customer is running against their own usual ordering rhythm."
-  - key: est_missed
-    label: "Est. missed $"
-    type: currency
-    kind: data
-    means: "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
-  - key: ar_open
-    label: "AR current $"
-    type: currency
-    kind: data
-    means: "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
-    kind: data
-    means: "Invoiced money past due — same basis as the Collections page."
-  - key: ar_outstanding
-    label: "AR outstanding $"
-    type: currency
-    kind: data
-    means: "Total invoiced money owed right now: AR current $ plus AR overdue $."
-  - key: ar_exposure
-    label: "Credit exposure $"
-    type: currency
-    kind: data
-    means: "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
-    kind: data
-    means: "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
-    kind: data
-    means: "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
-    kind: data
-    means: "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
-  - key: ar_aged_90_plus
-    label: "90+ days $"
-    type: currency
-    kind: data
-    means: "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
-  - key: days_to_pay
-    label: "Days to pay"
-    type: int
-    kind: data
-    means: "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
-  - key: top_category
-    label: "Top category"
-    type: text
-    kind: data
-    means: "The category this customer spent the most on in the last 12 months."
-  - key: top_category_pct
-    label: "Top category %"
-    type: pct
-    kind: data
-    means: "Share of last-12-months spend that went to the top category."
-  - key: sku_count
-    label: "SKUs bought"
-    type: int
-    kind: data
-    means: "Distinct products bought in the last 12 months."
-  - key: top_sku
-    label: "Top SKU"
-    type: text
-    kind: data
-    means: "The product this customer spent the most on in the last 12 months."
-  - key: days_since
-    label: "Days since order"
-    type: int
-    kind: data
-    means: "Days since the last confirmed order."
-  - key: typical_gap_days
-    label: "Typical gap days"
-    type: int
-    kind: data
-    means: "Days this customer usually goes between orders, from their own history."
-  - key: notes
-    label: "Notes"
-    type: text
-    kind: data
-    means: "Your notes on this customer. Saved in this app only, visible only to you."
-
-ai_context: >
-  The customer REGISTRY as a person sees it in the app — the database labelled 'Odoo customers'.
-  Use it to answer 'who is this customer', 'which customers exist', 'which agent owns them', 'where are they', and for the AR columns it carries (ar_open, ar_overdue, days_to_pay), which are reconciled by modules/ar.py.
-  ⛔ For anything WINDOWED or at line grain go to sales_lines / customer_invoices / receivables — those topics own the time dimension and this one has none.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_customers
+label: "Odoo customers"
+entity: res.partner
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: customer_data
+subject: "odoo:res.partner"
+grain: "one row per customer in tenant #0's scoped book — a REGISTRY, not a dated event stream. Identity is the Odoo `res.partner` id (the row's `pid` IS that id)."
+scope:
+  population: "the customer book `modules/customer_data.pool()` builds; the grid's own contract states it as one row per customer who ordered in the last 24 months"
+  identity: "the Odoo res.partner id — exposed as the `partner_id` column (W33-T43) and used as the row pid, so there is ONE id per row and no second one"
+  merged: "W33-T44 retired `ut_odoo_customers`, which presented this same subject. This topic describes the SURVIVING database, `customer_data`, which keeps its store bucket so no saved view, grant, cohort or formula moved"
+  no_date: "a registry has no date dimension; ask sales_lines or customer_invoices for anything time-windowed about a customer"
+store:
+  table: res_partner
+  alias: p
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+  dims:
+    agent: {label: "Sales agent"}
+    state: {label: "State"}
+    country: {label: "Country"}
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: customer
+    label: "Customer"
+    type: text
+    kind: data
+    means: "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
+  - key: partner_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The Odoo res.partner id — this row's identity, and the key every Odoo document joins on. W33-T43 / owner item 12: 'One unique ID per database always.' It is DERIVED rather than read off the pool row because a customer row's pid IS the partner id, so the value is already on every row and a second copy in the pool would be a second source for one fact."
+  - key: odoo_status
+    label: "Odoo record"
+    type: status
+    kind: data
+    means: "Whether this customer still exists in Odoo. Archived means deleted there."
+  - key: agent
+    label: "Agent"
+    type: text
+    kind: data
+    means: "The sales agent who owns this account."
+  - key: dba
+    label: "DBA"
+    type: select
+    kind: data
+    means: "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
+  - key: salesperson
+    label: "Salesperson"
+    type: text
+    kind: data
+    means: "Who keyed in most of this customer's orders — not the Agent, who owns the account."
+  - key: street
+    label: "Street"
+    type: text
+    kind: data
+    means: "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
+    kind: data
+    means: "Second address line (suite, unit, floor) on the customer's Odoo address."
+  - key: city
+    label: "City"
+    type: text
+    kind: data
+    means: "City on the customer's Odoo address."
+  - key: state
+    label: "State"
+    type: text
+    kind: data
+    means: "State or province on the customer's Odoo address."
+  - key: country
+    label: "Country"
+    type: text
+    kind: data
+    means: "Country on the customer's Odoo address."
+  - key: zip
+    label: "ZIP"
+    type: text
+    kind: data
+    means: "Postal code on the customer's Odoo address."
+  - key: customer_since
+    label: "Customer since"
+    type: date
+    kind: data
+    means: "When this customer was first set up in Odoo."
+  - key: tags
+    label: "Tags"
+    type: text
+    kind: data
+    means: "Odoo labels on this customer, comma-separated."
+  - key: pricelist
+    label: "Price list"
+    type: text
+    kind: data
+    means: "The price list this customer buys on."
+  - key: payment_terms
+    label: "Payment terms"
+    type: text
+    kind: data
+    means: "Payment terms on this customer's account — Net 30, for example."
+  - key: last_order
+    label: "Last order"
+    type: date
+    kind: data
+    means: "Date of the most recent confirmed order."
+  - key: overdue_days
+    label: "Overdue days"
+    type: int
+    kind: data
+    means: "How many days late this customer is running against their own usual ordering rhythm."
+  - key: est_missed
+    label: "Est. missed $"
+    type: currency
+    kind: data
+    means: "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
+  - key: ar_open
+    label: "AR current $"
+    type: currency
+    kind: data
+    means: "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
+    kind: data
+    means: "Invoiced money past due — same basis as the Collections page."
+  - key: ar_outstanding
+    label: "AR outstanding $"
+    type: currency
+    kind: data
+    means: "Total invoiced money owed right now: AR current $ plus AR overdue $."
+  - key: ar_exposure
+    label: "Credit exposure $"
+    type: currency
+    kind: data
+    means: "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
+    kind: data
+    means: "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
+    kind: data
+    means: "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
+    kind: data
+    means: "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
+  - key: ar_aged_90_plus
+    label: "90+ days $"
+    type: currency
+    kind: data
+    means: "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
+  - key: days_to_pay
+    label: "Days to pay"
+    type: int
+    kind: data
+    means: "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
+  - key: top_category
+    label: "Top category"
+    type: text
+    kind: data
+    means: "The category this customer spent the most on in the last 12 months."
+  - key: top_category_pct
+    label: "Top category %"
+    type: pct
+    kind: data
+    means: "Share of last-12-months spend that went to the top category."
+  - key: sku_count
+    label: "SKUs bought"
+    type: int
+    kind: data
+    means: "Distinct products bought in the last 12 months."
+  - key: top_sku
+    label: "Top SKU"
+    type: text
+    kind: data
+    means: "The product this customer spent the most on in the last 12 months."
+  - key: days_since
+    label: "Days since order"
+    type: int
+    kind: data
+    means: "Days since the last confirmed order."
+  - key: typical_gap_days
+    label: "Typical gap days"
+    type: int
+    kind: data
+    means: "Days this customer usually goes between orders, from their own history."
+  - key: notes
+    label: "Notes"
+    type: text
+    kind: data
+    means: "Your notes on this customer. Saved in this app only, visible only to you."
+
+ai_context: >
+  The customer REGISTRY as a person sees it in the app — the database labelled 'Odoo customers'.
+  Use it to answer 'who is this customer', 'which customers exist', 'which agent owns them', 'where are they', and for the AR columns it carries (ar_open, ar_overdue, days_to_pay), which are reconciled by modules/ar.py.
+  ⛔ For anything WINDOWED or at line grain go to sales_lines / customer_invoices / receivables — those topics own the time dimension and this one has none.

platform/model/topics/odoo_invoices.yml

@@ -1,98 +1,98 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_invoices
-label: "Odoo invoices"
-entity: account.move
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_invoices
-subject: "odoo:account.move.customer"
-grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
-scope:
-  population: "move_type in (out_invoice, out_refund) AND state = posted"
-  signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
-store:
-  table: account_move
-  alias: m
-  date_col: "m.invoice_date"
-  dims:
-    customer: {label: "Customer"}
-    payment_state: {label: "Payment state"}
-    move_type: {label: "Document type"}
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: invoice_no
-    label: "Invoice"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `account.move` id. Also this row's id."
-  - key: customer
-    label: "Customer"
-    type: text
-    kind: data
-  - key: partner_id
-    label: "Odoo partner id"
-    type: int
-    kind: data
-  - key: invoice_date
-    label: "Invoice date"
-    type: date
-    kind: data
-  - key: due_date
-    label: "Due date"
-    type: date
-    kind: data
-  - key: residual
-    label: "Outstanding $"
-    type: currency
-    kind: data
-    means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
-  - key: amount_untaxed
-    label: "Invoiced $"
-    type: currency
-    kind: data
-  - key: payment_state
-    label: "Payment state"
-    type: select
-    kind: data
-  - key: move_type
-    label: "Document"
-    type: select
-    kind: data
-  - key: wholesale_scope
-    label: "In wholesale scope"
-    type: checkbox
-    kind: data
-    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
-  - key: origin_order
-    label: "Source order"
-    type: text
-    kind: data
-    means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
-  - key: order_link
-    label: "Order record"
-    type: link
-    kind: link
-    to_grid: ut_odoo_orders
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-
-ai_context: >
-  Customer invoices at DOCUMENT grain — one row per invoice, not per line.
-  Use it for AR questions: what is open, what is overdue, what was invoiced.
-  For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
-  `origin_order` is the single stored key that joins an invoice back to the order it was raised from.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_invoices
+label: "Odoo invoices"
+entity: account.move
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_invoices
+subject: "odoo:account.move.customer"
+grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
+scope:
+  population: "move_type in (out_invoice, out_refund) AND state = posted"
+  signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
+store:
+  table: account_move
+  alias: m
+  date_col: "m.invoice_date"
+  dims:
+    customer: {label: "Customer"}
+    payment_state: {label: "Payment state"}
+    move_type: {label: "Document type"}
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: invoice_no
+    label: "Invoice"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `account.move` id. Also this row's id."
+  - key: customer
+    label: "Customer"
+    type: text
+    kind: data
+  - key: partner_id
+    label: "Odoo partner id"
+    type: int
+    kind: data
+  - key: invoice_date
+    label: "Invoice date"
+    type: date
+    kind: data
+  - key: due_date
+    label: "Due date"
+    type: date
+    kind: data
+  - key: residual
+    label: "Outstanding $"
+    type: currency
+    kind: data
+    means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
+  - key: amount_untaxed
+    label: "Invoiced $"
+    type: currency
+    kind: data
+  - key: payment_state
+    label: "Payment state"
+    type: select
+    kind: data
+  - key: move_type
+    label: "Document"
+    type: select
+    kind: data
+  - key: wholesale_scope
+    label: "In wholesale scope"
+    type: checkbox
+    kind: data
+    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
+  - key: origin_order
+    label: "Source order"
+    type: text
+    kind: data
+    means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
+  - key: order_link
+    label: "Order record"
+    type: link
+    kind: link
+    to_grid: ut_odoo_orders
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+
+ai_context: >
+  Customer invoices at DOCUMENT grain — one row per invoice, not per line.
+  Use it for AR questions: what is open, what is overdue, what was invoiced.
+  For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
+  `origin_order` is the single stored key that joins an invoice back to the order it was raised from.

platform/model/topics/odoo_orders.yml

@@ -1,87 +1,87 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_orders
-label: "Odoo orders"
-entity: sale.order
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_orders
-subject: "odoo:sale.order"
-grain: "one row per confirmed sales order (document grain)"
-scope:
-  population: "state in (sale, done) — quotations and cancellations excluded"
-  vs_sales_orders: "⚠ DISTINCT from the `sales_orders` topic: that one is the wholesale-scoped analytical view (teams 5/6, house accounts excluded); THIS one is the registry a person opens as a grid, and carries the row set the app shows"
-store:
-  table: sale_order
-  alias: o
-  date_col: "o.date_order"
-  dims:
-    customer: {label: "Customer"}
-    team: {label: "Business unit"}
-    state: {label: "State"}
-    invoice_status: {label: "Invoice status"}
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: order_no
-    label: "Order"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `sale.order` id. Also this row's id."
-  - key: customer
-    label: "Customer"
-    type: text
-    kind: data
-  - key: partner_id
-    label: "Odoo partner id"
-    type: int
-    kind: data
-  - key: order_date
-    label: "Order date"
-    type: date
-    kind: data
-  - key: amount_untaxed
-    label: "Order $"
-    type: currency
-    kind: data
-  - key: team
-    label: "Business unit"
-    type: select
-    kind: data
-  - key: state
-    label: "State"
-    type: select
-    kind: data
-  - key: invoice_status
-    label: "Invoice status"
-    type: select
-    kind: data
-  - key: wholesale_scope
-    label: "In wholesale scope"
-    type: checkbox
-    kind: data
-    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
-  - key: invoices
-    label: "Invoices"
-    type: link
-    kind: link
-    to_grid: ut_odoo_invoices
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-
-ai_context: >
-  Sales orders at DOCUMENT grain, as the app's grid shows them.
-  ⛔ If you are asked for revenue, prefer `sales_lines` (line grain, wholesale scope) or `sales_orders` — this topic exists to describe the ORDER RECORD a person can open, and its scope is the grid's, not the analytical model's.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_orders
+label: "Odoo orders"
+entity: sale.order
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_orders
+subject: "odoo:sale.order"
+grain: "one row per confirmed sales order (document grain)"
+scope:
+  population: "state in (sale, done) — quotations and cancellations excluded"
+  vs_sales_orders: "⚠ DISTINCT from the `sales_orders` topic: that one is the wholesale-scoped analytical view (teams 5/6, house accounts excluded); THIS one is the registry a person opens as a grid, and carries the row set the app shows"
+store:
+  table: sale_order
+  alias: o
+  date_col: "o.date_order"
+  dims:
+    customer: {label: "Customer"}
+    team: {label: "Business unit"}
+    state: {label: "State"}
+    invoice_status: {label: "Invoice status"}
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: order_no
+    label: "Order"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `sale.order` id. Also this row's id."
+  - key: customer
+    label: "Customer"
+    type: text
+    kind: data
+  - key: partner_id
+    label: "Odoo partner id"
+    type: int
+    kind: data
+  - key: order_date
+    label: "Order date"
+    type: date
+    kind: data
+  - key: amount_untaxed
+    label: "Order $"
+    type: currency
+    kind: data
+  - key: team
+    label: "Business unit"
+    type: select
+    kind: data
+  - key: state
+    label: "State"
+    type: select
+    kind: data
+  - key: invoice_status
+    label: "Invoice status"
+    type: select
+    kind: data
+  - key: wholesale_scope
+    label: "In wholesale scope"
+    type: checkbox
+    kind: data
+    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
+  - key: invoices
+    label: "Invoices"
+    type: link
+    kind: link
+    to_grid: ut_odoo_invoices
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+
+ai_context: >
+  Sales orders at DOCUMENT grain, as the app's grid shows them.
+  ⛔ If you are asked for revenue, prefer `sales_lines` (line grain, wholesale scope) or `sales_orders` — this topic exists to describe the ORDER RECORD a person can open, and its scope is the grid's, not the analytical model's.

platform/model/topics/odoo_products.yml

@@ -1,147 +1,147 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_products
-label: "Odoo products"
-entity: product.product
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: product_data
-subject: "odoo:product.product"
-grain: "one row per SKU in the active catalogue — a CATALOGUE, not a dated event stream"
-scope:
-  population: "every ACTIVE product, sold or not (measured 5,862). Deliberately not the sales-window universe: that lands at 2,717 and hides ~2,550 SKUs that have never sold in wholesale scope"
-  identity: "the SKU code (`default_code`). ⚠ 33 active products carry NO code and are keyed `pid:<odoo product id>` instead, so every active product has exactly one row and none is dropped"
-  merged: "W33-T44 retired `ut_odoo_products`, which presented this same subject on Odoo's product_id. This topic describes the SURVIVING database, `product_data`"
-  no_date: "a catalogue has no date dimension; ask sales_lines for movement"
-store:
-  table: product_product
-  alias: pp
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-  dims:
-    category: {label: "Category"}
-    supplier: {label: "Supplier"}
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: code
-    label: "SKU"
-    type: text
-    kind: data
-    means: "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
-    kind: data
-    means: "Product name as it appears in Odoo."
-  - key: category
-    label: "Category"
-    type: select
-    kind: data
-    means: "Product category; '(uncategorized)' when Odoo carries none."
-  - key: supplier
-    label: "Supplier"
-    type: text
-    kind: data
-    means: "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet."
-  - key: origin_country
-    label: "Country"
-    type: text
-    kind: data
-    means: "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet."
-  - key: lead_days
-    label: "Lead time (days)"
-    type: int
-    kind: data
-    means: "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone."
-  - key: first_cost
-    label: "First cost"
-    type: currency
-    kind: data
-    means: "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone."
-  - key: price_fisch
-    label: "Fisch price"
-    type: currency
-    kind: data
-    means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
-  - key: price_royal_1
-    label: "Royal 1 price"
-    type: currency
-    kind: data
-    means: "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
-  - key: price_royal_2
-    label: "Royal 2 price"
-    type: currency
-    kind: data
-    means: "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
-  - key: rev_ytd
-    label: "Revenue YTD"
-    type: currency
-    kind: data
-    means: "Year-to-date revenue for this SKU, BU-scoped when the caller is."
-  - key: rev_ly
-    label: "Revenue LY"
-    type: currency
-    kind: data
-    means: "Same period last year — seasonal wholesale compares like for like."
-  - key: yoy_pct
-    label: "YoY %"
-    type: pct
-    kind: data
-    means: "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
-    kind: data
-    means: "Units sold year to date."
-  - key: orders_ytd
-    label: "Orders YTD"
-    type: int
-    kind: data
-    means: "Distinct orders containing this SKU, year to date."
-  - key: on_hand
-    label: "On hand"
-    type: int
-    kind: data
-    means: "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
-    kind: data
-    means: "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
-  - key: inv_value
-    label: "Stock value"
-    type: currency
-    kind: data
-    means: "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
-  - key: qty_ltm
-    label: "Units LTM"
-    type: int
-    kind: data
-    means: "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
-  - key: dos
-    label: "Days of supply"
-    type: int
-    kind: data
-    means: "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
-    kind: data
-    means: "Days of supply minus lead time. Negative means it runs out before a reorder lands."
-  - key: stock_bucket
-    label: "Stock status"
-    type: select
-    kind: data
-    means: "Dead / excess / healthy bucket from the inventory module. Consolidated; absent for a BU-scoped caller."
-
-ai_context: >
-  The product CATALOGUE — the database labelled 'Odoo products'.
-  Use it for 'what do we sell', 'what does it cost' (first_cost/unit_cost), 'who supplies it', 'what is on hand' and the stock-coverage columns.
-  ⛔ Revenue and unit columns here are WINDOWED SNAPSHOTS (rev_ytd, qty_ltm); for any other window, or for line grain, go to sales_lines.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_products
+label: "Odoo products"
+entity: product.product
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: product_data
+subject: "odoo:product.product"
+grain: "one row per SKU in the active catalogue — a CATALOGUE, not a dated event stream"
+scope:
+  population: "every ACTIVE product, sold or not (measured 5,862). Deliberately not the sales-window universe: that lands at 2,717 and hides ~2,550 SKUs that have never sold in wholesale scope"
+  identity: "the SKU code (`default_code`). ⚠ 33 active products carry NO code and are keyed `pid:<odoo product id>` instead, so every active product has exactly one row and none is dropped"
+  merged: "W33-T44 retired `ut_odoo_products`, which presented this same subject on Odoo's product_id. This topic describes the SURVIVING database, `product_data`"
+  no_date: "a catalogue has no date dimension; ask sales_lines for movement"
+store:
+  table: product_product
+  alias: pp
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+  dims:
+    category: {label: "Category"}
+    supplier: {label: "Supplier"}
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: code
+    label: "SKU"
+    type: text
+    kind: data
+    means: "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
+    kind: data
+    means: "Product name as it appears in Odoo."
+  - key: category
+    label: "Category"
+    type: select
+    kind: data
+    means: "Product category; '(uncategorized)' when Odoo carries none."
+  - key: supplier
+    label: "Supplier"
+    type: text
+    kind: data
+    means: "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet."
+  - key: origin_country
+    label: "Country"
+    type: text
+    kind: data
+    means: "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet."
+  - key: lead_days
+    label: "Lead time (days)"
+    type: int
+    kind: data
+    means: "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone."
+  - key: first_cost
+    label: "First cost"
+    type: currency
+    kind: data
+    means: "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone."
+  - key: price_fisch
+    label: "Fisch price"
+    type: currency
+    kind: data
+    means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
+  - key: price_royal_1
+    label: "Royal 1 price"
+    type: currency
+    kind: data
+    means: "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
+  - key: price_royal_2
+    label: "Royal 2 price"
+    type: currency
+    kind: data
+    means: "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
+  - key: rev_ytd
+    label: "Revenue YTD"
+    type: currency
+    kind: data
+    means: "Year-to-date revenue for this SKU, BU-scoped when the caller is."
+  - key: rev_ly
+    label: "Revenue LY"
+    type: currency
+    kind: data
+    means: "Same period last year — seasonal wholesale compares like for like."
+  - key: yoy_pct
+    label: "YoY %"
+    type: pct
+    kind: data
+    means: "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
+    kind: data
+    means: "Units sold year to date."
+  - key: orders_ytd
+    label: "Orders YTD"
+    type: int
+    kind: data
+    means: "Distinct orders containing this SKU, year to date."
+  - key: on_hand
+    label: "On hand"
+    type: int
+    kind: data
+    means: "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
+    kind: data
+    means: "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
+  - key: inv_value
+    label: "Stock value"
+    type: currency
+    kind: data
+    means: "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
+  - key: qty_ltm
+    label: "Units LTM"
+    type: int
+    kind: data
+    means: "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
+  - key: dos
+    label: "Days of supply"
+    type: int
+    kind: data
+    means: "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
+    kind: data
+    means: "Days of supply minus lead time. Negative means it runs out before a reorder lands."
+  - key: stock_bucket
+    label: "Stock status"
+    type: select
+    kind: data
+    means: "Dead / excess / healthy bucket from the inventory module. Consolidated; absent for a BU-scoped caller."
+
+ai_context: >
+  The product CATALOGUE — the database labelled 'Odoo products'.
+  Use it for 'what do we sell', 'what does it cost' (first_cost/unit_cost), 'who supplies it', 'what is on hand' and the stock-coverage columns.
+  ⛔ Revenue and unit columns here are WINDOWED SNAPSHOTS (rev_ytd, qty_ltm); for any other window, or for line grain, go to sales_lines.

platform/model/topics/odoo_vendors.yml

@@ -1,103 +1,103 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_vendors
-label: "Odoo vendors"
-entity: res.partner
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_vendors
-subject: "odoo:res.partner.vendor"
-grain: "one row per partner we have posted a vendor bill to"
-scope:
-  population: "DERIVED FROM THE BILLS — a partner with no posted vendor bill has no payable history to show, so the bill is the population"
-  asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
-  overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
-store:
-  table: res_partner
-  alias: p
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-  dims:
-    country: {label: "Country"}
-
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: vendor
-    label: "Vendor"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `res.partner` id. Also this row's id."
-  - key: vendor_id
-    label: "Odoo vendor id"
-    type: int
-    kind: data
-  - key: country
-    label: "Country"
-    type: text
-    kind: data
-  - key: email
-    label: "Email"
-    type: text
-    kind: data
-  - key: phone
-    label: "Phone"
-    type: text
-    kind: data
-  - key: mobile
-    label: "Mobile"
-    type: text
-    kind: data
-  - key: vat
-    label: "Tax ID"
-    type: text
-    kind: data
-    means: "Odoo `vat` — the vendor's tax/VAT registration number."
-  - key: vendor_ref
-    label: "Vendor reference"
-    type: text
-    kind: data
-    means: "Odoo `res.partner.ref` — our internal reference for this vendor."
-  - key: website
-    label: "Website"
-    type: url
-    kind: data
-  - key: street
-    label: "Street"
-    type: text
-    kind: data
-  - key: street2
-    label: "Street 2"
-    type: text
-    kind: data
-  - key: city
-    label: "City"
-    type: text
-    kind: data
-  - key: zip
-    label: "ZIP"
-    type: text
-    kind: data
-  - key: bills
-    label: "Bills"
-    type: link
-    kind: link
-    to_grid: ut_odoo_bills
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-
-ai_context: >
-  The vendor/supplier registry, with contact and tax identity (W33-T48 widened it from 5 columns to 15 after a census found 76 populated fields on the underlying partner)
-  ⚠ The contact columns are SPARSE by nature — measured 65/393 with an email, 13/393 with a tax id — so 'blank' means Odoo has no value, never that the sync failed.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_vendors
+label: "Odoo vendors"
+entity: res.partner
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_vendors
+subject: "odoo:res.partner.vendor"
+grain: "one row per partner we have posted a vendor bill to"
+scope:
+  population: "DERIVED FROM THE BILLS — a partner with no posted vendor bill has no payable history to show, so the bill is the population"
+  asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
+  overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
+store:
+  table: res_partner
+  alias: p
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+  dims:
+    country: {label: "Country"}
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: vendor
+    label: "Vendor"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `res.partner` id. Also this row's id."
+  - key: vendor_id
+    label: "Odoo vendor id"
+    type: int
+    kind: data
+  - key: country
+    label: "Country"
+    type: text
+    kind: data
+  - key: email
+    label: "Email"
+    type: text
+    kind: data
+  - key: phone
+    label: "Phone"
+    type: text
+    kind: data
+  - key: mobile
+    label: "Mobile"
+    type: text
+    kind: data
+  - key: vat
+    label: "Tax ID"
+    type: text
+    kind: data
+    means: "Odoo `vat` — the vendor's tax/VAT registration number."
+  - key: vendor_ref
+    label: "Vendor reference"
+    type: text
+    kind: data
+    means: "Odoo `res.partner.ref` — our internal reference for this vendor."
+  - key: website
+    label: "Website"
+    type: url
+    kind: data
+  - key: street
+    label: "Street"
+    type: text
+    kind: data
+  - key: street2
+    label: "Street 2"
+    type: text
+    kind: data
+  - key: city
+    label: "City"
+    type: text
+    kind: data
+  - key: zip
+    label: "ZIP"
+    type: text
+    kind: data
+  - key: bills
+    label: "Bills"
+    type: link
+    kind: link
+    to_grid: ut_odoo_bills
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+
+ai_context: >
+  The vendor/supplier registry, with contact and tax identity (W33-T48 widened it from 5 columns to 15 after a census found 76 populated fields on the underlying partner)
+  ⚠ The contact columns are SPARSE by nature — measured 65/393 with an email, 13/393 with a tax id — so 'blank' means Odoo has no value, never that the sync failed.

platform/modules/collections_send.py

@@ -180,16 +180,20 @@ def load_collection_list(odoo):
 
 
 # --------------------------------------------------------------- statement email
-DEFAULT_SUBJECT = 'Statement of Account — {company} — {month}'
+# ⛔ STANDING RULE 2, AND THIS IS THE ONE STRING IN THE PRODUCT THAT LEAVES THE BUILDING.
+# Every other finding `web_prose` reports is copy on a screen somebody here opens; this is the
+# SUBJECT LINE of mail queued to a real debtor, over the single sanctioned Odoo write. It read
+# 'Statement of Account (em dash) {company} (em dash) {month}' until W36-T42.
+DEFAULT_SUBJECT = 'Statement of Account from {company}, {month}'
 DEFAULT_INTRO = (
     'Dear {customer},<br><br>'
     'Please find below your current statement of account with {company}. '
     'According to our records, the following invoices remain open:'
 )
 DEFAULT_FOOTER = (
-    'If you have already sent payment, please disregard this notice — and thank you. '
+    'If you have already sent payment, please disregard this notice, and thank you. '
     'For any questions about an invoice, simply reply to this email.<br><br>'
-    'Thank you for your business,<br>{company} — Accounts Receivable'
+    'Thank you for your business,<br>{company}<br>Accounts Receivable'
 )
 
 

platform/modules/product_data.py

@@ -1,804 +1,804 @@
-"""modules/product_data.py — the PRODUCT table's pool (wave 15 item 9/10, contract C-TOPIC).
-
-The second object on the table-page factory: same grid, same engine, same permission wall — the
-only difference is the field schema and the identity. `modules/customer_data.pool()` is the
-template and this deliberately mirrors its signature and its row shape.
-
-⛔ THREE DECISIONS THIS FILE HAD TO MAKE, EACH RECORDED BECAUSE A LATER READER WILL WONDER.
-
-1. **THE IDENTITY IS A SKU CODE, WHICH IS A STRING, AND THE GRID WANTS AN INTEGER `pid`.**
-   Cohort membership, `allowed_pids`, the measure channel and `rows_from_pool` all key on an
-   integer. So each row carries BOTH: `pid` (a stable CRC32 of the code, so the same SKU gets the
-   same id on every pull and across processes — never an enumeration index, which would reshuffle
-   whenever the catalogue changes) and `code`, the real business key, as a visible column.
-   `_assert_no_pid_collision` fails the BUILD rather than the read: two SKUs sharing a pid would
-   silently merge in every downstream set operation, and a loud build failure is the only version
-   of that anyone would notice.
-
-2. **THE SCOPE RULE — inventory columns are CONSOLIDATED and are therefore OMITTED for a
-   BU-scoped caller.** `products.directory(t, team_id)` is brand-shaped; `inventory.sku_inventory`
-   is explicitly NOT (its own docstring: "on-hand stock is one physical warehouse, not
-   brand-tagged"). Joining them for a Fisch-only user would put BU-shaped revenue beside
-   company-wide stock IN THE SAME ROW — the mixed-scope value defect wave 15's amendment 3 exists
-   for, arriving through a different door. The honest options were "omit" or "label the columns
-   company-wide"; omit is the fail-closed one, and a column that is absent asks a question,
-   whereas a column that is silently company-wide answers one wrongly.
-
-3. **WHAT IS NOT HERE, NAMED RATHER THAN QUIETLY MISSING.** R4 lists ~20 fields. Vendor and
-   COUNTRY are not in Odoo at all — they live in the inventory WORKBOOK
-   ([[odoo-vendor-country-origin]]) and need a loader this module deliberately does not invent.
-   Margin % comes from `modules/pricing.table`, which is a heavier build (channel-rate cost
-   allocation) and is left for the wave that needs it. `validate()` reconciles what SHIPS; it
-   does not pretend to cover columns that are absent.
-
-4. **THE POOL IS CATALOGUE-FIRST, WITH REVENUE LEFT-JOINED** (wave 29, owner item 22 / R12,
-   2026-08-11). It was `for r in products.directory(...)` — and `directory()`'s row set IS the
-   union of two revenue read-groups, so **a SKU that never sold could not exist** and the grid
-   showed **2,717** of **5,875** active products. Three things that will be re-derived otherwise:
-
-     · ⛔ THE CAUSE IS A JOIN, NOT A LIMIT. No row cap exists on this path. Removing the date
-       window from `directory()` would ALSO be wrong twice: it breaks four SKU-health metrics
-       that legitimately want a sales window, and it lands at 3,327 (all-time-sold), because
-       ~2,550 active SKUs have never sold in wholesale scope at all.
-     · ⭐ REVENUE ON A NEVER-SOLD ROW IS **BLANK, NOT $0** (R12). A row that appears in the
-       revenue universe carries measured numbers INCLUDING a real 0.0 — it sold last year and
-       not this one, and that zero is a measurement. A row that appears in NO revenue read
-       carries `None`, which the wire keeps (`aios_grid._round` passes None through) and the
-       client renders as an empty cell. Blank is an admission; zero is a measurement.
-     · ⚠ A BU-SCOPED CALLER NOW SEES THE WHOLE CATALOGUE, with ITS OWN revenue and blanks where
-       that BU never sold. That is not decision 2's mixed-scope defect: the catalogue is the ROW
-       UNIVERSE, not a company-wide VALUE sitting beside a BU-shaped one. `product.product`
-       carries no team, so a catalogue cannot be BU-shaped at all — which is exactly why the two
-       sources are JOINED rather than merged.
-"""
-import json
-import zlib
-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
-
-#: POOL-ROW KEYS that exist ONLY on a consolidated pull. See decision 2.
-#: `cover_gap_d` / `buy_now` (wave 17) join it because both are computed FROM `dos`, and a buy
-#: signal built on a stock number the caller cannot see would be a recommendation nobody could
-#: check ([[no-unverifiable-aggregates]]).
-#:
-#: ⚠ ROW KEYS, NOT FIELDS, and the distinction started mattering on 2026-08-03. Two readers:
-#: `verify_perm_scope` asserts the shape of a POOL ROW against this, and `routes_products`
-#: narrows the FIELD list with it. Since owner item 5 `buy_now` is a row key with no Field —
-#: computed as `validate()`'s oracle, projected onto no wire — so it belongs here for the first
-#: reader and is inert for the second. Removing it would stop the scope gate proving that a
-#: BU-scoped pull withholds it.
-#:
-#: ⭐⭐ OWNER RULING 2026-08-11 — THIS SET IS NOW EMPTY, AND THAT IS THE POINT. Verbatim:
-#: *"Just scope any inventory with Sales from Fisch, leave the rest."* Withholding the whole
-#: inventory block from a BU-scoped reader meant a Fisch salesperson could not see whether
-#: anything was IN STOCK, which is the first question they ask. The ruling splits the block by
-#: what a business unit can actually shape:
-#:
-#:   * `on_hand` / `unit_cost` / `inv_value` — ONE physical warehouse, no Fisch shelf and no
-#:     Royal shelf. Served UNSCOPED to everybody, identical in both pulls. ("leave the rest")
-#:   * `qty_ltm` / `dos` / `stock_bucket` / `cover_gap_d` / `buy_now` — all SALES-derived, so a
-#:     BU-scoped pull recomputes them from THAT unit's LTM units. ("scope any inventory with
-#:     Sales from Fisch")
-#:
-#: This deliberately relaxes decision 2's "never a company-wide value beside a BU-shaped one":
-#: stock is not a value a BU can own, and a column that is absent for a Fisch reader asks a
-#: question they cannot answer anywhere else in the product. `verify_perm_scope` no longer
-#: asserts the columns are WITHHELD — it asserts the split above, which is a stronger claim and
-#: cannot pass on an empty scoped payload (the shape the old rule and an outage share).
-CONSOLIDATED_ONLY = ()
-
-#: ⛔ POOL-ROW KEYS THAT DELIBERATELY HAVE NO FIELD — they must never reach a browser.
-#:
-#: `rows_from_pool` projects strictly through the field contract, so "no Field" already means
-#: "no cell on the wire". This tuple makes that a CHECKED fact rather than a consequence nobody
-#: is watching: `verify_perm_scope` asserts every member is absent from BOTH product contracts,
-#: and that every OTHER `CONSOLIDATED_ONLY` key is present in the consolidated one.
-#:
-#: Written because the two tuples silently diverged the moment owner item 5 retired `buy_now`'s
-#: Field while keeping its computation, and the gate — which was asserting a FIELD property from
-#: a ROW-key list — went red with no way to tell a deliberate divergence from a dropped column.
-UNSHIPPED_ROW_KEYS = ("buy_now",)
-
-#: Wave 17 (owner item 13, ruling R3) — the SUPPLIER MASTER, from the curated mastersheet map
-#: `procurement_suppliers.json` (3,963 SKUs; supplier on 3,624, lead time on 3,563). NOT Odoo:
-#: the owner confirmed this data came from the Inventory System Mastersheet, which is why
-#: `modules/product_data`'s header said Vendor/Country were "NOT HERE, named rather than
-#: quietly missing" and needed "a loader this module deliberately does not invent". This is
-#: that loader.
-#:
-#: ⛔ THESE ARE CONTRACT COLUMNS, NOT USER-CREATED FIELDS, AND THE REASON IS A PERMISSION FACT.
-#: A user-created field and its values live in the PER-USER strata (`table_store.workspace`
-#: reads `store.get(key)[username]`); only VIEWS are shared. So a shared "Buy list" view that
-#: filtered on a user-created column would, for every OTHER account, name a column that does not
-#: 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.
-#:
-#: ⭐⭐ 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 = {}
-
-
-def supplier_master():
-    """`{code: {supplier, lead_days, origin_country, first_cost}}`, read once per process.
-
-    Degrades to `{}` when the file is unreadable, matching `_inventory_by_code`: a product table
-    that will not render because a master map is missing is a worse failure than one with blank
-    supplier columns.
-    """
-    if _SUPPLIER_CACHE:
-        return _SUPPLIER_CACHE
-    try:
-        raw = json.loads(_SUPPLIER_MAP_PATH.read_text(encoding="utf-8"))
-    except Exception:
-        return {}
-    for code, meta in (raw or {}).items():
-        if not isinstance(meta, dict):
-            continue
-        lead = meta.get("lead")
-        _SUPPLIER_CACHE[str(code)] = {
-            "supplier": (meta.get("vendor") or "") or None,
-            "lead_days": int(lead) if isinstance(lead, (int, float)) else None,
-            "origin_country": (meta.get("country") or "") or None,
-            "first_cost": meta.get("first_cost"),
-        }
-    return _SUPPLIER_CACHE
-
-#: Wave 16 C-TOPIC — the PRODUCT table's OWN workspace bucket. ⛔ Never the customer one:
-#: product pids are CRC32 hashes of SKU codes and customer pids are Odoo partner ids, so in a
-#: SHARED overlay bucket a hash collision would silently write a product note onto somebody's
-#: customer (or the reverse). Separate store keys make that structurally impossible, which is
-#: 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'
-
-_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):
-    """A stable integer id for a SKU code. CRC32, masked to 31 bits so it is always positive and
-    always JSON-safe. Stable across processes and pulls, which an enumeration index is not."""
-    return zlib.crc32(str(code).encode("utf-8")) & 0x7FFFFFFF
-
-
-def _assert_no_pid_collision(rows):
-    """Two SKUs sharing a pid would MERGE in every set operation downstream — cohort membership,
-    allowed_pids, the measure channel — and nothing would report it. Fail the build instead."""
-    seen = {}
-    for r in rows:
-        prior = seen.get(r["pid"])
-        if prior is not None and prior != r["code"]:
-            raise ValueError(
-                f"product_data: pid collision — {prior!r} and {r['code']!r} both hash to "
-                f"{r['pid']}. Downstream set operations would merge them silently; widen the id "
-                f"before shipping this catalogue.")
-        seen[r["pid"]] = r["code"]
-
-
-def _inventory_by_code(t):
-    """`{code: {...}}` from the inventory module, or `{}` if it cannot be read.
-
-    Degrades to empty rather than raising, matching `customer_data._pool_build`'s treatment of
-    its own slow families: a product table that will not render because inventory is momentarily
-    unreachable is a worse failure than one with blank stock columns.
-    """
-    try:
-        import modules.inventory as inventory
-        return inventory.sku_inventory(t=t) or {}
-    except Exception:
-        return {}
-
-
-def _bu_ltm_share(t, team_id):
-    """`{code: 0.0..1.0}` — this unit's SHARE of the SKU's last-twelve-months units.
-
-    ⭐ OWNER 2026-08-11: *"scope any inventory with Sales from Fisch"*. The velocity half of the
-    inventory block has to be re-shaped by a BU fact, and this is that fact.
-
-    ⛔ A SHARE, NOT THE UNIT COUNT ITSELF — AND THE REASON IS A MEASURED IMPOSSIBILITY. My first
-    version returned `products._sku_rev(...)['qty']` and used it directly as the scoped `qty_ltm`,
-    leaving the consolidated column on `inventory.sku_inventory`'s own figure. Two readers of one
-    question ([[one-question-two-normalizers]]): they disagree, and on 5 SKUs of 5,871 the live
-    check found **Fisch's LTM units EXCEEDING the company's** — a subset larger than its superset,
-    which no reader could explain and no reconciliation could survive.
-
-    Both halves of the ratio come from the SAME read here, so the share is in [0, 1] by
-    construction and the scoped figure can never exceed the consolidated one. It also leaves the
-    consolidated column exactly as it was — the Inventory page and the Product grid still agree
-    about company-wide units, which is what "leave the rest" asked for.
-
-    `all_qty == 0` implies `bu_qty == 0` (same reader), so a share of 0 is the honest answer for
-    "this unit never sold it": `_bucket` turns that into 'No recent sales', not zero cover.
-
-    Degrades to `{}` on any failure, matching `_inventory_by_code` — and a missing code then takes
-    the `_DEFAULT_SHARE` below rather than a silent 0.
-    """
-    try:
-        f, to = P.ltm(t)
-        allq = {code: (r.get('qty') or 0.0)
-                for code, r in (products._sku_rev(f, to, None) or {}).items()}
-        buq = {code: (r.get('qty') or 0.0)
-               for code, r in (products._sku_rev(f, to, team_id) or {}).items()}
-    except Exception:
-        return {}
-    out = {}
-    for code, total in allq.items():
-        out[code] = min(1.0, max(0.0, (buq.get(code, 0.0) / total))) if total > 0 else 0.0
-    return out
-
-
-#: What a SKU absent from the LTM sales read is worth to a business unit. ZERO — it did not sell
-#: in anybody's book over the window, so no unit can claim its velocity. Named rather than
-#: inlined so the choice is visible: the alternative (1.0, "assume it is all ours") would print
-#: company-wide cover on a BU grid, which is the mixed-scope defect this whole rule avoids.
-_DEFAULT_SHARE = 0.0
-
-
-def _rescope_inventory(e, share):
-    """`(qty_ltm, dos, bucket)` recomputed for ONE business unit's sales rate.
-
-    The formulas are `inventory.sku_inventory`'s, applied to a BU-shaped numerator — NOT a second
-    idea of what days-of-supply means. `_bucket` is imported from there for the same reason: two
-    copies of a threshold table is how the Product grid and the Inventory page start disagreeing
-    about which SKUs are dead.
-
-    ⚠ `on_hand` is whatever the warehouse holds, unscoped — so a Fisch reader's `dos` answers
-    "how long does ALL our stock last at Fisch's rate", which is the question a Fisch salesperson
-    actually has. It is deliberately NOT a pro-rated share of the shelf: there is no such shelf,
-    and inventing one would put a number on screen that no Odoo query could reproduce.
-    """
-    on_hand = e.get("on_hand")
-    if on_hand is None:
-        return None, None, None          # no inventory row for this SKU: blank, never zero
-    qty = float(e.get("qty_ltm") or 0.0) * float(share or 0.0)
-    daily = qty / 365.0
-    if daily > 0:
-        dos_raw = on_hand / daily
-    else:
-        dos_raw = float('inf') if on_hand > 0 else 0.0
-    try:
-        import modules.inventory as inventory
-        bucket = inventory._bucket(dos_raw, on_hand, qty)
-    except Exception:
-        bucket = None
-    return qty, (None if dos_raw == float('inf') else round(float(dos_raw), 0)), bucket
-
-
-def _catalogue_by_code():
-    """`{code: {'product', 'category'}}` — the CATALOGUE universe this pool is built from.
-
-    ⛔ UNLIKE `_inventory_by_code`, THIS ONE RAISES, and the asymmetry is the whole point.
-    Inventory degrades to `{}` because a product table with blank stock columns beats one that
-    will not render. The CATALOGUE is not a column — it is the ROW SET. A catalogue read that
-    failed quietly would drop the grid straight back to the sold-only 2,717 with every gate
-    green and nothing on screen saying so, which is the defect this seam exists to end
-    ([[gate-can-report-green-on-nothing]]). `routes_products._pool_for` already turns the raise
-    into a 503 that names the cause, so the loud failure has somewhere honest to land.
-
-    It exists as a `pd`-level function rather than an inline `products.catalogue()` call for the
-    same reason `_inventory_by_code` does: it is the seam `verify_perm_scope`'s section H stubs
-    to build a pool without Odoo.
-    """
-    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`.
-
-    CATALOGUE-FIRST, REVENUE LEFT-JOINED (R12 — see decision 4 in the module header). The row set
-    is `products.catalogue()`; `products.directory()` supplies the revenue columns for the SKUs
-    that sold in its window and contributes NO rows of its own.
-
-    `team_id` shapes the revenue columns exactly as it does for customers (`products.directory`
-    passes it into `_sku_rev`), which is why `core.perm_scope.derive_pool_scope` must keep
-    driving it rather than a post-filter deciding the BU. It does NOT shape the row set: a
-    catalogue has no team.
-    """
-    t = t or P.today()
-    consolidated = team_id is None
-    # ⭐ OWNER 2026-08-11: read inventory on EVERY pull, not just a consolidated one. The stock
-    # itself is company-wide; only the sales-derived half is re-scoped, by `_rescope_inventory`.
-    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
-    # out. `validate()` asserts that of Odoo rather than assuming it, and reports the revenue
-    # that therefore sits outside the grid (MEASURED 2026-08-11: 3 codes, $0.00 YTD / $294.50 LY).
-    rev = {r["code"]: r for r in products.directory(t=t, team_id=team_id)}
-
-    rows = []
-    for code, meta in cat.items():
-        r = rev.get(code)
-        row = {
-            "pid": sku_pid(code),
-            "code": code,
-            # ⭐ ONE source for the name and the category, the CATALOGUE — not the sale line's
-            # m2o. For a re-SKUed code the line's name can be the ARCHIVED record's; the active
-            # record's `display_name` is the current truth, and it is the same string for every
-            # SKU that is not re-SKUed. `directory()` derives the category identically.
-            "product": meta.get("product") or code,
-            "category": meta.get("category") or "(uncategorized)",
-            # ⭐⭐ W33-T43 (R2 / amendment A2) — ODOO'S OWN PRODUCT ID, beside the hashed `pid`.
-            # R2 retires `ut_odoo_products` onto this key and keeps every data column it had; this
-            # is that column. ⛔ NOT DERIVABLE DOWNSTREAM: `pid` is `crc32(default_code)` here,
-            # unlike a customer row whose `pid` IS the partner id, so `aios_grid.py` cannot recover
-            # it and it has to be carried from `products.catalogue()`.
-            # ⚠ `None`, never 0, when the catalogue somehow has no id — 0 is a real Odoo id.
-            "product_id": meta.get("id"),
-            # ⭐ R12 — BLANK, NEVER $0, on a SKU no revenue read ever saw. A row that IS in `rev`
-            # keeps its measured numbers including a real 0.0 (it sold last year, not this one).
-            "rev_ytd": r.get("rev_ytd", 0.0) if r else None,
-            "rev_ly": r.get("rev_ly", 0.0) if r else None,
-            "yoy_pct": r.get("yoy_pct") if r else 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({
-            "supplier": s.get("supplier") or "(none)",
-            "lead_days": s.get("lead_days"),
-            "origin_country": s.get("origin_country") or "(none)",
-            "first_cost": s.get("first_cost"),
-        })
-        e = inv.get(code) or {}
-        if consolidated:
-            qty_ltm, dos, bucket = e.get("qty_ltm"), e.get("dos"), e.get("bucket")
-        else:
-            qty_ltm, dos, bucket = _rescope_inventory(e, bu_share.get(code, _DEFAULT_SHARE))
-        row.update({
-            # UNSCOPED on purpose (owner 2026-08-11): one warehouse, no per-brand shelf.
-            "on_hand": e.get("on_hand"),
-            "unit_cost": e.get("unit_cost"),
-            "inv_value": e.get("inv_value"),
-            # SCOPED: these three are functions of how fast THIS unit sells the SKU.
-            "qty_ltm": qty_ltm,
-            "dos": dos,
-            "stock_bucket": bucket,
-        })
-        # THE BUY TRIGGER (R3), ported from `modules/procurement`'s lead-time-cover rule:
-        # buy when the shelf runs out before a reorder could land.
-        #
-        # ⚠ BLANK, NOT "OK", WHEN EITHER INPUT IS MISSING. 339 SKUs have no supplier and 400
-        # no lead time; `dos` is null for anything that never sells through. "We don't know"
-        # and "you're fine" are different sentences, and only one of them is safe to print
-        # beside a purchasing decision.
-        #
-        # ⛔ `buy_now` SHIPS NOWHERE ANY MORE, and is computed anyway. OWNER 2026-08-03: it
-        # is not a preset field — it is a formula over the two columns beside it, and the
-        # platform has a formula field type for exactly that. Its Field is gone from
-        # `aios_grid_fields.json`, and `rows_from_pool` projects rows STRICTLY through that
-        # contract, so no Field means no cell on the wire. Nothing renders this key.
-        #
-        # It stays computed because deleting it would delete the PROOF. `validate()` below
-        # reconciles the formula's predicate against this one, row for row, which is the only
-        # thing that makes "the same exact figures" a claim rather than an assertion — and
-        # this repo has the scar already (wave 17: archiving `ar` "would have DELETED the
-        # proof"). Two comparisons per SKU is what that costs.
-        #
-        # ⭐ READS THE SCOPED `dos`, NOT `e['dos']`. On a Fisch pull the cover gap must answer
-        # "does the shelf outlast a reorder AT FISCH'S RATE" — reading the consolidated figure
-        # here would print a buy signal computed from both units' velocity beside a days-of-supply
-        # computed from one, and the two columns would disagree on the same row.
-        lead = s.get("lead_days")
-        if isinstance(dos, (int, float)) and isinstance(lead, (int, float)) and lead > 0:
-            row["cover_gap_d"] = int(round(dos - lead))
-            row["buy_now"] = "Buy now" if dos < lead else "OK"
-        else:
-            row["cover_gap_d"] = None
-            row["buy_now"] = None
-        rows.append(row)
-
-    # `or 0.0` reads a BLANK as zero FOR SORTING ONLY — never for the cell. A never-sold SKU
-    # settles among the zero-revenue ones at the bottom, which is where it belongs; the stored
-    # value stays None so nothing downstream can mistake "we never saw a sale" for "we measured
-    # nothing sold".
-    rows.sort(key=lambda r: -(r["rev_ytd"] or 0.0))
-    _assert_no_pid_collision(rows)
-    return rows
-
-
-#: ⭐ THE BUY SIGNAL, AS THE FORMULA FIELD EVALUATES IT (owner, 2026-08-03).
-#:
-#: The owner's ruling was that "Buy signal" is not a preset field — it is a formula over two
-#: columns the product table already carries, and the platform has a formula field type for it.
-#: The formula, verbatim, is what `_seed_wave17.BUY_SIGNAL_FORMULA` creates and what the JSON
-#: contract's `_product_removed_buy_now` note records:
-#:
-#:     IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), "")
-#:
-#: This function is a PORT of how `customer-grid/formulaEngine.ts` evaluates that tree, not a
-#: restatement of the business rule — that is the whole point, because the two could drift and
-#: `validate()` is where the drift must show. Three engine behaviours it reproduces exactly:
-#:
-#:   · a `ref` to a missing/non-numeric cell is None (`case "ref"` returns null for anything
-#:     that is not a finite number or a string);
-#:   · `cmp` returns BLANK unless BOTH sides read as numbers — it never coerces a blank to 0,
-#:     which is the difference between this and a filter engine's `toNum(null) === 0`;
-#:   · `IF` with a non-boolean condition returns BLANK ("no truthiness"), so a blank comparison
-#:     propagates out as a blank cell rather than taking the false branch.
-BUY_SIGNAL_FORMULA = 'IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), "")'
-
-
-def _buy_signal_formula(row):
-    """Evaluate `BUY_SIGNAL_FORMULA` over one pool row -> 'Buy now' | 'OK' | '' (blank)."""
-    def num(v):
-        # The engine's `ref` + `asNumber`: booleans are not values here, and a non-finite
-        # number is null. `isinstance(True, int)` is True in Python, so bool is excluded first.
-        if isinstance(v, bool) or not isinstance(v, (int, float)):
-            return None
-        return v if v == v and v not in (float('inf'), float('-inf')) else None
-
-    lead, dos = num(row.get("lead_days")), num(row.get("dos"))
-    if lead is None:                 # `{lead_days} > 0` is blank -> IF(blank, …) is blank
-        return ""
-    if not lead > 0:
-        return ""                    # the formula's own else-branch
-    if dos is None:                  # `{dos} < {lead_days}` is blank -> IF(blank, …) is blank
-        return ""
-    return "Buy now" if dos < lead else "OK"
-
-
-def validate(team_id=None, t=None):
-    """Reconcile what SHIPS to an independent aggregate — the platform's own rule that a number
-    which does not tie to Odoo does not ship.
-
-    ⛔⛔ THE POPULATION LEG IS NEW, AND IT IS HERE BECAUSE THIS FUNCTION USED TO BE SELF-SEALING
-    (wave 29, contract C8). It reconciled Σ per-SKU YTD revenue against `products._sku_rev` — the
-    same function `pool()` built its rows from. BOTH SIDES CAME FROM THE JOIN, so the oracle could
-    not see a missing row, and a grid holding 2,717 of 5,875 active products passed for a wave.
-    No gate anywhere asserted a pool row COUNT against an independent Odoo `search_count` either.
-    That is the leg below, and it is the control that would have caught it
-    ([[no-unverifiable-aggregates]]).
-
-    ⚠ The revenue leg was NOT deleted with it — it answers a different question ("did the join
-    lose money?") and is still the right shape for that one. What changed is that it now has to
-    account for revenue belonging to codes NO ACTIVE PRODUCT CARRIES, because R12 keeps archived
-    products out of the grid; the total is decomposed rather than compared loosely, so a growing
-    "outside the grid" figure shows up as a number rather than as slack in a tolerance.
-
-    Still deliberately NOT covered, and said rather than implied: the inventory columns are a
-    different module's reconciliation, and they are absent on a scoped pull anyway.
-    """
-    t = t or P.today()
-    rows = pool(team_id=team_id, t=t)
-
-    # ⭐⭐ THE POPULATION, AGAINST AN ORACLE THAT CANNOT SEE OUR JOIN. A bare Odoo count of active
-    # products, asked fresh — not a `len()` over anything this module or `products.catalogue()`
-    # built. NC: drop one row from `pool()` and this goes red; that is the whole point of it.
-    n_active = products.catalogue_count()
-    checks = [{
-        "check": "the pool holds one row per ACTIVE product (R12) — row count == an INDEPENDENT "
-                 "Odoo search_count('product.product', active=True)",
-        "ours": len(rows), "theirs": n_active, "ok": len(rows) == n_active,
-    }]
-
-    yf, yt = P.ytd(t)
-    sku_rev = products._sku_rev(yf, yt, team_id) or {}
-    in_pool = {r["code"] for r in rows}
-    outside = {c: v for c, v in sku_rev.items() if c not in in_pool}
-    ours = round(sum(r["rev_ytd"] or 0.0 for r in rows), 2)
-    theirs = round(sum(v.get("rev", 0.0) for v in sku_rev.values()), 2)
-    dropped = round(sum(v.get("rev", 0.0) for v in outside.values()), 2)
-    checks.append({
-        "check": "Σ per-SKU YTD revenue in the grid + Σ YTD revenue of codes no ACTIVE product "
-                 "carries == modules.products._sku_rev over the same window",
-        "ours": round(ours + dropped, 2), "theirs": theirs,
-        "ok": abs((ours + dropped) - theirs) < 0.01,
-        "detail": {"in_the_grid": ours, "outside_the_grid": dropped,
-                   "codes_outside": len(outside)},
-    })
-    # ⛔ AND THE EXCLUSION IS ASSERTED, NOT ASSUMED. "Everything I dropped was archived" is
-    # trivially true when checked against the dict that did the dropping — that is the
-    # self-sealing shape all over again. So it is asked of ODOO. A code here that a live ACTIVE
-    # product carries means `products.catalogue()` missed a row that has revenue, which is the
-    # 2,717 defect returning in a smaller costume.
-    # ⚠ `pid:N` keys are not `default_code`s and are skipped: an UNCODED active product is in the
-    # catalogue under its own `pid:N` key and therefore cannot be in `outside` at all.
-    coded_outside = sorted(c for c in outside if not str(c).startswith("pid:"))
-    still_active = (O.get_odoo().search_count(
-        'product.product', [('active', '=', True), ('default_code', 'in', coded_outside)])
-        if coded_outside else 0)
-    checks.append({
-        "check": "every SKU with revenue but NO grid row is genuinely ARCHIVED (R12: archived "
-                 "stay out) — asked of Odoo, never of the catalogue that did the dropping",
-        "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
-    # an input was missing, so the blank leg is checked as hard as the other two.
-    if team_id is None:                      # consolidated only — the inputs exist only there
-        buy = [r for r in rows if r.get("buy_now") == "Buy now"]
-        ok_rows = [r for r in rows if r.get("buy_now") == "OK"]
-        blank = [r for r in rows if r.get("buy_now") is None]
-        mis = sum(1 for r in buy if not (r["dos"] < r["lead_days"]))
-        mis += sum(1 for r in ok_rows if not (r["dos"] >= r["lead_days"]))
-        # A blank must be UNKNOWN — never a row we could have answered and quietly did not.
-        mis += sum(1 for r in blank
-                   if isinstance(r.get("dos"), (int, float))
-                   and isinstance(r.get("lead_days"), (int, float)) and r["lead_days"] > 0)
-        checks.append({
-            "check": "Buy signal partitions the catalogue (buy + ok + unknown == rows, none "
-                     "misclassified)",
-            "ours": len(buy) + len(ok_rows) + len(blank) - mis, "theirs": len(rows),
-            "ok": mis == 0 and len(buy) + len(ok_rows) + len(blank) == len(rows),
-            "detail": {"buy_now": len(buy), "ok": len(ok_rows), "unknown": len(blank),
-                       "misclassified": mis},
-        })
-        # ⭐ OWNER 2026-08-03 — "use the formula fields to come up to the same EXACT figures".
-        #
-        # This is that sentence, as a check. The retired preset column and the formula that
-        # replaces it must agree on every SKU, in all three states, or the replacement is not a
-        # replacement. `_buy_signal_formula` is a line-by-line port of the client formula
-        # engine's evaluation of
-        #
-        #     IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), "")
-        #
-        # including the part that is easy to get wrong: a comparison against a BLANK is blank,
-        # never a coerced 0. (The client engine's `cmp` returns null unless both sides read as
-        # numbers, and `IF` refuses a non-boolean condition — so a missing `dos` yields "" and
-        # not "Buy now". A filter engine would have said `0 < 30` and swept in every SKU that
-        # never sells through; the formula engine does not, and this check is what holds it.)
-        #
-        # ⚠ It compares SETS OF SKUs, not counts. Two different partitions can share a shape.
-        disagree = sorted(r["code"] for r in rows
-                          if (r.get("buy_now") or "") != _buy_signal_formula(r))
-        checks.append({
-            "check": 'Buy signal as a FORMULA field == the retired preset column, per SKU '
-                     '(IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), ""))',
-            "ours": len(rows) - len(disagree), "theirs": len(rows),
-            "ok": not disagree,
-            "detail": {"disagreeing_skus": disagree[:10], "n_disagree": len(disagree)},
-        })
-        # The other half of "the same figures": the SHARED Buy list view can no longer filter on
-        # the retired column, and its replacement conditions must select the same SKUs. They are
-        # `dos isNotEmpty AND lead_days isNotEmpty AND lead_days > 0 AND dos < lead_days`
-        # (_seed_wave17.views), so this reproduces exactly that conjunction.
-        #
-        # ⛔ THE NEGATIVE CONTROL IS WHY THIS IS NOT `cover_gap_d < 0`, which reads like the
-        # obvious filter and is WRONG: `cover_gap_d` is `int(round(dos - lead))`, so a genuine
-        # gap of -0.4 days rounds to 0 and that SKU drops off a buy list it belongs on.
-        view_rows = {r["code"] for r in rows
-                     if isinstance(r.get("dos"), (int, float))
-                     and isinstance(r.get("lead_days"), (int, float))
-                     and r["lead_days"] > 0 and r["dos"] < r["lead_days"]}
-        signal_rows = {r["code"] for r in buy}
-        rounding_would_miss = sorted(
-            c for c in signal_rows
-            if next((r for r in rows if r["code"] == c), {}).get("cover_gap_d") == 0)
-        checks.append({
-            "check": "Buy list view conditions (dos/lead_days, no retired column) select "
-                     "exactly the Buy-now SKUs",
-            "ours": len(view_rows), "theirs": len(signal_rows),
-            "ok": view_rows == signal_rows,
-            "detail": {"only_in_view": sorted(view_rows - signal_rows)[:10],
-                       "only_in_signal": sorted(signal_rows - view_rows)[:10],
-                       # Reported, not asserted: how many SKUs a `cover_gap_d < 0` filter would
-                       # have silently dropped. 0 today does not make that filter correct.
-                       "cover_gap_rounds_to_zero": len(rounding_would_miss)},
-        })
-    return checks
+"""modules/product_data.py — the PRODUCT table's pool (wave 15 item 9/10, contract C-TOPIC).
+
+The second object on the table-page factory: same grid, same engine, same permission wall — the
+only difference is the field schema and the identity. `modules/customer_data.pool()` is the
+template and this deliberately mirrors its signature and its row shape.
+
+⛔ THREE DECISIONS THIS FILE HAD TO MAKE, EACH RECORDED BECAUSE A LATER READER WILL WONDER.
+
+1. **THE IDENTITY IS A SKU CODE, WHICH IS A STRING, AND THE GRID WANTS AN INTEGER `pid`.**
+   Cohort membership, `allowed_pids`, the measure channel and `rows_from_pool` all key on an
+   integer. So each row carries BOTH: `pid` (a stable CRC32 of the code, so the same SKU gets the
+   same id on every pull and across processes — never an enumeration index, which would reshuffle
+   whenever the catalogue changes) and `code`, the real business key, as a visible column.
+   `_assert_no_pid_collision` fails the BUILD rather than the read: two SKUs sharing a pid would
+   silently merge in every downstream set operation, and a loud build failure is the only version
+   of that anyone would notice.
+
+2. **THE SCOPE RULE — inventory columns are CONSOLIDATED and are therefore OMITTED for a
+   BU-scoped caller.** `products.directory(t, team_id)` is brand-shaped; `inventory.sku_inventory`
+   is explicitly NOT (its own docstring: "on-hand stock is one physical warehouse, not
+   brand-tagged"). Joining them for a Fisch-only user would put BU-shaped revenue beside
+   company-wide stock IN THE SAME ROW — the mixed-scope value defect wave 15's amendment 3 exists
+   for, arriving through a different door. The honest options were "omit" or "label the columns
+   company-wide"; omit is the fail-closed one, and a column that is absent asks a question,
+   whereas a column that is silently company-wide answers one wrongly.
+
+3. **WHAT IS NOT HERE, NAMED RATHER THAN QUIETLY MISSING.** R4 lists ~20 fields. Vendor and
+   COUNTRY are not in Odoo at all — they live in the inventory WORKBOOK
+   ([[odoo-vendor-country-origin]]) and need a loader this module deliberately does not invent.
+   Margin % comes from `modules/pricing.table`, which is a heavier build (channel-rate cost
+   allocation) and is left for the wave that needs it. `validate()` reconciles what SHIPS; it
+   does not pretend to cover columns that are absent.
+
+4. **THE POOL IS CATALOGUE-FIRST, WITH REVENUE LEFT-JOINED** (wave 29, owner item 22 / R12,
+   2026-08-11). It was `for r in products.directory(...)` — and `directory()`'s row set IS the
+   union of two revenue read-groups, so **a SKU that never sold could not exist** and the grid
+   showed **2,717** of **5,875** active products. Three things that will be re-derived otherwise:
+
+     · ⛔ THE CAUSE IS A JOIN, NOT A LIMIT. No row cap exists on this path. Removing the date
+       window from `directory()` would ALSO be wrong twice: it breaks four SKU-health metrics
+       that legitimately want a sales window, and it lands at 3,327 (all-time-sold), because
+       ~2,550 active SKUs have never sold in wholesale scope at all.
+     · ⭐ REVENUE ON A NEVER-SOLD ROW IS **BLANK, NOT $0** (R12). A row that appears in the
+       revenue universe carries measured numbers INCLUDING a real 0.0 — it sold last year and
+       not this one, and that zero is a measurement. A row that appears in NO revenue read
+       carries `None`, which the wire keeps (`aios_grid._round` passes None through) and the
+       client renders as an empty cell. Blank is an admission; zero is a measurement.
+     · ⚠ A BU-SCOPED CALLER NOW SEES THE WHOLE CATALOGUE, with ITS OWN revenue and blanks where
+       that BU never sold. That is not decision 2's mixed-scope defect: the catalogue is the ROW
+       UNIVERSE, not a company-wide VALUE sitting beside a BU-shaped one. `product.product`
+       carries no team, so a catalogue cannot be BU-shaped at all — which is exactly why the two
+       sources are JOINED rather than merged.
+"""
+import json
+import zlib
+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
+
+#: POOL-ROW KEYS that exist ONLY on a consolidated pull. See decision 2.
+#: `cover_gap_d` / `buy_now` (wave 17) join it because both are computed FROM `dos`, and a buy
+#: signal built on a stock number the caller cannot see would be a recommendation nobody could
+#: check ([[no-unverifiable-aggregates]]).
+#:
+#: ⚠ ROW KEYS, NOT FIELDS, and the distinction started mattering on 2026-08-03. Two readers:
+#: `verify_perm_scope` asserts the shape of a POOL ROW against this, and `routes_products`
+#: narrows the FIELD list with it. Since owner item 5 `buy_now` is a row key with no Field —
+#: computed as `validate()`'s oracle, projected onto no wire — so it belongs here for the first
+#: reader and is inert for the second. Removing it would stop the scope gate proving that a
+#: BU-scoped pull withholds it.
+#:
+#: ⭐⭐ OWNER RULING 2026-08-11 — THIS SET IS NOW EMPTY, AND THAT IS THE POINT. Verbatim:
+#: *"Just scope any inventory with Sales from Fisch, leave the rest."* Withholding the whole
+#: inventory block from a BU-scoped reader meant a Fisch salesperson could not see whether
+#: anything was IN STOCK, which is the first question they ask. The ruling splits the block by
+#: what a business unit can actually shape:
+#:
+#:   * `on_hand` / `unit_cost` / `inv_value` — ONE physical warehouse, no Fisch shelf and no
+#:     Royal shelf. Served UNSCOPED to everybody, identical in both pulls. ("leave the rest")
+#:   * `qty_ltm` / `dos` / `stock_bucket` / `cover_gap_d` / `buy_now` — all SALES-derived, so a
+#:     BU-scoped pull recomputes them from THAT unit's LTM units. ("scope any inventory with
+#:     Sales from Fisch")
+#:
+#: This deliberately relaxes decision 2's "never a company-wide value beside a BU-shaped one":
+#: stock is not a value a BU can own, and a column that is absent for a Fisch reader asks a
+#: question they cannot answer anywhere else in the product. `verify_perm_scope` no longer
+#: asserts the columns are WITHHELD — it asserts the split above, which is a stronger claim and
+#: cannot pass on an empty scoped payload (the shape the old rule and an outage share).
+CONSOLIDATED_ONLY = ()
+
+#: ⛔ POOL-ROW KEYS THAT DELIBERATELY HAVE NO FIELD — they must never reach a browser.
+#:
+#: `rows_from_pool` projects strictly through the field contract, so "no Field" already means
+#: "no cell on the wire". This tuple makes that a CHECKED fact rather than a consequence nobody
+#: is watching: `verify_perm_scope` asserts every member is absent from BOTH product contracts,
+#: and that every OTHER `CONSOLIDATED_ONLY` key is present in the consolidated one.
+#:
+#: Written because the two tuples silently diverged the moment owner item 5 retired `buy_now`'s
+#: Field while keeping its computation, and the gate — which was asserting a FIELD property from
+#: a ROW-key list — went red with no way to tell a deliberate divergence from a dropped column.
+UNSHIPPED_ROW_KEYS = ("buy_now",)
+
+#: Wave 17 (owner item 13, ruling R3) — the SUPPLIER MASTER, from the curated mastersheet map
+#: `procurement_suppliers.json` (3,963 SKUs; supplier on 3,624, lead time on 3,563). NOT Odoo:
+#: the owner confirmed this data came from the Inventory System Mastersheet, which is why
+#: `modules/product_data`'s header said Vendor/Country were "NOT HERE, named rather than
+#: quietly missing" and needed "a loader this module deliberately does not invent". This is
+#: that loader.
+#:
+#: ⛔ THESE ARE CONTRACT COLUMNS, NOT USER-CREATED FIELDS, AND THE REASON IS A PERMISSION FACT.
+#: A user-created field and its values live in the PER-USER strata (`table_store.workspace`
+#: reads `store.get(key)[username]`); only VIEWS are shared. So a shared "Buy list" view that
+#: filtered on a user-created column would, for every OTHER account, name a column that does not
+#: 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.
+#:
+#: ⭐⭐ 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 = {}
+
+
+def supplier_master():
+    """`{code: {supplier, lead_days, origin_country, first_cost}}`, read once per process.
+
+    Degrades to `{}` when the file is unreadable, matching `_inventory_by_code`: a product table
+    that will not render because a master map is missing is a worse failure than one with blank
+    supplier columns.
+    """
+    if _SUPPLIER_CACHE:
+        return _SUPPLIER_CACHE
+    try:
+        raw = json.loads(_SUPPLIER_MAP_PATH.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    for code, meta in (raw or {}).items():
+        if not isinstance(meta, dict):
+            continue
+        lead = meta.get("lead")
+        _SUPPLIER_CACHE[str(code)] = {
+            "supplier": (meta.get("vendor") or "") or None,
+            "lead_days": int(lead) if isinstance(lead, (int, float)) else None,
+            "origin_country": (meta.get("country") or "") or None,
+            "first_cost": meta.get("first_cost"),
+        }
+    return _SUPPLIER_CACHE
+
+#: Wave 16 C-TOPIC — the PRODUCT table's OWN workspace bucket. ⛔ Never the customer one:
+#: product pids are CRC32 hashes of SKU codes and customer pids are Odoo partner ids, so in a
+#: SHARED overlay bucket a hash collision would silently write a product note onto somebody's
+#: customer (or the reverse). Separate store keys make that structurally impossible, which is
+#: 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'
+
+_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):
+    """A stable integer id for a SKU code. CRC32, masked to 31 bits so it is always positive and
+    always JSON-safe. Stable across processes and pulls, which an enumeration index is not."""
+    return zlib.crc32(str(code).encode("utf-8")) & 0x7FFFFFFF
+
+
+def _assert_no_pid_collision(rows):
+    """Two SKUs sharing a pid would MERGE in every set operation downstream — cohort membership,
+    allowed_pids, the measure channel — and nothing would report it. Fail the build instead."""
+    seen = {}
+    for r in rows:
+        prior = seen.get(r["pid"])
+        if prior is not None and prior != r["code"]:
+            raise ValueError(
+                f"product_data: pid collision — {prior!r} and {r['code']!r} both hash to "
+                f"{r['pid']}. Downstream set operations would merge them silently; widen the id "
+                f"before shipping this catalogue.")
+        seen[r["pid"]] = r["code"]
+
+
+def _inventory_by_code(t):
+    """`{code: {...}}` from the inventory module, or `{}` if it cannot be read.
+
+    Degrades to empty rather than raising, matching `customer_data._pool_build`'s treatment of
+    its own slow families: a product table that will not render because inventory is momentarily
+    unreachable is a worse failure than one with blank stock columns.
+    """
+    try:
+        import modules.inventory as inventory
+        return inventory.sku_inventory(t=t) or {}
+    except Exception:
+        return {}
+
+
+def _bu_ltm_share(t, team_id):
+    """`{code: 0.0..1.0}` — this unit's SHARE of the SKU's last-twelve-months units.
+
+    ⭐ OWNER 2026-08-11: *"scope any inventory with Sales from Fisch"*. The velocity half of the
+    inventory block has to be re-shaped by a BU fact, and this is that fact.
+
+    ⛔ A SHARE, NOT THE UNIT COUNT ITSELF — AND THE REASON IS A MEASURED IMPOSSIBILITY. My first
+    version returned `products._sku_rev(...)['qty']` and used it directly as the scoped `qty_ltm`,
+    leaving the consolidated column on `inventory.sku_inventory`'s own figure. Two readers of one
+    question ([[one-question-two-normalizers]]): they disagree, and on 5 SKUs of 5,871 the live
+    check found **Fisch's LTM units EXCEEDING the company's** — a subset larger than its superset,
+    which no reader could explain and no reconciliation could survive.
+
+    Both halves of the ratio come from the SAME read here, so the share is in [0, 1] by
+    construction and the scoped figure can never exceed the consolidated one. It also leaves the
+    consolidated column exactly as it was — the Inventory page and the Product grid still agree
+    about company-wide units, which is what "leave the rest" asked for.
+
+    `all_qty == 0` implies `bu_qty == 0` (same reader), so a share of 0 is the honest answer for
+    "this unit never sold it": `_bucket` turns that into 'No recent sales', not zero cover.
+
+    Degrades to `{}` on any failure, matching `_inventory_by_code` — and a missing code then takes
+    the `_DEFAULT_SHARE` below rather than a silent 0.
+    """
+    try:
+        f, to = P.ltm(t)
+        allq = {code: (r.get('qty') or 0.0)
+                for code, r in (products._sku_rev(f, to, None) or {}).items()}
+        buq = {code: (r.get('qty') or 0.0)
+               for code, r in (products._sku_rev(f, to, team_id) or {}).items()}
+    except Exception:
+        return {}
+    out = {}
+    for code, total in allq.items():
+        out[code] = min(1.0, max(0.0, (buq.get(code, 0.0) / total))) if total > 0 else 0.0
+    return out
+
+
+#: What a SKU absent from the LTM sales read is worth to a business unit. ZERO — it did not sell
+#: in anybody's book over the window, so no unit can claim its velocity. Named rather than
+#: inlined so the choice is visible: the alternative (1.0, "assume it is all ours") would print
+#: company-wide cover on a BU grid, which is the mixed-scope defect this whole rule avoids.
+_DEFAULT_SHARE = 0.0
+
+
+def _rescope_inventory(e, share):
+    """`(qty_ltm, dos, bucket)` recomputed for ONE business unit's sales rate.
+
+    The formulas are `inventory.sku_inventory`'s, applied to a BU-shaped numerator — NOT a second
+    idea of what days-of-supply means. `_bucket` is imported from there for the same reason: two
+    copies of a threshold table is how the Product grid and the Inventory page start disagreeing
+    about which SKUs are dead.
+
+    ⚠ `on_hand` is whatever the warehouse holds, unscoped — so a Fisch reader's `dos` answers
+    "how long does ALL our stock last at Fisch's rate", which is the question a Fisch salesperson
+    actually has. It is deliberately NOT a pro-rated share of the shelf: there is no such shelf,
+    and inventing one would put a number on screen that no Odoo query could reproduce.
+    """
+    on_hand = e.get("on_hand")
+    if on_hand is None:
+        return None, None, None          # no inventory row for this SKU: blank, never zero
+    qty = float(e.get("qty_ltm") or 0.0) * float(share or 0.0)
+    daily = qty / 365.0
+    if daily > 0:
+        dos_raw = on_hand / daily
+    else:
+        dos_raw = float('inf') if on_hand > 0 else 0.0
+    try:
+        import modules.inventory as inventory
+        bucket = inventory._bucket(dos_raw, on_hand, qty)
+    except Exception:
+        bucket = None
+    return qty, (None if dos_raw == float('inf') else round(float(dos_raw), 0)), bucket
+
+
+def _catalogue_by_code():
+    """`{code: {'product', 'category'}}` — the CATALOGUE universe this pool is built from.
+
+    ⛔ UNLIKE `_inventory_by_code`, THIS ONE RAISES, and the asymmetry is the whole point.
+    Inventory degrades to `{}` because a product table with blank stock columns beats one that
+    will not render. The CATALOGUE is not a column — it is the ROW SET. A catalogue read that
+    failed quietly would drop the grid straight back to the sold-only 2,717 with every gate
+    green and nothing on screen saying so, which is the defect this seam exists to end
+    ([[gate-can-report-green-on-nothing]]). `routes_products._pool_for` already turns the raise
+    into a 503 that names the cause, so the loud failure has somewhere honest to land.
+
+    It exists as a `pd`-level function rather than an inline `products.catalogue()` call for the
+    same reason `_inventory_by_code` does: it is the seam `verify_perm_scope`'s section H stubs
+    to build a pool without Odoo.
+    """
+    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`.
+
+    CATALOGUE-FIRST, REVENUE LEFT-JOINED (R12 — see decision 4 in the module header). The row set
+    is `products.catalogue()`; `products.directory()` supplies the revenue columns for the SKUs
+    that sold in its window and contributes NO rows of its own.
+
+    `team_id` shapes the revenue columns exactly as it does for customers (`products.directory`
+    passes it into `_sku_rev`), which is why `core.perm_scope.derive_pool_scope` must keep
+    driving it rather than a post-filter deciding the BU. It does NOT shape the row set: a
+    catalogue has no team.
+    """
+    t = t or P.today()
+    consolidated = team_id is None
+    # ⭐ OWNER 2026-08-11: read inventory on EVERY pull, not just a consolidated one. The stock
+    # itself is company-wide; only the sales-derived half is re-scoped, by `_rescope_inventory`.
+    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
+    # out. `validate()` asserts that of Odoo rather than assuming it, and reports the revenue
+    # that therefore sits outside the grid (MEASURED 2026-08-11: 3 codes, $0.00 YTD / $294.50 LY).
+    rev = {r["code"]: r for r in products.directory(t=t, team_id=team_id)}
+
+    rows = []
+    for code, meta in cat.items():
+        r = rev.get(code)
+        row = {
+            "pid": sku_pid(code),
+            "code": code,
+            # ⭐ ONE source for the name and the category, the CATALOGUE — not the sale line's
+            # m2o. For a re-SKUed code the line's name can be the ARCHIVED record's; the active
+            # record's `display_name` is the current truth, and it is the same string for every
+            # SKU that is not re-SKUed. `directory()` derives the category identically.
+            "product": meta.get("product") or code,
+            "category": meta.get("category") or "(uncategorized)",
+            # ⭐⭐ W33-T43 (R2 / amendment A2) — ODOO'S OWN PRODUCT ID, beside the hashed `pid`.
+            # R2 retires `ut_odoo_products` onto this key and keeps every data column it had; this
+            # is that column. ⛔ NOT DERIVABLE DOWNSTREAM: `pid` is `crc32(default_code)` here,
+            # unlike a customer row whose `pid` IS the partner id, so `aios_grid.py` cannot recover
+            # it and it has to be carried from `products.catalogue()`.
+            # ⚠ `None`, never 0, when the catalogue somehow has no id — 0 is a real Odoo id.
+            "product_id": meta.get("id"),
+            # ⭐ R12 — BLANK, NEVER $0, on a SKU no revenue read ever saw. A row that IS in `rev`
+            # keeps its measured numbers including a real 0.0 (it sold last year, not this one).
+            "rev_ytd": r.get("rev_ytd", 0.0) if r else None,
+            "rev_ly": r.get("rev_ly", 0.0) if r else None,
+            "yoy_pct": r.get("yoy_pct") if r else 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({
+            "supplier": s.get("supplier") or "(none)",
+            "lead_days": s.get("lead_days"),
+            "origin_country": s.get("origin_country") or "(none)",
+            "first_cost": s.get("first_cost"),
+        })
+        e = inv.get(code) or {}
+        if consolidated:
+            qty_ltm, dos, bucket = e.get("qty_ltm"), e.get("dos"), e.get("bucket")
+        else:
+            qty_ltm, dos, bucket = _rescope_inventory(e, bu_share.get(code, _DEFAULT_SHARE))
+        row.update({
+            # UNSCOPED on purpose (owner 2026-08-11): one warehouse, no per-brand shelf.
+            "on_hand": e.get("on_hand"),
+            "unit_cost": e.get("unit_cost"),
+            "inv_value": e.get("inv_value"),
+            # SCOPED: these three are functions of how fast THIS unit sells the SKU.
+            "qty_ltm": qty_ltm,
+            "dos": dos,
+            "stock_bucket": bucket,
+        })
+        # THE BUY TRIGGER (R3), ported from `modules/procurement`'s lead-time-cover rule:
+        # buy when the shelf runs out before a reorder could land.
+        #
+        # ⚠ BLANK, NOT "OK", WHEN EITHER INPUT IS MISSING. 339 SKUs have no supplier and 400
+        # no lead time; `dos` is null for anything that never sells through. "We don't know"
+        # and "you're fine" are different sentences, and only one of them is safe to print
+        # beside a purchasing decision.
+        #
+        # ⛔ `buy_now` SHIPS NOWHERE ANY MORE, and is computed anyway. OWNER 2026-08-03: it
+        # is not a preset field — it is a formula over the two columns beside it, and the
+        # platform has a formula field type for exactly that. Its Field is gone from
+        # `aios_grid_fields.json`, and `rows_from_pool` projects rows STRICTLY through that
+        # contract, so no Field means no cell on the wire. Nothing renders this key.
+        #
+        # It stays computed because deleting it would delete the PROOF. `validate()` below
+        # reconciles the formula's predicate against this one, row for row, which is the only
+        # thing that makes "the same exact figures" a claim rather than an assertion — and
+        # this repo has the scar already (wave 17: archiving `ar` "would have DELETED the
+        # proof"). Two comparisons per SKU is what that costs.
+        #
+        # ⭐ READS THE SCOPED `dos`, NOT `e['dos']`. On a Fisch pull the cover gap must answer
+        # "does the shelf outlast a reorder AT FISCH'S RATE" — reading the consolidated figure
+        # here would print a buy signal computed from both units' velocity beside a days-of-supply
+        # computed from one, and the two columns would disagree on the same row.
+        lead = s.get("lead_days")
+        if isinstance(dos, (int, float)) and isinstance(lead, (int, float)) and lead > 0:
+            row["cover_gap_d"] = int(round(dos - lead))
+            row["buy_now"] = "Buy now" if dos < lead else "OK"
+        else:
+            row["cover_gap_d"] = None
+            row["buy_now"] = None
+        rows.append(row)
+
+    # `or 0.0` reads a BLANK as zero FOR SORTING ONLY — never for the cell. A never-sold SKU
+    # settles among the zero-revenue ones at the bottom, which is where it belongs; the stored
+    # value stays None so nothing downstream can mistake "we never saw a sale" for "we measured
+    # nothing sold".
+    rows.sort(key=lambda r: -(r["rev_ytd"] or 0.0))
+    _assert_no_pid_collision(rows)
+    return rows
+
+
+#: ⭐ THE BUY SIGNAL, AS THE FORMULA FIELD EVALUATES IT (owner, 2026-08-03).
+#:
+#: The owner's ruling was that "Buy signal" is not a preset field — it is a formula over two
+#: columns the product table already carries, and the platform has a formula field type for it.
+#: The formula, verbatim, is what `_seed_wave17.BUY_SIGNAL_FORMULA` creates and what the JSON
+#: contract's `_product_removed_buy_now` note records:
+#:
+#:     IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), "")
+#:
+#: This function is a PORT of how `customer-grid/formulaEngine.ts` evaluates that tree, not a
+#: restatement of the business rule — that is the whole point, because the two could drift and
+#: `validate()` is where the drift must show. Three engine behaviours it reproduces exactly:
+#:
+#:   · a `ref` to a missing/non-numeric cell is None (`case "ref"` returns null for anything
+#:     that is not a finite number or a string);
+#:   · `cmp` returns BLANK unless BOTH sides read as numbers — it never coerces a blank to 0,
+#:     which is the difference between this and a filter engine's `toNum(null) === 0`;
+#:   · `IF` with a non-boolean condition returns BLANK ("no truthiness"), so a blank comparison
+#:     propagates out as a blank cell rather than taking the false branch.
+BUY_SIGNAL_FORMULA = 'IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), "")'
+
+
+def _buy_signal_formula(row):
+    """Evaluate `BUY_SIGNAL_FORMULA` over one pool row -> 'Buy now' | 'OK' | '' (blank)."""
+    def num(v):
+        # The engine's `ref` + `asNumber`: booleans are not values here, and a non-finite
+        # number is null. `isinstance(True, int)` is True in Python, so bool is excluded first.
+        if isinstance(v, bool) or not isinstance(v, (int, float)):
+            return None
+        return v if v == v and v not in (float('inf'), float('-inf')) else None
+
+    lead, dos = num(row.get("lead_days")), num(row.get("dos"))
+    if lead is None:                 # `{lead_days} > 0` is blank -> IF(blank, …) is blank
+        return ""
+    if not lead > 0:
+        return ""                    # the formula's own else-branch
+    if dos is None:                  # `{dos} < {lead_days}` is blank -> IF(blank, …) is blank
+        return ""
+    return "Buy now" if dos < lead else "OK"
+
+
+def validate(team_id=None, t=None):
+    """Reconcile what SHIPS to an independent aggregate — the platform's own rule that a number
+    which does not tie to Odoo does not ship.
+
+    ⛔⛔ THE POPULATION LEG IS NEW, AND IT IS HERE BECAUSE THIS FUNCTION USED TO BE SELF-SEALING
+    (wave 29, contract C8). It reconciled Σ per-SKU YTD revenue against `products._sku_rev` — the
+    same function `pool()` built its rows from. BOTH SIDES CAME FROM THE JOIN, so the oracle could
+    not see a missing row, and a grid holding 2,717 of 5,875 active products passed for a wave.
+    No gate anywhere asserted a pool row COUNT against an independent Odoo `search_count` either.
+    That is the leg below, and it is the control that would have caught it
+    ([[no-unverifiable-aggregates]]).
+
+    ⚠ The revenue leg was NOT deleted with it — it answers a different question ("did the join
+    lose money?") and is still the right shape for that one. What changed is that it now has to
+    account for revenue belonging to codes NO ACTIVE PRODUCT CARRIES, because R12 keeps archived
+    products out of the grid; the total is decomposed rather than compared loosely, so a growing
+    "outside the grid" figure shows up as a number rather than as slack in a tolerance.
+
+    Still deliberately NOT covered, and said rather than implied: the inventory columns are a
+    different module's reconciliation, and they are absent on a scoped pull anyway.
+    """
+    t = t or P.today()
+    rows = pool(team_id=team_id, t=t)
+
+    # ⭐⭐ THE POPULATION, AGAINST AN ORACLE THAT CANNOT SEE OUR JOIN. A bare Odoo count of active
+    # products, asked fresh — not a `len()` over anything this module or `products.catalogue()`
+    # built. NC: drop one row from `pool()` and this goes red; that is the whole point of it.
+    n_active = products.catalogue_count()
+    checks = [{
+        "check": "the pool holds one row per ACTIVE product (R12) — row count == an INDEPENDENT "
+                 "Odoo search_count('product.product', active=True)",
+        "ours": len(rows), "theirs": n_active, "ok": len(rows) == n_active,
+    }]
+
+    yf, yt = P.ytd(t)
+    sku_rev = products._sku_rev(yf, yt, team_id) or {}
+    in_pool = {r["code"] for r in rows}
+    outside = {c: v for c, v in sku_rev.items() if c not in in_pool}
+    ours = round(sum(r["rev_ytd"] or 0.0 for r in rows), 2)
+    theirs = round(sum(v.get("rev", 0.0) for v in sku_rev.values()), 2)
+    dropped = round(sum(v.get("rev", 0.0) for v in outside.values()), 2)
+    checks.append({
+        "check": "Σ per-SKU YTD revenue in the grid + Σ YTD revenue of codes no ACTIVE product "
+                 "carries == modules.products._sku_rev over the same window",
+        "ours": round(ours + dropped, 2), "theirs": theirs,
+        "ok": abs((ours + dropped) - theirs) < 0.01,
+        "detail": {"in_the_grid": ours, "outside_the_grid": dropped,
+                   "codes_outside": len(outside)},
+    })
+    # ⛔ AND THE EXCLUSION IS ASSERTED, NOT ASSUMED. "Everything I dropped was archived" is
+    # trivially true when checked against the dict that did the dropping — that is the
+    # self-sealing shape all over again. So it is asked of ODOO. A code here that a live ACTIVE
+    # product carries means `products.catalogue()` missed a row that has revenue, which is the
+    # 2,717 defect returning in a smaller costume.
+    # ⚠ `pid:N` keys are not `default_code`s and are skipped: an UNCODED active product is in the
+    # catalogue under its own `pid:N` key and therefore cannot be in `outside` at all.
+    coded_outside = sorted(c for c in outside if not str(c).startswith("pid:"))
+    still_active = (O.get_odoo().search_count(
+        'product.product', [('active', '=', True), ('default_code', 'in', coded_outside)])
+        if coded_outside else 0)
+    checks.append({
+        "check": "every SKU with revenue but NO grid row is genuinely ARCHIVED (R12: archived "
+                 "stay out) — asked of Odoo, never of the catalogue that did the dropping",
+        "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
+    # an input was missing, so the blank leg is checked as hard as the other two.
+    if team_id is None:                      # consolidated only — the inputs exist only there
+        buy = [r for r in rows if r.get("buy_now") == "Buy now"]
+        ok_rows = [r for r in rows if r.get("buy_now") == "OK"]
+        blank = [r for r in rows if r.get("buy_now") is None]
+        mis = sum(1 for r in buy if not (r["dos"] < r["lead_days"]))
+        mis += sum(1 for r in ok_rows if not (r["dos"] >= r["lead_days"]))
+        # A blank must be UNKNOWN — never a row we could have answered and quietly did not.
+        mis += sum(1 for r in blank
+                   if isinstance(r.get("dos"), (int, float))
+                   and isinstance(r.get("lead_days"), (int, float)) and r["lead_days"] > 0)
+        checks.append({
+            "check": "Buy signal partitions the catalogue (buy + ok + unknown == rows, none "
+                     "misclassified)",
+            "ours": len(buy) + len(ok_rows) + len(blank) - mis, "theirs": len(rows),
+            "ok": mis == 0 and len(buy) + len(ok_rows) + len(blank) == len(rows),
+            "detail": {"buy_now": len(buy), "ok": len(ok_rows), "unknown": len(blank),
+                       "misclassified": mis},
+        })
+        # ⭐ OWNER 2026-08-03 — "use the formula fields to come up to the same EXACT figures".
+        #
+        # This is that sentence, as a check. The retired preset column and the formula that
+        # replaces it must agree on every SKU, in all three states, or the replacement is not a
+        # replacement. `_buy_signal_formula` is a line-by-line port of the client formula
+        # engine's evaluation of
+        #
+        #     IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), "")
+        #
+        # including the part that is easy to get wrong: a comparison against a BLANK is blank,
+        # never a coerced 0. (The client engine's `cmp` returns null unless both sides read as
+        # numbers, and `IF` refuses a non-boolean condition — so a missing `dos` yields "" and
+        # not "Buy now". A filter engine would have said `0 < 30` and swept in every SKU that
+        # never sells through; the formula engine does not, and this check is what holds it.)
+        #
+        # ⚠ It compares SETS OF SKUs, not counts. Two different partitions can share a shape.
+        disagree = sorted(r["code"] for r in rows
+                          if (r.get("buy_now") or "") != _buy_signal_formula(r))
+        checks.append({
+            "check": 'Buy signal as a FORMULA field == the retired preset column, per SKU '
+                     '(IF({lead_days} > 0, IF({dos} < {lead_days}, "Buy now", "OK"), ""))',
+            "ours": len(rows) - len(disagree), "theirs": len(rows),
+            "ok": not disagree,
+            "detail": {"disagreeing_skus": disagree[:10], "n_disagree": len(disagree)},
+        })
+        # The other half of "the same figures": the SHARED Buy list view can no longer filter on
+        # the retired column, and its replacement conditions must select the same SKUs. They are
+        # `dos isNotEmpty AND lead_days isNotEmpty AND lead_days > 0 AND dos < lead_days`
+        # (_seed_wave17.views), so this reproduces exactly that conjunction.
+        #
+        # ⛔ THE NEGATIVE CONTROL IS WHY THIS IS NOT `cover_gap_d < 0`, which reads like the
+        # obvious filter and is WRONG: `cover_gap_d` is `int(round(dos - lead))`, so a genuine
+        # gap of -0.4 days rounds to 0 and that SKU drops off a buy list it belongs on.
+        view_rows = {r["code"] for r in rows
+                     if isinstance(r.get("dos"), (int, float))
+                     and isinstance(r.get("lead_days"), (int, float))
+                     and r["lead_days"] > 0 and r["dos"] < r["lead_days"]}
+        signal_rows = {r["code"] for r in buy}
+        rounding_would_miss = sorted(
+            c for c in signal_rows
+            if next((r for r in rows if r["code"] == c), {}).get("cover_gap_d") == 0)
+        checks.append({
+            "check": "Buy list view conditions (dos/lead_days, no retired column) select "
+                     "exactly the Buy-now SKUs",
+            "ours": len(view_rows), "theirs": len(signal_rows),
+            "ok": view_rows == signal_rows,
+            "detail": {"only_in_view": sorted(view_rows - signal_rows)[:10],
+                       "only_in_signal": sorted(signal_rows - view_rows)[:10],
+                       # Reported, not asserted: how many SKUs a `cover_gap_d < 0` filter would
+                       # have silently dropped. 0 today does not make that filter correct.
+                       "cover_gap_rounds_to_zero": len(rounding_would_miss)},
+        })
+    return checks

platform/modules/products.py

@@ -1,737 +1,737 @@
-"""Products / SKU module — SKU health: YoY movers (risers & decliners), zombie SKUs
-(catalog rot — sellable, formerly selling, now dead), new winners, coverage collapse
-(SKUs losing customer breadth — the FFS-recovery early-warning signal), and velocity leaders.
-
-Per-SKU margin already lives in the Financial module (low_margin_skus); not duplicated here.
-Basket / co-purchase (MBA) is intentionally deferred — the existing client app computes it
-runtime-side, and a local co-occurrence pull over 74k LTM lines is the kind of heavy job the
-project guardrails keep off the local PC. (See BACKLOG.)
-
-All line-level (sale.order.line), RI+FFS scope, excluded accounts removed — reusing sale_line_domain.
-Coverage (distinct customers per SKU) uses a 2-level read_group and is a touch slow (~15s/
-window), so it's its own function the app calls lazily and caches.
-"""
-import sys
-import datetime as dt
-from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-from functools import lru_cache
-import core.odoo as O
-import core.periods as P
-import modules.sales as sales_mod
-
-# SKU-health views are about real products — exclude service/delivery pseudo-SKUs
-# (Delivery Charges otherwise dominate movers/winners). Dot-path FILTER works (groupby
-# on the dot-path does not). Validation reconciles on this same non-service universe.
-_NO_SVC = [('product_id.type', '!=', 'service')]
-
-
-@lru_cache(maxsize=1)
-def _code_map():
-    """product_id → SKU code. Multiple product records can share a default_code (re-SKUing
-    /duplicates); keying by code merges them so a re-coded item doesn't read as a fake
-    decliner + fake riser. Products without a code fall back to a per-id key. Archived
-    products are INCLUDED — re-SKUing typically archives the old record and creates a new
-    one under the same code, and the old record still carries last-year sales."""
-    prods = O.search_read('product.product', [('active', 'in', [True, False])], ['id', 'default_code'],
-                          limit=50000)
-    return {p['id']: (str(p['default_code']).strip() if p.get('default_code') else f"pid:{p['id']}")
-            for p in prods}
-
-
-def _sku_rev(date_from, date_to, team_id=None):
-    """{sku_code: {'name','rev','qty','orders'}} over a window (services excluded,
-    duplicate product records merged by SKU code)."""
-    g = O.read_group('sale.order.line', O.sale_line_domain(date_from, date_to, team_id, extra=_NO_SVC),
-                     ['price_subtotal:sum', 'product_uom_qty:sum'], ['product_id'], lazy=False)
-    codes = _code_map()
-    out = {}
-    for r in g:
-        pid = O.m2o_id(r.get('product_id'))
-        if not pid:
-            continue
-        key = codes.get(pid, f"pid:{pid}")
-        e = out.setdefault(key, {'name': O.m2o_name(r.get('product_id')),
-                                 'rev': 0.0, 'qty': 0.0, 'orders': 0})
-        e['rev'] += r.get('price_subtotal') or 0.0
-        e['qty'] += r.get('product_uom_qty') or 0.0
-        e['orders'] += r.get('__count') or 0
-    return out
-
-
-def yoy_movers(t=None, limit=20, team_id=None):
-    """Top SKU risers and decliners by YTD-vs-same-period-LY revenue change."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this = _sku_rev(yf, yt, team_id)
-    last = _sku_rev(lf, lt, team_id)
-    rows = []
-    for pid in set(this) | set(last):
-        tr = this.get(pid, {'rev': 0.0, 'name': last.get(pid, {}).get('name', '')})
-        lr = last.get(pid, {'rev': 0.0})
-        name = this.get(pid, {}).get('name') or last.get(pid, {}).get('name') or ''
-        rows.append({'code': pid, 'product': name, 'rev_ytd': tr['rev'], 'rev_ly': lr['rev'],
-                     'change': tr['rev'] - lr['rev']})
-    risers = sorted([r for r in rows if r['change'] > 0], key=lambda x: -x['change'])[:limit]
-    decliners = sorted([r for r in rows if r['change'] < 0], key=lambda x: x['change'])[:limit]
-    return {'risers': risers, 'decliners': decliners}
-
-
-def zombie_skus(t=None, limit=30, min_prior=1500.0, team_id=None):
-    """Catalog rot: SKUs that sold materially last year but are ~dead this year."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this = _sku_rev(yf, yt, team_id)
-    last = _sku_rev(lf, lt, team_id)
-    rows = []
-    for pid, lr in last.items():
-        if lr['rev'] < min_prior:
-            continue
-        tr = this.get(pid, {'rev': 0.0})
-        if tr['rev'] > 0.05 * lr['rev']:   # still selling at >5% of prior → not a zombie
-            continue
-        rows.append({'code': pid, 'product': lr['name'], 'rev_ly': lr['rev'], 'rev_ytd': tr['rev'],
-                     'lost': lr['rev'] - tr['rev']})
-    rows.sort(key=lambda x: -x['lost'])
-    return rows[:limit]
-
-
-def new_winners(t=None, limit=20, min_this=1500.0, team_id=None):
-    """SKUs that barely sold last year but are selling well this year."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this = _sku_rev(yf, yt, team_id)
-    last = _sku_rev(lf, lt, team_id)
-    rows = []
-    for pid, tr in this.items():
-        if tr['rev'] < min_this:
-            continue
-        lr = last.get(pid, {'rev': 0.0})
-        if lr['rev'] > 0.05 * tr['rev']:
-            continue
-        rows.append({'code': pid, 'product': tr['name'], 'rev_ytd': tr['rev'], 'rev_ly': lr['rev'],
-                     'gained': tr['rev'] - lr['rev']})
-    rows.sort(key=lambda x: -x['gained'])
-    return rows[:limit]
-
-
-def velocity_leaders(t=None, limit=25, team_id=None):
-    """Top SKUs by LTM unit velocity (units/month) and revenue."""
-    t = t or P.today()
-    lf, lt = P.ltm(t)
-    sku = _sku_rev(lf, lt, team_id)
-    rows = [{'code': k, 'product': v['name'], 'units_ltm': v['qty'], 'units_per_mo': v['qty'] / 12.0,
-             'rev_ltm': v['rev'], 'orders_ltm': v['orders']} for k, v in sku.items()]
-    rows.sort(key=lambda x: -x['units_ltm'])
-    return rows[:limit]
-
-
-def _code_category():
-    """code -> category name. Built from _code_map (pid->code) + the sales category map
-    (pid->category); the first record carrying a code sets that code's category."""
-    codes = _code_map()
-    cats = sales_mod._product_cat()
-    out = {}
-    for pid, code in codes.items():
-        if code not in out and pid in cats:
-            out[code] = cats[pid]
-    return out
-
-
-def directory(t=None, team_id=None):
-    """Every SKU that sold this YTD or the same period last year, with the fields the SKU
-    drill-down filters/sorts on: category, YTD/LY revenue, YoY %, units and orders. Mirrors the
-    customer directory — the full list (filtering happens in the UI), sorted by YTD revenue."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this = _sku_rev(yf, yt, team_id)
-    last = _sku_rev(lf, lt, team_id)
-    code_cat = _code_category()
-    rows = []
-    for code in set(this) | set(last):
-        tr = this.get(code, {})
-        lr = last.get(code, {})
-        rev_ytd = tr.get('rev', 0.0)
-        rev_ly = lr.get('rev', 0.0)
-        rows.append({'code': code, 'product': tr.get('name') or lr.get('name') or code,
-                     'category': code_cat.get(code, '(uncategorized)'),
-                     'rev_ytd': rev_ytd, 'rev_ly': rev_ly, 'change': rev_ytd - rev_ly,
-                     'yoy_pct': P.yoy_pct(rev_ytd, rev_ly),
-                     'qty_ytd': tr.get('qty', 0.0), 'orders_ytd': tr.get('orders', 0)})
-    rows.sort(key=lambda r: -r['rev_ytd'])
-    return rows
-
-
-def catalogue():
-    """`{sku_code: {'product', 'category', 'id'}}` — EVERY ACTIVE product, sold or not.
-
-    ⛔ THIS IS THE CATALOGUE UNIVERSE, AND IT IS DELIBERATELY NOT `directory()`. `directory()`'s
-    row set IS the union of two revenue `read_group`s over `sale.order.line` (`:155`), so a SKU
-    that never sold cannot exist in it. That is CORRECT for its own callers — `yoy_movers`,
-    `zombie_skus`, `new_winners` and `categories` all legitimately want a sales-window universe —
-    and it is wrong for the PRODUCT GRID, which is a catalogue and was therefore showing 2,717 of
-    5,875 SKUs (wave 29, owner item 22 / ruling R12). The fix is this function plus a LEFT JOIN in
-    the consumer, never a window removed from `directory()`: removing the window alone lands at
-    3,327 (all-time-sold), because ~2,550 active SKUs have never sold in wholesale scope at all.
-
-    ⚠ NOT BU-SHAPED, and it cannot be: `product.product` carries no team. A catalogue is one
-    catalogue. `directory()` stays the BU-shaped half, which is why the two are joined rather than
-    merged — a scoped caller gets every SKU with ITS OWN revenue, blank where that BU never sold.
-
-    Keyed exactly like `_code_map()` — the `default_code`, or a `pid:N` fallback for the 33 active
-    records that carry none — so the join against `directory()` is code-for-code with no
-    normaliser. Names come from `display_name` (`[CODE] NAME`), which is what `O.m2o_name` yields
-    off a sale line, so a never-sold row wears the same format as a sold one.
-
-    ⛔ RAISES on a truncated read rather than returning a short catalogue. A silently short pull
-    would put the grid back at a plausible wrong number with every gate green — the exact failure
-    this function exists to end ([[no-unverifiable-aggregates]], and the same truncation guard
-    `modules/backorders.py:161` already uses).
-    """
-    dom = [('active', '=', True)]
-    prods = O.search_read('product.product', dom, ['id', 'default_code', 'display_name', 'name'],
-                          limit=50000)
-    n = O.get_odoo().search_count('product.product', dom)
-    if len(prods) != n:
-        raise ValueError(
-            f"products.catalogue: the product pull is TRUNCATED — read {len(prods)} rows against "
-            f"a search_count of {n}. A short catalogue renders as a plausible smaller grid with "
-            f"nothing reporting it; raise the limit before shipping this.")
-    code_cat = _code_category()
-    out = {}
-    for p in prods:
-        code = (str(p['default_code']).strip() if p.get('default_code') else f"pid:{p['id']}")
-        # First record wins, matching `_code_category`'s own convention. MEASURED 2026-08-11: zero
-        # active products share a code, so this branch is a guard, not a merge policy.
-        # ⭐⭐ W33-T43 (R2 / amendment A2) — `id` RIDES THE ROW. Odoo's `product.product` id is
-        # already in hand (the `pid:{id}` fallback above uses it and then threw it away), and it is
-        # the ONE column `ut_odoo_products` had that `product_data` lacked. R2 merges onto the
-        # legacy key and keeps every data column, so retiring the twin without this would lose a
-        # real identifier rather than a navigational link.
-        # ⚠ A product's grid pid is `crc32(default_code)`, NOT the Odoo id — unlike a CUSTOMER row,
-        # whose pid IS the partner id. That asymmetry is exactly why this cannot be derived
-        # downstream in `aios_grid.py` and has to be carried from the source read.
-        out.setdefault(code, {'product': p.get('display_name') or p.get('name') or code,
-                              'category': code_cat.get(code, '(uncategorized)'),
-                              'id': p['id']})
-    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.
-
-    Deliberately a bare `search_count` and not a `len()` over anything this module built — the
-    2,717 defect shipped silently for a wave because `product_data.validate()` derived BOTH sides
-    of its reconciliation from `_sku_rev`, so the oracle could never see a missing row.
-    """
-    return O.get_odoo().search_count('product.product', [('active', '=', True)])
-
-
-def categories(t=None, team_id=None):
-    """Sorted distinct category names present in the SKU directory (for the drill-down filter)."""
-    return sorted({r['category'] for r in directory(t, team_id)})
-
-
-def _coverage(date_from, date_to, team_id=None):
-    """{sku_code: distinct_customer_count} via 2-level read_group (slow-ish), merged by code.
-    (A customer buying two records sharing a code can count twice; duplicates are rare, and
-    code-level avoids the bigger error of a re-SKUed product reading as full coverage loss.)"""
-    g = O.read_group('sale.order.line', O.sale_line_domain(date_from, date_to, team_id, extra=_NO_SVC),
-                     ['__count'], ['product_id', 'order_partner_id'], lazy=False)
-    codes = _code_map()
-    cov = {}
-    names = {}
-    for r in g:
-        pid = O.m2o_id(r.get('product_id'))
-        if not pid:
-            continue
-        key = codes.get(pid, f"pid:{pid}")
-        cov[key] = cov.get(key, 0) + 1
-        names.setdefault(key, O.m2o_name(r.get('product_id')))
-    return cov, names
-
-
-def coverage_collapse(t=None, limit=25, min_prior_custs=8, team_id=None):
-    """SKUs that lost the most customer breadth YoY — early warning a SKU is dying even if
-    revenue hasn't fully cratered yet."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    cov_t, names_t = _coverage(yf, yt, team_id)
-    cov_l, names_l = _coverage(lf, lt, team_id)
-    rows = []
-    for pid, lc in cov_l.items():
-        if lc < min_prior_custs:
-            continue
-        tc = cov_t.get(pid, 0)
-        drop = lc - tc
-        if drop <= 0:
-            continue
-        rows.append({'code': pid, 'product': names_l.get(pid) or names_t.get(pid) or '',
-                     'custs_ly': lc, 'custs_ytd': tc, 'lost_custs': drop,
-                     'pct_drop': drop / lc * 100})
-    rows.sort(key=lambda x: (-x['lost_custs'], -x['pct_drop']))
-    return rows[:limit]
-
-
-# ====================================================================== SKU DRAWER (mirror of customer drawer)
-def _sku_product_ids(code):
-    """All product.product ids sharing this SKU code (merged variants / archived records)."""
-    return [pid for pid, c in _code_map().items() if c == code]
-
-
-def _sku_dom(pids, date_from, date_to, team_id=None):
-    return O.sale_line_domain(date_from, date_to, team_id, extra=[('product_id', 'in', pids)] + _NO_SVC)
-
-
-def _sku_name_category(pids):
-    rows = O.search_read('product.product', [('id', 'in', pids)], ['name', 'categ_id'])
-    name = rows[0]['name'] if rows else '(unknown)'
-    catmap = sales_mod._product_cat()
-    main = next((catmap.get(p) for p in pids if catmap.get(p)), '(uncategorized)')
-    return name, main
-
-
-def _sku_buyers(pids, date_from, date_to, team_id=None):
-    """{partner_id: {'name','rev','qty'}} for buyers of this SKU over a window."""
-    g = O.read_group('sale.order.line', _sku_dom(pids, date_from, date_to, team_id),
-                     ['price_subtotal:sum', 'product_uom_qty:sum'], ['order_partner_id'], lazy=False)
-    out = {}
-    for r in g:
-        pid = O.m2o_id(r.get('order_partner_id'))
-        if pid:
-            out[pid] = {'name': O.m2o_name(r.get('order_partner_id')),
-                        'rev': r.get('price_subtotal') or 0.0, 'qty': r.get('product_uom_qty') or 0.0}
-    return out
-
-
-def sku_detail(code, t=None, team_id=None, n_months=13, allsku=None):
-    """KPIs (rev/qty/buyers YoY, GM%), monthly trend, rank & % of BU for one SKU code.
-    Pass `allsku` (a cached _sku_rev YTD map) to skip the ~all-SKU rank read."""
-    t = t or P.today()
-    pids = _sku_product_ids(code)
-    if not pids:
-        return None
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    mf, mt = P.ltm(t)
-    name, category = _sku_name_category(pids)
-
-    def s(df, dtt, field='price_subtotal'):
-        return O.sum_field('sale.order.line', _sku_dom(pids, df, dtt, team_id), field)
-    rev_ytd, rev_ly = s(yf, yt), s(lf, lt)
-    qty_ytd, qty_ly = s(yf, yt, 'product_uom_qty'), s(lf, lt, 'product_uom_qty')
-    buyers_ytd = len(_sku_buyers(pids, yf, yt, team_id))
-    buyers_ly = len(_sku_buyers(pids, lf, lt, team_id))
-    g = O.read_group('sale.order.line', _sku_dom(pids, mf, mt, team_id),
-                     ['price_subtotal:sum', 'margin:sum'], [], lazy=False)
-    line_rev = (g[0].get('price_subtotal') if g else 0) or 0.0
-    margin = (g[0].get('margin') if g else 0) or 0.0
-
-    # Monthly trend: bin lines by their order's month in Python (dot-path month groupby is rejected
-    # on sale.order.line), in 2 reads instead of 26 point queries.
-    range_start = dt.date(t.year - 2, t.month, 1).isoformat()
-    lines = O.search_read('sale.order.line', _sku_dom(pids, range_start, t.isoformat(), team_id),
-                          ['price_subtotal', 'order_id'])
-    oids = list({O.m2o_id(line['order_id']) for line in lines if line.get('order_id')})
-    odate = {}
-    for i in range(0, len(oids), 1000):
-        for o in O.search_read('sale.order', [('id', 'in', oids[i:i + 1000])], ['date_order']):
-            if o.get('date_order'):
-                odate[o['id']] = str(o['date_order'])[:7]
-    mrev = {}
-    for line in lines:
-        ym = odate.get(O.m2o_id(line.get('order_id')))
-        if ym:
-            mrev[ym] = mrev.get(ym, 0.0) + (line.get('price_subtotal') or 0.0)
-    monthly = []
-    for ym, start, end in P.month_starts(n_months, t):
-        y, m = int(ym[:4]) - 1, int(ym[5:7])
-        monthly.append({'month': ym, 'revenue': mrev.get(ym, 0.0),
-                        'revenue_ly': mrev.get(f'{y:04d}-{m:02d}', 0.0)})
-
-    allsku = allsku if allsku is not None else _sku_rev(yf, yt, team_id)
-    total = sum(v['rev'] for v in allsku.values()) or 1.0
-    rank = next((i + 1 for i, (c, _v) in enumerate(sorted(allsku.items(), key=lambda kv: -kv[1]['rev']))
-                 if c == code), None)
-    return {
-        'code': code, 'name': name, 'category': category,
-        'rev_ytd': rev_ytd, 'rev_ly': rev_ly, 'rev_yoy_pct': P.yoy_pct(rev_ytd, rev_ly),
-        'qty_ytd': qty_ytd, 'qty_ly': qty_ly, 'qty_yoy_pct': P.yoy_pct(qty_ytd, qty_ly),
-        'buyers_ytd': buyers_ytd, 'buyers_ly': buyers_ly, 'buyers_delta': buyers_ytd - buyers_ly,
-        'gm_pct': (margin / line_rev * 100) if line_rev else 0.0, 'gm_dollars': margin,
-        'rank': rank, 'n_skus': len(allsku), 'pct_of_bu': rev_ytd / total * 100,
-        'monthly': monthly,
-    }
-
-
-def sku_buyer_bridge(code, t=None, team_id=None, top=12):
-    """Who drives the SKU's YoY: retained / new / churned buyers + a $-ranked churned call list."""
-    t = t or P.today()
-    pids = _sku_product_ids(code)
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this, last = _sku_buyers(pids, yf, yt, team_id), _sku_buyers(pids, lf, lt, team_id)
-    tset, lset = set(this), set(last)
-    retained, new, churned = tset & lset, tset - lset, lset - tset
-    churned_list = sorted([{'pid': p, 'customer': last[p]['name'], 'ly_rev': last[p]['rev']}
-                           for p in churned], key=lambda x: -x['ly_rev'])[:top]
-    return {'retained': {'n': len(retained), 'rev': sum(this[p]['rev'] for p in retained)},
-            'new': {'n': len(new), 'rev': sum(this[p]['rev'] for p in new)},
-            'churned': {'n': len(churned), 'rev': sum(last[p]['rev'] for p in churned)},
-            'buyer_retention_pct': (len(retained) / len(lset) * 100) if lset else 0.0,
-            'churned_buyers': churned_list, 'buyers_this': len(tset), 'buyers_last': len(lset),
-            'this_total': sum(v['rev'] for v in this.values())}
-
-
-def sku_concentration(code, t=None, team_id=None):
-    """Buyer-concentration risk: top-1/top-3 share, Herfindahl index, effective buyer count (LTM)."""
-    t = t or P.today()
-    mf, mt = P.ltm(t)
-    buyers = _sku_buyers(_sku_product_ids(code), mf, mt, team_id)
-    revs = sorted([v['rev'] for v in buyers.values()], reverse=True)
-    total = sum(revs) or 1.0
-    hhi = sum((r / total) ** 2 for r in revs)
-    return {'n_buyers': len(revs), 'top1_pct': (revs[0] / total * 100) if revs else 0.0,
-            'top3_pct': (sum(revs[:3]) / total * 100) if revs else 0.0,
-            'hhi': hhi, 'eff_buyers': (1 / hhi) if hhi else 0.0}
-
-
-def sku_price_dispersion(code, t=None, team_id=None, cap=60):
-    """Realized $/unit per buyer (LTM) vs the volume-weighted average; recoverable $ on below-VWAP
-    accounts. list_price is unreliable, so the dispersion among actual buyers is the margin lever."""
-    t = t or P.today()
-    mf, mt = P.ltm(t)
-    g = O.read_group('sale.order.line', _sku_dom(_sku_product_ids(code), mf, mt, team_id),
-                     ['price_subtotal:sum', 'product_uom_qty:sum'], ['order_partner_id'], lazy=False)
-    rows, tot_rev, tot_qty = [], 0.0, 0.0
-    for r in g:
-        pid = O.m2o_id(r.get('order_partner_id'))
-        rev = r.get('price_subtotal') or 0.0
-        qty = r.get('product_uom_qty') or 0.0
-        if not pid or qty <= 0:
-            continue
-        rows.append({'pid': pid, 'customer': O.m2o_name(r.get('order_partner_id')),
-                     'price': rev / qty, 'qty': qty, 'rev': rev})
-        tot_rev += rev
-        tot_qty += qty
-    vwap = (tot_rev / tot_qty) if tot_qty else 0.0
-    for r in rows:
-        r['recoverable'] = max(0.0, vwap - r['price']) * r['qty']
-    rows.sort(key=lambda x: -x['recoverable'])
-    return {'vwap': vwap, 'n_buyers': len(rows),
-            'recoverable_total': sum(r['recoverable'] for r in rows), 'rows': rows[:cap]}
-
-
-def sku_top_buyers(code, t=None, team_id=None, top=15):
-    """Ranked buyers of this SKU (YTD) with YoY — clickable to open the customer drawer."""
-    t = t or P.today()
-    pids = _sku_product_ids(code)
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this, last = _sku_buyers(pids, yf, yt, team_id), _sku_buyers(pids, lf, lt, team_id)
-    rows = [{'pid': p, 'customer': v['name'], 'rev': v['rev'], 'qty': v['qty'],
-             'yoy_pct': P.yoy_pct(v['rev'], last.get(p, {}).get('rev', 0.0))} for p, v in this.items()]
-    rows.sort(key=lambda x: -x['rev'])
-    return rows[:top]
-
-
-_BUYER_TIERS = [('Whale (≥$25k)', 25000.0), ('Large ($10–25k)', 10000.0),
-                ('Mid ($2–10k)', 2000.0), ('Small (<$2k)', 0.0)]
-
-
-def sku_customer_analysis(code, t=None, team_id=None, top=15):
-    """WHO buys this SKU (LTM), as customers: the value-tier mix of its buyers (by each buyer's TOTAL
-    spend), and the accounts most DEPENDENT on it (this SKU as a share of their spend — who gets hurt
-    most if it stocks out / who to protect)."""
-    t = t or P.today()
-    lf, lt = P.ltm(t)
-    pids = _sku_product_ids(code)
-    empty = {'segments': [], 'dependency': [], 'n_buyers': 0, 'avg_dependency': 0.0}
-    if not pids:
-        return empty
-    buyers = _sku_buyers(pids, lf, lt, team_id)        # {pid: {name, rev(this SKU), qty}}
-    if not buyers:
-        return empty
-    bpids = list(buyers)
-    g = O.read_group('sale.order', sales_mod.order_domain(lf, lt, team_id) + [('partner_id', 'in', bpids)],
-                     ['amount_untaxed:sum'], ['partner_id'], lazy=False)
-    total = {O.m2o_id(r['partner_id']): (r.get('amount_untaxed') or 0.0) for r in g if r.get('partner_id')}
-
-    def tier(rev):
-        for nm, lo in _BUYER_TIERS:
-            if rev >= lo:
-                return nm
-        return _BUYER_TIERS[-1][0]
-    seg = {nm: {'tier': nm, 'buyers': 0, 'sku_rev': 0.0} for nm, _ in _BUYER_TIERS}
-    dep = []
-    for p, v in buyers.items():
-        ct = total.get(p, v['rev']) or v['rev']
-        s = seg[tier(ct)]
-        s['buyers'] += 1
-        s['sku_rev'] += v['rev']
-        dep.append({'customer': v['name'], 'pid': p, 'sku_rev': v['rev'], 'cust_total': ct,
-                    'dependency_pct': (v['rev'] / ct * 100) if ct else None})
-    tot = sum(s['sku_rev'] for s in seg.values()) or 1.0
-    segments = []
-    for nm, _ in _BUYER_TIERS:
-        s = seg[nm]
-        s['rev_share'] = s['sku_rev'] / tot * 100
-        s['avg_per_buyer'] = (s['sku_rev'] / s['buyers']) if s['buyers'] else 0.0
-        segments.append(s)
-    dep.sort(key=lambda x: -x['sku_rev'])
-    deps_known = [d['dependency_pct'] for d in dep if d['dependency_pct'] is not None]
-    return {'segments': segments, 'dependency': dep[:top], 'n_buyers': len(buyers),
-            'avg_dependency': (sum(deps_known) / len(deps_known)) if deps_known else 0.0}
-
-
-def sku_whitespace(code, t=None, team_id=None, top=15):
-    """Customers who buy this SKU's category but NOT this SKU — ranked prospect list."""
-    import modules.customers as cust_mod
-    t = t or P.today()
-    pids = _sku_product_ids(code)
-    _name, category = _sku_name_category(pids)
-    cat_buyers = cust_mod.category_buyers(category, team_id=team_id) or set()
-    mf, mt = P.ltm(t)
-    prospects = list(cat_buyers - set(_sku_buyers(pids, mf, mt, team_id)))
-    if not prospects:
-        return {'category': category, 'rows': []}
-    g = O.read_group('sale.order', sales_mod.order_domain(mf, mt, team_id) + [('partner_id', 'in', prospects)],
-                     ['amount_untaxed:sum'], ['partner_id'], lazy=False)
-    rows = [{'pid': O.m2o_id(r['partner_id']), 'customer': O.m2o_name(r['partner_id']),
-             'total_spend': r.get('amount_untaxed') or 0.0} for r in g if r.get('partner_id')]
-    rows.sort(key=lambda x: -x['total_spend'])
-    return {'category': category, 'rows': rows[:top]}
-
-
-def sku_drawer_bundle(code, t=None, team_id=None, allsku=None):
-    """The whole SKU drawer's first paint in one cached unit: sku_detail first (the not-found gate),
-    then the other six pulls CONCURRENTLY (O.parallel). Cuts a ~6-call cold open to ~max(call)."""
-    detail = sku_detail(code, t=t, team_id=team_id, allsku=allsku)
-    if detail is None:
-        return {'detail': None}
-    bridge, conc, price, buyers, white, ca = O.parallel([
-        lambda: sku_buyer_bridge(code, t, team_id),
-        lambda: sku_concentration(code, t, team_id),
-        lambda: sku_price_dispersion(code, t, team_id),
-        lambda: sku_top_buyers(code, t, team_id),
-        lambda: sku_whitespace(code, t, team_id),
-        lambda: sku_customer_analysis(code, t, team_id),
-    ])
-    return {'detail': detail, 'bridge': bridge, 'conc': conc, 'price': price,
-            'buyers': buyers, 'white': white, 'ca': ca}
-
-
-def validate(t=None, team_id=None):
-    """Reconcile SKU metrics to independent Odoo aggregates. When team_id is set (a single BU
-    selected) every check runs SCOPED to that BU, so the validation panel never reconciles
-    against — or exposes — the other BU's numbers. All checks here are BU-scopeable (no cross-BU
-    mirror), so team_id threads straight through."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    checks = []
-    sku = _sku_rev(yf, yt, team_id)
-    sku_sum = sum(v['rev'] for v in sku.values())
-    line_total = O.sum_field('sale.order.line',
-                             O.sale_line_domain(yf, yt, team_id, extra=_NO_SVC), 'price_subtotal')
-    checks.append({'check': 'SKU rev: Σ(per-SKU) == total line revenue, ex-services (YTD)',
-                   'a': round(sku_sum, 2), 'b': round(line_total, 2),
-                   'gap': round(sku_sum - line_total, 2),
-                   'ok': abs(sku_sum - line_total) <= 1.0})
-
-    m = yoy_movers(t, limit=10**9, team_id=team_id)
-    movers_sum = sum(r['change'] for r in m['risers']) + sum(r['change'] for r in m['decliners'])
-    lf, lt = P.ytd_last_year(t)
-    last_total = O.sum_field('sale.order.line',
-                             O.sale_line_domain(lf, lt, team_id, extra=_NO_SVC), 'price_subtotal')
-    checks.append({'check': 'SKU movers: Σ(Δ) == (YTD − LY) total',
-                   'a': round(movers_sum, 2), 'b': round(line_total - last_total, 2),
-                   'gap': round(movers_sum - (line_total - last_total), 2),
-                   'ok': abs(movers_sum - (line_total - last_total)) <= 1.0})
-
-    # SKU drawer: buyer-bridge reconciles — retained + new buyer revenue == this-period SKU revenue
-    top_code = max(sku.items(), key=lambda kv: kv[1]['rev'])[0] if sku else None
-    if top_code:
-        bb = sku_buyer_bridge(top_code, t, team_id=team_id)
-        recon = bb['retained']['rev'] + bb['new']['rev']
-        checks.append({'check': 'SKU drawer: retained+new buyer rev == SKU YTD revenue',
-                       'a': round(recon, 2), 'b': round(bb['this_total'], 2),
-                       'gap': round(recon - bb['this_total'], 2),
-                       'ok': abs(recon - bb['this_total']) <= 1.0})
-    return checks
+"""Products / SKU module — SKU health: YoY movers (risers & decliners), zombie SKUs
+(catalog rot — sellable, formerly selling, now dead), new winners, coverage collapse
+(SKUs losing customer breadth — the FFS-recovery early-warning signal), and velocity leaders.
+
+Per-SKU margin already lives in the Financial module (low_margin_skus); not duplicated here.
+Basket / co-purchase (MBA) is intentionally deferred — the existing client app computes it
+runtime-side, and a local co-occurrence pull over 74k LTM lines is the kind of heavy job the
+project guardrails keep off the local PC. (See BACKLOG.)
+
+All line-level (sale.order.line), RI+FFS scope, excluded accounts removed — reusing sale_line_domain.
+Coverage (distinct customers per SKU) uses a 2-level read_group and is a touch slow (~15s/
+window), so it's its own function the app calls lazily and caches.
+"""
+import sys
+import datetime as dt
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from functools import lru_cache
+import core.odoo as O
+import core.periods as P
+import modules.sales as sales_mod
+
+# SKU-health views are about real products — exclude service/delivery pseudo-SKUs
+# (Delivery Charges otherwise dominate movers/winners). Dot-path FILTER works (groupby
+# on the dot-path does not). Validation reconciles on this same non-service universe.
+_NO_SVC = [('product_id.type', '!=', 'service')]
+
+
+@lru_cache(maxsize=1)
+def _code_map():
+    """product_id → SKU code. Multiple product records can share a default_code (re-SKUing
+    /duplicates); keying by code merges them so a re-coded item doesn't read as a fake
+    decliner + fake riser. Products without a code fall back to a per-id key. Archived
+    products are INCLUDED — re-SKUing typically archives the old record and creates a new
+    one under the same code, and the old record still carries last-year sales."""
+    prods = O.search_read('product.product', [('active', 'in', [True, False])], ['id', 'default_code'],
+                          limit=50000)
+    return {p['id']: (str(p['default_code']).strip() if p.get('default_code') else f"pid:{p['id']}")
+            for p in prods}
+
+
+def _sku_rev(date_from, date_to, team_id=None):
+    """{sku_code: {'name','rev','qty','orders'}} over a window (services excluded,
+    duplicate product records merged by SKU code)."""
+    g = O.read_group('sale.order.line', O.sale_line_domain(date_from, date_to, team_id, extra=_NO_SVC),
+                     ['price_subtotal:sum', 'product_uom_qty:sum'], ['product_id'], lazy=False)
+    codes = _code_map()
+    out = {}
+    for r in g:
+        pid = O.m2o_id(r.get('product_id'))
+        if not pid:
+            continue
+        key = codes.get(pid, f"pid:{pid}")
+        e = out.setdefault(key, {'name': O.m2o_name(r.get('product_id')),
+                                 'rev': 0.0, 'qty': 0.0, 'orders': 0})
+        e['rev'] += r.get('price_subtotal') or 0.0
+        e['qty'] += r.get('product_uom_qty') or 0.0
+        e['orders'] += r.get('__count') or 0
+    return out
+
+
+def yoy_movers(t=None, limit=20, team_id=None):
+    """Top SKU risers and decliners by YTD-vs-same-period-LY revenue change."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this = _sku_rev(yf, yt, team_id)
+    last = _sku_rev(lf, lt, team_id)
+    rows = []
+    for pid in set(this) | set(last):
+        tr = this.get(pid, {'rev': 0.0, 'name': last.get(pid, {}).get('name', '')})
+        lr = last.get(pid, {'rev': 0.0})
+        name = this.get(pid, {}).get('name') or last.get(pid, {}).get('name') or ''
+        rows.append({'code': pid, 'product': name, 'rev_ytd': tr['rev'], 'rev_ly': lr['rev'],
+                     'change': tr['rev'] - lr['rev']})
+    risers = sorted([r for r in rows if r['change'] > 0], key=lambda x: -x['change'])[:limit]
+    decliners = sorted([r for r in rows if r['change'] < 0], key=lambda x: x['change'])[:limit]
+    return {'risers': risers, 'decliners': decliners}
+
+
+def zombie_skus(t=None, limit=30, min_prior=1500.0, team_id=None):
+    """Catalog rot: SKUs that sold materially last year but are ~dead this year."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this = _sku_rev(yf, yt, team_id)
+    last = _sku_rev(lf, lt, team_id)
+    rows = []
+    for pid, lr in last.items():
+        if lr['rev'] < min_prior:
+            continue
+        tr = this.get(pid, {'rev': 0.0})
+        if tr['rev'] > 0.05 * lr['rev']:   # still selling at >5% of prior → not a zombie
+            continue
+        rows.append({'code': pid, 'product': lr['name'], 'rev_ly': lr['rev'], 'rev_ytd': tr['rev'],
+                     'lost': lr['rev'] - tr['rev']})
+    rows.sort(key=lambda x: -x['lost'])
+    return rows[:limit]
+
+
+def new_winners(t=None, limit=20, min_this=1500.0, team_id=None):
+    """SKUs that barely sold last year but are selling well this year."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this = _sku_rev(yf, yt, team_id)
+    last = _sku_rev(lf, lt, team_id)
+    rows = []
+    for pid, tr in this.items():
+        if tr['rev'] < min_this:
+            continue
+        lr = last.get(pid, {'rev': 0.0})
+        if lr['rev'] > 0.05 * tr['rev']:
+            continue
+        rows.append({'code': pid, 'product': tr['name'], 'rev_ytd': tr['rev'], 'rev_ly': lr['rev'],
+                     'gained': tr['rev'] - lr['rev']})
+    rows.sort(key=lambda x: -x['gained'])
+    return rows[:limit]
+
+
+def velocity_leaders(t=None, limit=25, team_id=None):
+    """Top SKUs by LTM unit velocity (units/month) and revenue."""
+    t = t or P.today()
+    lf, lt = P.ltm(t)
+    sku = _sku_rev(lf, lt, team_id)
+    rows = [{'code': k, 'product': v['name'], 'units_ltm': v['qty'], 'units_per_mo': v['qty'] / 12.0,
+             'rev_ltm': v['rev'], 'orders_ltm': v['orders']} for k, v in sku.items()]
+    rows.sort(key=lambda x: -x['units_ltm'])
+    return rows[:limit]
+
+
+def _code_category():
+    """code -> category name. Built from _code_map (pid->code) + the sales category map
+    (pid->category); the first record carrying a code sets that code's category."""
+    codes = _code_map()
+    cats = sales_mod._product_cat()
+    out = {}
+    for pid, code in codes.items():
+        if code not in out and pid in cats:
+            out[code] = cats[pid]
+    return out
+
+
+def directory(t=None, team_id=None):
+    """Every SKU that sold this YTD or the same period last year, with the fields the SKU
+    drill-down filters/sorts on: category, YTD/LY revenue, YoY %, units and orders. Mirrors the
+    customer directory — the full list (filtering happens in the UI), sorted by YTD revenue."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this = _sku_rev(yf, yt, team_id)
+    last = _sku_rev(lf, lt, team_id)
+    code_cat = _code_category()
+    rows = []
+    for code in set(this) | set(last):
+        tr = this.get(code, {})
+        lr = last.get(code, {})
+        rev_ytd = tr.get('rev', 0.0)
+        rev_ly = lr.get('rev', 0.0)
+        rows.append({'code': code, 'product': tr.get('name') or lr.get('name') or code,
+                     'category': code_cat.get(code, '(uncategorized)'),
+                     'rev_ytd': rev_ytd, 'rev_ly': rev_ly, 'change': rev_ytd - rev_ly,
+                     'yoy_pct': P.yoy_pct(rev_ytd, rev_ly),
+                     'qty_ytd': tr.get('qty', 0.0), 'orders_ytd': tr.get('orders', 0)})
+    rows.sort(key=lambda r: -r['rev_ytd'])
+    return rows
+
+
+def catalogue():
+    """`{sku_code: {'product', 'category', 'id'}}` — EVERY ACTIVE product, sold or not.
+
+    ⛔ THIS IS THE CATALOGUE UNIVERSE, AND IT IS DELIBERATELY NOT `directory()`. `directory()`'s
+    row set IS the union of two revenue `read_group`s over `sale.order.line` (`:155`), so a SKU
+    that never sold cannot exist in it. That is CORRECT for its own callers — `yoy_movers`,
+    `zombie_skus`, `new_winners` and `categories` all legitimately want a sales-window universe —
+    and it is wrong for the PRODUCT GRID, which is a catalogue and was therefore showing 2,717 of
+    5,875 SKUs (wave 29, owner item 22 / ruling R12). The fix is this function plus a LEFT JOIN in
+    the consumer, never a window removed from `directory()`: removing the window alone lands at
+    3,327 (all-time-sold), because ~2,550 active SKUs have never sold in wholesale scope at all.
+
+    ⚠ NOT BU-SHAPED, and it cannot be: `product.product` carries no team. A catalogue is one
+    catalogue. `directory()` stays the BU-shaped half, which is why the two are joined rather than
+    merged — a scoped caller gets every SKU with ITS OWN revenue, blank where that BU never sold.
+
+    Keyed exactly like `_code_map()` — the `default_code`, or a `pid:N` fallback for the 33 active
+    records that carry none — so the join against `directory()` is code-for-code with no
+    normaliser. Names come from `display_name` (`[CODE] NAME`), which is what `O.m2o_name` yields
+    off a sale line, so a never-sold row wears the same format as a sold one.
+
+    ⛔ RAISES on a truncated read rather than returning a short catalogue. A silently short pull
+    would put the grid back at a plausible wrong number with every gate green — the exact failure
+    this function exists to end ([[no-unverifiable-aggregates]], and the same truncation guard
+    `modules/backorders.py:161` already uses).
+    """
+    dom = [('active', '=', True)]
+    prods = O.search_read('product.product', dom, ['id', 'default_code', 'display_name', 'name'],
+                          limit=50000)
+    n = O.get_odoo().search_count('product.product', dom)
+    if len(prods) != n:
+        raise ValueError(
+            f"products.catalogue: the product pull is TRUNCATED — read {len(prods)} rows against "
+            f"a search_count of {n}. A short catalogue renders as a plausible smaller grid with "
+            f"nothing reporting it; raise the limit before shipping this.")
+    code_cat = _code_category()
+    out = {}
+    for p in prods:
+        code = (str(p['default_code']).strip() if p.get('default_code') else f"pid:{p['id']}")
+        # First record wins, matching `_code_category`'s own convention. MEASURED 2026-08-11: zero
+        # active products share a code, so this branch is a guard, not a merge policy.
+        # ⭐⭐ W33-T43 (R2 / amendment A2) — `id` RIDES THE ROW. Odoo's `product.product` id is
+        # already in hand (the `pid:{id}` fallback above uses it and then threw it away), and it is
+        # the ONE column `ut_odoo_products` had that `product_data` lacked. R2 merges onto the
+        # legacy key and keeps every data column, so retiring the twin without this would lose a
+        # real identifier rather than a navigational link.
+        # ⚠ A product's grid pid is `crc32(default_code)`, NOT the Odoo id — unlike a CUSTOMER row,
+        # whose pid IS the partner id. That asymmetry is exactly why this cannot be derived
+        # downstream in `aios_grid.py` and has to be carried from the source read.
+        out.setdefault(code, {'product': p.get('display_name') or p.get('name') or code,
+                              'category': code_cat.get(code, '(uncategorized)'),
+                              'id': p['id']})
+    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.
+
+    Deliberately a bare `search_count` and not a `len()` over anything this module built — the
+    2,717 defect shipped silently for a wave because `product_data.validate()` derived BOTH sides
+    of its reconciliation from `_sku_rev`, so the oracle could never see a missing row.
+    """
+    return O.get_odoo().search_count('product.product', [('active', '=', True)])
+
+
+def categories(t=None, team_id=None):
+    """Sorted distinct category names present in the SKU directory (for the drill-down filter)."""
+    return sorted({r['category'] for r in directory(t, team_id)})
+
+
+def _coverage(date_from, date_to, team_id=None):
+    """{sku_code: distinct_customer_count} via 2-level read_group (slow-ish), merged by code.
+    (A customer buying two records sharing a code can count twice; duplicates are rare, and
+    code-level avoids the bigger error of a re-SKUed product reading as full coverage loss.)"""
+    g = O.read_group('sale.order.line', O.sale_line_domain(date_from, date_to, team_id, extra=_NO_SVC),
+                     ['__count'], ['product_id', 'order_partner_id'], lazy=False)
+    codes = _code_map()
+    cov = {}
+    names = {}
+    for r in g:
+        pid = O.m2o_id(r.get('product_id'))
+        if not pid:
+            continue
+        key = codes.get(pid, f"pid:{pid}")
+        cov[key] = cov.get(key, 0) + 1
+        names.setdefault(key, O.m2o_name(r.get('product_id')))
+    return cov, names
+
+
+def coverage_collapse(t=None, limit=25, min_prior_custs=8, team_id=None):
+    """SKUs that lost the most customer breadth YoY — early warning a SKU is dying even if
+    revenue hasn't fully cratered yet."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    cov_t, names_t = _coverage(yf, yt, team_id)
+    cov_l, names_l = _coverage(lf, lt, team_id)
+    rows = []
+    for pid, lc in cov_l.items():
+        if lc < min_prior_custs:
+            continue
+        tc = cov_t.get(pid, 0)
+        drop = lc - tc
+        if drop <= 0:
+            continue
+        rows.append({'code': pid, 'product': names_l.get(pid) or names_t.get(pid) or '',
+                     'custs_ly': lc, 'custs_ytd': tc, 'lost_custs': drop,
+                     'pct_drop': drop / lc * 100})
+    rows.sort(key=lambda x: (-x['lost_custs'], -x['pct_drop']))
+    return rows[:limit]
+
+
+# ====================================================================== SKU DRAWER (mirror of customer drawer)
+def _sku_product_ids(code):
+    """All product.product ids sharing this SKU code (merged variants / archived records)."""
+    return [pid for pid, c in _code_map().items() if c == code]
+
+
+def _sku_dom(pids, date_from, date_to, team_id=None):
+    return O.sale_line_domain(date_from, date_to, team_id, extra=[('product_id', 'in', pids)] + _NO_SVC)
+
+
+def _sku_name_category(pids):
+    rows = O.search_read('product.product', [('id', 'in', pids)], ['name', 'categ_id'])
+    name = rows[0]['name'] if rows else '(unknown)'
+    catmap = sales_mod._product_cat()
+    main = next((catmap.get(p) for p in pids if catmap.get(p)), '(uncategorized)')
+    return name, main
+
+
+def _sku_buyers(pids, date_from, date_to, team_id=None):
+    """{partner_id: {'name','rev','qty'}} for buyers of this SKU over a window."""
+    g = O.read_group('sale.order.line', _sku_dom(pids, date_from, date_to, team_id),
+                     ['price_subtotal:sum', 'product_uom_qty:sum'], ['order_partner_id'], lazy=False)
+    out = {}
+    for r in g:
+        pid = O.m2o_id(r.get('order_partner_id'))
+        if pid:
+            out[pid] = {'name': O.m2o_name(r.get('order_partner_id')),
+                        'rev': r.get('price_subtotal') or 0.0, 'qty': r.get('product_uom_qty') or 0.0}
+    return out
+
+
+def sku_detail(code, t=None, team_id=None, n_months=13, allsku=None):
+    """KPIs (rev/qty/buyers YoY, GM%), monthly trend, rank & % of BU for one SKU code.
+    Pass `allsku` (a cached _sku_rev YTD map) to skip the ~all-SKU rank read."""
+    t = t or P.today()
+    pids = _sku_product_ids(code)
+    if not pids:
+        return None
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    mf, mt = P.ltm(t)
+    name, category = _sku_name_category(pids)
+
+    def s(df, dtt, field='price_subtotal'):
+        return O.sum_field('sale.order.line', _sku_dom(pids, df, dtt, team_id), field)
+    rev_ytd, rev_ly = s(yf, yt), s(lf, lt)
+    qty_ytd, qty_ly = s(yf, yt, 'product_uom_qty'), s(lf, lt, 'product_uom_qty')
+    buyers_ytd = len(_sku_buyers(pids, yf, yt, team_id))
+    buyers_ly = len(_sku_buyers(pids, lf, lt, team_id))
+    g = O.read_group('sale.order.line', _sku_dom(pids, mf, mt, team_id),
+                     ['price_subtotal:sum', 'margin:sum'], [], lazy=False)
+    line_rev = (g[0].get('price_subtotal') if g else 0) or 0.0
+    margin = (g[0].get('margin') if g else 0) or 0.0
+
+    # Monthly trend: bin lines by their order's month in Python (dot-path month groupby is rejected
+    # on sale.order.line), in 2 reads instead of 26 point queries.
+    range_start = dt.date(t.year - 2, t.month, 1).isoformat()
+    lines = O.search_read('sale.order.line', _sku_dom(pids, range_start, t.isoformat(), team_id),
+                          ['price_subtotal', 'order_id'])
+    oids = list({O.m2o_id(line['order_id']) for line in lines if line.get('order_id')})
+    odate = {}
+    for i in range(0, len(oids), 1000):
+        for o in O.search_read('sale.order', [('id', 'in', oids[i:i + 1000])], ['date_order']):
+            if o.get('date_order'):
+                odate[o['id']] = str(o['date_order'])[:7]
+    mrev = {}
+    for line in lines:
+        ym = odate.get(O.m2o_id(line.get('order_id')))
+        if ym:
+            mrev[ym] = mrev.get(ym, 0.0) + (line.get('price_subtotal') or 0.0)
+    monthly = []
+    for ym, start, end in P.month_starts(n_months, t):
+        y, m = int(ym[:4]) - 1, int(ym[5:7])
+        monthly.append({'month': ym, 'revenue': mrev.get(ym, 0.0),
+                        'revenue_ly': mrev.get(f'{y:04d}-{m:02d}', 0.0)})
+
+    allsku = allsku if allsku is not None else _sku_rev(yf, yt, team_id)
+    total = sum(v['rev'] for v in allsku.values()) or 1.0
+    rank = next((i + 1 for i, (c, _v) in enumerate(sorted(allsku.items(), key=lambda kv: -kv[1]['rev']))
+                 if c == code), None)
+    return {
+        'code': code, 'name': name, 'category': category,
+        'rev_ytd': rev_ytd, 'rev_ly': rev_ly, 'rev_yoy_pct': P.yoy_pct(rev_ytd, rev_ly),
+        'qty_ytd': qty_ytd, 'qty_ly': qty_ly, 'qty_yoy_pct': P.yoy_pct(qty_ytd, qty_ly),
+        'buyers_ytd': buyers_ytd, 'buyers_ly': buyers_ly, 'buyers_delta': buyers_ytd - buyers_ly,
+        'gm_pct': (margin / line_rev * 100) if line_rev else 0.0, 'gm_dollars': margin,
+        'rank': rank, 'n_skus': len(allsku), 'pct_of_bu': rev_ytd / total * 100,
+        'monthly': monthly,
+    }
+
+
+def sku_buyer_bridge(code, t=None, team_id=None, top=12):
+    """Who drives the SKU's YoY: retained / new / churned buyers + a $-ranked churned call list."""
+    t = t or P.today()
+    pids = _sku_product_ids(code)
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this, last = _sku_buyers(pids, yf, yt, team_id), _sku_buyers(pids, lf, lt, team_id)
+    tset, lset = set(this), set(last)
+    retained, new, churned = tset & lset, tset - lset, lset - tset
+    churned_list = sorted([{'pid': p, 'customer': last[p]['name'], 'ly_rev': last[p]['rev']}
+                           for p in churned], key=lambda x: -x['ly_rev'])[:top]
+    return {'retained': {'n': len(retained), 'rev': sum(this[p]['rev'] for p in retained)},
+            'new': {'n': len(new), 'rev': sum(this[p]['rev'] for p in new)},
+            'churned': {'n': len(churned), 'rev': sum(last[p]['rev'] for p in churned)},
+            'buyer_retention_pct': (len(retained) / len(lset) * 100) if lset else 0.0,
+            'churned_buyers': churned_list, 'buyers_this': len(tset), 'buyers_last': len(lset),
+            'this_total': sum(v['rev'] for v in this.values())}
+
+
+def sku_concentration(code, t=None, team_id=None):
+    """Buyer-concentration risk: top-1/top-3 share, Herfindahl index, effective buyer count (LTM)."""
+    t = t or P.today()
+    mf, mt = P.ltm(t)
+    buyers = _sku_buyers(_sku_product_ids(code), mf, mt, team_id)
+    revs = sorted([v['rev'] for v in buyers.values()], reverse=True)
+    total = sum(revs) or 1.0
+    hhi = sum((r / total) ** 2 for r in revs)
+    return {'n_buyers': len(revs), 'top1_pct': (revs[0] / total * 100) if revs else 0.0,
+            'top3_pct': (sum(revs[:3]) / total * 100) if revs else 0.0,
+            'hhi': hhi, 'eff_buyers': (1 / hhi) if hhi else 0.0}
+
+
+def sku_price_dispersion(code, t=None, team_id=None, cap=60):
+    """Realized $/unit per buyer (LTM) vs the volume-weighted average; recoverable $ on below-VWAP
+    accounts. list_price is unreliable, so the dispersion among actual buyers is the margin lever."""
+    t = t or P.today()
+    mf, mt = P.ltm(t)
+    g = O.read_group('sale.order.line', _sku_dom(_sku_product_ids(code), mf, mt, team_id),
+                     ['price_subtotal:sum', 'product_uom_qty:sum'], ['order_partner_id'], lazy=False)
+    rows, tot_rev, tot_qty = [], 0.0, 0.0
+    for r in g:
+        pid = O.m2o_id(r.get('order_partner_id'))
+        rev = r.get('price_subtotal') or 0.0
+        qty = r.get('product_uom_qty') or 0.0
+        if not pid or qty <= 0:
+            continue
+        rows.append({'pid': pid, 'customer': O.m2o_name(r.get('order_partner_id')),
+                     'price': rev / qty, 'qty': qty, 'rev': rev})
+        tot_rev += rev
+        tot_qty += qty
+    vwap = (tot_rev / tot_qty) if tot_qty else 0.0
+    for r in rows:
+        r['recoverable'] = max(0.0, vwap - r['price']) * r['qty']
+    rows.sort(key=lambda x: -x['recoverable'])
+    return {'vwap': vwap, 'n_buyers': len(rows),
+            'recoverable_total': sum(r['recoverable'] for r in rows), 'rows': rows[:cap]}
+
+
+def sku_top_buyers(code, t=None, team_id=None, top=15):
+    """Ranked buyers of this SKU (YTD) with YoY — clickable to open the customer drawer."""
+    t = t or P.today()
+    pids = _sku_product_ids(code)
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this, last = _sku_buyers(pids, yf, yt, team_id), _sku_buyers(pids, lf, lt, team_id)
+    rows = [{'pid': p, 'customer': v['name'], 'rev': v['rev'], 'qty': v['qty'],
+             'yoy_pct': P.yoy_pct(v['rev'], last.get(p, {}).get('rev', 0.0))} for p, v in this.items()]
+    rows.sort(key=lambda x: -x['rev'])
+    return rows[:top]
+
+
+_BUYER_TIERS = [('Whale (≥$25k)', 25000.0), ('Large ($10–25k)', 10000.0),
+                ('Mid ($2–10k)', 2000.0), ('Small (<$2k)', 0.0)]
+
+
+def sku_customer_analysis(code, t=None, team_id=None, top=15):
+    """WHO buys this SKU (LTM), as customers: the value-tier mix of its buyers (by each buyer's TOTAL
+    spend), and the accounts most DEPENDENT on it (this SKU as a share of their spend — who gets hurt
+    most if it stocks out / who to protect)."""
+    t = t or P.today()
+    lf, lt = P.ltm(t)
+    pids = _sku_product_ids(code)
+    empty = {'segments': [], 'dependency': [], 'n_buyers': 0, 'avg_dependency': 0.0}
+    if not pids:
+        return empty
+    buyers = _sku_buyers(pids, lf, lt, team_id)        # {pid: {name, rev(this SKU), qty}}
+    if not buyers:
+        return empty
+    bpids = list(buyers)
+    g = O.read_group('sale.order', sales_mod.order_domain(lf, lt, team_id) + [('partner_id', 'in', bpids)],
+                     ['amount_untaxed:sum'], ['partner_id'], lazy=False)
+    total = {O.m2o_id(r['partner_id']): (r.get('amount_untaxed') or 0.0) for r in g if r.get('partner_id')}
+
+    def tier(rev):
+        for nm, lo in _BUYER_TIERS:
+            if rev >= lo:
+                return nm
+        return _BUYER_TIERS[-1][0]
+    seg = {nm: {'tier': nm, 'buyers': 0, 'sku_rev': 0.0} for nm, _ in _BUYER_TIERS}
+    dep = []
+    for p, v in buyers.items():
+        ct = total.get(p, v['rev']) or v['rev']
+        s = seg[tier(ct)]
+        s['buyers'] += 1
+        s['sku_rev'] += v['rev']
+        dep.append({'customer': v['name'], 'pid': p, 'sku_rev': v['rev'], 'cust_total': ct,
+                    'dependency_pct': (v['rev'] / ct * 100) if ct else None})
+    tot = sum(s['sku_rev'] for s in seg.values()) or 1.0
+    segments = []
+    for nm, _ in _BUYER_TIERS:
+        s = seg[nm]
+        s['rev_share'] = s['sku_rev'] / tot * 100
+        s['avg_per_buyer'] = (s['sku_rev'] / s['buyers']) if s['buyers'] else 0.0
+        segments.append(s)
+    dep.sort(key=lambda x: -x['sku_rev'])
+    deps_known = [d['dependency_pct'] for d in dep if d['dependency_pct'] is not None]
+    return {'segments': segments, 'dependency': dep[:top], 'n_buyers': len(buyers),
+            'avg_dependency': (sum(deps_known) / len(deps_known)) if deps_known else 0.0}
+
+
+def sku_whitespace(code, t=None, team_id=None, top=15):
+    """Customers who buy this SKU's category but NOT this SKU — ranked prospect list."""
+    import modules.customers as cust_mod
+    t = t or P.today()
+    pids = _sku_product_ids(code)
+    _name, category = _sku_name_category(pids)
+    cat_buyers = cust_mod.category_buyers(category, team_id=team_id) or set()
+    mf, mt = P.ltm(t)
+    prospects = list(cat_buyers - set(_sku_buyers(pids, mf, mt, team_id)))
+    if not prospects:
+        return {'category': category, 'rows': []}
+    g = O.read_group('sale.order', sales_mod.order_domain(mf, mt, team_id) + [('partner_id', 'in', prospects)],
+                     ['amount_untaxed:sum'], ['partner_id'], lazy=False)
+    rows = [{'pid': O.m2o_id(r['partner_id']), 'customer': O.m2o_name(r['partner_id']),
+             'total_spend': r.get('amount_untaxed') or 0.0} for r in g if r.get('partner_id')]
+    rows.sort(key=lambda x: -x['total_spend'])
+    return {'category': category, 'rows': rows[:top]}
+
+
+def sku_drawer_bundle(code, t=None, team_id=None, allsku=None):
+    """The whole SKU drawer's first paint in one cached unit: sku_detail first (the not-found gate),
+    then the other six pulls CONCURRENTLY (O.parallel). Cuts a ~6-call cold open to ~max(call)."""
+    detail = sku_detail(code, t=t, team_id=team_id, allsku=allsku)
+    if detail is None:
+        return {'detail': None}
+    bridge, conc, price, buyers, white, ca = O.parallel([
+        lambda: sku_buyer_bridge(code, t, team_id),
+        lambda: sku_concentration(code, t, team_id),
+        lambda: sku_price_dispersion(code, t, team_id),
+        lambda: sku_top_buyers(code, t, team_id),
+        lambda: sku_whitespace(code, t, team_id),
+        lambda: sku_customer_analysis(code, t, team_id),
+    ])
+    return {'detail': detail, 'bridge': bridge, 'conc': conc, 'price': price,
+            'buyers': buyers, 'white': white, 'ca': ca}
+
+
+def validate(t=None, team_id=None):
+    """Reconcile SKU metrics to independent Odoo aggregates. When team_id is set (a single BU
+    selected) every check runs SCOPED to that BU, so the validation panel never reconciles
+    against — or exposes — the other BU's numbers. All checks here are BU-scopeable (no cross-BU
+    mirror), so team_id threads straight through."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    checks = []
+    sku = _sku_rev(yf, yt, team_id)
+    sku_sum = sum(v['rev'] for v in sku.values())
+    line_total = O.sum_field('sale.order.line',
+                             O.sale_line_domain(yf, yt, team_id, extra=_NO_SVC), 'price_subtotal')
+    checks.append({'check': 'SKU rev: Σ(per-SKU) == total line revenue, ex-services (YTD)',
+                   'a': round(sku_sum, 2), 'b': round(line_total, 2),
+                   'gap': round(sku_sum - line_total, 2),
+                   'ok': abs(sku_sum - line_total) <= 1.0})
+
+    m = yoy_movers(t, limit=10**9, team_id=team_id)
+    movers_sum = sum(r['change'] for r in m['risers']) + sum(r['change'] for r in m['decliners'])
+    lf, lt = P.ytd_last_year(t)
+    last_total = O.sum_field('sale.order.line',
+                             O.sale_line_domain(lf, lt, team_id, extra=_NO_SVC), 'price_subtotal')
+    checks.append({'check': 'SKU movers: Σ(Δ) == (YTD − LY) total',
+                   'a': round(movers_sum, 2), 'b': round(line_total - last_total, 2),
+                   'gap': round(movers_sum - (line_total - last_total), 2),
+                   'ok': abs(movers_sum - (line_total - last_total)) <= 1.0})
+
+    # SKU drawer: buyer-bridge reconciles — retained + new buyer revenue == this-period SKU revenue
+    top_code = max(sku.items(), key=lambda kv: kv[1]['rev'])[0] if sku else None
+    if top_code:
+        bb = sku_buyer_bridge(top_code, t, team_id=team_id)
+        recon = bb['retained']['rev'] + bb['new']['rev']
+        checks.append({'check': 'SKU drawer: retained+new buyer rev == SKU YTD revenue',
+                       'a': round(recon, 2), 'b': round(bb['this_total'], 2),
+                       'gap': round(recon - bb['this_total'], 2),
+                       'ok': abs(recon - bb['this_total']) <= 1.0})
+    return checks

web/public/sample_customers.json

@@ -1,558 +1,558 @@
-{
-  "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": "partner_id",
-      "label": "Odoo ID",
-      "type": "int",
-      "source": "odoo",
-      "derived": true,
-      "default": false,
-      "description": "The Odoo res.partner id — the key every Odoo document joins on. DERIVED: this row's pid IS the partner id, so a stored copy would be a second source."
-    },
-    {
-      "key": "odoo_status",
-      "label": "Odoo record",
-      "type": "status",
-      "source": "odoo",
-      "default": false,
-      "options": [
-        "Active",
-        "Archived"
-      ],
-      "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
-    }
-  ]
-}
+{
+  "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": "partner_id",
+      "label": "Odoo ID",
+      "type": "int",
+      "source": "odoo",
+      "derived": true,
+      "default": false,
+      "description": "The Odoo res.partner id — the key every Odoo document joins on. DERIVED: this row's pid IS the partner id, so a stored copy would be a second source."
+    },
+    {
+      "key": "odoo_status",
+      "label": "Odoo record",
+      "type": "status",
+      "source": "odoo",
+      "default": false,
+      "options": [
+        "Active",
+        "Archived"
+      ],
+      "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/alerts/alertsModel.ts

@@ -1,418 +1,418 @@
-// ---------------------------------------------------------------------------
-// alerts/alertsModel.ts — WAVE 20 item 25 (contract C-ALERT): the inbox's PURE
-// half. React-free and fetch-free, so `verify_alerts.py` runs it under node.
-//
-// An alert says "tell me when a record ENTERS this view". The client half is
-// small, and every part of it fails silently when it is wrong:
-//
-//   · an unread count taken from `items.length` rather than from the server's
-//     own `unread` disagrees with the badge the moment a page is capped or a
-//     read lands in another tab — and a badge that says 3 when the list shows 9
-//     teaches the reader to ignore the badge;
-//   · a notification whose `viewId` no longer resolves must open NOTHING rather
-//     than a wrong view — alerts outlive the views they were made from;
-//   · `topic` is the surface's scope key ("customer", "product", "ut_…"), and
-//     the ROUTE is a registry key ("customer_data") — mapping one to the other
-//     by guesswork sends every click to a page that does not exist.
-// ---------------------------------------------------------------------------
-
-/**
- * ⭐⭐ WAVE 32 · T20 · CONTRACT C3 — WHERE AN INBOX ITEM OPENS.
- *
- * `module` is the destination surface (`"database"` or `"automation"`) and `id` is what to open
- * in it. `tab` is the SUB-SELECTION inside that module: the literal `"runs"` for an automation's
- * run log, or the VIEW ID to select on a database. One optional key, two destinations.
- *
- * ⛔ EVERY FIELD IS A PLAIN `string`, NEVER A UNION, and that is alertsModel's wave-9 law rather
- * than laziness: the vocabulary is the SERVER's, and a client union over it turns "the server grew
- * a module" into "the client silently drops the row". An unknown module is refused by the
- * FRAME's dispatcher, out loud, which is a different thing from never arriving.
- */
-export interface NotificationTarget {
-  module: string;
-  id: string;
-  tab?: string;
-}
-
-/** C3's `kind` vocabulary, mirroring `routes_alerts.NOTIF_KIND_*`. Held as constants so the
- *  Inbox's branch and the gate's fixtures cannot disagree about the word. */
-export const NOTIF_KIND_ALERT = "alert";
-export const NOTIF_KIND_AUTOMATION = "automation";
-export const NOTIF_KIND_SHARE = "share";
-
-/** C3's `target.module` vocabulary, and the automation sub-selection. */
-export const TARGET_MODULE_DATABASE = "database";
-export const TARGET_MODULE_AUTOMATION = "automation";
-export const TARGET_TAB_RUNS = "runs";
-
-/** One notification, as `GET /api/v1/notifications` sends it. */
-export interface Notification {
-  id: string;
-  alertId: string;
-  viewId: string;
-  topic: string;
-  rowId: string;
-  /** What entered — the record's own label. */
-  label: string;
-  /** What the alert is called, so a row reads without opening anything. */
-  alertLabel: string;
-  /** UTC WITH OFFSET (D-18). Kept as the server's STRING: re-formatting it here
-   *  would re-introduce the browser-clock drift the offset exists to remove. */
-  at: string;
-  read: boolean;
-  /**
-   * WAVE 23 (contract C6) — WHAT KIND of notification this is.
-   *
-   * Absent (and every notification written before this wave) means the original one: a record
-   * ENTERED a watched view, routed by `topic` + `viewId`. `"automation_review"` means a card
-   * arrived at a review stage and routes by `autoId` instead — a different destination reached
-   * from the same list.
-   *
-   * ⛔ A STRING, NEVER A UNION, and that is the wave-9 law rather than laziness: the vocabulary
-   * is the SERVER's, and a client union over it turns "the server grew a kind" into "the client
-   * silently drops the row". Unknown kinds fall through to the view route, which is exactly what
-   * they did before this field existed.
-   */
-  kind?: string;
-  /** `automation_review` only: the automation whose review stage a card reached. Absent on
-   *  every other kind — and an `automation_review` row that arrives WITHOUT one opens nothing
-   *  rather than guessing, the same posture `viewId` gets. */
-  autoId?: string;
-  /** Advisory. A surface that does not scroll to a stage simply selects the automation. */
-  stageId?: string;
-  /** How many cards arrived in the batch. C6 queues ONE notification per run naming the count,
-   *  never one per record — so this is the number the row's own text is built from. */
-  count?: number;
-  /**
-   * ⭐ WAVE 32 · C3 — THE HEADER LINE, so the Inbox can be laid out like mail.
-   *
-   * `subject` is what the item is ABOUT (the alert's name, the automation's name, the database
-   * that was shared); `label` stays what HAPPENED (the record that entered, the run summary).
-   * They were one field, which is why the pane could only ever render a sentence with no sender.
-   * Absent on a server that predates this wave — {@link subjectOf} falls back rather than
-   * rendering a blank header.
-   */
-  subject?: string;
-  /**
-   * ⭐⭐ WAVE 33 · W33-T28 — WHO IT IS FROM. Mail has a sender; this list did not.
-   *
-   * A `verifier` reading the finished wave-32 Inbox found the row's sender POSITION occupied by
-   * `kindLabel(n.kind)` — the literals "Alert" / "Automation" / "Shared with you", a CATEGORY
-   * standing where a who belongs — and no sender anywhere on the wire. Derived by the server
-   * (`routes_alerts.notification_view`), never here: only it knows that a share has a person
-   * behind it and an alert has a machine.
-   * ⚠ Optional, so a payload from a server that predates this wave keeps today's shape;
-   * {@link senderOf} falls back rather than rendering a blank From column.
-   */
-  sender?: string;
-  /** ⭐ WAVE 32 · C3 — where clicking it goes. ABSENT when this product cannot resolve a
-   *  destination (an alert on a table this account can no longer route to), and that absence is
-   *  load-bearing: the Inbox renders such a row as plainly unclickable rather than as a click
-   *  that silently does nothing. */
-  target?: NotificationTarget;
-}
-
-/** One alert, as `GET /api/v1/alerts` sends it. */
-export interface Alert {
-  id: string;
-  viewId: string;
-  topic: string;
-  owner: string;
-  label: string;
-  createdAt: string;
-  /** How many records are in its remembered set right now. */
-  matched: number;
-  seeded: boolean;
-  lastRunAt: string;
-  lastError: string;
-}
-
-export interface Inbox {
-  unread: number;
-  items: Notification[];
-  /**
-   * ⭐⭐ WAVE 33 · W33-T28 / D-208 — THE SERVER'S CLOCK, so a stamp can be mail-shaped.
-   *
-   * ⛔ It exists so {@link stampText} never reads the BROWSER's clock, which is D-208's exit
-   * condition word for word. `at` is UTC with its offset (D-18) precisely so every reader sees
-   * the same instant; asking "is this today?" of a local clock would put the drift back.
-   * ⚠ Optional: absent, `stampText` returns the old absolute string rather than guessing.
-   */
-  now?: string;
-}
-
-export const EMPTY_INBOX: Inbox = { unread: 0, items: [] };
-
-/**
- * ⭐⭐ WAVE 31 · T23 (owner item 1) — WHAT THE PANE IS ENTITLED TO SAY, AS A FUNCTION.
- *
- * Owner, verbatim: *"Alerts shows notification, but when clicked it says nothing, and it doesn't
- * remove the notification number."* Both halves are ONE mechanism. `AlertsPane` held its own
- * `inbox` seeded to {@link EMPTY_INBOX} and had no pending state, so between opening the panel
- * and `GET /notifications` answering — measured at **3,280 ms live** — and for ever after a
- * failed fetch:
- *   · `items` was `[]`, so the pane printed **"Nothing new."** — a claim, not a wait;
- *   · `unread` was `0`, so **"Mark all read" was `disabled`**, and the badge the frame had
- *     already loaded could never be cleared.
- * A confident sentence about somebody's inbox, and the one control that would fix it, both
- * switched off by the same uninitialised state.
- *
- * ⛔ IT IS A FUNCTION BECAUSE THE PANE IS TSX AND TSX IS NOT UNDER TEST HERE. `verify_alerts`
- * compiles and RUNS this module under node; markup it cannot reach is markup no control can
- * mutate. Deciding here means the truth table is asserted and each branch is load-bearing.
- */
-export type PaneView = "pending" | "rows" | "empty" | "error";
-
-/**
- * `pending` while the first read is in flight · `error` when it failed and we have nothing to
- * show · `rows` when there is something · `empty` ONLY when a successful read returned nothing.
- *
- * ⚠ ROWS WIN OVER AN ERROR, and that is deliberate rather than lax: a refresh that fails while
- * the pane already holds notifications should not blank them — the reader loses real information
- * to a transient. The error still reaches them as the pane's message line.
- */
-export function paneView(
-  phase: "pending" | "ready" | "error",
-  rowCount: number,
-  seededUnread = 0
-): PaneView {
-  if (rowCount > 0) return "rows";
-  if (phase === "pending") return "pending";
-  if (phase === "error") return "error";
-  // ⚠ A SUCCESSFUL READ WITH NO ROWS AND A NON-ZERO COUNT IS NOT "nothing new". The badge says
-  // there is something; the page we were given does not contain it. Saying "Nothing new" there
-  // is the same false confidence in a different costume.
-  return seededUnread > 0 ? "error" : "empty";
-}
-
-/**
- * May "Mark all read" be pressed?
- *
- * ⛔ NOT `unread === 0`, WHICH IS THE SHIPPED BUG. That test asked the PANE's own state — zero
- * until its fetch lands, zero for ever if the fetch fails — so the control was dead in exactly
- * the situations the owner hit. The question is about the ACCOUNT, so it is asked of the count
- * the frame already holds, and a failed read does not take the verb away: `POST /notifications/
- * read` with `ids: null` clears the account's inbox whether or not we managed to list it.
- */
-export function canMarkAll(unread: number, busy = false): boolean {
-  return !busy && Math.max(0, Math.floor(unread)) > 0;
-}
-
-const str = (v: unknown): string => (typeof v === "string" ? v : "");
-const num = (v: unknown): number => (typeof v === "number" && isFinite(v) ? v : 0);
-
-/**
- * ⭐ WAVE 32 · C3 — one wire `target` → a {@link NotificationTarget}, or `null`.
- *
- * ⛔ BOTH `module` AND `id` ARE REQUIRED, and dropping either test is the failure this guard is
- * for: a target with a module and no id dispatches an open request naming NOTHING — a click that
- * appears to work and silently does not, which is this repo's most-repeated shape. `null` is
- * rendered as an unclickable row, which a reader can SEE.
- */
-export function parseTarget(raw: unknown): NotificationTarget | null {
-  if (!raw || typeof raw !== "object") return null;
-  const t = raw as Record<string, unknown>;
-  const module = str(t.module).trim();
-  const id = str(t.id).trim();
-  if (!module || !id) return null;
-  const tab = str(t.tab).trim();
-  return { module, id, ...(tab ? { tab } : {}) };
-}
-
-/**
- * `GET /notifications` → the inbox, fail-closed.
- *
- * ⚠ `unread` COMES FROM THE SERVER, and is not recounted from `items`. The two
- * can legitimately differ — the list is what this page holds, the count is what
- * the account has — and recomputing it here would make the badge a function of
- * whatever the last fetch happened to include.
- */
-export function parseInbox(body: unknown): Inbox {
-  const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
-  const raw = Array.isArray(b.items) ? b.items : [];
-  const items: Notification[] = [];
-  for (const item of raw) {
-    if (!item || typeof item !== "object") continue;
-    const n = item as Record<string, unknown>;
-    const id = str(n.id);
-    // An id-less notification cannot be marked read, so it would sit unread for
-    // ever and hold the badge up. Dropped, not rendered.
-    if (!id) continue;
-    items.push({
-      id,
-      alertId: str(n.alertId),
-      viewId: str(n.viewId),
-      topic: str(n.topic),
-      rowId: String(n.rowId ?? ""),
-      label: str(n.label) || String(n.rowId ?? ""),
-      alertLabel: str(n.alertLabel),
-      at: str(n.at),
-      read: n.read === true,
-      // WAVE 23 C6 — ADDITIVE and spread-conditional, exactly like `NavPage`'s flags: a payload
-      // that predates this wave keeps today's shape rather than gaining four `undefined` keys,
-      // and an `automation_review` row missing its `autoId` is left WITHOUT one rather than
-      // with an empty string that would render as a real destination.
-      ...(str(n.kind) ? { kind: str(n.kind) } : {}),
-      ...(str(n.autoId) ? { autoId: str(n.autoId) } : {}),
-      ...(str(n.stageId) ? { stageId: str(n.stageId) } : {}),
-      ...(num(n.count) > 0 ? { count: num(n.count) } : {}),
-      // ⭐ WAVE 32 · C3 — additive and spread-conditional, exactly like the four above.
-      ...(str(n.subject) ? { subject: str(n.subject) } : {}),
-      // ⭐ WAVE 33 · W33-T28 — additive and spread-conditional, like every flag above it.
-      ...(str(n.sender) ? { sender: str(n.sender) } : {}),
-      ...(parseTarget(n.target) ? { target: parseTarget(n.target)! } : {}),
-    });
-  }
-  // ⭐ W33-T28 / D-208 — the server's clock rides through, spread-conditionally like every other
-  // additive key here, so a server that predates this wave yields the same object it always did.
-  return {
-    unread: Math.max(0, num(b.unread)),
-    items,
-    ...(str(b.now) ? { now: str(b.now) } : {}),
-  };
-}
-
-/** `GET /alerts` → the alert list, fail-closed. */
-export function parseAlerts(body: unknown): Alert[] {
-  const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
-  const raw = Array.isArray(b.alerts) ? b.alerts : [];
-  const out: Alert[] = [];
-  for (const item of raw) {
-    if (!item || typeof item !== "object") continue;
-    const a = item as Record<string, unknown>;
-    const id = str(a.id);
-    if (!id) continue;
-    out.push({
-      id,
-      viewId: str(a.viewId),
-      topic: str(a.topic),
-      owner: str(a.owner),
-      label: str(a.label) || "Untitled alert",
-      createdAt: str(a.createdAt),
-      matched: num(a.matched),
-      seeded: a.seeded === true,
-      lastRunAt: str(a.lastRunAt),
-      lastError: str(a.lastError),
-    });
-  }
-  return out;
-}
-
-/**
- * A topic (the grid's scope key) → the hash route that renders it.
- *
- * The two built-ins are the only pair that differ, and they differ because the
- * REGISTRY names the surface while the GRID names the scope; a user table is its
- * own key in both. `null` for anything else: a notification for a topic this
- * client cannot route to must do nothing, not navigate somewhere plausible.
- */
-export function routeForTopic(topic: string): string | null {
-  const t = str(topic).trim();
-  if (t === "customer") return "customer_data";
-  if (t === "product") return "product_data";
-  if (/^ut_[A-Za-z0-9_]+$/.test(t)) return t;
-  return null;
-}
-
-
-
-
-
-
-/**
- * The stamp, made readable WITHOUT touching a clock.
- *
- * ⛔ NO `new Date()`, NO `toLocaleString()`, and that is the whole design. The
- * server sends UTC WITH ITS OFFSET (D-18) precisely so every reader sees the
- * same instant; parsing it into a browser Date and formatting it back would
- * re-introduce the drift the offset exists to remove — a tenant a day ahead
- * being told an event happened tomorrow ([[date-window-vocabulary]]). This is
- * STRING SURGERY: keep the date and the minutes, drop the seconds and the `T`.
- * Anything that does not look like an ISO stamp passes through untouched, so a
- * format this function has never seen is shown as sent rather than mangled.
- */
-const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
-                "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
-
-export function stampText(at: string, now?: string): string {
-  const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(str(at));
-  if (!m) return str(at);
-  const [, day, hhmm] = m;
-  // ⭐⭐ W33-T28 / D-208 — MAIL-SHAPED, AND STILL STRING SURGERY.
-  //
-  // ⛔ `now` COMES FROM THE SERVER (`inbox.now`), NEVER FROM `new Date()`. That is D-208's exit
-  // condition word for word — "without reading the browser clock" — and the reason is the same
-  // one this function has always carried: `at` is sent as UTC WITH its offset (D-18) so every
-  // reader sees the same instant, and deciding "is this today?" against a browser clock would
-  // re-introduce exactly the drift the offset removes. Both operands are the server's.
-  //
-  // ⚠ AND WITHOUT `now` IT DEGRADES TO THE OLD FORMAT RATHER THAN GUESSING. A caller that has no
-  // server clock gets `2026-08-13 09:41` — the pre-wave string, unambiguous and never wrong —
-  // instead of a relative stamp computed from something we do not trust.
-  const today = /^(\d{4}-\d{2}-\d{2})/.exec(str(now));
-  if (!today) return `${day} ${hhmm}`;
-  if (today[1] === day) return hhmm;
-  const [y, mo, d] = day.split("-");
-  const month = MONTHS[Number(mo) - 1] || mo;
-  // The year only when it differs — a mail client does not print "2026" on a message from March.
-  return today[1].slice(0, 4) === y
-    ? `${month} ${Number(d)}`
-    : `${month} ${Number(d)}, ${y}`;
-}
-
-/**
- * The badge's text. Never the raw number past 99: a nav row is 236px wide and a
- * four-digit badge pushes the label out of it.
- */
-export function badgeText(unread: number): string {
-  const n = Math.max(0, Math.floor(unread));
-  if (n <= 0) return "";
-  return n > 99 ? "99+" : String(n);
-}
-
-/**
- * Apply a read/unread change LOCALLY, mirroring what the server just stored, and
- * return the new inbox with the count corrected.
- *
- * `ids === null` is "all of them" (the API's own convention for mark-all). The
- * count is derived from the ITEMS here — deliberately, and it is the one place
- * that is right to do so: the server's answer is in flight, and the alternative
- * is a badge that keeps its old number until the refetch lands.
- */
-export function applyRead(inbox: Inbox, ids: string[] | null, read: boolean): Inbox {
-  const wanted = ids === null ? null : new Set(ids);
-  const items = inbox.items.map((n) =>
-    wanted === null || wanted.has(n.id) ? { ...n, read } : n
-  );
-  const seenUnread = items.filter((n) => !n.read).length;
-  // A page can hold fewer notifications than the account has, so a partial read
-  // must SUBTRACT from the server's count rather than replace it with this
-  // page's tally — except when marking everything, where zero is the answer.
-  if (wanted === null) return { unread: read ? 0 : items.length, items };
-  const changed = inbox.items.filter(
-    (n) => wanted.has(n.id) && n.read !== read
-  ).length;
-  const delta = read ? -changed : changed;
-  return { unread: Math.max(seenUnread, inbox.unread + delta), items };
-}
-
-/**
- * The shell↔rail channel for "make an alert out of this view" — the view rail
- * raises it, the frame (which knows the current route, and therefore the topic)
- * answers. Same reason as C-SHARE's event: the rail is host-neutral and cannot
- * import the shell, and it does not know its own scope key.
- */
-export const ALERT_CREATE_EVENT = "aios:alert-create";
-
-export interface AlertCreateRequest {
-  viewId: string;
-  label: string;
-}
-
-export function parseAlertCreate(detail: unknown): AlertCreateRequest | null {
-  if (!detail || typeof detail !== "object") return null;
-  const d = detail as Record<string, unknown>;
-  const viewId = str(d.viewId).trim();
-  if (!viewId) return null;
-  return { viewId, label: str(d.label).trim() || viewId };
-}
+// ---------------------------------------------------------------------------
+// alerts/alertsModel.ts — WAVE 20 item 25 (contract C-ALERT): the inbox's PURE
+// half. React-free and fetch-free, so `verify_alerts.py` runs it under node.
+//
+// An alert says "tell me when a record ENTERS this view". The client half is
+// small, and every part of it fails silently when it is wrong:
+//
+//   · an unread count taken from `items.length` rather than from the server's
+//     own `unread` disagrees with the badge the moment a page is capped or a
+//     read lands in another tab — and a badge that says 3 when the list shows 9
+//     teaches the reader to ignore the badge;
+//   · a notification whose `viewId` no longer resolves must open NOTHING rather
+//     than a wrong view — alerts outlive the views they were made from;
+//   · `topic` is the surface's scope key ("customer", "product", "ut_…"), and
+//     the ROUTE is a registry key ("customer_data") — mapping one to the other
+//     by guesswork sends every click to a page that does not exist.
+// ---------------------------------------------------------------------------
+
+/**
+ * ⭐⭐ WAVE 32 · T20 · CONTRACT C3 — WHERE AN INBOX ITEM OPENS.
+ *
+ * `module` is the destination surface (`"database"` or `"automation"`) and `id` is what to open
+ * in it. `tab` is the SUB-SELECTION inside that module: the literal `"runs"` for an automation's
+ * run log, or the VIEW ID to select on a database. One optional key, two destinations.
+ *
+ * ⛔ EVERY FIELD IS A PLAIN `string`, NEVER A UNION, and that is alertsModel's wave-9 law rather
+ * than laziness: the vocabulary is the SERVER's, and a client union over it turns "the server grew
+ * a module" into "the client silently drops the row". An unknown module is refused by the
+ * FRAME's dispatcher, out loud, which is a different thing from never arriving.
+ */
+export interface NotificationTarget {
+  module: string;
+  id: string;
+  tab?: string;
+}
+
+/** C3's `kind` vocabulary, mirroring `routes_alerts.NOTIF_KIND_*`. Held as constants so the
+ *  Inbox's branch and the gate's fixtures cannot disagree about the word. */
+export const NOTIF_KIND_ALERT = "alert";
+export const NOTIF_KIND_AUTOMATION = "automation";
+export const NOTIF_KIND_SHARE = "share";
+
+/** C3's `target.module` vocabulary, and the automation sub-selection. */
+export const TARGET_MODULE_DATABASE = "database";
+export const TARGET_MODULE_AUTOMATION = "automation";
+export const TARGET_TAB_RUNS = "runs";
+
+/** One notification, as `GET /api/v1/notifications` sends it. */
+export interface Notification {
+  id: string;
+  alertId: string;
+  viewId: string;
+  topic: string;
+  rowId: string;
+  /** What entered — the record's own label. */
+  label: string;
+  /** What the alert is called, so a row reads without opening anything. */
+  alertLabel: string;
+  /** UTC WITH OFFSET (D-18). Kept as the server's STRING: re-formatting it here
+   *  would re-introduce the browser-clock drift the offset exists to remove. */
+  at: string;
+  read: boolean;
+  /**
+   * WAVE 23 (contract C6) — WHAT KIND of notification this is.
+   *
+   * Absent (and every notification written before this wave) means the original one: a record
+   * ENTERED a watched view, routed by `topic` + `viewId`. `"automation_review"` means a card
+   * arrived at a review stage and routes by `autoId` instead — a different destination reached
+   * from the same list.
+   *
+   * ⛔ A STRING, NEVER A UNION, and that is the wave-9 law rather than laziness: the vocabulary
+   * is the SERVER's, and a client union over it turns "the server grew a kind" into "the client
+   * silently drops the row". Unknown kinds fall through to the view route, which is exactly what
+   * they did before this field existed.
+   */
+  kind?: string;
+  /** `automation_review` only: the automation whose review stage a card reached. Absent on
+   *  every other kind — and an `automation_review` row that arrives WITHOUT one opens nothing
+   *  rather than guessing, the same posture `viewId` gets. */
+  autoId?: string;
+  /** Advisory. A surface that does not scroll to a stage simply selects the automation. */
+  stageId?: string;
+  /** How many cards arrived in the batch. C6 queues ONE notification per run naming the count,
+   *  never one per record — so this is the number the row's own text is built from. */
+  count?: number;
+  /**
+   * ⭐ WAVE 32 · C3 — THE HEADER LINE, so the Inbox can be laid out like mail.
+   *
+   * `subject` is what the item is ABOUT (the alert's name, the automation's name, the database
+   * that was shared); `label` stays what HAPPENED (the record that entered, the run summary).
+   * They were one field, which is why the pane could only ever render a sentence with no sender.
+   * Absent on a server that predates this wave — {@link subjectOf} falls back rather than
+   * rendering a blank header.
+   */
+  subject?: string;
+  /**
+   * ⭐⭐ WAVE 33 · W33-T28 — WHO IT IS FROM. Mail has a sender; this list did not.
+   *
+   * A `verifier` reading the finished wave-32 Inbox found the row's sender POSITION occupied by
+   * `kindLabel(n.kind)` — the literals "Alert" / "Automation" / "Shared with you", a CATEGORY
+   * standing where a who belongs — and no sender anywhere on the wire. Derived by the server
+   * (`routes_alerts.notification_view`), never here: only it knows that a share has a person
+   * behind it and an alert has a machine.
+   * ⚠ Optional, so a payload from a server that predates this wave keeps today's shape;
+   * {@link senderOf} falls back rather than rendering a blank From column.
+   */
+  sender?: string;
+  /** ⭐ WAVE 32 · C3 — where clicking it goes. ABSENT when this product cannot resolve a
+   *  destination (an alert on a table this account can no longer route to), and that absence is
+   *  load-bearing: the Inbox renders such a row as plainly unclickable rather than as a click
+   *  that silently does nothing. */
+  target?: NotificationTarget;
+}
+
+/** One alert, as `GET /api/v1/alerts` sends it. */
+export interface Alert {
+  id: string;
+  viewId: string;
+  topic: string;
+  owner: string;
+  label: string;
+  createdAt: string;
+  /** How many records are in its remembered set right now. */
+  matched: number;
+  seeded: boolean;
+  lastRunAt: string;
+  lastError: string;
+}
+
+export interface Inbox {
+  unread: number;
+  items: Notification[];
+  /**
+   * ⭐⭐ WAVE 33 · W33-T28 / D-208 — THE SERVER'S CLOCK, so a stamp can be mail-shaped.
+   *
+   * ⛔ It exists so {@link stampText} never reads the BROWSER's clock, which is D-208's exit
+   * condition word for word. `at` is UTC with its offset (D-18) precisely so every reader sees
+   * the same instant; asking "is this today?" of a local clock would put the drift back.
+   * ⚠ Optional: absent, `stampText` returns the old absolute string rather than guessing.
+   */
+  now?: string;
+}
+
+export const EMPTY_INBOX: Inbox = { unread: 0, items: [] };
+
+/**
+ * ⭐⭐ WAVE 31 · T23 (owner item 1) — WHAT THE PANE IS ENTITLED TO SAY, AS A FUNCTION.
+ *
+ * Owner, verbatim: *"Alerts shows notification, but when clicked it says nothing, and it doesn't
+ * remove the notification number."* Both halves are ONE mechanism. `AlertsPane` held its own
+ * `inbox` seeded to {@link EMPTY_INBOX} and had no pending state, so between opening the panel
+ * and `GET /notifications` answering — measured at **3,280 ms live** — and for ever after a
+ * failed fetch:
+ *   · `items` was `[]`, so the pane printed **"Nothing new."** — a claim, not a wait;
+ *   · `unread` was `0`, so **"Mark all read" was `disabled`**, and the badge the frame had
+ *     already loaded could never be cleared.
+ * A confident sentence about somebody's inbox, and the one control that would fix it, both
+ * switched off by the same uninitialised state.
+ *
+ * ⛔ IT IS A FUNCTION BECAUSE THE PANE IS TSX AND TSX IS NOT UNDER TEST HERE. `verify_alerts`
+ * compiles and RUNS this module under node; markup it cannot reach is markup no control can
+ * mutate. Deciding here means the truth table is asserted and each branch is load-bearing.
+ */
+export type PaneView = "pending" | "rows" | "empty" | "error";
+
+/**
+ * `pending` while the first read is in flight · `error` when it failed and we have nothing to
+ * show · `rows` when there is something · `empty` ONLY when a successful read returned nothing.
+ *
+ * ⚠ ROWS WIN OVER AN ERROR, and that is deliberate rather than lax: a refresh that fails while
+ * the pane already holds notifications should not blank them — the reader loses real information
+ * to a transient. The error still reaches them as the pane's message line.
+ */
+export function paneView(
+  phase: "pending" | "ready" | "error",
+  rowCount: number,
+  seededUnread = 0
+): PaneView {
+  if (rowCount > 0) return "rows";
+  if (phase === "pending") return "pending";
+  if (phase === "error") return "error";
+  // ⚠ A SUCCESSFUL READ WITH NO ROWS AND A NON-ZERO COUNT IS NOT "nothing new". The badge says
+  // there is something; the page we were given does not contain it. Saying "Nothing new" there
+  // is the same false confidence in a different costume.
+  return seededUnread > 0 ? "error" : "empty";
+}
+
+/**
+ * May "Mark all read" be pressed?
+ *
+ * ⛔ NOT `unread === 0`, WHICH IS THE SHIPPED BUG. That test asked the PANE's own state — zero
+ * until its fetch lands, zero for ever if the fetch fails — so the control was dead in exactly
+ * the situations the owner hit. The question is about the ACCOUNT, so it is asked of the count
+ * the frame already holds, and a failed read does not take the verb away: `POST /notifications/
+ * read` with `ids: null` clears the account's inbox whether or not we managed to list it.
+ */
+export function canMarkAll(unread: number, busy = false): boolean {
+  return !busy && Math.max(0, Math.floor(unread)) > 0;
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+const num = (v: unknown): number => (typeof v === "number" && isFinite(v) ? v : 0);
+
+/**
+ * ⭐ WAVE 32 · C3 — one wire `target` → a {@link NotificationTarget}, or `null`.
+ *
+ * ⛔ BOTH `module` AND `id` ARE REQUIRED, and dropping either test is the failure this guard is
+ * for: a target with a module and no id dispatches an open request naming NOTHING — a click that
+ * appears to work and silently does not, which is this repo's most-repeated shape. `null` is
+ * rendered as an unclickable row, which a reader can SEE.
+ */
+export function parseTarget(raw: unknown): NotificationTarget | null {
+  if (!raw || typeof raw !== "object") return null;
+  const t = raw as Record<string, unknown>;
+  const module = str(t.module).trim();
+  const id = str(t.id).trim();
+  if (!module || !id) return null;
+  const tab = str(t.tab).trim();
+  return { module, id, ...(tab ? { tab } : {}) };
+}
+
+/**
+ * `GET /notifications` → the inbox, fail-closed.
+ *
+ * ⚠ `unread` COMES FROM THE SERVER, and is not recounted from `items`. The two
+ * can legitimately differ — the list is what this page holds, the count is what
+ * the account has — and recomputing it here would make the badge a function of
+ * whatever the last fetch happened to include.
+ */
+export function parseInbox(body: unknown): Inbox {
+  const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
+  const raw = Array.isArray(b.items) ? b.items : [];
+  const items: Notification[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const n = item as Record<string, unknown>;
+    const id = str(n.id);
+    // An id-less notification cannot be marked read, so it would sit unread for
+    // ever and hold the badge up. Dropped, not rendered.
+    if (!id) continue;
+    items.push({
+      id,
+      alertId: str(n.alertId),
+      viewId: str(n.viewId),
+      topic: str(n.topic),
+      rowId: String(n.rowId ?? ""),
+      label: str(n.label) || String(n.rowId ?? ""),
+      alertLabel: str(n.alertLabel),
+      at: str(n.at),
+      read: n.read === true,
+      // WAVE 23 C6 — ADDITIVE and spread-conditional, exactly like `NavPage`'s flags: a payload
+      // that predates this wave keeps today's shape rather than gaining four `undefined` keys,
+      // and an `automation_review` row missing its `autoId` is left WITHOUT one rather than
+      // with an empty string that would render as a real destination.
+      ...(str(n.kind) ? { kind: str(n.kind) } : {}),
+      ...(str(n.autoId) ? { autoId: str(n.autoId) } : {}),
+      ...(str(n.stageId) ? { stageId: str(n.stageId) } : {}),
+      ...(num(n.count) > 0 ? { count: num(n.count) } : {}),
+      // ⭐ WAVE 32 · C3 — additive and spread-conditional, exactly like the four above.
+      ...(str(n.subject) ? { subject: str(n.subject) } : {}),
+      // ⭐ WAVE 33 · W33-T28 — additive and spread-conditional, like every flag above it.
+      ...(str(n.sender) ? { sender: str(n.sender) } : {}),
+      ...(parseTarget(n.target) ? { target: parseTarget(n.target)! } : {}),
+    });
+  }
+  // ⭐ W33-T28 / D-208 — the server's clock rides through, spread-conditionally like every other
+  // additive key here, so a server that predates this wave yields the same object it always did.
+  return {
+    unread: Math.max(0, num(b.unread)),
+    items,
+    ...(str(b.now) ? { now: str(b.now) } : {}),
+  };
+}
+
+/** `GET /alerts` → the alert list, fail-closed. */
+export function parseAlerts(body: unknown): Alert[] {
+  const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
+  const raw = Array.isArray(b.alerts) ? b.alerts : [];
+  const out: Alert[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const a = item as Record<string, unknown>;
+    const id = str(a.id);
+    if (!id) continue;
+    out.push({
+      id,
+      viewId: str(a.viewId),
+      topic: str(a.topic),
+      owner: str(a.owner),
+      label: str(a.label) || "Untitled alert",
+      createdAt: str(a.createdAt),
+      matched: num(a.matched),
+      seeded: a.seeded === true,
+      lastRunAt: str(a.lastRunAt),
+      lastError: str(a.lastError),
+    });
+  }
+  return out;
+}
+
+/**
+ * A topic (the grid's scope key) → the hash route that renders it.
+ *
+ * The two built-ins are the only pair that differ, and they differ because the
+ * REGISTRY names the surface while the GRID names the scope; a user table is its
+ * own key in both. `null` for anything else: a notification for a topic this
+ * client cannot route to must do nothing, not navigate somewhere plausible.
+ */
+export function routeForTopic(topic: string): string | null {
+  const t = str(topic).trim();
+  if (t === "customer") return "customer_data";
+  if (t === "product") return "product_data";
+  if (/^ut_[A-Za-z0-9_]+$/.test(t)) return t;
+  return null;
+}
+
+
+
+
+
+
+/**
+ * The stamp, made readable WITHOUT touching a clock.
+ *
+ * ⛔ NO `new Date()`, NO `toLocaleString()`, and that is the whole design. The
+ * server sends UTC WITH ITS OFFSET (D-18) precisely so every reader sees the
+ * same instant; parsing it into a browser Date and formatting it back would
+ * re-introduce the drift the offset exists to remove — a tenant a day ahead
+ * being told an event happened tomorrow ([[date-window-vocabulary]]). This is
+ * STRING SURGERY: keep the date and the minutes, drop the seconds and the `T`.
+ * Anything that does not look like an ISO stamp passes through untouched, so a
+ * format this function has never seen is shown as sent rather than mangled.
+ */
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+                "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+export function stampText(at: string, now?: string): string {
+  const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(str(at));
+  if (!m) return str(at);
+  const [, day, hhmm] = m;
+  // ⭐⭐ W33-T28 / D-208 — MAIL-SHAPED, AND STILL STRING SURGERY.
+  //
+  // ⛔ `now` COMES FROM THE SERVER (`inbox.now`), NEVER FROM `new Date()`. That is D-208's exit
+  // condition word for word — "without reading the browser clock" — and the reason is the same
+  // one this function has always carried: `at` is sent as UTC WITH its offset (D-18) so every
+  // reader sees the same instant, and deciding "is this today?" against a browser clock would
+  // re-introduce exactly the drift the offset removes. Both operands are the server's.
+  //
+  // ⚠ AND WITHOUT `now` IT DEGRADES TO THE OLD FORMAT RATHER THAN GUESSING. A caller that has no
+  // server clock gets `2026-08-13 09:41` — the pre-wave string, unambiguous and never wrong —
+  // instead of a relative stamp computed from something we do not trust.
+  const today = /^(\d{4}-\d{2}-\d{2})/.exec(str(now));
+  if (!today) return `${day} ${hhmm}`;
+  if (today[1] === day) return hhmm;
+  const [y, mo, d] = day.split("-");
+  const month = MONTHS[Number(mo) - 1] || mo;
+  // The year only when it differs — a mail client does not print "2026" on a message from March.
+  return today[1].slice(0, 4) === y
+    ? `${month} ${Number(d)}`
+    : `${month} ${Number(d)}, ${y}`;
+}
+
+/**
+ * The badge's text. Never the raw number past 99: a nav row is 236px wide and a
+ * four-digit badge pushes the label out of it.
+ */
+export function badgeText(unread: number): string {
+  const n = Math.max(0, Math.floor(unread));
+  if (n <= 0) return "";
+  return n > 99 ? "99+" : String(n);
+}
+
+/**
+ * Apply a read/unread change LOCALLY, mirroring what the server just stored, and
+ * return the new inbox with the count corrected.
+ *
+ * `ids === null` is "all of them" (the API's own convention for mark-all). The
+ * count is derived from the ITEMS here — deliberately, and it is the one place
+ * that is right to do so: the server's answer is in flight, and the alternative
+ * is a badge that keeps its old number until the refetch lands.
+ */
+export function applyRead(inbox: Inbox, ids: string[] | null, read: boolean): Inbox {
+  const wanted = ids === null ? null : new Set(ids);
+  const items = inbox.items.map((n) =>
+    wanted === null || wanted.has(n.id) ? { ...n, read } : n
+  );
+  const seenUnread = items.filter((n) => !n.read).length;
+  // A page can hold fewer notifications than the account has, so a partial read
+  // must SUBTRACT from the server's count rather than replace it with this
+  // page's tally — except when marking everything, where zero is the answer.
+  if (wanted === null) return { unread: read ? 0 : items.length, items };
+  const changed = inbox.items.filter(
+    (n) => wanted.has(n.id) && n.read !== read
+  ).length;
+  const delta = read ? -changed : changed;
+  return { unread: Math.max(seenUnread, inbox.unread + delta), items };
+}
+
+/**
+ * The shell↔rail channel for "make an alert out of this view" — the view rail
+ * raises it, the frame (which knows the current route, and therefore the topic)
+ * answers. Same reason as C-SHARE's event: the rail is host-neutral and cannot
+ * import the shell, and it does not know its own scope key.
+ */
+export const ALERT_CREATE_EVENT = "aios:alert-create";
+
+export interface AlertCreateRequest {
+  viewId: string;
+  label: string;
+}
+
+export function parseAlertCreate(detail: unknown): AlertCreateRequest | null {
+  if (!detail || typeof detail !== "object") return null;
+  const d = detail as Record<string, unknown>;
+  const viewId = str(d.viewId).trim();
+  if (!viewId) return null;
+  return { viewId, label: str(d.label).trim() || viewId };
+}

web/src/assistant/AssistantPage.tsx

@@ -105,7 +105,17 @@ const KIND_LABEL: Record<string, string> = {
  * `modelStatus`: a model that IS offered and whose key this deployment does not hold.
  */
 const MODEL_LABEL: Record<string, string> = {
-  auto: "Auto", cerebras: "Cerebras", groq: "Groq", openrouter: "OpenRouter",
+  // ⭐ `anthropic` JOINS THE MAP (W36 · ASK E-11, ruling R4). Not a fifth option nobody wanted.
+  // E measured all three side rungs refusing live today (cerebras 402, groq 404, openrouter 402),
+  // so Anthropic is the only rung that answers at all, and C5 makes it the tool-calling path by
+  // ruling rather than by accident. The fall-through below still covers a provider added
+  // server-side; this row exists so the ONE rung that works is not the one rendered as a raw key.
+  // ⚠ NO `word` FOLLOWED BY A COLON IN THIS COMMENT, and that is not fussiness. `verify_query`
+  // reads this map with a regex over the block, comments included, so a phrase like "asked for"
+  // with a colon after it registered as a SIXTH key named `for` and reddened the check that
+  // exists to keep this map equal to the server's list [[prose-that-becomes-its-own-marker]].
+  auto: "Auto", anthropic: "Anthropic", cerebras: "Cerebras", groq: "Groq",
+  openrouter: "OpenRouter",
 };
 const modelLabel = (key: string) => MODEL_LABEL[key] ?? key;
 

web/src/automation/AutomationBuilder.tsx

@@ -46,13 +46,19 @@ import type {
   FlowVocab,
   GraphNode,
   OAuthStatus,
+  StatementWorld,
   TriggerOption,
   UserTable,
 } from "./automationApi";
 // ⭐ WAVE 26 · ITEM 22 / D-70 — the Run guard, imported rather than re-derived. This file and
 // `AutomationDetail` each paint a Run button onto the same paid action; ONE function decides.
 // ITEM 9 / R11 — `createTable` + `AutomationError` for the in-place "+ New database".
-import { AutomationError, createTable, runBlock } from "./automationApi";
+// ⭐ W36-T44 — the statements panel's three doors. They go to `routes_statements`, not
+// `/automations`, for the reason `statementBatch`'s own note gives: that is where the send
+// guardrails already are and R10's whole point is that they do not move.
+import {
+  AutomationError, createTable, previewStatement, runBlock, statementWorld, testSendStatement,
+} from "./automationApi";
 import CondBuilder, { condComplete } from "./CondBuilder";
 import { groupActions, groupBranches, groupByPanel, numberActions, reorderList }
   from "./steps";
@@ -141,7 +147,27 @@ interface Props {
    * ⚠ REQUIRED. An optional flag defaulting to `true` would make an unmounted toggle look like
    * a working panel, which is the shape this repo keeps paying for.
    */
+  /**
+   * ⭐ W36-T69 / R9 — `agentActions` off the wire, keyed by action id. Optional, and absent reads
+   * as "nothing is agent-owned" (the wire type carries the reasoning).
+   */
+  agentMarks?: Record<string, { agent: string; agentName?: string; created?: string; by?: string }>;
   showProperties: boolean;
+  /**
+   * ⭐⭐ W36-T32 (owner item 3) — HIDE THE FLOW, KEEP THE PANEL. `true` while the Chat view holds
+   * the work area.
+   *
+   * ⛔ WHY THE BUILDER STAYS MOUNTED AT ALL, WHICH REVISES A WAVE-34 TRADE RATHER THAN IGNORING
+   * IT. `AutomationDetail`'s own note recorded that keeping this component mounted behind
+   * `hidden` would "preserve the selection too, at the price of two live editors of one
+   * automation", and chose to unmount. The owner has since asked for the opposite in as many
+   * words: *"even when the Chat is shown first, we still need to be able to see the
+   * Properties/the new module/Run history tab on the right side."* The Properties panel is a
+   * child of THIS component, so an unmounted builder means no Properties tab during Chat.
+   * ⚠ The wave-34 concern is answered rather than overruled: what it feared was two live EDITORS
+   * of the flow, and the flow is exactly what this prop hides. The panel is the only live half.
+   */
+  flowHidden?: boolean;
   /** The Properties/Run-history switch, OWNED by `AutomationDetail` and drawn in both panel
    *  heads so it is in the same place whichever one is showing. */
   panelTabs: ReactNode;
@@ -420,7 +446,9 @@ export default function AutomationBuilder({
   onRunNow,
   renderNodeBody,
   scheduleFace,
+  agentMarks,
   showProperties,
+  flowHidden,
   panelTabs,
   onStepPicked,
   schedules,
@@ -1091,6 +1119,30 @@ export default function AutomationBuilder({
                     vocabulary — it would have gone on saying the old words after the catalog
                     changed, which is the one failure this file's header names twice. */}
                 {row?.label || a.kind}
+                {/*
+                  ⭐⭐ W36-T69 / R9 — THE LOCK, ON THE CARD, so the rule is visible BEFORE the panel
+                  is opened. The done-when asks for a lock that NAMES its agent; the glyph carries
+                  the name in its `title` and its `aria-label` rather than as a third line of card
+                  text, because every card in this column has exactly two lines and a third on one
+                  of them is the ragged edge the owner reads as unfinished.
+                  ⚠ `aria-hidden` on the SVG and the name on the wrapper: a screen reader should
+                  hear "set up by Odoo sync", never "image".
+                */}
+                {agentMarks?.[a.id] ? (
+                  <span
+                    className="autox-card-lock"
+                    title={`Set up by ${agentMarks[a.id].agentName || agentMarks[a.id].agent}. Its `
+                      + "configuration is edited by that agent."}
+                    aria-label={`Set up by ${agentMarks[a.id].agentName || agentMarks[a.id].agent}`}
+                  >
+                    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true"
+                      stroke="currentColor" strokeWidth="1.4" strokeLinecap="round"
+                      strokeLinejoin="round">
+                      <rect x="3.4" y="7" width="9.2" height="6.4" rx="1.4" />
+                      <path d="M5.6 7V5.2a2.4 2.4 0 0 1 4.8 0V7" />
+                    </svg>
+                  </span>
+                ) : null}
               </span>
               {isGroup ? (
                 <span className="autox-card-sub">
@@ -1224,7 +1276,10 @@ export default function AutomationBuilder({
 
   return (
     <>
-      <div className="autox-flow">
+      {/* ⚠ `hidden`, not unmounted (W36-T32). `.autox-flow` sets no `display`, so the UA's own
+          `[hidden] { display: none }` applies and no `!important` override is needed here — unlike
+          `.auto-panel[hidden]`, whose class rule sets `display: flex` and had to be beaten. */}
+      <div className="autox-flow" hidden={flowHidden}>
         {/* ── TRIGGER ─────────────────────────────────────────────────────────────────── */}
         <div className="autox-step">
           <div className="autox-side">
@@ -1504,6 +1559,11 @@ export default function AutomationBuilder({
         ) : (
           <ActionProps
             action={findAction(actions, sel.id)}
+            /* ⛔ THE MARK FOR THIS ACTION, LOOKED UP ONCE HERE. The panel takes a mark rather than
+               the whole map so it cannot accidentally read another step's ownership, which is the
+               kind of off-by-one that renders a lock on the wrong card and is invisible to a
+               source grep. */
+            agentMark={agentMarks?.[sel.id] || null}
             /* ⭐ THE SAME RULE `actionCard` DERIVES AND THE SERVER ENFORCES (`ig_action_pinned`),
                passed down rather than re-derived a third time. The panel needs it because the
                pinned step is the one action in the product whose value map the ENGINE NEVER
@@ -1938,7 +1998,8 @@ function TriggerProps({
             <p className="auto-note">This server did not offer a view list for that database.</p>
           ) : !table.views.length ? (
             <p className="auto-note">
-              That database has no saved views yet — make one on its grid and it appears here.
+              That database has no saved views yet. Make one on its grid and it
+              appears here.
             </p>
           ) : (
             <select
@@ -2379,8 +2440,8 @@ export function WebActionConfig({
               <div className="auto-field" key="field">
                 <label>{mark("field")} Column to write into</label>
                 <p className="auto-note">
-                  This flow has no record to write to — give it a database on the trigger
-                  first.
+                  This flow has no record to write to. Give it a database on the
+                  trigger first.
                 </p>
               </div>
             );
@@ -2462,6 +2523,379 @@ export function WebActionConfig({
   );
 }
 
+/**
+ * ⭐⭐ WAVE 36 · W36-T44 (D-316 + D-299) — THE STATEMENTS STEP'S CONFIGURATION, WHICH DID NOT EXIST.
+ *
+ * ⛔ THE DEFECT WAS NOT A WRONG CONTROL. IT WAS NO CONTROL, ON THE PUBLIC DOMAIN. The server half
+ * has been complete since wave 35: `automation_engine` seeds `{tier, subject, intro, footer}`,
+ * `_clean_action_config` validates all four, and `assemble_statements` reads all four. This file's
+ * `kind ===` chain had no arm for the kind, so a Royal admin opening *Monthly statements* met a
+ * heading, a hint and NOT ONE INPUT. QA measured it exactly: a page-wide `input, textarea` count
+ * of **1**, the agent's own Name field. And the run's parked-batch banner said *"or narrow the
+ * tier filter"*, naming a control that existed nowhere.
+ * ⚠ THIS IS `ai_enrich` (D-277) A SECOND TIME. A step kind is a CONTRACT BETWEEN TWO TREES and
+ * each end's gate was green because each end was internally consistent
+ * [[artifact-with-no-importer]]. W36-T39 is the gate that makes the class unrepeatable; this is
+ * the instance [[reachable-is-not-the-same-as-built]].
+ *
+ * ⛔ THE FIX IS THE RENDERER, NEVER A SEED. Blank tier means EVERY tier and blank template means
+ * the sender's own default, and both are deliberate: the seed's own comment says the blank "is the
+ * value the config panel shows as all of them rather than an empty box". Writing non-empty values
+ * in would hide the missing panel and freeze today's wording into every stored agent.
+ *
+ * ⛔ A COMPONENT AND NOT AN ARM, for a reason the file enforces structurally: `ActionProps` opens
+ * with `if (!action) return`, an early return BEFORE any hook, so nothing inside it may hold
+ * state. This panel has to load the sender's own vocabulary, so it needs its own frame. That is
+ * `WebActionConfig`'s shape too, and exported for `WebActionConfig`'s reason: a panel's defects
+ * (a control bound to no key, a stored value that never reaches its box) are invisible to a grep.
+ */
+export function StatementActionConfig({
+  cfg,
+  busy,
+  setCfg,
+}: {
+  cfg: Record<string, unknown>;
+  busy: boolean;
+  setCfg: (patch: Record<string, unknown>) => void;
+}) {
+  /**
+   * ⚠ THE WORKLIST IS A THIRD STATE AND IS KEPT AS ONE. `null` is "not answered yet", an error
+   * string is "asked and refused", and a value is a value. Collapsing the first two would paint
+   * "this tenant has no tiers" over a request still in flight [[empty-answer-vs-unfinished-answer]].
+   */
+  const [world, setWorld] = useState<StatementWorld | null>(null);
+  const [worldErr, setWorldErr] = useState("");
+  const [customer, setCustomer] = useState("");
+  const [shot, setShot] = useState<{ html: string; to: string; subject: string } | null>(null);
+  const [testTo, setTestTo] = useState("");
+  const [outcome, setOutcome] = useState("");
+  const [working, setWorking] = useState<"" | "preview" | "test">("");
+
+  /*
+    ⛔ ONE READ, ON MOUNT, ABORTED ON UNMOUNT. `GET /admin/statements` reaches Odoo through
+    `load_collection_list` (cached ~30 min server side), so it is the one slow thing on this panel
+    and everything above it paints without waiting. Selecting a different step unmounts this, and
+    an in-flight answer landing in a dead component is how a panel paints the previous step's
+    customers over the current one's.
+    ⚠ The header of this file forbids a fetch in the BUILDER's own render (C14 leg 1, the ghost
+    fix). That rule is about the trigger/actions/graph painting synchronously from the list
+    payload, and they still do. This is a leaf panel for one selected step, the same shape
+    `NewDatabase`'s create call already has.
+  */
+  useEffect(() => {
+    const ac = new AbortController();
+    statementWorld(ac.signal)
+      .then((w) => {
+        if (!ac.signal.aborted) setWorld(w);
+      })
+      .catch((e: unknown) => {
+        if (ac.signal.aborted) return;
+        setWorldErr(e instanceof Error ? e.message : "the collection list could not be read");
+      });
+    return () => ac.abort();
+  }, []);
+
+  const text = (v: unknown) => (v === undefined || v === null ? "" : String(v));
+  const tier = text(cfg.tier);
+  const templates = {
+    subject: text(cfg.subject),
+    intro: text(cfg.intro),
+    footer: text(cfg.footer),
+  };
+  const tiers = world?.tiers || [];
+  const rows = world?.rows || [];
+
+  /* Free text commits on BLUR, which is this file's idiom and its stated reason: `setCfg` merges
+     into the action and re-renders the whole builder, so a controlled box would round-trip the
+     tree on every keystroke of a footer. */
+  const template = (
+    key: "subject" | "intro" | "footer",
+    label: string,
+    rowsCount: number,
+    hint: string
+  ) => (
+    <div className="auto-field" key={key}>
+      <label htmlFor={`autox-stmt-${key}`}>{label}</label>
+      {rowsCount > 1 ? (
+        <textarea
+          id={`autox-stmt-${key}`}
+          className="auto-input"
+          rows={rowsCount}
+          defaultValue={templates[key]}
+          /* ⚠ THE DEFAULT IS THE PLACEHOLDER, NOT THE VALUE. Blank means "use the sender's own",
+             and the send door resolves it at send time, so painting it as a placeholder shows what
+             blank actually does without storing a copy that stops tracking the sender. With no
+             worklist yet there is nothing honest to show, so it shows nothing. */
+          placeholder={world?.templates?.[key] || ""}
+          disabled={busy}
+          onBlur={(e) => setCfg({ [key]: e.target.value })}
+        />
+      ) : (
+        <input
+          id={`autox-stmt-${key}`}
+          className="auto-input"
+          defaultValue={templates[key]}
+          placeholder={world?.templates?.[key] || ""}
+          disabled={busy}
+          onBlur={(e) => setCfg({ [key]: e.target.value })}
+        />
+      )}
+      <p className="auto-hint">{hint}</p>
+    </div>
+  );
+
+  const canPreview = !!customer && !busy && working === "";
+  const canTest = canPreview && !!testTo.trim();
+
+  return (
+    <>
+      <div className="auto-field">
+        <label htmlFor="autox-stmt-tier">Customers to include</label>
+        <select
+          id="autox-stmt-tier"
+          className="auto-input"
+          value={tier}
+          disabled={busy}
+          onChange={(e) => setCfg({ tier: e.target.value })}
+        >
+          {/*
+            ⛔⛔ THE BLANK OPTION IS THE STORED DEFAULT AND IT MUST EXIST. `tier: ""` is what the
+            seed writes and it means EVERY tier. A `<select>` whose `value` matches no `<option>`
+            renders the FIRST one, so without this row a freshly seeded agent would paint
+            "A-Urgent", and the next edit would write that over the blank: blank-means-all would
+            silently become a tier filter, and a batch of 200 would quietly become a batch of 40.
+            Same guard the `find_records` database picker carries, and D-10 is why it carries it.
+          */}
+          <option value="">Every tier</option>
+          {/*
+            ⚠ AND THE STORED VALUE IS ALWAYS AN OPTION, with its wording decided by WHICH THIRD
+            STATE we are in. Before the worklist answers, an unmatched stored tier is simply
+            painted: calling it unknown while the list is still empty would be a lie about a
+            request in flight. After it answers, an unmatched value is genuinely not a tier the
+            sender knows, and saying so is the honest reading.
+          */}
+          {tier && !tiers.includes(tier) ? (
+            <option value={tier}>{world ? `${tier} (not a tier the sender offers)` : tier}</option>
+          ) : null}
+          {tiers.map((t) => (
+            <option key={t} value={t}>
+              {t}
+            </option>
+          ))}
+        </select>
+        <p className="auto-hint">
+          {world
+            ? "Leave this on Every tier to statement the whole collection list. One batch holds "
+              + "200 customers."
+            : worldErr
+              ? "The collection list could not be read, so the tier names are not available yet. "
+                + "What is already saved here is kept."
+              : "Reading the collection list to get the tier names."}
+        </p>
+        {worldErr ? <p className="auto-note">{worldErr}</p> : null}
+      </div>
+
+      {template("subject", "Subject", 1,
+        "Leave blank to use the sender's own subject, shown greyed above. {customer}, {company} "
+        + "and {month} are filled in for each customer.")}
+      {template("intro", "Opening", 4,
+        "The paragraph above the invoice table. Blank uses the sender's own. HTML is allowed, and "
+        + "the same three placeholders work here.")}
+      {template("footer", "Closing", 4,
+        "The paragraph below the total. Blank uses the sender's own.")}
+
+      {/*
+        ⭐⭐ D-299 SHIPS IN THIS SAME PANEL, AND THAT IS THE POINT OF PUTTING IT HERE.
+        `W35-T38` deleted `settings/StatementsPane.tsx` and left `routes_statements.preview` and
+        the `overrideTo` branch of `.send` working, gated, and reachable from nowhere. A template
+        editor with no preview and no test send is how somebody mails 200 real debtors to find out
+        what the template looks like, so the editor above and these two controls are ONE piece of
+        work rather than two tickets [[artifact-with-no-importer]].
+      */}
+      <h3>Check it before it goes</h3>
+      <div className="auto-field">
+        <label htmlFor="autox-stmt-customer">Try it on this customer</label>
+        <select
+          id="autox-stmt-customer"
+          className="auto-input"
+          value={customer}
+          disabled={busy || !world}
+          onChange={(e) => {
+            setCustomer(e.target.value);
+            setShot(null);
+            setOutcome("");
+          }}
+        >
+          <option value="">
+            {world
+              ? "Select a customer…"
+              : worldErr
+                ? "The collection list could not be read"
+                : "Reading the collection list…"}
+          </option>
+          {rows.map((r) => (
+            <option key={r.Customer} value={r.Customer}>
+              {r.Customer}
+              {r.Tier ? ` (${r.Tier})` : ""}
+              {r.Email ? "" : ", no email on record"}
+            </option>
+          ))}
+        </select>
+        <p className="auto-hint">
+          Whoever you pick here is only used for the preview and the test send below. It does not
+          narrow what the agent sends.
+        </p>
+      </div>
+
+      <div className="autox-stmt-row">
+        <button
+          type="button"
+          className="auto-btn"
+          disabled={!canPreview}
+          onClick={async () => {
+            setWorking("preview");
+            setOutcome("");
+            try {
+              setShot(await previewStatement(customer, templates));
+            } catch (e: unknown) {
+              setShot(null);
+              setOutcome(e instanceof Error ? e.message : "the preview could not be rendered");
+            } finally {
+              setWorking("");
+            }
+          }}
+        >
+          {working === "preview" ? "Rendering…" : "Preview"}
+        </button>
+      </div>
+
+      {shot ? (
+        <div className="autox-stmt-shot">
+          <p className="auto-hint">
+            To {shot.to || "no address on this customer's record"}. Subject: {shot.subject}
+          </p>
+          {/*
+            ⛔ SANDBOXED, AND `sandbox=""` IS THE WHOLE POINT. This body is rendered by the SAME
+            `render_statement_html` the send door uses, so what a person approves is what goes out.
+            But it interpolates customer names and document numbers straight out of Odoo, and an
+            empty sandbox attribute is the most restrictive value there is: no scripts, no forms,
+            no same-origin. Painting it with `dangerouslySetInnerHTML` instead would run whatever a
+            partner name happens to contain, inside our own origin.
+          */}
+          <iframe
+            className="autox-stmt-frame"
+            title="Statement preview"
+            sandbox=""
+            srcDoc={shot.html}
+          />
+        </div>
+      ) : null}
+
+      <div className="auto-field">
+        <label htmlFor="autox-stmt-testto">Send one test to this address</label>
+        <input
+          id="autox-stmt-testto"
+          className="auto-input"
+          value={testTo}
+          disabled={busy || !world}
+          onChange={(e) => setTestTo(e.target.value)}
+        />
+        <p className="auto-hint">
+          {world?.safeMode
+            ? "Safe mode is on, so mail can only reach "
+              + (world.safeRecipients.length
+                ? world.safeRecipients.join(", ")
+                : "an allow-list nobody is on yet")
+              + ". Anything else is refused."
+            : "One statement, to this address only. The customer above is never mailed by this "
+              + "button."}
+        </p>
+      </div>
+
+      <div className="autox-stmt-row">
+        <button
+          type="button"
+          className="auto-btn"
+          disabled={!canTest}
+          onClick={async () => {
+            setWorking("test");
+            setOutcome("");
+            try {
+              const r = await testSendStatement(customer, testTo, templates);
+              /* ⛔ THE OUTCOME IS READ OFF THE RESPONSE, never assumed from a 200. The send door
+                 answers `{sent, failed, skipped}` per customer precisely so that "we could not"
+                 and "there was nowhere to send" stay distinct, and SAFE_MODE's refusal arrives as
+                 a `failed` row with its own sentence rather than as an HTTP error. A caller that
+                 printed "sent" on a 200 would report a delivery the guardrail blocked. */
+              const failed = r.failed?.[0];
+              const skipped = r.skipped?.[0];
+              setOutcome(
+                failed
+                  ? `Not sent. ${failed.error}`
+                  : skipped
+                    ? `Not sent. ${skipped.reason}`
+                    : r.sent?.length
+                      ? `Sent one test to ${r.sent[0].to}.`
+                      : "The send door reported nothing sent and gave no reason."
+              );
+            } catch (e: unknown) {
+              setOutcome(e instanceof Error ? e.message : "the test send was refused");
+            } finally {
+              setWorking("");
+            }
+          }}
+        >
+          {working === "test" ? "Sending…" : "Send one test"}
+        </button>
+      </div>
+      {outcome ? <p className="auto-note">{outcome}</p> : null}
+    </>
+  );
+}
+
+/**
+ * ⭐⭐ WAVE 36 · W36-T69 (owner item 8, ruling R9) + E-13 — A CONFIG THAT CAN BE READ AND NOT TYPED.
+ *
+ * ⛔ ONE MECHANISM, THREE CALLERS, and that is the point rather than a tidiness. Three different
+ * steps need the same thing — a configuration a person may READ but not EDIT:
+ *   · an agent-authored Action (R9: *"its configuration can only be touched by the agent"*),
+ *   · `ai_enrich`, whose settings belong to a COLUMN (D-277's exit condition: "a NAMED first step
+ *     with the Field and the Database under Config"),
+ *   · `odoo_sync`, configured on the connector rather than here.
+ * A second read-only renderer per case is how three surfaces come to disagree about what
+ * "read-only" looks like, and E booked the last two as PENDING precisely because they had no
+ * mechanism yet. They have one now.
+ *
+ * ⛔ AND IT IS A DEFINITION LIST, NOT DISABLED INPUTS. A greyed-out `<input>` still reads as a
+ * control somebody could enable, invites a click that does nothing, and is announced as a form
+ * field to a screen reader. What this renders is what it is: the values, as text, labelled.
+ */
+function ReadOnlyConfig({ rows, note }: {
+  rows: { label: string; value: string }[];
+  note: string;
+}) {
+  const shown = rows.filter((r) => r.value);
+  return (
+    <>
+      {shown.length ? (
+        <dl className="autox-ro">
+          {shown.map((r) => (
+            <div key={r.label}>
+              <dt>{r.label}</dt>
+              <dd>{r.value}</dd>
+            </div>
+          ))}
+        </dl>
+      ) : (
+        /* ⚠ NEVER AN EMPTY PANEL. A step whose config has not been filled in yet still has to say
+           what it IS, or the reader meets the captioned-step-over-nothing that D-277 reported. */
+        <p className="auto-note">This step has nothing configured yet.</p>
+      )}
+      <p className="auto-hint">{note}</p>
+    </>
+  );
+}
+
 /**
  * ⭐ WAVE 28 — EXPORTED so the include-row render suite can mount the real panel.
  *
@@ -2474,6 +2908,7 @@ export function WebActionConfig({
 export function ActionProps({
   action,
   pinned,
+  agentMark,
   catalog,
   tables,
   onTablesChanged,
@@ -2501,6 +2936,13 @@ export function ActionProps({
    * refuses in five other places.
    */
   pinned: boolean;
+  /**
+   * ⭐ W36-T69 / R9 — the `agentActions` entry for THIS action, or `null`.
+   * ⚠ OPTIONAL, and absent reads as "not agent-owned" (see the wire type's own note): an older
+   * server sends no map, and a client that defaulted the other way would lock every step in the
+   * product behind a rule nobody had applied.
+   */
+  agentMark?: { agent: string; agentName?: string; created?: string; by?: string } | null;
   catalog: ActionCatalogRow[];
   tables: UserTable[];
   /** ITEM 9 / R11 — re-read the list after this panel's picker creates one. REQUIRED; see Props. */
@@ -2556,6 +2998,17 @@ export function ActionProps({
    * picker that reads as "this database has no views".
    */
   const walkViews = (tables.find((t) => t.key === walkTable) || null)?.views;
+  /**
+   * ⭐⭐ W36-T69 — IS THIS STEP'S CONFIGURATION READ-ONLY? ONE PREDICATE, CONSULTED BY EVERY EDITOR.
+   *
+   * ⛔ THE FIRST DRAFT GUARDED ONLY THE `group`/`create_record`/`find_records` TERNARY CHAIN, and
+   * the render suite caught it in one line: `isWeb(...)`, `ai_agent` and the condition editor are
+   * SEPARATE JSX expressions, so an agent-owned `web_read` still painted seven inputs under a
+   * notice saying it could not be edited. A rule spelled once per arm is a rule with a list to
+   * maintain, and the arm added next wave will not be on it.
+   */
+  const readOnly = !!agentMark
+    || action.kind === "ai_enrich" || action.kind === "odoo_sync";
 
   return (
     <>
@@ -2564,7 +3017,60 @@ export function ActionProps({
 
       <h3>Configuration</h3>
 
-      {action.kind === "group" ? (
+      {/*
+        ⛔⛔ W36-T69 — THE AGENT-OWNED BRANCH COMES FIRST AND RETURNS, so no per-kind editor below
+        can paint a control over a config the server will refuse. Putting it after them would leave
+        the wall depending on which arm happened to match, which is a wall with a list to maintain.
+        ⚠ R9 IS A WRITE RULE. The user reads everything and may still DELETE the step; only the
+        typing is gone. Today the server 409s a PATCH and no client knows, so a person configures,
+        saves, and meets a refusal they were never warned about.
+      */}
+      {agentMark ? (
+        <>
+          <p className="auto-note">
+            {agentMark.agentName || agentMark.agent} set this step up, so its configuration is
+            edited by that agent rather than by hand. You can still read it here, and you can
+            delete the step.
+          </p>
+          <ReadOnlyConfig
+            rows={Object.entries(cfg as Record<string, unknown>)
+              .filter(([, v]) => typeof v !== "object" || v === null)
+              .map(([k, v]) => ({ label: k, value: v === null ? "" : String(v) }))}
+            note="Ask the agent to change any of this."
+          />
+        </>
+      ) : action.kind === "ai_enrich" ? (
+        /* ⭐ D-277's exit condition, verbatim: "a NAMED first step with the Field and the Database
+           under Config". The NAME arrives from E's catalog row; these are the two lines under it.
+           An enrichment is configured on the COLUMN, which is why it is read-only here rather than
+           missing: `patch_automation` already refuses a `field:` id. */
+        <ReadOnlyConfig
+          rows={[
+            { label: "Column", value: String((cfg as { field?: string }).field || "") },
+            { label: "Database",
+              value: String((cfg as { tableLabel?: string; table?: string }).tableLabel
+                || (cfg as { table?: string }).table || "") },
+          ]}
+          /* ⚠ A TEMPLATE, NOT A WRAPPED ATTRIBUTE STRING. JSX collapses whitespace in TEXT
+             children but preserves it verbatim inside an attribute, so the wrapped literal that
+             was here rendered a newline and fourteen spaces into the middle of the sentence. It
+             looked right in the source and wrong on the screen, which is the only kind of typo
+             a type-checker cannot help with. */
+          note={"An enrichment belongs to its column. Change its prompt, model or schedule "
+            + "on the column itself."}
+        />
+      ) : action.kind === "odoo_sync" ? (
+        <ReadOnlyConfig
+          rows={[
+            { label: "Connector",
+              value: String((cfg as { connector?: string }).connector || "") },
+            { label: "Runs", value: String((cfg as { every?: string }).every || "") },
+          ]}
+          note="This schedule is configured on the connector, under Keychains."
+        />
+      ) : null}
+
+      {readOnly ? null : action.kind === "group" ? (
         <>
           {/*
             ⭐ ONE CONDITION EDITOR PER BRANCH (C-FORK). The group's own `config.cond` is GONE —
@@ -2606,8 +3112,8 @@ export function ActionProps({
             </div>
           ))}
           <p className="auto-hint">
-            The first branch whose conditions match is the one that runs — the record does not go
-            down two of them.
+            The first branch whose conditions match is the one that runs. The record
+            does not go down two of them.
           </p>
         </>
       ) : null}
@@ -2665,9 +3171,9 @@ export function ActionProps({
           the same lie the value map was. */}
       {pinned ? (
         <p className="auto-hint">
-          The search writes one row per profile it finds — handle, profile link, name, followers,
-          following, average engagement, bio, link in bio, verified and category — into that
-          database. It matches on the handle, so a profile found again updates its row instead of
+          The search writes one row per profile it finds, into that database: handle,
+          profile link, name, followers, following, average engagement, bio, link in
+          bio, verified and category. It matches on the handle, so a profile found again updates its row instead of
           adding another. There is nothing to map: the columns come from the search.
         </p>
       ) : null}
@@ -3254,7 +3760,7 @@ export function ActionProps({
           start, what to do in words, and where to put the answer. Deliberately NOT routed through
           `WebActionConfig`: that component walks `WEB_SEEDS`, and sharing it would mean adding
           `ai_agent` to a table the browser job's runner does not implement. */}
-      {action.kind === "ai_agent" ? (
+      {action.kind === "ai_agent" && !readOnly ? (
         <>
           <div className="auto-field">
             <label htmlFor="autox-ai-url">
@@ -3296,7 +3802,8 @@ export function ActionProps({
             <div className="auto-field">
               <label>Column to write the answer into</label>
               <p className="auto-note">
-                This flow has no record to write to — give it a database on the trigger first.
+                This flow has no record to write to. Give it a database on the trigger
+                first.
               </p>
             </div>
           ) : (
@@ -3359,7 +3866,7 @@ export function ActionProps({
         </>
       ) : null}
 
-      {isWeb(action.kind) ? (
+      {isWeb(action.kind) && !readOnly ? (
         <WebActionConfig
           kind={action.kind}
           cfg={cfg as Record<string, unknown>}
@@ -3371,6 +3878,13 @@ export function ActionProps({
         />
       ) : null}
 
+      {/* ⭐⭐ W36-T44 (D-316) — the arm whose absence was the whole defect. See
+          `StatementActionConfig`: the server has seeded, validated and consumed these four keys
+          since wave 35, and this line is what lets anybody type them. */}
+      {action.kind === "send_statement" && !readOnly ? (
+        <StatementActionConfig cfg={cfg as Record<string, unknown>} busy={busy} setCfg={setCfg} />
+      ) : null}
+
       {/*
         ⭐ WAVE 26 · ITEM 5 — OWNER RULINGS R9 AND R10, and they are two different fixes to one
         symptom (*"the condition on action act_1 names no field"*).
@@ -3396,11 +3910,38 @@ export function ActionProps({
         walking a database that genuinely has no columns yet keeps its (empty) picker, because
         for that flow the picker is the right control and adding a column is the fix.
       */}
-      {action.kind === "create_record" ? null : !walkTable ? (
+      {/*
+        ⭐⭐ W36-T44 — AND A `send_statement` HAS NO CONDITIONS EITHER, for R9's reason arriving at
+        a different kind. R9 removed the editor from `create_record` because that step MAKES the
+        record there is nothing to test yet. This step is not record-scoped at all: a statements
+        flow is BATCH-scoped, it binds no database (its customers come from the Odoo collection
+        list, not a `ut_*` grid), and `assemble_statements` reads the step's `config` and NOTHING
+        else. `is_statement_flow` requires exactly ONE enabled action, so there is no walk to
+        condition and no second step to condition it against.
+        ⛔ AND THE STORED KEY SURVIVES, WHICH IS WHY THE EDITOR MUST NOT. `clean_actions` drops
+        `when` for `create_record` alone; on this kind it is kept, stored, reloaded, and read by
+        nobody. That is a control whose value appears to be ignored, which is exactly the state R9
+        called out as indefensible and exactly what the `discover_instagram` values editor was
+        [[a-flag-can-ship-without-its-writer]]. The sentence points at the control that DOES narrow
+        the batch, which is the tier filter above, and which is the control the run's own
+        parked-batch banner has been naming all along.
+      */}
+      {/* ⛔ A CONDITION IS CONFIGURATION TOO. `clean_actions` keeps `when` on an agent-authored
+          step exactly as it keeps its config, so leaving this editor live would be a control the
+          server refuses on the same PATCH — the whole defect one field over. */}
+      {readOnly ? null : action.kind === "send_statement" ? (
+        <>
+          <h3>Run this only when</h3>
+          <p className="auto-note">
+            A statements step runs over the whole collection list at once, not once per record, so
+            there is no record here to test. Narrow it with Customers to include, above.
+          </p>
+        </>
+      ) : action.kind === "create_record" ? null : !walkTable ? (
         <>
           <h3>Run this only when</h3>
           <p className="auto-note">
-            This flow has no record to test — set conditions on the trigger instead.
+            This flow has no record to test. Set conditions on the trigger instead.
           </p>
         </>
       ) : (