Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,5 +1,5 @@
 {
- "current": "9445b77",
+ "current": "2de35b7",
  "releases": [
   {
    "version": "v29",

VERSION

@@ -1 +1 @@
-9445b77
+2de35b7

api/ai_enrich.py

@@ -314,6 +314,102 @@ def _ask(provider, model, prompt, max_tokens, timeout):
         return '', None, f"{provider['name']} failed: {type(exc).__name__}"
 
 
+# ===========================================================================
+# W37-T37 (R4 / C7) -- THE GEOCODE FIELD's pure half: turning a record into ONE query string.
+#
+# ⛔ WHY IT IS HERE AND NOT IN `routes_geo.py`. This module's contract, stated in its own header,
+# is that everything in it is a pure function of data it is handed -- which is what lets a gate
+# exercise it with no network, no store and no server. Composing an address is exactly that shape.
+# `routes_geo.py` owns the part that cannot be pure: the outbound call, the throttle and the cache.
+#
+# ⭐ WHY IT COMPOSES AT ALL, rather than sending the one column the field names. The field config
+# is `{addressField, country?}` -- a single column -- but a customers table stores an address across
+# six of them. B MEASURED the fill rates on the real 3,641-row mirror (W37-T11):
+#
+#     street 96.2% · city 96.0% · zip 94.6% · country 95.6% · state 92.0% · street2 5.2%
+#     street AND city together: 95.9%   <- the pair this feature actually needs
+#
+# Sending `street` alone would ask a global geocoder to place "123 Main Street" with no town, which
+# resolves confidently and often wrongly. So the named column LEADS and the conventional siblings
+# follow, which is also how a person would write the address down.
+# ===========================================================================
+
+#: The sibling columns appended after the named one, in the order an address is spoken. ⚠ A LIST
+#: rather than a formatted string: a template would have to decide what to do about the ~4% of rows
+#: missing any one part, and the answer is always "leave it out", never "leave a gap".
+GEOCODE_PARTS = ('street2', 'city', 'state', 'zip', 'postal_code', 'country')
+
+#: ⛔ B's SECOND MEASURED TRAP. Odoo serves `state` as its DISPLAY name, country code included:
+#: `New York (US)`, `British Columbia (CA)`. A naive join yields "SCARSDALE, New York (US)", and the
+#: parenthetical is noise to a geocoder at best. Stripped here, once, rather than at each caller.
+_PAREN_TAIL = re.compile(r'\s*\([^)]*\)\s*$')
+
+
+def geocode_query(row, cfg, seen_parts=None):
+    """One record plus a geocode field's config -> the query string, or '' when there is nothing.
+
+    ⛔ RETURNS '' RATHER THAN A PARTIAL GUESS when the named column is empty. B measured ~150 of
+    3,641 customers with no street at all, and the honest UI for those is "no address on file", not
+    a request that spends a second of a shared service's budget to place a bare postcode.
+
+    ⚠ `seen_parts=None` RESOLVES `GEOCODE_PARTS` AT CALL TIME, and that is not style. It was
+    `seen_parts=GEOCODE_PARTS`, which binds the tuple once at import, so the module constant stopped
+    being the live answer the moment anything wanted to vary it: the gate's own negative control set
+    `ai_enrich.GEOCODE_PARTS = ()` and the function carried on composing the full address. A default
+    argument that captures a module constant is a SECOND COPY of it with an earlier timestamp, and
+    the copy is the one that runs ([[a-constant-two-features-share]]). Caught by that control."""
+    if not isinstance(row, dict) or not isinstance(cfg, dict):
+        return ''
+    if seen_parts is None:
+        seen_parts = GEOCODE_PARTS
+    key = str(cfg.get('addressField') or '').strip()
+    if not key:
+        return ''
+    lead = _clean_part(row.get(key))
+    if not lead:
+        return ''
+    parts = [lead]
+    for k in seen_parts:
+        if k == key:
+            continue
+        v = _clean_part(row.get(k))
+        # ⚠ The dedupe is not tidiness. `country` is often both the field's own value and already
+        # present in the street line on an imported record, and "USA, USA" measurably degrades a
+        # free-form geocoder's confidence.
+        if v and v.lower() not in {p.lower() for p in parts}:
+            parts.append(v)
+    return ', '.join(parts)
+
+
+def _clean_part(v):
+    """One address component, trimmed and stripped of a trailing country parenthetical."""
+    if v is None:
+        return ''
+    s = re.sub(r'\s+', ' ', str(v)).strip()
+    if not s or s.lower() in ('false', 'none', 'null'):
+        return ''
+    return _PAREN_TAIL.sub('', s).strip()
+
+
+def geocode_plan(rows, cfg, coord_key=None, overwrite=False):
+    """Which records a run would actually ask about, and why the rest are being left out.
+
+    ⛔ THIS IS THE R3 GUARD IN ITS ARITHMETIC FORM. It is handed the records a PERSON chose; it
+    never reads a table. `skipped` is returned rather than swallowed so the surface can say "142 to
+    look up, 9 have no address, 31 already have coordinates" instead of a bare number."""
+    run, skipped = [], {}
+    for rid, row in (rows or {}).items():
+        q = geocode_query(row, cfg)
+        if not q:
+            skipped['no_address'] = skipped.get('no_address', 0) + 1
+            continue
+        if coord_key and not overwrite and str((row or {}).get(coord_key) or '').strip():
+            skipped['already_located'] = skipped.get('already_located', 0) + 1
+            continue
+        run.append((str(rid), q))
+    return {'run': run, 'skipped': skipped}
+
+
 def on_change_fields(defn, changed_keys):
     """Which `ai_enrich` columns in this table want a run because one of their inputs moved.
 

api/ai_review.py

@@ -17,15 +17,23 @@ the work. Nothing here can move a card somewhere the review does not already per
 last rather than absent — it is the quality backstop, not the default. `AIOS_AI_REVIEW_PROVIDER`
 pins one; `AIOS_AI_MODEL` overrides the model.
 
-⚠ WHY RAW HTTP RATHER THAN THE `anthropic` SDK, stated because it is a deliberate deviation from
-the /claude-api skill's default and not an oversight. Three of the four legs are OpenAI-chat-shaped
-endpoints with no shared SDK, so a ladder built on the SDK would be one SDK leg beside three
-hand-rolled ones — two implementations of the same call, the seam this repo keeps closing. And
-`aios-web/api/requirements.txt` is PINNED to what the verify battery proves ([[pin-deps-space-
-rebuilds]]): adding a dependency there rebuilds the container, which is a real deploy risk to take
-for one leg of an optional feature. `requests` is already a dependency and `harness/analyst.py`
-established per-provider raw HTTP as the house pattern. Booked as a DEBT line so the integrator
-can overturn it deliberately rather than by drift.
+⭐⭐ THE ANTHROPIC LEG IS ON THE OFFICIAL SDK NOW (D-346, W37-T39, 2026-08-19). ⛔ THIS PARAGRAPH
+USED TO ARGUE THE OPPOSITE and is rewritten rather than deleted, because a comment left asserting
+the reverse of its own code is [[two-gates-can-assert-opposite-things]] with no gate to catch it.
+The retired text said raw HTTP was *"a deliberate deviation … booked as a DEBT line so the
+integrator can overturn it deliberately rather than by drift"*. This is that overturn.
+
+Its two reasons were real and are both answered rather than waved away:
+  1. *"one SDK leg beside three hand-rolled ones is two implementations of the same call."* It is
+     not, because the leg does not live here: `providers.anthropic_send` owns the wire, prefers
+     the SDK, and normalises BOTH transports to one `(status, body)` pair. This file gained no
+     Anthropic knowledge — it lost some.
+  2. *"adding a pinned dependency rebuilds the container, a real deploy risk."* Still true, so the
+     import is LAZY and its absence is a FALLBACK, not a crash: with no `anthropic` package the
+     same raw POST runs and `LAST_ANTHROPIC_TRANSPORT` reports `'http'`. The pin is owed in BOTH
+     manifests ([[pin-deps-space-rebuilds]]) and is outside every worker fence this wave.
+⚠ The other three legs stay OpenAI-chat-shaped over `requests` — they have no shared SDK, and that
+half of the original reasoning never expired.
 
 The Messages shape below is the current one: `x-api-key` + `anthropic-version: 2023-06-01`, and
 `stop_reason: "refusal"` is checked BEFORE reading `content` — a refusal answers HTTP 200 with an
@@ -41,9 +49,13 @@ import requests
 
 #: The ladder. Order IS the policy (R14) — cheapest capable first, Anthropic last.
 PROVIDERS = [
+    # ⛔⛔ D-345, FIXED W37-T39 (2026-08-19). This read `llama-3.3-70b-versatile` and Groq RETIRED
+    # it: a real POST with the live key answers HTTP 404 `model_not_found`, and the id is absent
+    # from `GET /openai/v1/models`. ⚠ THE `openai/` PREFIX IS PART OF GROQ'S ID and is NOT a typo
+    # for the cerebras rung below, which serves the same family bare as `gpt-oss-120b`.
     {"name": "groq", "env": "GROQ_API_KEY", "shape": "openai",
      "url": "https://api.groq.com/openai/v1/chat/completions",
-     "model": "llama-3.3-70b-versatile"},
+     "model": "openai/gpt-oss-120b"},
     {"name": "cerebras", "env": "CEREBRAS_API_KEY", "shape": "openai",
      "url": "https://api.cerebras.ai/v1/chat/completions",
      "model": "gpt-oss-120b"},
@@ -161,16 +173,35 @@ def _call_openai(p, model, system, user, timeout):
     return str(((choices[0] or {}).get("message") or {}).get("content") or ""), "", body
 
 
+#: What transport the last Anthropic call actually used: `'sdk'`, `'http'`, or `''` before any.
+#: ⚠ PROCESS-LOCAL AND FOR REPORTING ONLY. It exists so `GET /meta` and `verify_web_agent` can say
+#: WHICH path ran rather than inferring it from a requirements file nobody in this lane can edit.
+LAST_ANTHROPIC_TRANSPORT = ""
+
+
 def _call_anthropic(p, model, system, user, timeout):
-    r = requests.post(p["url"], timeout=timeout,
-                      headers={"x-api-key": os.environ[p["env"]].strip(),
-                               "anthropic-version": ANTHROPIC_VERSION,
-                               "content-type": "application/json"},
-                      json={"model": model, "max_tokens": 300, "system": system,
-                            "messages": [{"role": "user", "content": user}]})
-    if r.status_code >= 400:
-        return "", f"anthropic answered {r.status_code}", None
-    body = r.json()
+    """One classification turn on the Messages API, through `providers.anthropic_send`.
+
+    ⭐ D-346 (W37-T39): this used to hand-roll the POST. It now goes through the shared wire, which
+    prefers the OFFICIAL `anthropic` SDK and falls back to the same raw POST when the package is
+    absent. The shape of what comes back is unchanged, deliberately: `anthropic_send` normalises
+    both transports to `(status, body)`, so every line below this call is untouched.
+    """
+    global LAST_ANTHROPIC_TRANSPORT
+    import providers as _prov                                           # noqa: PLC0415
+    # ⚠ NO TOOLS ON THIS PATH. The builder omits `tool_choice` for exactly that case, so there is
+    # nothing to strip here — the rule lives in `anthropic_request`, beside the thing it constrains.
+    req = _prov.anthropic_request(
+        model=model, key=os.environ[p["env"]].strip(), system=system,
+        messages=[{"role": "user", "content": user}], tools=[], max_tokens=300)
+    status, body, transport = _prov.anthropic_send(req, timeout=timeout)
+    LAST_ANTHROPIC_TRANSPORT = transport
+    if status >= 400 or status == 0:
+        # ⭐ THE SENTENCE COMES FROM THE LADDER, NOT FROM HERE. `refusal_sentence` already names the
+        # vendor and the action for every status R4 enumerated, so a bare "anthropic answered 402"
+        # (which is what this line used to say, and what the owner quoted back at us) cannot recur.
+        return "", _prov.refusal_sentence("anthropic", status, json.dumps(body)[:400]), None
+    body = body or {}
     # ⛔ stop_reason FIRST. A safety refusal is a successful 200 with an EMPTY content list, so
     # reading content[0] before this check turns a refusal into an IndexError inside a run.
     # ⚠ A refusal IS billed and its body carries `usage`, so the body rides back on this branch too.
@@ -444,6 +475,9 @@ def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeou
     `routes_automation`'s draft door) are in lane D's fence. C7 says E adds the ledger line here and
     D asserts it; the two keywords are what D has to pass for the line to be attributable.
     """
+    # ⚠ DECLARED AT THE TOP OF THE FUNCTION, not beside the assignment inside the provider loop.
+    # It parses either way; a reader scanning for the declaration does not look inside a `for`.
+    global LAST_ANTHROPIC_TRANSPORT
     import usage_ledger                                                 # noqa: PLC0415
     text = str(prompt or "").strip()[:MAX_PROMPT_CHARS]
     if not text:
@@ -487,13 +521,18 @@ def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeou
         # 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.
+        # ⭐ D-346 (W37-T39): BOTH shapes now yield the SAME `(status, body)` pair, so every branch
+        # below reads one thing. The anthropic side gets there through `anthropic_send` (official
+        # SDK when installed, the identical raw POST when not); the openai side still posts here
+        # because there is no shared SDK across three different vendors on that wire.
+        global LAST_ANTHROPIC_TRANSPORT
         try:
             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"])
+                status, body, transport = _prov.anthropic_send(req, timeout=tmo)
+                LAST_ANTHROPIC_TRANSPORT = transport
             else:
                 r = requests.post(p["url"], timeout=tmo,
                                   headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
@@ -501,19 +540,24 @@ def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeou
                                   json={"model": p["model"], "messages": messages, "tools": tools,
                                         "tool_choice": "required", "temperature": 0.1,
                                         "max_tokens": 1500})
+                status = r.status_code
+                body = r.json() if (r.content and r.status_code == 200) else {"_text": r.text}
         except Exception as e:                                    # noqa: BLE001
             problems.append(f"{p['name']}: {type(e).__name__}")
             continue
-        if r.status_code != 200:
+        if status != 200:
             # ⛔ 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):
+            # ⚠ The body is re-serialised for the substring test because the SDK path never had a
+            # `.text` — that is the one thing this normalisation costs, and it costs nothing else.
+            detail = json.dumps(body)[:600] if isinstance(body, dict) else str(body)[:600]
+            if _prov.is_credit_failure(status, detail):
                 _prov.mark_no_credit(p["name"])
-            problems.append(_prov.refusal_sentence(p["name"], r.status_code, r.text))
+            problems.append(_prov.refusal_sentence(p["name"], status, detail))
             continue
         try:
-            body = r.json()
+            body = body or {}
             if p["shape"] == "anthropic":
                 _text, args, _refused = _prov.anthropic_read(body)
                 if _refused:

api/main.py

@@ -87,6 +87,7 @@ import routes_usage  # noqa: E402  (wave 35 R9/C7 — the AI usage meter; E's ro
 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)
+import routes_geo  # noqa: E402  (wave 37 R14/A11 — the keyless map provider seam; D'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
@@ -395,6 +396,18 @@ app.include_router(routes_agent_harness.router)  # R8 / C4 — versioned agent h
 # 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
+# ⭐⭐ WAVE 37 (R14, amendment A11) — THE KEYLESS MAP PROVIDER SEAM, mounted on `ASK D-1` in the
+# same wave that created `routes_geo.py`. NINTH consecutive wave in which this block is the
+# artefact the protocol nearly loses, and the first in which the ask that carries it was itself
+# lost: D raised it inside a ``` fence, so `wave_board.py` blanked it and the bus never delivered
+# it (D-366). The integrator found it reading the peer mailbox by hand.
+# ⚠ Placement, as for every line above: ABOVE `app.mount("/", _AppStatic(...), html=True)` at the
+# end of this file, or GET answers 404 and POST answers 405 while every one of its own gates is
+# green. D is adding a `web_map` leg that reads THIS FILE and asserts this line — keep it.
+# ⛔ R14 put the provider behind a seam precisely so swapping Google in later is a config change:
+# tiles = OpenStreetMap · routing = OSRM · geocoding = Nominatim, none of them keyed, all of them
+# rate-limited by POLITENESS rather than by a bill (~1 req/s, and bulk harvesting is forbidden).
+app.include_router(routes_geo.router)            # R14 / A11 — D's router, A's line (map providers)
 
 
 # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)

api/odoo_relational.py

@@ -636,8 +636,25 @@ def customer_fields():
          "default": True, "pinned": True},
         {"key": JOIN_KEY, "label": "Odoo ID", "type": "int", "source": "overlay",
          "default": False, "description": "The `res.partner` id. Also this row's id."},
+        # ⭐⭐ W37-T11 / D-165 — THE POSTAL ADDRESS, which this table declared nowhere and served
+        # never. `verify_odoo_relational._prove_customer_address` recorded the blocker in its own
+        # docstring on 2026-08-12 — *"`street`/`street2`/`zip` are not among [the mirror's 16
+        # columns] … blocked on a `sync_all()` backfill no ticket in wave 30 owns"*. That backfill
+        # HAS since run (`_sync_state` carries `res_partner.cols.…,street,street2,…,zip`, done
+        # 2026-08-15), so the half that could not be built now can be.
+        # ⛔ THIS IS ALSO LANE D'S DEPENDENCY. R4 puts address→coordinates in an enrichment field,
+        # and a geocoder pointed at a column that does not exist enriches nothing.
+        # ⚠ `default: False` on the postal lines, `True` on city/state — the same split
+        # `vendor_fields` made and for the same reason: four address columns on by default push
+        # the useful ones off the first screen. A locked database still allows fields, so every
+        # one is a click away in the picker.
+        {"key": "street", "label": "Street", "type": "text", "source": "overlay",
+         "default": False},
+        {"key": "street2", "label": "Street 2", "type": "text", "source": "overlay",
+         "default": False},
         {"key": "city", "label": "City", "type": "text", "source": "overlay", "default": True},
         {"key": "state", "label": "State", "type": "text", "source": "overlay", "default": True},
+        {"key": "zip", "label": "ZIP", "type": "text", "source": "overlay", "default": False},
         {"key": "country", "label": "Country", "type": "text", "source": "overlay",
          "default": False},
         {"key": "agent", "label": "Sales agent", "type": "text", "source": "overlay",
@@ -976,8 +993,13 @@ def read_customers(cur, excluded=None):
     # the mirror carries. Absent ⇒ the leg is dropped WHOLE, exactly like the agent join above.
     rank_leg = ("   OR (p.customer_rank > 0 AND p.active) "
                 if {"customer_rank", "active"} <= have else "")
+    # ⭐⭐ W37-T11 / D-165 — the POSTAL columns join city/state/country here. They ride `_col` like
+    # every other optional column, so a mirror predating the 2026-08-15 backfill degrades the CELL
+    # to blank rather than failing the spawn with a Binder error (see `columns()`'s header for the
+    # live 500 that rule was written after).
     sql = (f"SELECT p.id, p.name, {_col(have, 'p.city')}, {_col(have, 'p.state_name')}, "
-           f"       {_col(have, 'p.country_name')}, {agent}, {agent_id_col} "
+           f"       {_col(have, 'p.country_name')}, {agent}, {agent_id_col}, "
+           f"       {_col(have, 'p.street')}, {_col(have, 'p.street2')}, {_col(have, 'p.zip')} "
            "FROM res_partner p "
            f"{join}"
            "WHERE p.id IN ("
@@ -988,13 +1010,16 @@ def read_customers(cur, excluded=None):
            f"{rank_leg}")
     out = []
     for r in cur.execute(sql).fetchall():
-        (pid, name, city, state, country, agent, agent_id) = r
+        (pid, name, city, state, country, agent, agent_id, street, street2, zipc) = r
         out.append({
             "_id": str(pid),
             "customer": str(name or ""),
             JOIN_KEY: int(pid),
+            "street": str(street or ""),
+            "street2": str(street2 or ""),
             "city": str(city or ""),
             "state": str(state or ""),
+            "zip": str(zipc or ""),
             "country": str(country or ""),
             "agent": str(agent or ""),
             AGENT_JOIN_KEY: int(agent_id) if agent_id else "",

api/providers.py

@@ -39,6 +39,12 @@ import time
 from dataclasses import dataclass, field
 from typing import Callable
 
+# ⚠ TOP-LEVEL AND SAFE, unlike the `anthropic` import in `anthropic_sdk()`: `requests` is pinned in
+# BOTH manifests and is already a transitive dependency of `huggingface_hub`, so it cannot be the
+# line that stops a container booting. That asymmetry is the whole reason the two are imported
+# differently — see `anthropic_sdk()`.
+import requests
+
 #: ⚠ APPROXIMATE, AND DELIBERATELY SO. These are list prices per RECORD in USD, used only to RANK
 #: providers and to estimate a run's spend for the operator. They are not billing truth — the
 #: vendor's own dashboard is. Wrong by 2x still ranks correctly; wrong by 100x does not, which is
@@ -352,6 +358,8 @@ LLM_PROVIDERS: dict[str, LlmProvider] = {
         # ⚠ 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.
+        # ⭐ W37-T39 re-verified this default against the vendor rather than the docs: a real
+        # Messages POST answers HTTP 200, and `claude-opus-5` is in `GET /v1/models`.
         model=os.environ.get("AIOS_ANTHROPIC_MODEL") or "claude-opus-5",
         wire="anthropic",
         caps={
@@ -367,24 +375,48 @@ LLM_PROVIDERS: dict[str, LlmProvider] = {
     "cerebras": LlmProvider(
         name="cerebras", label="Cerebras", env="CEREBRAS_API_KEY",
         url="https://api.cerebras.ai/v1/chat/completions",
+        # ⚠ STILL A LIVE ID, and W37-T39 checked rather than assumed: `gpt-oss-120b` is one of the
+        # two ids `GET https://api.cerebras.ai/v1/models` returns. What it is NOT is callable on
+        # this account — a real POST answers `HTTP 402 payment_required`, which `mark_no_credit`
+        # already knows how to survive (R4: skipped, not tried).
         model="gpt-oss-120b", wire="openai",
         caps={
+            # ⚠ STILL "DECLARED, NOT MEASURED", DELIBERATELY. The 2026-08-19 sweep could not
+            # measure this rung: a 402 comes back before any tool is considered, so there is no
+            # observation to record. Leaving the old wording is the honest answer — upgrading it
+            # to MEASURED beside its two neighbours would be claiming an account balance as
+            # evidence about a capability.
             "llm_tool_calling": Capability(True, 0.0,
                                            "DECLARED, not measured: this account's tool-capable "
-                                           "model per the wave-32 ladder note"),
+                                           "model per the wave-32 ladder note. ⚠ 2026-08-19: the "
+                                           "account answers 402, so this stays unmeasured"),
             "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",
+        # ⛔⛔ D-345, FIXED W37-T39 (2026-08-19): this read `llama-3.3-70b-versatile` and Groq
+        # RETIRED it. Measured, not inferred — a real POST with the live key answered
+        # `HTTP 404 {"code":"model_not_found"}`, and `GET /openai/v1/models` returns 13 ids with
+        # that one absent. ⚠ THE STATUS IS THE EVIDENCE AND 404 IS THE ONLY ONE THAT LICENSES A
+        # RENAME: cerebras answered 402 on the same sweep, which is a BILLING fact about the
+        # account and says nothing about its model id (`gpt-oss-120b` is in its /models list).
+        # "Fixing" an id behind a 401/402 is how a second bug ships behind a green probe.
+        # ⚠ THE PREFIX IS NOT A TYPO: Groq serves this model as `openai/gpt-oss-120b` while
+        # Cerebras serves the same family bare as `gpt-oss-120b`. The two rungs are DELIBERATELY
+        # spelled differently and a sweep that "normalises" them breaks one of them.
         url="https://api.groq.com/openai/v1/chat/completions",
-        model="llama-3.3-70b-versatile", wire="openai",
+        model="openai/gpt-oss-120b", wire="openai",
         caps={
+            # ⭐ MEASURED 2026-08-19, W37-T39, and this comment used to say the opposite. The old
+            # text read *"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"*. It is recorded now: on
+            # this id Groq answers HTTP 200 with a TYPED `tool_calls` block carrying parsed
+            # `arguments`, so it is not the provider `_FAILED_GEN` apologises for.
             "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"),
+                                           "MEASURED 2026-08-19: HTTP 200, typed tool_calls block "
+                                           "with parsed arguments; no failed_generation recovery"),
             "llm_chat": Capability(True, 0.0, "OpenAI-compatible"),
             "llm_json_mode": Capability(True, 0.0, "response_format json_object"),
         }),
@@ -393,7 +425,11 @@ LLM_PROVIDERS: dict[str, LlmProvider] = {
         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"),
+            # ⭐ MEASURED 2026-08-19, W37-T39 (was "DECLARED, not measured"): HTTP 200 with a typed
+            # `tool_calls` block. So on the OpenAI wire BOTH reachable rungs tool-call cleanly, and
+            # `_FAILED_GEN` is still holding a door nobody on this ladder has been seen to use.
+            "llm_tool_calling": Capability(True, 0.0,
+                                           "MEASURED 2026-08-19: HTTP 200, typed tool_calls block"),
             "llm_chat": Capability(True, 0.0, "OpenAI-compatible"),
             "llm_json_mode": Capability(True, 0.0, "response_format json_object"),
         }),
@@ -538,16 +574,25 @@ def anthropic_request(*, model, key, system, messages, tools, max_tokens,
     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()]
+    wire_tools = [{"name": t["function"]["name"],
+                   "description": t["function"]["description"],
+                   "input_schema": t["function"]["parameters"]} for t in (tools or [])]
     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"},
+        "tools": wire_tools,
     }
+    # ⛔ W37-T39: `tool_choice` IS OMITTED WHEN THERE ARE NO TOOLS, and the builder decides that
+    # rather than each caller. The Messages API refuses `tool_choice` beside an empty `tools` list,
+    # so this used to be a `req["json"].pop("tool_choice", None)` at the one call site that sends no
+    # tools — a rule living outside the thing it constrains, which is [[limit-with-no-enforcer]]:
+    # the next no-tools caller inherits a 400 that reads like a model problem, not a shape problem.
+    # ⚠ Safe for all three callers today, checked rather than assumed: `routes_query` and
+    # `ai_review.draft_flow` both pass a non-empty tool list and keep the key exactly as before.
+    if wire_tools:
+        body["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,
@@ -557,6 +602,88 @@ def anthropic_request(*, model, key, system, messages, tools, max_tokens,
             "json": body}
 
 
+#: Cached result of `import anthropic`: the module, or `False` once it is known to be absent.
+#: ⚠ `None` is NOT the "absent" sentinel — a plain falsy check would re-attempt the import on every
+#: call, and a failed import is not cheap. `False` says "asked and answered".
+_SDK: object = None
+
+
+def anthropic_sdk():
+    """The official `anthropic` SDK, or `None` if this deployment does not carry it.
+
+    ⭐⭐ D-346, W37-T39. THIS FUNCTION IS THE WHOLE OF THE FIX AND ALSO THE WHOLE OF ITS RISK.
+    `aios-web/requirements.txt` is what the Dockerfile installs and it is OUTSIDE every lane's
+    fence this wave, so the pin is another session's edit. A hard `import anthropic` at module
+    scope would therefore turn a missing line in a manifest into a container that cannot boot at
+    all: the API imports this module on every request path.
+
+    So the import is LAZY and its absence is REPORTED rather than fatal — `anthropic_send` falls
+    back to the raw `requests` POST that has always worked, and says which transport ran. When the
+    pin lands the SDK path takes over with no further change.
+    ⛔ The fallback is a BRIDGE, not a second implementation: both transports send the SAME body
+    `anthropic_request()` built and return the SAME `(status, body)` pair, so `anthropic_read`,
+    `is_credit_failure` and `refusal_sentence` each keep exactly one normalizer
+    ([[one-question-two-normalizers]]).
+    """
+    global _SDK
+    if _SDK is None:
+        try:
+            import anthropic as _mod      # noqa: PLC0415 - deliberately lazy; see the docstring
+            _SDK = _mod
+        except Exception:
+            _SDK = False
+    return _SDK or None
+
+
+def anthropic_send(req, timeout=None, use_sdk=None):
+    """POST one `anthropic_request()` dict. Returns `(status, body, transport)`.
+
+    ⭐ `transport` is `'sdk'` or `'http'` and it is RETURNED, not logged and forgotten: a reader
+    who cannot tell which path ran cannot tell whether the requirements pin reached the container
+    [[report-the-cause-before-you-fix-it]]. ⛔ A gate must assert on THIS RETURN VALUE, never on
+    `ai_review.LAST_ANTHROPIC_TRANSPORT` — that global is a convenience for `GET /meta`, and a
+    check keyed to it passes on a stale value written by an earlier check in the same process.
+
+    `status` is an int and `body` is the parsed JSON dict in BOTH paths, including on an error —
+    the SDK raises where `requests` returns, and normalising that difference here is the only
+    reason this function exists rather than the caller branching on transport.
+
+    ⚠ `use_sdk=False` forces the fallback. It exists so a gate can exercise BOTH transports
+    without assigning to `_SDK`: a test that mutates a module global and then throws leaves every
+    later check in that process running on the wrong path and passing for the wrong reason.
+    """
+    sdk = None if use_sdk is False else anthropic_sdk()
+    payload = dict(req.get("json") or {})
+    if sdk is None:
+        r = requests.post(req["url"], headers=req["headers"], json=payload,
+                          timeout=(timeout or 60))
+        try:
+            return r.status_code, (r.json() if r.content else {}), "http"
+        except Exception:
+            return r.status_code, {"_text": (r.text or "")[:2000]}, "http"
+
+    key = (req.get("headers") or {}).get("x-api-key") or ""
+    try:
+        client = sdk.Anthropic(api_key=key, timeout=float(timeout or 60))
+        msg = client.messages.create(**payload)
+        # ⚠ `.model_dump()` is what makes ONE reader serve both transports: it hands back the same
+        # wire-shaped dict the raw POST parses out of the response body.
+        return 200, msg.model_dump(), "sdk"
+    except Exception as exc:
+        # ⛔ THE STATUS IS THE PRODUCT HERE. Every sentence the reader sees is chosen by
+        # `refusal_sentence(status)`, so an exception that loses its code turns "Anthropic is out
+        # of credit" into "Anthropic did not answer" — the exact regression R4 was written to end.
+        status = int(getattr(exc, "status_code", 0) or 0)
+        body = getattr(exc, "body", None)
+        if not isinstance(body, dict):
+            body = {"_text": str(exc)[:2000]}
+        if not status:
+            # No status at all = it never reached the vendor (DNS, TLS, timeout). 408 is the one
+            # code `_STATUS_WORDS` already words as a reachability problem rather than a refusal.
+            status = 408 if isinstance(exc, getattr(sdk, "APIConnectionError", ())) else 0
+        return status, body, "sdk"
+
+
 def anthropic_read(body):
     """`(text, tool_input, refusal)` out of a Messages API answer.
 

api/routes_geo.py

@@ -0,0 +1,369 @@
+"""routes_geo.py — the MAP PROVIDER SEAM (wave 37, R3/R14, tickets T35/T36/T37).
+
+⭐ WHY THIS FILE EXISTS AT ALL, and why the map does not simply call a vendor.
+
+R14 (owner, 2026-08-19): no Google Maps API key this wave. The map work is not dropped, it is
+retargeted to providers that need no key: OpenStreetMap tiles, OSRM routing, Nominatim geocoding.
+The deferral only holds if swapping a paid vendor back in is a CONFIG change rather than a rewrite,
+so every provider is a (base URL + attribution) pair read from the environment and served from ONE
+door. The renderer receives a URL template and a credit line; it knows nothing about who is behind
+them. That is the seam.
+
+    tiles     AIOS_MAP_TILE_URL           default  https://tile.openstreetmap.org/{z}/{x}/{y}.png
+    geocode   AIOS_GEOCODE_URL            default  https://nominatim.openstreetmap.org/search
+    routing   AIOS_ROUTE_URL              default  https://router.project-osrm.org/route/v1/driving/
+
+⛔ R3'S ON-DEMAND RULE, AND WHY IT IS STRUCTURAL HERE RATHER THAN A COMMENT.
+R3 forbids geocoding a whole table automatically. Under R14 the reason moves from money to manners
+and gets sharper: Nominatim's usage policy allows roughly one request per second and explicitly
+forbids bulk harvesting, so a loop over 3,636 customers does not produce a bill, it produces a
+BLOCKED tenant. Three mechanisms enforce it, none of them advisory:
+
+  1. `/geo/geocode` takes an explicit LIST OF ADDRESSES from the caller. It cannot read a table, so
+     there is no code path from "a database exists" to "its rows were geocoded". Somebody had to
+     choose the records.
+  2. `MAX_BATCH` refuses an oversized list with a named error rather than truncating it. The client
+     drives the loop and can therefore SHOW the wait, which is the half of the ticket a comment
+     cannot satisfy.
+  3. `_throttle()` blocks in-process until the minimum interval has elapsed, so even a caller that
+     ignores everything above cannot exceed the published rate.
+
+⭐ AND A CACHE, because the policy asks for one: an address geocoded once is answered from memory
+for the rest of the container's life. It is the cheapest way to be a good citizen and it makes a
+re-run of the same records free rather than merely legal.
+
+⚠ NOTHING HERE PROXIES TILES. Tiles are fetched by the BROWSER, straight from the provider, which
+is what every OSM client does and what the tile policy expects. Proxying them through this app
+would put a free tier in the path of every pan and would breach the same policy it looks like it is
+respecting. This door serves the tile URL, never the tile.
+"""
+import os
+import re
+import threading
+import time
+from collections import OrderedDict
+
+import requests
+from fastapi import APIRouter, Body, Depends
+
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+# --------------------------------------------------------------------- the seam
+#
+# Every value below is an environment override with a keyless default. Pointing the map at a paid
+# vendor is three variables on the Space and no code change, which is what makes R14 a deferral.
+
+_TILE_URL_DEFAULT = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+_TILE_CREDIT_DEFAULT = "© OpenStreetMap contributors"
+_TILE_CREDIT_HREF_DEFAULT = "https://www.openstreetmap.org/copyright"
+_GEOCODE_URL_DEFAULT = "https://nominatim.openstreetmap.org/search"
+_ROUTE_URL_DEFAULT = "https://router.project-osrm.org/route/v1/driving/"
+
+#: Both policies require a real, identifying User-Agent. A generic one is how a shared service
+#: decides an application is a scraper, so this carries the product name and a contact URL.
+_UA_DEFAULT = "AIOS-Loopable/1.0 (+https://runloopable.com)"
+
+#: Nominatim publishes one request per second. 1100 ms leaves room for clock jitter rather than
+#: sitting exactly on the published edge.
+_MIN_INTERVAL_MS_DEFAULT = 1100
+
+#: The most addresses one call may carry. Small on purpose: the client loops and shows progress,
+#: and no single request can sit on the connection for a minute waiting out the throttle.
+MAX_BATCH = 25
+
+#: Tile zoom the provider actually serves. OSM stops at 19.
+_TILE_MAX_Z_DEFAULT = 19
+
+_CACHE_MAX = 4096
+
+
+def _env(name, default):
+    return (os.environ.get(name) or "").strip() or default
+
+
+def _env_int(name, default):
+    try:
+        n = int((os.environ.get(name) or "").strip())
+        return n if n > 0 else default
+    except (TypeError, ValueError):
+        return default
+
+
+def provider_config():
+    """The whole seam as one dict. `GET /geo/providers` serves it and the gate reads it."""
+    return {
+        "tiles": {
+            "url": _env("AIOS_MAP_TILE_URL", _TILE_URL_DEFAULT),
+            "attribution": _env("AIOS_MAP_TILE_ATTRIBUTION", _TILE_CREDIT_DEFAULT),
+            "attributionUrl": _env("AIOS_MAP_TILE_ATTRIBUTION_URL", _TILE_CREDIT_HREF_DEFAULT),
+            "maxZoom": _env_int("AIOS_MAP_TILE_MAX_Z", _TILE_MAX_Z_DEFAULT),
+        },
+        "geocode": {
+            "available": True,
+            "maxBatch": MAX_BATCH,
+            "minIntervalMs": _env_int("AIOS_GEOCODE_MIN_INTERVAL_MS", _MIN_INTERVAL_MS_DEFAULT),
+            # ⭐⭐ THE NUMBER THE SURFACE MUST QUOTE, AND IT IS NOT THE RATE LIMIT.
+            # T37 asks for the estimated wait to be shown BEFORE a run. The obvious source is
+            # `minIntervalMs`, and it is wrong: 1.1 s is a floor on POLITENESS, not a prediction of
+            # LATENCY. One real lookup was MEASURED at 3.28 s end to end on 2026-08-19. Quoting the
+            # limit would promise a minute and take three, and a progress estimate that runs out
+            # before the work does reads as a hang rather than as a wait.
+            "secondsPerAddress": float(_env("AIOS_GEOCODE_SECONDS_EACH", "3.3")),
+            "attribution": _env("AIOS_GEOCODE_ATTRIBUTION", _TILE_CREDIT_DEFAULT),
+        },
+        "route": {
+            "available": True,
+            "attribution": _env("AIOS_ROUTE_ATTRIBUTION", "Routing by OSRM"),
+        },
+    }
+
+
+# ------------------------------------------------------------------ the throttle
+#
+# ⚠ ONE lock and ONE timestamp for the whole process, shared by geocoding and routing, because the
+# rate limit belongs to the SERVICE and not to the endpoint. Two independent throttles would each
+# stay honest and together double the published rate.
+
+_gate = threading.Lock()
+_last_call = [0.0]
+
+
+def _throttle(min_interval_ms):
+    """Block until the minimum interval since the last outbound call has elapsed.
+
+    Returns the seconds actually waited, so a caller can report the wait rather than hide it."""
+    wait = 0.0
+    with _gate:
+        gap = min_interval_ms / 1000.0
+        now = time.monotonic()
+        due = _last_call[0] + gap
+        if now < due:
+            wait = due - now
+            time.sleep(wait)
+        _last_call[0] = time.monotonic()
+    return wait
+
+
+# --------------------------------------------------------------------- the cache
+
+_cache = OrderedDict()
+_cache_lock = threading.Lock()
+
+
+def _cache_key(q, country):
+    return (re.sub(r"\s+", " ", str(q or "")).strip().lower(), str(country or "").strip().lower())
+
+
+def _cache_get(key):
+    with _cache_lock:
+        if key not in _cache:
+            return None
+        _cache.move_to_end(key)
+        return _cache[key]
+
+
+def _cache_put(key, value):
+    with _cache_lock:
+        _cache[key] = value
+        _cache.move_to_end(key)
+        while len(_cache) > _CACHE_MAX:
+            _cache.popitem(last=False)
+
+
+def geocode_one(address, country=None, timeout=12):
+    """One address to {lat, lon, label} or None.
+
+    ⛔ THE ONLY PLACE AN OUTBOUND GEOCODE HAPPENS. `ai_enrich.py`'s geocode field calls this rather
+    than reaching for `requests` itself, so the throttle and the cache cannot be walked around by a
+    second caller. A cache hit costs no request and no wait."""
+    q = re.sub(r"\s+", " ", str(address or "")).strip()
+    if not q:
+        return None
+    key = _cache_key(q, country)
+    hit = _cache_get(key)
+    if hit is not None:
+        return dict(hit) if hit else None
+
+    cfg = provider_config()["geocode"]
+    _throttle(cfg["minIntervalMs"])
+    params = {"q": q, "format": "jsonv2", "limit": 1}
+    if country:
+        params["countrycodes"] = str(country).strip().lower()
+    try:
+        r = requests.get(
+            _env("AIOS_GEOCODE_URL", _GEOCODE_URL_DEFAULT),
+            params=params,
+            headers={"User-Agent": _env("AIOS_GEO_USER_AGENT", _UA_DEFAULT),
+                     "Accept": "application/json"},
+            timeout=timeout,
+        )
+        r.raise_for_status()
+        rows = r.json()
+    except Exception:
+        # ⚠ A transport failure is NOT cached. Caching it would turn one bad minute into a
+        # permanently empty column that no re-run could ever repair.
+        return None
+    if not isinstance(rows, list) or not rows:
+        # A genuine "no such place" IS cached, as a negative: asking again gets the same answer and
+        # spends another second of a shared service's budget to hear it.
+        _cache_put(key, {})
+        return None
+    top = rows[0] or {}
+    try:
+        lat = float(top.get("lat"))
+        lon = float(top.get("lon"))
+    except (TypeError, ValueError):
+        _cache_put(key, {})
+        return None
+    if not (-90 <= lat <= 90) or not (-180 <= lon <= 180):
+        _cache_put(key, {})
+        return None
+    out = {"lat": lat, "lon": lon, "label": str(top.get("display_name") or q)}
+    _cache_put(key, out)
+    return dict(out)
+
+
+# ---------------------------------------------------------------------- the doors
+
+
+@router.get("/geo/providers")
+def geo_providers(session: Session = Depends(require_session)):
+    """What the map should draw with, and who to credit for it.
+
+    Session gated like every other door here. The values are not secret, but an unauthenticated
+    endpoint on this app is a door somebody eventually hangs something else on."""
+    return provider_config()
+
+
+@router.post("/geo/geocode")
+def geo_geocode(body: dict = Body(...), session: Session = Depends(require_session)):
+    """Turn a bounded list of addresses into coordinates.
+
+    ⛔ Takes ADDRESSES, never a table key, a view id or a filter. There is deliberately no shape of
+    request that means "geocode everything", which is R3 expressed as an API rather than as a
+    warning."""
+    items = body.get("addresses")
+    # ⭐ THE SECOND SHAPE, AND IT EXISTS TO KEEP ONE COMPOSER. A caller may send whole RECORDS plus
+    # the geocode field's config instead of finished address strings, and the server builds the
+    # query with `ai_enrich.geocode_query`. The alternative was a TypeScript twin of that function
+    # on the client, and an address composer that exists twice will disagree the first time either
+    # copy learns about a new column ([[one-question-two-normalizers]]) -- which is exactly the trap
+    # B's measured `New York (US)` suffix would spring, silently, in whichever copy forgot.
+    if items is None:
+        records = body.get("records")
+        cfg = body.get("config") or {}
+        if isinstance(records, list) and records:
+            import ai_enrich
+            items = []
+            for rec in records:
+                if not isinstance(rec, dict):
+                    continue
+                q = ai_enrich.geocode_query(rec.get("row") or {}, cfg)
+                # ⛔ A record with no usable address is REPORTED, not dropped: it comes back
+                # `found: false` with an empty address, so the caller can name it on screen instead
+                # of quietly returning fewer answers than it asked questions.
+                items.append({"key": rec.get("key"), "address": q})
+            if not body.get("country") and cfg.get("country"):
+                body = {**body, "country": cfg.get("country")}
+    if not isinstance(items, list) or not items:
+        raise err(400, "no_addresses", "Send at least one address to look up.")
+    if len(items) > MAX_BATCH:
+        raise err(
+            400,
+            "batch_too_large",
+            f"Look up at most {MAX_BATCH} addresses per request. "
+            f"The map sends them in batches of {MAX_BATCH} so the wait stays visible.",
+        )
+    country = body.get("country")
+    out = []
+    started = time.monotonic()
+    for raw in items:
+        if isinstance(raw, dict):
+            key, addr = raw.get("key"), raw.get("address")
+        else:
+            key, addr = None, raw
+        # ⛔ AN EMPTY QUERY COSTS NO REQUEST AND CARRIES ITS OWN REASON. Nominatim's policy is a
+        # budget shared with everyone else using it, and asking it to place "" would spend a second
+        # of that budget to be told nothing. `reason` is what lets the surface say "no address on
+        # file" rather than "not found", which are different facts and want different actions.
+        if not str(addr or "").strip():
+            out.append({"key": key, "address": "", "found": False, "lat": None, "lon": None,
+                        "label": None, "reason": "no_address"})
+            continue
+        hit = geocode_one(addr, country=country)
+        out.append({"key": key, "address": str(addr or ""), "found": bool(hit),
+                    "reason": None if hit else "not_found",
+                    "lat": hit["lat"] if hit else None,
+                    "lon": hit["lon"] if hit else None,
+                    "label": hit["label"] if hit else None})
+    elapsed = time.monotonic() - started
+    return {"results": out,
+            "found": sum(1 for r in out if r["found"]),
+            "asked": len(out),
+            "secondsElapsed": round(elapsed, 2),
+            "attribution": provider_config()["geocode"]["attribution"]}
+
+
+@router.post("/geo/route")
+def geo_route(body: dict = Body(...), session: Session = Depends(require_session)):
+    """Road distance, duration and the drawn line, for stops ALREADY put in order.
+
+    ⭐ THE ORDERING IS NOT DONE HERE. `mapProjection.planRoute` sequences the stops on the client,
+    for free, and keeps working when this service does not answer. This door adds the half that
+    arithmetic cannot produce: what the ROADS actually cost. Splitting it that way is why the Start
+    picker and the round-trip toggle keep working with no network at all."""
+    stops = body.get("stops")
+    if not isinstance(stops, list) or len(stops) < 2:
+        raise err(400, "too_few_stops", "A route needs at least two stops with a location.")
+    if len(stops) > 25:
+        raise err(400, "too_many_stops",
+                   "Route at most 25 stops at once. Narrow the selection and try again.")
+    pairs = []
+    for s in stops:
+        try:
+            lat, lon = float(s["lat"]), float(s["lon"])
+        except (TypeError, ValueError, KeyError, IndexError):
+            raise err(400, "bad_stop", "Every stop needs a numeric latitude and longitude.")
+        if not (-90 <= lat <= 90) or not (-180 <= lon <= 180):
+            raise err(400, "bad_stop", "Every stop needs a latitude and longitude on the globe.")
+        pairs.append(f"{lon:.6f},{lat:.6f}")
+
+    base = _env("AIOS_ROUTE_URL", _ROUTE_URL_DEFAULT)
+    _throttle(_env_int("AIOS_GEOCODE_MIN_INTERVAL_MS", _MIN_INTERVAL_MS_DEFAULT))
+    try:
+        r = requests.get(
+            base.rstrip("/") + "/" + ";".join(pairs),
+            params={"overview": "simplified", "geometries": "geojson", "steps": "false"},
+            headers={"User-Agent": _env("AIOS_GEO_USER_AGENT", _UA_DEFAULT)},
+            timeout=20,
+        )
+        r.raise_for_status()
+        data = r.json()
+    except Exception:
+        raise err(502, "route_service_unavailable",
+                   "The routing service did not answer. The stop order and the straight line "
+                   "distance are still on the map.")
+    routes = (data or {}).get("routes") or []
+    if not routes:
+        raise err(
+            502,
+            "no_route",
+            "No road route connects these stops. They may be on different land masses, or one of "
+            "them may be far from any road.",
+        )
+    top = routes[0]
+    geom = ((top.get("geometry") or {}).get("coordinates")) or []
+    line = []
+    for c in geom:
+        try:
+            line.append([float(c[0]), float(c[1])])
+        except (TypeError, ValueError, IndexError):
+            continue
+    return {
+        "km": round(float(top.get("distance") or 0.0) / 1000.0, 1),
+        "minutes": int(round(float(top.get("duration") or 0.0) / 60.0)),
+        "line": line,
+        "attribution": provider_config()["route"]["attribution"],
+    }

api/routes_products.py

@@ -115,15 +115,190 @@ def scoped_pool(session: Session):
     return pids, team_id, rows_src, fields_base
 
 
+#: The semantic ENTITY topic this grid IS. `model/topics/odoo_products.yml` names the same store
+#: key in its `grid:` field, so the binding is stated at both ends rather than inferred.
+TOPIC = "product_data"
+SEM_TOPIC = "odoo_products"
+
+
+def _measure_err(tag, e):
+    try:
+        import harness.telemetry as _tel
+        _tel.error(f"api:{tag}", e)
+    except Exception:
+        pass
+
+
+def _measure_stamp(rt, team_id):
+    """The cached pool's build timestamp — the DATA STAMP in every memo key, so a pool refresh
+    invalidates memoised measure answers exactly when the underlying rows changed. Same
+    discipline as `routes_customers._pool_stamp`, over THIS route's cache key."""
+    entry = rt.pool_cache.get(("product_pool", team_id))
+    return entry[0] if isinstance(entry, tuple) and entry else 0
+
+
+def product_measures():
+    """The measure OFFER for this database, or `[]` when the semantic layer cannot answer.
+
+    ⭐⭐ W37-T10 / owner item 4 (R1) — this is what turns `measures: []` into a real catalogue.
+    Owner: *"Odoo products should have a lookbsck metrics like sales etc."* The list is DERIVED
+    from `model/topics/odoo_products.yml`'s `measures:` binding, never written here — a second
+    list would be a second definition of the same fact.
+
+    ⚠ `[]` ON FAILURE IS THE CORRECT DEGRADE and it is not silent: `entity_measures` refuses a key
+    it cannot prove, the reasons are readable through `semantic.entity_measure_refusals`, and the
+    client's own rule (`offerMeasure={measures.length > 0}`) then hides the Metric kind rather
+    than offering a column that could only render blank.
+    """
+    try:
+        from harness import semantic as sem
+        return sem.entity_measures(SEM_TOPIC)
+    except Exception as e:                                             # noqa: BLE001
+        _measure_err("product-measure-offer", e)
+        return []
+
+
+def _measure_cells(fields, rows_src, team_id, today, stamp, memo, offer):
+    """`{pid: {field key: value}}` for every measure column on this grid.
+
+    ⛔ THIS IS THE HALF THAT MAKES THE FEATURE REAL. Serving the OFFER alone flips the client's
+    `offerMeasure` on and lets a user mint a Metric column that would then be blank forever —
+    this repo's most repeated defect ([[reachable-is-not-the-same-as-built]]). Nothing else
+    computes product-grain measure values: `core.measure_resolve.column_values` is CUSTOMER-grain
+    (it resolves through `harness.measure_filter`, whose entity is the partner), which is exactly
+    what this route's docstring used to record as an honest absence.
+
+    ⭐ ONE QUERY PER WINDOW, not per column. Two Metric columns over the same 90 days are one
+    grouped scan; the fan-out to field keys happens in memory afterwards.
+
+    ⛔ THE JOIN IS BY SKU CODE, per contract C1's trap. `sales_lines.product_code` reproduces this
+    pool's identity (`default_code`, or `pid:<odoo id>` for the 33 codeless actives) and `pid` is
+    a CRC32 of it — so the map is `row['code'] -> row['pid']`, taken off the rows we already hold.
+    Grouping by Odoo's `product_id` instead would key cells on a value no grid row carries.
+    """
+    import aios_grid
+
+    mfields = aios_grid.measure_fields_of(fields)
+    if not mfields or not offer:
+        return {}
+    from harness import semantic as sem
+    from harness import windows as _wn
+
+    by_key = {m["key"]: m for m in offer}
+    codes = {r["pid"]: r["code"] for r in rows_src if r.get("pid") is not None}
+
+    # Group the columns by WINDOW: same window, same scan.
+    by_window = {}
+    for f in mfields:
+        spec = f.get("measure") or {}
+        if spec.get("key") not in by_key:
+            continue           # not offered for this caller -> the column stays blank, honestly
+        w = _wn.normalize(spec.get("window"))
+        rng = _wn.resolve(spec.get("window"), today) if w is not None else None
+        if rng is None:
+            # ⛔ NEVER WIDEN TO ALL TIME. An unresolvable window is an unanswerable column, and
+            # silently answering a different question is worse than a blank one.
+            continue
+        by_window.setdefault((rng[0], rng[1]), []).append(f)
+
+    out = {}
+    for (dfrom, dto), group in by_window.items():
+        keys = tuple(sorted({f["measure"]["key"] for f in group}))
+        mkey = ("entity", SEM_TOPIC, stamp, team_id, dfrom, dto, keys)
+        if mkey not in memo:
+            try:
+                memo[mkey] = sem.entity_measure_values(
+                    SEM_TOPIC, list(keys), date_from=dfrom, date_to=dto, team_id=team_id,
+                    # ⛔ SERVICES ARE IN THIS CATALOGUE (37 active), so they must NOT be excluded
+                    # here. The service filter exists to stop Delivery Charges polluting a SKU
+                    # RANKING; on a per-row column the row IS the service product, and excluding
+                    # it would print a FALSE 0 — which under C1's rule asserts "sold nothing".
+                    exclude_services=False, offer=offer)
+            except Exception as e:                                     # noqa: BLE001
+                _measure_err("product-measure-column", e)
+                # Same memo discipline as `measure_resolve.column_values`: a PERMANENT failure
+                # memoises, a TRANSIENT one (store still warming after a restart) must not, or
+                # the cells stay blank for the rest of the session long after the data landed.
+                transient = False
+                try:
+                    from harness import datastore as _ds
+                    transient = not _ds.ready()
+                except Exception:                                      # noqa: BLE001
+                    transient = False
+                if transient:
+                    continue
+                memo[mkey] = None
+        vals = memo[mkey]
+        if vals is None:
+            continue
+        # C1's empty-window rule, applied to EVERY row — not only the ones with a group. 72% of
+        # this catalogue has no group in a 90-day window, so this loop IS the common case.
+        filled = {pid: sem.entity_zero_fill(vals.get(code), list(keys), offer)
+                  for pid, code in codes.items()}
+        for f in group:
+            k, fkey = f["measure"]["key"], f["key"]
+            for pid, cell in filled.items():
+                if k in cell:
+                    out.setdefault(pid, {})[fkey] = cell[k]
+    if len(memo) > 100:                        # a lifetime cache, not a leak
+        memo.clear()
+    return out
+
+
+def _measure_condition_sets(views, offer, rows_src, team_id, today):
+    """`{rule id: [pid, …]}` for every measure CONDITION across this session's saved views.
+
+    ⚠ THE ANSWER IS KEYED BY pid, NOT BY SKU CODE. `entity_measure_sets` answers in the SOURCE
+    dim's own values (the code) because it cannot know how a grid hashes identity; the map back
+    is this route's job, exactly as it is for the column cells.
+    """
+    if not offer:
+        return {}
+    from harness import semantic as sem
+
+    admitted = {m["key"] for m in offer}
+    by_id = {}
+    for v in views or []:
+        cfg = (v.get("config") or {})
+        for rule in sem.entity_measure_leaves(cfg.get("filters"), admitted):
+            rid = str(rule.get("id") or "")
+            if rid:
+                by_id[rid] = rule            # last statement of the question wins
+    if not by_id:
+        return {}
+    pid_by_code = {r["code"]: r["pid"] for r in rows_src if r.get("pid") is not None}
+    try:
+        sets = sem.entity_measure_sets(
+            SEM_TOPIC, list(by_id.values()), today, team_id=team_id,
+            keys_by_id=list(pid_by_code), offer=offer, exclude_services=False)
+    except Exception as e:                                             # noqa: BLE001
+        _measure_err("product-measure-sets", e)
+        return {}
+    # A code the pool does not carry is dropped rather than keyed on None — the same rule the
+    # cell path applies, for the same reason.
+    return {rid: sorted(pid_by_code[c] for c in codes if c in pid_by_code)
+            for rid, codes in sets.items()}
+
+
 def product_assembly(session: Session, scope: str = "product", storage_key: str = "",
                      consume_corrections: bool = True):
     """The product topic's mirror of `routes_customers.grid_assembly` — SAME g-dict keys, so
     the /workspace and events routes consume either interchangeably.
 
-    One deliberate absence, a topic fact rather than a gap:
-      * `measures`/`measure_sets` are EMPTY — `core.measure_resolve` is CUSTOMER-grain (the
-        C-TOPIC v1 descope, booked in the wave doc); the events ctx therefore refuses measure
-        creates on this surface, which is the correct fail-closed shape.
+    ⭐⭐ W37-T10 / OWNER ITEM 4 (R1) — `measures` IS NO LONGER EMPTY, and the header above it used
+    to record the opposite as a topic fact. It was one: `core.measure_resolve` is CUSTOMER-grain,
+    so nothing here could resolve a product-grain measure. What changed is that the ENTITY path
+    exists now (`semantic.entity_measures` / `entity_measure_values`, bound in
+    `model/topics/odoo_products.yml`), so this surface serves a real six-metric catalogue AND the
+    cells to go with it — the offer and the resolver landing together, deliberately, because an
+    offer whose values nobody computes is a column that renders blank forever.
+
+    One deliberate absence remains, and it is a real one:
+      * `measure_sets` stays EMPTY — that is the measure CONDITION channel (a filter answered
+        server-side as a pid set), which still runs through the customer-grain
+        `measure_resolve.condition_sets`. So a Metric COLUMN works here; a Metric FILTER does
+        not yet. Stated rather than left to be discovered: `clean_filter_tree` drops a measure
+        condition whose key is not in `measure_keys`, so the refusal is already fail-closed.
 
     ⭐ WAVE 19 / R9 — `lists` IS NO LONGER EMPTY. Wave 16 passed `with_cohorts=False` because
     there was one customer-keyed cohort bucket and product pids are CRC32 hashes of SKU codes;
@@ -172,12 +347,29 @@ def product_assembly(session: Session, scope: str = "product", storage_key: str
         fields = [f for f in fields if f.get("key") not in hidden]
         rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
 
+    today = time.strftime("%Y-%m-%d")
+    stamp = _measure_stamp(session.runtime, team_id)
+    measures = product_measures()
+
+    # R9: the Cohorts column's cells, built from THIS topic's lists. ⭐ W37-T10 — the measure
+    # half of this same read-only channel is no longer empty; the customer assembly merges its
+    # measure columns here for exactly the same reason and through the same door.
+    derived = aios_grid.cohort_cells(lists)
+    for pid, cells in _measure_cells(fields, rows_src, team_id, today, stamp,
+                                     session.runtime.measure_memo, measures).items():
+        derived.setdefault(pid, {}).update(cells)
+
+    # ⛔ THE CONDITION CHANNEL SHIPS WITH THE OFFER, NOT AFTER IT. `routes_grid` derives
+    # `measure_keys` from this same list, so the moment `measures` is non-empty the client's
+    # filter builder offers measure conditions — and an id missing from `measureSets` renders as
+    # PENDING ("Calculating…") and matches nothing, permanently. Serving the offer without this
+    # would trade one honest absence for a spinner that never resolves.
+    measure_sets = _measure_condition_sets(views, measures, rows_src, team_id, today)
+
     return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
             "fields": fields, "views": views, "lists": lists,
-            # R9: the Cohorts column's cells, built from THIS topic's lists. Same read-only
-            # `derived` channel the customer assembly uses — the measure half stays empty.
-            "derived": aios_grid.cohort_cells(lists),
-            "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
+            "derived": derived,
+            "measures": measures, "measure_sets": measure_sets, "today": today,
             "team_id": team_id}
 
 

api/routes_script_views.py

@@ -1,329 +1,439 @@
-"""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
+"""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}
+    POST   /api/v1/script-views/{id}/revert     go back to an earlier version  {version}
+
+⭐⭐ **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, *, allow_empty=False):
+    """The stored source, or a 400. `allow_empty` is CREATE's alone and the asymmetry is the point.
+
+    ⭐⭐ W37-T41 — WHY CREATE MAY BE EMPTY AND SAVE MAY NOT.
+    Picking "Custom View" in the mode picker mints the view immediately, before a line of code
+    exists, so that `mode === 'script'` always implies a real id and no reader has to carry a
+    "the id might be missing" branch (the create semantics handed to lane C in mailbox E-7).
+    A view that has been created and not yet written is therefore a REAL, legible state: the editor
+    shows its starter placeholder and the Run control is right there.
+    A PUT is a different act. It appends a VERSION to a history capped at 40, and blanking a
+    working script by saving nothing over it is not an edit anybody means to make. So the guard
+    stays exactly where it was on that door, and a person who wants the view gone deletes it.
+
+    ⛔ THIS WAS FOUND BY THE GATE, NOT BY READING. `core.script_sandbox.check_source("")` returns
+    None, so "an empty script is storable" looked true and was written into a mailbox answer another
+    lane was about to build on. The refusal was HERE, one layer above, in a function the sandbox
+    knows nothing about. Two validators for one question, disagreeing
+    [[one-question-two-normalizers]] — and the one that would have bitten a person is the one no
+    unit of this feature was asserting.
+    """
+    source = str(raw or "")
+    if not source.strip() and not allow_empty:
+        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),
+           # ⭐ W37-T46: which version this one was RESTORED from, when it was. Present on the
+           # row (not only the history) because the editor's header is where a person reads "what
+           # am I looking at", and "v5, restored from v2" is the sentence that makes a roll-back
+           # legible as an event rather than as a coincidence of matching code.
+           "restoredFrom": rec.get("restoredFrom")}
+    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)
+    # ⭐  is CREATE's alone - see . The picker mints a view the
+    # moment a person chooses the mode, so the empty source is the normal first state, not a slip.
+    source = _clean_source(body.get("source"), allow_empty=True)
+    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.post("/script-views/{view_id}/revert")
+def revert_script_view(view_id: str, body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    """Put one view back to an earlier version. D-338 / W37-T46.
+
+    ⭐⭐ A ROLL-BACK IS A NEW VERSION, NEVER A DELETE OF THE ONES AFTER IT, and that is the whole
+    point of the ticket rather than an implementation detail. The history is what lets a person
+    trust an agent with their code: if reverting destroyed the versions it stepped over, one
+    mistaken revert would cost exactly what the history existed to protect, and there would be no
+    way back from the way back. So this appends, and `restoredFrom` records where the text came
+    from — the same posture the agent-harness roll-back already takes, so a reader who has seen one
+    is not surprised by the other.
+
+    ⛔ IT LIVES ON THE SERVER BECAUSE THE HISTORY DOES. The list door deliberately serves history
+    entries WITHOUT their source (`_row`: the rail lists names), so a client cannot assemble an old
+    version's text to re-PUT it. Handing the source out just so the client could send it straight
+    back would widen a payload for a round trip that does not need to exist, and would make the
+    revert non-atomic: two calls, and a failure between them leaves the person looking at code that
+    is not what is stored.
+    ⚠ `_clean_source` is NOT re-run. The text being restored was already validated when it was
+    first saved, and a source that a later, stricter rule would now reject is exactly the source a
+    person is most likely to want back. `check_source` still runs, because the SANDBOX's refusal is
+    about what the code would DO and that must never be bypassed by a route.
+    """
+    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 {}
+    try:
+        want = int(body.get("version"))
+    except (TypeError, ValueError):
+        raise err(400, "no_version", "say which version to go back to") from None
+
+    history = [h for h in (rec.get("history") or []) if isinstance(h, dict)]
+    match = next((h for h in history if int(h.get("version") or 0) == want), None)
+    if match is None:
+        # ⛔ TWO REASONS A VERSION IS MISSING AND THEY ARE NOT THE SAME FACT. One was never
+        # written; the other was TRIMMED off the 40-deep history and the record even counts how
+        # many. Saying "that version is gone" for the first would be a lie a person could act on.
+        trimmed = int(rec.get("trimmed") or 0)
+        if trimmed and want <= trimmed:
+            raise err(410, "version_trimmed",
+                      f"version {want} is older than this view's history keeps "
+                      f"({trimmed} earlier versions have been dropped)")
+        raise err(404, "no_version", f"this view has no version {want}")
+
+    source = str(match.get("source") or "")
+    refusal = sandbox.check_source(source)
+    if refusal is not None:
+        # An older version that today's sandbox refuses. The person is told which version and why,
+        # rather than being handed a 400 about code they did not just type.
+        raise err(400, refusal.code, f"version {want} cannot be restored: {refusal.message}")
+
+    def _mutate(prior):
+        prior = dict(prior or rec)
+        history_now = list(prior.get("history") or [])
+        history_now.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_now) - MAX_HISTORY)
+        prior["history"] = history_now[dropped:] if dropped else history_now
+        prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
+        prior["source"] = source
+        prior["version"] = int(prior.get("version") or 1) + 1
+        prior["updated"] = _now()
+        # ⚠ ON THE RECORD, so the history reads as WHAT HAPPENED rather than as a version that
+        # mysteriously matches an older one. Without it a reader sees v5 and v2 with identical
+        # code and no way to tell a revert from a coincidence.
+        prior["restoredFrom"] = want
+        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 roll-back was NOT saved")
+    return {"view": _row(fresh, source=True), "restoredFrom": want, "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_tables.py

@@ -630,7 +630,23 @@ def ut_write_ctx(session: Session, table_key: str):
     return {"rows_src": [], "pids": pids, "ws": ws, "workspace": workspace,
             "fields": fields, "views": views, "lists": lists, "hidden": hidden,
             "derived": aios_grid.cohort_cells(lists),
-            "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
+            # ⭐ W37-T12 — the OFFER, because `routes_grid` reads `g["measures"]` as the ADMISSION
+            # list for `clean_measure_field`: without it a Metric create on this surface is
+            # refused `measure_not_offered` even though the read door offers the kind.
+            # ⛔ THE CELLS ARE DELIBERATELY ABSENT HERE. This ctx validates a write and
+            # materialises no rows at all (W30-T30 removed a full table build from the write
+            # path); computing measure values would put that work straight back. `measure_sets`
+            # stays empty for the same reason — a write is not a render.
+            # ⭐ AND THE ASYMMETRY IS SAFE, WHICH IS NOT OBVIOUS AND WAS CHECKED RATHER THAN
+            # ASSUMED. `routes_grid._ctx` derives TWO things from this dict and they have
+            # different jobs: `measure_keys` (from `measures`) is the ADMISSION list
+            # `clean_filter_tree` uses — non-empty here, so a saved measure CONDITION survives the
+            # write, which is the failure that comment records for the customer path. Empty
+            # `resolved_ids` (from `measure_sets`) only makes `view_upsert` answer "rerender",
+            # so the next `/workspace` — which DOES compute the sets, in `ut_assembly` — resolves
+            # it. Conservative in the right direction: one extra repaint, never a dropped filter.
+            "measures": ut_measures(table_key),
+            "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
             # ⭐ W31-T20 — the write door reads this to refuse a PID-BEARING event loudly rather
             # than letting `allowed_pids` swallow it as a no-op. See `routes_grid`'s ut_ branch.
             "limits": limits, "defn": defn}
@@ -741,16 +757,154 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
     # so the closure covers this user's `custom_` and `measure_` columns too.
     fields, rows_src, hidden = _ut_field_wall(session, table_key, fields, rows_src)
 
+    # ⭐⭐ W37-T12 / owner item 4 (R1) — `measures` IS NO LONGER UNCONDITIONALLY EMPTY. A database
+    # whose entity topic declares a `measures:` binding (today `ut_odoo_agents`) serves a real
+    # lookback catalogue AND the cells to go with it; every other user table still serves `[]`,
+    # which is the honest answer for a hand-typed one rather than a descope.
+    today = time.strftime("%Y-%m-%d")
+    measures = ut_measures(table_key)
+    derived = aios_grid.cohort_cells(lists)          # R9: this table's own lists
+    for _pid, _cells in _ut_measure_cells(table_key, fields, pids, today, measures,
+                                          session.runtime.measure_memo).items():
+        derived.setdefault(_pid, {}).update(_cells)
+
     return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
             "fields": fields, "views": views, "lists": lists, "hidden": hidden,
-            # R9: the Cohorts column's cells from this table's own lists.
-            "derived": aios_grid.cohort_cells(lists),
-            "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
+            "derived": derived,
+            "measures": measures,
+            "measure_sets": _ut_measure_sets(table_key, views, measures, pids, today),
+            "today": today,
             # ⚠ ALWAYS PRESENT, EMPTY WHEN THERE IS NOTHING TO SAY — a key a consumer has to test
             # for is a key a consumer forgets to test for, and this one carries a refusal.
             "limits": limits, "defn": defn}
 
 
+def _ut_measure_err(tag, e):
+    try:
+        import harness.telemetry as _tel
+        _tel.error(f"api:{tag}", e)
+    except Exception:                                                  # noqa: BLE001
+        pass
+
+
+def ut_measures(table_key):
+    """The lookback-measure OFFER for a user database, or `[]` — W37-T12 / owner item 4 (R1).
+
+    ⭐ THE SAME ENGINE THE PRODUCT GRID USES (`semantic.entity_measures`), reached through the
+    topic that DESCRIBES this database. A table with no entity topic, or a topic with no
+    `measures:` binding, gets `[]` — which is the honest answer for a hand-typed database and is
+    what keeps the Metric kind hidden there (`ColumnMenu`'s `offerMeasure={measures.length > 0}`).
+
+    ⛔ NOT A `{table_key: [keys]}` MAP IN THIS FILE. The binding is declared in the model
+    (`model/topics/odoo_agents.yml`'s `measures:` block) and the topic already names its own grid,
+    so a list here would be a second definition of one fact — the argument `_rollup_source_offer`
+    makes about itself one screen down.
+    """
+    try:
+        from harness import semantic as sem
+        topic = sem.topic_for_grid(table_key)
+        return sem.entity_measures(topic) if topic else []
+    except Exception as e:                                             # noqa: BLE001
+        _ut_measure_err("ut-measure-offer", e)
+        return []
+
+
+def _ut_measure_cells(table_key, fields, pids, today, offer, memo, team_id=None):
+    """`{pid: {field key: value}}` for this database's Metric columns.
+
+    ⭐ THE JOIN NEEDS NO MAP HERE, and that is worth stating because the product grid DOES need
+    one. `sales_lines.agent` is `rp.agent_id` — a `res.partner` id — and a `ut_odoo_agents` row's
+    `pid` IS its `res.partner` id (`scoped_pool` sets `pid = int(rid)` and `read_agents` keys
+    `_id` on the partner id). So the group key and the pid are the same integer. The product grid
+    keys on `default_code` instead, which is exactly why contract C1 calls the join key a trap:
+    the right answer differs per database and must be read off the binding, never assumed.
+    """
+    import aios_grid
+
+    mfields = aios_grid.measure_fields_of(fields)
+    if not mfields or not offer:
+        return {}
+    from harness import semantic as sem
+    from harness import windows as _wn
+
+    topic = sem.topic_for_grid(table_key)
+    by_key = {m["key"]: m for m in offer}
+    by_window = {}
+    for f in mfields:
+        spec = f.get("measure") or {}
+        if spec.get("key") not in by_key:
+            continue
+        rng = _wn.resolve(spec.get("window"), today) if _wn.normalize(spec.get("window")) else None
+        if rng is None:
+            continue           # an unresolvable window is unanswerable — never widen to all time
+        by_window.setdefault((rng[0], rng[1]), []).append(f)
+
+    out = {}
+    for (dfrom, dto), group in by_window.items():
+        keys = tuple(sorted({f["measure"]["key"] for f in group}))
+        mkey = ("entity", topic, table_key, today, team_id, dfrom, dto, keys)
+        if mkey not in memo:
+            try:
+                memo[mkey] = sem.entity_measure_values(topic, list(keys), date_from=dfrom,
+                                                       date_to=dto, team_id=team_id, offer=offer)
+            except Exception as e:                                     # noqa: BLE001
+                _ut_measure_err("ut-measure-column", e)
+                transient = False
+                try:
+                    from harness import datastore as _ds
+                    transient = not _ds.ready()
+                except Exception:                                      # noqa: BLE001
+                    transient = False
+                if transient:
+                    continue           # a warming store must not memoise as a permanent failure
+                memo[mkey] = None
+        vals = memo[mkey]
+        if vals is None:
+            continue
+        # C1's empty-window rule for EVERY row, not only the grouped ones.
+        filled = {pid: sem.entity_zero_fill(vals.get(pid), list(keys), offer) for pid in pids}
+        for f in group:
+            k, fkey = f["measure"]["key"], f["key"]
+            for pid, cell in filled.items():
+                if k in cell:
+                    out.setdefault(pid, {})[fkey] = cell[k]
+    if len(memo) > 100:
+        memo.clear()
+    return out
+
+
+def _ut_measure_sets(table_key, views, offer, pids, today, team_id=None):
+    """`{rule id: [pid, …]}` for the measure CONDITIONS in this database's saved views.
+
+    ⛔ SHIPS WITH THE OFFER, NEVER AFTER IT. `routes_grid` derives `measure_keys` from the same
+    list, so a non-empty `measures` also opens the measure condition in the filter builder — and a
+    rule id missing from `measureSets` renders PENDING ("Calculating…") and matches nothing,
+    permanently. Offer and sets are one feature.
+    """
+    if not offer:
+        return {}
+    from harness import semantic as sem
+
+    topic = sem.topic_for_grid(table_key)
+    admitted = {m["key"] for m in offer}
+    by_id = {}
+    for v in views or []:
+        for rule in sem.entity_measure_leaves((v.get("config") or {}).get("filters"), admitted):
+            rid = str(rule.get("id") or "")
+            if rid:
+                by_id[rid] = rule
+    if not by_id:
+        return {}
+    try:
+        sets = sem.entity_measure_sets(topic, list(by_id.values()), today, team_id=team_id,
+                                       keys_by_id=list(pids), offer=offer)
+    except Exception as e:                                             # noqa: BLE001
+        _ut_measure_err("ut-measure-sets", e)
+        return {}
+    return {rid: sorted(int(k) for k in ks if str(k).lstrip("-").isdigit())
+            for rid, ks in sets.items()}
+
+
 def ut_label(defn, key, meta=None):
     """THE name of a user table, resolved ONCE (wave 20, item 6a).
 
@@ -857,11 +1011,38 @@ def _rollup_source_offer():
              "description": m.get("description") or ""})
 
     out = []
+    indeterminate = False
     for tkey, t in sorted(topics.items()):
         dims = ((t.get("store") or {}).get("dims") or {})
         measures = by_topic.get(tkey) or []
         if not dims or not measures:
             continue
+        # ⛔⛔ W37-T13 / /validate-wave 2026-08-19 — THE SOURCE TABLE MUST BE LIVE, AND THIS DOOR
+        # DID NOT ASK. The docstring above already promises *"ONLY COMBINATIONS THAT CAN RESOLVE
+        # ARE OFFERED"*; adding `stock_move` to `datastore.ENTITIES` broke that promise on the one
+        # door nobody re-read. `semantic._one_binding_offer` — the MEASURE-CATALOG door — refuses
+        # the same bindings with a stated cause, so the wave shipped **two doors onto one
+        # vocabulary with only one of them guarded**, and the unguarded one is the picker.
+        # MEASURED: `_rollup_source_offer()` listed `stock_moves` with both measures and all four
+        # dims while `royal.duckdb` has no `stock_move` table at all, so choosing it raised
+        # `CatalogException: Table with name stock_move does not exist!` — five of the fifty
+        # (topic, measure, dim) triples in `verify_odoo_relational`. A user meets a raw catalog
+        # error, or a column that looks configured and is blank forever
+        # ([[permitted-is-not-answerable]]).
+        # ⚠ REUSES `_source_ready` rather than re-deriving readiness: one question, one
+        # normalizer. `None` (the store could not be asked) refuses TOO — fail closed, exactly as
+        # the measure door does.
+        _tbl = (t.get("store") or {}).get("table")
+        if _tbl:
+            _rdy = sem._source_ready(_tbl)
+            if _rdy is not True:
+                # ⛔ AND AN INDETERMINATE ANSWER MUST NOT BE CACHED. `_source_ready`'s own comment
+                # records the measured version of this: a cold container with no mirror yet
+                # refused every binding, the refusal was memoised, and the grid served no measures
+                # long after the mirror arrived. Here the same shape would freeze a truncated
+                # PICKER for the life of the process.
+                indeterminate = indeterminate or (_rdy is None)
+                continue
         out.append({
             "key": tkey,
             "label": t.get("label") or tkey,
@@ -883,7 +1064,10 @@ def _rollup_source_offer():
     windows = [{"key": k, "label": W.WINDOW_LABELS.get(k, k).format(n="N")}
                for k in ut.ROLLUP_SOURCE_WINDOWS]
     offer = {"topics": out, "windows": windows}
-    _ROLLUP_CACHE["offer"] = offer
+    # ⚠ Cache only a DEFINITE answer (see the readiness block above): if any topic was dropped
+    # because the store could not be asked, this offer is a snapshot of an unknown, not a fact.
+    if not indeterminate:
+        _ROLLUP_CACHE["offer"] = offer
     return offer
 
 

platform/aios_grid.py

@@ -24,6 +24,7 @@ Design notes:
     injected-HTML path remains a read/local-write fallback when component assets are absent.
 """
 import json
+import math
 import re
 from pathlib import Path
 
@@ -89,6 +90,22 @@ def _round(v):
     return round(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else v
 
 
+def _round2(v):
+    """D-153 (W37, asked by lane B) — MONEY AND PERCENT KEEP THEIR DECIMALS.
+
+    `_round`'s whole-number convention is right for counts and wrong for currency: `first_cost`
+    3.47 shipped as `3`, so every money cell on every Odoo grid was a whole dollar.
+
+    ⚠ `pct` IS AFFECTED TOO, and that is the half most likely to be dropped. `cells.ts` renders a
+    percent as `num(v).toFixed(1) + "%"`, so a `yoy_pct` of 12.34 was `round()`ed to 12 and painted
+    "12.0%" — one decimal of a number that HAS one, which reads as precision rather than as loss.
+    ⛔ NOT written as a `_round(v, nd=0)` default argument, deliberately: `round(v, 0)` returns a
+    FLOAT where `round(v)` returns an INT, so every integer column's wire shape would change under
+    an edit that looks purely cosmetic.
+    """
+    return round(v, 2) if isinstance(v, (int, float)) and not isinstance(v, bool) else v
+
+
 # Types a USER may create from the column menu (owner item 7, 2026-07-26). Mirrors
 # customer-grid/types.ts CREATABLE_TYPES; verify_fields_contract.py holds the two in step.
 #   select — a single-select with its own `options` (the "Status" a user wants to add; distinct
@@ -415,6 +432,52 @@ def _clean_formula(raw, valid_keys=None):
     return s
 
 
+def _clean_geocode(raw):
+    """One `geocode` bag → the stored shape, or None (dropped).
+
+    ⭐⭐ W37-T22 (owner item 15 / ruling R4, contract C7). THE ONE validator for the geocode
+    pseudo-kind, called by BOTH field doors: `_field_extras` here (the Odoo grids) and
+    `core/user_tables._clean_field` via `_ag_geocode` (every `ut_*` user database).
+
+    ⛔ IT WAS INLINE IN `_field_extras` UNTIL 2026-08-19 AND THAT IS WHY IT SHIPPED HALF-DONE.
+    `user_tables._clean_field` is a strict allowlist that returns only the bags it NAMES, so a
+    geocode column created on a user database was stored WITHOUT its `{addressField}` — the
+    *"created, named, configured, gone"* failure the `image` type shipped as in wave 19. Extracting
+    it rather than copying the rules is [[one-question-two-normalizers]]: a second copy is how the
+    two doors come to disagree about what a valid bag is.
+
+    ⛔ WHOLE-KEY DROP (the `swipe` construction): a geocode column with no address column is not
+    a degraded column, it is a column no run can ever fill, and the honest state for that is the
+    unconfigured one the client refuses at `canCreate`.
+
+    ⛔ THE FIELD'S `type` IS `text` AND THERE IS NO `geocode` FieldType. The kind is a PSEUDO-KIND
+    in the create picker (the `measure` construction), so `CUSTOM_FIELD_TYPES`, `UT_FIELD_TYPES`,
+    `CREATABLE_TYPES`, the shape/label tables and the cell renderer are all untouched — three
+    parity gates chain over those sets and none permits a partial landing. This is also why the
+    bag takes `format`'s posture and NOT `formula`'s: there is no type to pair it with, so an
+    absent bag is an ordinary text column rather than a refusal.
+
+    ⚠ `addressField` is NOT checked against the table's keys: neither door is given `valid_keys`,
+    and the split this module already draws puts that loss on the surface that RENDERS. The
+    enricher must SAY the address column is gone rather than geocode an empty string.
+    """
+    if not isinstance(raw, dict):
+        return None
+    addr = raw.get("addressField")
+    if not isinstance(addr, str) or not addr.strip():
+        return None
+    out = {"addressField": addr.strip()[:80]}
+    # D-3 — the optional ISO 3166-1 alpha-2 hint, mapped straight onto the geocoder's
+    # `countrycodes` parameter. NORMALISED to upper case and stored only when it is exactly two
+    # letters: absent means "anywhere", and `""` would be that state's second spelling. A
+    # three-letter or numeric code is REFUSED rather than truncated, because a truncated code is
+    # a valid code for a different country.
+    cc = raw.get("country")
+    if isinstance(cc, str) and re.fullmatch(r"[A-Za-z]{2}", cc.strip() or ""):
+        out["country"] = cc.strip().upper()
+    return out
+
+
 def _field_extras(saved, ftype):
     """createdBy / permissions / format / scope — the validated passthrough the created strata
     share (wave 5). `createdBy` is only ever WRITTEN host-side (the handler stamps it); here it
@@ -434,6 +497,27 @@ def _field_extras(saved, ftype):
         out["format"] = fmt
     if saved.get("scope") == "cohort":
         out["scope"] = "cohort"
+    # ── ⭐⭐ W37-T22 (owner item 15 / ruling R4, contract C7): THE GEOCODE COLUMN'S CONFIG ──
+    #
+    # `{addressField}` — which column this one reads. WHOLE-KEY drop (the `swipe` construction):
+    # a geocode column with no address column is not a degraded one, it is a column no run can
+    # ever fill, and the honest state for that is the unconfigured one the client refuses at
+    # `canCreate`.
+    #
+    # ⛔ THE FIELD'S `type` IS `text` AND THERE IS NO `geocode` FieldType. The kind is a PSEUDO-KIND
+    # in the create picker (the `measure` construction), so `CUSTOM_FIELD_TYPES`, `UT_FIELD_TYPES`,
+    # `CREATABLE_TYPES`, the shape/label tables and the cell renderer are all untouched — three
+    # parity gates chain over those sets and none permits a partial landing.
+    # ⚠ `addressField` is NOT checked against this table's keys: `_field_extras` is not given
+    # `valid_keys`, and the split this module already draws puts that loss on the surface that
+    # RENDERS ("what each mode MEANS ... is the client's business"). The enricher must SAY the
+    # address column is gone rather than geocode an empty string.
+    # ⚠ EXTRACTED to `_clean_geocode` 2026-08-19 (/validate-wave, W37-T22 clause 1). The rules
+    # did not change; what changed is that `core/user_tables.py` now reaches THIS function through
+    # `_ag_geocode` instead of carrying a second copy. See `_clean_geocode`'s own note.
+    geo = _clean_geocode(saved.get("geocode"))
+    if geo:
+        out["geocode"] = geo
     corrected_from = saved.get("labelCorrectedFrom")
     correction_id = saved.get("labelCorrectionId")
     if (isinstance(corrected_from, str) and corrected_from.strip()
@@ -752,7 +836,10 @@ def rows_from_pool(pool_rows, fields=None, overlays=None, derived=None):
             if field.get("derived"):
                 continue          # not on the pool row — filled from `derived` below
             v = r.get(k)
-            row[k] = v if field["type"] in {"text", "status", "date"} else _round(v)
+            # D-153 — three roundings, not two: text/status/date pass through verbatim, currency
+            # and pct keep two decimals (`_round2`), everything else stays a whole number.
+            row[k] = v if field["type"] in {"text", "status", "date"} else (
+                _round2(v) if field["type"] in {"currency", "pct"} else _round(v))
         saved = overlays.get(str(pid), {}) or {}
         for field in overlay_fields:
             row[field["key"]] = saved.get(field["key"], "")
@@ -789,6 +876,19 @@ COHORT_FIELD = '__cohort__'
 #: a set op reaching a column leaf would fall through the client engine's switch to "no
 #: narrowing", so keeping the vocabularies apart makes the existing fail-closed drop do the work.
 COHORT_OPS = {'anyOf', 'allOf', 'noneOf'}
+
+#: ⭐⭐ WAVE-37 T26 (owner item 14, contract C4) — THE VIEW-MEMBERSHIP LEAF's reserved
+#: pseudo-column and its operators. Mirrors `customer-grid/types.ts` VIEW_FIELD / VIEW_OPS.
+#:
+#: ⛔ DISJOINT FROM `FILTER_OPS`, for the reason COHORT_OPS is: `matchFilter` answers an operator
+#: it does not know by NOT NARROWING, so an op that reached a column leaf would widen the result
+#: under an authoritative count. Keeping the two vocabularies apart means a column leaf carrying
+#: `inView` is dropped by the same fail-closed path that drops `dropTable`.
+#: ⚠ The leaf names exactly ONE view (singular where a cohort leaf names a set), so there is no
+#: all-or-nothing rule to get wrong here — the id either resolves or the leaf goes.
+VIEW_FIELD = '__view__'
+VIEW_OPS = {'inView', 'notInView'}
+MAX_VIEW_ID = 64
 #: The single-cohort ops this leaf shipped with, kept as PERMANENT aliases and REWRITTEN here:
 #: `is part of [one]` is `is any of [that one]`, so a saved view keeps answering and upgrades the
 #: next time it is written. Mirrors types.ts COHORT_OP_ALIASES.
@@ -912,8 +1012,32 @@ def _clean_rhs(raw, valid_keys):
 #: written into `iconShapes.ts`, and now machine-enforced in BOTH directions by
 #: `verify_icons.py::mode_parity` — offering an unmounted mode is red, and mounting an unoffered
 #: one is red too, so the hold cannot outlive its reason the way wave 27's did).
+#: ⭐⭐ WAVE-37 T20 (owner item 10, ruling R2, contract C2) — 'script', and the reason it lands
+#: here is NOT the one the PRD gives. The PRD says the Custom View is invisible because this set
+#: omits the name so `_clean_display` drops the mode on every write. MEASURED, that write never
+#: happens: a script view is a rail PROJECTION built client-side by
+#: `CustomerGrid.tsx::scriptProjectionView`, its panel is gated on `activeScriptId !== null`
+#: (a row in E's per-database store), there is no `displayMode === "script"` branch at all, and the
+#: autosave effect reads `views.find(...)` while the projections are appended to `railViews` ALONE.
+#: Nothing was ever dropped, because nothing was ever sent.
+#: ⭐ WHAT THE NAME ACTUALLY BUYS is the PRECONDITION for the create door the owner asked for: a
+#: script view can only be offered through the display-mode picker once a view STORED as
+#: `mode: 'script'` survives a round trip, and until this line it could not. The picker entry
+#: itself is W37-T41 (lane E) plus `CREATABLE_MODES`, and `_test/icons.test.ts::HELD_MODES` keeps
+#: the hold with its release condition rewritten to say so.
+#: ⚠ CONTRACT C2 MAKES THIS SET AND `customer-grid/types.ts::DISPLAY_MODES` IDENTICAL NAME FOR
+#: NAME, and `verify_fields_contract.py` now asserts it in BOTH directions. That retires the staged
+#: hold every mode from `timeseries` to `form` was landed with — a client-first name is now RED
+#: rather than merely risky. The protection the hold gave is structural instead: both halves are in
+#: one lane's fence, so they ship in one change, and whether a mode may be CREATED is a separate
+#: question answered by `CREATABLE_MODES` / `HELD_MODES`.
 DISPLAY_MODES = {'grid', 'list', 'calendar', 'kanban', 'map', 'dashboard', 'chart',
-                 'timeseries', 'catalog', 'swipe', 'form'}
+                 'timeseries', 'catalog', 'swipe', 'form', 'script'}
+
+#: W37-T20 (C2) — the cap on `display.script.id`. Script-view ids are minted server-side as
+#: `'sv_' + secrets.token_urlsafe(9)` (`routes_script_views.py::create_script_view`), so ~15 chars;
+#: 64 is a bound on a hostile payload, not an opinion about the format.
+MAX_SCRIPT_ID = 64
 
 #: ⭐⭐ WAVE-29 R7 (owner item 10, contracts C3/C4) — THE FORM INTERFACE's stored spec, at
 #: `views[<id>].config.display.form`. The public door (`aios-web/api/routes_forms.py`) has read
@@ -926,6 +1050,166 @@ DISPLAY_MODES = {'grid', 'list', 'calendar', 'kanban', 'map', 'dashboard', 'char
 #: so one tenant setting its token to another tenant's value would silently receive that tenant's
 #: submissions. The token is minted server-side and lives in a bucket no client write can reach;
 #: `_clean_form` drops any `token` key that arrives here, rather than validating its shape.
+#: ⭐⭐ WAVE-37 T21 (owner items 1/12, rulings R5+R6, contract C3) — THE PER-VIEW CATALOG SPEC,
+#: stored at `views[<id>].config.display.catalog`.
+#:
+#: ⛔⛔ IT IS **`catalog`**, SINGULAR, AND IT IS NOT `catalogs`. Both keys live on `display`, they
+#: are one letter apart, and that is the single most likely mistake anybody touching this file will
+#: make. They are different things and BOTH are live:
+#:   · `catalogs` (wave-18 C6) — a LIST of up to 12 print artifacts, each with its own paper,
+#:     brand and pages of kind cover/intro/section/gallery. Authored CONTENT. UNTOUCHED by T21.
+#:   · `catalog`  (wave-37 C3)  — THIS view's catalog SETTINGS: which column is the picture, which
+#:     is the title (R5: per view, so two catalog views on one database may differ), plus the page
+#:     order and the free-placed items R6 asks for.
+#: Neither replaces the other, and neither validator reads the other's key.
+#:
+#: ⛔ THE MIGRATION IS A RULE ABOUT WHAT THIS FUNCTION MUST **NOT** DO (R6, C3). An item authored
+#: before free placement has no `x`/`y`, and an ABSENT coordinate must read back ABSENT — never
+#: normalised to 0. Defaulting to zero would pile every pre-existing item at the origin, which is
+#: "a catalog that silently loses its layout is a FAIL, not a migration" stated as code. The
+#: RENDERER turns an absent coordinate into flow position N; the host's whole job is to not destroy
+#: the distinction it reads.
+#: ⚠ `w`/`h` carry the OPPOSITE asymmetry, deliberately: a zero WIDTH is an invisible item, so 0
+#: is refused and absent means "the renderer's default size". A zero X is the top-left corner and is
+#: a real, storable position. Two keys of one shape with two rules — the `kanbanClamp` family —
+#: which is why each is written out rather than looped.
+MAX_CATALOG_SECTIONS = 20
+#: A bound on a hostile payload, not an opinion about the renderer's coordinate space: D owns what
+#: the numbers MEAN. Stored to 2 decimals, finer than any print surface resolves.
+MAX_CATALOG_COORD = 10000
+#: The page `order` bound. ABSENT => that page's ARRAY INDEX, and `order` WINS where present; ties
+#: break by array index. Decided HERE rather than left to the renderer, because two readers guessing
+#: differently about page order is exactly the divergence contract C3 exists to close.
+MAX_CATALOG_ORDER = 9999
+
+
+def _clean_catalog_coord(raw, allow_zero):
+    """One free-placement number, or None. `allow_zero` False is the w/h leg (see the header).
+
+    ⛔ THE ROUNDING IS `floor(v * 100 + 0.5) / 100` AND NOT `round(v, 2)`, AND THAT IS THE WHOLE
+    POINT OF THIS FUNCTION EXISTING SEPARATELY. Python's `round` is BANKER'S rounding and
+    JavaScript's `Math.round` is half-up-toward-+Infinity, so the two engines disagree on every
+    exact half: `round(0.125, 2)` is 0.12 here and 0.13 in the browser. One dragged item landing two
+    hundredths apart on the two engines is a `display` object that never compares equal — the
+    silent mirror drift contract C2 exists to prevent, arriving through arithmetic instead of
+    through a missing key. The expression below is `Math.floor(v * 100 + 0.5) / 100` written in
+    Python, evaluated in the same IEEE doubles, so the two agree bit for bit.
+    ⚠ AND AN INTEGRAL RESULT IS EMITTED AS AN `int`: `12.0` serialises as `12.0` in Python and
+    `12` in JSON.stringify, which is one stored value with two spellings.
+    """
+    if isinstance(raw, bool) or not isinstance(raw, (int, float)):
+        return None
+    if raw != raw or raw in (float("inf"), float("-inf")):        # NaN / +-inf
+        return None
+    val = math.floor(float(raw) * 100 + 0.5) / 100
+    if val > MAX_CATALOG_COORD or val < -MAX_CATALOG_COORD:
+        return None
+    if not allow_zero and val <= 0:
+        return None
+    return int(val) if val == int(val) else val
+
+
+def _clean_catalog_item(raw):
+    """One free-placed item: `{code, x?, y?, w?, h?}`. `code` REQUIRED; every coordinate optional.
+
+    Key EMISSION ORDER is fixed and mirrored byte-for-byte by `types.ts::cleanCatalogSpec` — an
+    accepted save has to read back identically on both engines, and this pair is where that is
+    decided.
+    """
+    if not isinstance(raw, dict):
+        return None
+    code = raw.get("code")
+    if not isinstance(code, str) or not code.strip():
+        return None
+    out = {"code": code.strip()[:CATALOG_CODE_MAX]}
+    for key, allow_zero in (("x", True), ("y", True), ("w", False), ("h", False)):
+        val = _clean_catalog_coord(raw.get(key), allow_zero)
+        if val is not None:
+            out[key] = val
+    return out
+
+
+def _clean_catalog_spec(raw, valid_keys):
+    """C3 — `display.catalog`, fail-closed. See the header block above for what it is NOT.
+
+    Field refs follow the `dateField`/`stackField` rule this module already runs: a ref naming a
+    deleted column is dropped INDIVIDUALLY and the renderer falls back to its per-mode default. It
+    never costs the user their pages — the `charts` per-entry-drop precedent, applied to the one
+    payload here that is AUTHORED rather than derived from the rows.
+    """
+    if not isinstance(raw, dict):
+        return None
+    out = {}
+    for ref in ("imageField", "titleField"):
+        if raw.get(ref) in valid_keys:
+            out[ref] = raw[ref]
+    pages_raw = raw.get("pages")
+    pages = []
+    if isinstance(pages_raw, list):
+        # ONE cumulative item budget across the whole spec, spent in page order then section order
+        # — the `_clean_catalogs` construction, so a 40-page catalog cannot smuggle 20,000 items
+        # past a per-page cap.
+        budget = MAX_CATALOG_CODES
+        seen_pages = set()
+        for raw_page in pages_raw:
+            if len(pages) >= MAX_CATALOG_PAGES:
+                break
+            if not isinstance(raw_page, dict):
+                continue
+            pid = str(raw_page.get("id") or "").strip()[:CATALOG_ID_MAX]
+            if not pid or pid in seen_pages:
+                continue
+            seen_pages.add(pid)
+            page = {"id": pid}
+            order = raw_page.get("order")
+            if (isinstance(order, int) and not isinstance(order, bool)
+                    and 0 <= order <= MAX_CATALOG_ORDER):
+                page["order"] = order
+            sections_raw = raw_page.get("sections")
+            sections = []
+            if isinstance(sections_raw, list):
+                seen_sections = set()
+                for raw_section in sections_raw:
+                    if len(sections) >= MAX_CATALOG_SECTIONS:
+                        break
+                    if not isinstance(raw_section, dict):
+                        continue
+                    sid = str(raw_section.get("id") or "").strip()[:CATALOG_ID_MAX]
+                    if not sid or sid in seen_sections:
+                        continue
+                    seen_sections.add(sid)
+                    section = {"id": sid}
+                    items_raw = raw_section.get("items")
+                    items = []
+                    if isinstance(items_raw, list) and budget > 0:
+                        for raw_item in items_raw:
+                            item = _clean_catalog_item(raw_item)
+                            if item is None:
+                                continue
+                            items.append(item)
+                            budget -= 1
+                            if budget <= 0:
+                                break
+                    # ⚠ NOT de-duplicated by `code`. The same product legitimately appears twice in
+                    # one section at two positions — that is what free placement IS — and wave-18's
+                    # "deduped WITHIN a page" rule was written for a LISTING, where a repeat is a
+                    # mistake. Here it is the feature.
+                    if items:
+                        section["items"] = items
+                    sections.append(section)
+            # An EMPTY section is KEPT: a person adds a New Section and then drags into it, and
+            # dropping it would delete the thing they just made, between two autosaves.
+            if sections:
+                page["sections"] = sections
+            pages.append(page)
+    if pages:
+        out["pages"] = pages
+    # A spec that reduces to nothing is DROPPED, never stored as `{}`. "No image field, no title
+    # field, no pages" IS the unconfigured state, and `{}` would be its second spelling — the
+    # no-churn law every literal-only key in `_clean_display` follows.
+    return out or None
+
+
 FORM_ACCESS = ('public', 'emails')
 MAX_FORM_FIELDS = 60
 MAX_FORM_EMAILS = 200
@@ -1373,7 +1657,11 @@ def _clean_display(raw, valid_keys):
     # saved 'dashboard' view reads back as 'chart' from here on; nothing writes 'dashboard'.
     mode = _LEGACY_MODES.get(mode, mode)
     out = {'mode': mode}
-    for ref in ('dateField', 'stackField', 'titleField', 'colorField', 'sizeField'):
+    # ⭐ W37-T28 (owner item 15) — `coordField`: ONE column holding `"lat,lon"`, so a map is no
+    # longer a customers-only feature. It joins this loop rather than getting a clause of its own
+    # because it IS a field ref with the same drop-if-deleted rule; `customer-grid/types.ts`
+    # gains it in the SAME change, which is contract C2's whole point.
+    for ref in ('dateField', 'stackField', 'titleField', 'colorField', 'sizeField', 'coordField'):
         if raw.get(ref) in valid_keys:
             out[ref] = raw[ref]
     # ── C-DISP (wave 2026-08-02) ─────────────────────────────────────────────────────────
@@ -1508,6 +1796,12 @@ def _clean_display(raw, valid_keys):
     catalogs = _clean_catalogs(raw.get('catalogs'), valid_keys)
     if catalogs:
         out['catalogs'] = catalogs
+    # ── ⭐⭐ WAVE-37 C3 (T21) — `catalog`, SINGULAR, and it is NOT the line above it. See the
+    # header on `_clean_catalog_spec` for the two-keys-one-letter-apart warning; this call site is
+    # where a reader is most likely to "fix" one into the other.
+    catalog = _clean_catalog_spec(raw.get('catalog'), valid_keys)
+    if catalog:
+        out['catalog'] = catalog
     # ── ⭐ WAVE-27 C3 (item 8 / R2): the swipe binding ────────────────────────────────────
     # `{fieldKey, leftOption, rightOption}` — WHOLE-KEY drop, never a partial one, and that
     # asymmetry against `charts`/`calendarMetrics` above is the point rather than an oversight.
@@ -1536,6 +1830,26 @@ def _clean_display(raw, valid_keys):
             # `kanbanClamp` law) wearing a control that promises a choice.
             if left and right and left.casefold() != right.casefold():
                 out['swipe'] = {'fieldKey': f_key, 'leftOption': left, 'rightOption': right}
+    # ── ⭐⭐ WAVE-37 T20 (owner item 10 / R2, contract C2): WHICH SCRIPT THIS VIEW RENDERS ──
+    #
+    # `{id}` — the row in E's per-database script store (`/api/v1/script-views`) whose source this
+    # view draws. WHOLE-KEY drop, the `swipe` construction rather than the `charts` one: a script
+    # view with no id is not a degraded script view, it is a panel with nothing to run, and the
+    # honest state for that is the unconfigured one the client already has a surface for.
+    #
+    # ⛔ THE ID IS DELIBERATELY NOT CHECKED AGAINST `valid_keys`, AND THAT IS NOT AN OVERSIGHT.
+    # `valid_keys` is this table's FIELD keys; a script id names a record in a DIFFERENT store that
+    # this function cannot reach. So the host bounds the shape and nothing else, and the renderer
+    # owns the one loss this is blind to — the script row was deleted — which it must SHOW rather
+    # than fall back to another script (the `viewModes.tsx` house rule `_clean_swipe`'s note cites).
+    # ⚠ Mirrored key-for-key by `customer-grid/types.ts::cleanDisplay`. That file rebuilds the
+    # config key by key on every autosave, so a key accepted HERE and unknown THERE is erased on the
+    # next column resize — which is the half of the round trip this docstring's W33 note warns about.
+    script = raw.get('script')
+    if isinstance(script, dict):
+        s_id = script.get('id')
+        if isinstance(s_id, str) and s_id.strip():
+            out['script'] = {'id': s_id.strip()[:MAX_SCRIPT_ID]}
     # ── ⭐⭐ WAVE-29 R7 (item 10): the FORM spec — see `_clean_form` for why the token is not here.
     form = _clean_form(raw.get('form'), valid_keys)
     if form:
@@ -1743,7 +2057,59 @@ def clean_item_folders(raw, folders, valid_ids):
     return out
 
 
-def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None):
+def view_refs_of(nodes):
+    """C4 — every view id a tree REFERS to, deduped, in order. Mirrors `types.ts::viewRefsOf`.
+
+    ⚠ An INACTIVE leaf (no view chosen yet) is not a reference, on both engines: counting one
+    would refuse a save the moment somebody opened the condition and had not picked anything.
+    """
+    out = []
+    for node in nodes or []:
+        if not isinstance(node, dict):
+            continue
+        if 'children' in node:
+            for vid in view_refs_of(node.get('children')):
+                if vid not in out:
+                    out.append(vid)
+            continue
+        if node.get('colId') != VIEW_FIELD:
+            continue
+        vid = str(node.get('value') or '').strip()[:MAX_VIEW_ID]
+        if vid and vid not in out:
+            out.append(vid)
+    return out
+
+
+def view_filter_cycle(view_id, nodes, filters_of):
+    """⭐⭐ W37-T26 / C4 — THE CYCLE REFUSAL's host half. Mirrors `types.ts::viewFilterCycle`.
+
+    View X filtered on "is in View Y" where Y is filtered on X cannot be resolved by anything:
+    X needs Y needs X. Returns the CYCLE PATH (ids, starting and ending at `view_id`) or None.
+
+    ⛔ THE CLIENT REFUSES THE SAME SHAPE AND THAT IS NOT DUPLICATION. The browser's guard is what
+    a PERSON sees and is the only one that can explain itself; this one is what makes the rule true
+    for a caller that POSTs a view directly, which is every guard-in-the-browser's blind spot.
+    ⚠ A view referring to ITSELF is a cycle of length one and is caught by the same walk — also
+    the case a person reaches most easily, by duplicating a view.
+    """
+    def walk(current, path, seen):
+        refs = view_refs_of(nodes if current == view_id else filters_of(current))
+        for nxt in refs:
+            if nxt == view_id:
+                return path + [nxt]
+            if nxt in seen:
+                continue
+            seen.add(nxt)
+            found = walk(nxt, path + [nxt], seen)
+            if found:
+                return found
+        return None
+
+    return walk(view_id, [view_id], {view_id})
+
+
+def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None,
+                      visible_view_ids=None):
     """Recursively validate an UNTRUSTED filter tree (conditions + nested groups).
 
     Returns a clean tree of leaf conditions ({colId, op, value, value2}) and
@@ -1762,6 +2128,14 @@ def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None):
     condition that can only match nothing, so `List is not [deleted]` would show an empty table
     forever with no way to tell why. `None` means this host has no cohorts, and then every
     cohort leaf is dropped: fail-closed, like every other unknown key.
+
+    ⭐⭐ W37-T26 (C4) — `visible_view_ids` is the same parameter one leaf over: the views this
+    caller may name in a `__view__` membership leaf. A leaf naming anything else is DROPPED here
+    for the identical reason, and `None` (this host has no views to offer) drops every one.
+    ⚠ DEFAULTS TO `None` SO EVERY EXISTING CALLER IS BYTE-IDENTICAL. Three callers pass nothing
+    (`routes_admin`, `routes_query` twice) and each of them is a surface with no saved-view
+    vocabulary of its own; under the fail-closed rule they drop the leaf, which is correct rather
+    than merely safe.
     """
     if budget is None:
         budget = [MAX_FILTER_NODES]
@@ -1776,7 +2150,7 @@ def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None):
                 continue                                       # too deep -> drop
             budget[0] -= 1
             children = clean_filter_tree(node['children'], valid_keys,
-                                        depth + 1, budget, cohort_ids)
+                                        depth + 1, budget, cohort_ids, visible_view_ids)
             if children:
                 out.append({'conj': 'or' if node.get('conj') == 'or' else 'and',
                             'children': children})
@@ -1793,6 +2167,21 @@ def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None):
                 out.append({'colId': COHORT_FIELD, 'op': op,
                             'value': ','.join(named), 'value2': ''})
             continue
+        if node.get('colId') == VIEW_FIELD:                   # C4: a view-membership leaf
+            # ⛔ THE SAME ALL-OR-NOTHING THE COHORT ARM ABOVE APPLIES, AND FOR THE SAME REASON.
+            # A leaf naming a view this caller cannot see is DROPPED rather than kept, because a
+            # kept one can only ever match nothing: `View is not [a view you cannot see]` would
+            # show an empty table forever with no way to tell why. Dropping it puts the view back
+            # in its honest unfiltered state, which is what `clean_filter_tree`'s own docstring
+            # already promises for cohorts.
+            # ⚠ `visible_views` is what the caller passes; `None` means this host does not know,
+            # and then EVERY view leaf is dropped — fail-closed, like every other unknown key.
+            v_op = node.get('op')
+            v_id = str(node.get('value') or '').strip()[:MAX_VIEW_ID]
+            if v_op in VIEW_OPS and v_id and v_id in (visible_view_ids or ()):
+                budget[0] -= 1
+                out.append({'colId': VIEW_FIELD, 'op': v_op, 'value': v_id, 'value2': ''})
+            continue
         if node.get('colId') in valid_keys and node.get('op') in FILTER_OPS:
             budget[0] -= 1
             # `or ''` would be wrong here: it maps every FALSY value to '', and '' is the

platform/aios_grid_fields.json

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

platform/core/grid_events.py

@@ -801,9 +801,39 @@ def handle_one(event, ctx):
         # else is dropped here. Leaving it in would persist a condition the engine can only
         # answer with "nothing", so `Cohort is not [a list I deleted]` would show an empty table
         # forever with nothing on screen explaining why.
+        # ⭐⭐ W37-T26 / CONTRACT C4 — `visible_view_ids` is the same PERMISSION list one leaf over:
+        # a `__view__` membership leaf naming a view this caller cannot see is dropped here, for
+        # the identical reason the cohort line above gives. Without it the arm is fail-closed and
+        # every view leaf is dropped on save, so the condition would vanish on the next read —
+        # D-90's shape exactly.
+        # ⚠ `ctx.visible_views` is already populated (`routes_grid.py` passes it, `:714` reads it),
+        # so this needs no new plumbing; it is the value nobody had handed to the validator.
+        # ⚠ Edited by lane C, not this file's owner: `platform/core/grid_events.py` is in NO fence
+        # and lane C was the last session open. See `mailbox/C.md` NOTE C-24.
+        _view_ids = {str(v.get('id')) for v in (visible_views or ())
+                     if isinstance(v, dict) and v.get('id')}
+        # ⛔⛔ THE CYCLE REFUSAL'S HOST HALF (C4), and it is the ticket's `done-when` rather than a
+        # guard bolted on afterwards. View X filtered on "is in View Y" where Y is filtered on X
+        # cannot be resolved by anything: X needs Y needs X. The browser refuses it too, with a
+        # sentence a person reads; this one is what makes the rule true for a caller that POSTs a
+        # view directly, which is every guard-in-the-browser's blind spot.
+        # ⚠ REFUSED, NOT REPAIRED. Dropping the offending leaf would save a view the person did not
+        # write and leave the panel showing a condition the config does not carry.
+        _cycle = _ag.view_filter_cycle(
+            view_id, cfg.get('filters'),
+            lambda vid: next((v.get('config', {}).get('filters')
+                              for v in (visible_views or ())
+                              if isinstance(v, dict) and str(v.get('id')) == vid), None))
+        if _cycle:
+            _refuse(ctx, 'view_cycle',
+                    'that would make a loop: ' + ' refers to '.join(_cycle) +
+                    '. A view cannot filter on a view that filters on it, because neither can '
+                    'be worked out without the other.', view_id)
+            return False
         filters = _ag.clean_filter_tree(cfg.get('filters'),
                                         valid_keys | set(measure_keys),
-                                        cohort_ids=set(cohort_ids))
+                                        cohort_ids=set(cohort_ids),
+                                        visible_view_ids=_view_ids)
         sorts = []
         for rule in list(cfg.get('sorts') or [])[:20]:
             if (isinstance(rule, dict) and rule.get('colId') in valid_keys

platform/core/user_tables.py

@@ -732,6 +732,24 @@ def _ag_formula(raw):
     return _agf._clean_formula(raw)
 
 
+def _ag_geocode(raw):
+    """`aios_grid._clean_geocode`, reached exactly the way `_ag_formula` reaches its validator.
+
+    ⭐⭐ W37-T22 clause 1, landed by /validate-wave 2026-08-19. The geocode PSEUDO-KIND was
+    offered in `ColumnMenu` and cleaned in `aios_grid._field_extras`, but THIS module — the
+    allowlist every `ut_*` create and patch goes through — named no `geocode` arm, so the bag was
+    stripped on every user database and the kind had to be gated OFF there. That gap is what made
+    the ticket's *"the kind is offered on ANY database that has a text field"* clause false.
+
+    ⚠ ONE call site for the function-local import, shared by BOTH field doors (`clean_fields` and
+    `_clean_field`), for the reason `_ag_formula` states: `core` must not import `aios_grid` at
+    module level, and a third and fourth copy of `import aios_grid as _agX` is how one of them
+    ends up calling a different validator.
+    """
+    import aios_grid as _agg
+    return _agg._clean_geocode(raw)
+
+
 #: Display formats a field may declare. ⛔ DISPLAY ONLY — none of these touches the stored value,
 #: which stays the scalar the fold or the mapper wrote. That separation is the whole safety of the
 #: feature: a `thousands` setting can never make a number wrong, only easier to read.
@@ -934,6 +952,16 @@ def clean_fields(raw):
                 entry['aiEnrich'] = ae
                 # C3: derived, never typed beside the config. Same call as the other door.
                 entry['automation'] = _field_agent_binding(entry)
+        # ⭐⭐ W37-T22 (R4 / C7) — THE GEOCODE BAG RIDES THIS DOOR TOO, written in the SAME change
+        # as `_clean_field`'s arm rather than a wave later. That is the only difference between
+        # this entry and the six above it (`pinned`, `code`, `link`/`rollup`, `formula`,
+        # `aiEnrich`), every one of which was a bag this validator dropped until somebody found a
+        # column that rendered and computed nothing forever.
+        # ⚠ NO type/bag pairing: geocode is a pseudo-kind on a `text` column (see `_clean_geocode`).
+        if entry is not None:
+            geo = (_ag_geocode(f.get('geocode')) if f.get('geocode') is not None else None)
+            if geo and ftype == 'text':
+                entry['geocode'] = geo
         if entry is None:
             seen.discard(key)
             continue
@@ -2255,6 +2283,24 @@ def _clean_field(raw, previous=None):
     # a `field_agent` bag that disagrees with the column. Every OTHER automation bag is untouched.
     if ftype == 'ai_enrich':
         out['automation'] = _field_agent_binding(out)
+    # ⭐⭐ W37-T22 (R4 / C7) — THE GEOCODE PSEUDO-KIND'S BAG, added 2026-08-19 by /validate-wave.
+    # Posture is `format`'s and NOT `formula`'s, and that is the whole design: geocode has no
+    # FieldType to pair with (the column's `type` is `text`), so an absent bag is an ordinary text
+    # column rather than a refusal. Enforcing a pairing here would refuse every text column in
+    # every user database.
+    # ⚠ `'geocode' in raw` rather than `raw.get('geocode')`, exactly like `format` and
+    # `description`: an explicit `{}`/None CLEARS the address column while OMITTING the key keeps
+    # what is stored. A PATCH that sends only a label must not silently unconfigure the column —
+    # that is the same rule `agg` and `optionColors` are written for.
+    # ⚠ Inheritance is guarded on `ftype == 'text'` for the reason `prev_type == ftype` guards
+    # `link`/`rollup`/`formula`: retyping a geocode column to a number must not resurrect an
+    # address binding through `prev` that nothing will ever read again.
+    geocode_raw = (raw.get('geocode') if 'geocode' in raw
+                   else (prev.get('geocode') if ftype == 'text' else None))
+    if geocode_raw is not None:
+        geo = _ag_geocode(geocode_raw)
+        if geo and ftype == 'text':
+            out['geocode'] = geo
     return out
 
 

platform/core/users.py

@@ -1,525 +1,532 @@
-"""Per-user accounts for the platform, persisted in the HF Dataset store (users.json).
-
-Passwords are salted + PBKDF2-HMAC-SHA256 (200k iterations) — never stored or logged in plaintext.
-A bootstrap 'admin' account is seeded from APP_PASSWORD so the owner can always log in and create
-users; APP_PASSWORD also works as an emergency master for 'admin' if the registry is unreachable.
-
-Each account carries BU access ('all' or a list of team-ids [5=Fisch, 6=Royal]) which drives
-allowed_bus() — the basis for per-Business-Unit permissioning (a Royal-only user never sees Fisch).
-"""
-import os
-import hmac
-import hashlib
-import secrets
-
-import core.store as store
-
-BU_LABELS = {5: 'Fisch', 6: 'Royal'}
-_ITER = 200_000
-
-#: Wave 15 C-PERM — the explicit-resolution marker. Mirrors `core.perm_scope.PERMS_VERSION`;
-#: kept as a literal here so `users` does not import the permission layer it is read by.
-PERMS_VERSION = 1
-
-
-def _hash(pw, salt):
-    return hashlib.pbkdf2_hmac('sha256', str(pw).encode('utf-8'), bytes.fromhex(salt), _ITER).hex()
-
-
-def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
-            perms=None, tenant='royal-imports', platform_admin=False):
-    salt = secrets.token_hex(16)
-    rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
-           'bus': bus, 'active': active, 'modules': modules,
-           'agent': agent or None, 'email': email or None,
-           # Wave 18 (C1-TENANT, R1): the account's COMPANY. Absent == 'royal-imports' on every
-           # pre-wave record — no migration. Login binds the session to THIS value; the posted
-           # tenant field can hint but never override it.
-           'tenant': str(tenant or 'royal-imports').strip().lower()}
-    if platform_admin is True:
-        # Wave 19 (R3): the PLATFORM-operator flag — half of `core.platform_admin`'s double lock
-        # (the other half is `tenant == 'loopable'`). Written ONLY for True, so every record that
-        # is not deliberately promoted keeps its pre-wave shape and answers False by absence.
-        # There is no UI writer and there never should be: it is set by provisioning, on purpose.
-        rec['platform_admin'] = True
-    if perms is not None:
-        # Wave 15 C-PERM. A record written WITH perms is migrated by construction — the marker
-        # and the block are set together, here, so no writer can create one without the other.
-        # (`core.perm_scope` reads an unmarked record as legacy, so a block without its marker
-        # would be silently ignored; a marker without a block would deny everything.)
-        rec['perms'] = perms
-        rec['perms_v'] = PERMS_VERSION
-    return rec
-
-
-def registry():
-    return store.get('users')
-
-
-def ensure_bootstrap():
-    """Seed an 'admin' account from APP_PASSWORD ONLY on a truly fresh store (no users file yet).
-    Idempotent; no-op if the store is unavailable (the app then falls back to the master-password
-    path in verify()).
-
-    Critically, this NEVER overwrites an existing registry: it seeds only when store.exists('users')
-    is definitively False. A transient read failure at startup used to return {} and make this
-    re-seed just {admin} over the real accounts — that is the bug that wiped users on restart."""
-    if not store.available():
-        return
-    if store.exists('users'):          # present, or uncertain -> never clobber
-        return
-    try:
-        reg = store.get('users', fresh=True)
-    except Exception:
-        return
-    if reg:
-        return
-    master = os.environ.get('APP_PASSWORD', '')
-    if not master:
-        return
-    try:
-        store.put('users', {'admin': _record(master, 'Administrator', 'admin', 'all')})
-    except Exception:
-        pass
-
-
-def _public(username, u):
-    return {'username': username, 'name': u.get('name', username),
-            'role': u.get('role', 'user'), 'bus': u.get('bus', 'all'),
-            'modules': u.get('modules', 'all'),
-            'agent': u.get('agent'), 'email': u.get('email'),
-            # Wave 18 (C1-TENANT): the session's tenant binding travels on the projection or it
-            # does not travel — the same rule the perms block states below.
-            'tenant': str(u.get('tenant') or 'royal-imports').strip().lower(),
-            # Wave 14 C-AVATAR: the profile photo is public-safe by definition (it is served
-            # to every grid session via the workspace map); without it here the API session's
-            # user record silently drops it and /me can never show your own photo.
-            'avatar': u.get('avatar') or None,
-            # ⛔ WAVE 15 C-PERM — THE WALL TRAVELS ON THIS PROJECTION OR IT DOES NOT TRAVEL.
-            # `deps._user_for` builds every API session from `_public()`, so a `perms` block
-            # dropped here is a restricted account served as an unrestricted one — silently, on
-            # every route, with nothing to notice. `perms_v` must ride ALONG WITH it and for the
-            # same reason inverted: the marker without the block denies everything, the block
-            # without the marker is ignored. Two keys, one fact, never separated.
-            # `verify_api` asserts a restricted user's SESSION OBJECT carries both, at the mount
-            # rather than by grep — a projection is exactly the kind of wiring that looks
-            # present in three files and is absent in the one that runs.
-            **({'perms': u['perms']} if isinstance(u.get('perms'), dict) else {}),
-            **({'perms_v': int(u['perms_v'] or 0)} if u.get('perms_v') else {}),
-            # ⛔ WAVE 19 R3 — THE SAME RULE, ON A NEW FIELD. `deps._user_for` builds every API
-            # session from this projection, so the platform-admin flag travels here or
-            # `core.platform_admin.is_platform_admin(session.user)` is blind and the Loopable
-            # admin plane 403s its own operator. Carried ONLY when the record says True, so a
-            # session dict for any other account is byte-identical to its pre-wave shape.
-            # Not a client leak: `routes_auth._public_user` is a whitelist projection and does
-            # not name this key, so it reaches no browser via /login or /me — the client's copy
-            # is the separate `platformAdmin` bool on GET /settings, which is derived from this.
-            **({'platform_admin': True} if u.get('platform_admin') is True else {}),
-            'epoch': int(u.get('epoch') or 0)}
-
-
-# ------------------------------------------------------------------ session revocation (X3)
-# The API's session cookie is SIGNED AND STATELESS: there is no server-side session table to
-# delete from, so "log this user out everywhere" needs a number that lives with the account. The
-# cookie carries the epoch it was minted under; bumping the account's epoch makes every
-# outstanding cookie for that user fail verification on its next use. Absent == 0, so every
-# record written before this wave is valid without a migration.
-def epoch(username):
-    """The current session epoch for `username`. None when there is no such account.
-
-    None is NOT 0. 0 is "this account exists and has never been revoked"; None is "no record" —
-    which the session verifier must treat as a reason to refuse, not as a default to compare
-    against. (The APP_PASSWORD emergency-master admin has no record at all; the verifier handles
-    that case explicitly rather than inventing an epoch for it here.)
-    """
-    username = (username or '').strip().lower()
-    try:
-        u = (store.get('users') or {}).get(username)
-    except Exception:
-        return None
-    return int((u or {}).get('epoch') or 0) if u else None
-
-
-def bump_epoch(username):
-    """Revoke every outstanding API session for this account."""
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            u['epoch'] = int(u.get('epoch') or 0) + 1
-        return reg
-    store.update('users', _set)
-
-
-def verify(username, pw):
-    """Return a public user dict on success, else None. APP_PASSWORD is an emergency master for the
-    'admin' login even if the store is unreachable, so the owner is never locked out."""
-    username = (username or '').strip().lower()
-    if not username or not pw:
-        return None
-    master = os.environ.get('APP_PASSWORD', '')
-    try:
-        # read fresh so accounts created moments ago (UI or out-of-band) are recognised at once
-        reg = store.get('users', fresh=True)
-    except Exception:
-        reg = {}
-    u = reg.get(username)
-    if u is None and '@' in username:
-        # Wave 18 (R1): the login box takes a username OR an email — admin@nurilab.id signs in
-        # without knowing the slug an admin chose. First case-insensitive email match wins;
-        # ambiguity is an admin data problem, not a login feature.
-        for k, r in reg.items():
-            if isinstance(r, dict) and str(r.get('email') or '').strip().lower() == username:
-                username, u = k, r
-                break
-    if u and u.get('active', True) and hmac.compare_digest(_hash(pw, u['salt']), u['hash']):
-        return _public(username, u)
-    # emergency master: admin + APP_PASSWORD always works (covers first run / store outage)
-    if username == 'admin' and master and hmac.compare_digest(str(pw), master):
-        # ⚠ CARRY THE RECORD'S CURRENT EPOCH when there is a record to read, so the session cookie
-        # the API mints from this dict AGREES with the stored account.
-        #
-        # This is not what stops the emergency lockout — `deps._user_for`'s master fallback does
-        # that, and a negative control confirmed the lockout is gone with or without this line.
-        # What it fixes is subtler and is a SCOPE question: a cookie whose epoch disagrees with the
-        # record falls through to that master fallback, which hands back a SYNTHETIC identity
-        # (`bus: 'all'`, `modules: 'all'`). An admin whose record narrows either field would
-        # therefore be silently WIDENED to consolidated, all-module access for the life of that
-        # session. Matching the epoch means the record branch wins and the account's real scope
-        # applies, leaving the master fallback as the true last resort it is meant to be.
-        # 0 when the store is unreachable, which is the case this branch was written for.
-        return {'username': 'admin', 'name': 'Administrator', 'role': 'admin', 'bus': 'all',
-                'modules': 'all', 'epoch': int((reg.get('admin') or {}).get('epoch') or 0)}
-    return None
-
-
-def create_user(username, pw, name, role='user', bus='all', modules='all',
-                agent=None, email=None, tenant=None, platform_admin=None):
-    """Create — or, from app.py's dialog, OVERWRITE — an account.
-
-    ⛔ X3: OVERWRITING AN ACCOUNT MUST NOT RESURRECT ITS OLD SESSIONS. `_record()` builds a fresh
-    record with no `epoch` key, i.e. absent == 0. So re-saving an existing username used to reset
-    the epoch to 0, and every cookie minted before that account's last password rotation started
-    verifying again — a silent un-revocation. `app.py`'s "Add / update a user" calls this function
-    for BOTH add and update, so the hole was reachable from the shipped UI.
-
-    Epoch revocation is only ever as strong as the NARROWEST write path that touches the record, so
-    the carry-and-bump lives here rather than in each caller: an overwrite is at least as
-    session-invalidating as a password change, and it usually IS one.
-    """
-    username = (username or '').strip().lower()
-    if not username or not pw:
-        raise ValueError('username and password are required')
-
-    def _add(reg):
-        prior = reg.get(username) or {}
-        rec = _record(pw, name or username, role, bus, modules=modules,
-                      agent=agent, email=email,
-                      # An overwrite that names no tenant KEEPS the account's company — a
-                      # rename must never quietly move a user between tenants.
-                      tenant=(tenant or prior.get('tenant') or 'royal-imports'),
-                      # Wave 19 (R3): CARRIED, for the same reason `epoch` is carried below —
-                      # `_record` builds a FRESH record, so re-running the provisioner (it is
-                      # documented as idempotent) or saving an account through this function
-                      # would silently DEMOTE a platform admin and lock the operator out of
-                      # their own plane. None = leave as it was; True/False = set it deliberately.
-                      platform_admin=(prior.get('platform_admin') is True
-                                      if platform_admin is None else platform_admin is True))
-        if prior:
-            rec['epoch'] = int(prior.get('epoch') or 0) + 1
-        reg[username] = rec
-        return reg
-    store.update('users', _add)
-
-
-def set_password(username, pw):
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            u['salt'] = secrets.token_hex(16)
-            u['hash'] = _hash(pw, u['salt'])
-            # X3: a password change revokes every outstanding API session for the account. Bumped
-            # INSIDE the same read-modify-write as the hash so the two can never disagree — a
-            # separate update() could rotate the password and leave old cookies live if the second
-            # write failed.
-            u['epoch'] = int(u.get('epoch') or 0) + 1
-        return reg
-    store.update('users', _set)
-
-
-def set_active(username, active):
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        if username in reg:
-            reg[username]['active'] = bool(active)
-            # X3: DEACTIVATION must kill live sessions, not just future logins — otherwise a
-            # disabled account keeps working until its cookie expires. Bumped on reactivation too:
-            # cheap, and it means a re-enabled account never resurrects a stale cookie.
-            reg[username]['epoch'] = int(reg[username].get('epoch') or 0) + 1
-        return reg
-    store.update('users', _set)
-
-
-def set_platform_admin(username, on):
-    """Promote/demote a PLATFORM administrator (wave 19, R3) without touching the password.
-
-    The narrow write, deliberately: `create_user` is the destructive path (fresh salt, fresh
-    hash, bumped epoch) and promoting somebody should not sign them out or rotate a credential.
-    Cleared by REMOVING the key, so a demoted record goes back to its pre-wave shape rather than
-    carrying a `False` that reads as "somebody considered this".
-
-    ⚠ This is the flag only. It grants nothing on its own — `core.platform_admin` also demands
-    the `loopable` tenant, and there is no code path anywhere that moves an account between
-    tenants, which is what makes the second lock hold.
-    """
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            if on is True:
-                u['platform_admin'] = True
-            else:
-                u.pop('platform_admin', None)
-        return reg
-    store.update('users', _set)
-
-
-# ------------------------------------------------------------------ activity stamps (wave 19 R4)
-# "When did this account last sign in, and is anyone actually using it?" — the two questions the
-# Loopable admin plane exists to answer and that NOTHING in the product could answer before this
-# wave (there is no login history, no audit log, no request log anywhere).
-#
-# ⛔ THIS IS THE FIRST HIGH-FREQUENCY WRITER `users.json` HAS EVER HAD, and that bucket also holds
-# every password hash, `active`, `epoch` and the permission blocks. Three rules follow, and the
-# second one is a correctness rule, not a performance one:
-#
-#   1. **In-place mutation of ONE key.** Never `_record()`, never a whole-record replace: a stamp
-#      that rebuilt the record would reset the salt/hash (locking the user out) or the epoch
-#      (silently un-revoking every cookie ever minted for them). `set_password`'s docstring
-#      explains why that class of bug is worth naming out loud.
-#
-#   2. **SYNCHRONOUS FLUSH — deliberately NOT the async path, and this reverses my first draft.**
-#      `store.update(flush='async')` rebases on the PROCESS CACHE once a key is `_owned`
-#      (`core/store.py:284`) and its worker uploads that whole cached blob. For a
-#      table-workspace key, written by one process, that is exactly right. For `users` it is a
-#      silent-revert machine: tenant #0's Streamlit host writes the SAME file, so an API process
-#      holding a cache from an hour ago would, on its next stamp, upload a blob in which a
-#      password rotation or a deactivation performed in the other host simply never happened.
-#      A telemetry stamp must not be able to resurrect a disabled account. `flush='sync'` does a
-#      FRESH strict read inside the store's lock and then uploads, which is the same discipline
-#      every other `users` writer already uses.
-#
-#   3. **OFF THE REQUEST THREAD, so rule 2 costs nothing.** A sync commit is a hub round-trip, and
-#      neither a sign-in nor a random request an hour later should wait for it. Each stamp runs on
-#      a short-lived daemon thread; `flush_stamps()` is how a test or a shutdown waits for them.
-#      Everything is fail-silent: a stamp is telemetry and may never turn a good login into a
-#      failed one — the plane shows an honest "never" instead.
-def _now_iso():
-    import datetime as _dt
-    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec='seconds')
-
-
-#: Live stamp threads, so `flush_stamps()` can join them. Bounded by construction — one thread per
-#: stamp, and a stamp is at most one per login plus one per account per hour per process.
-_STAMPS = []
-_STAMPS_LOCK = __import__('threading').Lock()
-
-
-def _stamp(username, fields):
-    """Merge `fields` into ONE account record, on a background thread, with a fresh read."""
-    username = (username or '').strip().lower()
-    if not username or not fields:
-        return None
-
-    def _set(reg):
-        u = reg.get(username)
-        if isinstance(u, dict):
-            u.update(fields)
-        return reg
-
-    def _work():
-        try:
-            store.update('users', _set)          # sync: fresh strict read + blocking upload
-        except Exception:
-            pass                                  # a lost stamp is a lost stamp, never an error
-    import threading
-    t = threading.Thread(target=_work, daemon=True, name=f'user-stamp:{username}')
-    with _STAMPS_LOCK:
-        _STAMPS[:] = [x for x in _STAMPS if x.is_alive()]
-        _STAMPS.append(t)
-    t.start()
-    return t
-
-
-def flush_stamps(timeout=10.0):
-    """Block until outstanding stamp writes have been applied. For gates and shutdown hooks —
-    the app never needs it, exactly like `core.store.flush`."""
-    with _STAMPS_LOCK:
-        pending = list(_STAMPS)
-    for t in pending:
-        t.join(timeout=timeout)
-    return all(not t.is_alive() for t in pending)
-
-
-def touch_login(username, when=None):
-    """Stamp `last_login` (ISO-8601, UTC, OFFSET-BEARING) on a SUCCESSFUL login.
-
-    `username` must be the RESOLVED account key, not what the person typed: `verify()` accepts an
-    email address and resolves it to the registry key, so stamping the typed identifier would
-    write a stamp onto a key that does not exist and create a phantom account in the registry.
-
-    `last_active` rides along — signing in IS activity, and setting both here means the plane's
-    two columns agree the moment somebody logs in rather than an hour later.
-    """
-    stamp = when or _now_iso()
-    return _stamp(username, {'last_login': stamp, 'last_active': stamp})
-
-
-def touch_active(username, when=None):
-    """Stamp `last_active` — "this session did something". Throttled BY THE CALLER (`deps.py`
-    holds a process-local last-seen map), so this is not a store round-trip per request."""
-    return _stamp(username, {'last_active': when or _now_iso()})
-
-
-def set_access(username, role=None, bus=None, modules=None, agent=None, email=None,
-               name=None, perms=None):
-    """Update access fields. agent/email: pass '' to clear, None to leave unchanged —
-    the user↔agent link scopes the Customer List page / digests to that agent's book.
-
-    `name` follows the same None-means-unchanged idiom. It is here because it had no setter at all:
-    a display name could previously only be changed by re-creating the record through
-    `create_user`, i.e. by also resetting the password (and, before the fix above, the session
-    epoch). Y4's `PATCH {name?}` needs the narrow write, not the destructive one."""
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            if name is not None:
-                u['name'] = name
-            if role is not None:
-                u['role'] = role
-            if bus is not None:
-                u['bus'] = bus
-            if modules is not None:
-                u['modules'] = modules
-            if agent is not None:
-                u['agent'] = agent or None
-            if email is not None:
-                u['email'] = email or None
-            if perms is not None:
-                # Wave 15 C-PERM. Writing perms MIGRATES the record: the marker goes on in the
-                # same read-modify-write, so a record can never end up with one and not the
-                # other (see `_record`). Whole-block replace, matching the PUT route's shape —
-                # a merge would make "remove this restriction" unexpressible.
-                u['perms'] = perms
-                u['perms_v'] = PERMS_VERSION
-        return reg
-    store.update('users', _set)
-
-
-def allowed_bus_labels(user):
-    """BU labels this user may select. 'all' -> All+Fisch+Royal; a single BU -> just that BU (no
-    'All', so the other BU is never reachable); multiple -> All + each."""
-    bus = (user or {}).get('bus', 'all')
-    if bus == 'all':
-        return ['All', 'Fisch', 'Royal']
-    labels = [BU_LABELS[b] for b in bus if b in BU_LABELS]
-    if not labels:
-        return ['All', 'Fisch', 'Royal']
-    return (['All'] + labels) if len(labels) > 1 else labels
-
-
-def assignable_people(tenant=None):
-    """Display names for `user`-typed overlay columns — the tenant's ACTIVE accounts.
-
-    Moved from app.py (2026-07-31) so both hosts serve the same choices. Resolved on every
-    call rather than persisted with the column: a snapshot would keep offering people who
-    have left and never offer people who joined. Deactivated accounts are excluded; a value
-    already stored on a row is untouched — history should still say who owned something.
-
-    Wave 18 (C1-TENANT): pass `tenant` to scope the choices to ONE company — the user registry
-    is a global control-plane bucket, and a Nurilab picker offering Royal's staff is a
-    cross-tenant name leak.
-
-    ⛔⛔ WAVE 33 (W33-T37) — A BLANK `tenant` NOW RETURNS NOTHING. It used to skip the filter and
-    return EVERY tenant's staff: `if want and …` is structurally fail-OPEN, and the exemption was
-    written for "None = unscoped (the Streamlit host, tenant #0's process)" — a host DELETED at
-    EXIT-6. So the sanctioned caller no longer exists, and what was left is a whole-platform
-    roster one forgotten kwarg away, with no error to notice
-    ([[gate-must-go-red-not-crash]]'s sibling: a wall that answers instead of refusing).
-    ⚠ The direction is the safety: this can only ever NARROW. All six live call sites pass
-    `session.tenant`, which `aios_session.read` refuses to admit blank, so nothing legitimate
-    changes — and a future caller that forgets gets an empty picker somebody notices instead of a
-    leak nobody does.
-    """
-    return sorted({str(u.get('name') or n) for n, u in _tenant_accounts(tenant)})
-
-
-def set_avatar(username, data_url):
-    """Set (or clear, with None/'') the user's profile photo — a data URL (wave 14 C-AVATAR,
-    [[loopable-wave14-split]] item 11). Stored VERBATIM; the API route owns validation (mime +
-    decoded size) because this value is served back to every grid session. Cleared by removing
-    the key, so records without a photo keep their pre-wave shape."""
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            if data_url:
-                u['avatar'] = str(data_url)
-            else:
-                u.pop('avatar', None)
-        return reg
-    store.update('users', _set)
-
-
-def avatar_map(tenant=None):
-    """{display name -> avatar data URL} for ACTIVE accounts with a photo — the companion of
-    `assignable_people()`, keyed by the SAME vocabulary: a `user` cell stores the display
-    name, so the display name is the only join a renderer has. Two active accounts sharing a
-    display name share one option; the first WITH a photo wins the key rather than a coin
-    flip deciding whether the option has a face. `tenant` scopes it exactly as
-    `assignable_people(tenant)` does, and for the same leak — including wave 33's fail-closed
-    blank, which both take from the ONE resolver below rather than each writing `if want and …`.
-    """
-    out = {}
-    for username, u in sorted(_tenant_accounts(tenant), key=lambda kv: kv[0]):
-        av = u.get('avatar')
-        nm = str(u.get('name') or username)
-        if av and nm not in out:
-            out[nm] = str(av)
-    return out
-
-
-def _tenant_accounts(tenant):
-    """`[(username, record), …]` — the ACTIVE accounts of exactly ONE tenant. FAIL-CLOSED.
-
-    ⛔ THE ONE PLACE THE TENANT FILTER FOR THE USER REGISTRY IS WRITTEN. It was written twice,
-    identically, in `assignable_people` and `avatar_map`, and both copies were fail-OPEN on a
-    blank slug in the same way (`if want and …`). Two copies of a wall is two places for one of
-    them to be fixed [[one-question-two-normalizers]]; `routes_shares._people` is a THIRD copy of
-    the same predicate and is lane C's to fold in.
-
-    ⚠ `str(u.get('tenant') or 'royal-imports')` is kept on the RECORD side deliberately: a
-    pre-wave-18 account genuinely has no `tenant` key and IS tenant #0's, and `users._public`
-    normalises it the same way. What changed is the WANT side — a blank want is now a refusal
-    rather than a wildcard.
-    """
-    want = str(tenant or '').strip().lower()
-    if not want:
-        # Not an error and not everything: nobody. See `assignable_people`'s note — the one
-        # caller this exemption was written for (the Streamlit host) was deleted at EXIT-6.
-        return []
-    try:
-        reg = registry() or {}
-    except Exception:
-        return []
-    return [(n, u) for n, u in reg.items()
-            if isinstance(u, dict) and u.get('active') is not False
-            and str(u.get('tenant') or 'royal-imports').strip().lower() == want]
+"""Per-user accounts for the platform, persisted in the HF Dataset store (users.json).
+
+Passwords are salted + PBKDF2-HMAC-SHA256 (200k iterations) — never stored or logged in plaintext.
+A bootstrap 'admin' account is seeded from APP_PASSWORD so the owner can always log in and create
+users; APP_PASSWORD also works as an emergency master for 'admin' if the registry is unreachable.
+
+Each account carries BU access ('all' or a list of team-ids [5=Fisch, 6=Royal]) which drives
+allowed_bus() — the basis for per-Business-Unit permissioning (a Royal-only user never sees Fisch).
+"""
+import os
+import hmac
+import hashlib
+import secrets
+
+import core.store as store
+
+BU_LABELS = {5: 'Fisch', 6: 'Royal'}
+_ITER = 200_000
+
+#: Wave 15 C-PERM — the explicit-resolution marker. Mirrors `core.perm_scope.PERMS_VERSION`;
+#: kept as a literal here so `users` does not import the permission layer it is read by.
+PERMS_VERSION = 1
+
+
+def _hash(pw, salt):
+    return hashlib.pbkdf2_hmac('sha256', str(pw).encode('utf-8'), bytes.fromhex(salt), _ITER).hex()
+
+
+def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
+            perms=None, tenant='royal-imports', platform_admin=False):
+    salt = secrets.token_hex(16)
+    rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
+           'bus': bus, 'active': active, 'modules': modules,
+           'agent': agent or None, 'email': email or None,
+           # Wave 18 (C1-TENANT, R1): the account's COMPANY. Absent == 'royal-imports' on every
+           # pre-wave record — no migration. Login binds the session to THIS value; the posted
+           # tenant field can hint but never override it.
+           'tenant': str(tenant or 'royal-imports').strip().lower()}
+    if platform_admin is True:
+        # Wave 19 (R3): the PLATFORM-operator flag — half of `core.platform_admin`'s double lock
+        # (the other half is `tenant == 'loopable'`). Written ONLY for True, so every record that
+        # is not deliberately promoted keeps its pre-wave shape and answers False by absence.
+        # There is no UI writer and there never should be: it is set by provisioning, on purpose.
+        rec['platform_admin'] = True
+    if perms is not None:
+        # Wave 15 C-PERM. A record written WITH perms is migrated by construction — the marker
+        # and the block are set together, here, so no writer can create one without the other.
+        # (`core.perm_scope` reads an unmarked record as legacy, so a block without its marker
+        # would be silently ignored; a marker without a block would deny everything.)
+        rec['perms'] = perms
+        rec['perms_v'] = PERMS_VERSION
+    return rec
+
+
+def registry():
+    return store.get('users')
+
+
+def ensure_bootstrap():
+    """Seed an 'admin' account from APP_PASSWORD ONLY on a truly fresh store (no users file yet).
+    Idempotent; no-op if the store is unavailable (the app then falls back to the master-password
+    path in verify()).
+
+    Critically, this NEVER overwrites an existing registry: it seeds only when store.exists('users')
+    is definitively False. A transient read failure at startup used to return {} and make this
+    re-seed just {admin} over the real accounts — that is the bug that wiped users on restart."""
+    if not store.available():
+        return
+    if store.exists('users'):          # present, or uncertain -> never clobber
+        return
+    try:
+        reg = store.get('users', fresh=True)
+    except Exception:
+        return
+    if reg:
+        return
+    master = os.environ.get('APP_PASSWORD', '')
+    if not master:
+        return
+    try:
+        store.put('users', {'admin': _record(master, 'Administrator', 'admin', 'all')})
+    except Exception:
+        pass
+
+
+def _public(username, u):
+    return {'username': username, 'name': u.get('name', username),
+            'role': u.get('role', 'user'), 'bus': u.get('bus', 'all'),
+            'modules': u.get('modules', 'all'),
+            'agent': u.get('agent'), 'email': u.get('email'),
+            # Wave 18 (C1-TENANT): the session's tenant binding travels on the projection or it
+            # does not travel — the same rule the perms block states below.
+            'tenant': str(u.get('tenant') or 'royal-imports').strip().lower(),
+            # Wave 14 C-AVATAR: the profile photo is public-safe by definition (it is served
+            # to every grid session via the workspace map); without it here the API session's
+            # user record silently drops it and /me can never show your own photo.
+            'avatar': u.get('avatar') or None,
+            # ⛔ WAVE 15 C-PERM — THE WALL TRAVELS ON THIS PROJECTION OR IT DOES NOT TRAVEL.
+            # `deps._user_for` builds every API session from `_public()`, so a `perms` block
+            # dropped here is a restricted account served as an unrestricted one — silently, on
+            # every route, with nothing to notice. `perms_v` must ride ALONG WITH it and for the
+            # same reason inverted: the marker without the block denies everything, the block
+            # without the marker is ignored. Two keys, one fact, never separated.
+            # `verify_api` asserts a restricted user's SESSION OBJECT carries both, at the mount
+            # rather than by grep — a projection is exactly the kind of wiring that looks
+            # present in three files and is absent in the one that runs.
+            **({'perms': u['perms']} if isinstance(u.get('perms'), dict) else {}),
+            **({'perms_v': int(u['perms_v'] or 0)} if u.get('perms_v') else {}),
+            # ⛔ WAVE 19 R3 — THE SAME RULE, ON A NEW FIELD. `deps._user_for` builds every API
+            # session from this projection, so the platform-admin flag travels here or
+            # `core.platform_admin.is_platform_admin(session.user)` is blind and the Loopable
+            # admin plane 403s its own operator. Carried ONLY when the record says True, so a
+            # session dict for any other account is byte-identical to its pre-wave shape.
+            # Not a client leak: `routes_auth._public_user` is a whitelist projection and does
+            # not name this key, so it reaches no browser via /login or /me — the client's copy
+            # is the separate `platformAdmin` bool on GET /settings, which is derived from this.
+            **({'platform_admin': True} if u.get('platform_admin') is True else {}),
+            'epoch': int(u.get('epoch') or 0)}
+
+
+# ------------------------------------------------------------------ session revocation (X3)
+# The API's session cookie is SIGNED AND STATELESS: there is no server-side session table to
+# delete from, so "log this user out everywhere" needs a number that lives with the account. The
+# cookie carries the epoch it was minted under; bumping the account's epoch makes every
+# outstanding cookie for that user fail verification on its next use. Absent == 0, so every
+# record written before this wave is valid without a migration.
+def epoch(username):
+    """The current session epoch for `username`. None when there is no such account.
+
+    None is NOT 0. 0 is "this account exists and has never been revoked"; None is "no record" —
+    which the session verifier must treat as a reason to refuse, not as a default to compare
+    against. (The APP_PASSWORD emergency-master admin has no record at all; the verifier handles
+    that case explicitly rather than inventing an epoch for it here.)
+    """
+    username = (username or '').strip().lower()
+    try:
+        u = (store.get('users') or {}).get(username)
+    except Exception:
+        return None
+    return int((u or {}).get('epoch') or 0) if u else None
+
+
+def bump_epoch(username):
+    """Revoke every outstanding API session for this account."""
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            u['epoch'] = int(u.get('epoch') or 0) + 1
+        return reg
+    store.update('users', _set)
+
+
+def verify(username, pw):
+    """Return a public user dict on success, else None. APP_PASSWORD is an emergency master for the
+    'admin' login even if the store is unreachable, so the owner is never locked out."""
+    username = (username or '').strip().lower()
+    if not username or not pw:
+        return None
+    master = os.environ.get('APP_PASSWORD', '')
+    try:
+        # read fresh so accounts created moments ago (UI or out-of-band) are recognised at once
+        reg = store.get('users', fresh=True)
+    except Exception:
+        reg = {}
+    u = reg.get(username)
+    # ⛔ KEY FIRST, EMAIL SECOND, AND SINCE WAVE 37 THAT ORDER IS A DECISION RATHER THAN AN ACCIDENT.
+    # R8 lets a username BE an email address, so a typed string can now match a registry KEY and a
+    # different account's `email` field at the same time. The key wins, here, by construction: this
+    # branch is only reached when `reg.get(username)` missed. `routes_admin.py::create_user` refuses
+    # to CREATE either collision (`username_shadows_email` / `email_shadows_username`) so the
+    # ambiguity cannot be introduced through the product; this line is what decides it for any
+    # record that arrived some other way.
+    if u is None and '@' in username:
+        # Wave 18 (R1): the login box takes a username OR an email — admin@nurilab.id signs in
+        # without knowing the slug an admin chose. First case-insensitive email match wins;
+        # ambiguity is an admin data problem, not a login feature.
+        for k, r in reg.items():
+            if isinstance(r, dict) and str(r.get('email') or '').strip().lower() == username:
+                username, u = k, r
+                break
+    if u and u.get('active', True) and hmac.compare_digest(_hash(pw, u['salt']), u['hash']):
+        return _public(username, u)
+    # emergency master: admin + APP_PASSWORD always works (covers first run / store outage)
+    if username == 'admin' and master and hmac.compare_digest(str(pw), master):
+        # ⚠ CARRY THE RECORD'S CURRENT EPOCH when there is a record to read, so the session cookie
+        # the API mints from this dict AGREES with the stored account.
+        #
+        # This is not what stops the emergency lockout — `deps._user_for`'s master fallback does
+        # that, and a negative control confirmed the lockout is gone with or without this line.
+        # What it fixes is subtler and is a SCOPE question: a cookie whose epoch disagrees with the
+        # record falls through to that master fallback, which hands back a SYNTHETIC identity
+        # (`bus: 'all'`, `modules: 'all'`). An admin whose record narrows either field would
+        # therefore be silently WIDENED to consolidated, all-module access for the life of that
+        # session. Matching the epoch means the record branch wins and the account's real scope
+        # applies, leaving the master fallback as the true last resort it is meant to be.
+        # 0 when the store is unreachable, which is the case this branch was written for.
+        return {'username': 'admin', 'name': 'Administrator', 'role': 'admin', 'bus': 'all',
+                'modules': 'all', 'epoch': int((reg.get('admin') or {}).get('epoch') or 0)}
+    return None
+
+
+def create_user(username, pw, name, role='user', bus='all', modules='all',
+                agent=None, email=None, tenant=None, platform_admin=None):
+    """Create — or, from app.py's dialog, OVERWRITE — an account.
+
+    ⛔ X3: OVERWRITING AN ACCOUNT MUST NOT RESURRECT ITS OLD SESSIONS. `_record()` builds a fresh
+    record with no `epoch` key, i.e. absent == 0. So re-saving an existing username used to reset
+    the epoch to 0, and every cookie minted before that account's last password rotation started
+    verifying again — a silent un-revocation. `app.py`'s "Add / update a user" calls this function
+    for BOTH add and update, so the hole was reachable from the shipped UI.
+
+    Epoch revocation is only ever as strong as the NARROWEST write path that touches the record, so
+    the carry-and-bump lives here rather than in each caller: an overwrite is at least as
+    session-invalidating as a password change, and it usually IS one.
+    """
+    username = (username or '').strip().lower()
+    if not username or not pw:
+        raise ValueError('username and password are required')
+
+    def _add(reg):
+        prior = reg.get(username) or {}
+        rec = _record(pw, name or username, role, bus, modules=modules,
+                      agent=agent, email=email,
+                      # An overwrite that names no tenant KEEPS the account's company — a
+                      # rename must never quietly move a user between tenants.
+                      tenant=(tenant or prior.get('tenant') or 'royal-imports'),
+                      # Wave 19 (R3): CARRIED, for the same reason `epoch` is carried below —
+                      # `_record` builds a FRESH record, so re-running the provisioner (it is
+                      # documented as idempotent) or saving an account through this function
+                      # would silently DEMOTE a platform admin and lock the operator out of
+                      # their own plane. None = leave as it was; True/False = set it deliberately.
+                      platform_admin=(prior.get('platform_admin') is True
+                                      if platform_admin is None else platform_admin is True))
+        if prior:
+            rec['epoch'] = int(prior.get('epoch') or 0) + 1
+        reg[username] = rec
+        return reg
+    store.update('users', _add)
+
+
+def set_password(username, pw):
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            u['salt'] = secrets.token_hex(16)
+            u['hash'] = _hash(pw, u['salt'])
+            # X3: a password change revokes every outstanding API session for the account. Bumped
+            # INSIDE the same read-modify-write as the hash so the two can never disagree — a
+            # separate update() could rotate the password and leave old cookies live if the second
+            # write failed.
+            u['epoch'] = int(u.get('epoch') or 0) + 1
+        return reg
+    store.update('users', _set)
+
+
+def set_active(username, active):
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        if username in reg:
+            reg[username]['active'] = bool(active)
+            # X3: DEACTIVATION must kill live sessions, not just future logins — otherwise a
+            # disabled account keeps working until its cookie expires. Bumped on reactivation too:
+            # cheap, and it means a re-enabled account never resurrects a stale cookie.
+            reg[username]['epoch'] = int(reg[username].get('epoch') or 0) + 1
+        return reg
+    store.update('users', _set)
+
+
+def set_platform_admin(username, on):
+    """Promote/demote a PLATFORM administrator (wave 19, R3) without touching the password.
+
+    The narrow write, deliberately: `create_user` is the destructive path (fresh salt, fresh
+    hash, bumped epoch) and promoting somebody should not sign them out or rotate a credential.
+    Cleared by REMOVING the key, so a demoted record goes back to its pre-wave shape rather than
+    carrying a `False` that reads as "somebody considered this".
+
+    ⚠ This is the flag only. It grants nothing on its own — `core.platform_admin` also demands
+    the `loopable` tenant, and there is no code path anywhere that moves an account between
+    tenants, which is what makes the second lock hold.
+    """
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            if on is True:
+                u['platform_admin'] = True
+            else:
+                u.pop('platform_admin', None)
+        return reg
+    store.update('users', _set)
+
+
+# ------------------------------------------------------------------ activity stamps (wave 19 R4)
+# "When did this account last sign in, and is anyone actually using it?" — the two questions the
+# Loopable admin plane exists to answer and that NOTHING in the product could answer before this
+# wave (there is no login history, no audit log, no request log anywhere).
+#
+# ⛔ THIS IS THE FIRST HIGH-FREQUENCY WRITER `users.json` HAS EVER HAD, and that bucket also holds
+# every password hash, `active`, `epoch` and the permission blocks. Three rules follow, and the
+# second one is a correctness rule, not a performance one:
+#
+#   1. **In-place mutation of ONE key.** Never `_record()`, never a whole-record replace: a stamp
+#      that rebuilt the record would reset the salt/hash (locking the user out) or the epoch
+#      (silently un-revoking every cookie ever minted for them). `set_password`'s docstring
+#      explains why that class of bug is worth naming out loud.
+#
+#   2. **SYNCHRONOUS FLUSH — deliberately NOT the async path, and this reverses my first draft.**
+#      `store.update(flush='async')` rebases on the PROCESS CACHE once a key is `_owned`
+#      (`core/store.py:284`) and its worker uploads that whole cached blob. For a
+#      table-workspace key, written by one process, that is exactly right. For `users` it is a
+#      silent-revert machine: tenant #0's Streamlit host writes the SAME file, so an API process
+#      holding a cache from an hour ago would, on its next stamp, upload a blob in which a
+#      password rotation or a deactivation performed in the other host simply never happened.
+#      A telemetry stamp must not be able to resurrect a disabled account. `flush='sync'` does a
+#      FRESH strict read inside the store's lock and then uploads, which is the same discipline
+#      every other `users` writer already uses.
+#
+#   3. **OFF THE REQUEST THREAD, so rule 2 costs nothing.** A sync commit is a hub round-trip, and
+#      neither a sign-in nor a random request an hour later should wait for it. Each stamp runs on
+#      a short-lived daemon thread; `flush_stamps()` is how a test or a shutdown waits for them.
+#      Everything is fail-silent: a stamp is telemetry and may never turn a good login into a
+#      failed one — the plane shows an honest "never" instead.
+def _now_iso():
+    import datetime as _dt
+    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec='seconds')
+
+
+#: Live stamp threads, so `flush_stamps()` can join them. Bounded by construction — one thread per
+#: stamp, and a stamp is at most one per login plus one per account per hour per process.
+_STAMPS = []
+_STAMPS_LOCK = __import__('threading').Lock()
+
+
+def _stamp(username, fields):
+    """Merge `fields` into ONE account record, on a background thread, with a fresh read."""
+    username = (username or '').strip().lower()
+    if not username or not fields:
+        return None
+
+    def _set(reg):
+        u = reg.get(username)
+        if isinstance(u, dict):
+            u.update(fields)
+        return reg
+
+    def _work():
+        try:
+            store.update('users', _set)          # sync: fresh strict read + blocking upload
+        except Exception:
+            pass                                  # a lost stamp is a lost stamp, never an error
+    import threading
+    t = threading.Thread(target=_work, daemon=True, name=f'user-stamp:{username}')
+    with _STAMPS_LOCK:
+        _STAMPS[:] = [x for x in _STAMPS if x.is_alive()]
+        _STAMPS.append(t)
+    t.start()
+    return t
+
+
+def flush_stamps(timeout=10.0):
+    """Block until outstanding stamp writes have been applied. For gates and shutdown hooks —
+    the app never needs it, exactly like `core.store.flush`."""
+    with _STAMPS_LOCK:
+        pending = list(_STAMPS)
+    for t in pending:
+        t.join(timeout=timeout)
+    return all(not t.is_alive() for t in pending)
+
+
+def touch_login(username, when=None):
+    """Stamp `last_login` (ISO-8601, UTC, OFFSET-BEARING) on a SUCCESSFUL login.
+
+    `username` must be the RESOLVED account key, not what the person typed: `verify()` accepts an
+    email address and resolves it to the registry key, so stamping the typed identifier would
+    write a stamp onto a key that does not exist and create a phantom account in the registry.
+
+    `last_active` rides along — signing in IS activity, and setting both here means the plane's
+    two columns agree the moment somebody logs in rather than an hour later.
+    """
+    stamp = when or _now_iso()
+    return _stamp(username, {'last_login': stamp, 'last_active': stamp})
+
+
+def touch_active(username, when=None):
+    """Stamp `last_active` — "this session did something". Throttled BY THE CALLER (`deps.py`
+    holds a process-local last-seen map), so this is not a store round-trip per request."""
+    return _stamp(username, {'last_active': when or _now_iso()})
+
+
+def set_access(username, role=None, bus=None, modules=None, agent=None, email=None,
+               name=None, perms=None):
+    """Update access fields. agent/email: pass '' to clear, None to leave unchanged —
+    the user↔agent link scopes the Customer List page / digests to that agent's book.
+
+    `name` follows the same None-means-unchanged idiom. It is here because it had no setter at all:
+    a display name could previously only be changed by re-creating the record through
+    `create_user`, i.e. by also resetting the password (and, before the fix above, the session
+    epoch). Y4's `PATCH {name?}` needs the narrow write, not the destructive one."""
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            if name is not None:
+                u['name'] = name
+            if role is not None:
+                u['role'] = role
+            if bus is not None:
+                u['bus'] = bus
+            if modules is not None:
+                u['modules'] = modules
+            if agent is not None:
+                u['agent'] = agent or None
+            if email is not None:
+                u['email'] = email or None
+            if perms is not None:
+                # Wave 15 C-PERM. Writing perms MIGRATES the record: the marker goes on in the
+                # same read-modify-write, so a record can never end up with one and not the
+                # other (see `_record`). Whole-block replace, matching the PUT route's shape —
+                # a merge would make "remove this restriction" unexpressible.
+                u['perms'] = perms
+                u['perms_v'] = PERMS_VERSION
+        return reg
+    store.update('users', _set)
+
+
+def allowed_bus_labels(user):
+    """BU labels this user may select. 'all' -> All+Fisch+Royal; a single BU -> just that BU (no
+    'All', so the other BU is never reachable); multiple -> All + each."""
+    bus = (user or {}).get('bus', 'all')
+    if bus == 'all':
+        return ['All', 'Fisch', 'Royal']
+    labels = [BU_LABELS[b] for b in bus if b in BU_LABELS]
+    if not labels:
+        return ['All', 'Fisch', 'Royal']
+    return (['All'] + labels) if len(labels) > 1 else labels
+
+
+def assignable_people(tenant=None):
+    """Display names for `user`-typed overlay columns — the tenant's ACTIVE accounts.
+
+    Moved from app.py (2026-07-31) so both hosts serve the same choices. Resolved on every
+    call rather than persisted with the column: a snapshot would keep offering people who
+    have left and never offer people who joined. Deactivated accounts are excluded; a value
+    already stored on a row is untouched — history should still say who owned something.
+
+    Wave 18 (C1-TENANT): pass `tenant` to scope the choices to ONE company — the user registry
+    is a global control-plane bucket, and a Nurilab picker offering Royal's staff is a
+    cross-tenant name leak.
+
+    ⛔⛔ WAVE 33 (W33-T37) — A BLANK `tenant` NOW RETURNS NOTHING. It used to skip the filter and
+    return EVERY tenant's staff: `if want and …` is structurally fail-OPEN, and the exemption was
+    written for "None = unscoped (the Streamlit host, tenant #0's process)" — a host DELETED at
+    EXIT-6. So the sanctioned caller no longer exists, and what was left is a whole-platform
+    roster one forgotten kwarg away, with no error to notice
+    ([[gate-must-go-red-not-crash]]'s sibling: a wall that answers instead of refusing).
+    ⚠ The direction is the safety: this can only ever NARROW. All six live call sites pass
+    `session.tenant`, which `aios_session.read` refuses to admit blank, so nothing legitimate
+    changes — and a future caller that forgets gets an empty picker somebody notices instead of a
+    leak nobody does.
+    """
+    return sorted({str(u.get('name') or n) for n, u in _tenant_accounts(tenant)})
+
+
+def set_avatar(username, data_url):
+    """Set (or clear, with None/'') the user's profile photo — a data URL (wave 14 C-AVATAR,
+    [[loopable-wave14-split]] item 11). Stored VERBATIM; the API route owns validation (mime +
+    decoded size) because this value is served back to every grid session. Cleared by removing
+    the key, so records without a photo keep their pre-wave shape."""
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            if data_url:
+                u['avatar'] = str(data_url)
+            else:
+                u.pop('avatar', None)
+        return reg
+    store.update('users', _set)
+
+
+def avatar_map(tenant=None):
+    """{display name -> avatar data URL} for ACTIVE accounts with a photo — the companion of
+    `assignable_people()`, keyed by the SAME vocabulary: a `user` cell stores the display
+    name, so the display name is the only join a renderer has. Two active accounts sharing a
+    display name share one option; the first WITH a photo wins the key rather than a coin
+    flip deciding whether the option has a face. `tenant` scopes it exactly as
+    `assignable_people(tenant)` does, and for the same leak — including wave 33's fail-closed
+    blank, which both take from the ONE resolver below rather than each writing `if want and …`.
+    """
+    out = {}
+    for username, u in sorted(_tenant_accounts(tenant), key=lambda kv: kv[0]):
+        av = u.get('avatar')
+        nm = str(u.get('name') or username)
+        if av and nm not in out:
+            out[nm] = str(av)
+    return out
+
+
+def _tenant_accounts(tenant):
+    """`[(username, record), …]` — the ACTIVE accounts of exactly ONE tenant. FAIL-CLOSED.
+
+    ⛔ THE ONE PLACE THE TENANT FILTER FOR THE USER REGISTRY IS WRITTEN. It was written twice,
+    identically, in `assignable_people` and `avatar_map`, and both copies were fail-OPEN on a
+    blank slug in the same way (`if want and …`). Two copies of a wall is two places for one of
+    them to be fixed [[one-question-two-normalizers]]; `routes_shares._people` is a THIRD copy of
+    the same predicate and is lane C's to fold in.
+
+    ⚠ `str(u.get('tenant') or 'royal-imports')` is kept on the RECORD side deliberately: a
+    pre-wave-18 account genuinely has no `tenant` key and IS tenant #0's, and `users._public`
+    normalises it the same way. What changed is the WANT side — a blank want is now a refusal
+    rather than a wildcard.
+    """
+    want = str(tenant or '').strip().lower()
+    if not want:
+        # Not an error and not everything: nobody. See `assignable_people`'s note — the one
+        # caller this exemption was written for (the Streamlit host) was deleted at EXIT-6.
+        return []
+    try:
+        reg = registry() or {}
+    except Exception:
+        return []
+    return [(n, u) for n, u in reg.items()
+            if isinstance(u, dict) and u.get('active') is not False
+            and str(u.get('tenant') or 'royal-imports').strip().lower() == want]

platform/model/metrics/sales.yml

@@ -1,108 +1,149 @@
-# Metrics: sales — the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
-# metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
-# Fields per metric:
-#   key/label/description — identity + the human definition (visibility = trust)
-#   agg + field           — sum | count_distinct over the topic's entity
-#   agg: ratio            — numerator/denominator are metric KEYS (resolved recursively)
-#   agg: derived + expr   — arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
-#   format                — usd | int | pct (rendering hint for surfaces)
-#   ai_context            — what a small model must know to use the metric correctly
-#   validate              — the INDEPENDENT Odoo cross-check contract (named method implemented in
-#                           harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
-topic: sales_lines
-metrics:
-  - key: revenue
-    label: Revenue
-    agg: sum
-    field: price_subtotal
-    format: usd
-    description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
-    ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
-    validate:
-      method: order_level_revenue
-      note: "Σ line price_subtotal must equal Σ parent-order amount_untaxed under the same scope, to the cent (line vs order basis — the built-in cross-check)."
-
-  - key: units
-    label: Units sold
-    agg: sum
-    field: product_uom_qty
-    format: int
-    description: "Total quantity across confirmed wholesale order lines."
-    ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
-
-  - key: margin
-    label: Gross margin $
-    agg: sum
-    field: margin
-    format: usd
-    description: "Line revenue minus line cost (Odoo Margin module), summed."
-    ai_context: "margin is read_group-aggregatable (Margin module installed). COGS = revenue - margin. purchase_price is per-UNIT cost — never sum it as a total."
-
-  - key: cogs
-    label: COGS
-    agg: derived
-    expr: "revenue - margin"
-    format: usd
-    description: "Cost of goods sold, derived: revenue minus gross margin."
-    ai_context: "Derived, not pulled — Odoo carries cost on lines as margin; COGS is the difference."
-
-  - key: margin_pct
-    label: Gross margin %
-    agg: ratio
-    numerator: margin
-    denominator: revenue
-    format: pct
-    description: "Gross margin as a share of revenue."
-    ai_context: "Guarded against zero revenue (returns 0). Compare across BUs/categories at the same scope only."
-
-  - key: orders
-    label: Orders
-    topic: sales_orders
-    agg: count
-    format: int
-    description: "Confirmed wholesale orders in the window (order-header count — what the scorecards show)."
-    ai_context: "Order-level count; slightly higher than distinct-orders-from-lines because a few confirmed orders carry zero lines (a data-health artifact the reconciliation contract counts exactly)."
-    validate:
-      method: order_count
-      note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
-
-  - key: customers
-    label: Active customers
-    agg: count_distinct
-    field: order_partner_id
-    format: int
-    description: "Distinct customers with at least one confirmed wholesale order line in the window."
-    ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
-
-  - key: aov
-    label: Average order value
-    agg: ratio
-    numerator: revenue
-    denominator: orders
-    format: usd
-    description: "Revenue per distinct order."
-    ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
-
-  # ⭐ Wave 21 R2 — the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
-  # not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
-  # invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
-  # `live_domain` filters the live path — BOTH or store_parity compares two different questions.
-  - key: revenue_invoiced
-    label: Sales — fully invoiced
-    agg: sum
-    field: price_subtotal
-    store_filter_sql: "o.invoice_status = 'invoiced'"
-    live_domain: [["order_id.invoice_status", "=", "invoiced"]]
-    format: usd
-    description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
-    ai_context: "Same scope as revenue, narrowed by the ORDER-level fully-invoiced flag. This is NOT posted-invoice-line revenue: a partially invoiced order is excluded entirely until Odoo flips the flag. Reconciled store-vs-live per BU by store_parity."
-
-  - key: orders_invoiced
-    label: Orders — fully invoiced
-    topic: sales_orders
-    agg: count
-    store_filter_sql: "o.invoice_status = 'invoiced'"
-    live_domain: [["invoice_status", "=", "invoiced"]]
-    format: int
-    description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
-    ai_context: "Order-header count under the orders scope plus the fully-invoiced flag; partially invoiced and not-yet-invoiced orders are excluded. Reconciled store-vs-live per BU by store_parity."
+# Metrics: sales — the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
+# metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
+# Fields per metric:
+#   key/label/description — identity + the human definition (visibility = trust)
+#   agg + field           — sum | count_distinct over the topic's entity
+#   agg: ratio            — numerator/denominator are metric KEYS (resolved recursively)
+#   agg: derived + expr   — arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
+#   format                — usd | int | pct (rendering hint for surfaces)
+#   ai_context            — what a small model must know to use the metric correctly
+#   validate              — the INDEPENDENT Odoo cross-check contract (named method implemented in
+#                           harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
+#   empty                 — W37 C1's EMPTY-WINDOW FAMILY. See below; a metric an ENTITY topic
+#                           offers as a lookback column MUST declare one.
+#
+# ⛔⛔ `empty:` — WHAT A ROW WITH NO ACTIVITY IN THE WINDOW RENDERS AS (wave 37, contract C1).
+# Measured and load-bearing: only 1,646 of 5,836 active products sold in the last 90 days, so a
+# per-SKU lookback metric has NO GROUP for 72% of the catalogue. Get the default wrong and every
+# product grid reads as broken. Two values, and the difference is whether the blank cell would be
+# a TRUE STATEMENT:
+#   empty: zero    ADDITIVE — units, revenue, margin $, COGS. "It sold nothing" is a real
+#                  measurement, so 0 is the honest cell and a blank would hide a fact.
+#   empty: blank   RATIO / DERIVED-FROM-A-RATIO — GM %, ASP. A 0% margin on zero sales is a
+#                  FALSE statement, not a missing one. ⛔ AND THE GUARD IS THE DENOMINATOR, NOT
+#                  THE MISSING GROUP: `semantic._post_compute` returns 0.0 for `num/0`, so a SKU
+#                  that DID sell at $0 would print "0.0%" with a group behind it. The resolver
+#                  blanks on a zero denominator, which is the only reading that is never a lie.
+# ⚠ A metric with no `empty:` is REFUSED by `entity_measures()` rather than defaulted — a
+# defaulted family is a guess about truth, and C1 says a metric that cannot say which family it
+# is in does not ship.
+topic: sales_lines
+metrics:
+  - key: revenue
+    label: Revenue
+    agg: sum
+    field: price_subtotal
+    format: usd
+    empty: zero
+    description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
+    ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
+    validate:
+      method: order_level_revenue
+      note: "Σ line price_subtotal must equal Σ parent-order amount_untaxed under the same scope, to the cent (line vs order basis — the built-in cross-check)."
+
+  - key: units
+    label: Units sold
+    agg: sum
+    field: product_uom_qty
+    format: int
+    empty: zero
+    description: "Total quantity across confirmed wholesale order lines."
+    ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
+
+  - key: margin
+    label: Gross margin $
+    agg: sum
+    field: margin
+    format: usd
+    empty: zero
+    description: "Line revenue minus line cost (Odoo Margin module), summed."
+    ai_context: "margin is read_group-aggregatable (Margin module installed). COGS = revenue - margin. purchase_price is per-UNIT cost — never sum it as a total."
+
+  - key: cogs
+    label: COGS
+    agg: derived
+    expr: "revenue - margin"
+    format: usd
+    empty: zero
+    description: "Cost of goods sold, derived: revenue minus gross margin."
+    ai_context: "Derived, not pulled — Odoo carries cost on lines as margin; COGS is the difference."
+
+  - key: margin_pct
+    label: Gross margin %
+    agg: ratio
+    numerator: margin
+    denominator: revenue
+    format: pct
+    empty: blank
+    description: "Gross margin as a share of revenue."
+    ai_context: "Compare across BUs/categories at the same scope only. ⚠ TWO ZERO-REVENUE BEHAVIOURS, deliberately: the scalar/analyst path returns 0 (semantic._post_compute's guard), while an ENTITY LOOKBACK COLUMN renders BLANK (empty: blank) — on a grid, a printed 0.0% beside 5,836 products would assert a margin nobody measured."
+
+  # ⭐ W37-T10 — ASP, the fifth SHIP-FIRST per-SKU metric (proto/P3). Blended $18.76 over 1,646
+  # SKUs in the 90 days to 2026-08-19. A RATIO of two same-topic base measures, so it survives a
+  # GROUPED store_query (only a CROSS-TOPIC component is refused — that is what stops `aov`,
+  # whose denominator `orders` lives on sales_orders).
+  # ⚠ UNITS ARE AS-ORDERED, mixed UoM. `units` says so and this inherits it: a SKU sold in cases
+  # and in singles has an ASP blended across both, which is the true average selling price of a
+  # line unit and NOT a per-piece price.
+  - key: asp
+    label: Average selling price
+    agg: ratio
+    numerator: revenue
+    denominator: units
+    format: usd
+    empty: blank
+    description: "Revenue per unit sold — the blended average selling price."
+    ai_context: "revenue ÷ units at identical scope. Mixed units of measure are summed as ordered quantity, so this is per ordered unit, not per piece. Blank when nothing sold: an ASP of $0 on zero units is a false statement, not a missing one."
+
+  - key: orders
+    label: Orders
+    topic: sales_orders
+    agg: count
+    format: int
+    description: "Confirmed wholesale orders in the window (order-header count — what the scorecards show)."
+    ai_context: "Order-level count; slightly higher than distinct-orders-from-lines because a few confirmed orders carry zero lines (a data-health artifact the reconciliation contract counts exactly)."
+    validate:
+      method: order_count
+      note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
+
+  - key: customers
+    label: Active customers
+    agg: count_distinct
+    field: order_partner_id
+    format: int
+    empty: zero
+    description: "Distinct customers with at least one confirmed wholesale order line in the window."
+    ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
+
+  - key: aov
+    label: Average order value
+    agg: ratio
+    numerator: revenue
+    denominator: orders
+    format: usd
+    description: "Revenue per distinct order."
+    ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
+
+  # ⭐ Wave 21 R2 — the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
+  # not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
+  # invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
+  # `live_domain` filters the live path — BOTH or store_parity compares two different questions.
+  - key: revenue_invoiced
+    label: Sales — fully invoiced
+    agg: sum
+    field: price_subtotal
+    store_filter_sql: "o.invoice_status = 'invoiced'"
+    live_domain: [["order_id.invoice_status", "=", "invoiced"]]
+    format: usd
+    description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
+    ai_context: "Same scope as revenue, narrowed by the ORDER-level fully-invoiced flag. This is NOT posted-invoice-line revenue: a partially invoiced order is excluded entirely until Odoo flips the flag. Reconciled store-vs-live per BU by store_parity."
+
+  - key: orders_invoiced
+    label: Orders — fully invoiced
+    topic: sales_orders
+    agg: count
+    store_filter_sql: "o.invoice_status = 'invoiced'"
+    live_domain: [["invoice_status", "=", "invoiced"]]
+    format: int
+    description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
+    ai_context: "Order-header count under the orders scope plus the fully-invoiced flag; partially invoiced and not-yet-invoiced orders are excluded. Reconciled store-vs-live per BU by store_parity."

platform/model/metrics/stock.yml

@@ -0,0 +1,57 @@
+# Metrics: stock — physical movement (W37-T13, owner item 4 / ruling R1).
+#
+# ⛔⛔ THE DIRECTION LIVES IN `store_filter_sql`, WHICH IS WHY THESE ARE TWO METRICS AND NOT ONE
+# METRIC WITH A PARAMETER. The model's filtered-measure support compiles `store_filter_sql` into
+# `sum(CASE WHEN <predicate> THEN <field> ELSE 0 END)`, so IN and OUT are the SAME sum over the
+# SAME rows under two different predicates — one scan answers both, and neither can drift from the
+# other's scope because they share every other clause.
+#
+# ⛔ EACH PREDICATE IS TWO-SIDED, and that is the ticket's headline trap (`proto/P1-stock-moves.md`):
+# `internal -> internal` is **58% of all moves**. A one-sided test (`destination is internal`) counts
+# every internal transfer as an arrival AND a one-sided `source is internal` counts it as a
+# departure — both columns roughly double, nothing errors, and the totals stay internally
+# consistent with each other, which is what makes it survive review.
+#
+# ⚠ `usage` COMES FROM `stock_location`, NOT from the move. `location_id` mirrors as an id plus a
+# NAME; there is no usage on the move row, so `stock_location` is joined in the topic precisely to
+# make this predicate expressible. If that join is ever dropped, these two metrics do not go red —
+# they go NULL-predicate, which SQL treats as false, and both columns silently read ZERO.
+#
+# ⚠ ADJUSTMENTS AND SCRAP ARE INCLUDED, DELIBERATELY, AND THE ALTERNATIVE WAS MEASURED. They are
+# ~30% of IN and ~20% of OUT, and the two obvious exclusions are NOT equivalent — the 5,320-unit
+# gap between them is entirely `Virtual Locations/Scrap`. A physical arrival is an arrival however
+# it was booked, so the honest default is to count it and let the `source`/`destination` dims
+# separate it. Excluding it silently would be a different number under the same label.
+topic: stock_moves
+metrics:
+  - key: stock_in
+    label: Stock moved in
+    agg: sum
+    field: quantity_done
+    store_filter_sql: "sd.usage = 'internal' AND COALESCE(sl.usage, '') <> 'internal'"
+    format: int
+    empty: zero
+    description: "Units that ARRIVED at an internal location from outside it, over the window."
+    ai_context: "Receipts, returns inward and inventory adjustments upward. Two-sided by construction: an internal-to-internal transfer is NOT an arrival. Quantities are in each product's own unit, so never sum this across SKUs."
+
+  - key: stock_out
+    label: Stock moved out
+    agg: sum
+    field: quantity_done
+    store_filter_sql: "sl.usage = 'internal' AND COALESCE(sd.usage, '') <> 'internal'"
+    format: int
+    empty: zero
+    description: "Units that LEFT an internal location for outside it, over the window."
+    ai_context: "Deliveries, scrap and adjustments downward. Two-sided by construction: an internal-to-internal transfer is NOT a departure. Quantities are in each product's own unit, so never sum this across SKUs."
+
+  # ⚠ NET IS DERIVED, never a third sum. Deriving it guarantees `net = in - out` exactly, where a
+  # separately-summed net could disagree with its own two components under a filter and nothing
+  # would say which was right.
+  - key: stock_net
+    label: Stock moved net
+    agg: derived
+    expr: "stock_in - stock_out"
+    format: int
+    empty: zero
+    description: "Arrivals minus departures over the window — the period change in units held."
+    ai_context: "Derived from stock_in and stock_out, so it always reconciles to them. It is a MOVEMENT figure, not the on-hand balance: the balance is `product_data.on_hand` from stock.quant."

platform/model/topics/odoo_agents.yml

@@ -21,6 +21,38 @@ store:
   # 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.
 
+# ⭐⭐ W37-T12 / owner item 4 (R1) — THE LOOKBACK-MEASURE BINDING, the agent half of
+# *"It should apply to Odoo agents database as well."* Same contract as
+# `odoo_products.yml`: a FACT topic, and the dim of that topic which carries THIS
+# entity's identity.
+#
+# ⛔⛔ WHICH AGENT SOURCE, STATED — because there are THREE in this Odoo and they name
+# DIFFERENT PEOPLE (`proto/P3-metric-catalog.md`: 9 agents carry route-1 revenue, 12
+# carry commission lines, 17 carry the flag). This binds ROUTE 1, the CUSTOMER-MASTER
+# BOOK: `sales_lines.agent` is `rp.agent_id`, the customer's assigned agent, so every
+# order of that customer counts toward their agent. That is "whose book is this" and it
+# is the right question for a column on the AGENT REGISTRY.
+# ⚠ It is NOT commission. `account.invoice.line.agent` (topic `commission_lines`) is the
+# per-INVOICE-LINE credited agent and answers a different question; `sales_lines.yml`'s
+# own `agent` dim comment carries the full disagreement and says never to "fix" one by
+# reading the other.
+#
+# ⭐ THE JOIN NEEDS NO NEW DIM, unlike the product side. `sales_lines.agent` declares a
+# `name_col`, so `store_query` emits `agent_id` — which IS `res.partner.id`, which IS
+# this grid's `odoo_id` identity. Product needed `product_code` because its grid keys on
+# `default_code`; this one already keys on the same integer the fact topic groups by.
+measures:
+  source: sales_lines
+  dim: agent
+  keys: [revenue, units, margin, cogs, margin_pct, asp, customers]
+  not_yet:
+    - key: orders / aov
+      cause: "`orders` lives on topic `sales_orders`, so under a `group_by` it is a CROSS-TOPIC measure and `semantic.store_query` refuses it (scalar-only). `aov` inherits the refusal through its denominator"
+      fix: "add an ORDER-COUNT metric to `sales_lines` itself — `count_distinct` over `l.order_id` — which answers the same question at this grain in one pass"
+    - key: commission_amount
+      cause: "the commission basis lives on `account.invoice.line.agent` (topic `commission_lines`), a different topic AND a different grain; `invoice_lines` deduplicates to at most one agent per line"
+      fix: "bind a SECOND measures block per source once the contract allows more than one, and label the columns so the two routes can never be read as the same number"
+
 # 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.

platform/model/topics/odoo_products.yml

@@ -26,6 +26,57 @@ store:
     category: {label: "Category"}
     supplier: {label: "Supplier"}
 
+# ⭐⭐ W37-T10 / owner item 4 (ruling R1) — THE LOOKBACK-MEASURE BINDING. Owner: *"Odoo products
+# should have a lookbsck metrics like sales etc."* This block is what turns `measures: []` on the
+# product workspace into a real catalogue, and it is DECLARED HERE rather than hand-written in a
+# route for the reason `_rollup_source_offer` gives about itself: a second list is a second
+# definition of the same fact, and the two drift the day somebody adds a metric.
+#
+# ⛔ THE JOIN KEY IS THE TRAP CONTRACT C1 NAMES, and this is where it is answered. `source` is a
+# FACT topic; `dim` is the dim of THAT topic which carries THIS entity's identity. `sales_lines`
+# has two candidates and only one is right: `product` groups by Odoo's `product_id`, while this
+# database's identity (see `scope.identity` above) is `default_code`. Binding to `product` would
+# key every cell on a number no grid row carries — a column of nulls that reads as "never sold".
+#
+# ⚠ A SINGLE-TOPIC GROUPED QUERY, which is why `semantic.store_query`'s cross-topic refusal does
+# not bite: `revenue` lives ON `sales_lines` and we group `sales_lines` by its OWN dim. The same
+# refusal is real and DOES bite `aov`/`orders` (denominator `orders` lives on `sales_orders`), so
+# those two are absent from `keys` below and `entity_measures()` re-proves that rather than
+# trusting this list.
+# ⭐ A LIST SINCE W37-T13: an entity's columns legitimately come from more than ONE fact topic.
+# Sales movement is `sales_lines`; physical movement is `stock_moves`. Same grid, same join key
+# (`product_code`), different tables — forcing stock into the sales topic would have defined a
+# metric against rows it does not have.
+measures:
+- source: sales_lines
+  dim: product_code
+  # ⭐ The SHIP-FIRST six of `proto/P3-metric-catalog.md`, and they cost ONE grouped query
+  # together (measured 0.22 s over 1,670 groups against the mirror; 2.55 s live).
+  keys: [units, revenue, margin, cogs, margin_pct, asp]
+  # ⛔ REPORTED, NOT SILENTLY DROPPED (standing rule 1's second sentence, applied to a catalogue).
+  # Each of these is a real metric `proto/P3-metric-catalog.md` measured and this wave does not
+  # ship, with the CAUSE and the fix — so the next session extends the list instead of
+  # re-measuring, and nobody reads the six as "all Odoo can answer".
+  not_yet:
+    - key: days_since_last_sale
+      cause: "needs `agg: max` over a DATE, which `semantic._measure_sql` does not implement (sum | count | count_distinct only), and a date-typed measure could not render anyway: `aios_grid.MEASURE_FIELD_TYPES` is {currency, int, pct}"
+      fix: "add `agg: max` to `_measure_sql` and express the metric as an INT — `date_diff('day', max(date), today)` — so it renders as a number of days rather than a date. Measured live at 4.61 s over 3,348 SKUs"
+    - key: distinct_orders
+      cause: "`__count` on the live path is LINE count, not ORDER count (12,707 lines vs 12,645 distinct SKU-order pairs); the honest figure needs a 2-level groupby measured at 10.87 s live"
+      fix: "on the STORE path this is `count(DISTINCT l.order_id)` in one pass — add it as a `count_distinct` metric on `sales_lines` with field `order_id`"
+
+# ⭐⭐ W37-T13 — PHYSICAL MOVEMENT. `stock.move` and `stock_location` are mirrored now (the
+# `not_yet` entry that used to sit here said "not mirrored, so there is no store binding to
+# group"; that is what changed). The direction rule is TWO-SIDED and lives in the metrics'
+# `store_filter_sql` — see `model/metrics/stock.yml`, which carries the 58% trap in full.
+- source: stock_moves
+  dim: product_code
+  keys: [stock_in, stock_out, stock_net]
+  not_yet:
+    - key: stock_in_excl_adjustments
+      cause: "adjustments and scrap are ~30% of IN / ~20% of OUT and the two obvious exclusions are NOT equivalent - the 5,320-unit gap between them is entirely `Virtual Locations/Scrap`, so the choice is a business ruling rather than a filter"
+      fix: "ask the owner which exclusion they mean, then add it as a SEPARATE metric with `store_filter_sql` narrowed on `sl.usage`/`sd.usage` - never by changing what `stock_in` means"
+
 # 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.

platform/model/topics/sales_lines.yml

@@ -42,6 +42,19 @@ store:
   dims:
     order_partner: {col: "l.order_partner_id", name_col: "l.order_partner_name", label: "Customer"}
     product:       {col: "l.product_id",       name_col: "l.product_name",       label: "Product"}
+    # ⭐⭐ W37-T10 — THE SKU-CODE DIM, added because a per-SKU metric has to group by the key the
+    # PRODUCT GRID actually carries. `product` above groups by Odoo's `product_id`; the
+    # `odoo_products` database's identity is `default_code` (its own topic file says so), and a
+    # metric keyed on the wrong one is a column of nulls that reads as "this never sold".
+    # ⚠ `COALESCE(NULLIF(...))` REPRODUCES THE GRID'S IDENTITY EXACTLY, including the codeless
+    # fallback: `modules/product_data.py` keys an uncoded active product as `pid:<odoo id>`, so
+    # this expression has to as well or those rows silently lose their metrics.
+    # ⭐ It also MERGES a re-SKUed pair: an archived record and the active one sharing a code are
+    # one product to the grid, and grouping by `product_id` would split them into two.
+    # ⚠ NO `name_col` — the code IS its own label, so `store_query` emits the bare `product_code`
+    # (the value-keyed shape `rollup_sql.group_values` handles beside `payment_state`).
+    product_code:  {col: "COALESCE(NULLIF(pp.default_code, ''), 'pid:' || CAST(pp.id AS VARCHAR))",
+                    label: "SKU code"}
     # team names via CASE (crm_team is not synced; ids are baked tenant scope like the team filter)
     team:          {col: "o.team_id",
                     name_col: "CASE o.team_id WHEN 5 THEN 'Fisch' WHEN 6 THEN 'Royal' ELSE CAST(o.team_id AS VARCHAR) END",

platform/model/topics/stock_moves.yml

@@ -0,0 +1,72 @@
+# ⭐⭐ W37-T13 (owner: stock moved IN and OUT, per SKU, over a lookback window).
+#
+# A DATED EVENT STREAM at move grain — the counterpart to `odoo_products`, which is a
+# catalogue and says so ("a catalogue has no date dimension; ask sales_lines for
+# movement"). This is the topic that answers movement for stock, as `sales_lines` does
+# for revenue.
+#
+# ⛔ EVERY CLAUSE HERE WAS MEASURED, in `proto/P1-stock-moves.md`, against live Odoo.
+# Do not "simplify" one without re-reading it — three of them are traps that produce a
+# plausible wrong number rather than an error.
+key: stock_moves
+label: Stock movement
+entity: stock.move
+domain_builder: ~
+scope:
+  state: "done moves ONLY — a draft/waiting/assigned move is an intention, not a movement"
+  direction: >-
+    DIRECTION IS A PROPERTY OF THE PAIR OF LOCATIONS, never of one. A move is IN when it
+    arrives at an internal location from a non-internal one, and OUT when it leaves an
+    internal location for a non-internal one. internal->internal is 58% of all moves and
+    is NEITHER; counting it as both is the defect a one-sided domain produces.
+  not_picking_code: >-
+    `picking_code` is NOT the discriminator. It is store=False, so a groupby faults, and
+    ('picking_code','=',False) returns 0 while 5,800 pickingless done moves exist - the
+    count that would warn you also reads 0.
+  scale: "236k rows over 1,095 days; cost is FLAT in window length (30d 2.1s .. 1095d 4.0s live)"
+  no_bu: >-
+    `stock.move` has no team_id. Stock is HQ-consolidated, like AR and Inventory - stated
+    as a fact rather than left to read as a missing filter.
+
+grain: "one row per done stock move; time-filterable by move date; NOT BU-filterable"
+
+store:
+  table: stock_move
+  alias: sm
+  # ⛔ BOTH LOCATION JOINS, and they are the whole of the direction rule. `sl` is where it
+  # came FROM, `sd` is where it went TO. Dropping either makes every direction metric
+  # silently one-sided.
+  join: >-
+    LEFT JOIN stock_location sl ON sl.id = sm.location_id
+    LEFT JOIN stock_location sd ON sd.id = sm.location_dest_id
+    LEFT JOIN product_product pp ON pp.id = sm.product_id
+  date_col: "sm.date"
+  # NO team_col — see scope.no_bu. A BU-scoped caller is REFUSED by `store_query` with a
+  # sentence rather than being served a company-wide number wearing a unit's label.
+  scope_sql: "sm.state = 'done'"
+  dims:
+    # ⭐ THE SAME CODE-KEYED SHAPE `sales_lines.product_code` uses, and for the same reason:
+    # the product grid's identity is `default_code`, with `pid:<odoo id>` for the codeless
+    # actives. A dim keyed on Odoo's `product_id` would key every cell on a value no grid
+    # row carries (contract C1's join-key trap).
+    product_code: {col: "COALESCE(NULLIF(pp.default_code, ''), 'pid:' || CAST(pp.id AS VARCHAR))",
+                   label: "SKU code"}
+    product:      {col: "sm.product_id",  name_col: "pp.name",          label: "Product"}
+    source:       {col: "sm.location_id", name_col: "sl.complete_name", label: "From location"}
+    destination:  {col: "sm.location_dest_id", name_col: "sd.complete_name", label: "To location"}
+
+ai_context: >
+  Physical stock movement at move grain, from Odoo `stock.move`, done moves only.
+  Use it for "what came in", "what went out", "what moved" over a window, per SKU or per location.
+  ⛔ DIRECTION IS A PAIR TEST, never a single location: `stock_in` counts moves ARRIVING at an
+  internal location from a non-internal one, `stock_out` counts moves LEAVING an internal location
+  for a non-internal one, and internal-to-internal transfers (58% of all moves) are in NEITHER.
+  Quantities are `quantity_done` — what actually moved — in the product's own unit of measure, so
+  units are NOT comparable across SKUs and must never be summed into one total across products.
+  ⛔ THIS TOPIC HAS NO BUSINESS UNIT. `stock.move` carries no team, so a question scoped to Fisch
+  or Royal cannot be answered here and must be refused rather than answered company-wide.
+  ⚠ Adjustments (`inventory` locations) and scrap are ~30% of IN and ~20% of OUT. `stock_in` and
+  `stock_out` INCLUDE them, because a physical arrival is an arrival however it was booked; use
+  the `source`/`destination` dims to separate them, and say which you did.
+  For SALES movement use sales_lines (revenue and units ordered); this topic is the warehouse,
+  and the two legitimately disagree because an order is not a shipment.

platform/modules/agent.py

@@ -1,277 +1,385 @@
-"""Agent module — per-agent (res.partner.agent_ids) analytics.
-
-An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
-module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
-with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
-trend, returns, top SKUs (with profit/order) and the FULL customer list — INCLUDING inactive
-accounts (no recent orders) so a rep sees who they've stopped selling to.
-
-Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
-so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
-everything else is BU-filterable via team_id.
-"""
-import sys
-import datetime as dt
-from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-import core.odoo as O
-import core.periods as P
-import modules.sales as sales_mod
-import modules.customers as cust_mod
-
-
-def options(t=None, team_id=None):
-    """Agent names with book activity — for the page/drawer picker."""
-    return cust_mod.agent_options(t, team_id)
-
-
-def _book(name):
-    """frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
-    return cust_mod.agent_partner_ids(name)
-
-
-def _rev(date_from, date_to, team_id, book):
-    return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
-                       'amount_untaxed')
-
-
-def _orders(date_from, date_to, team_id, book):
-    return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
-
-
-def _custs(date_from, date_to, team_id, book):
-    return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
-                            'partner_id')
-
-
-# ------------------------------------------------------------ period scorecard (custom dating)
-# Today / WTD / Last week / MTD / QTD / YTD — each carries its window so the UI can decompose it
-# and so "what did this agent sell this/last week" is a click, not a date-math exercise.
-_PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
-            ('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
-
-
-def _window(key, t):
-    if key == 'today':
-        return P._d(t), P._d(t)
-    if key == 'lwk':                       # the full prior Mon–Sun week
-        f, _tt = P.wtd(t)
-        start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
-        return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
-    return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
-
-
-def scorecard(name, t=None, team_id=None):
-    """Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
-    t = t or P.today()
-    book = _book(name)
-    out = []
-    for label, key in _PERIODS:
-        f, tt = _window(key, t)
-        wk = key in ('today', 'wtd', 'lwk')          # weekday-align the short windows' LY compare
-        cf, ct = P.shift_year(f, tt, weeks=wk)
-        rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
-        out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
-                    'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
-                    'orders': _orders(f, tt, team_id, book)})
-    return out
-
-
-def headline(name, date_from, date_to, team_id=None):
-    """Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
-    active customers, AOV and returns $ / return rate."""
-    book = _book(name)
-    cf, ct = P.shift_year(date_from, date_to, weeks=False)
-    rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
-    orders = _orders(date_from, date_to, team_id, book)
-    ret = sales_mod._returns_amt(date_from, date_to, book)
-    return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
-            'revenue': rev, 'revenue_ly': rev_ly,
-            'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
-            'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
-            'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
-
-
-# ------------------------------------------------------------ sales trend
-def _book_monthly_rev(book, date_from, date_to, team_id=None):
-    g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
-                     ['amount_untaxed:sum'], ['date_order:month'], lazy=False)
-    out = {}
-    for r in g:
-        ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
-        if ym:
-            out[ym] = r.get('amount_untaxed') or 0.0
-    return out
-
-
-def monthly(name, n=13, t=None, team_id=None):
-    """Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
-    t = t or P.today()
-    book = _book(name)
-    mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
-    rows = []
-    for ym, _s, _e in P.month_starts(n, t):
-        y, m = int(ym[:4]) - 1, int(ym[5:7])
-        this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
-        rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
-    return rows
-
-
-# ------------------------------------------------------------ full customer book (incl. inactive)
-def customers(name, t=None, team_id=None):
-    """EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) — those
-    show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
-    carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
-    t = t or P.today()
-    book = _book(name)
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this = cust_mod._cust_rev(yf, yt, team_id, book)
-    last = cust_mod._cust_rev(lf, lt, team_id, book)
-    lastord = cust_mod._last_order_dates(None, None, team_id, book)   # all-time last order = recency
-    ids = list(book) if book is not None else list(set(this) | set(last))
-    attrs = cust_mod._partner_attrs(set(ids))
-    namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
-    rows = []
-    for p in ids:
-        tr = this.get(p, {}).get('rev', 0.0)
-        lr = last.get(p, {}).get('rev', 0.0)
-        a = attrs.get(p, {})
-        lo = lastord.get(p, '')
-        recency = (t - dt.date.fromisoformat(lo)).days if lo else None
-        status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
-        rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
-                     'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
-                     'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
-                     'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
-                     'agent': a.get('agent', name)})
-    rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
-    return rows
-
-
-# ------------------------------------------------------------ top SKUs (with profit/order)
-def top_skus(name, t=None, team_id=None, top=30):
-    """The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
-    t = t or P.today()
-    book = _book(name)
-    if book is not None and not book:
-        return []
-    yf, yt = P.ytd(t)
-    lex = [('order_partner_id', 'in', list(book))] if book is not None else None
-    return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
-
-
-# ------------------------------------------------------------ returns (book-scoped, consolidated)
-def returns_trend(name, n=13, t=None):
-    return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
-
-
-def returns_headline(name, t=None):
-    return sales_mod.returns_headline(t, partner_ids=_book(name))
-
-
-# ------------------------------------------------------------ all-agents rollup (the page table)
-def _returns_by_agent(t=None):
-    """{agent_name: returns$ YTD} — credit notes mapped to each customer's agent."""
-    by_p = sales_mod.returns_by_partner(t)
-    attrs = cust_mod._partner_attrs(list(by_p))
-    agg = {}
-    for pid, amt in by_p.items():
-        a = (attrs.get(pid) or {}).get('agent') or '(none)'
-        agg[a] = agg.get(a, 0.0) + amt
-    return agg
-
-
-def rollup(t=None, team_id=None):
-    """Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
-    rate. Reuses the Customers MECE agent rollup, so Σ(agents) == total YTD revenue."""
-    rows = cust_mod.by_dimension('agent', t, team_id=team_id)
-    ret = _returns_by_agent(t)
-    for r in rows:
-        r['agent'] = r['group']
-        r['returns'] = ret.get(r['group'], 0.0)
-        r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
-    return rows
-
-
-# ------------------------------------------------------------ VALIDATION
-def validate(t=None, team_id=None):
-    """Reconcile the agent rollup to Odoo. (1) Σ(agent book revenue) == total YTD revenue — the
-    rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    checks = []
-    rows = rollup(t, team_id=team_id)
-    agent_sum = sum(r['revenue'] for r in rows)
-    total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
-    checks.append({'check': 'YTD revenue: Σ(agent book) == total', 'a': round(agent_sum, 2),
-                   'b': round(total, 2), 'gap': round(agent_sum - total, 2),
-                   'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
-    # sampled agent: scorecard YTD == headline YTD for the same window
-    sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
-    if sample:
-        sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
-        hl = headline(sample, yf, yt, team_id)['revenue']
-        checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
-                       'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
-    return checks
-
-
-# ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
-# A SECOND agent source. Everything above this line attributes by BOOK — the customer's assigned
-# agent (res.partner.agent_ids) — over confirmed SALES ORDERS. This section attributes per INVOICE
-# LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
-# commission_lines). The two disagree on purpose and answer different questions:
-#
-#   book     -> "whose customer is this / who owns the relationship"   (order basis)
-#   invoice  -> "what was actually credited to an agent on the billing" + the ONLY source that can
-#               say what is NOT allocated to an agent                   (invoice basis)
-#
-# ⚠ A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT — `res.partner.agent` is the flag.
-# "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
-# dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
-# See [[invoice-line-agent-commission]].
-
-_ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
-                'none': 'Not allocated'}
-
-
-def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
-    """Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
-
-    Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
-             'unallocated': float, 'basis': str} — or {'error': msg} when the tenant store is not
-    ready (this path is store-only; there is no live fallback that stays honest about the
-    unallocated bucket).
-    """
-    import harness.semantic as S
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    dim = 'commission_name' if include_salespeople else 'agent'
-    try:
-        by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
-                           date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
-        alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
-                              date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
-        tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
-                             team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
-    except Exception as e:                       # store not ready / model error — say so, don't fake
-        return {'error': str(e)}
-    # store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
-    # (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
-    # returns None for every row and silently renders the whole table as "no agent".
-    rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
-             'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
-    rows.sort(key=lambda r: -r['revenue'])
-    amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
-    allocated = amap.get('agent', 0.0)
-    return {
-        'by_agent': rows,
-        'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
-                       for k in ('agent', 'salesperson', 'none') if k in amap or True],
-        'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
-        'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
-        'window': (yf, yt),
-        'basis': ('invoice line · commission names incl. salespeople' if include_salespeople
-                  else 'invoice line · real agents only'),
-    }
+"""Agent module — per-agent (res.partner.agent_ids) analytics.
+
+An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
+module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
+with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
+trend, returns, top SKUs (with profit/order) and the FULL customer list — INCLUDING inactive
+accounts (no recent orders) so a rep sees who they've stopped selling to.
+
+Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
+so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
+everything else is BU-filterable via team_id.
+"""
+import sys
+import datetime as dt
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import core.odoo as O
+import core.periods as P
+import modules.sales as sales_mod
+import modules.customers as cust_mod
+
+
+def options(t=None, team_id=None):
+    """Agent names with book activity — for the page/drawer picker."""
+    return cust_mod.agent_options(t, team_id)
+
+
+def _book(name):
+    """frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
+    return cust_mod.agent_partner_ids(name)
+
+
+def _rev(date_from, date_to, team_id, book):
+    return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
+                       'amount_untaxed')
+
+
+def _orders(date_from, date_to, team_id, book):
+    return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
+
+
+def _custs(date_from, date_to, team_id, book):
+    return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
+                            'partner_id')
+
+
+# ------------------------------------------------------------ period scorecard (custom dating)
+# Today / WTD / Last week / MTD / QTD / YTD — each carries its window so the UI can decompose it
+# and so "what did this agent sell this/last week" is a click, not a date-math exercise.
+_PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
+            ('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
+
+
+def _window(key, t):
+    if key == 'today':
+        return P._d(t), P._d(t)
+    if key == 'lwk':                       # the full prior Mon–Sun week
+        f, _tt = P.wtd(t)
+        start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
+        return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
+    return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
+
+
+def scorecard(name, t=None, team_id=None):
+    """Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
+    t = t or P.today()
+    book = _book(name)
+    out = []
+    for label, key in _PERIODS:
+        f, tt = _window(key, t)
+        wk = key in ('today', 'wtd', 'lwk')          # weekday-align the short windows' LY compare
+        cf, ct = P.shift_year(f, tt, weeks=wk)
+        rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
+        out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
+                    'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
+                    'orders': _orders(f, tt, team_id, book)})
+    return out
+
+
+def headline(name, date_from, date_to, team_id=None):
+    """Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
+    active customers, AOV and returns $ / return rate."""
+    book = _book(name)
+    cf, ct = P.shift_year(date_from, date_to, weeks=False)
+    rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
+    orders = _orders(date_from, date_to, team_id, book)
+    ret = sales_mod._returns_amt(date_from, date_to, book)
+    return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
+            'revenue': rev, 'revenue_ly': rev_ly,
+            'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
+            'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
+            'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
+
+
+# ------------------------------------------------------------ sales trend
+def _book_monthly_rev(book, date_from, date_to, team_id=None):
+    g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
+                     ['amount_untaxed:sum'], ['date_order:month'], lazy=False)
+    out = {}
+    for r in g:
+        ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
+        if ym:
+            out[ym] = r.get('amount_untaxed') or 0.0
+    return out
+
+
+def monthly(name, n=13, t=None, team_id=None):
+    """Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
+    t = t or P.today()
+    book = _book(name)
+    mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
+    rows = []
+    for ym, _s, _e in P.month_starts(n, t):
+        y, m = int(ym[:4]) - 1, int(ym[5:7])
+        this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
+        rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
+    return rows
+
+
+# ------------------------------------------------------------ full customer book (incl. inactive)
+def customers(name, t=None, team_id=None):
+    """EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) — those
+    show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
+    carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
+    t = t or P.today()
+    book = _book(name)
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this = cust_mod._cust_rev(yf, yt, team_id, book)
+    last = cust_mod._cust_rev(lf, lt, team_id, book)
+    lastord = cust_mod._last_order_dates(None, None, team_id, book)   # all-time last order = recency
+    ids = list(book) if book is not None else list(set(this) | set(last))
+    attrs = cust_mod._partner_attrs(set(ids))
+    namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
+    rows = []
+    for p in ids:
+        tr = this.get(p, {}).get('rev', 0.0)
+        lr = last.get(p, {}).get('rev', 0.0)
+        a = attrs.get(p, {})
+        lo = lastord.get(p, '')
+        recency = (t - dt.date.fromisoformat(lo)).days if lo else None
+        status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
+        rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
+                     'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
+                     'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
+                     'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
+                     'agent': a.get('agent', name)})
+    rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
+    return rows
+
+
+# ------------------------------------------------------------ top SKUs (with profit/order)
+def top_skus(name, t=None, team_id=None, top=30):
+    """The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
+    t = t or P.today()
+    book = _book(name)
+    if book is not None and not book:
+        return []
+    yf, yt = P.ytd(t)
+    lex = [('order_partner_id', 'in', list(book))] if book is not None else None
+    return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
+
+
+# ------------------------------------------------------------ returns (book-scoped, consolidated)
+def returns_trend(name, n=13, t=None):
+    return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
+
+
+def returns_headline(name, t=None):
+    return sales_mod.returns_headline(t, partner_ids=_book(name))
+
+
+# ------------------------------------------------------------ all-agents rollup (the page table)
+def _returns_by_agent(t=None):
+    """{agent_name: returns$ YTD} — credit notes mapped to each customer's agent."""
+    by_p = sales_mod.returns_by_partner(t)
+    attrs = cust_mod._partner_attrs(list(by_p))
+    agg = {}
+    for pid, amt in by_p.items():
+        a = (attrs.get(pid) or {}).get('agent') or '(none)'
+        agg[a] = agg.get(a, 0.0) + amt
+    return agg
+
+
+def rollup(t=None, team_id=None):
+    """Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
+    rate. Reuses the Customers MECE agent rollup, so Σ(agents) == total YTD revenue."""
+    rows = cust_mod.by_dimension('agent', t, team_id=team_id)
+    ret = _returns_by_agent(t)
+    for r in rows:
+        r['agent'] = r['group']
+        r['returns'] = ret.get(r['group'], 0.0)
+        r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
+    return rows
+
+
+# ------------------------------------------------------------ VALIDATION
+def validate(t=None, team_id=None):
+    """Reconcile the agent rollup to Odoo. (1) Σ(agent book revenue) == total YTD revenue — the
+    rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    checks = []
+    rows = rollup(t, team_id=team_id)
+    agent_sum = sum(r['revenue'] for r in rows)
+    total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
+    checks.append({'check': 'YTD revenue: Σ(agent book) == total', 'a': round(agent_sum, 2),
+                   'b': round(total, 2), 'gap': round(agent_sum - total, 2),
+                   'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
+    # sampled agent: scorecard YTD == headline YTD for the same window
+    sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
+    if sample:
+        sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
+        hl = headline(sample, yf, yt, team_id)['revenue']
+        checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
+                       'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
+    checks.extend(validate_measures(t=t, team_id=team_id))
+    return checks
+
+
+def validate_measures(t=None, team_id=None, days=90):
+    """⭐⭐ W37-T12 — the minted PER-AGENT lookback columns, against a DIRECT Odoo aggregate.
+
+    ⛔ WHICH AGENT SOURCE, AND THE TICKET REQUIRES IT SAID OUT LOUD: this reconciles ROUTE 1, the
+    CUSTOMER-MASTER BOOK (`res.partner.agent_ids` -> the mirror's `res_partner.agent_id`, which is
+    `sales_lines`' `agent` dim). It is NOT the OCA commission route below — measured 2026-08-19,
+    9 agents carry route-1 revenue against 12 on commission lines and 17 carrying the flag, so the
+    two produce materially different rankings and a check that mixed them would be comparing two
+    different questions and calling the gap an error.
+
+    ⚠ THE ORACLE IS THE ORDER HEADER, not the mirror the columns are served from. `sale.order`
+    grouped by `partner_id`, mapped to each customer's agent CLIENT-SIDE — a different model, a
+    different grain and a different code path from `store_query`'s line-level sum, so agreement
+    between them is evidence rather than tautology.
+    ⚠ Windowed to the MIRROR'S newest order, like `product_data.validate_measures`, so the
+    residual is about EDITS to a shared period and not about orders the mirror has never seen.
+    """
+    from harness import datastore as DS
+    from harness import semantic as sem
+
+    t = t or P.today()
+    checks = []
+    try:
+        if not DS.ready():
+            return [{'check': 'agent lookback measures reconcile to Odoo', 'a': 'no mirror',
+                     'b': '-', 'ok': False,
+                     'detail': 'the tenant store is not readable, so this is UNPROVEN, which standing rule '
+                               '8 does not accept as green'}]
+    except Exception as e:                                             # noqa: BLE001
+        return [{'check': 'agent lookback measures reconcile to Odoo', 'a': type(e).__name__,
+                 'b': '-', 'ok': False, 'detail': str(e)[:200]}]
+
+    offer = sem.entity_measures('odoo_agents')
+    checks.append({'check': 'the agent measure OFFER is non-empty and every key resolves '
+                            '(owner item 4 / R1)',
+                   'a': len(offer), 'b': '>0', 'ok': bool(offer),
+                   'detail': {'keys': [m['key'] for m in offer],
+                              'refused': sem.entity_measure_refusals('odoo_agents')}})
+    if not offer:
+        return checks
+
+    con = DS.ro_cursor()
+    try:
+        newest = con.execute('SELECT max(date_order) FROM sale_order').fetchone()
+    finally:
+        con.close()
+    d_to = t - dt.timedelta(days=2)
+    if newest and newest[0]:
+        try:
+            d_to = min(d_to, dt.date.fromisoformat(str(newest[0])[:10]) - dt.timedelta(days=1))
+        except ValueError:
+            pass
+    d_from = d_to - dt.timedelta(days=days)
+    DF, DT = d_from.isoformat(), d_to.isoformat()
+
+    ours = sem.entity_measure_values('odoo_agents', ['revenue'], date_from=DF, date_to=DT,
+                                     team_id=team_id, offer=offer)
+    # THE ORACLE — order headers, grouped by customer, mapped to that customer's agent here.
+    o = O.get_odoo()
+    grp = o.read_group('sale.order', sales_mod.order_domain(DF, DT, team_id),
+                       ['partner_id', 'amount_untaxed:sum'], ['partner_id'], lazy=False)
+    pids = sorted({r['partner_id'][0] for r in grp if r.get('partner_id')})
+    agent_of = {}
+    for i in range(0, len(pids), 500):
+        for p in o.search_read('res.partner', [('id', 'in', pids[i:i + 500])],
+                               ['id', 'agent_ids']):
+            ag = (p.get('agent_ids') or [])
+            if ag:
+                agent_of[p['id']] = ag[0]          # the Customers-module convention: agent_ids[0]
+    theirs = {}
+    for r in grp:
+        if not r.get('partner_id'):
+            continue
+        a = agent_of.get(r['partner_id'][0])
+        if a is not None:
+            theirs[a] = theirs.get(a, 0.0) + r['amount_untaxed']
+
+    ours_tot = round(sum(c.get('revenue', 0) for c in ours.values()), 2)
+    theirs_tot = round(sum(theirs.values()), 2)
+    # ⚠ ORDER-HEADER vs LINE-SUM is a REAL basis difference (an order's untaxed total includes
+    # lines this topic's service filter drops), so the tolerance is a stated 3% rather than a
+    # cent — and the FIGURE is reported so a drift is readable instead of absorbed.
+    gap = ours_tot - theirs_tot
+    checks.append({
+        'check': 'per-agent revenue (BOOK route) vs an INDEPENDENT Odoo order-header aggregate '
+                 'mapped through res.partner.agent_ids',
+        'a': ours_tot, 'b': theirs_tot, 'gap': round(gap, 2),
+        'ok': bool(theirs_tot) and abs(gap) <= 0.03 * theirs_tot,
+        'detail': {'window': [DF, DT], 'agents_ours': len(ours), 'agents_theirs': len(theirs),
+                   'gap_pct': round(gap / theirs_tot * 100, 3) if theirs_tot else None,
+                   'route': 'customer-master book (res.partner.agent_ids), NOT the OCA '
+                            'commission table; the two name different people'}})
+    # ⛔ AND PER AGENT, because a total can agree while every row is keyed wrong — the join-key
+    # trap contract C1 names. Here the key is the `res.partner` id at both ends.
+    off_by = sorted(((abs(ours.get(a, {}).get('revenue', 0.0) - v), a)
+                     for a, v in theirs.items() if v), reverse=True)
+    bad = [(a, round(ours.get(a, {}).get('revenue', 0.0), 2), round(theirs[a], 2))
+           for d, a in off_by if d > 0.03 * theirs[a]]
+    checks.append({
+        'check': 'each agent\'s own figure ties (the C1 join-key test: a wrong key agrees in '
+                 'total and disagrees on every row)',
+        'a': len(bad), 'b': 0, 'ok': not bad,
+        'detail': {'worst': [(a, ours_v, th_v) for a, ours_v, th_v in bad[:5]],
+                   'agents_compared': len(theirs)}})
+    return checks
+
+
+# ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
+# A SECOND agent source. Everything above this line attributes by BOOK — the customer's assigned
+# agent (res.partner.agent_ids) — over confirmed SALES ORDERS. This section attributes per INVOICE
+# LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
+# commission_lines). The two disagree on purpose and answer different questions:
+#
+#   book     -> "whose customer is this / who owns the relationship"   (order basis)
+#   invoice  -> "what was actually credited to an agent on the billing" + the ONLY source that can
+#               say what is NOT allocated to an agent                   (invoice basis)
+#
+# ⚠ A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT — `res.partner.agent` is the flag.
+# "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
+# dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
+# See [[invoice-line-agent-commission]].
+
+_ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
+                'none': 'Not allocated'}
+
+
+def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
+    """Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
+
+    Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
+             'unallocated': float, 'basis': str} — or {'error': msg} when the tenant store is not
+    ready (this path is store-only; there is no live fallback that stays honest about the
+    unallocated bucket).
+    """
+    import harness.semantic as S
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    dim = 'commission_name' if include_salespeople else 'agent'
+    try:
+        by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
+                           date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
+        alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
+                              date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
+        tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
+                             team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
+    except Exception as e:                       # store not ready / model error — say so, don't fake
+        return {'error': str(e)}
+    # store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
+    # (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
+    # returns None for every row and silently renders the whole table as "no agent".
+    rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
+             'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
+    rows.sort(key=lambda r: -r['revenue'])
+    amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
+    allocated = amap.get('agent', 0.0)
+    return {
+        'by_agent': rows,
+        'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
+                       for k in ('agent', 'salesperson', 'none') if k in amap or True],
+        'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
+        'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
+        'window': (yf, yt),
+        'basis': ('invoice line · commission names incl. salespeople' if include_salespeople
+                  else 'invoice line · real agents only'),
+    }

platform/modules/product_data.py

@@ -51,6 +51,7 @@ template and this deliberately mirrors its signature and its row shape.
        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 datetime as _dt
 import json
 import zlib
 from pathlib import Path
@@ -391,6 +392,17 @@ def pool(team_id=None, t=None):
     bu_share = {} if consolidated else _bu_ltm_share(t, team_id)
     sup = supplier_master()
     prices, _price_report = _pricelist_by_code()
+    # ⭐ W37-T14 / T15. ⚠ MEASURED COST, stated because it lands on a scope's FIRST build:
+    # tier prices 15.1 s + packagings 8.1 s on top of the ~44 s consolidated build. Only the
+    # first build for a scope blocks (`routes_products._pool_for`'s stale-while-refresh), and
+    # both degrade to `{}` on a read failure rather than taking the grid down — the same
+    # asymmetry `pricelist_by_code` documents: a column is not the ROW SET.
+    try:
+        _prods = products.active_products()      # ONE read, shared by both (see its docstring)
+    except Exception:                                                  # noqa: BLE001
+        _prods = None
+    tiers, _tier_report = products.tier_prices_by_code(_prods)
+    packs, _pack_report = products.packagings_by_code(_prods)
     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
@@ -437,6 +449,19 @@ def pool(team_id=None, t=None):
         p = prices.get(code) or {}
         for _col, _name in products.PRICELIST_COLUMNS:
             row[_col] = p.get(_col)
+        # ⭐⭐ W37-T14 / T15 — THE HONEST SETS, beside the three declared columns rather than
+        # instead of them. The columns above answer "what does Fisch charge"; these answer "how
+        # many prices/units does this SKU actually have", which the columns structurally cannot:
+        # they are named after THIS tenant's lists, so a price on any other list is invisible.
+        # ⚠ A `json` cell is a STRING on the wire (the type's own contract), so these are dumped
+        # here rather than handed over as lists — a bare list would round-trip through the overlay
+        # as something `grid_events` refuses to re-parse.
+        # ⚠ BLANK, NOT "[]" — an empty cell reads as "sold in one unit / not priced on any list",
+        # and an empty JSON array on screen reads as a bug.
+        _tiers = tiers.get(code)
+        row["tier_prices"] = json.dumps(_tiers, ensure_ascii=False) if _tiers else None
+        _units = packs.get(code)
+        row["units"] = json.dumps(_units, ensure_ascii=False) if _units else None
         # Wave 17 R3 — the supplier master, on every pull (it is catalogue data, not stock).
         s = sup.get(code) or {}
         row.update({
@@ -801,4 +826,390 @@ def validate(team_id=None, t=None):
                        # have silently dropped. 0 today does not make that filter correct.
                        "cover_gap_rounds_to_zero": len(rounding_would_miss)},
         })
+    checks.extend(validate_measures(t=t, team_id=team_id,
+                                    pool_codes={r["code"] for r in rows}))
+    checks.extend(validate_price_and_unit_cells(rows))
+    checks.extend(validate_stock_measures(t=t))
+    return checks
+
+
+def validate_stock_measures(t=None, days=90, sample=4):
+    """⭐⭐ W37-T13 — `stock_in` / `stock_out` per SKU, against a DIRECT live Odoo `read_group`.
+
+    ⛔ THE TWO-SIDED DOMAIN IS REPRODUCED ON THE LIVE SIDE, and getting it wrong there would hide
+    exactly the defect this validates. `location_id.usage` is a DOT-PATH FILTER, which Odoo
+    supports; a dot-path GROUPBY faults, which is why the direction is expressed as two separate
+    filtered reads rather than one grouped-by-usage read (`proto/P1-stock-moves.md`, gotcha 1).
+
+    ⛔ AND THE DIRECTION SPLIT IS ASSERTED, NOT ASSUMED. A one-sided domain produces IN == OUT for
+    every internal transfer, so a run where the two columns agree everywhere is the signature of
+    the bug rather than of a quiet warehouse. The last leg requires a SKU where they genuinely
+    differ — the ticket's own `done-when` clause, and the only one a total cannot fake.
+    """
+    from harness import datastore as DS
+    from harness import semantic as sem
+
+    t = t or P.today()
+    checks = []
+    offer = sem.entity_measures("odoo_products")
+    keys = [m["key"] for m in offer if m["key"].startswith("stock_")]
+    if not keys:
+        why = [r for r in sem.entity_measure_refusals("odoo_products")
+               if str(r.get("key", "")).startswith("stock_")]
+        return [{"check": "the product catalogue offers Stock moved in / out (W37-T13)",
+                 "ours": 0, "theirs": 3, "ok": False,
+                 # ⭐ The refusal carries its own cause — reported, not inferred from an absence.
+                 "detail": {"refusals": why or "no stock binding declared"}}]
+    checks.append({"check": "the product measure catalogue offers the stock-movement keys "
+                            "(W37-T13)", "ours": sorted(keys), "theirs": 3,
+                   "ok": {"stock_in", "stock_out"} <= set(keys)})
+
+    con = DS.ro_cursor()
+    try:
+        newest = con.execute("SELECT max(date) FROM stock_move").fetchone()
+    finally:
+        con.close()
+    d_to = t - _dt.timedelta(days=2)
+    if newest and newest[0]:
+        try:
+            d_to = min(d_to, _dt.date.fromisoformat(str(newest[0])[:10]) - _dt.timedelta(days=1))
+        except ValueError:
+            pass
+    d_from = d_to - _dt.timedelta(days=days)
+    DF, DT = d_from.isoformat(), d_to.isoformat()
+    ours = sem.entity_measure_values("odoo_products", ["stock_in", "stock_out"],
+                                     date_from=DF, date_to=DT, offer=offer)
+
+    o = O.get_odoo()
+    base = [("state", "=", "done"),
+            ("date", ">=", f"{DF} 00:00:00"), ("date", "<=", f"{DT} 23:59:59")]
+    IN = base + [("location_dest_id.usage", "=", "internal"),
+                 ("location_id.usage", "!=", "internal")]
+    OUT = base + [("location_id.usage", "=", "internal"),
+                  ("location_dest_id.usage", "!=", "internal")]
+    live = {}
+    for dom, side in ((IN, "stock_in"), (OUT, "stock_out")):
+        for r in o.read_group("stock.move", dom, ["product_id", "quantity_done:sum"],
+                              ["product_id"], lazy=False):
+            if not r.get("product_id"):
+                continue
+            live.setdefault(r["product_id"][0], {})[side] = r["quantity_done"]
+    code_of = _codes_of_odoo_products(o, list(live))
+    by_code = {}
+    for pid_, v in live.items():
+        c = code_of.get(pid_, f"pid:{pid_}")
+        d = by_code.setdefault(c, {"stock_in": 0.0, "stock_out": 0.0})
+        for k in ("stock_in", "stock_out"):
+            d[k] += v.get(k, 0.0)
+
+    for side in ("stock_in", "stock_out"):
+        a = round(sum(c.get(side, 0) for c in ours.values()), 2)
+        b = round(sum(c.get(side, 0) for c in by_code.values()), 2)
+        checks.append({
+            "check": f"{side}: the mirror's per-SKU total vs a DIRECT Odoo read_group under the "
+                     f"SAME two-sided location domain",
+            "ours": a, "theirs": b, "gap": round(a - b, 2),
+            "ok": bool(b) and abs(a - b) <= 0.02 * b,
+            "detail": {"window": [DF, DT], "skus_ours": len(ours), "skus_odoo": len(by_code)}})
+
+    # ⛔ THE NAMED SKU, and it is chosen for DIFFERING — see the docstring.
+    diff = sorted(((abs((c.get("stock_in") or 0) - (c.get("stock_out") or 0)), k)
+                   for k, c in ours.items()), reverse=True)[:sample]
+    named = []
+    for _d, k in diff:
+        named.append({"sku": k,
+                      "ours": {s: round(ours[k].get(s, 0), 2) for s in ("stock_in", "stock_out")},
+                      "odoo": {s: round((by_code.get(k) or {}).get(s, 0), 2)
+                               for s in ("stock_in", "stock_out")}})
+    off = [n for n in named
+           if any(abs(n["ours"][s] - n["odoo"][s]) > max(0.01, 0.02 * (n["odoo"][s] or 1))
+                  for s in ("stock_in", "stock_out"))]
+    checks.append({
+        "check": f"each NAMED SKU's in/out ties to Odoo ({len(named)} SKUs, picked for the "
+                 f"largest in-vs-out difference)",
+        "ours": len(off), "theirs": 0, "ok": not off,
+        "detail": {"named": named[:3], "mismatched": off[:2]}})
+    genuinely_split = [n for n in named if n["ours"]["stock_in"] != n["ours"]["stock_out"]]
+    checks.append({
+        "check": "⛔ the DIRECTION SPLIT is real: at least one SKU where IN and OUT genuinely "
+                 "differ. A one-sided domain makes them equal for every internal transfer, so "
+                 "all-equal is the SIGNATURE OF THE BUG, not a quiet warehouse",
+        "ours": len(genuinely_split), "theirs": ">=1", "ok": bool(genuinely_split),
+        "detail": {"example": genuinely_split[0] if genuinely_split else None}})
+    return checks
+
+
+def validate_price_and_unit_cells(rows, sample=6):
+    """⭐⭐ W37-T14 / T15 — the `Tier prices` and `Units` cells, against a FRESH Odoo read.
+
+    ⛔ THE ORACLE IS ASKED PER SKU, not in bulk, and deliberately so: the builders group a
+    bulk read in Python, so re-running the same bulk read would re-run the same grouping and
+    could only ever agree with itself. Asking Odoo for ONE SKU's price rules is a different
+    question shape and can actually disagree ([[no-unverifiable-aggregates]]).
+
+    ⚠ WHAT IS NOT PROVEN HERE, said rather than implied: that a PERSON sees the cell. These are
+    `json` columns on the product grid and the render is the client's; the data half is what a
+    module `validate()` can reach.
+    """
+    checks = []
+    priced = [r for r in rows if r.get("tier_prices")]
+    united = [r for r in rows if r.get("units")]
+    checks.append({
+        "check": "the product grid serves a Tier-prices cell (W37-T14) and a Units cell (T15); "
+                 "a DECLARED column that is never filled is the defect these replace",
+        "ours": {"with_tier_prices": len(priced), "with_units": len(united), "rows": len(rows)},
+        "theirs": ">0 each",
+        # ⚠ Units are legitimately sparse (19.6% measured), so the floor is existence, not a rate.
+        "ok": bool(priced) and bool(united),
+        "detail": {"multi_price_skus": sum(1 for r in priced
+                                           if len(json.loads(r["tier_prices"])) > 1)},
+    })
+    if not priced:
+        return checks
+    o = O.get_odoo()
+    pls = {p["id"]: str(p.get("name") or "").strip()
+           for p in O.search_read("product.pricelist", [], ["id", "name"])}
+    today = P.today().isoformat()
+    # Prefer SKUs that carry MORE THAN ONE price — the ticket's own subject.
+    cand = sorted(priced, key=lambda r: -len(json.loads(r["tier_prices"])))[:sample]
+    bad = []
+    for r in cand:
+        mine = sorted((t["pricelist"], round(float(t["unit_price"]), 2))
+                      for t in json.loads(r["tier_prices"]))
+        pid = r.get("product_id")
+        tmpl = None
+        if pid:
+            rec = o.search_read("product.product", [("id", "=", pid)], ["product_tmpl_id"])
+            tmpl = O.m2o_id(rec[0].get("product_tmpl_id")) if rec else None
+        dom = [("compute_price", "=", "fixed"),
+               "|", ("date_start", "=", False), ("date_start", "<=", today),
+               "|", ("date_end", "=", False), ("date_end", ">=", today),
+               ("fixed_price", ">", 0),
+               "|", ("product_id", "=", pid), ("product_tmpl_id", "=", tmpl)]
+        live = o.search_read("product.pricelist.item", dom,
+                             ["pricelist_id", "fixed_price", "min_quantity", "applied_on"])
+        best = {}
+        for it in live:
+            nm = pls.get(O.m2o_id(it.get("pricelist_id")), "?")
+            q = it.get("min_quantity") or 0.0
+            if nm not in best or q < best[nm][0]:
+                best[nm] = (q, round(it.get("fixed_price") or 0.0, 2))
+        theirs = sorted((nm, v) for nm, (q, v) in best.items())
+        # ⚠ A code carried by TWO active products legitimately holds MORE entries than a single
+        # product's rules (D-309 / `2112-12`), so ours is a SUPERSET, never an equality.
+        if not set(theirs) <= set(mine):
+            bad.append({"sku": r.get("code"), "ours": mine, "odoo": theirs})
+    checks.append({
+        "check": f"each sampled SKU's Tier prices contain every live Odoo price for it "
+                 f"({len(cand)} SKUs, chosen for having the MOST prices)",
+        "ours": len(bad), "theirs": 0, "ok": not bad,
+        "detail": {"mismatches": bad[:3],
+                   "sampled": [r.get("code") for r in cand]},
+    })
+    return checks
+
+
+def _codes_of_odoo_products(o, ids):
+    """`{odoo product id: the identity key the GRID uses}` — `default_code`, or `pid:<id>`.
+
+    ⚠ BATCHED, 500 at a time. One call per id is ~1,700 XML-RPC round trips on this window and
+    turns a 5-second reconciliation into a coffee break.
+    ⚠ `active in [True, False]`: a re-SKUed line points at the ARCHIVED record and the grid
+    merges it under the surviving code, so an active-only read would key it `pid:<id>` and
+    manufacture a mismatch this check would then report as a defect.
+    """
+    ids = sorted({i for i in ids if i})
+    out = {}
+    for i in range(0, len(ids), 500):
+        for p in o.search_read('product.product',
+                               [('id', 'in', ids[i:i + 500]), ('active', 'in', [True, False])],
+                               ['default_code']):
+            out[p['id']] = p.get('default_code') or f"pid:{p['id']}"
+    return {i: out.get(i, f"pid:{i}") for i in ids}
+
+
+def validate_measures(t=None, team_id=None, days=90, pool_codes=None):
+    """⭐⭐ W37-T10 — THE MINTED LOOKBACK MEASURES, against a DIRECT Odoo `read_group`.
+
+    Standing rule 8: a number that does not tie to Odoo does not ship. These columns are minted
+    from the tenant MIRROR (`semantic.entity_measure_values`), so the oracle has to be the live
+    ERP and nothing derived from the mirror — otherwise both sides come from the same place and
+    the check cannot fail, which is the self-sealing shape `validate()`'s own header records
+    costing a wave.
+
+    ⛔⛔ THE MIRROR IS BEHIND LIVE, ALWAYS, AND THAT IS NOT A DEFECT — so a bare equality here
+    would be RED every day and would teach everyone to ignore it. The reconciliation is therefore
+    two-legged, and the second leg is the one that carries the meaning:
+
+      leg 1  totals agree within the lag, and the lag is REPORTED as a number, not a tolerance;
+      leg 2  ⭐ EVERY line-level difference traces to a line ODOO WROTE AFTER THE MIRROR'S OWN
+             WATERMARK. This is what makes the check falsifiable: a join bug produces differences
+             on lines the mirror holds perfectly, and leg 2 goes red on the first one.
+
+    ⚠ Do NOT "fix" leg 2 by filtering the live side on `write_date <= watermark` and comparing
+    totals — MEASURED 2026-08-19, that is a far worse instrument: confirming an order touches its
+    lines' `write_date` without changing a value, so the filter drops thousands of lines the
+    mirror holds correctly and the gap grows from $425 to $140,030.
+    """
+    from harness import datastore as DS
+    from harness import semantic as sem
+
+    t = t or P.today()
+    checks = []
+    try:
+        if not DS.ready():
+            return [{"check": "product lookback measures reconcile to Odoo",
+                     "ours": "no mirror", "theirs": "-", "ok": False,
+                     "detail": "the tenant store is not readable, so the measures are UNPROVEN, "
+                               "and an unproven aggregate is exactly what standing rule 8 bars"}]
+    except Exception as e:                                             # noqa: BLE001
+        return [{"check": "product lookback measures reconcile to Odoo",
+                 "ours": f"{type(e).__name__}", "theirs": "-", "ok": False, "detail": str(e)[:200]}]
+
+    # ⛔ THE WINDOW END COMES FROM THE MIRROR, NOT FROM `today`, and this was measured the wrong
+    # way round first. A window ending today reaches past what the mirror has ever seen: orders
+    # placed since the last sync exist live and NOWHERE in the store, so the totals leg reported
+    # a 2.69% "lag" that was really "the last three days do not exist here yet". Anchoring on the
+    # mirror's own newest order makes the comparison one about EDITS to a shared period — which
+    # is the only difference that could indicate a join bug.
+    con = DS.ro_cursor()
+    try:
+        _newest = con.execute("SELECT max(date_order) FROM sale_order").fetchone()
+    finally:
+        con.close()
+    d_to = t - _dt.timedelta(days=2)
+    if _newest and _newest[0]:
+        _n = str(_newest[0])[:10]
+        try:
+            # one day INSIDE the mirror's newest order: the final day may be half-synced.
+            d_to = min(d_to, _dt.date.fromisoformat(_n) - _dt.timedelta(days=1))
+        except ValueError:
+            pass
+    d_from = d_to - _dt.timedelta(days=days)
+    DF, DT = d_from.isoformat(), d_to.isoformat()
+
+    offer = sem.entity_measures("odoo_products")
+    checks.append({
+        "check": "the product measure OFFER is non-empty and every key it names resolves in the "
+                 "semantic model (owner item 4 / R1)",
+        "ours": len(offer), "theirs": ">0", "ok": len(offer) > 0,
+        "detail": {"keys": [m["key"] for m in offer],
+                   # ⭐ The REPORTING half of standing rule 1: a declared key that dropped out
+                   # says why, rather than being quietly absent from a list nobody diffs.
+                   "refused": sem.entity_measure_refusals("odoo_products")},
+    })
+    if not offer:
+        return checks
+    missing_family = [m["key"] for m in offer if m.get("empty") not in ("zero", "blank")]
+    checks.append({
+        "check": "every offered measure declares an EMPTY-WINDOW family (C1: additive->0, "
+                 "ratio->blank), because 72% of this catalogue has no group in a 90-day window",
+        "ours": len(missing_family), "theirs": 0, "ok": not missing_family,
+        "detail": {"undeclared": missing_family},
+    })
+
+    store = sem.entity_measure_values("odoo_products", ["revenue", "units", "margin"],
+                                      date_from=DF, date_to=DT, exclude_services=False,
+                                      offer=offer)
+    o = O.get_odoo()
+    # ⛔ ASKED OF ODOO DIRECTLY, grouped by Odoo's OWN product id — deliberately NOT by the SKU
+    # code the mirror joins on, so the oracle cannot inherit our join key.
+    g = o.read_group('sale.order.line', O.sale_line_domain(DF, DT),
+                     ['product_id', 'price_subtotal:sum', 'product_uom_qty:sum', 'margin:sum'],
+                     ['product_id'], lazy=False)
+    live_tot = {"revenue": round(sum(r['price_subtotal'] for r in g), 2),
+                "units": round(sum(r['product_uom_qty'] for r in g), 2),
+                "margin": round(sum(r['margin'] for r in g), 2)}
+    ours_tot = {k: round(sum(v.get(k, 0) for v in store.values()), 2)
+                for k in ("revenue", "units", "margin")}
+
+    # leg 2 — the falsifiable one. Every discrepant LINE must post-date the mirror's watermark.
+    con = DS.ro_cursor()
+    try:
+        wm = con.execute("SELECT cursor_wd FROM _sync_state WHERE entity = 'sale_order_line'"
+                         ).fetchone()
+        wm = wm[0] if wm else None
+        rows = con.execute(
+            "SELECT l.id, l.price_subtotal FROM sale_order_line l "
+            "JOIN sale_order o ON o.id = l.order_id "
+            "WHERE o.state IN ('sale','done') AND o.team_id IN (5,6) "
+            "  AND l.product_id IS NOT NULL "
+            "  AND l.order_partner_id NOT IN "
+            "      (SELECT id FROM res_partner WHERE name LIKE 'GIFTWARE%') "
+            "  AND CAST(o.date_order AS TIMESTAMP) >= ? AND CAST(o.date_order AS TIMESTAMP) <= ?",
+            [f"{DF} 00:00:00", f"{DT} 23:59:59"]).fetchall()
+    finally:
+        con.close()
+    mine = {r[0]: (r[1] or 0.0) for r in rows}
+    theirs = {r['id']: (r['price_subtotal'] or 0.0) for r in
+              o.search_read('sale.order.line', O.sale_line_domain(DF, DT),
+                            ['id', 'price_subtotal', 'write_date'])}
+    wd = {r['id']: str(r['write_date']) for r in
+          o.search_read('sale.order.line', O.sale_line_domain(DF, DT), ['id', 'write_date'])}
+    discrepant = [i for i, v in theirs.items()
+                  if i not in mine or abs(mine[i] - v) >= 0.005]
+    unexplained = [i for i in discrepant if not wm or wd.get(i, '') <= str(wm)]
+    checks.append({
+        "check": "every per-SKU measure difference vs live Odoo traces to a line Odoo wrote "
+                 "AFTER the mirror's watermark, because a join bug would differ on a mirrored line",
+        "ours": len(unexplained), "theirs": 0, "ok": not unexplained,
+        "detail": {"lines_compared": len(theirs), "discrepant": len(discrepant),
+                   "explained_by_mirror_lag": len(discrepant) - len(unexplained),
+                   "watermark": str(wm), "window": [DF, DT],
+                   "unexplained_line_ids": unexplained[:10]},
+    })
+    # ⛔⛔ THE LEG THAT CATCHES A WRONG JOIN KEY, and neither leg above can. Both of those sum the
+    # same LINES whatever dim they were grouped by, so swapping `dim: product_code` for
+    # `dim: product` (contract C1's trap, an Odoo id where the grid carries a SKU code) leaves
+    # them both green while every cell on the screen goes blank. This one asks: does the answer
+    # arrive under a key a GRID ROW ACTUALLY HAS, and is the value right FOR THAT SKU?
+    code_of = _codes_of_odoo_products(o, [r['product_id'][0] for r in g if r.get('product_id')])
+    by_code = {}
+    for r in g:
+        if not r.get('product_id'):
+            continue
+        c = code_of.get(r['product_id'][0], f"pid:{r['product_id'][0]}")
+        by_code[c] = by_code.get(c, 0.0) + r['price_subtotal']
+    # ⚠ The pool is the CALLER'S when it has one (it has already paid for it), and read fresh
+    # otherwise — `validate_measures` is runnable on its own, and a leg that silently skips when
+    # called directly is a leg nobody runs ([[gate-can-report-green-on-nothing]]).
+    pool_codes = set(pool_codes) if pool_codes is not None else {
+        r["code"] for r in pool(team_id=team_id, t=t)}
+    keyed_to_a_row = [c for c in store if c in pool_codes]
+    top = sorted(store.items(), key=lambda kv: -(kv[1].get("revenue") or 0))[:10]
+    spot = [{"sku": c,
+             "ours": round(v.get("revenue") or 0.0, 2),
+             "odoo": round(by_code.get(c, 0.0), 2)} for c, v in top]
+    # A named SKU may legitimately differ by a line Odoo edited after the watermark; the
+    # assertion is that MOST of the top ten tie exactly and NONE is off by an order of magnitude,
+    # which is what a mis-keyed join looks like (0.00 against a five-figure number).
+    exact = sum(1 for s in spot if abs(s["ours"] - s["odoo"]) < 0.005)
+    checks.append({
+        "check": "the measure answer is KEYED TO THE GRID'S OWN IDENTITY (C1's join-key trap): "
+                 "every group key is a SKU code a pool row carries, and the top-10 SKUs' revenue "
+                 "ties to Odoo for THAT SKU",
+        "ours": {"keys_matching_a_pool_row": len(keyed_to_a_row), "of": len(store),
+                 "top10_exact": exact},
+        "theirs": {"keys_matching_a_pool_row": len(store), "of": len(store), "top10_exact": 10},
+        # ⚠ Not `== len(store)`: a code whose ONLY product record is archived legitimately has
+        # revenue and no grid row (R12 keeps archived out), which `validate()`'s own
+        # "outside the grid" leg already reconciles. A mis-keyed join lands at ~0, not at 99%.
+        "ok": len(store) > 0 and len(keyed_to_a_row) / len(store) > 0.95 and exact >= 8,
+        "detail": {"spot_checks": spot,
+                   "keys_with_no_pool_row": sorted(set(store) - pool_codes)[:10]},
+    })
+    checks.append({
+        "check": "product lookback totals vs a DIRECT Odoo read_group, where the residual is mirror "
+                 "lag and is REPORTED as a figure, never absorbed into a tolerance",
+        "ours": ours_tot, "theirs": live_tot,
+        # The assertion is on leg 2; this leg is red only if the lag is implausibly large, which
+        # is the shape that means "the mirror stopped" rather than "the mirror is a day behind".
+        "ok": abs(ours_tot["revenue"] - live_tot["revenue"]) <= max(
+            0.01, live_tot["revenue"] * 0.02),
+        "detail": {"revenue_lag": round(ours_tot["revenue"] - live_tot["revenue"], 2),
+                   "revenue_lag_pct": round(
+                       (ours_tot["revenue"] - live_tot["revenue"]) / live_tot["revenue"] * 100, 4)
+                   if live_tot["revenue"] else None,
+                   "skus_in_grid_answer": len(store)},
+    })
     return checks

platform/modules/products.py

@@ -393,6 +393,178 @@ def pricelist_by_code():
     return out, report
 
 
+def active_products(limit=50000):
+    """`[{id, default_code, product_tmpl_id}]` for every ACTIVE product — read ONCE and shared.
+
+    ⛔ RAISES ON A SHORT PULL, like `catalogue()` and for the same reason: a truncated product read
+    renders as a plausible smaller set of priced SKUs with nothing reporting it.
+    ⭐ It exists so `tier_prices_by_code` and `packagings_by_code` can be called from ONE pool
+    build without each paying for its own copy of the same 5,873-row read — measured at ~4 s each
+    on this connection, on a path that is somebody's first page load.
+    """
+    dom = [('active', '=', True)]
+    prods = O.search_read('product.product', dom, ['id', 'default_code', 'product_tmpl_id'],
+                          limit=limit)
+    n = O.get_odoo().search_count('product.product', dom)
+    if len(prods) != n:
+        raise ValueError(f"products.active_products: the product pull is TRUNCATED. Read "
+                         f"{len(prods)} rows against a search_count of {n}.")
+    return prods
+
+
+def tier_prices_by_code(prods=None):
+    """`({code: [{pricelist, unit_price}]}, report)` — EVERY live price a SKU really has.
+
+    ⭐⭐ W37-T14 (owner: multiple prices per SKU). `pricelist_by_code` above answers a DIFFERENT
+    question and both are needed: it fills three DECLARED columns (`price_fisch`, `price_royal_1`,
+    `price_royal_2`) and therefore cannot show a price on a list the contract does not name. This
+    one is the honest set — one entry per pricelist that actually prices this SKU today.
+
+    ⛔ IT READS EVERY LIVE PRICELIST, not `PRICELIST_COLUMNS`. Hardcoding this tenant's three list
+    names into "how many prices does a SKU have" is exactly what the ticket forbids, and it is what
+    would make the answer wrong for tenant #1 on the day they are onboarded.
+
+    ⛔ ROWS ARE TEMPLATE-SCOPED (`proto/P2-pricing-uom.md`): joining on `product_id` drops 99.9% of
+    price rows, because `applied_on` is `1_product` on 10,454 of 10,468 items and `1_product` means
+    the TEMPLATE. A variant rule (`0_product_variant`, 13 rows) is the more specific statement and
+    wins, matching `pricecomp._tier_for` and `pricelist_by_code`.
+
+    ⛔ FILTER BY `pricelist_id`, NEVER BY `active`: the default `product.pricelist.item` count hides
+    2,580 archived items, so an `active` filter reads as a smaller, plausible, wrong set.
+
+    ⚠ THE BASE TIER, at qty 1, for the same reason `pricelist_by_code` gives: a catalogue cell has
+    no quantity in hand. Measured: only 10 of 10,468 items carry a quantity break at all, so this
+    is very nearly the whole story rather than a simplification.
+    ⚠ CARDINALITY 1..3 TODAY, mode 3 — and `Royal 2` carries 2,605 price rows against **0 customers
+    and 0 orders**, so a SKU reading "3 tiers" is catalogue-true and commercially misleading. The
+    entry keeps the list NAME so a reader can see which tier it is rather than a bare count.
+    """
+    report = {"lists": [], "rules_total": 0, "rules_not_fixed": 0, "rules_out_of_date": 0,
+              "rules_global": 0, "skus_with_no_price": 0, "identity_breaks": 0}
+    try:
+        pls = {p['id']: str(p.get('name') or '').strip()
+               for p in O.search_read('product.pricelist', [], ['id', 'name'])}
+        report["lists"] = sorted(pls.values())
+        today = P.today().isoformat()
+        dom = [('pricelist_id', 'in', sorted(pls)), ('compute_price', '=', 'fixed'),
+               ('applied_on', 'in', ['0_product_variant', '1_product']),
+               '|', ('date_start', '=', False), ('date_start', '<=', today),
+               '|', ('date_end', '=', False), ('date_end', '>=', today),
+               ('fixed_price', '>', 0)]
+        rules = O.search_read('product.pricelist.item', dom,
+                              ['pricelist_id', 'product_id', 'product_tmpl_id', 'applied_on',
+                               'fixed_price', 'min_quantity'])
+
+        # R6's second sentence: what this reader cannot see is COUNTED, never dropped.
+        def _n(extra):
+            try:
+                return O.get_odoo().search_count('product.pricelist.item', extra)
+            except Exception:                                          # noqa: BLE001
+                return -1                     # -1 reads as "not measured", never as zero
+        report["rules_total"] = _n([])
+        report["rules_not_fixed"] = _n([('compute_price', '!=', 'fixed')])
+        report["rules_global"] = _n([('applied_on', '=', '3_global')])
+        report["rules_out_of_date"] = _n(['|', ('date_end', '!=', False),
+                                          ('date_start', '!=', False)])
+
+        by_var, by_tmpl = {}, {}
+        for r in rules:
+            plid = O.m2o_id(r.get('pricelist_id'))
+            if r.get('applied_on') == '0_product_variant' and r.get('product_id'):
+                by_var.setdefault((plid, O.m2o_id(r['product_id'])), []).append(r)
+            elif r.get('product_tmpl_id'):
+                by_tmpl.setdefault((plid, O.m2o_id(r['product_tmpl_id'])), []).append(r)
+
+        prods = active_products() if prods is None else prods
+    except Exception as e:                                             # noqa: BLE001
+        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'))
+        tiers = []
+        for plid, name in sorted(pls.items(), key=lambda kv: kv[1].lower()):
+            cands = by_var.get((plid, p['id'])) or by_tmpl.get((plid, tmpl))
+            if not cands:
+                continue
+            base = min(cands, key=lambda r: r.get('min_quantity') or 0.0)
+            tiers.append({"pricelist": name, "unit_price": round(base.get('fixed_price') or 0.0, 2)})
+        if tiers:
+            # ⚠ A code carried by TWO active products (D-309: `2112-12`) MERGES here, because the
+            # grid is keyed by code and one code is one row. The prices are UNIONED rather than
+            # one silently winning — a SKU that really does have two different Fisch prices should
+            # show both, and hiding one is how a $60 price disappeared behind a $24 one.
+            prior = out.get(code)
+            if prior is None:
+                out[code] = tiers
+            else:
+                seen = {(t["pricelist"], t["unit_price"]) for t in prior}
+                for t in tiers:
+                    if (t["pricelist"], t["unit_price"]) not in seen:
+                        prior.append(t)
+                        report["identity_breaks"] += 1
+        else:
+            report["skus_with_no_price"] += 1
+    return out, report
+
+
+def packagings_by_code(prods=None):
+    """`({code: [{name, qty}]}, report)` — the UNITS a SKU is really sold in (W37-T15).
+
+    ⛔ IT COMES FROM `product.packaging` ALONE, and `proto/P2-pricing-uom.md` measured why the
+    obvious alternative is a dead end: the `uom.uom` Config category holds 26 conversion-bearing
+    units (`Case-Packed 12` … `Pallet-Packed 4,800`) referenced by **0 products, 0 sale lines and
+    0 stock moves**, and every unit actually in use has `factor_inv = 1`. Building on `uom.uom`
+    conversions yields a column of 1s.
+
+    ⛔ `qty > 1` IS A FILTER, NOT A TIDY-UP. 6,283 of 7,471 packaging rows are `qty = 1.0` — a
+    packaging that packs one of something is not a unit tier — plus real junk (one-character
+    names). Without it "units per SKU" reads **5,859** SKUs instead of **1,150**.
+
+    ⛔ 133 ROWS ARE ORPHANS (`product_id = False`) and would collapse under a `groupby(product_id)`
+    into ONE fake product carrying 133 packagings. Dropped, and counted.
+
+    ⚠ HONEST EMPTY: only **1,150 of 5,873 SKUs (19.6%)** have any unit tier, so this cell is
+    legitimately blank for 80% of the catalogue — "this SKU is sold in one unit", never "missing".
+    The 19.6% is not decoration: units are transacted on 77.9% of confirmed sale lines.
+    ⚠ `qty` is denominated in the product's OWN `uom_id` (matched on 7,338/7,338).
+    """
+    report = {"rows_total": 0, "rows_orphan": 0, "rows_qty_le_1": 0, "skus_with_units": 0}
+    try:
+        rows = O.search_read('product.packaging', [], ['id', 'name', 'qty', 'product_id'])
+    except Exception as e:                                             # noqa: BLE001
+        report["error"] = f"{type(e).__name__}: {str(e)[:200]}"
+        return {}, report
+    report["rows_total"] = len(rows)
+    by_pid = {}
+    for r in rows:
+        pid = O.m2o_id(r.get('product_id'))
+        if not pid:
+            report["rows_orphan"] += 1
+            continue
+        if (r.get('qty') or 0) <= 1:
+            report["rows_qty_le_1"] += 1
+            continue
+        by_pid.setdefault(pid, []).append(
+            {"name": str(r.get('name') or '').strip(), "qty": float(r.get('qty') or 0)})
+    try:
+        prods = active_products() if prods is None else prods
+    except Exception as e:                                             # noqa: BLE001
+        report["error"] = f"{type(e).__name__}: {str(e)[:200]}"
+        return {}, report
+    out = {}
+    for p in prods:
+        got = by_pid.get(p['id'])
+        if not got:
+            continue
+        code = (str(p['default_code']).strip() if p.get('default_code') else f"pid:{p['id']}")
+        out.setdefault(code, []).extend(sorted(got, key=lambda u: u["qty"]))
+    report["skus_with_units"] = len(out)
+    return out, report
+
+
 def catalogue_count():
     """The INDEPENDENT population oracle: Odoo's own count of active products.
 

requirements.txt

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

web/index.html

@@ -1,14 +1,46 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Loopable</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <div id="portal"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Loopable</title>
+  </head>
+  <body>
+    <!-- ⭐⭐ WAVE 37 · T48 — THE BOOT SKELETON, AND EVERY CHOICE HERE IS FORCED BY WHEN IT HAS TO
+         PAINT. Measured on the deployed build (proto/P4-first-load.md §A.2): `#root` was EMPTY and
+         the screen white for 6.0–8.0 s of an 11.6–16.0 s first open, while one 580 KB entry chunk
+         downloaded and parsed. The `<body>` was two empty divs, so there was nothing to show.
+
+         ⛔ INLINE STYLES, NOT A CLASS. `index.css` is its own ~324 KB render-blocking chunk that
+         took 3.3 s in that same trace — a skeleton styled from it would wait for the exact asset
+         whose arrival it exists to cover, and paint white until then. Inline is the only thing that
+         can render from the HTML alone.
+
+         ⛔ INSIDE `#root`, NOT BESIDE IT. `createRoot(...).render()` REPLACES the container's
+         children, so this is removed by the mount itself. A skeleton outside `#root` needs JS to
+         take it away, which is a second thing that can fail and a flash-of-two-uis if it does.
+
+         ⚠ NO ANIMATION. A shimmer would be a keyframe the CSS chunk has not delivered yet, and a
+         static block that never moves is honest about a page that is still downloading; a frozen
+         shimmer would read as a hung app. `aria-hidden` + `role="presentation"`: a screen reader
+         should hear the app, not its scaffolding. -->
+    <div id="root"><div aria-hidden="true" role="presentation" style="height:100vh;display:flex;flex-direction:column;background:#ffffff">
+      <div style="height:44px;flex:none;border-bottom:1px solid #e8e8ea;display:flex;align-items:center;padding:0 14px">
+        <div style="width:22px;height:22px;border-radius:11px;background:#efedf9"></div>
+        <div style="width:96px;height:12px;margin-left:10px;border-radius:3px;background:#efedf9"></div>
+      </div>
+      <div style="flex:1;display:flex;min-height:0">
+        <div style="width:288px;flex:none;border-right:1px solid #e8e8ea;padding:14px 12px">
+          <div style="height:11px;width:64%;border-radius:3px;background:#f1f0f4;margin-bottom:14px"></div>
+          <div style="height:11px;width:78%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
+          <div style="height:11px;width:54%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
+          <div style="height:11px;width:70%;border-radius:3px;background:#f4f3f7"></div>
+        </div>
+        <div style="flex:1;background:#fafafb"></div>
+      </div>
+    </div></div>
+    <div id="portal"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

web/src/App.tsx

@@ -1,30 +1,41 @@
-import CustomerGrid from "./customer-grid/CustomerGrid";
-import { OverlayProvider } from "./customer-grid/OverlaySurface";
-import { isStreamlitComponent } from "./customer-grid/hostBridge";
-import Shell from "./shell/Shell";
-
-// HOSTED = either Streamlit path (the component iframe, or the legacy injected
-// payload). There the surrounding app owns all chrome and this tree renders the
-// BARE grid, byte-for-byte the behavior the embed always had. Only the
-// standalone build gets the shell (wave 4, the strangler frame). Computed once
-// at module level, like useCustomerData's own mode constants — the host mode
-// cannot change within a page lifetime.
-// EXPORTED (EXIT wave 1): main.tsx needs the same answer to decide whether to
-// install the standalone event sink, and two copies of a mode predicate is how
-// the two halves of "standalone-only" end up disagreeing.
-export const HOSTED =
-  isStreamlitComponent() ||
-  typeof (window as unknown as { __AIOS_GRID__?: unknown }).__AIOS_GRID__ !== "undefined";
-
-export default function App() {
-  if (HOSTED) {
-    return (
-      <div style={{ width: "100%", height: "100%", overflow: "hidden" }}>
-        <OverlayProvider>
-          <CustomerGrid />
-        </OverlayProvider>
-      </div>
-    );
-  }
-  return <Shell />;
-}
+import { Suspense, lazy } from "react";
+// ⭐⭐ WAVE 37 · T48 — LAZY, AND IT IS THE LAST OF THE THREE EAGER IMPORTS. `CustomerGrid` (7,715
+// lines) plus glide-data-grid sat in the ENTRY chunk because these three files imported it at the
+// top level, while twelve other surfaces were already `lazy()`. Measured on the deployed build
+// (`proto/P4-first-load.md` §A.2): the entry chunk was 580,102 B on the wire and took 5.6-5.8 s,
+// during which `#root` was EMPTY and the screen was white — 6.0-8.0 s of the 11.6-16.0 s first open.
+// ⚠ THE EMBED PAYS THIS TOO, and it is the one path where the grid IS the page, so its fallback is
+// deliberately the same skeleton shape the shell uses rather than `null`: a blank iframe is
+// indistinguishable from a broken one.
+const CustomerGrid = lazy(() => import("./customer-grid/CustomerGrid"));
+import { OverlayProvider } from "./customer-grid/OverlaySurface";
+import { isStreamlitComponent } from "./customer-grid/hostBridge";
+import Shell from "./shell/Shell";
+
+// HOSTED = either Streamlit path (the component iframe, or the legacy injected
+// payload). There the surrounding app owns all chrome and this tree renders the
+// BARE grid, byte-for-byte the behavior the embed always had. Only the
+// standalone build gets the shell (wave 4, the strangler frame). Computed once
+// at module level, like useCustomerData's own mode constants — the host mode
+// cannot change within a page lifetime.
+// EXPORTED (EXIT wave 1): main.tsx needs the same answer to decide whether to
+// install the standalone event sink, and two copies of a mode predicate is how
+// the two halves of "standalone-only" end up disagreeing.
+export const HOSTED =
+  isStreamlitComponent() ||
+  typeof (window as unknown as { __AIOS_GRID__?: unknown }).__AIOS_GRID__ !== "undefined";
+
+export default function App() {
+  if (HOSTED) {
+    return (
+      <div style={{ width: "100%", height: "100%", overflow: "hidden" }}>
+        <OverlayProvider>
+          <Suspense fallback={<div className="lp-boot" aria-hidden="true" />}>
+            <CustomerGrid />
+          </Suspense>
+        </OverlayProvider>
+      </div>
+    );
+  }
+  return <Shell />;
+}

web/src/account/SubscriptionPage.tsx

@@ -1,47 +1,49 @@
-// ---------------------------------------------------------------------------
-// account/SubscriptionPage.tsx — WAVE 35 · W35-T20 (owner item 13, contract C6).
-//
-// Owner item 13, verbatim: *"add below settings the following button: Feedback …,
-// Usage credits …, and a Subscription module … Specialized for the Royal Imports
-// tenant, do not show it."*
-//
-// This is the third of those three, and the only one with nothing behind it yet.
-// So it says so, in the words this app already uses for a boarded door
-// (`Shell.tsx`'s templates note: "Under construction. … will open here in a later
-// release."). One voice for one state — DESIGN.md 1's "variety is a defect".
-//
-// ⛔ THIS PAGE DOES NOT HIDE ITSELF, AND THAT IS THE TICKET'S OWN TRAP.
-// C6 puts the Royal Imports rule in TWO places that are both the frame's: the
-// account MENU does not draw the row, and the ROUTE refuses. A third opinion here
-// would be a third thing to keep in step, and the day they disagree the reader
-// gets a menu row that opens a page which says it does not exist. The page renders
-// the same for every tenant that can reach it, because reaching it IS the decision.
-//
-// ⛔ AND IT TAKES NO PROPS, WHICH IS ALSO A DECISION rather than an omission.
-// The wave's rule is that a prop must be REQUIRED, never optional — an optional one
-// degrades to "the page does not exist", which is indistinguishable from never
-// built. That rule constrains the props that EXIST; it does not ask for a prop that
-// carries nothing. There is nothing this page needs from the frame: it holds no
-// state, makes no call, and takes no decision the frame has already taken. A
-// `tenant` prop here would be exactly the second opinion the paragraph above
-// refuses. The mount is proven by A's `verify_wiring` row (W2), not by a signature.
-// ---------------------------------------------------------------------------
-
-import "./account.css";
-
-export default function SubscriptionPage() {
-  return (
-    <div className="acct-page">
-      <h1 className="acct-title">Subscription</h1>
-      <div className="acct-col">
-        {/* ⚠ TWO SHORT SENTENCES AND NO TOUR (DESIGN.md 4 / wave-22 R13: the app does not
-            narrate itself). The reader arrived here on purpose and wants one fact: is there
-            anything to do? There is not, and every further word would be spent on someone
-            who is already leaving. No feature list, no roadmap, no "in the meantime". */}
-        <p className="acct-note">
-          Under construction. Plans, billing and invoices will open here in a later release.
-        </p>
-      </div>
-    </div>
-  );
-}
+// ---------------------------------------------------------------------------
+// account/SubscriptionPage.tsx — WAVE 35 · W35-T20 (owner item 13, contract C6).
+//
+// Owner item 13, verbatim: *"add below settings the following button: Feedback …,
+// Usage credits …, and a Subscription module … Specialized for the Royal Imports
+// tenant, do not show it."*
+// ⛔ "verbatim" IS THE POINT: W37-T02 renamed that surface to "Usage" and this quote KEEPS the
+// owner's own wording. A quote edited to match a later rename is no longer evidence of anything.
+//
+// This is the third of those three, and the only one with nothing behind it yet.
+// So it says so, in the words this app already uses for a boarded door
+// (`Shell.tsx`'s templates note: "Under construction. … will open here in a later
+// release."). One voice for one state — DESIGN.md 1's "variety is a defect".
+//
+// ⛔ THIS PAGE DOES NOT HIDE ITSELF, AND THAT IS THE TICKET'S OWN TRAP.
+// C6 puts the Royal Imports rule in TWO places that are both the frame's: the
+// account MENU does not draw the row, and the ROUTE refuses. A third opinion here
+// would be a third thing to keep in step, and the day they disagree the reader
+// gets a menu row that opens a page which says it does not exist. The page renders
+// the same for every tenant that can reach it, because reaching it IS the decision.
+//
+// ⛔ AND IT TAKES NO PROPS, WHICH IS ALSO A DECISION rather than an omission.
+// The wave's rule is that a prop must be REQUIRED, never optional — an optional one
+// degrades to "the page does not exist", which is indistinguishable from never
+// built. That rule constrains the props that EXIST; it does not ask for a prop that
+// carries nothing. There is nothing this page needs from the frame: it holds no
+// state, makes no call, and takes no decision the frame has already taken. A
+// `tenant` prop here would be exactly the second opinion the paragraph above
+// refuses. The mount is proven by A's `verify_wiring` row (W2), not by a signature.
+// ---------------------------------------------------------------------------
+
+import "./account.css";
+
+export default function SubscriptionPage() {
+  return (
+    <div className="acct-page">
+      <h1 className="acct-title">Subscription</h1>
+      <div className="acct-col">
+        {/* ⚠ TWO SHORT SENTENCES AND NO TOUR (DESIGN.md 4 / wave-22 R13: the app does not
+            narrate itself). The reader arrived here on purpose and wants one fact: is there
+            anything to do? There is not, and every further word would be spent on someone
+            who is already leaving. No feature list, no roadmap, no "in the meantime". */}
+        <p className="acct-note">
+          Under construction. Plans, billing and invoices will open here in a later release.
+        </p>
+      </div>
+    </div>
+  );
+}

web/src/account/UsagePage.tsx

@@ -1,297 +1,297 @@
-// ---------------------------------------------------------------------------
-// account/UsagePage.tsx — WAVE 35 · W35-T19 (owner item 13, ruling R9, C6/C7).
-//
-// R9: ONE meter for every AI surface. It REPORTS weekly usage against an
-// allowance and does not cut anyone off this wave; over the allowance the
-// product still works and the bar is red.
-//
-// ⛔⛔ THIS PAGE MAY NOT INVENT A FIGURE, AND THAT IS THE WHOLE TICKET.
-// Every number here comes off `GET /usage` — the week, the reset date, the
-// allowance, each surface's tokens and calls. Nothing is derived from a clock,
-// nothing is estimated, and a surface with no ledger lines shows **0**, not a
-// blank and not an omission (E-9 guarantees all four surfaces are always
-// present, so there is no missing-row branch to get wrong).
-// [[no-unverifiable-aggregates]]
-//
-// ⛔ AND `unmeasured` IS RENDERED, NOT SWALLOWED. Those are real calls whose
-// provider declined to report a token count, so the total beside them is a
-// FLOOR. A page that hides them presents the floor as a complete figure, which
-// is the cost-surprise failure one step removed — the same reason
-// `usage_ledger` books an unmeasured call as unknown rather than as zero.
-//
-// ⚠ SURFACE/READ SPLIT, as on Home and Starred: `renderToStaticMarkup` runs no
-// effect, so a shot of the fetching component photographs only its spinner.
-// ---------------------------------------------------------------------------
-
-import { useCallback, useEffect, useRef, useState } from "react";
-
-import { fmt } from "../ui/fmt";
-import { loadUsage } from "./accountApi";
-import type { Usage, UsageSurface } from "./accountApi";
-import "./account.css";
-
-/**
- * The four surfaces C7 names, in the order R9 lists them.
- *
- * ⚠ AN UNKNOWN KEY IS HUMANISED, NEVER DROPPED. Dropping it would hide real usage from a meter
- * whose whole job is to account for it, and printing the raw key would put an internal identifier
- * on screen. The day a fifth LLM entry point lands (this product added two in one wave) it shows
- * up here as a readable name with the right number beside it, and somebody can then decide what
- * to call it.
- */
-const SURFACE_LABEL: Record<string, string> = {
-  assistant: "Assistant",
-  field_agent: "Field agents",
-  ai_review: "Reviews",
-  automation_draft: "Drafting",
-};
-const ORDER = ["assistant", "field_agent", "ai_review", "automation_draft"];
-
-export function surfaceLabel(key: string): string {
-  const known = SURFACE_LABEL[key];
-  if (known) return known;
-  const words = key.replace(/[_-]+/g, " ").trim();
-  return words ? words.charAt(0).toUpperCase() + words.slice(1) : key;
-}
-
-/** C7's order first, then anything the server added, alphabetically. */
-export function orderSurfaces(surfaces: UsageSurface[]): UsageSurface[] {
-  const rank = (s: UsageSurface) => {
-    const i = ORDER.indexOf(s.surface);
-    return i === -1 ? ORDER.length : i;
-  };
-  return [...surfaces].sort(
-    (a, b) => rank(a) - rank(b) || surfaceLabel(a.surface).localeCompare(surfaceLabel(b.surface))
-  );
-}
-
-/**
- * The bar's fill, as a percentage, CLAMPED to 100.
- *
- * ⚠ The clamp is what keeps "over the allowance" a COLOUR rather than a bar that overflows its
- * own track and paints across the page. The number above the bar is unclamped and is where the
- * overage is actually read.
- * ⚠ An allowance of 0 (unset) yields 0 rather than a division by zero: no allowance means the
- * meter has nothing to measure against, and a full red bar would be an assertion nobody made.
- */
-export function barPct(value: number, of: number): number {
-  if (!(of > 0)) return 0;
-  return Math.max(0, Math.min(100, (value / of) * 100));
-}
-
-export type UsageLoad =
-  | { phase: "loading" }
-  | { phase: "ready"; usage: Usage }
-  | { phase: "failed"; message: string };
-
-function Bar({ pct, over }: { pct: number; over: boolean }) {
-  return (
-    <span className="acct-bar" aria-hidden="true">
-      <span className={"acct-bar-fill" + (over ? " is-over" : "")} style={{ width: `${pct}%` }} />
-    </span>
-  );
-}
-
-export function UsageSurfaceRows({ usage }: { usage: Usage }) {
-  // ⚠ SCALED TO THE LARGEST SURFACE, NOT TO THE WEEK'S TOTAL, and the difference is legibility
-  // rather than accuracy. `total` is the week's whole figure and can legitimately exceed the sum
-  // of these four (unattributed calls are counted there and belong to nobody), so scaling to it
-  // shrinks every bar by an amount the reader cannot see the cause of. Scaled to the biggest row,
-  // the bars answer the question a row of bars is actually asked: which surface is spending most.
-  // The absolute number sits beside each one, so nothing here is only readable as a shape.
-  const biggest = usage.surfaces.reduce((m, s) => Math.max(m, s.tokens), 0);
-  return (
-    <div className="acct-rows">
-      {orderSurfaces(usage.surfaces).map((s) => (
-        <div key={s.surface} className="acct-row">
-          <span className="acct-row-name">{surfaceLabel(s.surface)}</span>
-          <Bar pct={barPct(s.tokens, biggest)} over={false} />
-          <span className="acct-row-num">{fmt.int(s.tokens)}</span>
-          <span className="acct-row-sub">
-            {fmt.int(s.calls)} {s.calls === 1 ? "call" : "calls"}
-            {/* ⛔ NOT HOVER-ONLY. A surface whose provider declined to report tokens has a
-                token number that is a floor, and D-253 is a booked defect whose entire content
-                is "the explanation was satisfied only on hover". */}
-            {s.unmeasured > 0 ? `, ${fmt.int(s.unmeasured)} not measured` : ""}
-          </span>
-        </div>
-      ))}
-    </div>
-  );
-}
-
-export function UsageView({
-  load,
-  scope,
-  canSeeTenant,
-  onScope,
-  onRetry,
-}: {
-  load: UsageLoad;
-  scope: "me" | "tenant";
-  /**
-   * Whether the workspace view is reachable AT ALL for this account.
-   *
-   * ⛔ THE TOGGLE IS NOT DRAWN WHEN IT IS NOT, and that is R8's fake-affordance rule applied to a
-   * permission: `?scope=tenant` is admin-only and 403s for everybody else, so an always-visible
-   * control would be a button most accounts can only be refused by.
-   */
-  canSeeTenant: boolean;
-  onScope: (scope: "me" | "tenant") => void;
-  onRetry: () => void;
-}) {
-  return (
-    <div className="acct-page">
-      <h1 className="acct-title">Usage credits</h1>
-      <div className="acct-col">
-        {canSeeTenant ? (
-          <div className="acct-scope" role="group" aria-label="Whose usage">
-            {(["me", "tenant"] as const).map((key) => (
-              <button
-                key={key}
-                type="button"
-                className={"acct-scope-btn" + (scope === key ? " is-on" : "")}
-                aria-pressed={scope === key}
-                onClick={() => onScope(key)}
-              >
-                {key === "me" ? "You" : "Workspace"}
-              </button>
-            ))}
-          </div>
-        ) : null}
-        {load.phase === "loading" ? (
-          <div className="acct-loading">
-            <span className="lp-spin lp-spin--lg" role="status" aria-label="Loading" />
-          </div>
-        ) : load.phase === "failed" ? (
-          // ⛔ NOT A ZERO METER. A failed read and a quiet week look identical on screen unless
-          // this branch exists, and a meter reading zero is the most reassuring possible lie.
-          <div className="acct-failed">
-            <p className="acct-note">{load.message}</p>
-            <button type="button" className="acct-retry" onClick={onRetry}>
-              Try again
-            </button>
-          </div>
-        ) : (
-          <>
-            <div className="acct-meter">
-              {/* ⛔ THE METER SAYS WHOSE USAGE IT IS, IN WORDS, and that is not decoration. The
-                  allowance is a WORKSPACE number; the total beside it is this account's own
-                  unless the scope says otherwise. A meter that shows a personal figure against a
-                  shared limit without saying so is a ratio nobody can read correctly, and it is
-                  the one way this page can be wrong while every number on it is right. */}
-              <div className="acct-meter-head">
-                <span className="acct-meter-who">
-                  {load.usage.scope === "tenant" ? "This workspace" : "You"}, this week
-                </span>
-              </div>
-              <div className="acct-meter-head">
-                <span className={"acct-meter-value" + (load.usage.over ? " is-over" : "")}>
-                  {fmt.int(load.usage.total)}
-                </span>
-                <span className="acct-meter-of">
-                  of {fmt.int(load.usage.allowance)} tokens
-                </span>
-              </div>
-              <Bar pct={barPct(load.usage.total, load.usage.allowance)} over={load.usage.over} />
-              <div className="acct-meter-foot">
-                {/* Both facts are the SERVER'S: the week it counted and the date it rolls over.
-                    A week boundary computed in the browser can disagree with the bucketing that
-                    produced the number above it, and then the page states a period nobody
-                    measured. */}
-                <span>
-                  Week {load.usage.week}. Resets {fmt.date(load.usage.resets)}.
-                </span>
-                <span className="acct-meter-calls">
-                  {fmt.int(load.usage.calls)} {load.usage.calls === 1 ? "call" : "calls"}
-                </span>
-              </div>
-            </div>
-
-            {/* ⛔ R9's whole point, in one line: over the allowance it STILL WORKS. The bar is
-                red, nothing is cut off, and the sentence says which of those two is true so
-                nobody has to infer it from a colour. */}
-            {load.usage.over ? (
-              <p className="acct-error" role="status">
-                This workspace is over its weekly allowance. Nothing is cut off; the AI surfaces
-                keep working.
-              </p>
-            ) : null}
-
-            {/* The server's own sentence, present only when something really was unmeasured. */}
-            {load.usage.note ? <p className="acct-note acct-note--inline">{load.usage.note}</p> : null}
-
-            <h2 className="acct-section">By surface</h2>
-            <UsageSurfaceRows usage={load.usage} />
-
-            {load.usage.unattributed > 0 ? (
-              // ⚠ LABELLED A WIRING GAP, NOT USAGE (E-9). These are AI calls this container could
-              // not attribute to an account. Folding them into somebody's total would be an
-              // invented attribution, and leaving them out entirely would understate the week.
-              <p className="acct-note acct-note--inline">
-                {fmt.int(load.usage.unattributed)} tokens this week could not be attributed to an
-                account. That is a wiring gap in the meter, not somebody's usage.
-              </p>
-            ) : null}
-          </>
-        )}
-      </div>
-    </div>
-  );
-}
-
-export default function UsagePage() {
-  const [load, setLoad] = useState<UsageLoad>({ phase: "loading" });
-  const [scope, setScope] = useState<"me" | "tenant">("me");
-  /**
-   * Whether the workspace view exists for this account, ANSWERED BY ASKING ONCE.
-   *
-   * ⛔ WHY A PROBE RATHER THAN A ROLE CHECK. The frame knows the role, but these pages take no
-   * props by contract (C6's trap: a page that decides its own visibility is a second opinion that
-   * will one day disagree with the route). The route itself is the authority, so the page asks it
-   * once: a 200 means the door is open and the toggle is real; a 403 means it is not and no
-   * control is drawn. ⚠ That 403 is an ANSWER, not an error — it is never shown to the reader.
-   * ⭐ AND IT IS WHAT GIVES `?scope=tenant` A DOOR. E built it admin-only; without this it would
-   * be a finished capability with no caller, which is this repo's most-repeated failure
-   * [[reachable-is-not-the-same-as-built]].
-   */
-  const [canSeeTenant, setCanSeeTenant] = useState(false);
-  const gen = useRef(0);
-
-  const read = useCallback((which: "me" | "tenant") => {
-    const mine = gen.current + 1;
-    gen.current = mine;
-    setLoad({ phase: "loading" });
-    void loadUsage(which === "tenant" ? "tenant" : undefined).then((r) => {
-      if (gen.current !== mine) return;
-      setLoad(r.ok ? { phase: "ready", usage: r.value } : { phase: "failed", message: r.message });
-    });
-  }, []);
-
-  useEffect(() => {
-    read(scope);
-    return () => {
-      gen.current += 1;
-    };
-  }, [read, scope]);
-
-  useEffect(() => {
-    let live = true;
-    void loadUsage("tenant").then((r) => {
-      if (live) setCanSeeTenant(r.ok);
-    });
-    return () => {
-      live = false;
-    };
-  }, []);
-
-  return (
-    <UsageView
-      load={load}
-      scope={scope}
-      canSeeTenant={canSeeTenant}
-      onScope={setScope}
-      onRetry={() => read(scope)}
-    />
-  );
-}
+// ---------------------------------------------------------------------------
+// account/UsagePage.tsx — WAVE 35 · W35-T19 (owner item 13, ruling R9, C6/C7).
+//
+// R9: ONE meter for every AI surface. It REPORTS weekly usage against an
+// allowance and does not cut anyone off this wave; over the allowance the
+// product still works and the bar is red.
+//
+// ⛔⛔ THIS PAGE MAY NOT INVENT A FIGURE, AND THAT IS THE WHOLE TICKET.
+// Every number here comes off `GET /usage` — the week, the reset date, the
+// allowance, each surface's tokens and calls. Nothing is derived from a clock,
+// nothing is estimated, and a surface with no ledger lines shows **0**, not a
+// blank and not an omission (E-9 guarantees all four surfaces are always
+// present, so there is no missing-row branch to get wrong).
+// [[no-unverifiable-aggregates]]
+//
+// ⛔ AND `unmeasured` IS RENDERED, NOT SWALLOWED. Those are real calls whose
+// provider declined to report a token count, so the total beside them is a
+// FLOOR. A page that hides them presents the floor as a complete figure, which
+// is the cost-surprise failure one step removed — the same reason
+// `usage_ledger` books an unmeasured call as unknown rather than as zero.
+//
+// ⚠ SURFACE/READ SPLIT, as on Home and Starred: `renderToStaticMarkup` runs no
+// effect, so a shot of the fetching component photographs only its spinner.
+// ---------------------------------------------------------------------------
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { fmt } from "../ui/fmt";
+import { loadUsage } from "./accountApi";
+import type { Usage, UsageSurface } from "./accountApi";
+import "./account.css";
+
+/**
+ * The four surfaces C7 names, in the order R9 lists them.
+ *
+ * ⚠ AN UNKNOWN KEY IS HUMANISED, NEVER DROPPED. Dropping it would hide real usage from a meter
+ * whose whole job is to account for it, and printing the raw key would put an internal identifier
+ * on screen. The day a fifth LLM entry point lands (this product added two in one wave) it shows
+ * up here as a readable name with the right number beside it, and somebody can then decide what
+ * to call it.
+ */
+const SURFACE_LABEL: Record<string, string> = {
+  assistant: "Assistant",
+  field_agent: "Field agents",
+  ai_review: "Reviews",
+  automation_draft: "Drafting",
+};
+const ORDER = ["assistant", "field_agent", "ai_review", "automation_draft"];
+
+export function surfaceLabel(key: string): string {
+  const known = SURFACE_LABEL[key];
+  if (known) return known;
+  const words = key.replace(/[_-]+/g, " ").trim();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : key;
+}
+
+/** C7's order first, then anything the server added, alphabetically. */
+export function orderSurfaces(surfaces: UsageSurface[]): UsageSurface[] {
+  const rank = (s: UsageSurface) => {
+    const i = ORDER.indexOf(s.surface);
+    return i === -1 ? ORDER.length : i;
+  };
+  return [...surfaces].sort(
+    (a, b) => rank(a) - rank(b) || surfaceLabel(a.surface).localeCompare(surfaceLabel(b.surface))
+  );
+}
+
+/**
+ * The bar's fill, as a percentage, CLAMPED to 100.
+ *
+ * ⚠ The clamp is what keeps "over the allowance" a COLOUR rather than a bar that overflows its
+ * own track and paints across the page. The number above the bar is unclamped and is where the
+ * overage is actually read.
+ * ⚠ An allowance of 0 (unset) yields 0 rather than a division by zero: no allowance means the
+ * meter has nothing to measure against, and a full red bar would be an assertion nobody made.
+ */
+export function barPct(value: number, of: number): number {
+  if (!(of > 0)) return 0;
+  return Math.max(0, Math.min(100, (value / of) * 100));
+}
+
+export type UsageLoad =
+  | { phase: "loading" }
+  | { phase: "ready"; usage: Usage }
+  | { phase: "failed"; message: string };
+
+function Bar({ pct, over }: { pct: number; over: boolean }) {
+  return (
+    <span className="acct-bar" aria-hidden="true">
+      <span className={"acct-bar-fill" + (over ? " is-over" : "")} style={{ width: `${pct}%` }} />
+    </span>
+  );
+}
+
+export function UsageSurfaceRows({ usage }: { usage: Usage }) {
+  // ⚠ SCALED TO THE LARGEST SURFACE, NOT TO THE WEEK'S TOTAL, and the difference is legibility
+  // rather than accuracy. `total` is the week's whole figure and can legitimately exceed the sum
+  // of these four (unattributed calls are counted there and belong to nobody), so scaling to it
+  // shrinks every bar by an amount the reader cannot see the cause of. Scaled to the biggest row,
+  // the bars answer the question a row of bars is actually asked: which surface is spending most.
+  // The absolute number sits beside each one, so nothing here is only readable as a shape.
+  const biggest = usage.surfaces.reduce((m, s) => Math.max(m, s.tokens), 0);
+  return (
+    <div className="acct-rows">
+      {orderSurfaces(usage.surfaces).map((s) => (
+        <div key={s.surface} className="acct-row">
+          <span className="acct-row-name">{surfaceLabel(s.surface)}</span>
+          <Bar pct={barPct(s.tokens, biggest)} over={false} />
+          <span className="acct-row-num">{fmt.int(s.tokens)}</span>
+          <span className="acct-row-sub">
+            {fmt.int(s.calls)} {s.calls === 1 ? "call" : "calls"}
+            {/* ⛔ NOT HOVER-ONLY. A surface whose provider declined to report tokens has a
+                token number that is a floor, and D-253 is a booked defect whose entire content
+                is "the explanation was satisfied only on hover". */}
+            {s.unmeasured > 0 ? `, ${fmt.int(s.unmeasured)} not measured` : ""}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export function UsageView({
+  load,
+  scope,
+  canSeeTenant,
+  onScope,
+  onRetry,
+}: {
+  load: UsageLoad;
+  scope: "me" | "tenant";
+  /**
+   * Whether the workspace view is reachable AT ALL for this account.
+   *
+   * ⛔ THE TOGGLE IS NOT DRAWN WHEN IT IS NOT, and that is R8's fake-affordance rule applied to a
+   * permission: `?scope=tenant` is admin-only and 403s for everybody else, so an always-visible
+   * control would be a button most accounts can only be refused by.
+   */
+  canSeeTenant: boolean;
+  onScope: (scope: "me" | "tenant") => void;
+  onRetry: () => void;
+}) {
+  return (
+    <div className="acct-page">
+      <h1 className="acct-title">Usage</h1>
+      <div className="acct-col">
+        {canSeeTenant ? (
+          <div className="acct-scope" role="group" aria-label="Whose usage">
+            {(["me", "tenant"] as const).map((key) => (
+              <button
+                key={key}
+                type="button"
+                className={"acct-scope-btn" + (scope === key ? " is-on" : "")}
+                aria-pressed={scope === key}
+                onClick={() => onScope(key)}
+              >
+                {key === "me" ? "You" : "Workspace"}
+              </button>
+            ))}
+          </div>
+        ) : null}
+        {load.phase === "loading" ? (
+          <div className="acct-loading">
+            <span className="lp-spin lp-spin--lg" role="status" aria-label="Loading" />
+          </div>
+        ) : load.phase === "failed" ? (
+          // ⛔ NOT A ZERO METER. A failed read and a quiet week look identical on screen unless
+          // this branch exists, and a meter reading zero is the most reassuring possible lie.
+          <div className="acct-failed">
+            <p className="acct-note">{load.message}</p>
+            <button type="button" className="acct-retry" onClick={onRetry}>
+              Try again
+            </button>
+          </div>
+        ) : (
+          <>
+            <div className="acct-meter">
+              {/* ⛔ THE METER SAYS WHOSE USAGE IT IS, IN WORDS, and that is not decoration. The
+                  allowance is a WORKSPACE number; the total beside it is this account's own
+                  unless the scope says otherwise. A meter that shows a personal figure against a
+                  shared limit without saying so is a ratio nobody can read correctly, and it is
+                  the one way this page can be wrong while every number on it is right. */}
+              <div className="acct-meter-head">
+                <span className="acct-meter-who">
+                  {load.usage.scope === "tenant" ? "This workspace" : "You"}, this week
+                </span>
+              </div>
+              <div className="acct-meter-head">
+                <span className={"acct-meter-value" + (load.usage.over ? " is-over" : "")}>
+                  {fmt.int(load.usage.total)}
+                </span>
+                <span className="acct-meter-of">
+                  of {fmt.int(load.usage.allowance)} tokens
+                </span>
+              </div>
+              <Bar pct={barPct(load.usage.total, load.usage.allowance)} over={load.usage.over} />
+              <div className="acct-meter-foot">
+                {/* Both facts are the SERVER'S: the week it counted and the date it rolls over.
+                    A week boundary computed in the browser can disagree with the bucketing that
+                    produced the number above it, and then the page states a period nobody
+                    measured. */}
+                <span>
+                  Week {load.usage.week}. Resets {fmt.date(load.usage.resets)}.
+                </span>
+                <span className="acct-meter-calls">
+                  {fmt.int(load.usage.calls)} {load.usage.calls === 1 ? "call" : "calls"}
+                </span>
+              </div>
+            </div>
+
+            {/* ⛔ R9's whole point, in one line: over the allowance it STILL WORKS. The bar is
+                red, nothing is cut off, and the sentence says which of those two is true so
+                nobody has to infer it from a colour. */}
+            {load.usage.over ? (
+              <p className="acct-error" role="status">
+                This workspace is over its weekly allowance. Nothing is cut off; the AI surfaces
+                keep working.
+              </p>
+            ) : null}
+
+            {/* The server's own sentence, present only when something really was unmeasured. */}
+            {load.usage.note ? <p className="acct-note acct-note--inline">{load.usage.note}</p> : null}
+
+            <h2 className="acct-section">By surface</h2>
+            <UsageSurfaceRows usage={load.usage} />
+
+            {load.usage.unattributed > 0 ? (
+              // ⚠ LABELLED A WIRING GAP, NOT USAGE (E-9). These are AI calls this container could
+              // not attribute to an account. Folding them into somebody's total would be an
+              // invented attribution, and leaving them out entirely would understate the week.
+              <p className="acct-note acct-note--inline">
+                {fmt.int(load.usage.unattributed)} tokens this week could not be attributed to an
+                account. That is a wiring gap in the meter, not somebody's usage.
+              </p>
+            ) : null}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default function UsagePage() {
+  const [load, setLoad] = useState<UsageLoad>({ phase: "loading" });
+  const [scope, setScope] = useState<"me" | "tenant">("me");
+  /**
+   * Whether the workspace view exists for this account, ANSWERED BY ASKING ONCE.
+   *
+   * ⛔ WHY A PROBE RATHER THAN A ROLE CHECK. The frame knows the role, but these pages take no
+   * props by contract (C6's trap: a page that decides its own visibility is a second opinion that
+   * will one day disagree with the route). The route itself is the authority, so the page asks it
+   * once: a 200 means the door is open and the toggle is real; a 403 means it is not and no
+   * control is drawn. ⚠ That 403 is an ANSWER, not an error — it is never shown to the reader.
+   * ⭐ AND IT IS WHAT GIVES `?scope=tenant` A DOOR. E built it admin-only; without this it would
+   * be a finished capability with no caller, which is this repo's most-repeated failure
+   * [[reachable-is-not-the-same-as-built]].
+   */
+  const [canSeeTenant, setCanSeeTenant] = useState(false);
+  const gen = useRef(0);
+
+  const read = useCallback((which: "me" | "tenant") => {
+    const mine = gen.current + 1;
+    gen.current = mine;
+    setLoad({ phase: "loading" });
+    void loadUsage(which === "tenant" ? "tenant" : undefined).then((r) => {
+      if (gen.current !== mine) return;
+      setLoad(r.ok ? { phase: "ready", usage: r.value } : { phase: "failed", message: r.message });
+    });
+  }, []);
+
+  useEffect(() => {
+    read(scope);
+    return () => {
+      gen.current += 1;
+    };
+  }, [read, scope]);
+
+  useEffect(() => {
+    let live = true;
+    void loadUsage("tenant").then((r) => {
+      if (live) setCanSeeTenant(r.ok);
+    });
+    return () => {
+      live = false;
+    };
+  }, []);
+
+  return (
+    <UsageView
+      load={load}
+      scope={scope}
+      canSeeTenant={canSeeTenant}
+      onScope={setScope}
+      onRetry={() => read(scope)}
+    />
+  );
+}

web/src/account/account.css

@@ -1,372 +1,372 @@
-/* ─────────────────────────────────────────────────────────────────────────────────────────
-   account/account.css — WAVE 35, owner item 13: the three surfaces that hang off the
-   account button (Feedback, Usage credits, Subscription).
-
-   ⛔ ITS OWN STYLESHEET, NOT index.css. That file belongs to the INTEGRATOR for the whole
-   wave, and the wave's own rule is that a new surface brings its own sheet. Every selector
-   here is .acct-*; nothing in this file redefines a .home-*, .shell-* or .cg-* rule, so
-   nothing here can win or lose a source-order fight with the shared sheet.
-
-   ⚠ .acct-page RESTATES .shell-home's five box declarations rather than reusing that class,
-   and that is deliberate rather than lazy. .shell-home is Home's box by name and by its own
-   region header; borrowing it would make every future Home layout change silently a change
-   to three account pages. The VALUES are copied on purpose — DESIGN.md 2's sibling rule
-   ("a panel matches its sibling's rendered values, not merely the scale") is what makes the
-   account pages read as the same system as Home, and .shell-main is overflow:hidden, so a
-   page that does not own its own scroll box simply loses everything below the fold.
-
-   ⚠ EVERY font-size IS A --lp-fs-* TOKEN. verify_ui globs src/**.css (every stylesheet in
-   the tree, not just index.css) and goes RED on a literal — wave-21 R5.
-   ───────────────────────────────────────────────────────────────────────────────────────── */
-
-.acct-page {
-  height: 100%;
-  overflow-y: auto;
-  padding: 34px 44px 56px;
-  box-sizing: border-box;
-  background: var(--lp-wash);
-}
-
-/* A short plain noun, same size and weight as .home-title, because it is the same role on a
-   sibling surface. DESIGN.md 2: headers are 1 to 3 words, never a sentence. */
-.acct-title {
-  margin: 0 0 20px;
-  font-size: var(--lp-fs-lg);
-  font-weight: 650;
-  color: var(--lp-ink);
-}
-
-/* THE ONE COLUMN. Every account surface is a reading-width column, not a full-bleed page:
-   a composer, a meter list and a note are all narrow objects, and stretching them to a
-   1600px window is how a page stops looking like it was designed. The reference the owner
-   gave for the assistant uses the same centred column for the same reason. */
-.acct-col {
-  max-width: 640px;
-}
-
-/* ── the honest note (Subscription today; any boarded account surface tomorrow) ─────────
-   ONE containment layer: a hairline panel on the wash, no card inside a card, no shadow
-   (DESIGN.md 4). It is a panel rather than a bare paragraph so the emptiness reads as
-   deliberate instead of as a page that failed to load. */
-.acct-note {
-  margin: 0;
-  padding: 16px 18px;
-  border: 1px solid var(--lp-line);
-  border-radius: var(--lp-r-md);
-  background: var(--lp-surface);
-  font-size: var(--lp-fs-xs);
-  line-height: var(--lp-lh);
-  color: var(--lp-muted);
-}
-
-/* ── loading, and the way back from a failed read ─────────────────────────────────────────── */
-.acct-loading {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 180px;
-}
-.acct-failed {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-}
-/* DESIGN.md 4's quiet button, with the UA chrome reset explicitly (the wave-19 "mystery outer
-   lines and tinted fill" rule). */
-.acct-retry {
-  flex: 0 0 auto;
-  padding: 6px 12px;
-  border: 1px solid var(--lp-line);
-  border-radius: var(--lp-r-md);
-  background: var(--lp-surface);
-  color: var(--lp-ink);
-  font: inherit;
-  font-size: var(--lp-fs-2xs);
-  font-weight: 600;
-  cursor: pointer;
-}
-.acct-retry:hover {
-  background: var(--lp-surface-2);
-  border-color: var(--lp-blue-deep);
-}
-
-/* ── the two answers a write can give ─────────────────────────────────────────────────────
-   Green = positive, red = negative: the fixed semantics (DESIGN.md 3), on the DEEP companions
-   because a pastel on white is not a light aesthetic, it is an unreadable one. */
-.acct-ok,
-.acct-error {
-  margin: 0 0 12px;
-  padding: 9px 12px;
-  border-radius: var(--lp-r-md);
-  font-size: var(--lp-fs-2xs);
-  line-height: var(--lp-lh);
-}
-.acct-ok {
-  border: 1px solid var(--lp-green);
-  background: var(--lp-green-tint);
-  color: var(--lp-green-deep);
-}
-.acct-error {
-  border: 1px solid var(--lp-red);
-  background: var(--lp-red-tint);
-  color: var(--lp-red-deep);
-}
-
-/* ── the composer ─────────────────────────────��───────────────────────────────────────────
-   The ASSISTANT'S anatomy in this module's own rules: one rounded field that contains its own
-   control row, so the category and the send button read as part of the thing being written
-   rather than as chrome around it. `assistant.css` is another session's file this wave and is
-   deliberately not imported; the shape is borrowed, the rules are local.
-   ⚠ The radius is smaller than the assistant's 22px pill on purpose: this field is a paragraph
-   box, not a one-line prompt, and a heavily rounded tall box reads as a speech bubble. */
-.acct-field {
-  border: 1px solid var(--lp-line);
-  border-radius: var(--lp-r-lg);
-  background: var(--lp-surface);
-  padding: 12px 10px 10px 14px;
-}
-.acct-field:focus-within {
-  border-color: var(--lp-blue-solid);
-}
-.acct-prompt {
-  display: block;
-  width: 100%;
-  border: 0;
-  outline: none;
-  padding: 0 6px 0 0;
-  background: transparent;
-  color: var(--lp-ink);
-  font: inherit;
-  font-size: var(--lp-fs-sm);
-  line-height: var(--lp-lh);
-  resize: vertical;
-  box-sizing: border-box;
-}
-.acct-prompt::placeholder {
-  color: var(--lp-muted);
-}
-.acct-field-foot {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  margin-top: 10px;
-}
-.acct-pick {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  min-width: 0;
-}
-.acct-pick-label {
-  color: var(--lp-muted);
-  font-size: var(--lp-fs-2xs);
-}
-.acct-select {
-  max-width: 220px;
-  padding: 4px 8px;
-  border: 1px solid var(--lp-line);
-  border-radius: var(--lp-r-sm);
-  background: var(--lp-surface);
-  color: var(--lp-ink);
-  font: inherit;
-  font-size: var(--lp-fs-2xs);
-  cursor: pointer;
-}
-/* Tabular figures so the count does not jitter as it climbs. Red only once the limit is actually
-   passed: a counter that warns before anything is wrong trains people to ignore it. */
-.acct-count {
-  color: var(--lp-muted);
-  font-size: var(--lp-fs-3xs);
-  font-variant-numeric: tabular-nums;
-}
-.acct-count.is-over {
-  color: var(--lp-red-deep);
-  font-weight: 600;
-}
-/* The send button takes the ink fill when it can send and the wash when it cannot, which is the
-   assistant's own rule: the control says whether there is anything to send before it is pressed. */
-.acct-send {
-  flex: 0 0 auto;
-  margin-left: auto;
-  width: 30px;
-  height: 30px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  border: 0;
-  border-radius: var(--lp-r-pill);
-  background: var(--lp-ink);
-  color: var(--lp-surface);
-  font: inherit;
-  cursor: pointer;
-}
-.acct-send:disabled {
-  background: var(--lp-surface-2);
-  color: var(--lp-muted);
-  cursor: default;
-}
-.acct-send-icon {
-  fill: none;
-  stroke: currentColor;
-  stroke-width: 1.7;
-  stroke-linecap: round;
-  stroke-linejoin: round;
-}
-
-/* ── the usage meter (R9) ─────────────────────────────────────────────────────────────────
-   One containment layer, hairline, no shadow. The bar is the only new SHAPE on these pages, and
-   the ticket asks for it by name ("over the allowance the bar is red"). */
-.acct-note--inline {
-  margin: 12px 0 0;
-  padding: 9px 12px;
-  font-size: var(--lp-fs-2xs);
-}
-.acct-scope {
-  display: inline-flex;
-  gap: 2px;
-  margin-bottom: 14px;
-  padding: 2px;
-  border: 1px solid var(--lp-line);
-  border-radius: var(--lp-r-md);
-  background: var(--lp-surface);
-}
-/* Selection is TINT plus WEIGHT with the ink left alone, which is `.shell-nav-item.is-active`'s
-   rule. ⚠ NOT `--lp-blue-deep` on `--lp-blue-tint`: that pair measures 2.96:1, under the 4.5:1
-   text bar and under the 3:1 graphical one, and this control holds words. */
-.acct-scope-btn {
-  padding: 4px 12px;
-  border: 0;
-  border-radius: var(--lp-r-sm);
-  background: transparent;
-  color: var(--lp-muted);
-  font: inherit;
-  font-size: var(--lp-fs-2xs);
-  font-weight: 600;
-  cursor: pointer;
-}
-.acct-scope-btn:hover {
-  background: var(--lp-surface-2);
-}
-.acct-scope-btn.is-on {
-  background: var(--lp-blue-tint);
-  color: var(--lp-ink);
-}
-
-.acct-meter {
-  padding: 16px 18px;
-  border: 1px solid var(--lp-line);
-  border-radius: var(--lp-r-md);
-  background: var(--lp-surface);
-}
-.acct-meter-head {
-  display: flex;
-  align-items: baseline;
-  gap: 8px;
-  flex-wrap: wrap;
-}
-.acct-meter-who {
-  font-size: var(--lp-fs-2xs);
-  font-weight: 600;
-  color: var(--lp-muted);
-  margin-bottom: 4px;
-}
-/* Tabular figures on every financial-grade number (DESIGN.md 2), so a total that climbs does not
-   make the label beside it dance. Weight 650, never a display weight. */
-.acct-meter-value {
-  font-size: var(--lp-fs-xl);
-  font-weight: 650;
-  color: var(--lp-ink);
-  font-variant-numeric: tabular-nums;
-}
-/* Red = negative/over, the fixed semantic, on the deep companion. */
-.acct-meter-value.is-over {
-  color: var(--lp-red-deep);
-}
-.acct-meter-of {
-  font-size: var(--lp-fs-xs);
-  color: var(--lp-muted);
-  font-variant-numeric: tabular-nums;
-}
-.acct-meter-foot {
-  display: flex;
-  align-items: baseline;
-  justify-content: space-between;
-  gap: 12px;
-  margin-top: 8px;
-  font-size: var(--lp-fs-2xs);
-  color: var(--lp-muted);
-}
-.acct-meter-calls {
-  flex: 0 0 auto;
-  font-variant-numeric: tabular-nums;
-}
-
-/* The track is the wash so an empty meter still reads as a meter rather than as a missing
-   element; the fill is the brand at rest and red once the allowance is passed. */
-.acct-bar {
-  display: block;
-  width: 100%;
-  height: 8px;
-  margin-top: 10px;
-  border-radius: var(--lp-r-pill);
-  background: var(--lp-wash);
-  overflow: hidden;
-}
-.acct-bar-fill {
-  display: block;
-  height: 100%;
-  border-radius: var(--lp-r-pill);
-  background: var(--lp-primary);
-  transition: width 0.18s var(--lp-fold-e);
-}
-.acct-bar-fill.is-over {
-  background: var(--lp-red-deep);
-}
-
-/* A short plain noun, muted, sentence case, matching `.home-section-title` exactly: the same role
-   on a sibling surface takes the same rendered values (DESIGN.md 2). */
-.acct-section {
-  margin: 22px 0 9px;
-  font-size: var(--lp-fs-2xs);
-  font-weight: 600;
-  color: var(--lp-muted);
-}
-.acct-rows {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-}
-/* One row per surface: name, share bar, tokens, calls. Fixed columns so the four numbers form a
-   column a reader can scan rather than four numbers at four different left edges. */
-.acct-row {
-  display: grid;
-  grid-template-columns: 120px 1fr 92px 150px;
-  align-items: center;
-  gap: 12px;
-  padding: 8px 2px;
-  border-bottom: 1px solid var(--lp-line);
-}
-.acct-row:last-child {
-  border-bottom: 0;
-}
-.acct-row-name {
-  font-size: var(--lp-fs-xs);
-  font-weight: 600;
-  color: var(--lp-ink);
-}
-/* Numbers right-aligned, text left (DESIGN.md 2), tabular so the column lines up digit for digit. */
-.acct-row-num {
-  text-align: right;
-  font-size: var(--lp-fs-xs);
-  color: var(--lp-ink);
-  font-variant-numeric: tabular-nums;
-}
-.acct-row-sub {
-  font-size: var(--lp-fs-2xs);
-  color: var(--lp-muted);
-  font-variant-numeric: tabular-nums;
-}
-.acct-row .acct-bar {
-  margin-top: 0;
-  height: 6px;
-}
+/* ─────────────────────────────────────────────────────────────────────────────────────────
+   account/account.css — WAVE 35, owner item 13: the three surfaces that hang off the
+   account button (Feedback, Usage, Subscription).
+
+   ⛔ ITS OWN STYLESHEET, NOT index.css. That file belongs to the INTEGRATOR for the whole
+   wave, and the wave's own rule is that a new surface brings its own sheet. Every selector
+   here is .acct-*; nothing in this file redefines a .home-*, .shell-* or .cg-* rule, so
+   nothing here can win or lose a source-order fight with the shared sheet.
+
+   ⚠ .acct-page RESTATES .shell-home's five box declarations rather than reusing that class,
+   and that is deliberate rather than lazy. .shell-home is Home's box by name and by its own
+   region header; borrowing it would make every future Home layout change silently a change
+   to three account pages. The VALUES are copied on purpose — DESIGN.md 2's sibling rule
+   ("a panel matches its sibling's rendered values, not merely the scale") is what makes the
+   account pages read as the same system as Home, and .shell-main is overflow:hidden, so a
+   page that does not own its own scroll box simply loses everything below the fold.
+
+   ⚠ EVERY font-size IS A --lp-fs-* TOKEN. verify_ui globs src/**.css (every stylesheet in
+   the tree, not just index.css) and goes RED on a literal — wave-21 R5.
+   ───────────────────────────────────────────────────────────────────────────────────────── */
+
+.acct-page {
+  height: 100%;
+  overflow-y: auto;
+  padding: 34px 44px 56px;
+  box-sizing: border-box;
+  background: var(--lp-wash);
+}
+
+/* A short plain noun, same size and weight as .home-title, because it is the same role on a
+   sibling surface. DESIGN.md 2: headers are 1 to 3 words, never a sentence. */
+.acct-title {
+  margin: 0 0 20px;
+  font-size: var(--lp-fs-lg);
+  font-weight: 650;
+  color: var(--lp-ink);
+}
+
+/* THE ONE COLUMN. Every account surface is a reading-width column, not a full-bleed page:
+   a composer, a meter list and a note are all narrow objects, and stretching them to a
+   1600px window is how a page stops looking like it was designed. The reference the owner
+   gave for the assistant uses the same centred column for the same reason. */
+.acct-col {
+  max-width: 640px;
+}
+
+/* ── the honest note (Subscription today; any boarded account surface tomorrow) ─────────
+   ONE containment layer: a hairline panel on the wash, no card inside a card, no shadow
+   (DESIGN.md 4). It is a panel rather than a bare paragraph so the emptiness reads as
+   deliberate instead of as a page that failed to load. */
+.acct-note {
+  margin: 0;
+  padding: 16px 18px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+  font-size: var(--lp-fs-xs);
+  line-height: var(--lp-lh);
+  color: var(--lp-muted);
+}
+
+/* ── loading, and the way back from a failed read ─────────────────────────────────────────── */
+.acct-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 180px;
+}
+.acct-failed {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+/* DESIGN.md 4's quiet button, with the UA chrome reset explicitly (the wave-19 "mystery outer
+   lines and tinted fill" rule). */
+.acct-retry {
+  flex: 0 0 auto;
+  padding: 6px 12px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+  color: var(--lp-ink);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+  font-weight: 600;
+  cursor: pointer;
+}
+.acct-retry:hover {
+  background: var(--lp-surface-2);
+  border-color: var(--lp-blue-deep);
+}
+
+/* ── the two answers a write can give ─────────────────────────────────────────────────────
+   Green = positive, red = negative: the fixed semantics (DESIGN.md 3), on the DEEP companions
+   because a pastel on white is not a light aesthetic, it is an unreadable one. */
+.acct-ok,
+.acct-error {
+  margin: 0 0 12px;
+  padding: 9px 12px;
+  border-radius: var(--lp-r-md);
+  font-size: var(--lp-fs-2xs);
+  line-height: var(--lp-lh);
+}
+.acct-ok {
+  border: 1px solid var(--lp-green);
+  background: var(--lp-green-tint);
+  color: var(--lp-green-deep);
+}
+.acct-error {
+  border: 1px solid var(--lp-red);
+  background: var(--lp-red-tint);
+  color: var(--lp-red-deep);
+}
+
+/* ── the composer ─────────────────────────────────────────────────────────────────────────
+   The ASSISTANT'S anatomy in this module's own rules: one rounded field that contains its own
+   control row, so the category and the send button read as part of the thing being written
+   rather than as chrome around it. `assistant.css` is another session's file this wave and is
+   deliberately not imported; the shape is borrowed, the rules are local.
+   ⚠ The radius is smaller than the assistant's 22px pill on purpose: this field is a paragraph
+   box, not a one-line prompt, and a heavily rounded tall box reads as a speech bubble. */
+.acct-field {
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-lg);
+  background: var(--lp-surface);
+  padding: 12px 10px 10px 14px;
+}
+.acct-field:focus-within {
+  border-color: var(--lp-blue-solid);
+}
+.acct-prompt {
+  display: block;
+  width: 100%;
+  border: 0;
+  outline: none;
+  padding: 0 6px 0 0;
+  background: transparent;
+  color: var(--lp-ink);
+  font: inherit;
+  font-size: var(--lp-fs-sm);
+  line-height: var(--lp-lh);
+  resize: vertical;
+  box-sizing: border-box;
+}
+.acct-prompt::placeholder {
+  color: var(--lp-muted);
+}
+.acct-field-foot {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-top: 10px;
+}
+.acct-pick {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+.acct-pick-label {
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-2xs);
+}
+.acct-select {
+  max-width: 220px;
+  padding: 4px 8px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-sm);
+  background: var(--lp-surface);
+  color: var(--lp-ink);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+  cursor: pointer;
+}
+/* Tabular figures so the count does not jitter as it climbs. Red only once the limit is actually
+   passed: a counter that warns before anything is wrong trains people to ignore it. */
+.acct-count {
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-3xs);
+  font-variant-numeric: tabular-nums;
+}
+.acct-count.is-over {
+  color: var(--lp-red-deep);
+  font-weight: 600;
+}
+/* The send button takes the ink fill when it can send and the wash when it cannot, which is the
+   assistant's own rule: the control says whether there is anything to send before it is pressed. */
+.acct-send {
+  flex: 0 0 auto;
+  margin-left: auto;
+  width: 30px;
+  height: 30px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: var(--lp-r-pill);
+  background: var(--lp-ink);
+  color: var(--lp-surface);
+  font: inherit;
+  cursor: pointer;
+}
+.acct-send:disabled {
+  background: var(--lp-surface-2);
+  color: var(--lp-muted);
+  cursor: default;
+}
+.acct-send-icon {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.7;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+/* ── the usage meter (R9) ─────────────────────────────────────────────────────────────────
+   One containment layer, hairline, no shadow. The bar is the only new SHAPE on these pages, and
+   the ticket asks for it by name ("over the allowance the bar is red"). */
+.acct-note--inline {
+  margin: 12px 0 0;
+  padding: 9px 12px;
+  font-size: var(--lp-fs-2xs);
+}
+.acct-scope {
+  display: inline-flex;
+  gap: 2px;
+  margin-bottom: 14px;
+  padding: 2px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+}
+/* Selection is TINT plus WEIGHT with the ink left alone, which is `.shell-nav-item.is-active`'s
+   rule. ⚠ NOT `--lp-blue-deep` on `--lp-blue-tint`: that pair measures 2.96:1, under the 4.5:1
+   text bar and under the 3:1 graphical one, and this control holds words. */
+.acct-scope-btn {
+  padding: 4px 12px;
+  border: 0;
+  border-radius: var(--lp-r-sm);
+  background: transparent;
+  color: var(--lp-muted);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+  font-weight: 600;
+  cursor: pointer;
+}
+.acct-scope-btn:hover {
+  background: var(--lp-surface-2);
+}
+.acct-scope-btn.is-on {
+  background: var(--lp-blue-tint);
+  color: var(--lp-ink);
+}
+
+.acct-meter {
+  padding: 16px 18px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+}
+.acct-meter-head {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+.acct-meter-who {
+  font-size: var(--lp-fs-2xs);
+  font-weight: 600;
+  color: var(--lp-muted);
+  margin-bottom: 4px;
+}
+/* Tabular figures on every financial-grade number (DESIGN.md 2), so a total that climbs does not
+   make the label beside it dance. Weight 650, never a display weight. */
+.acct-meter-value {
+  font-size: var(--lp-fs-xl);
+  font-weight: 650;
+  color: var(--lp-ink);
+  font-variant-numeric: tabular-nums;
+}
+/* Red = negative/over, the fixed semantic, on the deep companion. */
+.acct-meter-value.is-over {
+  color: var(--lp-red-deep);
+}
+.acct-meter-of {
+  font-size: var(--lp-fs-xs);
+  color: var(--lp-muted);
+  font-variant-numeric: tabular-nums;
+}
+.acct-meter-foot {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 12px;
+  margin-top: 8px;
+  font-size: var(--lp-fs-2xs);
+  color: var(--lp-muted);
+}
+.acct-meter-calls {
+  flex: 0 0 auto;
+  font-variant-numeric: tabular-nums;
+}
+
+/* The track is the wash so an empty meter still reads as a meter rather than as a missing
+   element; the fill is the brand at rest and red once the allowance is passed. */
+.acct-bar {
+  display: block;
+  width: 100%;
+  height: 8px;
+  margin-top: 10px;
+  border-radius: var(--lp-r-pill);
+  background: var(--lp-wash);
+  overflow: hidden;
+}
+.acct-bar-fill {
+  display: block;
+  height: 100%;
+  border-radius: var(--lp-r-pill);
+  background: var(--lp-primary);
+  transition: width 0.18s var(--lp-fold-e);
+}
+.acct-bar-fill.is-over {
+  background: var(--lp-red-deep);
+}
+
+/* A short plain noun, muted, sentence case, matching `.home-section-title` exactly: the same role
+   on a sibling surface takes the same rendered values (DESIGN.md 2). */
+.acct-section {
+  margin: 22px 0 9px;
+  font-size: var(--lp-fs-2xs);
+  font-weight: 600;
+  color: var(--lp-muted);
+}
+.acct-rows {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+/* One row per surface: name, share bar, tokens, calls. Fixed columns so the four numbers form a
+   column a reader can scan rather than four numbers at four different left edges. */
+.acct-row {
+  display: grid;
+  grid-template-columns: 120px 1fr 92px 150px;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 2px;
+  border-bottom: 1px solid var(--lp-line);
+}
+.acct-row:last-child {
+  border-bottom: 0;
+}
+.acct-row-name {
+  font-size: var(--lp-fs-xs);
+  font-weight: 600;
+  color: var(--lp-ink);
+}
+/* Numbers right-aligned, text left (DESIGN.md 2), tabular so the column lines up digit for digit. */
+.acct-row-num {
+  text-align: right;
+  font-size: var(--lp-fs-xs);
+  color: var(--lp-ink);
+  font-variant-numeric: tabular-nums;
+}
+.acct-row-sub {
+  font-size: var(--lp-fs-2xs);
+  color: var(--lp-muted);
+  font-variant-numeric: tabular-nums;
+}
+.acct-row .acct-bar {
+  margin-top: 0;
+  height: 6px;
+}

web/src/account/accountApi.ts

@@ -1,188 +1,188 @@
-// ---------------------------------------------------------------------------
-// account/accountApi.ts — WAVE 35, owner item 13: the wire behind the two account
-// surfaces that have one (Feedback, contract C6/R8; Usage credits, C7/R9).
-//
-// ⛔ THE CATEGORY VOCABULARY IS THE SERVER'S AND IS FETCHED, NOT DECLARED HERE.
-// That is a decision, not an omission: a client constant beside a server enum is
-// two lists that drift, and the day they do the dropdown offers a value the door
-// refuses. Asked and settled in mailbox B-1 / E-9 — the server serves the list,
-// this file renders it, and there is no local fallback to drift TO.
-//
-// ⛔ AND THERE IS NO TENANT-SIDE READ OF A SUBMISSION AT ALL (R8). No "my
-// feedback" list, no edit, no delete: the operator plane is the only reader. The
-// 201 is the receipt. If that ever feels like a gap, it is R8, not a missing
-// endpoint.
-//
-// ⚠ NOTHING ON THE USAGE SIDE IS COMPUTED HERE. The allowance, the week and the
-// reset date all ride the payload (E-9), because a week boundary computed in the
-// browser can disagree with the server's own bucketing — and then the page shows
-// a number that traces to no ledger line, which is exactly what R9's meter must
-// never do.
-// ---------------------------------------------------------------------------
-
-import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
-
-/** The same discriminated result the other feature modules use. */
-export type Result<T> =
-  | { ok: true; value: T }
-  | { ok: false; status: number; message: string };
-
-async function call<T>(
-  path: string,
-  init: RequestInit,
-  read: (body: unknown) => T
-): Promise<Result<T>> {
-  let res: Response;
-  try {
-    res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init });
-  } catch {
-    return { ok: false, status: 0, message: "Cannot reach the server." };
-  }
-  if (checkTenant(res)) return { ok: false, status: 0, message: "Reloading." };
-  if (res.status === 401) signal(UNAUTHORIZED_EVENT);
-  const body = (await res.json().catch(() => null)) as unknown;
-  if (!res.ok) {
-    // ⚠ A 4xx MESSAGE IS POLICY AND IS SHOWN; a 5xx message is an internal detail and is not.
-    // `session.ts` states the same rule for sign-in, and E names each 400 case ("unknown
-    // category", "empty text", "over maxChars"), so the server's sentence is the useful one.
-    const detail = (body as { error?: { message?: string } } | null)?.error?.message;
-    return {
-      ok: false,
-      status: res.status,
-      message:
-        res.status >= 500 || !detail
-          ? res.status >= 500
-            ? "Something went wrong on our side. Try again in a moment."
-            : `The server answered ${res.status}.`
-          : detail,
-    };
-  }
-  return { ok: true, value: read(body) };
-}
-
-const row = (v: unknown): Record<string, unknown> =>
-  v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
-const str = (v: unknown): string => (typeof v === "string" ? v : "");
-const int = (v: unknown): number =>
-  typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
-
-// ── FEEDBACK (R8, C6) ───────────────────────────────────────────────────────────────────────
-
-export interface FeedbackCategory {
-  key: string;
-  label: string;
-}
-
-export interface FeedbackForm {
-  categories: FeedbackCategory[];
-  maxChars: number;
-}
-
-/**
- * `GET /api/v1/feedback/form` — the category list and the length limit, both the server's.
- *
- * ⛔ A CATEGORY WITH NO LABEL IS DROPPED, never rendered as its key: an internal identifier in a
- * dropdown is the same defect `parsePages` refuses one layer up ("a nav row with no name is a
- * door with no sign on it"). And an EMPTY list is a real answer the caller must handle, not a
- * reason to invent one.
- */
-export function parseFeedbackForm(body: unknown): FeedbackForm {
-  const r = row(body);
-  const categories = (Array.isArray(r.categories) ? r.categories : [])
-    .map(row)
-    .filter((c) => str(c.key) !== "" && str(c.label) !== "")
-    .map((c) => ({ key: str(c.key), label: str(c.label) }));
-  return { categories, maxChars: int(r.maxChars) };
-}
-
-export function loadFeedbackForm(): Promise<Result<FeedbackForm>> {
-  return call("/feedback/form", {}, parseFeedbackForm);
-}
-
-export function sendFeedback(category: string, text: string): Promise<Result<{ id: string }>> {
-  return call(
-    "/feedback",
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ category, text }),
-    },
-    (b) => ({ id: str(row(b).id) })
-  );
-}
-
-// ── USAGE (R9, C7) ──────────────────────────────────────────────────────────────────────────
-
-/** One AI surface's week. Every surface is present at zero when unused (E-9), so nothing here
- *  branches on a missing row. */
-export interface UsageSurface {
-  surface: string;
-  calls: number;
-  tokens: number;
-  tokensIn: number;
-  tokensOut: number;
-  /**
-   * Calls whose provider declined to report a token count.
-   *
-   * ⛔ NOT ZERO-PADDING. These are real calls with an UNKNOWN cost, which is why the total beside
-   * them is a FLOOR rather than a figure. A page that hides this presents the floor as complete,
-   * and that is the cost-surprise failure one step removed.
-   */
-  unmeasured: number;
-}
-
-export interface Usage {
-  /** ISO year-week, UTC. A string that sorts chronologically, so nothing here parses a date. */
-  week: string;
-  /** The UTC date the counters roll over, as the server states it. */
-  resets: string;
-  allowance: number;
-  total: number;
-  over: boolean;
-  calls: number;
-  unmeasured: number;
-  /** `"me"` or `"tenant"`. Which question the numbers answer, decided by the server. */
-  scope: string;
-  surfaces: UsageSurface[];
-  /** The server's own sentence about `unmeasured`. Empty when there is nothing unmeasured. */
-  note: string;
-  /**
-   * Admin only: AI calls this container could not attribute to an account.
-   *
-   * ⚠ LABEL IT A WIRING GAP, NOT USAGE (E-9). It is the meter reporting on ITSELF, and folding it
-   * into somebody's total would be an invented attribution.
-   */
-  unattributed: number;
-}
-
-export function parseUsage(body: unknown): Usage {
-  const r = row(body);
-  const surfaces = (Array.isArray(r.surfaces) ? r.surfaces : [])
-    .map(row)
-    .filter((s) => str(s.surface) !== "")
-    .map((s) => ({
-      surface: str(s.surface),
-      calls: int(s.calls),
-      tokens: int(s.tokens),
-      tokensIn: int(s.tokens_in),
-      tokensOut: int(s.tokens_out),
-      unmeasured: int(s.unmeasured),
-    }));
-  return {
-    week: str(r.week),
-    resets: str(r.resets),
-    allowance: int(r.allowance),
-    total: int(r.total),
-    over: r.over === true,
-    calls: int(r.calls),
-    unmeasured: int(r.unmeasured),
-    scope: str(r.scope) || "me",
-    surfaces,
-    note: str(r.note),
-    unattributed: int(r.unattributed),
-  };
-}
-
-export function loadUsage(scope?: "tenant"): Promise<Result<Usage>> {
-  return call(scope === "tenant" ? "/usage?scope=tenant" : "/usage", {}, parseUsage);
-}
+// ---------------------------------------------------------------------------
+// account/accountApi.ts — WAVE 35, owner item 13: the wire behind the two account
+// surfaces that have one (Feedback, contract C6/R8; Usage, C7/R9).
+//
+// ⛔ THE CATEGORY VOCABULARY IS THE SERVER'S AND IS FETCHED, NOT DECLARED HERE.
+// That is a decision, not an omission: a client constant beside a server enum is
+// two lists that drift, and the day they do the dropdown offers a value the door
+// refuses. Asked and settled in mailbox B-1 / E-9 — the server serves the list,
+// this file renders it, and there is no local fallback to drift TO.
+//
+// ⛔ AND THERE IS NO TENANT-SIDE READ OF A SUBMISSION AT ALL (R8). No "my
+// feedback" list, no edit, no delete: the operator plane is the only reader. The
+// 201 is the receipt. If that ever feels like a gap, it is R8, not a missing
+// endpoint.
+//
+// ⚠ NOTHING ON THE USAGE SIDE IS COMPUTED HERE. The allowance, the week and the
+// reset date all ride the payload (E-9), because a week boundary computed in the
+// browser can disagree with the server's own bucketing — and then the page shows
+// a number that traces to no ledger line, which is exactly what R9's meter must
+// never do.
+// ---------------------------------------------------------------------------
+
+import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
+
+/** The same discriminated result the other feature modules use. */
+export type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; status: number; message: string };
+
+async function call<T>(
+  path: string,
+  init: RequestInit,
+  read: (body: unknown) => T
+): Promise<Result<T>> {
+  let res: Response;
+  try {
+    res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init });
+  } catch {
+    return { ok: false, status: 0, message: "Cannot reach the server." };
+  }
+  if (checkTenant(res)) return { ok: false, status: 0, message: "Reloading." };
+  if (res.status === 401) signal(UNAUTHORIZED_EVENT);
+  const body = (await res.json().catch(() => null)) as unknown;
+  if (!res.ok) {
+    // ⚠ A 4xx MESSAGE IS POLICY AND IS SHOWN; a 5xx message is an internal detail and is not.
+    // `session.ts` states the same rule for sign-in, and E names each 400 case ("unknown
+    // category", "empty text", "over maxChars"), so the server's sentence is the useful one.
+    const detail = (body as { error?: { message?: string } } | null)?.error?.message;
+    return {
+      ok: false,
+      status: res.status,
+      message:
+        res.status >= 500 || !detail
+          ? res.status >= 500
+            ? "Something went wrong on our side. Try again in a moment."
+            : `The server answered ${res.status}.`
+          : detail,
+    };
+  }
+  return { ok: true, value: read(body) };
+}
+
+const row = (v: unknown): Record<string, unknown> =>
+  v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+const int = (v: unknown): number =>
+  typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
+
+// ── FEEDBACK (R8, C6) ───────────────────────────────────────────────────────────────────────
+
+export interface FeedbackCategory {
+  key: string;
+  label: string;
+}
+
+export interface FeedbackForm {
+  categories: FeedbackCategory[];
+  maxChars: number;
+}
+
+/**
+ * `GET /api/v1/feedback/form` — the category list and the length limit, both the server's.
+ *
+ * ⛔ A CATEGORY WITH NO LABEL IS DROPPED, never rendered as its key: an internal identifier in a
+ * dropdown is the same defect `parsePages` refuses one layer up ("a nav row with no name is a
+ * door with no sign on it"). And an EMPTY list is a real answer the caller must handle, not a
+ * reason to invent one.
+ */
+export function parseFeedbackForm(body: unknown): FeedbackForm {
+  const r = row(body);
+  const categories = (Array.isArray(r.categories) ? r.categories : [])
+    .map(row)
+    .filter((c) => str(c.key) !== "" && str(c.label) !== "")
+    .map((c) => ({ key: str(c.key), label: str(c.label) }));
+  return { categories, maxChars: int(r.maxChars) };
+}
+
+export function loadFeedbackForm(): Promise<Result<FeedbackForm>> {
+  return call("/feedback/form", {}, parseFeedbackForm);
+}
+
+export function sendFeedback(category: string, text: string): Promise<Result<{ id: string }>> {
+  return call(
+    "/feedback",
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ category, text }),
+    },
+    (b) => ({ id: str(row(b).id) })
+  );
+}
+
+// ── USAGE (R9, C7) ──────────────────────────────────────────────────────────────────────────
+
+/** One AI surface's week. Every surface is present at zero when unused (E-9), so nothing here
+ *  branches on a missing row. */
+export interface UsageSurface {
+  surface: string;
+  calls: number;
+  tokens: number;
+  tokensIn: number;
+  tokensOut: number;
+  /**
+   * Calls whose provider declined to report a token count.
+   *
+   * ⛔ NOT ZERO-PADDING. These are real calls with an UNKNOWN cost, which is why the total beside
+   * them is a FLOOR rather than a figure. A page that hides this presents the floor as complete,
+   * and that is the cost-surprise failure one step removed.
+   */
+  unmeasured: number;
+}
+
+export interface Usage {
+  /** ISO year-week, UTC. A string that sorts chronologically, so nothing here parses a date. */
+  week: string;
+  /** The UTC date the counters roll over, as the server states it. */
+  resets: string;
+  allowance: number;
+  total: number;
+  over: boolean;
+  calls: number;
+  unmeasured: number;
+  /** `"me"` or `"tenant"`. Which question the numbers answer, decided by the server. */
+  scope: string;
+  surfaces: UsageSurface[];
+  /** The server's own sentence about `unmeasured`. Empty when there is nothing unmeasured. */
+  note: string;
+  /**
+   * Admin only: AI calls this container could not attribute to an account.
+   *
+   * ⚠ LABEL IT A WIRING GAP, NOT USAGE (E-9). It is the meter reporting on ITSELF, and folding it
+   * into somebody's total would be an invented attribution.
+   */
+  unattributed: number;
+}
+
+export function parseUsage(body: unknown): Usage {
+  const r = row(body);
+  const surfaces = (Array.isArray(r.surfaces) ? r.surfaces : [])
+    .map(row)
+    .filter((s) => str(s.surface) !== "")
+    .map((s) => ({
+      surface: str(s.surface),
+      calls: int(s.calls),
+      tokens: int(s.tokens),
+      tokensIn: int(s.tokens_in),
+      tokensOut: int(s.tokens_out),
+      unmeasured: int(s.unmeasured),
+    }));
+  return {
+    week: str(r.week),
+    resets: str(r.resets),
+    allowance: int(r.allowance),
+    total: int(r.total),
+    over: r.over === true,
+    calls: int(r.calls),
+    unmeasured: int(r.unmeasured),
+    scope: str(r.scope) || "me",
+    surfaces,
+    note: str(r.note),
+    unattributed: int(r.unattributed),
+  };
+}
+
+export function loadUsage(scope?: "tenant"): Promise<Result<Usage>> {
+  return call(scope === "tenant" ? "/usage?scope=tenant" : "/usage", {}, parseUsage);
+}

web/src/customer-grid/GridChat.tsx

@@ -0,0 +1,512 @@
+// ---------------------------------------------------------------------------
+// customer-grid / GridChat.tsx — the docked chat for ANY database view (W37-T40, R2, R10, C6).
+//
+// Owner items 10 and 11 are ONE feature (ruling R2): the chat IS the builder. This is its shell —
+// the conversation surface every later ticket in the lane hangs a power off. T42 gives it the
+// schema to answer from, T43 the view controls, T44 the Custom View's code, T45 the confirmed
+// record edit.
+//
+// ⛔⛔ IT REACHES INTO NOTHING. Contract C6: every action is a callback the host supplies, and
+// EVERY PROP IS REQUIRED. An optional prop is how a panel ships mounted-but-inert — the feature is
+// whole, the gate is green, and the one line that would have passed the callback was never
+// written. This repo shipped five of those in a single wave. A required prop makes the omission a
+// compile error in the mounting file, which is where a person can see it.
+//
+// ⚠ THE SHAPE IS THE ONE THIS PRODUCT ALREADY HAS, not a third chat look. `AutomationChat` and
+// `AssistantPage` both render a centred opening while the transcript is empty, then a log with the
+// SAME composer moved to the foot; `FieldAgentChat` reuses the same composer classes rather than
+// drawing a second one. Copying that is not laziness, it is the reason the owner cannot tell which
+// surface was built by whom.
+//
+// ⚠ NO `import.meta.env` ANYWHERE IN THIS FILE'S GRAPH, and the constraint is load-bearing rather
+// than stylistic: the gate renders this component from a CommonJS build, and `import.meta` cannot
+// be required from one. `AutomationChat`'s own header records that exact crash. The imports below
+// are `react` + `./gridChat` + the stylesheet, and nothing else.
+// ---------------------------------------------------------------------------
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import {
+  answered,
+  asked,
+  composerHint,
+  editSummary,
+  emptyChat,
+  failed,
+  isBusy,
+  noted,
+  proposedEdits,
+  readIntent,
+  runSentence,
+  wrote,
+} from "./gridChat";
+import type {
+  GridChatAnswer,
+  GridChatEdit,
+  GridChatField,
+  GridChatRunResult,
+  GridChatState,
+  GridChatTurn,
+} from "./gridChat";
+import "./gridChat.css";
+
+// ⭐ RE-EXPORTED SO THE MOUNTING FILE TAKES ONE IMPORT. The types live in `gridChat.ts` (they have
+// to: the state machine is typed by them and that module must stay React-free), but a host that
+// had to import the component from here and its types from there would be one refactor away from
+// the two drifting. Published to C in mailbox E-4 as a single import line.
+export type {
+  GridChatAnswer,
+  GridChatEdit,
+  GridChatField,
+  GridChatRunResult,
+  GridChatState,
+  GridChatTurn,
+};
+
+/**
+ * What the host asks the chat to do about the view. ⚠ DELIBERATELY NARROW: this is the vocabulary
+ * `assistant build_view` already speaks, minus what it cannot express. There is no `rhs` in that
+ * tool schema, so a field-versus-field condition is not sayable
+ * [[assistant-build-view-is-a-subset]] — W37-T43 has to SAY it cannot rather than fail quietly.
+ */
+export interface GridChatViewSpec {
+  /**
+   * ⚠ RESERVED AND DELIBERATELY NOT POPULATED BY `readIntent` YET. The panel understands
+   * sort/group/colour from a sentence; a real FILTER needs the condition vocabulary the host owns,
+   * so this is the slot C fills rather than a field the panel quietly leaves empty. Named here so
+   * it reads as a contract with a known gap instead of a channel nobody noticed was dead
+   * [[flag-shipped-without-its-writer]].
+   */
+  filter?: unknown;
+  sortBy?: string;
+  groupBy?: string;
+  colorBy?: string;
+}
+
+export interface GridChatProps {
+  /** The host owns the toggle. The panel never closes itself except through `onClose`. */
+  open: boolean;
+  onClose: () => void;
+  /** What this chat is reading, in the person's words. Appears in the header and the placeholder. */
+  databaseLabel: string;
+  /** The columns the chat may reason about. The host decides; the chat never discovers. */
+  schema: GridChatField[];
+  rowCount: number;
+  /**
+   * ⛔ R10's BOUND, EXPRESSED AS AN AFFORDANCE. `false` means the edit power is not OFFERED, not
+   * that it is offered and then refused. The chat is not a privilege escalation: a caller whose
+   * own permissions would refuse the write must not be invited to compose one
+   * [[permitted-is-not-answerable]].
+   */
+  canEdit: boolean;
+  /** (a) answer a question about this database. */
+  onDescribe: (question: string) => Promise<GridChatAnswer>;
+  /** (b) change filter, sort, group or colour on the ACTIVE view. */
+  onApplyView: (spec: GridChatViewSpec) => void;
+  /** (b, undo half) put the view back the way it was. */
+  onUndoView: () => void;
+  /** (d) write the cells the person just confirmed. ⛔ Reached only from the confirm control. */
+  onWriteCells: (edits: GridChatEdit[]) => Promise<void>;
+  /** (c) run the Custom View's code and report what happened. */
+  onRunScript: (code: string) => Promise<GridChatRunResult>;
+}
+
+/** The send mark. ⛔ The Assistant's own path, point for point: a second arrow drawn slightly
+ *  differently is precisely how two surfaces stop looking like one product. */
+function SendMark() {
+  return (
+    <svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true" fill="none">
+      <path d="M8 13V3.6M4 7.4 8 3.4l4 4" stroke="currentColor" strokeWidth="1.5"
+            strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+export default function GridChat(props: GridChatProps) {
+  const {
+    open, onClose, databaseLabel, schema, rowCount, canEdit,
+    onDescribe, onApplyView, onUndoView, onWriteCells, onRunScript,
+  } = props;
+
+  const [state, setState] = useState<GridChatState>(emptyChat);
+  const [draft, setDraft] = useState("");
+  const [writing, setWriting] = useState(false);
+  const logRef = useRef<HTMLDivElement | null>(null);
+  const busy = isBusy(state);
+
+  // ⚠ THE UNUSED-POWER GUARD. `onApplyView`, `onUndoView` and `onRunScript` are wired by W37-T43
+  // and W37-T44; naming them here keeps them REQUIRED props from the first mount, so C's wiring
+  // lands with the shell rather than being remembered two tickets later. `void` is the honest
+  // spelling of "held, not yet called" and it survives `noUnusedLocals`.
+  // ⚠ WHERE EACH CALLBACK IS ACTUALLY REACHED, because saying so is the only thing that stops a
+  // required prop becoming a decorative one: `onApplyView` from `send` (T43), `onUndoView` from the
+  // Undo control in the foot row, `onRunScript` from `runScript` below, which `send` calls when the
+  // host returns generated code (T44), `onWriteCells` from the confirm and the undo (T45, R10).
+
+  // The transcript follows the newest turn. Guarded on the ref because the log is not rendered at
+  // all while the conversation is empty (see the opening below).
+  useEffect(() => {
+    const log = logRef.current;
+    if (log) log.scrollTop = log.scrollHeight;
+  }, [state.turns.length, busy]);
+
+  // ⛔ DECLARED BEFORE `send`, AND THE ORDER IS LOAD-BEARING RATHER THAN TIDY. `send`'s
+  // dependency array names `runScript`, and a dependency array is evaluated AT RENDER, not
+  // when the callback fires. With `runScript` declared after `send` that array reads a `const`
+  // in its temporal dead zone and the panel throws `Cannot access 'runScript' before
+  // initialization` on its FIRST paint. ⚠ `tsc` does not catch it: it is a runtime TDZ, and
+  // the build was green with the crash in it.
+  /**
+   * ⭐ W37-T44 — THE CHAT WRITES THE CUSTOM VIEW'S CODE AND RUNS IT.
+   * ⛔ THE SANDBOX IS NOT WIDENED TO MAKE A GENERATED SCRIPT WORK. `onRunScript` is the host's
+   * ordinary run door, the same one a hand-typed script goes through, so a script the chat wrote
+   * has exactly the powers a person's own script has and no more. A failure is REPORTED and the
+   * code is left in the editor to be fixed by hand, never blanked.
+   */
+  const runScript = useCallback((code: string) => {
+    void (async () => {
+      try {
+        const result = await onRunScript(code);
+        setState((s) => noted(s, runSentence(result)));
+      } catch (err) {
+        const why = err instanceof Error && err.message ? err.message : "";
+        setState((s) => noted(s, runSentence({ ok: false, error: why })));
+      }
+    })();
+  }, [onRunScript]);
+
+  const send = useCallback(() => {
+    const said = draft.trim();
+    if (!said || busy) return;
+    setState((s) => asked(s, said));
+    setDraft("");
+
+    // ⭐⭐ W37-T42/T43/T44 — READ THE SENTENCE BEFORE SPENDING ANYTHING ON IT.
+    // ⛔ THE REFUSAL BRANCH IS THE POINT OF T42 AND IT COSTS NOTHING. D-339's defect is an agent
+    // that cannot read the database answering from words alone and inventing a number. The panel
+    // HOLDS the schema, so a question naming a field this database does not have is answered here,
+    // truthfully, without a model call that could only guess.
+    const intent = readIntent(schema, databaseLabel, said);
+    if (intent.refusal) {
+      setState((s) => answered(s, said, { text: intent.refusal!, unanswerable: true }));
+      return;
+    }
+    // ⚠ ...and a question the panel already knows the answer to is not a paid round trip either.
+    if (intent.localAnswer) {
+      setState((s) => answered(s, said, { text: intent.localAnswer! }));
+      return;
+    }
+    if (intent.kind === "view") {
+      // T43: the VIEW changes through the host's callback (C6), and what could NOT be expressed is
+      // named rather than dropped [[assistant-build-view-is-a-subset]].
+      if (intent.view) onApplyView(intent.view);
+      const applied = intent.view
+        ? "The view has been changed. Ask again or press Undo to put it back."
+        : "I could not tell which field you meant, so the view is unchanged.";
+      setState((s) => answered(s, said, {
+        text: intent.cannot ? `${applied} ${intent.cannot}` : applied,
+      }));
+      return;
+    }
+
+    void (async () => {
+      try {
+        const answer = await onDescribe(said);
+        // ⛔ THE PROPOSAL BRANCH IS HERE AND NOT IN THE HOST. A host that returned edits and also
+        // wrote them would make the confirm cosmetic; the panel decides that edits mean "show the
+        // person first", so there is exactly one place that decision can be got wrong.
+        // ⚠ NO CAST. `GridChatAnswer.edits` is a declared part of the contract now, so the host
+        // reads the same channel this line does; it used to be an `as` and the two could drift.
+        const edits = answer?.edits;
+        setState((s) => (canEdit && Array.isArray(edits) && edits.length
+          ? proposedEdits(s, said, answer.text, edits)
+          : answered(s, said, answer)));
+        // ⛔ W37-T44 — AND THIS BRANCH IS THE WHOLE POINT OF THE TICKET. The first draft classified
+        // a build request correctly and then had nothing consume the classification: `runScript`
+        // was defined and `void`ed, so `onRunScript` was unreachable from every path while the
+        // ticket claimed it routed. That is [[reachable-is-not-the-same-as-built]], and `void` is
+        // what hid it from tsc. The host authors the code; the panel runs it and reports.
+        if (typeof answer?.script === "string" && answer.script.trim())
+          runScript(answer.script);
+      } catch (err) {
+        const sentence = err instanceof Error ? err.message : "";
+        setState((s) => failed(s, said, sentence));
+      }
+    })();
+  }, [draft, busy, canEdit, onDescribe, onApplyView, runScript, schema, databaseLabel]);
+
+  const confirmWrite = useCallback((edits: GridChatEdit[]) => {
+    if (writing) return;
+    setWriting(true);
+    void (async () => {
+      try {
+        await onWriteCells(edits);
+        // ⛔ `wrote` rather than `noted`: the note it appends CARRIES THE INVERSE, built from the
+        // `before` values the person confirmed. An undo assembled after the write would have
+        // nothing left to read [[capture-the-inverse-before-the-write]].
+        setState((s) => wrote(s, edits));
+      } catch (err) {
+        const sentence = err instanceof Error && err.message
+          ? err.message
+          : "That write was refused, so nothing changed.";
+        setState((s) => noted(s, sentence));
+      } finally {
+        setWriting(false);
+      }
+    })();
+  }, [onWriteCells, writing]);
+
+  if (!open) return null;
+  return (
+    <GridChatView
+      state={state}
+      draft={draft}
+      writing={writing}
+      databaseLabel={databaseLabel}
+      schema={schema}
+      rowCount={rowCount}
+      canEdit={canEdit}
+      logRef={logRef}
+      onClose={onClose}
+      onDraft={setDraft}
+      onSend={send}
+      onUndoView={onUndoView}
+      onConfirmWrite={confirmWrite}
+      onDeclineWrite={() => setState((s) => noted(s, "Nothing was written."))}
+    />
+  );
+}
+
+/**
+ * ⭐⭐ THE PRESENTATIONAL HALF, AND IT IS SPLIT OUT FOR A REASON A GATE CAN USE.
+ *
+ * `<GridChat>` owns the state; this owns the pixels and takes the state as a prop. That split is
+ * what makes T40's `done-when` observable at all: the only renderer available in this repo is
+ * `react-dom/server`, which fires no events and runs no effects, so a gate can never DRIVE a
+ * stateful component into its in-flight or error state. It can render THIS one into any state it
+ * likes, because the state is an argument.
+ *
+ * ⛔ THE HOST NEVER IMPORTS THIS. `GridChat` is the default export and the contract C6 describes;
+ * every prop on it is required, and nothing here weakens that. Splitting the render out is the
+ * opposite of an optional prop: it adds a seam for the gate without adding a way for a mount to
+ * be silently inert.
+ */
+export function GridChatView(props: {
+  state: GridChatState;
+  draft: string;
+  writing: boolean;
+  databaseLabel: string;
+  schema: GridChatField[];
+  rowCount: number;
+  canEdit: boolean;
+  // ⚠ Typed exactly as `useRef<HTMLDivElement | null>(null)` produces it, and OPTIONAL only
+  // here: a server render has no DOM to scroll, so the gate omits it. The stateful shell
+  // above always passes one.
+  logRef?: React.Ref<HTMLDivElement>;
+  onClose: () => void;
+  onDraft: (text: string) => void;
+  onSend: () => void;
+  onUndoView: () => void;
+  onConfirmWrite: (edits: GridChatEdit[]) => void;
+  onDeclineWrite: () => void;
+}) {
+  const {
+    state, draft, writing, databaseLabel, schema, rowCount, canEdit, logRef,
+    onClose, onDraft, onSend, onUndoView, onConfirmWrite, onDeclineWrite,
+  } = props;
+  const busy = isBusy(state);
+  const hint = composerHint(databaseLabel, canEdit);
+
+  const composer = (
+    <div className="cg-chat-composer">
+      <textarea
+        className="cg-chat-input"
+        value={draft}
+        rows={2}
+        placeholder={hint}
+        aria-label={hint}
+        disabled={busy}
+        onChange={(e) => onDraft(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && !e.shiftKey) {
+            e.preventDefault();
+            onSend();
+          }
+        }}
+      />
+      <div className="cg-chat-composer-foot">
+        {/* ⚠ THE SCOPE LINE, NOT A DISCLAIMER. It says what the chat is reading, which is the one
+            thing a person cannot tell by looking at a docked panel. */}
+        <span className="cg-chat-scope">
+          {rowCount === 1 ? "1 record" : `${rowCount} records`}
+          {schema.length ? `, ${schema.length === 1 ? "1 field" : `${schema.length} fields`}` : ""}
+        </span>
+        <span className="cg-chat-spacer" />
+        {/* ⭐ W37-T43's "and the change is undoable", as a control rather than a promise. It sits
+            beside Send because that is where the person is after asking for a view change, and it
+            calls the host's own undo so there is one place a view can be put back. */}
+        <button
+          type="button"
+          className="cg-chat-ghost"
+          onClick={onUndoView}
+          title="Put the view back the way it was"
+        >
+          Undo view
+        </button>
+        <button
+          type="button"
+          className="cg-chat-send"
+          onClick={onSend}
+          disabled={busy || draft.trim() === ""}
+          aria-label="Send"
+          title="Send"
+        >
+          <SendMark />
+        </button>
+      </div>
+    </div>
+  );
+
+  return (
+    <aside className="cg-chat" aria-label={`Chat about ${databaseLabel}`}>
+      <header className="cg-chat-head">
+        <span className="cg-chat-title">{databaseLabel}</span>
+        <button
+          type="button"
+          className="cg-chat-close"
+          onClick={onClose}
+          aria-label="Close the chat"
+          title="Close the chat"
+        >
+          <svg viewBox="0 0 16 16" width="13" height="13" aria-hidden="true" fill="none">
+            <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5"
+                  strokeLinecap="round" />
+          </svg>
+        </button>
+      </header>
+
+      {/* ⛔ THE LOG IS NOT RENDERED AT ALL WHEN EMPTY, and `hidden` would be the bug. `.cg-chat-log`
+          sets `display: flex`, and an author rule beats the user-agent `[hidden] { display: none }`
+          whatever its specificity. `hidden` would take the log out of the accessibility tree and
+          leave it PAINTED: an empty flex band shoving the centred opening off centre. That exact
+          defect was found and written down one wave ago in `AutomationChat`, and it is invisible to
+          any assertion that reads markup as text [[ui-invisible-to-assertions]]. */}
+      {state.turns.length ? (
+        <div className="cg-chat-log" ref={logRef}>
+          {state.turns.map((turn, i) => (
+            <div className="cg-chat-turn" key={i}>
+              <div
+                className={
+                  "cg-chat-msg " +
+                  (turn.error ? "is-error" : turn.who === "you" ? "is-you"
+                    : turn.who === "note" ? "is-note" : "is-assistant")
+                }
+              >
+                {turn.text}
+              </div>
+
+              {/* ⭐ UNDO, OFFERED FROM THE TRANSCRIPT. R10 says the person confirms before a write;
+                  this is the other half of taking them seriously. A confirmed write they did not
+                  mean stays reversible in the place they are already looking, rather than behind a
+                  toast that faded while they read the result.
+                  ⛔ IT ROUTES THROUGH THE SAME `onWriteCells` the original went through, so the
+                  undo passes the caller's permission wall exactly as the write did. An undo with
+                  its own door would be a second write path, and the one nobody tested. */}
+              {canEdit && turn.undo?.length ? (
+                <div className="cg-chat-undo">
+                  <button
+                    type="button"
+                    className="cg-chat-ghost"
+                    disabled={writing}
+                    onClick={() => onConfirmWrite(turn.undo || [])}
+                  >
+                    Put it back
+                  </button>
+                </div>
+              ) : null}
+
+              {/* ⛔⛔ R10 ON SCREEN: EXACTLY WHAT WILL BE WRITTEN, BEFORE ANYTHING IS. Not a count,
+                  not a summary of a summary. The person sees the record, the field, the old value
+                  and the new one, and nothing reaches `onWriteCells` until they press Write. */}
+              {/* ⛔⛔ `canEdit` IS CHECKED HERE, IN THE VIEW, AND NOT ONLY WHERE THE PROPOSAL IS
+                  BUILT. The stateful shell already refuses to build a proposal for a caller who
+                  may not write, so this looked redundant and was left out of the first draft; the
+                  gate caught it. The wall has to sit where the CONTROL is drawn, because the view
+                  renders whatever state it is handed and a second caller, a replayed transcript or
+                  a permission that changed mid-session would otherwise paint a Write button for
+                  somebody the store is going to refuse [[permitted-is-not-answerable]]. A wall
+                  that depends on its caller's discipline is not a wall. */}
+              {canEdit && turn.edits?.length ? (
+                <div className="cg-chat-edits">
+                  <p className="cg-chat-edits-head">{editSummary(turn.edits)}</p>
+                  <table className="cg-chat-edits-table">
+                    <thead>
+                      <tr><th>Record</th><th>Field</th><th>Now</th><th>Would become</th></tr>
+                    </thead>
+                    <tbody>
+                      {turn.edits.map((edit, j) => (
+                        <tr key={j}>
+                          <td>{edit.rowLabel || edit.rowId}</td>
+                          <td>{edit.fieldLabel || edit.field}</td>
+                          <td className="cg-chat-before">{edit.before || "empty"}</td>
+                          <td className="cg-chat-after">{edit.after || "empty"}</td>
+                        </tr>
+                      ))}
+                    </tbody>
+                  </table>
+                  <div className="cg-chat-edits-act">
+                    <button
+                      type="button"
+                      className="cg-chat-ghost"
+                      disabled={writing}
+                      onClick={onDeclineWrite}
+                    >
+                      Leave it
+                    </button>
+                    <button
+                      type="button"
+                      className="cg-chat-go"
+                      disabled={writing}
+                      onClick={() => onConfirmWrite(turn.edits || [])}
+                    >
+                      {writing ? "Writing" : "Write these"}
+                    </button>
+                  </div>
+                </div>
+              ) : null}
+            </div>
+          ))}
+
+          {/* ⚠ `.lp-spin` is the ONE loading mark in this application. A second spinner vocabulary
+              in a new surface is how an app stops having one. */}
+          {busy ? (
+            <div className="cg-chat-pending" role="status">
+              <span className="lp-spin" aria-hidden="true" />
+              Reading {databaseLabel}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+
+      {/* The centred opening, exactly the shape `AssistantPage` and `AutomationChat` already use.
+          ⚠ NO DECORATIVE MARK: the reference image has a soft dot ring, and neither of this
+          product's two existing chat surfaces does. A mark on the third one is the difference the
+          owner would notice. */}
+      {state.turns.length ? null : (
+        <div className="cg-chat-opening">
+          <h2 className="cg-chat-opening-h">How can I help?</h2>
+          <p className="cg-chat-opening-p">
+            {canEdit
+              ? "Ask about the records in front of you, change what the view shows, or say what to change. Nothing is written until you confirm it."
+              : "Ask about the records in front of you, or change what the view shows."}
+          </p>
+          {composer}
+        </div>
+      )}
+
+      {/* ⚠ ONE composer const, rendered in exactly one place at a time. Two on screen at once is
+          the defect this pattern exists to make impossible. */}
+      {state.turns.length ? <div className="cg-chat-foot">{composer}</div> : null}
+    </aside>
+  );
+}

web/src/customer-grid/ScriptViewPanel.tsx

@@ -113,6 +113,23 @@ function ScriptRefusal({ run }: { run: ScriptRun }) {
   );
 }
 
+/**
+ * ⭐⭐ W37-T41 — THE SHAPE OF A SCRIPT, SHOWN AS A PLACEHOLDER RATHER THAN PREFILLED.
+ *
+ * Picking Custom View mints a view with an EMPTY source (verified: `script_sandbox.check_source("")`
+ * accepts it, which is why "mint on pick" was safe to hand lane C in mailbox E-7). Without this, the
+ * person who has just created one meets a blank box and a Run button, which is not an invitation.
+ *
+ * ⛔ A PLACEHOLDER, NEVER A PREFILLED `value`. Prefilling would make the view DIRTY the moment it
+ * opened, arm Save on code nobody wrote, and put a version nobody asked for into a 40-deep history.
+ * A placeholder vanishes on the first keystroke and is never stored.
+ * ⚠ It is the two lines the sandbox's own fixture uses, so the example a person is shown is the
+ * example the gate proves runs [[test-double-built-from-the-producer]].
+ */
+const SCRIPT_STARTER =
+  "rows = scoped_table()\nemit({'kind': 'kpi', 'label': 'Records', 'value': len(rows)})";
+
+
 export function ScriptOutput({ run }: { run: ScriptRun | null }) {
   if (run === null)
     return <p className="cg-script-empty">Run the script to see what it draws.</p>;
@@ -165,16 +182,31 @@ export const ScriptView = memo(function ScriptView({
   run,
   saving,
   readOnly = false,
+  loading = false,
+  reverting = false,
   onRun,
   onSave,
+  onRevert,
 }: {
   view: ScriptViewRecord | null;
   running: boolean;
   run: ScriptRun | null;
   saving?: boolean;
   readOnly?: boolean;
+  /** ⚠ The host knows whether a fetch is outstanding; the panel cannot tell that from a null view.
+   *  Defaulted so no existing caller breaks, which is safe HERE because the default is the older,
+   *  more pessimistic sentence rather than a silently disabled feature. */
+  loading?: boolean;
+  reverting?: boolean;
   onRun: (draft: string) => void;
   onSave?: (source: string) => void;
+  /**
+   * ⭐ W37-T46 / D-338. Optional for the SAME reason `onSave` is: a read-only reader gets the
+   * editor without the controls, and a caller that cannot revert simply does not pass this. The
+   * control is not rendered at all when it is absent, rather than rendered and refused
+   * [[permitted-is-not-answerable]].
+   */
+  onRevert?: (version: number) => void;
 }) {
   const [draft, setDraft] = useState(view?.source ?? "");
   const loadedId = useRef<string | null>(null);
@@ -186,11 +218,16 @@ export const ScriptView = memo(function ScriptView({
     setDraft(view.source);
   }, [view]);
   const dirty = view !== null && draft !== view.source;
+  // ⛔ W37-T41: "STILL LOADING" AND "COULD NOT BE OPENED" ARE DIFFERENT FACTS AND USED TO SHARE A
+  // SENTENCE. With mint-on-pick (E-7) the normal path now passes through `view === null` for as
+  // long as the fetch takes, so the old copy told every person who created a Custom View that it
+  // was broken, for a moment, every time. A state that renames itself is exactly what cost this
+  // product a QA pass one wave ago [[a-store-outage-renames-itself-at-every-layer]].
   if (view === null)
     return (
       <div className="cg-script">
         <p className="cg-script-empty cg-script-empty--pad">
-          This script view could not be opened.
+          {loading === true ? "Opening this view." : "This script view could not be opened."}
         </p>
       </div>
     );
@@ -202,6 +239,9 @@ export const ScriptView = memo(function ScriptView({
             <span>Code</span>
             <span className="cg-script-meta">
               {`v${view.version}`}
+              {/* ⚠ "v5" alone cannot tell a roll-back from a coincidence of matching code. This is
+                  the sentence that makes the history read as what happened. */}
+              {view.restoredFrom ? `, restored from v${view.restoredFrom}` : ""}
               {dirty ? ", unsaved changes" : ""}
             </span>
             <span className="cg-script-spacer" />
@@ -222,11 +262,55 @@ export const ScriptView = memo(function ScriptView({
               {running ? "Running" : "Run"}
             </button>
           </div>
+          {/* ⭐⭐ W37-T41 — THE PLACEHOLDER IS THE CREATE FLOW'S WHOLE EMPTY STATE, and it is the
+              half that made item 10 worth reopening. Picking Custom View mints a view with an
+              EMPTY source (verified: `script_sandbox.check_source("")` accepts it, which is why
+              "mint on pick" was safe to hand lane C in mailbox E-7). Without this the person who
+              just created one meets a blank box and a Run button, which is not an invitation, it
+              is a puzzle.
+              ⛔ A PLACEHOLDER, NOT A PREFILLED `value`. Prefilling would make the view DIRTY the
+              moment it opened, arm Save on code nobody wrote, and put a version nobody asked for
+              into a 40-deep history. It vanishes on the first keystroke and is never saved. */}
+          {/* ⭐⭐ W37-T46 / D-338 — THE CONTROL THAT WAS MISSING. The API already returned
+              `history` newest-first and the header already showed `v<n>`; there was simply no way
+              to go back, which is the whole of D-338. It matters more now that a chat writes the
+              code (R2): generation without roll-back means one bad answer costs somebody their
+              view, and the person cannot tell in advance which answer that will be.
+              ⛔ THE STRIP IS ABSENT, NOT DISABLED, WHEN THERE IS NOTHING TO GO BACK TO. A first
+              version has no history, and a row of dead controls reads as a broken feature rather
+              than as an empty one.
+              ⚠ `trimmed` is PRINTED when it is non-zero. A history capped at 40 that silently
+              showed 40 would let a reader conclude the view was only ever saved 40 times; saying
+              how many were dropped is the difference between a partial record and a wrong one. */}
+          {(view.history?.length ?? 0) > 0 ? (
+            <div className="cg-script-history" aria-label="Earlier versions">
+              <span className="cg-script-history-lead">Earlier</span>
+              {[...(view.history ?? [])].map((h) => (
+                <button
+                  type="button"
+                  key={h.version}
+                  className="cg-script-history-item"
+                  disabled={readOnly || reverting || onRevert === undefined}
+                  title={`Go back to version ${h.version}, saved by ${h.author || "somebody"}`}
+                  onClick={() => onRevert?.(h.version)}
+                >
+                  {`v${h.version}`}
+                </button>
+              ))}
+              {view.trimmed > 0 ? (
+                <span className="cg-script-history-trimmed">
+                  {`${view.trimmed} older ${view.trimmed === 1 ? "version" : "versions"} dropped`}
+                </span>
+              ) : null}
+              {reverting ? <span className="cg-script-history-trimmed">Going back</span> : null}
+            </div>
+          ) : null}
           <textarea
             className="cg-script-code"
             value={draft}
             spellCheck={false}
             readOnly={readOnly}
+            placeholder={SCRIPT_STARTER}
             aria-label="Script source"
             onChange={(e) => setDraft(e.target.value)}
           />

web/src/customer-grid/Toolbar.tsx

@@ -111,6 +111,14 @@ export interface ToolbarProps {
   unresolvedCount?: number;
   /** Owner item 5 — the cohorts this user has, for `Where [Cohort] [is part of] […]`. */
   lists?: { id: string; name: string }[];
+  /** ⭐⭐ W37-T26 (C4) — the views a `Where [View] [is] […]` condition may name. A PASS-THROUGH:
+   *  this toolbar mounts `FilterBuilderPanel`, so without these two lines the leaf evaluates,
+   *  persists and refuses cycles while being impossible to REACH — mounted-but-never-offered.
+   *  ⚠ Empty = not offered, which is what a server-windowed grid passes (the SQL compiler has no
+   *  arm for the pseudo-column, so a leaf there would be INACTIVE and inactive means every row).
+   *  ⚠ Edited by lane C, not this file's owner: `Toolbar.tsx` is in NO fence and lane C was the
+   *  last session open. See `mailbox/C.md` NOTE C-24. */
+  viewChoices?: { id: string; name: string }[];
   /**
    * Item 12 (C-LOCK) — this view is LOCKED to a cohort. Present = say so in the filter
    * builder, because the lock narrows the list and is not one of the conditions shown there:
@@ -565,6 +573,7 @@ export default function Toolbar({
   pendingMeasureCount = 0,
   unresolvedCount = 0,
   lists = [],
+  viewChoices = [],
   cohortLock,
   copyViews,
   onCopyConfig,
@@ -737,6 +746,7 @@ export default function Toolbar({
             fields={fields}
             measures={measures}
             cohorts={lists}
+            viewChoices={viewChoices}
             filters={filterTree}
             onChange={onFilterTree}
             statusValues={statusValues}

web/src/customer-grid/catalog.css

@@ -0,0 +1,91 @@
+/* customer-grid/catalog.css — W37-T32/T33, the catalog designer's new gestures.
+ *
+ * ⛔ WHY THIS FILE AND NOT index.css: contract C8. `index.css` is 12k+ lines and belongs to lane A
+ * this wave, so every other lane adds styles in its own per-surface stylesheet imported by its own
+ * component. `scriptView.css`, `navExtras.css` and this wave's `map.css` are the precedent.
+ *
+ * ⚠ NOTHING PRINT-RELATED MAY LAND HERE WITHOUT ITS SCAN COMING WITH IT. `catalog.test.ts` reads
+ * `src/index.css` BY NAME for the print-isolation rules (`html.cg-cat-printing body > *`,
+ * `print-color-adjust: exact`, the tokens declared inside `.cg-cat-page`). A print rule moved into
+ * this file would be invisible to that check, which is a gate quietly getting smaller. Everything
+ * below is SCREEN-ONLY designer chrome, on purpose.
+ */
+
+/* --- dragging a page to reorder it (T32 / R6) -----------------------------
+ *
+ * ⛔ PAGES REORDER, THEY DO NOT FREE-FLOAT. A printed document is a sequence, so a page has a
+ * position IN that sequence; only the images inside a section carry free coordinates (T33). The
+ * affordance therefore has to read as "this row moves between other rows", never as "this thing
+ * floats", which is why the drop target is a LINE and not a box.
+ */
+
+.cg-cat-pagerow {
+  /* The grab affordance sits on the row, not on the button inside it: a draggable <button> starts
+     a drag in some browsers, fires a click in others, and does neither reliably in Firefox. */
+  cursor: grab;
+  position: relative;
+  border-radius: 5px;
+}
+
+.cg-cat-pagerow:active {
+  cursor: grabbing;
+}
+
+.cg-cat-pagerow.is-dragging {
+  /* Faded, NOT hidden. A row that vanishes while you hold it makes the list jump under the cursor
+     and you lose the place you were aiming at. */
+  opacity: 0.42;
+}
+
+.cg-cat-pagerow.is-dropzone::before {
+  /* The insertion LINE. A highlighted box would say "drop it into this page"; a line above the row
+     says "it lands here, before this one", which is what actually happens. */
+  content: "";
+  position: absolute;
+  left: 2px;
+  right: 2px;
+  top: -2px;
+  height: 2px;
+  border-radius: 2px;
+  background: #1f4e78;
+}
+
+/* --- free-placed items inside a section (T33 / R6) ------------------------
+ *
+ * ⛔⛔ A COORDINATE-FREE ITEM IS NOT AN ITEM AT THE ORIGIN. Everything authored before this wave
+ * has no `x`/`y`, and the renderer reads that absence as "flow position N" so an existing catalog
+ * keeps printing exactly as it did. These rules only ever apply to an item that HAS coordinates;
+ * the flow layout is untouched and stays the default.
+ */
+
+/* ⛔⛔ DELIBERATELY *NOT* `position: relative`, AND THIS IS THE LOAD-BEARING LINE.
+ *
+ * It was relative, which made the GRID the containing block for every placed item. The grid's
+ * height comes from its in-flow content, and placing an item REMOVES it from that flow: place them
+ * all and the grid collapses to nothing, so `top: 96%` becomes 96% of zero and every placed image
+ * piles at the top. A feedback loop between the layout and the coordinates it is measured in.
+ *
+ * With the grid static, an absolutely-positioned item resolves against `.cg-cat-page`, which is
+ * `position: relative` with an EXPLICIT `height: var(--cat-h)` and `overflow: hidden`. That box is
+ * the sheet of paper: fixed, independent of how much flows inside it, and identical in the designer
+ * and in the print tree. A percentage of it means the same thing forever.
+ * ⚠ The class stays because it MARKS the state for the gate and for the eye. It must not acquire a
+ * `position` later; that is the bug above, coming back.
+ */
+.cg-cat-slot-free {
+  position: static;
+}
+
+.cg-cat-item-free {
+  position: absolute;
+  cursor: grab;
+}
+
+.cg-cat-item-free:active {
+  cursor: grabbing;
+}
+
+.cg-cat-item-free.is-dragging {
+  opacity: 0.55;
+  outline: 1px dashed #1f4e78;
+}

web/src/customer-grid/chatDock.css

@@ -0,0 +1,52 @@
+/* customer-grid/chatDock.css — W37-T29 (contract C6 + C8): the chat's DOCK and its LAUNCHER.
+ *
+ * ⛔ A SEPARATE SHEET FROM E's `gridChat.css` ON PURPOSE, and the split is the contract rather
+ * than taste. C8 hands `index.css` to lane A alone and tells every other lane to add styles in its
+ * own per-surface sheet; E owns how the PANEL looks and this file owns where the HOST puts it and
+ * how a person opens it. Two lanes editing one sheet is the collision C8 exists to prevent.
+ *
+ * ⛔⛔ THE LAUNCHER IS THE WHOLE REASON THIS FILE EXISTS. A panel with no control that opens it is
+ * mounted-but-never-offered, which is this repo's most repeated defect: one wave shipped five whole,
+ * correct, unreachable features past every gate. E's sheet cannot carry the launcher, because the
+ * launcher is not part of the panel.
+ * ⚠ Tokens only, never fresh hexes (DESIGN.md: navy #1F4E78 + gold #C8A24B). No emojis, no
+ * ALL-CAPS chrome.
+ */
+
+/* The dock: a flex child of `.cg-shell`, seated between the views rail and the grid, so the panel
+   reads as part of the workspace rather than as an overlay floating on top of it. E's `.cg-chat`
+   brings its own width floor, ceiling and left border; this wrapper only owns the seat. */
+.cg-chat-dock {
+  display: flex;
+  min-height: 0;
+  align-self: stretch;
+}
+
+/* The launcher. A rail-height strip rather than a floating bubble: a bubble would sit over the
+   grid's own rows, which is the one place a person is trying to read. */
+.cg-chat-open {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  align-self: flex-start;
+  margin: 8px 0 0 8px;
+  padding: 6px 10px;
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 6px;
+  background: var(--lp-surface, #ffffff);
+  color: var(--lp-ink, #1f2937);
+  font-size: var(--lp-fs-xs);
+  line-height: 1.2;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.cg-chat-open:hover {
+  border-color: var(--lp-navy, #1f4e78);
+  color: var(--lp-navy, #1f4e78);
+}
+
+.cg-chat-open:focus-visible {
+  outline: 2px solid var(--lp-gold, #c8a24b);
+  outline-offset: 1px;
+}

web/src/customer-grid/gridChat.css

@@ -0,0 +1,294 @@
+/* customer-grid/gridChat.css — the docked chat panel (W37-T40, contract C8).
+ *
+ * ⛔ MODULE-LOCAL BY CONTRACT, not by preference. C8 hands `index.css` (12k+ lines) to lane A
+ * alone this wave, and every other lane adds styles in its own per-surface sheet imported by its
+ * own component. The precedent already exists next door in `scriptView.css` and `navExtras.css`.
+ * ⚠ Colours come from the design tokens (navy #1F4E78 + gold #C8A24B, DESIGN.md), never from fresh
+ * hexes: a surface that invents its own palette is the thing the constitution exists to prevent.
+ * Only the tokens this file actually uses are named.
+ * ⛔⛔ NO FALLBACK LITERAL INSIDE A `font:` SHORTHAND, and this sheet shipped ten of them before
+ * `web_ui` said so (lane A, mailbox A-47). A fallback there is a SECOND SOURCE OF TRUTH for a size
+ * that silently becomes THE size the day the token is renamed, and `index.css` always loads, so it
+ * can never actually fire. Sizes are therefore `var(--lp-fs-xs)` bare; colours keep their fallback
+ * because a missing colour is a legibility failure rather than a silent wrong number.
+ * ⚠ NO EMOJIS AND NO ALL-CAPS CHROME (DESIGN.md). */
+
+.cg-chat {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  /* ⚠ A FLOOR AND A CEILING, NOT A FIXED WIDTH. The host docks this beside a grid whose columns
+     are the reason the person is here; a panel that cannot give width back squeezes the thing it
+     is talking about. Below the floor the transcript stops being readable, so the floor is real. */
+  min-width: 280px;
+  max-width: 420px;
+  flex: 0 0 340px;
+  background: var(--lp-surface, #ffffff);
+  border-left: 1px solid var(--lp-border, #e4e7ec);
+}
+
+/* Below 1024px a docked panel and a grid cannot both be usable, so the panel takes the surface.
+   ⚠ It does NOT hide itself: hiding would leave the host's toggle saying "open" with nothing on
+   screen, which is a worse failure than a full-width panel the person can close. */
+@media (max-width: 1024px) {
+  .cg-chat { flex: 1 1 auto; max-width: none; border-left: 0; }
+}
+
+.cg-chat-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--lp-border, #e4e7ec);
+  background: var(--lp-surface, #ffffff);
+}
+
+.cg-chat-title {
+  font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+  /* The database name can be long and the header is narrow. Truncating beats wrapping into a
+     two-line header that shifts the whole panel down. */
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.cg-chat-close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-text-muted, #667085);
+  cursor: pointer;
+}
+.cg-chat-close:hover { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-text, #1d2939); }
+
+/* ── the transcript ─────────────────────────────────────────────────────── */
+
+.cg-chat-log {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 14px 12px;
+}
+
+.cg-chat-turn { display: flex; flex-direction: column; gap: 6px; }
+
+.cg-chat-msg {
+  max-width: 92%;
+  padding: 8px 10px;
+  border-radius: 10px;
+  font: 400 var(--lp-fs-xs)/1.55 Inter, system-ui, sans-serif;
+  white-space: pre-wrap;
+  /* ⚠ A pasted column name or an id has no spaces to break on and would otherwise push the panel
+     wider than its own max-width. */
+  overflow-wrap: anywhere;
+}
+
+.cg-chat-msg.is-you {
+  align-self: flex-end;
+  background: var(--lp-navy, #1f4e78);
+  color: #ffffff;
+}
+.cg-chat-msg.is-assistant {
+  align-self: flex-start;
+  background: var(--lp-surface-sunken, #f2f4f7);
+  color: var(--lp-text, #1d2939);
+}
+/* ⚠ The panel talking about ITSELF (a write landed, a proposal was declined) is neither side of
+   the conversation, so it is centred and quiet rather than dressed as an answer. */
+.cg-chat-msg.is-note {
+  align-self: center;
+  max-width: 100%;
+  background: transparent;
+  color: var(--lp-text-muted, #667085);
+  font-size: var(--lp-fs-2xs, 11px);
+  text-align: center;
+  padding: 2px 4px;
+}
+/* ⛔ An error is a KIND OF TURN, in the transcript where it can be re-read while the person
+   rephrases. Not a toast that has already faded by then. */
+.cg-chat-msg.is-error {
+  align-self: flex-start;
+  background: #fef3f2;
+  color: #b42318;
+  border: 1px solid #fecdca;
+}
+
+.cg-chat-pending {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 2px 2px 4px;
+  font: 400 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+
+/* ── the write confirm (R10) ────────────────────────────────────────────── */
+
+.cg-chat-edits {
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 10px;
+  background: var(--lp-surface, #ffffff);
+  padding: 10px;
+}
+
+.cg-chat-edits-head {
+  margin: 0 0 8px;
+  font: 600 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+}
+
+.cg-chat-edits-table {
+  width: 100%;
+  border-collapse: collapse;
+  font: 400 var(--lp-fs-3xs)/1.45 Inter, system-ui, sans-serif;
+  /* A proposal can name more cells than fit; it scrolls rather than being clipped, because a
+     confirm the person cannot fully read is not a confirm. */
+  display: block;
+  max-height: 220px;
+  overflow: auto;
+}
+.cg-chat-edits-table th {
+  text-align: left;
+  font-weight: 600;
+  color: var(--lp-text-muted, #667085);
+  padding: 0 8px 4px 0;
+  position: sticky;
+  top: 0;
+  background: var(--lp-surface, #ffffff);
+}
+.cg-chat-edits-table td {
+  padding: 3px 8px 3px 0;
+  color: var(--lp-text, #1d2939);
+  border-top: 1px solid var(--lp-border, #e4e7ec);
+  vertical-align: top;
+  overflow-wrap: anywhere;
+}
+/* ⚠ The two values are told apart by WEIGHT and colour, never by colour alone: a red/green pair
+   is unreadable to a substantial minority of people, and this is a confirm before a write. */
+.cg-chat-before { color: var(--lp-text-muted, #667085); text-decoration: line-through; }
+.cg-chat-after { color: var(--lp-navy, #1f4e78); font-weight: 600; }
+
+/* ⚠ Centred under the note it belongs to, and quiet: an undo control that shouted would read as
+   a warning that something went wrong, when what happened is exactly what the person confirmed. */
+.cg-chat-undo { display: flex; justify-content: center; margin-top: 2px; }
+
+.cg-chat-edits-act {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 10px;
+}
+
+.cg-chat-ghost,
+.cg-chat-go {
+  border-radius: 7px;
+  padding: 5px 12px;
+  font: 500 var(--lp-fs-2xs)/1.2 Inter, system-ui, sans-serif;
+  cursor: pointer;
+}
+.cg-chat-ghost {
+  border: 1px solid var(--lp-border, #e4e7ec);
+  background: var(--lp-surface, #ffffff);
+  color: var(--lp-text, #1d2939);
+}
+.cg-chat-go {
+  border: 1px solid var(--lp-navy, #1f4e78);
+  background: var(--lp-navy, #1f4e78);
+  color: #ffffff;
+}
+.cg-chat-ghost:disabled,
+.cg-chat-go:disabled { opacity: 0.55; cursor: default; }
+
+/* ── the opening and the composer ───────────────────────────────────────── */
+
+.cg-chat-opening {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  flex: 1 1 auto;
+  min-height: 0;
+  gap: 10px;
+  padding: 16px 12px;
+  text-align: center;
+}
+
+.cg-chat-opening-h {
+  margin: 0;
+  font: 600 var(--lp-fs-lg)/1.3 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+}
+
+.cg-chat-opening-p {
+  margin: 0 0 6px;
+  font: 400 var(--lp-fs-2xs)/1.55 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+
+.cg-chat-foot { padding: 10px 12px 12px; border-top: 1px solid var(--lp-border, #e4e7ec); }
+
+.cg-chat-composer {
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 12px;
+  background: var(--lp-surface, #ffffff);
+  padding: 8px;
+  text-align: left;
+}
+.cg-chat-composer:focus-within { border-color: var(--lp-navy, #1f4e78); }
+
+.cg-chat-input {
+  width: 100%;
+  border: 0;
+  outline: 0;
+  resize: none;
+  background: transparent;
+  color: var(--lp-text, #1d2939);
+  font: 400 var(--lp-fs-xs)/1.5 Inter, system-ui, sans-serif;
+}
+.cg-chat-input::placeholder { color: var(--lp-text-muted, #667085); }
+.cg-chat-input:disabled { color: var(--lp-text-muted, #667085); }
+
+/* ⚠ The foot row sits INSIDE the composer's border, which is the shape `cg-agent-composer-foot`
+   already established. A second card outline under the input would read as two controls. */
+.cg-chat-composer-foot {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 6px;
+}
+
+.cg-chat-scope {
+  font: 400 var(--lp-fs-3xs)/1.3 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+
+.cg-chat-spacer { flex: 1 1 auto; }
+
+.cg-chat-send {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border: 0;
+  border-radius: 50%;
+  background: var(--lp-navy, #1f4e78);
+  color: #ffffff;
+  cursor: pointer;
+}
+.cg-chat-send:disabled {
+  background: var(--lp-surface-sunken, #f2f4f7);
+  color: var(--lp-text-muted, #667085);
+  cursor: default;
+}

web/src/customer-grid/gridChat.ts

@@ -0,0 +1,461 @@
+// ---------------------------------------------------------------------------
+// customer-grid / gridChat.ts — the chat panel's state, as pure functions (W37-T40, R2, C6).
+//
+// ⭐⭐ WHY THE STATE LIVES HERE AND NOT IN THE COMPONENT. `<GridChat>` has to demonstrate three
+// things its `done-when` names: a message history, an in-flight state and an error state. If those
+// transitions live in `useState` callbacks inside the .tsx, the only way to assert on them is to
+// render React and match emitted markup — which pins the compiler's output rather than the
+// behaviour, and goes red on a refactor that changed nothing a person can see. Here they are plain
+// functions over a plain object, so the gate checks the STATE MACHINE without React in the process
+// at all, and the render only has to prove the three states paint.
+//
+// ⛔⛔ NOTHING IN THIS FILE TALKS TO THE NETWORK, THE GRID, OR THE STORE — contract C6, and it is
+// structural rather than a promise. There is no `fetch` here and no import of anything that has
+// one: every action the chat can take arrives as a callback the host supplies. That is what lets
+// the host WALL the chat by simply not passing a power, instead of the chat asking permission and
+// being told no [[permitted-is-not-answerable]].
+//
+// ⚠ NO EM DASH OR EN DASH IN ANY STRING THAT REACHES A SCREEN (standing rule 2). The sentences
+// below are user-facing copy, and `web_prose` cannot see a wrapped JSX sentence, so the discipline
+// is on the author. Commas, colons and full stops carry the same weight and are not AI slop.
+// ---------------------------------------------------------------------------
+
+/** One column the chat is allowed to know about. The host decides what goes in this list. */
+export interface GridChatField {
+  key: string;
+  label: string;
+  type: string;
+}
+
+/**
+ * What a host callback hands back for a question.
+ *
+ * ⛔ `text` IS REQUIRED AND `unanswerable` IS THE HONEST OUT. D-339's lesson is that an agent
+ * which cannot read the database answers from words alone and invents a number; a host that cannot
+ * answer must be able to SAY so rather than return an empty string the panel renders as silence.
+ */
+export interface GridChatAnswer {
+  text: string;
+  /** Set when the question named something this database does not have. Rendered as an answer,
+   *  not as a failure: the person asked a reasonable question about the wrong column. */
+  unanswerable?: boolean;
+  /**
+   * ⭐⭐ R10's PROPOSAL CHANNEL, DECLARED RATHER THAN CAST. The panel reads this to decide that an
+   * answer is a proposed WRITE and must be shown for confirmation instead of rendered as prose.
+   *
+   * ⛔ IT WAS A CAST FIRST, AND THAT WAS THE BUG-IN-WAITING. `GridChat` read
+   * `(answer as {edits?: ...}).edits` while this interface said nothing about it, so the contract
+   * lived in one file and the reader in another. The host reads the PUBLISHED type; a host that
+   * never sees `edits` never sends `edits`, the whole confirm path is dead on arrival, and nothing
+   * anywhere fails [[flag-shipped-without-its-writer]]. Typing it is the difference between a
+   * channel and a coincidence.
+   * ⚠ Its presence is a PROPOSAL, never an instruction: nothing is written until the person
+   * confirms, and a caller with `canEdit:false` is not shown the control at all.
+   */
+  edits?: GridChatEdit[];
+  /**
+   * ⭐⭐ W37-T44's GENERATION CHANNEL. The host authored a Custom View's code; the panel RUNS it
+   * through `onRunScript` and reports what happened.
+   *
+   * ⛔ DECLARED, NOT INFERRED, FOR THE SAME REASON `edits` IS. A channel the reader consumes and
+   * the published type does not mention is a channel the host never fills, and nothing anywhere
+   * fails [[flag-shipped-without-its-writer]] — which is exactly what a `void`ed callback and a
+   * confident `observed:` line looked like in the first draft of this ticket.
+   * ⚠ AUTHORING IS THE HOST'S, RUNNING IS THE PANEL'S. That split is what keeps the sandbox
+   * un-widened: the code goes through the ordinary run door a hand-typed script uses.
+   */
+  script?: string;
+}
+
+/** The outcome of running a Custom View's code. `error` is a sentence, never a stack trace. */
+export interface GridChatRunResult {
+  ok: boolean;
+  error?: string;
+}
+
+/** One cell the chat proposes to write. R10: the person sees `before` and `after` before anything. */
+export interface GridChatEdit {
+  rowId: string;
+  rowLabel: string;
+  field: string;
+  fieldLabel: string;
+  before: string;
+  after: string;
+}
+
+/** Who said it. `note` is the panel talking about itself (a confirm outcome, a cancelled write). */
+export type GridChatWho = "you" | "assistant" | "note";
+
+/**
+ * One turn. ⚠ `error` is a KIND OF TURN rather than a banner, and that is deliberate: a failed
+ * question is part of the conversation a person is having. They will rephrase and try again, and a
+ * toast that has already faded cannot be re-read while they do. `AutomationChat` made the same
+ * call for the same reason; two chat surfaces disagreeing about where failure lives is how one
+ * product stops looking like one product.
+ */
+export interface GridChatTurn {
+  who: GridChatWho;
+  text: string;
+  error?: boolean;
+  /** Present only on a turn that is proposing writes. The panel renders the before/after list. */
+  edits?: GridChatEdit[];
+  /**
+   * ⭐⭐ THE INVERSE OF A WRITE THAT ALREADY HAPPENED, CARRIED ON THE NOTE THAT REPORTS IT.
+   *
+   * ⛔ IT IS BUILT FROM THE PROPOSAL, BEFORE THE WRITE, NOT READ BACK AFTER IT
+   * [[capture-the-inverse-before-the-write]]. Once the cells are written the old values are gone
+   * from the store, so an undo assembled afterwards can only re-read what it just wrote and undo
+   * nothing. Every `GridChatEdit` already carries `before` because the person had to SEE it in
+   * order to confirm, which means the inverse costs nothing extra and cannot be stale.
+   */
+  undo?: GridChatEdit[];
+}
+
+/**
+ * The whole panel state.
+ *
+ * ⭐ `pending` IS THE IN-FLIGHT STATE AND IT IS THE QUESTION ITSELF, not a boolean. A boolean can
+ * go stale against the transcript: two rapid sends with `busy: true` leave no record of which
+ * question is actually outstanding, and the answer lands under whichever turn happens to be last.
+ * Holding the text means the panel can always say what it is waiting on, and `answered()` can
+ * refuse an answer that arrived after the person moved on.
+ */
+export interface GridChatState {
+  turns: GridChatTurn[];
+  pending: string | null;
+}
+
+export function emptyChat(): GridChatState {
+  return { turns: [], pending: null };
+}
+
+export function isBusy(state: GridChatState): boolean {
+  return state.pending !== null;
+}
+
+/**
+ * The person sent something. Returns the new state, or the SAME state when there is nothing to
+ * send or a question is already outstanding.
+ *
+ * ⛔ ONE QUESTION AT A TIME, AND THE REFUSAL IS SILENT BY DESIGN. The composer disables its own
+ * send button while `pending`, so a second send can only arrive from a key repeat or a double
+ * click. Answering that with an error turn would put a scolding message in a transcript the person
+ * did not mean to write in. Returning the same object also lets the caller skip the re-render.
+ */
+export function asked(state: GridChatState, said: string): GridChatState {
+  const text = String(said || "").trim();
+  if (!text || state.pending !== null) return state;
+  return { turns: [...state.turns, { who: "you", text }], pending: text };
+}
+
+/**
+ * A host callback answered. `forQuestion` is the text `asked()` returned in `pending`.
+ *
+ * ⛔ AN ANSWER TO A QUESTION NOBODY IS WAITING ON IS DROPPED. A slow first answer that lands after
+ * the person cancelled and asked something else would otherwise be appended under the new question
+ * and read as its answer. Checking the text is enough here because `asked()` refuses to start a
+ * second question while one is outstanding, so at most one can ever be in flight.
+ */
+export function answered(
+  state: GridChatState,
+  forQuestion: string,
+  answer: GridChatAnswer,
+): GridChatState {
+  if (state.pending === null || state.pending !== forQuestion) return state;
+  const said = String(answer?.text || "").trim();
+  return {
+    turns: [...state.turns, {
+      who: "assistant",
+      // ⚠ An empty answer is a defect in the host, not a blank bubble for the reader to interpret.
+      text: said || "That came back empty, so there is nothing to show. Try asking again.",
+      error: !said,
+    }],
+    pending: null,
+  };
+}
+
+/**
+ * A host callback failed. `sentence` is what the person reads.
+ *
+ * ⛔ THE SENTENCE IS THE PRODUCT. `HTTP 402` on a screen tells a reader nothing they can do, and
+ * the owner has quoted a raw status back at us twice. A caller with nothing better than an
+ * exception name passes nothing and gets the fallback below, which at least says what happened and
+ * what to do next.
+ */
+export function failed(
+  state: GridChatState,
+  forQuestion: string,
+  sentence?: string,
+): GridChatState {
+  if (state.pending === null || state.pending !== forQuestion) return state;
+  const said = String(sentence || "").trim();
+  return {
+    turns: [...state.turns, {
+      who: "assistant",
+      text: said || "That did not go through. Nothing was changed, so it is safe to try again.",
+      error: true,
+    }],
+    pending: null,
+  };
+}
+
+/** The panel telling the person what it just did. Never in flight, never an error. */
+export function noted(state: GridChatState, text: string): GridChatState {
+  const said = String(text || "").trim();
+  if (!said) return state;
+  return { ...state, turns: [...state.turns, { who: "note", text: said }] };
+}
+
+/**
+ * The assistant is proposing cell writes and wants a confirm (R10).
+ *
+ * ⭐ THE PROPOSAL IS A TURN, not a modal. A modal would cover the transcript the person needs in
+ * order to judge the proposal, and it would vanish on a mis-click taking the reasoning with it.
+ * ⛔ NOTHING IS WRITTEN BY THIS FUNCTION. It appends a turn carrying the before/after list; the
+ * host's `onWriteCells` is reached only from the confirm control, which is W37-T45's half.
+ */
+export function proposedEdits(
+  state: GridChatState,
+  forQuestion: string,
+  text: string,
+  edits: GridChatEdit[],
+): GridChatState {
+  if (state.pending === null || state.pending !== forQuestion) return state;
+  const rows = (edits || []).filter((e) => e && e.rowId && e.field);
+  if (!rows.length) return answered(state, forQuestion, { text });
+  return {
+    turns: [...state.turns, {
+      who: "assistant",
+      text: String(text || "").trim() || "Here is exactly what this would write.",
+      edits: rows,
+    }],
+    pending: null,
+  };
+}
+
+/**
+ * The inverse of a set of edits: what would put every cell back.
+ *
+ * ⛔ CALL THIS BEFORE THE WRITE, NOT AFTER. It reads `before`, which only exists on the proposal
+ * the person confirmed; after the write the store holds `after` and there is nothing left to
+ * invert from [[capture-the-inverse-before-the-write]].
+ * ⚠ `rowLabel` and `fieldLabel` are carried through unchanged, so an undo confirm reads in the
+ * same words the original proposal did rather than in keys.
+ */
+export function invertEdits(edits: GridChatEdit[]): GridChatEdit[] {
+  return (edits || [])
+    .filter((e) => e && e.rowId && e.field)
+    .map((e) => ({ ...e, before: e.after, after: e.before }));
+}
+
+/**
+ * A confirmed write landed. The note it appends CARRIES ITS OWN INVERSE, so undo is offered from
+ * the transcript rather than from a toast that has already gone.
+ */
+export function wrote(state: GridChatState, edits: GridChatEdit[]): GridChatState {
+  const rows = (edits || []).filter((e) => e && e.rowId && e.field);
+  if (!rows.length) return state;
+  return {
+    ...state,
+    turns: [...state.turns, {
+      who: "note",
+      text: `Written. ${editSummary(rows)}`,
+      undo: invertEdits(rows),
+    }],
+  };
+}
+
+/**
+ * The one-line summary a confirm control shows beside the before/after list.
+ *
+ * ⚠ It counts CELLS and RECORDS separately because they are different risks: twenty cells on one
+ * record is a correction, one cell on twenty records is a sweep. A single "20 changes" hides which
+ * of those the person is about to approve.
+ */
+export function editSummary(edits: GridChatEdit[]): string {
+  const rows = (edits || []).filter((e) => e && e.rowId && e.field);
+  if (!rows.length) return "Nothing to write.";
+  const records = new Set(rows.map((e) => e.rowId)).size;
+  const cellWord = rows.length === 1 ? "cell" : "cells";
+  const recordWord = records === 1 ? "record" : "records";
+  return `${rows.length} ${cellWord} on ${records} ${recordWord}.`;
+}
+
+/**
+ * What the composer invites the person to type.
+ *
+ * ⚠ IT NAMES THE DATABASE. A chat docked beside a grid is ambiguous about what it is reading the
+ * moment a person has two tabs open, and the fix is one word in the placeholder rather than a
+ * second header line.
+ */
+export function composerHint(databaseLabel: string, canEdit: boolean): string {
+  const where = String(databaseLabel || "").trim() || "this database";
+  return canEdit
+    ? `Ask about ${where}, or say what to change`
+    : `Ask about ${where}`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════
+// ⭐⭐ THE INTENT LAYER (W37-T42 · T43 · T44) — WHAT THE CHAT KNOWS WITHOUT SPENDING ANYTHING
+//
+// ⛔⛔ ITS JOB IS TO REFUSE HONESTLY BEFORE A MODEL CALL, NOT TO BE CLEVER. D-339's lesson is that
+// an agent which cannot read the database answers from WORDS ALONE and invents a number; the fix
+// is not a better guess, it is knowing what this database actually has and saying so when the
+// question names something it does not. The panel holds the schema, so that answer costs nothing
+// and cannot be wrong in the direction that matters.
+// ⚠ EVERYTHING HERE IS PURE AND LOCAL. Anything that needs a model, a query or a write goes out
+// through a host callback (C6). This layer only decides WHICH callback, and catches the questions
+// that should never reach one.
+// ═══════════════════════════════════════════════════════════════════════════════════════════
+
+/** What the panel decided a sentence was asking for. */
+export type GridChatIntentKind = "schema" | "view" | "script" | "ask";
+
+export interface GridChatIntent {
+  kind: GridChatIntentKind;
+  /** A complete answer the panel can give with NO model call. Present only when it truly can. */
+  localAnswer?: string;
+  /** Set when the sentence names something this database does not have. */
+  refusal?: string;
+  /** For `view`: what the panel understood, in the vocabulary the host's callback takes. */
+  view?: { sortBy?: string; groupBy?: string; colorBy?: string };
+  /** For `view`: what was asked for and CANNOT be expressed, named rather than dropped. */
+  cannot?: string;
+}
+
+const norm = (s: string) => String(s || "").toLowerCase().trim();
+
+/**
+ * Which known fields a sentence mentions, by label or by key.
+ *
+ * ⚠ LABEL FIRST AND LONGEST FIRST. A person types the label they can see ("Sales rep"), not the
+ * key (`agent_id`), and matching short keys first would let a field called `n` match the word "in".
+ */
+export function fieldsNamed(schema: GridChatField[], said: string): GridChatField[] {
+  const text = norm(said);
+  if (!text) return [];
+  return (schema || [])
+    .filter((f) => f && (f.label || f.key))
+    .slice()
+    .sort((a, b) => (b.label || b.key).length - (a.label || a.key).length)
+    .filter((f) => {
+      const label = norm(f.label);
+      const key = norm(f.key);
+      return (label.length > 2 && text.includes(label))
+        || (key.length > 2 && text.includes(key));
+    });
+}
+
+/**
+ * A quoted name that this database does not have, if the sentence contains one.
+ *
+ * ⛔ ONLY QUOTED NAMES, DELIBERATELY. Guessing that any capitalised phrase is a column would refuse
+ * perfectly good questions ("how many are in New York?"), and a refusal that fires on a real
+ * question is worse than a model call that answers it. Quotes are the one place a person has said
+ * "this is a name" out loud, so the panel can be certain enough to answer instead of asking.
+ * ⚠ This is the D-339 half the panel can do alone. Everything unquoted still goes to the host,
+ * which knows the data and can say `unanswerable` with better information than a regex has.
+ */
+export function unknownFieldNamed(schema: GridChatField[], said: string): string | null {
+  const quoted = String(said || "").match(/"[^"]{1,60}"|'[^']{1,60}'/g) || [];
+  const known = new Set((schema || []).flatMap((f) => [norm(f.label), norm(f.key)]));
+  for (const raw of quoted) {
+    const typed = raw.slice(1, -1).trim();
+    // ⛔ COMPARE LOWERCASED, RETURN AS TYPED, AND THE FIRST DRAFT DID NOT. It returned the
+    // normalised form, so somebody who wrote "Supplier Rep" was told there is no field called
+    // "supplier rep" — their own words handed back mangled, which reads as the system having
+    // misheard them rather than as an honest answer. Matching is case-insensitive because a person
+    // should not have to match a label's capitalisation; the MESSAGE quotes them exactly.
+    if (typed && !known.has(norm(typed))) return typed;
+  }
+  return null;
+}
+
+/** The plain-language field list, for a question the panel can answer with no model call at all. */
+export function schemaSentence(schema: GridChatField[], databaseLabel: string): string {
+  const where = String(databaseLabel || "").trim() || "this database";
+  const names = (schema || []).map((f) => f.label || f.key).filter(Boolean);
+  if (!names.length) return where + " has no fields the chat can see.";
+  const word = names.length === 1 ? "field" : "fields";
+  return where + " has " + names.length + " " + word + ": " + names.join(", ") + ".";
+}
+
+/** Sentences that are asking what is here, rather than asking about the data. */
+const SCHEMA_WORDS = ["what fields", "which fields", "what columns", "which columns",
+                      "list the fields", "list the columns", "what can you see"];
+/** Sentences asking for the VIEW to change rather than for an answer. */
+const VIEW_WORDS = ["sort by", "sorted by", "group by", "grouped by", "colour by", "color by",
+                    "show me only", "filter"];
+/** Sentences asking for code. */
+const SCRIPT_WORDS = ["build me", "make me", "write a script", "custom view", "dashboard",
+                      "calculator", "chart"];
+
+/**
+ * Read a sentence. ⛔ THE ORDER IS THE POLICY: refuse first, answer locally second, route third.
+ *
+ * ⚠ A DELIBERATELY SHALLOW READER. It is not trying to understand the question, because the host's
+ * model does that. It is trying to catch the two cases where going to the model is WRONG: a name
+ * this database does not have (which would come back as an invented number), and a question the
+ * panel already knows the answer to (which would be a paid round trip for a list it is holding).
+ */
+export function readIntent(
+  schema: GridChatField[],
+  databaseLabel: string,
+  said: string,
+): GridChatIntent {
+  const text = norm(said);
+  const where = String(databaseLabel || "").trim() || "this database";
+  const missing = unknownFieldNamed(schema, said);
+  if (missing) {
+    const names = (schema || []).map((f) => f.label || f.key).filter(Boolean);
+    return {
+      kind: "ask",
+      refusal: 'There is no field called "' + missing + '" in ' + where + ". "
+        + (names.length
+          ? "The fields here are: " + names.join(", ") + "."
+          : "This database has no fields the chat can see."),
+    };
+  }
+  if (SCHEMA_WORDS.some((w) => text.includes(w)))
+    return { kind: "schema", localAnswer: schemaSentence(schema, databaseLabel) };
+
+  if (VIEW_WORDS.some((w) => text.includes(w))) {
+    const named = fieldsNamed(schema, said);
+    const view: { sortBy?: string; groupBy?: string; colorBy?: string } = {};
+    if (named.length) {
+      if (text.includes("group")) view.groupBy = named[0].key;
+      else if (text.includes("colour") || text.includes("color")) view.colorBy = named[0].key;
+      else if (text.includes("sort")) view.sortBy = named[0].key;
+    }
+    // ⛔ WHAT IT CANNOT SAY, SAID OUT LOUD. `assistant build_view` has no `rhs` in its tool schema,
+    // so a condition comparing one field to another is not expressible anywhere in this product
+    // [[assistant-build-view-is-a-subset]]. Dropping it silently would leave a person looking at a
+    // view that quietly ignored half their sentence, which is the failure this note exists to stop.
+    const fieldVsField = named.length >= 2 && /\b(than|versus|vs\.?|compared to)\b/.test(text);
+    return {
+      kind: "view",
+      view: Object.keys(view).length ? view : undefined,
+      cannot: fieldVsField
+        ? "This build cannot compare one field against another in a view filter, so that part was "
+          + "left out. Everything else was applied."
+        : undefined,
+    };
+  }
+  if (SCRIPT_WORDS.some((w) => text.includes(w))) return { kind: "script" };
+  return { kind: "ask" };
+}
+
+/**
+ * The sentence shown when a script the chat wrote is run.
+ *
+ * ⛔ THE VIEW IS NOT BLANKED ON FAILURE (W37-T44's own `done-when`). A script that raised is a fact
+ * about the code, and the code is still there to be edited; replacing the panel with nothing would
+ * take away the one thing the person needs in order to fix it.
+ */
+export function runSentence(result: GridChatRunResult): string {
+  if (result && result.ok) return "That ran. The view is showing what it drew.";
+  const why = String((result && result.error) || "").trim();
+  return why
+    ? "That script did not run: " + why + " The code is still in the editor, so you can change it."
+    : "That script did not produce a view. The code is still in the editor, so you can change it.";
+}

web/src/customer-grid/map.css

@@ -0,0 +1,209 @@
+/* customer-grid/map.css — W37-T35/T36, the real-tile basemap and its credit line.
+ *
+ * ⛔ WHY THIS FILE EXISTS AND NOT A BLOCK IN index.css: contract C8. `index.css` is 12k+ lines and
+ * belongs to lane A this wave, so every other lane adds styles in its own per-surface stylesheet
+ * imported by its own component. `scriptView.css` and `navExtras.css` are the precedent.
+ *
+ * ⚠ NOTHING HERE MAY ADD `vector-effect: non-scaling-stroke` TO A `.cg-map*` RULE. The map divides
+ * every stroke by the zoom in the markup (`hairline`), so a CSS rule that also cancels the scale
+ * double-compensates, and that is the wave-9 "blurry when zoomed in" bug. `map.test.ts` scans
+ * `index.css` for it and cannot see this file, so `verify_map.py::css_scan` applies the same rule
+ * here. A new stylesheet that escapes an existing gate is a gate quietly getting smaller.
+ */
+
+/* --- the tile layer -------------------------------------------------------
+ *
+ * Tiles are <image> elements INSIDE the same transformed <g> the pins live in, so they pan and
+ * zoom with the geography for free and no second camera can drift out of step with the first.
+ */
+
+.cg-map-tiles {
+  /* A raster basemap is a photograph of a map, so it must never intercept a gesture: every
+     pointer event belongs to the pins and the marquee above it. */
+  pointer-events: none;
+  /* ⭐ THE DARK-MODE SEAM, and it is deliberately INERT today. This app ships no dark theme (there
+     is not one `prefers-color-scheme` rule in `index.css`), so an inverting media query here would
+     turn the basemap negative for anyone whose OS is dark while the rest of the product stayed
+     light, which is a defect rather than a feature. Setting `--cg-tile-filter` is one line on the
+     day a theme arrives. */
+  filter: var(--cg-tile-filter, none);
+}
+
+.cg-map-tile {
+  /* Tile edges are cut to the pixel, so any smoothing at the seam paints a visible grid over the
+     whole basemap. */
+  image-rendering: -webkit-optimize-contrast;
+}
+
+/* The tile the browser has not fetched yet. Without this a pan shows the page background through
+   the gaps, which reads as holes in the map rather than as loading. */
+.cg-map-tilebed {
+  fill: #eef2f7;
+}
+
+/* --- attribution ----------------------------------------------------------
+ *
+ * ⛔ THIS IS A LICENCE TERM, NOT DECORATION. OpenStreetMap's terms require visible credit wherever
+ * its tiles are shown, and the same applies to whatever provider replaces it: the text and the
+ * link both come from the server's provider config, so a swap carries its own credit with it and
+ * cannot leave the previous one on screen.
+ */
+
+.cg-map-credit {
+  position: absolute;
+  right: 6px;
+  bottom: 4px;
+  z-index: 2;
+  padding: 1px 6px;
+  border-radius: 4px;
+  background: rgba(255, 255, 255, 0.82);
+  /* ⛔ A TOKEN, NOT A LITERAL (R5, and A-53 caught the 10.5px this replaced). A hardcoded size
+     becomes THE size the day the type scale moves, so a stylesheet that invents one is a second
+     source of truth. `--lp-fs-4xs` is the 10px step, which is what a credit line wants. */
+  font: 400 var(--lp-fs-4xs)/1.5 Inter, system-ui, sans-serif;
+  color: #5b6270;
+  letter-spacing: 0.1px;
+}
+
+.cg-map-credit a {
+  color: #4a5568;
+  text-decoration: none;
+}
+
+.cg-map-credit a:hover {
+  text-decoration: underline;
+}
+
+/* --- the route line (T36) -------------------------------------------------
+ *
+ * The ROAD geometry, as distinct from `.cg-map-route-line`, which is the straight-line plan drawn
+ * from arithmetic alone. Two different claims about the same stops, so two different looks: the
+ * road route is solid and confident, the straight-line plan stays dashed and provisional.
+ */
+
+.cg-map-road {
+  fill: none;
+  stroke: #1f4e78;
+  stroke-opacity: 0.85;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.cg-map-road-halo {
+  fill: none;
+  stroke: #ffffff;
+  stroke-opacity: 0.75;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+/* --- the ordered stop list (T36) ------------------------------------------
+ *
+ * The route's stops as a row of numbered chips with move controls. Inline in the map bar rather
+ * than in a panel: reordering is a thing people do WHILE looking at the map, and a dialog over the
+ * picture would hide the answer they are reordering against.
+ */
+
+.cg-map-stoplist {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex-wrap: wrap;
+  max-width: 460px;
+}
+
+.cg-map-stopitem {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  padding: 1px 2px 1px 4px;
+  border: 1px solid #dfe3ea;
+  border-radius: 11px;
+  background: #fff;
+  font: 500 var(--lp-fs-3xs)/1.6 Inter, system-ui, sans-serif;
+  color: #2c3340;
+}
+
+.cg-map-stopn {
+  display: inline-grid;
+  place-items: center;
+  width: 15px;
+  height: 15px;
+  border-radius: 50%;
+  background: #1f4e78;
+  color: #fff;
+  font-size: var(--lp-fs-5xs);
+  font-weight: 600;
+}
+
+.cg-map-stopname {
+  max-width: 108px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cg-map-stopmove {
+  display: inline-grid;
+  place-items: center;
+  width: 15px;
+  height: 15px;
+  padding: 0;
+  border: 0;
+  border-radius: 3px;
+  background: none;
+  color: #6b7280;
+  cursor: pointer;
+}
+
+.cg-map-stopmove:hover:not(:disabled) {
+  background: #eef2f7;
+  color: #1f4e78;
+}
+
+.cg-map-stopmove:disabled {
+  /* Visible but inert at the ends of the list. Removing the control instead would make the row
+     change width as a stop moves, so the button you are aiming at walks away from the cursor. */
+  opacity: 0.28;
+  cursor: default;
+}
+
+.cg-map-stopmove svg {
+  width: 11px;
+  height: 11px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.7;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+/* --- the address lookup (T37) ---------------------------------------------
+ *
+ * ⛔ THE PROGRESS LINE IS A REQUIREMENT, NOT A COURTESY. The free geocoder allows about one
+ * request a second, so a run over a real selection takes minutes. A spinner would make that read
+ * as a hang; a count that moves reads as work. The note beside it says WHY it is slow, because
+ * "this product is slow" and "this service asks us to be polite" are different facts.
+ */
+
+.cg-map-geo {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.cg-map-geo-run {
+  font: 500 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
+  color: #1f4e78;
+}
+
+.cg-map-geo-note {
+  font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
+  color: #6b7280;
+}
+
+/* The lookup offered from the EMPTY state. A map with nothing on it is exactly where this feature
+   is needed, and the control used to be unreachable there (see MapView's `geoControl`). */
+.cg-map-geo-empty {
+  margin-top: 10px;
+}

web/src/customer-grid/mapProjection.ts

@@ -1,632 +1,677 @@
-// ---------------------------------------------------------------------------
-// customer-grid / mapProjection.ts
-// Wave-8 I2/I6 — the map's geometry, split from MapView so it can be tested
-// under node without React.
-//
-// WHY THIS EXISTS AS ITS OWN LAYER. The wave-7 map derived its projection from
-// the DATA's bounding box (MapView.tsx:96-118, an equirectangular fit). That is
-// fine for a static scatter and wrong for everything wave 8 asks of it:
-//
-//   - the map re-projected on every filter change, so the whole picture jumped
-//     whenever a condition was edited;
-//   - box-select needs a stable screen<->point mapping DURING a drag, which a
-//     projection memoised over `points` is not;
-//   - a data-fit projection distorts real geography — state outlines drawn
-//     through it visibly skew once you zoom into one metro.
-//
-// So the two concerns are separated:
-//   PROJECTION  fixed Web Mercator, world -> a fixed square. Never changes.
-//   VIEW        {k, tx, ty} — zoom and pan, an affine transform ON TOP.
-// The old data-fit becomes the INITIAL VIEW value rather than the projection,
-// which is what makes zoom/pan and hit-testing tractable at all.
-// ---------------------------------------------------------------------------
-
-/** Base resolution of the projected world square, in SVG user units. */
-export const WORLD = 4096;
-
-/** Mercator blows up at the poles; every web map clamps. */
-const MAX_LAT = 85.05112878;
-
-export interface Pt {
-  x: number;
-  y: number;
-}
-
-/** A pan/zoom transform: screen = view.t + view.k * projected. */
-export interface View {
-  k: number;
-  tx: number;
-  ty: number;
-}
-
-/** lon/lat -> the fixed projected plane (0..WORLD on both axes). */
-export function project(lon: number, lat: number): Pt {
-  const clamped = Math.max(-MAX_LAT, Math.min(MAX_LAT, lat));
-  const rad = (clamped * Math.PI) / 180;
-  const x = (lon + 180) / 360;
-  const y = 0.5 - Math.log(Math.tan(Math.PI / 4 + rad / 2)) / (2 * Math.PI);
-  return { x: x * WORLD, y: y * WORLD };
-}
-
-/** The fixed projected plane -> lon/lat. The exact inverse of `project`. */
-export function unproject(p: Pt): { lon: number; lat: number } {
-  const t = 0.5 - p.y / WORLD;
-  const rad = 2 * Math.atan(Math.exp(2 * Math.PI * t)) - Math.PI / 2;
-  return { lon: (p.x / WORLD) * 360 - 180, lat: (rad * 180) / Math.PI };
-}
-
-/** Screen -> the fixed projected plane, through a view. The inverse of `toScreen`. */
-export function fromScreen(s: Pt, view: View): Pt {
-  return { x: (s.x - view.tx) / view.k, y: (s.y - view.ty) / view.k };
-}
-
-// -------------------------------------------------------- the Google hand-off
-//
-// The honest answer to "I need to see the actual street". A licence-free offline
-// vector basemap stops at roughly metro scale (see BASEMAP_DETAIL_K), and the
-// alternative — bundling a tile renderer — costs 270 KB gz, an API key or a
-// hosted planet file, and sends every customer's coordinates to a third party on
-// every pan. A LINK costs none of that: nothing ships, nothing is fetched, and
-// the coordinates travel only if the user deliberately clicks.
-//
-// ⚠ Every one of these must be rendered with rel="noopener noreferrer" — that
-// strips the Referer, so the destination never learns which tenant or which
-// deployment the click came from, and it denies the opened tab window.opener.
-
-/**
- * Google Maps' zoom level for our zoom `k`.
- *
- * Google measures a world 256 * 2^z px wide; ours is WORLD units wide, painted
- * at `k` and then ~1.08 CSS px per unit. Equating the two:
- *   256 * 2^z = WORLD * k * 1.08   ->   z = log2(WORLD * 1.08 * k / 256)
- * Clamped to Google's own 0..21. A fitted US book (k~1.36) hands over z5, the
- * country; the detail cap (k=32) hands over z9, a metro — i.e. the hand-off
- * starts exactly where our basemap runs out, which is the point of it.
- */
-export function googleZoomForK(k: number): number {
-  if (!Number.isFinite(k) || k <= 0) return 4;
-  const z = Math.log2((WORLD * 1.08 * k) / 256);
-  return Math.max(0, Math.min(21, Math.round(z)));
-}
-
-/** True only for a coordinate Google can actually be sent. */
-export function isPlottable(lat: number | null, lon: number | null): boolean {
-  return (
-    lat != null && lon != null &&
-    Number.isFinite(lat) && Number.isFinite(lon) &&
-    Math.abs(lat) <= 90 && Math.abs(lon) <= 180
-  );
-}
-
-/**
- * A dropped pin at exactly the coordinate WE plotted.
- *
- * ⚠ Deliberately by lat/lon and never by customer name or address: a name search
- * can resolve somewhere else entirely, and then the app's map and the link
- * disagree about where a customer is. The pin is the geocode; the link is the
- * same geocode. `api=1` is Google's documented, stable URL contract.
- */
-export function googleMapsUrl(lat: number, lon: number, zoom?: number): string {
-  const at = `${lat.toFixed(6)},${lon.toFixed(6)}`;
-  return zoom == null
-    ? `https://www.google.com/maps/search/?api=1&query=${at}`
-    : `https://www.google.com/maps/@${at},${Math.round(zoom)}z`;
-}
-
-/** Directions to a customer — the version a rep on the road actually wants. */
-export function googleDirectionsUrl(lat: number, lon: number): string {
-  return `https://www.google.com/maps/dir/?api=1&destination=${lat.toFixed(6)},${lon.toFixed(6)}`;
-}
-
-/** Projected point -> screen, through a view. */
-export function toScreen(p: Pt, view: View): Pt {
-  return { x: view.tx + p.x * view.k, y: view.ty + p.y * view.k };
-}
-
-/**
- * The view that frames `pts` inside a w x h viewport with `pad` px of margin.
- * `minSpan` stops a single point (or one city) from zooming to street level:
- * one customer should still look like a PLACE, not a full-bleed dot — the
- * wave-7 behaviour, kept.
- */
-export function fitView(
-  pts: Pt[],
-  w: number,
-  h: number,
-  pad = 40,
-  minSpan = WORLD / 90
-): View | null {
-  if (pts.length === 0) return null;
-  let minX = Infinity;
-  let maxX = -Infinity;
-  let minY = Infinity;
-  let maxY = -Infinity;
-  for (const p of pts) {
-    minX = Math.min(minX, p.x);
-    maxX = Math.max(maxX, p.x);
-    minY = Math.min(minY, p.y);
-    maxY = Math.max(maxY, p.y);
-  }
-  let spanX = Math.max(maxX - minX, minSpan);
-  let spanY = Math.max(maxY - minY, minSpan);
-  const cx = (minX + maxX) / 2;
-  const cy = (minY + maxY) / 2;
-  spanX *= 1.16; // breathing room so edge pins are not on the frame
-  spanY *= 1.16;
-  const k = Math.min((w - pad * 2) / spanX, (h - pad * 2) / spanY);
-  return { k, tx: w / 2 - cx * k, ty: h / 2 - cy * k };
-}
-
-/** Zoom by `factor` while holding the point under (mx, my) still — the gesture
- *  every map has and the reason zoom cannot be a plain scale on the group. */
-export function zoomAt(view: View, factor: number, mx: number, my: number, kMin: number, kMax: number): View {
-  const k = Math.max(kMin, Math.min(kMax, view.k * factor));
-  if (k === view.k) return view;
-  return {
-    k,
-    tx: mx - ((mx - view.tx) * k) / view.k,
-    ty: my - ((my - view.ty) * k) / view.k,
-  };
-}
-
-// ---------------------------------------------------------------- stroke width
-//
-// ⚠ THE MAP HAS EXACTLY ONE STROKE-WIDTH MECHANISM, AND THIS IS IT.
-//
-// Everything painted inside `<g transform="... scale(k)">` is scaled by k, so a
-// line meant to read 1.1 px on screen must be handed 1.1/k. That is `hairline`.
-// SVG offers a SECOND way to the same end — the CSS `vector-effect:
-// non-scaling-stroke`, which makes the renderer ignore the transform when it
-// strokes. Either works. Using BOTH cancels the zoom twice, and the line then
-// gets THINNER the further you zoom IN.
-//
-// Wave 9 found exactly that, and it is the "blurry when zoomed" bug the owner
-// reported. `.cg-map-land` carried the CSS property AND `hair(1.1)`. Measured
-// against the real constants (WORLD 4096, viewBox 1000x620, ~1.10 CSS px per
-// viewBox unit, fitted k ~1.359): the coastline painted 0.89 CSS px at the
-// fitted view, 0.445 at 2x, 0.089 at 10x and 0.015 at the zoom cap — below
-// ~0.5 px a stroke is an anti-aliased smear and below ~0.2 px a ghost. The
-// graticule, the lakes and the pins were all correct, because they use
-// `hairline` alone. The bug hid precisely because two idioms coexisted on
-// different elements of the same picture.
-//
-// So the rule is singular now, and it is GATED rather than merely commented:
-// `paintedStroke` must be flat across the whole zoom range, and
-// `scalingConflicts` re-reads the real stylesheet so the CSS half cannot come
-// back either. If a future element genuinely wants `non-scaling-stroke`, that
-// is a deliberate change to this rule — change the comment and the gate, not
-// just the stylesheet.
-
-/** Stroke width to hand an element drawn INSIDE the zoomed group. */
-export function hairline(basePx: number, k: number): number {
-  return basePx / k;
-}
-
-/**
- * A dash pattern for a line drawn INSIDE the zoomed group.
- *
- * ⚠ Exactly the same trap as stroke width, and it caught me: `stroke-dasharray`
- * in CSS is in USER units, so inside `scale(k)` a "5 4" dash becomes 5k on and
- * 4k off. At a regional fit that is a 70 px dash and a 55 px gap — the route
- * line renders as a few disconnected strokes floating between the stops, which
- * reads as a broken polyline rather than a scaled dash. Every length handed to
- * the transformed group goes through `hairline`, dashes included.
- */
-export function dashPattern(onPx: number, offPx: number, k: number): string {
-  return `${hairline(onPx, k)} ${hairline(offPx, k)}`;
-}
-
-/**
- * What the renderer actually paints, in screen units, for a `hairline` width at
- * zoom k — i.e. the attribute multiplied by the group's scale. Not circular: it
- * models the SVG pipeline, which is the thing the invariant is about. It must
- * return `basePx` at EVERY k, and the gate sweeps the range to prove it.
- */
-export function paintedStroke(basePx: number, k: number): number {
-  return hairline(basePx, k) * k;
-}
-
-/**
- * The CSS half of the same invariant: any `.cg-map*` rule that declares
- * `vector-effect: non-scaling-stroke` is double-compensating against
- * `hairline`. Returns the offending selectors (empty = clean) so the gate can
- * name them. Comments are stripped first so a commented-out example cannot trip
- * it.
- */
-export function scalingConflicts(css: string): string[] {
-  const bad: string[] = [];
-  for (const chunk of css.replace(/\/\*[\s\S]*?\*\//g, "").split("}")) {
-    const brace = chunk.indexOf("{");
-    if (brace < 0) continue;
-    const selector = chunk.slice(0, brace);
-    if (!selector.includes(".cg-map")) continue;
-    if (/vector-effect\s*:[^;]*non-scaling/i.test(chunk.slice(brace + 1)))
-      bad.push(selector.trim().replace(/\s+/g, " "));
-  }
-  return bad;
-}
-
-/**
- * How far in the VENDORED basemap is still worth showing, as an absolute zoom.
- *
- * DERIVED, not chosen by feel. The geometry in mapGeometry.ts is Natural Earth
- * 50m simplified at 0.02 degrees, giving a ~13 km median vertex spacing. With
- * the viewBox painting ~1.08 CSS px per unit at latitude 39, one screen pixel is
- * ~7041/k metres, so a 13 km segment measures ~1.85*k pixels. At k = 32 that is
- * a ~60 px straight run and ~10 px of simplification error — coarse but still
- * unmistakably a shape. Past it the coastline degenerates into long straight
- * lines and the user is zooming into an empty polygon, which is the opposite of
- * the sharpness this was asked for.
- *
- * ⚠ This is an HONESTY limit and it is the reason the map stops where it does:
- * street-level detail is not available from any licence-free offline vector set.
- * It needs a tile provider — a runtime network dependency, an API key and an
- * attribution obligation — which is the owner's call, not a silent addition.
- */
-export const BASEMAP_DETAIL_K = 32;
-
-/**
- * The camera's zoom range for a given fitted zoom.
- *
- * `kMin` — zoom OUT to four times the data's own extent for context, but never
- * past the point where the whole projected world already fits: beyond that
- * there is nothing further to reveal, only empty margin. (The wave-8 rule was a
- * flat `fit.k * 0.6`, which locked you in at barely half a step out.)
- *
- * `kMax` — how far IN. This is a HONESTY limit as much as a UX one: zooming
- * past the resolution of the basemap actually vendored just shows a bigger
- * empty polygon, so `detailK` caps it. Pass `Infinity` for no cap.
- */
-export function zoomLimits(
-  fitK: number,
-  viewH: number,
-  detailK = Infinity
-): { kMin: number; kMax: number } {
-  const worldFit = viewH / WORLD;
-  const kMin = Math.min(fitK, Math.max(worldFit, fitK * 0.25));
-  return { kMin, kMax: Math.max(fitK, Math.min(fitK * 60, detailK)) };
-}
-
-/**
- * Graticule opacity at zoom k. The 10-degree grid earns its place on a
- * zoomed-OUT world view, where it is the only thing giving scale. Once wave 9
- * vendored real state borders it became noise the moment you zoom into the
- * country: two competing line systems over the same picture. So it fades out
- * before the borders take over rather than fighting them.
- */
-export function graticuleOpacity(k: number): number {
-  return Math.max(0, Math.min(1, (1.5 - k) / 0.9));
-}
-
-/**
- * Where to put a hover card of `w` x `h` for a pin at (sx, sy), in screen space.
- *
- * Prefers ABOVE the pin, flips below when there is no room, and clamps inside
- * the viewport on both axes — a card that runs off the frame is a card whose
- * numbers cannot be read, and the pins nearest the edge are exactly the ones a
- * territory question is usually about.
- */
-export function cardBox(
-  sx: number, sy: number, w: number, h: number,
-  viewW: number, viewH: number, gap = 14, pad = 6
-): Pt {
-  const above = sy - h - gap;
-  // ⚠ Both axes clamp UNCONDITIONALLY. Clamping only the "flipped below" branch
-  // looks right and is not: a pin panned off the BOTTOM of the frame still has
-  // acres of room "above" it, passes the room check, and places the card far
-  // below the viewport. Caught by the every-corner leg, never by a screenshot.
-  return {
-    x: Math.max(pad, Math.min(viewW - w - pad, sx - w / 2)),
-    y: Math.max(pad, Math.min(viewH - h - pad, above >= pad ? above : sy + gap)),
-  };
-}
-
-// ---------------------------------------------------------- route planning
-//
-// I18-R. Sequencing a visit order is a TRAVELLING SALESMAN problem, and it is
-// pure arithmetic: no data, no service, no dependency, no cost. The half that
-// costs money is turning an order into ROAD distances, and this deliberately
-// does not attempt that — see `routeNote` and the mailbox's tier analysis
-// (Google's route matrix bills per element: a 30-stop run is ~$4.50, a full
-// 1,550-customer matrix ~$12,000).
-
-/** A stop, in the coordinates the host geocoded — never projected units. */
-export interface GeoStop {
-  lat: number;
-  lon: number;
-}
-
-/**
- * ⚠ THE SEAM. Everything below takes distance as a FUNCTION and knows nothing
- * else about it. Swapping in real road distances later (a self-hosted OSRM
- * matrix, precomputed and cached) is then a one-line change at the call site
- * rather than a rewrite of the sequencer.
- */
-export type StopDistance = (a: GeoStop, b: GeoStop) => number;
-
-const EARTH_R_KM = 6371.0088;
-
-/**
- * Great-circle distance in km.
- *
- * ⚠ MUST be computed on lon/lat, NOT as euclidean distance in projected WORLD
- * units. Mercator stretches by 1/cos(latitude): across this book's range
- * (lat 25-49) that is a 0.91 -> 0.66 swing, ~38%, which systematically ranks
- * north-south pairs against east-west ones. The resulting route looks entirely
- * plausible and is wrong, which is the worst kind of wrong.
- */
-export const haversineKm: StopDistance = (a, b) => {
-  const rad = Math.PI / 180;
-  const dLat = (b.lat - a.lat) * rad;
-  const dLon = (b.lon - a.lon) * rad;
-  const s =
-    Math.sin(dLat / 2) ** 2 +
-    Math.cos(a.lat * rad) * Math.cos(b.lat * rad) * Math.sin(dLon / 2) ** 2;
-  return 2 * EARTH_R_KM * Math.asin(Math.min(1, Math.sqrt(s)));
-};
-
-/** Total length of a tour. `roundTrip` adds the closing edge back to the start. */
-export function tourLength(
-  order: number[], stops: GeoStop[], dist: StopDistance, roundTrip = false
-): number {
-  if (order.length < 2) return 0;
-  let km = 0;
-  for (let i = 1; i < order.length; i++) km += dist(stops[order[i - 1]], stops[order[i]]);
-  if (roundTrip) km += dist(stops[order[order.length - 1]], stops[order[0]]);
-  return km;
-}
-
-/** Greedy construction: from `start`, repeatedly hop to the nearest unvisited stop. */
-export function nearestNeighbourOrder(
-  stops: GeoStop[], dist: StopDistance, start = 0
-): number[] {
-  const n = stops.length;
-  if (n === 0) return [];
-  const from = Math.max(0, Math.min(n - 1, Math.round(start) || 0));
-  const seen = new Array<boolean>(n).fill(false);
-  const order = [from];
-  seen[from] = true;
-  for (let k = 1; k < n; k++) {
-    const last = order[order.length - 1];
-    let best = -1;
-    let bestD = Infinity;
-    for (let i = 0; i < n; i++) {
-      if (seen[i]) continue;
-      const d = dist(stops[last], stops[i]);
-      if (d < bestD) { bestD = d; best = i; }
-    }
-    if (best < 0) break;
-    seen[best] = true;
-    order.push(best);
-  }
-  return order;
-}
-
-/**
- * 2-opt: repeatedly reverse a segment when doing so shortens the tour.
- *
- * Index 0 is PINNED — it is the origin the user chose, and silently re-rooting
- * their route would be a worse bug than a slightly longer one. Only strictly
- * improving moves are accepted, which is what makes "never returns a tour
- * longer than the one it was given" a guarantee the gate can assert rather than
- * a hope.
- */
-export function twoOptOrder(
-  order: number[], stops: GeoStop[], dist: StopDistance,
-  roundTrip = false, maxPasses = 24
-): number[] {
-  const n = order.length;
-  const cur = order.slice();
-  if (n < 4) return cur;
-  const D = (a: number, b: number) => dist(stops[a], stops[b]);
-  for (let pass = 0; pass < maxPasses; pass++) {
-    let improved = false;
-    for (let i = 1; i < n - 1; i++) {
-      for (let j = i + 1; j < n; j++) {
-        const a = cur[i - 1], b = cur[i], c = cur[j];
-        let delta: number;
-        if (j === n - 1 && !roundTrip) {
-          // Reversing the tail of an OPEN path only re-hangs the entry edge:
-          // there is no closing edge to pay for.
-          delta = D(a, c) - D(a, b);
-        } else {
-          const d = cur[(j + 1) % n];
-          delta = D(a, c) + D(b, d) - D(a, b) - D(c, d);
-        }
-        if (delta < -1e-9) {
-          for (let lo = i, hi = j; lo < hi; lo++, hi--) {
-            const t = cur[lo]; cur[lo] = cur[hi]; cur[hi] = t;
-          }
-          improved = true;
-        }
-      }
-    }
-    if (!improved) break;
-  }
-  return cur;
-}
-
-/** Construct then improve. Returns the visit order and its length. */
-export function planRoute(
-  stops: GeoStop[], dist: StopDistance,
-  opts: { start?: number; roundTrip?: boolean } = {}
-): { order: number[]; km: number } {
-  const roundTrip = !!opts.roundTrip;
-  if (stops.length === 0) return { order: [], km: 0 };
-  const nn = nearestNeighbourOrder(stops, dist, opts.start ?? 0);
-  const order = twoOptOrder(nn, stops, dist, roundTrip);
-  return { order, km: tourLength(order, stops, dist, roundTrip) };
-}
-
-// --------------------------------------------------- handing the route over
-//
-// MEASURED 2026-07-29, do not re-derive: Google Maps URLs need NO API key and
-// cost NOTHING, but they carry at most 9 waypoints on desktop and 3 on mobile
-// browsers, inside a 2,048-character URL.
-
-export const ROUTE_WAYPOINTS_DESKTOP = 9;
-export const ROUTE_WAYPOINTS_MOBILE = 3;
-export const MAX_MAPS_URL = 2048;
-
-/** How many STOPS can ride the free URL: the waypoints plus the two endpoints
- *  (a round trip returns to its origin, so the origin is not also a waypoint). */
-export function routeStopCap(coarsePointer: boolean, roundTrip = false): number {
-  const w = coarsePointer ? ROUTE_WAYPOINTS_MOBILE : ROUTE_WAYPOINTS_DESKTOP;
-  return roundTrip ? w + 1 : w + 2;
-}
-
-/**
- * Build the free Google directions URL for an ORDERED list of stops.
- *
- * Returns `used` alongside the url so the caller can say "first 11 of 23" on
- * screen. It never silently drops a stop; truncation is a fact the UI states
- * ([[no-unverifiable-aggregates]]). Shrinks further if the character budget
- * binds, which it can with a long tail of 6-dp coordinates.
- */
-export function googleRouteUrl(
-  stops: GeoStop[],
-  opts: { roundTrip?: boolean; coarsePointer?: boolean } = {}
-): { url: string; used: number } | null {
-  if (stops.length < 2) return null;
-  const roundTrip = !!opts.roundTrip;
-  const at = (s: GeoStop) => `${s.lat.toFixed(6)},${s.lon.toFixed(6)}`;
-  let used = Math.min(stops.length, routeStopCap(!!opts.coarsePointer, roundTrip));
-  for (;;) {
-    const chosen = stops.slice(0, used);
-    const origin = chosen[0];
-    const dest = roundTrip ? origin : chosen[chosen.length - 1];
-    const mids = roundTrip ? chosen.slice(1) : chosen.slice(1, -1);
-    const url =
-      `https://www.google.com/maps/dir/?api=1&origin=${at(origin)}` +
-      `&destination=${at(dest)}` +
-      (mids.length ? `&waypoints=${mids.map(at).join("|")}` : "") +
-      `&travelmode=driving`;
-    if (url.length <= MAX_MAPS_URL || used <= 2) return { url, used };
-    used -= 1;
-  }
-}
-
-/** An svg's own bounding box in client px — the `getBoundingClientRect()` half
- *  of the conversion below, taken as plain data so the maths stays testable
- *  without a DOM. */
-export interface FrameRect {
-  left: number;
-  top: number;
-  width: number;
-  height: number;
-}
-
-/**
- * Client px -> the svg's own user-space coords. Every pointer gesture on the
- * map — marquee, rubber band, cursor-anchored wheel zoom — starts here.
- *
- * ⚠ It is NOT `(client / frame) * viewBox`. MapView paints with
- * `preserveAspectRatio="xMidYMid meet"`, so the viewBox is scaled UNIFORMLY by
- * the tighter of the two axes and then CENTRED, leaving a letterbox band on the
- * other axis. Wave 8 (`f6f45a6`) bolted a stretch-to-fill conversion onto that
- * `meet` svg: the binding axis came out right and the other carried BOTH a
- * wrong scale and a missing offset. On a 1400x600 frame the full 0..1000
- * x-range collapsed into ~154..846 — so a marquee at either edge caught
- * NOTHING, the rubber band lagged the cursor by ~150 px, and cursor-anchored
- * zoom drifted, all from this one function. `zoomAt` and the hit test were
- * always correct; they were being handed the wrong point.
- *
- * ⛔ The result is deliberately NOT clamped to the viewBox. A drag that begins
- * in the letterbox band is a real gesture — everything from the painted edge
- * inward must still be caught — and clamping re-breaks exactly the edge
- * marquee this exists to fix.
- */
-export function clientToUser(
-  clientX: number,
-  clientY: number,
-  rect: FrameRect,
-  viewW: number,
-  viewH: number
-): Pt {
-  const s = Math.min(rect.width / viewW, rect.height / viewH);
-  if (!(s > 0) || !Number.isFinite(s)) return { x: 0, y: 0 };
-  const offX = (rect.width - viewW * s) / 2;
-  const offY = (rect.height - viewH * s) / 2;
-  return { x: (clientX - rect.left - offX) / s, y: (clientY - rect.top - offY) / s };
-}
-
-/**
- * Is `p` inside the closed polygon `poly`? Even-odd ray casting (the crossing
- * number), in the same user-space units `toScreen` returns.
- *
- * ⛔ It is NOT a bounding-box test, and that difference IS the feature. A lasso
- * drawn as a C or a horseshoe must EXCLUDE whatever sits in its mouth —
- * otherwise it is the rectangle marquee wearing a lasso's name, which is the
- * one thing a person drawing a loop by hand would never expect. The gate
- * asserts exactly that case, over a shape whose bounding box gives a different
- * answer: a convex test polygon would make the control inert.
- *
- * The ray is cast along +x from `p`, and each edge that straddles `p.y` and
- * crosses to the LEFT of nothing / RIGHT of `p.x` flips the parity. A point
- * exactly on a vertex or an edge may fall either way: this selects pins under a
- * hand-drawn path, where a half-pixel tie carries no meaning and an epsilon to
- * break it would be a number nobody could justify.
- */
-export function pointInPolygon(p: Pt, poly: Pt[]): boolean {
-  if (poly.length < 3) return false;
-  let inside = false;
-  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
-    const a = poly[i];
-    const b = poly[j];
-    const straddles = a.y > p.y !== b.y > p.y;
-    if (straddles && p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
-  }
-  return inside;
-}
-
-/**
- * The axis-aligned bounds of a freehand path, in `normRect`'s own {x0,y0,x1,y1}
- * shape so one mis-click rule can measure either gesture. An empty path is a
- * zero box rather than an Infinity one — the caller's "did this move at all"
- * test must answer NO, not NaN.
- */
-export function pathBounds(pts: Pt[]) {
-  if (pts.length === 0) return { x0: 0, y0: 0, x1: 0, y1: 0 };
-  let x0 = pts[0].x;
-  let y0 = pts[0].y;
-  let x1 = pts[0].x;
-  let y1 = pts[0].y;
-  for (const p of pts) {
-    if (p.x < x0) x0 = p.x;
-    if (p.x > x1) x1 = p.x;
-    if (p.y < y0) y0 = p.y;
-    if (p.y > y1) y1 = p.y;
-  }
-  return { x0, y0, x1, y1 };
-}
-
-/** Screen-space rect (any two corners) -> normalized {x0,y0,x1,y1}. */
-export function normRect(ax: number, ay: number, bx: number, by: number) {
-  return {
-    x0: Math.min(ax, bx),
-    y0: Math.min(ay, by),
-    x1: Math.max(ax, bx),
-    y1: Math.max(ay, by),
-  };
-}
-
-/**
- * Bubble radius for a value under a sqrt scale (I5). AREA is proportional to
- * the value, which is the only honest way to size a circle — radius-proportional
- * bubbles overstate large values by the square, the classic bubble-chart lie.
- * `null`/non-finite gets `rNull`: a value-less row is drawn small, never hidden
- * and never faked (rule 8b).
- */
-export function bubbleRadius(
-  v: number | null,
-  min: number,
-  max: number,
-  rMin: number,
-  rMax: number,
-  rNull: number
-): number {
-  if (v == null || !Number.isFinite(v)) return rNull;
-  if (!(max > min)) return (rMin + rMax) / 2;
-  const t = Math.max(0, Math.min(1, (v - min) / (max - min)));
-  return Math.sqrt(rMin * rMin + t * (rMax * rMax - rMin * rMin));
-}
+// ---------------------------------------------------------------------------
+// customer-grid / mapProjection.ts
+// Wave-8 I2/I6 — the map's geometry, split from MapView so it can be tested
+// under node without React.
+//
+// WHY THIS EXISTS AS ITS OWN LAYER. The wave-7 map derived its projection from
+// the DATA's bounding box (MapView.tsx:96-118, an equirectangular fit). That is
+// fine for a static scatter and wrong for everything wave 8 asks of it:
+//
+//   - the map re-projected on every filter change, so the whole picture jumped
+//     whenever a condition was edited;
+//   - box-select needs a stable screen<->point mapping DURING a drag, which a
+//     projection memoised over `points` is not;
+//   - a data-fit projection distorts real geography — state outlines drawn
+//     through it visibly skew once you zoom into one metro.
+//
+// So the two concerns are separated:
+//   PROJECTION  fixed Web Mercator, world -> a fixed square. Never changes.
+//   VIEW        {k, tx, ty} — zoom and pan, an affine transform ON TOP.
+// The old data-fit becomes the INITIAL VIEW value rather than the projection,
+// which is what makes zoom/pan and hit-testing tractable at all.
+// ---------------------------------------------------------------------------
+
+/** Base resolution of the projected world square, in SVG user units. */
+export const WORLD = 4096;
+
+/** Mercator blows up at the poles; every web map clamps. */
+const MAX_LAT = 85.05112878;
+
+export interface Pt {
+  x: number;
+  y: number;
+}
+
+/** A pan/zoom transform: screen = view.t + view.k * projected. */
+export interface View {
+  k: number;
+  tx: number;
+  ty: number;
+}
+
+/** lon/lat -> the fixed projected plane (0..WORLD on both axes). */
+export function project(lon: number, lat: number): Pt {
+  const clamped = Math.max(-MAX_LAT, Math.min(MAX_LAT, lat));
+  const rad = (clamped * Math.PI) / 180;
+  const x = (lon + 180) / 360;
+  const y = 0.5 - Math.log(Math.tan(Math.PI / 4 + rad / 2)) / (2 * Math.PI);
+  return { x: x * WORLD, y: y * WORLD };
+}
+
+/** The fixed projected plane -> lon/lat. The exact inverse of `project`. */
+export function unproject(p: Pt): { lon: number; lat: number } {
+  const t = 0.5 - p.y / WORLD;
+  const rad = 2 * Math.atan(Math.exp(2 * Math.PI * t)) - Math.PI / 2;
+  return { lon: (p.x / WORLD) * 360 - 180, lat: (rad * 180) / Math.PI };
+}
+
+/** Screen -> the fixed projected plane, through a view. The inverse of `toScreen`. */
+export function fromScreen(s: Pt, view: View): Pt {
+  return { x: (s.x - view.tx) / view.k, y: (s.y - view.ty) / view.k };
+}
+
+// -------------------------------------------------------- the Google hand-off
+//
+// The honest answer to "I need to see the actual street". A licence-free offline
+// vector basemap stops at roughly metro scale (see BASEMAP_DETAIL_K), and the
+// alternative — bundling a tile renderer — costs 270 KB gz, an API key or a
+// hosted planet file, and sends every customer's coordinates to a third party on
+// every pan. A LINK costs none of that: nothing ships, nothing is fetched, and
+// the coordinates travel only if the user deliberately clicks.
+//
+// ⚠ Every one of these must be rendered with rel="noopener noreferrer" — that
+// strips the Referer, so the destination never learns which tenant or which
+// deployment the click came from, and it denies the opened tab window.opener.
+
+/**
+ * Google Maps' zoom level for our zoom `k`.
+ *
+ * Google measures a world 256 * 2^z px wide; ours is WORLD units wide, painted
+ * at `k` and then ~1.08 CSS px per unit. Equating the two:
+ *   256 * 2^z = WORLD * k * 1.08   ->   z = log2(WORLD * 1.08 * k / 256)
+ * Clamped to Google's own 0..21. A fitted US book (k~1.36) hands over z5, the
+ * country; the detail cap (k=32) hands over z9, a metro — i.e. the hand-off
+ * starts exactly where our basemap runs out, which is the point of it.
+ */
+export function googleZoomForK(k: number): number {
+  if (!Number.isFinite(k) || k <= 0) return 4;
+  const z = Math.log2((WORLD * 1.08 * k) / 256);
+  return Math.max(0, Math.min(21, Math.round(z)));
+}
+
+/** True only for a coordinate Google can actually be sent. */
+export function isPlottable(lat: number | null, lon: number | null): boolean {
+  return (
+    lat != null && lon != null &&
+    Number.isFinite(lat) && Number.isFinite(lon) &&
+    Math.abs(lat) <= 90 && Math.abs(lon) <= 180
+  );
+}
+
+/**
+ * A dropped pin at exactly the coordinate WE plotted.
+ *
+ * ⚠ Deliberately by lat/lon and never by customer name or address: a name search
+ * can resolve somewhere else entirely, and then the app's map and the link
+ * disagree about where a customer is. The pin is the geocode; the link is the
+ * same geocode. `api=1` is Google's documented, stable URL contract.
+ */
+export function googleMapsUrl(lat: number, lon: number, zoom?: number): string {
+  const at = `${lat.toFixed(6)},${lon.toFixed(6)}`;
+  return zoom == null
+    ? `https://www.google.com/maps/search/?api=1&query=${at}`
+    : `https://www.google.com/maps/@${at},${Math.round(zoom)}z`;
+}
+
+/** Directions to a customer — the version a rep on the road actually wants. */
+export function googleDirectionsUrl(lat: number, lon: number): string {
+  return `https://www.google.com/maps/dir/?api=1&destination=${lat.toFixed(6)},${lon.toFixed(6)}`;
+}
+
+/** Projected point -> screen, through a view. */
+export function toScreen(p: Pt, view: View): Pt {
+  return { x: view.tx + p.x * view.k, y: view.ty + p.y * view.k };
+}
+
+/**
+ * The view that frames `pts` inside a w x h viewport with `pad` px of margin.
+ * `minSpan` stops a single point (or one city) from zooming to street level:
+ * one customer should still look like a PLACE, not a full-bleed dot — the
+ * wave-7 behaviour, kept.
+ */
+export function fitView(
+  pts: Pt[],
+  w: number,
+  h: number,
+  pad = 40,
+  minSpan = WORLD / 90
+): View | null {
+  if (pts.length === 0) return null;
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (const p of pts) {
+    minX = Math.min(minX, p.x);
+    maxX = Math.max(maxX, p.x);
+    minY = Math.min(minY, p.y);
+    maxY = Math.max(maxY, p.y);
+  }
+  let spanX = Math.max(maxX - minX, minSpan);
+  let spanY = Math.max(maxY - minY, minSpan);
+  const cx = (minX + maxX) / 2;
+  const cy = (minY + maxY) / 2;
+  spanX *= 1.16; // breathing room so edge pins are not on the frame
+  spanY *= 1.16;
+  const k = Math.min((w - pad * 2) / spanX, (h - pad * 2) / spanY);
+  return { k, tx: w / 2 - cx * k, ty: h / 2 - cy * k };
+}
+
+/** Zoom by `factor` while holding the point under (mx, my) still — the gesture
+ *  every map has and the reason zoom cannot be a plain scale on the group. */
+export function zoomAt(view: View, factor: number, mx: number, my: number, kMin: number, kMax: number): View {
+  const k = Math.max(kMin, Math.min(kMax, view.k * factor));
+  if (k === view.k) return view;
+  return {
+    k,
+    tx: mx - ((mx - view.tx) * k) / view.k,
+    ty: my - ((my - view.ty) * k) / view.k,
+  };
+}
+
+// ---------------------------------------------------------------- stroke width
+//
+// ⚠ THE MAP HAS EXACTLY ONE STROKE-WIDTH MECHANISM, AND THIS IS IT.
+//
+// Everything painted inside `<g transform="... scale(k)">` is scaled by k, so a
+// line meant to read 1.1 px on screen must be handed 1.1/k. That is `hairline`.
+// SVG offers a SECOND way to the same end — the CSS `vector-effect:
+// non-scaling-stroke`, which makes the renderer ignore the transform when it
+// strokes. Either works. Using BOTH cancels the zoom twice, and the line then
+// gets THINNER the further you zoom IN.
+//
+// Wave 9 found exactly that, and it is the "blurry when zoomed" bug the owner
+// reported. `.cg-map-land` carried the CSS property AND `hair(1.1)`. Measured
+// against the real constants (WORLD 4096, viewBox 1000x620, ~1.10 CSS px per
+// viewBox unit, fitted k ~1.359): the coastline painted 0.89 CSS px at the
+// fitted view, 0.445 at 2x, 0.089 at 10x and 0.015 at the zoom cap — below
+// ~0.5 px a stroke is an anti-aliased smear and below ~0.2 px a ghost. The
+// graticule, the lakes and the pins were all correct, because they use
+// `hairline` alone. The bug hid precisely because two idioms coexisted on
+// different elements of the same picture.
+//
+// So the rule is singular now, and it is GATED rather than merely commented:
+// `paintedStroke` must be flat across the whole zoom range, and
+// `scalingConflicts` re-reads the real stylesheet so the CSS half cannot come
+// back either. If a future element genuinely wants `non-scaling-stroke`, that
+// is a deliberate change to this rule — change the comment and the gate, not
+// just the stylesheet.
+
+/** Stroke width to hand an element drawn INSIDE the zoomed group. */
+export function hairline(basePx: number, k: number): number {
+  return basePx / k;
+}
+
+/**
+ * A dash pattern for a line drawn INSIDE the zoomed group.
+ *
+ * ⚠ Exactly the same trap as stroke width, and it caught me: `stroke-dasharray`
+ * in CSS is in USER units, so inside `scale(k)` a "5 4" dash becomes 5k on and
+ * 4k off. At a regional fit that is a 70 px dash and a 55 px gap — the route
+ * line renders as a few disconnected strokes floating between the stops, which
+ * reads as a broken polyline rather than a scaled dash. Every length handed to
+ * the transformed group goes through `hairline`, dashes included.
+ */
+export function dashPattern(onPx: number, offPx: number, k: number): string {
+  return `${hairline(onPx, k)} ${hairline(offPx, k)}`;
+}
+
+/**
+ * What the renderer actually paints, in screen units, for a `hairline` width at
+ * zoom k — i.e. the attribute multiplied by the group's scale. Not circular: it
+ * models the SVG pipeline, which is the thing the invariant is about. It must
+ * return `basePx` at EVERY k, and the gate sweeps the range to prove it.
+ */
+export function paintedStroke(basePx: number, k: number): number {
+  return hairline(basePx, k) * k;
+}
+
+/**
+ * The CSS half of the same invariant: any `.cg-map*` rule that declares
+ * `vector-effect: non-scaling-stroke` is double-compensating against
+ * `hairline`. Returns the offending selectors (empty = clean) so the gate can
+ * name them. Comments are stripped first so a commented-out example cannot trip
+ * it.
+ */
+export function scalingConflicts(css: string): string[] {
+  const bad: string[] = [];
+  for (const chunk of css.replace(/\/\*[\s\S]*?\*\//g, "").split("}")) {
+    const brace = chunk.indexOf("{");
+    if (brace < 0) continue;
+    const selector = chunk.slice(0, brace);
+    if (!selector.includes(".cg-map")) continue;
+    if (/vector-effect\s*:[^;]*non-scaling/i.test(chunk.slice(brace + 1)))
+      bad.push(selector.trim().replace(/\s+/g, " "));
+  }
+  return bad;
+}
+
+/**
+ * How far in the VENDORED basemap is still worth showing, as an absolute zoom.
+ *
+ * DERIVED, not chosen by feel. The geometry in mapGeometry.ts is Natural Earth
+ * 50m simplified at 0.02 degrees, giving a ~13 km median vertex spacing. With
+ * the viewBox painting ~1.08 CSS px per unit at latitude 39, one screen pixel is
+ * ~7041/k metres, so a 13 km segment measures ~1.85*k pixels. At k = 32 that is
+ * a ~60 px straight run and ~10 px of simplification error — coarse but still
+ * unmistakably a shape. Past it the coastline degenerates into long straight
+ * lines and the user is zooming into an empty polygon, which is the opposite of
+ * the sharpness this was asked for.
+ *
+ * ⚠ This is an HONESTY limit and it is the reason the map stops where it does:
+ * street-level detail is not available from any licence-free offline vector set.
+ * It needs a tile provider — a runtime network dependency, an API key and an
+ * attribution obligation — which is the owner's call, not a silent addition.
+ */
+export const BASEMAP_DETAIL_K = 32;
+
+/**
+ * The camera's zoom range for a given fitted zoom.
+ *
+ * `kMin` — zoom OUT to four times the data's own extent for context, but never
+ * past the point where the whole projected world already fits: beyond that
+ * there is nothing further to reveal, only empty margin. (The wave-8 rule was a
+ * flat `fit.k * 0.6`, which locked you in at barely half a step out.)
+ *
+ * `kMax` — how far IN. This is a HONESTY limit as much as a UX one: zooming
+ * past the resolution of the basemap actually vendored just shows a bigger
+ * empty polygon, so `detailK` caps it. Pass `Infinity` for no cap.
+ */
+export function zoomLimits(
+  fitK: number,
+  viewH: number,
+  detailK = Infinity
+): { kMin: number; kMax: number } {
+  const worldFit = viewH / WORLD;
+  const kMin = Math.min(fitK, Math.max(worldFit, fitK * 0.25));
+  return { kMin, kMax: Math.max(fitK, Math.min(fitK * 60, detailK)) };
+}
+
+/**
+ * Graticule opacity at zoom k. The 10-degree grid earns its place on a
+ * zoomed-OUT world view, where it is the only thing giving scale. Once wave 9
+ * vendored real state borders it became noise the moment you zoom into the
+ * country: two competing line systems over the same picture. So it fades out
+ * before the borders take over rather than fighting them.
+ */
+export function graticuleOpacity(k: number): number {
+  return Math.max(0, Math.min(1, (1.5 - k) / 0.9));
+}
+
+/**
+ * Where to put a hover card of `w` x `h` for a pin at (sx, sy), in screen space.
+ *
+ * Prefers ABOVE the pin, flips below when there is no room, and clamps inside
+ * the viewport on both axes — a card that runs off the frame is a card whose
+ * numbers cannot be read, and the pins nearest the edge are exactly the ones a
+ * territory question is usually about.
+ */
+export function cardBox(
+  sx: number, sy: number, w: number, h: number,
+  viewW: number, viewH: number, gap = 14, pad = 6
+): Pt {
+  const above = sy - h - gap;
+  // ⚠ Both axes clamp UNCONDITIONALLY. Clamping only the "flipped below" branch
+  // looks right and is not: a pin panned off the BOTTOM of the frame still has
+  // acres of room "above" it, passes the room check, and places the card far
+  // below the viewport. Caught by the every-corner leg, never by a screenshot.
+  return {
+    x: Math.max(pad, Math.min(viewW - w - pad, sx - w / 2)),
+    y: Math.max(pad, Math.min(viewH - h - pad, above >= pad ? above : sy + gap)),
+  };
+}
+
+// ---------------------------------------------------------- route planning
+//
+// I18-R. Sequencing a visit order is a TRAVELLING SALESMAN problem, and it is
+// pure arithmetic: no data, no service, no dependency, no cost. The half that
+// costs money is turning an order into ROAD distances, and this deliberately
+// does not attempt that — see `routeNote` and the mailbox's tier analysis
+// (Google's route matrix bills per element: a 30-stop run is ~$4.50, a full
+// 1,550-customer matrix ~$12,000).
+
+/** A stop, in the coordinates the host geocoded — never projected units. */
+export interface GeoStop {
+  lat: number;
+  lon: number;
+}
+
+/**
+ * ⚠ THE SEAM. Everything below takes distance as a FUNCTION and knows nothing
+ * else about it. Swapping in real road distances later (a self-hosted OSRM
+ * matrix, precomputed and cached) is then a one-line change at the call site
+ * rather than a rewrite of the sequencer.
+ */
+export type StopDistance = (a: GeoStop, b: GeoStop) => number;
+
+const EARTH_R_KM = 6371.0088;
+
+/**
+ * Great-circle distance in km.
+ *
+ * ⚠ MUST be computed on lon/lat, NOT as euclidean distance in projected WORLD
+ * units. Mercator stretches by 1/cos(latitude): across this book's range
+ * (lat 25-49) that is a 0.91 -> 0.66 swing, ~38%, which systematically ranks
+ * north-south pairs against east-west ones. The resulting route looks entirely
+ * plausible and is wrong, which is the worst kind of wrong.
+ */
+export const haversineKm: StopDistance = (a, b) => {
+  const rad = Math.PI / 180;
+  const dLat = (b.lat - a.lat) * rad;
+  const dLon = (b.lon - a.lon) * rad;
+  const s =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(a.lat * rad) * Math.cos(b.lat * rad) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_R_KM * Math.asin(Math.min(1, Math.sqrt(s)));
+};
+
+/** Total length of a tour. `roundTrip` adds the closing edge back to the start. */
+export function tourLength(
+  order: number[], stops: GeoStop[], dist: StopDistance, roundTrip = false
+): number {
+  if (order.length < 2) return 0;
+  let km = 0;
+  for (let i = 1; i < order.length; i++) km += dist(stops[order[i - 1]], stops[order[i]]);
+  if (roundTrip) km += dist(stops[order[order.length - 1]], stops[order[0]]);
+  return km;
+}
+
+/** Greedy construction: from `start`, repeatedly hop to the nearest unvisited stop. */
+export function nearestNeighbourOrder(
+  stops: GeoStop[], dist: StopDistance, start = 0
+): number[] {
+  const n = stops.length;
+  if (n === 0) return [];
+  const from = Math.max(0, Math.min(n - 1, Math.round(start) || 0));
+  const seen = new Array<boolean>(n).fill(false);
+  const order = [from];
+  seen[from] = true;
+  for (let k = 1; k < n; k++) {
+    const last = order[order.length - 1];
+    let best = -1;
+    let bestD = Infinity;
+    for (let i = 0; i < n; i++) {
+      if (seen[i]) continue;
+      const d = dist(stops[last], stops[i]);
+      if (d < bestD) { bestD = d; best = i; }
+    }
+    if (best < 0) break;
+    seen[best] = true;
+    order.push(best);
+  }
+  return order;
+}
+
+/**
+ * 2-opt: repeatedly reverse a segment when doing so shortens the tour.
+ *
+ * Index 0 is PINNED — it is the origin the user chose, and silently re-rooting
+ * their route would be a worse bug than a slightly longer one. Only strictly
+ * improving moves are accepted, which is what makes "never returns a tour
+ * longer than the one it was given" a guarantee the gate can assert rather than
+ * a hope.
+ */
+export function twoOptOrder(
+  order: number[], stops: GeoStop[], dist: StopDistance,
+  roundTrip = false, maxPasses = 24
+): number[] {
+  const n = order.length;
+  const cur = order.slice();
+  if (n < 4) return cur;
+  const D = (a: number, b: number) => dist(stops[a], stops[b]);
+  for (let pass = 0; pass < maxPasses; pass++) {
+    let improved = false;
+    for (let i = 1; i < n - 1; i++) {
+      for (let j = i + 1; j < n; j++) {
+        const a = cur[i - 1], b = cur[i], c = cur[j];
+        let delta: number;
+        if (j === n - 1 && !roundTrip) {
+          // Reversing the tail of an OPEN path only re-hangs the entry edge:
+          // there is no closing edge to pay for.
+          delta = D(a, c) - D(a, b);
+        } else {
+          const d = cur[(j + 1) % n];
+          delta = D(a, c) + D(b, d) - D(a, b) - D(c, d);
+        }
+        if (delta < -1e-9) {
+          for (let lo = i, hi = j; lo < hi; lo++, hi--) {
+            const t = cur[lo]; cur[lo] = cur[hi]; cur[hi] = t;
+          }
+          improved = true;
+        }
+      }
+    }
+    if (!improved) break;
+  }
+  return cur;
+}
+
+/** Construct then improve. Returns the visit order and its length. */
+export function planRoute(
+  stops: GeoStop[], dist: StopDistance,
+  opts: { start?: number; roundTrip?: boolean } = {}
+): { order: number[]; km: number } {
+  const roundTrip = !!opts.roundTrip;
+  if (stops.length === 0) return { order: [], km: 0 };
+  const nn = nearestNeighbourOrder(stops, dist, opts.start ?? 0);
+  const order = twoOptOrder(nn, stops, dist, roundTrip);
+  return { order, km: tourLength(order, stops, dist, roundTrip) };
+}
+
+// --------------------------------------------------- handing the route over
+//
+// MEASURED 2026-07-29, do not re-derive: Google Maps URLs need NO API key and
+// cost NOTHING, but they carry at most 9 waypoints on desktop and 3 on mobile
+// browsers, inside a 2,048-character URL.
+
+export const ROUTE_WAYPOINTS_DESKTOP = 9;
+export const ROUTE_WAYPOINTS_MOBILE = 3;
+export const MAX_MAPS_URL = 2048;
+
+/** How many STOPS can ride the free URL: the waypoints plus the two endpoints
+ *  (a round trip returns to its origin, so the origin is not also a waypoint). */
+export function routeStopCap(coarsePointer: boolean, roundTrip = false): number {
+  const w = coarsePointer ? ROUTE_WAYPOINTS_MOBILE : ROUTE_WAYPOINTS_DESKTOP;
+  return roundTrip ? w + 1 : w + 2;
+}
+
+/**
+ * Build the free Google directions URL for an ORDERED list of stops.
+ *
+ * Returns `used` alongside the url so the caller can say "first 11 of 23" on
+ * screen. It never silently drops a stop; truncation is a fact the UI states
+ * ([[no-unverifiable-aggregates]]). Shrinks further if the character budget
+ * binds, which it can with a long tail of 6-dp coordinates.
+ */
+export function googleRouteUrl(
+  stops: GeoStop[],
+  opts: { roundTrip?: boolean; coarsePointer?: boolean } = {}
+): { url: string; used: number } | null {
+  if (stops.length < 2) return null;
+  const roundTrip = !!opts.roundTrip;
+  const at = (s: GeoStop) => `${s.lat.toFixed(6)},${s.lon.toFixed(6)}`;
+  let used = Math.min(stops.length, routeStopCap(!!opts.coarsePointer, roundTrip));
+  for (;;) {
+    const chosen = stops.slice(0, used);
+    const origin = chosen[0];
+    const dest = roundTrip ? origin : chosen[chosen.length - 1];
+    const mids = roundTrip ? chosen.slice(1) : chosen.slice(1, -1);
+    const url =
+      `https://www.google.com/maps/dir/?api=1&origin=${at(origin)}` +
+      `&destination=${at(dest)}` +
+      (mids.length ? `&waypoints=${mids.map(at).join("|")}` : "") +
+      `&travelmode=driving`;
+    if (url.length <= MAX_MAPS_URL || used <= 2) return { url, used };
+    used -= 1;
+  }
+}
+
+/** An svg's own bounding box in client px — the `getBoundingClientRect()` half
+ *  of the conversion below, taken as plain data so the maths stays testable
+ *  without a DOM. */
+export interface FrameRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Client px -> the svg's own user-space coords. Every pointer gesture on the
+ * map — marquee, rubber band, cursor-anchored wheel zoom — starts here.
+ *
+ * ⚠ It is NOT `(client / frame) * viewBox`. MapView paints with
+ * `preserveAspectRatio="xMidYMid meet"`, so the viewBox is scaled UNIFORMLY by
+ * the tighter of the two axes and then CENTRED, leaving a letterbox band on the
+ * other axis. Wave 8 (`f6f45a6`) bolted a stretch-to-fill conversion onto that
+ * `meet` svg: the binding axis came out right and the other carried BOTH a
+ * wrong scale and a missing offset. On a 1400x600 frame the full 0..1000
+ * x-range collapsed into ~154..846 — so a marquee at either edge caught
+ * NOTHING, the rubber band lagged the cursor by ~150 px, and cursor-anchored
+ * zoom drifted, all from this one function. `zoomAt` and the hit test were
+ * always correct; they were being handed the wrong point.
+ *
+ * ⛔ The result is deliberately NOT clamped to the viewBox. A drag that begins
+ * in the letterbox band is a real gesture — everything from the painted edge
+ * inward must still be caught — and clamping re-breaks exactly the edge
+ * marquee this exists to fix.
+ */
+export function clientToUser(
+  clientX: number,
+  clientY: number,
+  rect: FrameRect,
+  viewW: number,
+  viewH: number
+): Pt {
+  const s = Math.min(rect.width / viewW, rect.height / viewH);
+  if (!(s > 0) || !Number.isFinite(s)) return { x: 0, y: 0 };
+  const offX = (rect.width - viewW * s) / 2;
+  const offY = (rect.height - viewH * s) / 2;
+  return { x: (clientX - rect.left - offX) / s, y: (clientY - rect.top - offY) / s };
+}
+
+/**
+ * Is `p` inside the closed polygon `poly`? Even-odd ray casting (the crossing
+ * number), in the same user-space units `toScreen` returns.
+ *
+ * ⛔ It is NOT a bounding-box test, and that difference IS the feature. A lasso
+ * drawn as a C or a horseshoe must EXCLUDE whatever sits in its mouth —
+ * otherwise it is the rectangle marquee wearing a lasso's name, which is the
+ * one thing a person drawing a loop by hand would never expect. The gate
+ * asserts exactly that case, over a shape whose bounding box gives a different
+ * answer: a convex test polygon would make the control inert.
+ *
+ * The ray is cast along +x from `p`, and each edge that straddles `p.y` and
+ * crosses to the LEFT of nothing / RIGHT of `p.x` flips the parity. A point
+ * exactly on a vertex or an edge may fall either way: this selects pins under a
+ * hand-drawn path, where a half-pixel tie carries no meaning and an epsilon to
+ * break it would be a number nobody could justify.
+ */
+export function pointInPolygon(p: Pt, poly: Pt[]): boolean {
+  if (poly.length < 3) return false;
+  let inside = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const a = poly[i];
+    const b = poly[j];
+    const straddles = a.y > p.y !== b.y > p.y;
+    if (straddles && p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
+  }
+  return inside;
+}
+
+/**
+ * The axis-aligned bounds of a freehand path, in `normRect`'s own {x0,y0,x1,y1}
+ * shape so one mis-click rule can measure either gesture. An empty path is a
+ * zero box rather than an Infinity one — the caller's "did this move at all"
+ * test must answer NO, not NaN.
+ */
+export function pathBounds(pts: Pt[]) {
+  if (pts.length === 0) return { x0: 0, y0: 0, x1: 0, y1: 0 };
+  let x0 = pts[0].x;
+  let y0 = pts[0].y;
+  let x1 = pts[0].x;
+  let y1 = pts[0].y;
+  for (const p of pts) {
+    if (p.x < x0) x0 = p.x;
+    if (p.x > x1) x1 = p.x;
+    if (p.y < y0) y0 = p.y;
+    if (p.y > y1) y1 = p.y;
+  }
+  return { x0, y0, x1, y1 };
+}
+
+/** Screen-space rect (any two corners) -> normalized {x0,y0,x1,y1}. */
+export function normRect(ax: number, ay: number, bx: number, by: number) {
+  return {
+    x0: Math.min(ax, bx),
+    y0: Math.min(ay, by),
+    x1: Math.max(ax, bx),
+    y1: Math.max(ay, by),
+  };
+}
+
+/**
+ * Bubble radius for a value under a sqrt scale (I5). AREA is proportional to
+ * the value, which is the only honest way to size a circle — radius-proportional
+ * bubbles overstate large values by the square, the classic bubble-chart lie.
+ * `null`/non-finite gets `rNull`: a value-less row is drawn small, never hidden
+ * and never faked (rule 8b).
+ */
+export function bubbleRadius(
+  v: number | null,
+  min: number,
+  max: number,
+  rMin: number,
+  rMax: number,
+  rNull: number
+): number {
+  if (v == null || !Number.isFinite(v)) return rNull;
+  if (!(max > min)) return (rMin + rMax) / 2;
+  const t = Math.max(0, Math.min(1, (v - min) / (max - min)));
+  return Math.sqrt(rMin * rMin + t * (rMax * rMax - rMin * rMin));
+}
+
+/**
+ * W37-T34 / contract C7 — ONE cell holding BOTH numbers: `"40.712780,-74.006110"`.
+ *
+ * ⭐ IT LIVES HERE AND NOT IN MapView.tsx, AND THAT PLACEMENT IS THE POINT. `MapView.tsx`
+ * imports `./cells`, which imports glide, so nothing in it can be loaded by a node gate: a pure
+ * function stranded there is unreachable by every one of this gate's compiled-artifact
+ * mutations. That is the wave-29 scar verbatim, where a client-px conversion living in the .tsx
+ * shipped broken and green for four waves. Amendment A15 moved this file into lane D's fence
+ * precisely so this function could sit where a test can reach it.
+ *
+ * ⭐ WHY A PAIR IN ONE CELL RATHER THAN TWO COLUMNS. The map was built for the customers table,
+ * which happens to carry `lat` and `lon` as separate mirrored columns, and reading those two names
+ * directly is the whole reason a map could not be opened on anything else. The geocode field (R4)
+ * writes a coordinate as a VALUE, so it is one cell like every other cell: sortable, exportable,
+ * readable by a formula, and copyable between databases. Two columns would have made the map's
+ * schema a requirement on every table that ever wants a pin.
+ *
+ * Tolerant on the way IN and strict on the way OUT: any precision, an optional space after the
+ * comma, and a leading plus are all accepted because a person will type them, while anything off
+ * the globe is refused rather than clamped. Clamping would put a pin at a real place that the data
+ * never named, which is worse than no pin ([[no-unverifiable-aggregates]]).
+ */
+export function parseLatLon(v: unknown): { lat: number; lon: number } | null {
+  if (v == null) return null;
+  const s = String(v).trim();
+  if (!s) return null;
+  const parts = s.split(",");
+  if (parts.length !== 2) return null;
+  const lat = Number(parts[0].trim());
+  const lon = Number(parts[1].trim());
+  if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
+  if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return null;
+  return { lat, lon };
+}
+
+/** Minutes as a person says them. 95 reads as "1 h 35 m"; nobody plans a day in minutes past an
+ *  hour, and "95 min" is a number you have to do arithmetic on before it means anything. */
+export function formatDuration(minutes: number): string {
+  const m = Math.max(0, Math.round(minutes));
+  if (m < 60) return `${m} min`;
+  const h = Math.floor(m / 60);
+  const rest = m % 60;
+  return rest === 0 ? `${h} h` : `${h} h ${rest} min`;
+}

web/src/customer-grid/scriptView.css

@@ -1,479 +1,509 @@
-/* customer-grid/scriptView.css — owner item 6, the code-script View.
- *
- * ⛔ MODULE-LOCAL BY RULING, not by preference. `index.css` is a 12k-line shared file and this
- * wave's PRD hands it to ONE session; a new surface that grew it would be three lanes editing the
- * monolith at once. It is also item 13's smallest real win: the monolith stops growing.
- * ⚠ Colours come from the design tokens (navy #1F4E78 + gold #C8A24B, DESIGN.md), never from
- * fresh hexes: a surface that invents its own palette is the thing the constitution exists to
- * prevent. Only the tokens this file actually uses are named. */
-
-.cg-script {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-  min-height: 0;
-  background: var(--lp-surface, #ffffff);
-}
-
-/* The two halves the owner asked for by name: "the code AND the dashboard output of course."
-   Side by side above 900px, stacked below it, and the SPLIT is the point either way. */
-.cg-script-body {
-  display: grid;
-  grid-template-columns: minmax(280px, 5fr) minmax(320px, 7fr);
-  gap: 1px;
-  flex: 1 1 auto;
-  min-height: 0;
-  background: var(--lp-border, #e4e7ec);
-}
-@media (max-width: 900px) {
-  .cg-script-body { grid-template-columns: 1fr; grid-template-rows: minmax(180px, 2fr) 3fr; }
-}
-
-.cg-script-pane {
-  display: flex;
-  flex-direction: column;
-  min-width: 0;
-  min-height: 0;
-  background: var(--lp-surface, #ffffff);
-}
-
-.cg-script-pane-head {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 12px;
-  border-bottom: 1px solid var(--lp-border, #e4e7ec);
-  font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-.cg-script-pane-head .cg-script-spacer { flex: 1 1 auto; }
-
-/* ⚠ A textarea, not a highlighted editor. A syntax highlighter is a second parser of the same
-   source, and the two disagree the first time either learns a token; the owner asked to SEE the
-   code, which a monospaced pane does. */
-.cg-script-code {
-  flex: 1 1 auto;
-  min-height: 0;
-  width: 100%;
-  resize: none;
-  border: 0;
-  outline: none;
-  padding: 12px;
-  font: 400 var(--lp-fs-xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
-  color: var(--lp-text, #1d2939);
-  background: var(--lp-surface-sunken, #fbfcfd);
-  tab-size: 4;
-  white-space: pre;
-  overflow: auto;
-}
-.cg-script-code:focus-visible { box-shadow: inset 0 0 0 2px var(--lp-navy, #1f4e78); }
-
-.cg-script-out {
-  flex: 1 1 auto;
-  min-height: 0;
-  overflow: auto;
-  padding: 14px 16px;
-}
-
-.cg-script-run {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  height: 26px;
-  padding: 0 12px;
-  border: 0;
-  border-radius: 6px;
-  background: var(--lp-navy, #1f4e78);
-  color: #ffffff;
-  font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
-  cursor: pointer;
-}
-.cg-script-run:disabled { opacity: 0.55; cursor: default; }
-.cg-script-ghost {
-  height: 26px;
-  padding: 0 10px;
-  border: 1px solid var(--lp-border, #e4e7ec);
-  border-radius: 6px;
-  background: transparent;
-  color: var(--lp-text, #1d2939);
-  font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
-  cursor: pointer;
-}
-.cg-script-ghost:disabled { opacity: 0.5; cursor: default; }
-
-.cg-script-meta {
-  font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-
-/* A refusal is CONTENT, not a toast: the reader asked a question and this is the answer, so it
-   stays on screen next to the code that caused it. */
-.cg-script-refusal {
-  border: 1px solid var(--lp-border, #e4e7ec);
-  border-left: 3px solid var(--lp-gold, #c8a24b);
-  border-radius: 6px;
-  padding: 12px 14px;
-  background: var(--lp-surface-sunken, #fbfcfd);
-}
-.cg-script-refusal h4 {
-  margin: 0 0 6px;
-  font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-}
-.cg-script-refusal p { margin: 0 0 4px; font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif; }
-.cg-script-refusal dl {
-  margin: 8px 0 0;
-  display: grid;
-  grid-template-columns: auto 1fr;
-  gap: 2px 10px;
-  font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
-}
-.cg-script-refusal dt { color: var(--lp-text-muted, #667085); }
-.cg-script-refusal dd { margin: 0; }
-
-.cg-script-title {
-  margin: 0 0 10px;
-  font: 600 var(--lp-fs-sm)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-}
-
-.cg-script-table { width: 100%; border-collapse: collapse; }
-.cg-script-table th,
-.cg-script-table td {
-  border-bottom: 1px solid var(--lp-border, #e4e7ec);
-  padding: 6px 10px;
-  text-align: left;
-  font: 400 var(--lp-fs-xs)/1.5 Inter, system-ui, sans-serif;
-  vertical-align: top;
-}
-.cg-script-table th {
-  font-weight: 600;
-  color: var(--lp-text-muted, #667085);
-  position: sticky;
-  top: 0;
-  background: var(--lp-surface, #ffffff);
-}
-
-.cg-script-metrics {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
-  gap: 10px;
-}
-.cg-script-metric {
-  border: 1px solid var(--lp-border, #e4e7ec);
-  border-radius: 8px;
-  padding: 10px 12px;
-}
-.cg-script-metric-label {
-  font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-.cg-script-metric-value {
-  margin-top: 4px;
-  font: 600 var(--lp-fs-lg)/1.2 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-}
-.cg-script-metric-note {
-  margin-top: 2px;
-  font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-
-.cg-script-bars { display: flex; flex-direction: column; gap: 8px; }
-.cg-script-bar { display: grid; grid-template-columns: minmax(80px, 22%) 1fr auto; gap: 10px;
-  align-items: center; font: 400 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; }
-.cg-script-bar-track {
-  height: 10px;
-  border-radius: 5px;
-  background: var(--lp-surface-sunken, #f2f4f7);
-  overflow: hidden;
-}
-.cg-script-bar-fill { height: 100%; border-radius: 5px; background: var(--lp-navy, #1f4e78); }
-.cg-script-bar-value { color: var(--lp-text-muted, #667085); font-variant-numeric: tabular-nums; }
-
-.cg-script-text {
-  margin: 0;
-  font: 400 var(--lp-fs-xs)/1.7 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-  white-space: pre-wrap;
-  word-break: break-word;
-}
-
-.cg-script-stdout {
-  margin: 14px 0 0;
-  padding: 10px 12px;
-  border-radius: 6px;
-  background: var(--lp-surface-sunken, #fbfcfd);
-  border: 1px solid var(--lp-border, #e4e7ec);
-  font: 400 var(--lp-fs-3xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
-  color: var(--lp-text-muted, #667085);
-  white-space: pre-wrap;
-  word-break: break-word;
-  max-height: 220px;
-  overflow: auto;
-}
-
-.cg-script-empty {
-  font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-/* The whole-panel empty state needs its own padding: there is no `.cg-script-out` around it.
-   Kept HERE rather than inline, so the renderer's one and only computed style stays the bar
-   width, which is arithmetic on a validated number and is asserted as the only one. */
-.cg-script-empty--pad { padding: 16px; }
-
-/* ═══════════════════════════════════════════════════════════════════════════════════════════
-   W36-T05 — THE VIEW AGENT PANEL, left of the View navigation.
-
-   ⛔ `.cg-agent-panel` IS A CROSS-FENCE CLASS NAME (wiring W8, F's DONE B-3). `index.css` folds
-   the main rail on `.shell-root:has(.cg-agent-panel) .shell-side`. Renaming it here silently
-   un-folds the rail and leaves 187px of grid at 1440, with nothing going red. Its WIDTH lives
-   here because the panel is B's; the FOLD lives in index.css because the rail is F's.
-   ⚠ ~565px is the reference's own column at 1919px wide, and it is what R14's arithmetic is
-   built on: 48 (folded nav) + 565 (this) + 344 (views rail) = 957, leaving 483px of grid.
-   ═══════════════════════════════════════════════════════════════════════════════════════════ */
-.cg-agent-panel {
-  display: flex;
-  flex-direction: column;
-  flex: 0 0 565px;
-  width: 565px;
-  max-width: 46vw;
-  min-height: 0;
-  border-right: 1px solid var(--lp-border, #e4e7ec);
-  background: var(--lp-surface, #ffffff);
-}
-
-.cg-agent-head {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 10px 14px;
-  border-bottom: 1px solid var(--lp-border, #e4e7ec);
-}
-.cg-agent-title { font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; color: var(--lp-text, #1d2939); }
-.cg-agent-spacer { flex: 1 1 auto; }
-.cg-agent-icon {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 26px;
-  height: 26px;
-  border: 0;
-  border-radius: 6px;
-  background: transparent;
-  color: var(--lp-text-muted, #667085);
-  cursor: pointer;
-}
-.cg-agent-icon:hover { background: var(--lp-surface-sunken, #f2f4f7); }
-
-.cg-agent-body { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 16px; }
-
-/* The empty state: centred, one soft mark, one question. Whitespace is the design. */
-.cg-agent-empty {
-  height: 100%;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: 14px;
-}
-.cg-agent-mark {
-  width: 54px;
-  height: 54px;
-  border-radius: 50%;
-  border: 2px dotted var(--lp-gold, #c8a24b);
-  opacity: 0.55;
-}
-.cg-agent-ask {
-  margin: 0;
-  font: 500 var(--lp-fs-md)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-
-.cg-agent-listhead {
-  margin: 0 0 8px;
-  font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-.cg-agent-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column;
-  gap: 4px; }
-/* The suggestion row from the reference: icon tile, bold title, muted subtitle, an arrow right. */
-.cg-agent-row {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  width: 100%;
-  padding: 8px 10px;
-  border: 0;
-  border-radius: 8px;
-  background: transparent;
-  text-align: left;
-  cursor: pointer;
-}
-.cg-agent-row:hover { background: var(--lp-surface-sunken, #f2f4f7); }
-.cg-agent-row-tile {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 28px;
-  height: 28px;
-  flex: 0 0 28px;
-  border-radius: 7px;
-  background: var(--lp-surface-sunken, #f2f4f7);
-  color: var(--lp-navy, #1f4e78);
-}
-.cg-agent-row-text { display: flex; flex-direction: column; min-width: 0; flex: 1 1 auto; }
-.cg-agent-row-title {
-  font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-.cg-agent-row-sub {
-  font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-.cg-agent-row-go { color: var(--lp-text-muted, #667085); }
-
-.cg-agent-error {
-  margin: 12px 0 0;
-  font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-  border-left: 3px solid var(--lp-gold, #c8a24b);
-  padding-left: 10px;
-}
-
-/* ONE card border around the input AND its affordances, which is what the reference does. */
-.cg-agent-composer {
-  margin: 0 16px;
-  border: 1px solid var(--lp-border, #e4e7ec);
-  border-radius: 12px;
-  background: var(--lp-surface, #ffffff);
-}
-.cg-agent-input {
-  display: block;
-  width: 100%;
-  border: 0;
-  outline: none;
-  resize: none;
-  padding: 12px 14px 6px;
-  background: transparent;
-  font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-}
-.cg-agent-composer:focus-within { border-color: var(--lp-navy, #1f4e78); }
-.cg-agent-composer-foot {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 6px 8px 8px 12px;
-}
-.cg-agent-pill {
-  font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-  border: 1px solid var(--lp-border, #e4e7ec);
-  border-radius: 999px;
-  padding: 3px 9px;
-}
-.cg-agent-send {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 30px;
-  height: 30px;
-  border: 0;
-  border-radius: 50%;
-  background: var(--lp-navy, #1f4e78);
-  color: #ffffff;
-  cursor: pointer;
-}
-.cg-agent-send:disabled { opacity: 0.4; cursor: default; }
-
-.cg-agent-foot {
-  margin: 8px 16px 14px;
-  font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-
-/* The robot, beside the views rail's own minimize toggle (W35-T28 keeps that one FIRST). */
-.cg-agent-open {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 26px;
-  height: 26px;
-  border: 0;
-  border-radius: 6px;
-  background: transparent;
-  color: var(--lp-text-muted, #667085);
-  cursor: pointer;
-}
-.cg-agent-open:hover { background: var(--lp-surface-sunken, #f2f4f7); }
-.cg-agent-open.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
-
-/* ═══════════════════════════════════════════════════════════════════════════════════════════
-   W36-T07 — THE FIELD AGENT, inside the column menu's create pane.
-   ⚠ It reuses the `cg-agent-*` composer above rather than growing a second chat look. What is
-   added here is only what a conversation inside a 320px menu needs that a full-height panel
-   does not: a bounded scroll, a proposal card, and the two-button accept row.
-   ═══════════════════════════════════════════════════════════════════════════════════════════ */
-.cg-fagent { display: flex; flex-direction: column; gap: 10px; min-width: 0; }
-.cg-fagent-body { max-height: 320px; overflow: auto; }
-.cg-fagent-turns { list-style: none; margin: 0 0 10px; padding: 0; display: flex;
-  flex-direction: column; gap: 6px; }
-.cg-fagent-turn { display: flex; justify-content: flex-end; }
-.cg-fagent-said {
-  max-width: 88%;
-  padding: 6px 10px;
-  border-radius: 10px 10px 2px 10px;
-  background: var(--lp-surface-sunken, #f2f4f7);
-  font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-  word-break: break-word;
-}
-.cg-fagent-card {
-  border: 1px solid var(--lp-border, #e4e7ec);
-  border-left: 3px solid var(--lp-gold, #c8a24b);
-  border-radius: 8px;
-  padding: 10px 12px;
-}
-.cg-fagent-card-head {
-  margin: 0 0 6px;
-  font: 600 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
-  color: var(--lp-text, #1d2939);
-}
-.cg-fagent-def {
-  margin: 0;
-  display: grid;
-  grid-template-columns: auto 1fr;
-  gap: 2px 10px;
-  font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
-}
-.cg-fagent-def dt { color: var(--lp-text-muted, #667085); }
-.cg-fagent-def dd { margin: 0; color: var(--lp-text, #1d2939); }
-.cg-fagent-why,
-.cg-fagent-missing {
-  margin: 8px 0 0;
-  padding-left: 16px;
-  font: 400 var(--lp-fs-3xs)/1.55 Inter, system-ui, sans-serif;
-  color: var(--lp-text-muted, #667085);
-}
-/* What is still OPEN reads differently from what was decided: the reader has to answer these. */
-.cg-fagent-missing { color: var(--lp-text, #1d2939); }
-.cg-fagent-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 10px; }
-/* The agent's door in the create pane. A quiet row, not a second primary button. */
-.cg-fagent-open {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  width: 100%;
-  padding: 7px 10px;
-  border: 1px dashed var(--lp-border, #e4e7ec);
-  border-radius: 8px;
-  background: transparent;
-  color: var(--lp-text-muted, #667085);
-  font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
-  cursor: pointer;
-}
-.cg-fagent-open:hover { border-color: var(--lp-navy, #1f4e78); color: var(--lp-navy, #1f4e78); }
+/* customer-grid/scriptView.css — owner item 6, the code-script View.
+ *
+ * ⛔ MODULE-LOCAL BY RULING, not by preference. `index.css` is a 12k-line shared file and this
+ * wave's PRD hands it to ONE session; a new surface that grew it would be three lanes editing the
+ * monolith at once. It is also item 13's smallest real win: the monolith stops growing.
+ * ⚠ Colours come from the design tokens (navy #1F4E78 + gold #C8A24B, DESIGN.md), never from
+ * fresh hexes: a surface that invents its own palette is the thing the constitution exists to
+ * prevent. Only the tokens this file actually uses are named. */
+
+.cg-script {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  background: var(--lp-surface, #ffffff);
+}
+
+/* The two halves the owner asked for by name: "the code AND the dashboard output of course."
+   Side by side above 900px, stacked below it, and the SPLIT is the point either way. */
+.cg-script-body {
+  display: grid;
+  grid-template-columns: minmax(280px, 5fr) minmax(320px, 7fr);
+  gap: 1px;
+  flex: 1 1 auto;
+  min-height: 0;
+  background: var(--lp-border, #e4e7ec);
+}
+@media (max-width: 900px) {
+  .cg-script-body { grid-template-columns: 1fr; grid-template-rows: minmax(180px, 2fr) 3fr; }
+}
+
+.cg-script-pane {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  background: var(--lp-surface, #ffffff);
+}
+
+.cg-script-pane-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--lp-border, #e4e7ec);
+  font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+.cg-script-pane-head .cg-script-spacer { flex: 1 1 auto; }
+
+/* ⚠ A textarea, not a highlighted editor. A syntax highlighter is a second parser of the same
+   source, and the two disagree the first time either learns a token; the owner asked to SEE the
+   code, which a monospaced pane does. */
+.cg-script-code {
+  flex: 1 1 auto;
+  min-height: 0;
+  width: 100%;
+  resize: none;
+  border: 0;
+  outline: none;
+  padding: 12px;
+  font: 400 var(--lp-fs-xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
+  color: var(--lp-text, #1d2939);
+  background: var(--lp-surface-sunken, #fbfcfd);
+  tab-size: 4;
+  white-space: pre;
+  overflow: auto;
+}
+.cg-script-code:focus-visible { box-shadow: inset 0 0 0 2px var(--lp-navy, #1f4e78); }
+
+.cg-script-out {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+  padding: 14px 16px;
+}
+
+.cg-script-run {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 26px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: 6px;
+  background: var(--lp-navy, #1f4e78);
+  color: #ffffff;
+  font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
+  cursor: pointer;
+}
+.cg-script-run:disabled { opacity: 0.55; cursor: default; }
+.cg-script-ghost {
+  height: 26px;
+  padding: 0 10px;
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-text, #1d2939);
+  font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
+  cursor: pointer;
+}
+.cg-script-ghost:disabled { opacity: 0.5; cursor: default; }
+
+.cg-script-meta {
+  font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+
+/* A refusal is CONTENT, not a toast: the reader asked a question and this is the answer, so it
+   stays on screen next to the code that caused it. */
+.cg-script-refusal {
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-left: 3px solid var(--lp-gold, #c8a24b);
+  border-radius: 6px;
+  padding: 12px 14px;
+  background: var(--lp-surface-sunken, #fbfcfd);
+}
+.cg-script-refusal h4 {
+  margin: 0 0 6px;
+  font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+}
+.cg-script-refusal p { margin: 0 0 4px; font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif; }
+.cg-script-refusal dl {
+  margin: 8px 0 0;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 2px 10px;
+  font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
+}
+.cg-script-refusal dt { color: var(--lp-text-muted, #667085); }
+.cg-script-refusal dd { margin: 0; }
+
+.cg-script-title {
+  margin: 0 0 10px;
+  font: 600 var(--lp-fs-sm)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+}
+
+.cg-script-table { width: 100%; border-collapse: collapse; }
+.cg-script-table th,
+.cg-script-table td {
+  border-bottom: 1px solid var(--lp-border, #e4e7ec);
+  padding: 6px 10px;
+  text-align: left;
+  font: 400 var(--lp-fs-xs)/1.5 Inter, system-ui, sans-serif;
+  vertical-align: top;
+}
+.cg-script-table th {
+  font-weight: 600;
+  color: var(--lp-text-muted, #667085);
+  position: sticky;
+  top: 0;
+  background: var(--lp-surface, #ffffff);
+}
+
+.cg-script-metrics {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+  gap: 10px;
+}
+.cg-script-metric {
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 8px;
+  padding: 10px 12px;
+}
+.cg-script-metric-label {
+  font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+.cg-script-metric-value {
+  margin-top: 4px;
+  font: 600 var(--lp-fs-lg)/1.2 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+}
+.cg-script-metric-note {
+  margin-top: 2px;
+  font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+
+.cg-script-bars { display: flex; flex-direction: column; gap: 8px; }
+.cg-script-bar { display: grid; grid-template-columns: minmax(80px, 22%) 1fr auto; gap: 10px;
+  align-items: center; font: 400 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; }
+.cg-script-bar-track {
+  height: 10px;
+  border-radius: 5px;
+  background: var(--lp-surface-sunken, #f2f4f7);
+  overflow: hidden;
+}
+.cg-script-bar-fill { height: 100%; border-radius: 5px; background: var(--lp-navy, #1f4e78); }
+.cg-script-bar-value { color: var(--lp-text-muted, #667085); font-variant-numeric: tabular-nums; }
+
+.cg-script-text {
+  margin: 0;
+  font: 400 var(--lp-fs-xs)/1.7 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.cg-script-stdout {
+  margin: 14px 0 0;
+  padding: 10px 12px;
+  border-radius: 6px;
+  background: var(--lp-surface-sunken, #fbfcfd);
+  border: 1px solid var(--lp-border, #e4e7ec);
+  font: 400 var(--lp-fs-3xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
+  color: var(--lp-text-muted, #667085);
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 220px;
+  overflow: auto;
+}
+
+.cg-script-empty {
+  font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+/* The whole-panel empty state needs its own padding: there is no `.cg-script-out` around it.
+   Kept HERE rather than inline, so the renderer's one and only computed style stays the bar
+   width, which is arithmetic on a validated number and is asserted as the only one. */
+.cg-script-empty--pad { padding: 16px; }
+
+/* ═══════════════════════════════════════════════════════════════════════════════════════════
+   W36-T05 — THE VIEW AGENT PANEL, left of the View navigation.
+
+   ⛔ `.cg-agent-panel` IS A CROSS-FENCE CLASS NAME (wiring W8, F's DONE B-3). `index.css` folds
+   the main rail on `.shell-root:has(.cg-agent-panel) .shell-side`. Renaming it here silently
+   un-folds the rail and leaves 187px of grid at 1440, with nothing going red. Its WIDTH lives
+   here because the panel is B's; the FOLD lives in index.css because the rail is F's.
+   ⚠ ~565px is the reference's own column at 1919px wide, and it is what R14's arithmetic is
+   built on: 48 (folded nav) + 565 (this) + 344 (views rail) = 957, leaving 483px of grid.
+   ═══════════════════════════════════════════════════════════════════════════════════════════ */
+.cg-agent-panel {
+  display: flex;
+  flex-direction: column;
+  flex: 0 0 565px;
+  width: 565px;
+  max-width: 46vw;
+  min-height: 0;
+  border-right: 1px solid var(--lp-border, #e4e7ec);
+  background: var(--lp-surface, #ffffff);
+}
+
+.cg-agent-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--lp-border, #e4e7ec);
+}
+.cg-agent-title { font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; color: var(--lp-text, #1d2939); }
+.cg-agent-spacer { flex: 1 1 auto; }
+.cg-agent-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-text-muted, #667085);
+  cursor: pointer;
+}
+.cg-agent-icon:hover { background: var(--lp-surface-sunken, #f2f4f7); }
+
+.cg-agent-body { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 16px; }
+
+/* The empty state: centred, one soft mark, one question. Whitespace is the design. */
+.cg-agent-empty {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+}
+.cg-agent-mark {
+  width: 54px;
+  height: 54px;
+  border-radius: 50%;
+  border: 2px dotted var(--lp-gold, #c8a24b);
+  opacity: 0.55;
+}
+.cg-agent-ask {
+  margin: 0;
+  font: 500 var(--lp-fs-md)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+
+.cg-agent-listhead {
+  margin: 0 0 8px;
+  font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+.cg-agent-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column;
+  gap: 4px; }
+/* The suggestion row from the reference: icon tile, bold title, muted subtitle, an arrow right. */
+.cg-agent-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 8px 10px;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  text-align: left;
+  cursor: pointer;
+}
+.cg-agent-row:hover { background: var(--lp-surface-sunken, #f2f4f7); }
+.cg-agent-row-tile {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  flex: 0 0 28px;
+  border-radius: 7px;
+  background: var(--lp-surface-sunken, #f2f4f7);
+  color: var(--lp-navy, #1f4e78);
+}
+.cg-agent-row-text { display: flex; flex-direction: column; min-width: 0; flex: 1 1 auto; }
+.cg-agent-row-title {
+  font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.cg-agent-row-sub {
+  font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+.cg-agent-row-go { color: var(--lp-text-muted, #667085); }
+
+.cg-agent-error {
+  margin: 12px 0 0;
+  font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+  border-left: 3px solid var(--lp-gold, #c8a24b);
+  padding-left: 10px;
+}
+
+/* ONE card border around the input AND its affordances, which is what the reference does. */
+.cg-agent-composer {
+  margin: 0 16px;
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 12px;
+  background: var(--lp-surface, #ffffff);
+}
+.cg-agent-input {
+  display: block;
+  width: 100%;
+  border: 0;
+  outline: none;
+  resize: none;
+  padding: 12px 14px 6px;
+  background: transparent;
+  font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+}
+.cg-agent-composer:focus-within { border-color: var(--lp-navy, #1f4e78); }
+.cg-agent-composer-foot {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px 8px 12px;
+}
+.cg-agent-pill {
+  font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 999px;
+  padding: 3px 9px;
+}
+.cg-agent-send {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  border: 0;
+  border-radius: 50%;
+  background: var(--lp-navy, #1f4e78);
+  color: #ffffff;
+  cursor: pointer;
+}
+.cg-agent-send:disabled { opacity: 0.4; cursor: default; }
+
+.cg-agent-foot {
+  margin: 8px 16px 14px;
+  font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+
+/* The robot, beside the views rail's own minimize toggle (W35-T28 keeps that one FIRST). */
+.cg-agent-open {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-text-muted, #667085);
+  cursor: pointer;
+}
+.cg-agent-open:hover { background: var(--lp-surface-sunken, #f2f4f7); }
+.cg-agent-open.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
+
+/* ═══════════════════════════════════════════════════════════════════════════════════════════
+   W36-T07 — THE FIELD AGENT, inside the column menu's create pane.
+   ⚠ It reuses the `cg-agent-*` composer above rather than growing a second chat look. What is
+   added here is only what a conversation inside a 320px menu needs that a full-height panel
+   does not: a bounded scroll, a proposal card, and the two-button accept row.
+   ═══════════════════════════════════════════════════════════════════════════════════════════ */
+.cg-fagent { display: flex; flex-direction: column; gap: 10px; min-width: 0; }
+.cg-fagent-body { max-height: 320px; overflow: auto; }
+.cg-fagent-turns { list-style: none; margin: 0 0 10px; padding: 0; display: flex;
+  flex-direction: column; gap: 6px; }
+.cg-fagent-turn { display: flex; justify-content: flex-end; }
+.cg-fagent-said {
+  max-width: 88%;
+  padding: 6px 10px;
+  border-radius: 10px 10px 2px 10px;
+  background: var(--lp-surface-sunken, #f2f4f7);
+  font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+  word-break: break-word;
+}
+.cg-fagent-card {
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-left: 3px solid var(--lp-gold, #c8a24b);
+  border-radius: 8px;
+  padding: 10px 12px;
+}
+.cg-fagent-card-head {
+  margin: 0 0 6px;
+  font: 600 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
+  color: var(--lp-text, #1d2939);
+}
+.cg-fagent-def {
+  margin: 0;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 2px 10px;
+  font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
+}
+.cg-fagent-def dt { color: var(--lp-text-muted, #667085); }
+.cg-fagent-def dd { margin: 0; color: var(--lp-text, #1d2939); }
+.cg-fagent-why,
+.cg-fagent-missing {
+  margin: 8px 0 0;
+  padding-left: 16px;
+  font: 400 var(--lp-fs-3xs)/1.55 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+/* What is still OPEN reads differently from what was decided: the reader has to answer these. */
+.cg-fagent-missing { color: var(--lp-text, #1d2939); }
+.cg-fagent-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 10px; }
+/* The agent's door in the create pane. A quiet row, not a second primary button. */
+.cg-fagent-open {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  padding: 7px 10px;
+  border: 1px dashed var(--lp-border, #e4e7ec);
+  border-radius: 8px;
+  background: transparent;
+  color: var(--lp-text-muted, #667085);
+  font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
+  cursor: pointer;
+}
+.cg-fagent-open:hover { border-color: var(--lp-navy, #1f4e78); color: var(--lp-navy, #1f4e78); }
+
+/* ── W37-T46 / D-338: the roll-back strip ───────────────────────────────────
+   ⚠ It sits between the head row and the code, where a person looking for "what came before" is
+   already looking. A separate panel or a modal would put the history somewhere you have to go
+   rather than somewhere you are. */
+.cg-script-history {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 6px 12px;
+  border-bottom: 1px solid var(--lp-border, #e4e7ec);
+  background: var(--lp-surface-sunken, #fbfcfd);
+}
+.cg-script-history-lead,
+.cg-script-history-trimmed {
+  font: 400 var(--lp-fs-3xs)/1.3 Inter, system-ui, sans-serif;
+  color: var(--lp-text-muted, #667085);
+}
+.cg-script-history-item {
+  border: 1px solid var(--lp-border, #e4e7ec);
+  border-radius: 6px;
+  background: var(--lp-surface, #ffffff);
+  color: var(--lp-navy, #1f4e78);
+  font: 500 var(--lp-fs-3xs)/1.2 Inter, system-ui, sans-serif;
+  padding: 2px 7px;
+  cursor: pointer;
+}
+.cg-script-history-item:hover:enabled { border-color: var(--lp-navy, #1f4e78); }
+.cg-script-history-item:disabled { opacity: 0.5; cursor: default; }