Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,5 +1,5 @@
 {
- "current": "v52 (8263493)",
+ "current": "0b2ab48",
  "releases": [
   {
    "version": "v52",

VERSION

@@ -1 +1 @@
-v52 (8263493)
+0b2ab48

api/aios_session.py

@@ -1,124 +1,124 @@
-"""aios_session.py — X3: the signed, STATELESS session cookie (EXIT-3a, 2026-07-30).
-
-    aios_session = base64url(json {t,u,e,i,x}) . base64url(HMAC-SHA256)
-
-`t` tenant slug · `u` username · `e` the user's revocation epoch · `i` idle deadline ·
-`x` absolute expiry. Signed with `AIOS_SESSION_SECRET` using stdlib `hmac` — no new dependency,
-and nothing to store server-side, which is the whole point: EXIT-4 requires a process that holds
-no per-tenant state, and a session TABLE is per-tenant state. D2's Postgres sessions-MIRROR (an
-audit view, not the source of truth) arrives with C-2 and is deliberately deferred.
-
-WHY STATELESS STILL REVOKES. A cookie nobody can delete sounds like a cookie nobody can revoke.
-The answer is the `epoch` integer on the user record (`core.users.epoch` / `bump_epoch`): the
-cookie carries the epoch it was minted under, every verification re-reads the account's current
-epoch, and a password change or a deactivation bumps it — so every outstanding cookie for that
-user dies at once, without a session table.
-
-⚠ NO FALLBACK SECRET, EVER. With `AIOS_SESSION_SECRET` unset this module mints a RANDOM
-per-process key: sessions then die on restart, which is an inconvenience. A hardcoded default
-would instead let anyone who has read this repo forge a cookie for any user of any tenant — an
-inconvenience is the correct trade against a forgery key. `EPHEMERAL_SECRET` records which
-happened so the app can say so at startup and a gate can assert it.
-"""
-import base64
-import hmac
-import json
-import os
-import secrets
-import time
-from hashlib import sha256
-
-COOKIE_NAME = "aios_session"
-IDLE_SECONDS = 8 * 60 * 60           # D2: reissued on every authenticated request
-ABSOLUTE_SECONDS = 30 * 24 * 60 * 60  # D2: a hard ceiling no amount of activity extends
-
-_env_secret = os.environ.get("AIOS_SESSION_SECRET") or ""
-EPHEMERAL_SECRET = not _env_secret
-_SECRET = _env_secret.encode("utf-8") if _env_secret else secrets.token_bytes(32)
-
-
-def _b64(raw: bytes) -> str:
-    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
-
-
-def _unb64(txt: str) -> bytes:
-    return base64.urlsafe_b64decode(txt + "=" * (-len(txt) % 4))
-
-
-def _sign(payload: bytes) -> str:
-    return _b64(hmac.new(_SECRET, payload, sha256).digest())
-
-
-def mint(tenant, username, epoch, now=None, absolute_expiry=None):
-    """A fresh cookie value. `absolute_expiry` carries over on reissue so refreshing the idle
-    window can never extend the 30-day ceiling — that would make the ceiling unreachable."""
-    now = int(now if now is not None else time.time())
-    claims = {"t": str(tenant), "u": str(username), "e": int(epoch),
-              "i": now + IDLE_SECONDS,
-              "x": int(absolute_expiry if absolute_expiry is not None
-                       else now + ABSOLUTE_SECONDS)}
-    payload = json.dumps(claims, separators=(",", ":"), sort_keys=True).encode("utf-8")
-    return f"{_b64(payload)}.{_sign(payload)}", claims
-
-
-def read(value, now=None):
-    """Parse + verify a cookie value → claims dict, or None.
-
-    None for EVERY failure mode — bad shape, bad signature, expired, unparseable. The caller
-    answers 401 and must not learn which: an error that distinguishes "signature wrong" from
-    "expired" tells a forger whether their key is right.
-    """
-    if not value or not isinstance(value, str) or value.count(".") != 1:
-        return None
-    body, sig = value.split(".", 1)
-    try:
-        payload = _unb64(body)
-    except Exception:
-        return None
-    # compare_digest on the SIGNATURE, always — a byte-wise early exit is a timing oracle.
-    if not hmac.compare_digest(sig, _sign(payload)):
-        return None
-    try:
-        claims = json.loads(payload.decode("utf-8"))
-    except Exception:
-        return None
-    if not isinstance(claims, dict):
-        return None
-    if not isinstance(claims.get("u"), str) or not isinstance(claims.get("t"), str):
-        return None
-    if not claims["u"] or not claims["t"]:
-        return None
-    try:
-        idle, absolute, epoch = int(claims["i"]), int(claims["x"]), int(claims["e"])
-    except (KeyError, TypeError, ValueError):
-        return None
-    now = int(now if now is not None else time.time())
-    if now >= idle or now >= absolute:
-        return None
-    claims["e"], claims["i"], claims["x"] = epoch, idle, absolute
-    return claims
-
-
-def is_secure_request(request):
-    """Secure flag ON unless this is plain-HTTP localhost. Set unconditionally in production;
-    unset on a local http:// dev origin, where a Secure cookie is simply never sent back and
-    login would appear to succeed and then not work."""
-    host = (request.headers.get("host") or "").split(":")[0].lower()
-    proto = (request.headers.get("x-forwarded-proto")
-             or request.url.scheme or "http").split(",")[0].strip().lower()
-    if proto == "https":
-        return True
-    return host not in ("localhost", "127.0.0.1", "[::1]", "::1")
-
-
-def set_cookie(response, request, value):
-    response.set_cookie(
-        COOKIE_NAME, value, httponly=True, samesite="lax",
-        secure=is_secure_request(request), max_age=ABSOLUTE_SECONDS, path="/")
-
-
-def clear_cookie(response, request):
-    # Same attributes as when it was set: a browser matches on path/secure/samesite when
-    # deleting, and a mismatched delete silently leaves the cookie in place.
-    response.delete_cookie(COOKIE_NAME, path="/", httponly=True, samesite="lax",
-                           secure=is_secure_request(request))
+"""aios_session.py — X3: the signed, STATELESS session cookie (EXIT-3a, 2026-07-30).
+
+    aios_session = base64url(json {t,u,e,i,x}) . base64url(HMAC-SHA256)
+
+`t` tenant slug · `u` username · `e` the user's revocation epoch · `i` idle deadline ·
+`x` absolute expiry. Signed with `AIOS_SESSION_SECRET` using stdlib `hmac` — no new dependency,
+and nothing to store server-side, which is the whole point: EXIT-4 requires a process that holds
+no per-tenant state, and a session TABLE is per-tenant state. D2's Postgres sessions-MIRROR (an
+audit view, not the source of truth) arrives with C-2 and is deliberately deferred.
+
+WHY STATELESS STILL REVOKES. A cookie nobody can delete sounds like a cookie nobody can revoke.
+The answer is the `epoch` integer on the user record (`core.users.epoch` / `bump_epoch`): the
+cookie carries the epoch it was minted under, every verification re-reads the account's current
+epoch, and a password change, a deactivation, or (wave 40, R2) any LOGIN bumps it — so every outstanding cookie for that
+user dies at once, without a session table.
+
+⚠ NO FALLBACK SECRET, EVER. With `AIOS_SESSION_SECRET` unset this module mints a RANDOM
+per-process key: sessions then die on restart, which is an inconvenience. A hardcoded default
+would instead let anyone who has read this repo forge a cookie for any user of any tenant — an
+inconvenience is the correct trade against a forgery key. `EPHEMERAL_SECRET` records which
+happened so the app can say so at startup and a gate can assert it.
+"""
+import base64
+import hmac
+import json
+import os
+import secrets
+import time
+from hashlib import sha256
+
+COOKIE_NAME = "aios_session"
+IDLE_SECONDS = 8 * 60 * 60           # D2: reissued on every authenticated request
+ABSOLUTE_SECONDS = 30 * 24 * 60 * 60  # D2: a hard ceiling no amount of activity extends
+
+_env_secret = os.environ.get("AIOS_SESSION_SECRET") or ""
+EPHEMERAL_SECRET = not _env_secret
+_SECRET = _env_secret.encode("utf-8") if _env_secret else secrets.token_bytes(32)
+
+
+def _b64(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _unb64(txt: str) -> bytes:
+    return base64.urlsafe_b64decode(txt + "=" * (-len(txt) % 4))
+
+
+def _sign(payload: bytes) -> str:
+    return _b64(hmac.new(_SECRET, payload, sha256).digest())
+
+
+def mint(tenant, username, epoch, now=None, absolute_expiry=None):
+    """A fresh cookie value. `absolute_expiry` carries over on reissue so refreshing the idle
+    window can never extend the 30-day ceiling — that would make the ceiling unreachable."""
+    now = int(now if now is not None else time.time())
+    claims = {"t": str(tenant), "u": str(username), "e": int(epoch),
+              "i": now + IDLE_SECONDS,
+              "x": int(absolute_expiry if absolute_expiry is not None
+                       else now + ABSOLUTE_SECONDS)}
+    payload = json.dumps(claims, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return f"{_b64(payload)}.{_sign(payload)}", claims
+
+
+def read(value, now=None):
+    """Parse + verify a cookie value → claims dict, or None.
+
+    None for EVERY failure mode — bad shape, bad signature, expired, unparseable. The caller
+    answers 401 and must not learn which: an error that distinguishes "signature wrong" from
+    "expired" tells a forger whether their key is right.
+    """
+    if not value or not isinstance(value, str) or value.count(".") != 1:
+        return None
+    body, sig = value.split(".", 1)
+    try:
+        payload = _unb64(body)
+    except Exception:
+        return None
+    # compare_digest on the SIGNATURE, always — a byte-wise early exit is a timing oracle.
+    if not hmac.compare_digest(sig, _sign(payload)):
+        return None
+    try:
+        claims = json.loads(payload.decode("utf-8"))
+    except Exception:
+        return None
+    if not isinstance(claims, dict):
+        return None
+    if not isinstance(claims.get("u"), str) or not isinstance(claims.get("t"), str):
+        return None
+    if not claims["u"] or not claims["t"]:
+        return None
+    try:
+        idle, absolute, epoch = int(claims["i"]), int(claims["x"]), int(claims["e"])
+    except (KeyError, TypeError, ValueError):
+        return None
+    now = int(now if now is not None else time.time())
+    if now >= idle or now >= absolute:
+        return None
+    claims["e"], claims["i"], claims["x"] = epoch, idle, absolute
+    return claims
+
+
+def is_secure_request(request):
+    """Secure flag ON unless this is plain-HTTP localhost. Set unconditionally in production;
+    unset on a local http:// dev origin, where a Secure cookie is simply never sent back and
+    login would appear to succeed and then not work."""
+    host = (request.headers.get("host") or "").split(":")[0].lower()
+    proto = (request.headers.get("x-forwarded-proto")
+             or request.url.scheme or "http").split(",")[0].strip().lower()
+    if proto == "https":
+        return True
+    return host not in ("localhost", "127.0.0.1", "[::1]", "::1")
+
+
+def set_cookie(response, request, value):
+    response.set_cookie(
+        COOKIE_NAME, value, httponly=True, samesite="lax",
+        secure=is_secure_request(request), max_age=ABSOLUTE_SECONDS, path="/")
+
+
+def clear_cookie(response, request):
+    # Same attributes as when it was set: a browser matches on path/secure/samesite when
+    # deleting, and a mismatched delete silently leaves the cookie in place.
+    response.delete_cookie(COOKIE_NAME, path="/", httponly=True, samesite="lax",
+                           secure=is_secure_request(request))

api/deps.py

@@ -551,8 +551,11 @@ def _user_for(claims):
         # The emergency master is TENANT #0's break-glass, not the platform's: a synthetic
         # all-access identity minted into another tenant's session would be the exact
         # cross-tenant widening the rule above closes.
+        # ⚠ WAVE 40 (R2): the same mark `users.verify`'s master branch carries. The two dicts are
+        # documented mirrors of each other, so the key rides on both or they are not mirrors.
         return {"username": "admin", "name": "Administrator", "role": "admin",
                 "bus": "all", "modules": "all", "tenant": "royal-imports",
+                "emergency_master": True,
                 "epoch": int(claims.get("e") or 0)}
     return None
 

api/routes_admin.py

@@ -607,9 +607,7 @@ def _module_fields(key, session=None):
                       f"{key!r} is not a database in this workspace")
         src = defn.get("fields") or []
     else:
-        providers = {"customer_data": lambda: aios_grid.FIELDS,
-                     "product_data": aios_grid.product_fields}
-        provider = providers.get(key)
+        provider = _static_field_providers().get(key)
         if provider is None:
             # Reached only by a caller that skipped `_perm_modules`. Loud, because the alternative
             # (`[]`) is an empty option list read as an ANSWER — wave 26 item 24, `if ([])` is
@@ -617,7 +615,32 @@ def _module_fields(key, session=None):
             raise err(400, "ungoverned_module",
                       f"{key!r} has no permission-editor field schema. The editor governs "
                       f"{sorted(providers)} and this tenant's own databases")
-        src = provider()
+        src = list(provider())
+    import core.perm_scope as perm_scope
+    # ⭐⭐ W40-T05 / OWNER I16 — THE USER-GENERATED COLUMNS JOIN THE TOPIC'S VOCABULARY.
+    # *"Permission Filters must be able to filter on user-generated Fields too."* The two topic
+    # providers above are the STATIC contract (`aios_grid.FIELDS` = 35, `product_fields()` = 40
+    # including the built-in Image column), so until this line NO column a user created could
+    # ever reach the picker — measured, both topics, zero `custom_` keys in either. The `ut_*`
+    # arm never needed it: a user table's stored definition IS its user-generated schema.
+    #
+    # ⛔ ADDITIVE AND DEDUPED, so a declared column always wins its own key — the same rule the
+    # metric rows are appended under below. A user column shadowing a contract column would let
+    # an admin hide or filter something other than what they read off the label.
+    #
+    # ⚠ NO SESSION MEANS TODAY'S ANSWER, AND THAT IS CORRECT RATHER THAN DEGRADED. A workspace
+    # bucket is per-tenant data with no tenant-blind read, and two callers arrive without one:
+    # `_fold_legacy_scope` on the live PUT path and `verify_api`'s W30a probe. Both get the
+    # pre-set list they have always had, and the legacy fold cannot start dropping a leaf it used
+    # to keep, because `_prune_to_module` only ever narrows the LEGACY tree (`dba`/`agent`) to
+    # keys the contract already carries.
+    if key in _FIELD_PROVIDER_KEYS:
+        _have = {f.get("key") for f in src if isinstance(f, dict)}
+        for _uf in (perm_scope.user_generated_fields(
+                key, st=getattr(session, "runtime", None)) or ()):
+            if isinstance(_uf, dict) and _uf.get("key") and _uf["key"] not in _have:
+                _have.add(_uf["key"])
+                src.append(_uf)
     known = _server_side_vocabularies()
     out = []
     for f in src:
@@ -631,10 +654,145 @@ def _module_fields(key, session=None):
         out.append({"key": f["key"], "label": f.get("label") or f["key"],
                     "type": f.get("type") or "text",
                     **({"options": list(opts)} if isinstance(opts, list) and opts else {}),
-                    **({"pinned": True} if f.get("pinned") else {})})
+                    **({"pinned": True} if f.get("pinned") else {}),
+                    # ⭐⭐ CONTRACT C3 / AM-2 — THE FOUR MEMBERSHIP BOOLEANS, ON EVERY ROW.
+                    # READ OFF THE FIELD'S OWN DECLARATION, never inferred from its key, because
+                    # the declaration is the authority the GRID already uses:
+                    # `aios_grid.clean_measure_field` writes `custom: True` on a user-created
+                    # column, the product contract declares `shared: true` on its nine
+                    # tenant-wide-value columns, and `filterable: False` is how a column states
+                    # the engine cannot filter it (`est_missed` is the one that does).
+                    #
+                    # ⚠ `shared` IS INFORMATIONAL AND MUST NEVER BECOME THE HIDE RULE. AM-2's
+                    # rule is `metric || !custom`. Nine declared PRODUCT columns carry
+                    # `shared: true` (`first_cost`, `supplier`, `notes`, ...) and every one of
+                    # them has to stay hideable — `verify_api`'s legacy-fold leg hides
+                    # `first_cost` by name. A client that excluded rows on `shared` would revoke
+                    # the admin's control over nine pre-set columns, which is I15's own defect
+                    # one word over.
+                    "custom": bool(f.get("custom")),
+                    "shared": (bool(f.get("shared"))
+                               or f.get(perm_scope.FIELD_GRANT_MARK) is True),
+                    "filterable": f.get("filterable") is not False,
+                    "metric": False})
+    # ⭐⭐ I13 — THE METRIC ROWS, APPENDED LAST so no declared column is ever displaced, and
+    # skipped on a key collision so a declared column always wins its own key.
+    taken = {f["key"] for f in out}
+    out.extend(m for m in _metric_fields(key) if m["key"] not in taken)
+    return out
+
+
+def _metric_fields(key):
+    """One `measure_`-namespaced pseudo-field per measure BOUND to `key`'s entity topic.
+
+    ⭐⭐ I13 — THE ROW THE OWNER ASKED FOR: *"Fold 'Metrics fields (lookback measures over
+    this database)' into the 'Hide fields' checkboxes, one row per metric, named
+    'Metric - Revenue', 'Metric - Order' and so on, so a user can check the ones the
+    permissioning is limited to."* Until this existed the entire capability was ONE boolean
+    (`perm_scope.may_metrics`), so an administrator could revoke every metric on a database or
+    none of them.
+
+    ⭐⭐ AND IT IS WHY I15 HAD NO CONTROL TO OFFER. *"Shantal has access to gross profit."*
+    "Gross profit" is the measure `margin` — label "Gross margin $", defined at
+    `platform/model/metrics/sales.yml::margin` and bound onto this grid by
+    `platform/model/topics/odoo_products.yml::measures`. **It is not a column in
+    `aios_grid_fields.json` and never was**, so a picker built from the declared contract alone
+    could not list it however carefully that contract was read. No key literally named
+    `gross_profit` reaches this grid at all.
+
+    ⛔ THE OFFER IS READ, NEVER RESTATED. `semantic.entity_measures` is the ONE catalogue, and
+    it REFUSES a key it cannot prove — a half-synced mirror, a metric with no `empty:` family,
+    a format with no grid type — with the cause available through `entity_measure_refusals`.
+    Re-measured 2026-08-24 in this tree, after W40-T10 bound the channel split: the product topic
+    declares **27 key-slots across five bindings** and the catalogue offers **24**;
+    `stock_in`/`stock_out`/`stock_net` are refused because `stock_move` has not finished syncing.
+    Hardcoding a declared list would offer three columns that render blank today AND would stop
+    growing the day a binding is added. The offer widens on its own when the mirror catches up,
+    because this asks rather than remembers — and the eighteen channel rows below
+    ("Metric - Revenue (Fisch)", "Metric - Revenue (Amazon)", …) arrived here with NO change to
+    this function for exactly that reason.
+
+    ⭐⭐ W40-T10 / owner item 26 (R7) — AND THAT IS WHY THE CHANNEL RIDES THE MEASURE KEY. A
+    per-metric channel spelled as a member of the stored field spec would be invisible here:
+    this row is minted from `m["key"]` and `m["label"]`, so a channel carried anywhere else
+    would give an admin eighteen columns they can neither tell apart nor hide separately.
+    `semantic._one_binding_offer` therefore namespaces the key and appends "(Fisch)" to the
+    label, and both halves land in this vocabulary for free.
+
+    ⛔ THE TOPIC IS DERIVED, NEVER MAPPED. `semantic.topic_for_grid` reads the `grid:` key the
+    topic file already declares, which is the reason its own docstring gives for existing: a
+    `{module: topic}` literal in a route would be a second statement of one fact and would
+    drift the day a topic is renamed. It answers for every arm — `product_data` ->
+    `odoo_products`, `customer_data` -> `odoo_customers` (which binds none), `ut_odoo_agents` ->
+    `odoo_agents` (which binds seven) — so this needs NO per-module branch, and a database
+    with no bound measure simply receives no rows.
+
+    ⛔⛔ IT CANNOT RAISE, AND THAT IS LOAD-BEARING RATHER THAN DEFENSIVE. Two callers reach
+    `_module_fields` with NO session and outside any store fixture: `_fold_legacy_scope`, on the
+    live migration path of a PUT, and `verify_api`'s W30a probe, which runs ABOVE the line that
+    installs the fake store. A raise on either is not a red gate but a CRASHED one
+    [[gate-must-go-red-not-crash]], and on the route it is a 500 on the administrator's own save.
+    `entity_measures` already degrades to `[]` when the mirror cannot be read; this makes the
+    whole derivation degrade with it, so the payload simply carries no metric rows.
+
+    ⛔ `filterable: False`, AND IT IS A MEASUREMENT RATHER THAN A PREFERENCE. A pseudo-key is
+    not a column any row carries — a real Metric column is keyed `measure_<slug>_<rand>` by
+    `CustomerGrid.createField`. Measured: `clean_filter_tree` ACCEPTS a leaf on `measure_margin`
+    once the key is admitted, and `harness.filter_eval.permits` then answers **False for every
+    product row**, because the row has no such key. That is exactly the "deny-everything trap
+    wearing a saved-successfully toast" `_module_fields`' own docstring forbids. The governed way
+    to filter on a measure is the measure CONDITION channel (`measure_sets`, CG-8), not a field
+    leaf, so these rows join the HIDE vocabulary only.
+
+    ⛔ THE PREFIX IS `aios_grid.MEASURE_FIELD_PREFIX`, IMPORTED. Spelling "measure_" here would
+    be a second copy of a constant two features already share
+    [[constant-two-features-share]], and `verify_fields_contract` gates that the client keys its
+    real measure columns off the same one.
+    """
+    try:
+        import aios_grid
+        import harness.semantic as semantic
+        topic = semantic.topic_for_grid(key)
+        if not topic:
+            return []
+        offer = semantic.entity_measures(topic)
+    except Exception:                                        # noqa: BLE001
+        return []
+    out = []
+    for m in offer or ():
+        if not isinstance(m, dict):
+            continue
+        mkey = str(m.get("key") or "").strip()
+        if not mkey:
+            continue
+        # ⭐ THE LABEL IS THE MEASURE'S OWN, prefixed. A hand-written second vocabulary here
+        # would read "Metric - Gross profit" while the grid column read "Gross margin $", and an
+        # admin cannot hide what they cannot recognise. ASCII hyphen, exactly as the owner wrote
+        # it — CLAUDE.md rule 2 bars a dash in copy that reaches a screen.
+        label = str(m.get("label") or mkey).strip()
+        mtype = m.get("type")
+        out.append({"key": f"{aios_grid.MEASURE_FIELD_PREFIX}{mkey}",
+                    "label": f"Metric - {label}",
+                    "type": mtype if mtype in aios_grid.MEASURE_FIELD_TYPES else "currency",
+                    "custom": False,
+                    "shared": False,
+                    "filterable": False,
+                    "metric": True})
     return out
 
 
+#: The value every blank Odoo connector attribute displays as. The writer is
+#: `modules/customers._partner_attrs` (`... or '(none)'`) and the client mirror is
+#: `customer-grid/types.ts::CONNECTOR_BLANK`. It is a DELIBERATE, documented, visible value, so a
+#: choice vocabulary that omitted it would deny an admin any rule about the blank rows.
+BLANK = "(none)"
+
+#: `_server_side_vocabularies`' per-process memo. `None` until a COMPLETE build succeeds; a build
+#: with any failed arm is returned but NOT stored, so a transient Odoo outage cannot pin a short
+#: answer for the life of the worker.
+_VOCAB_CACHE = None
+
+
 def _server_side_vocabularies():
     """`{field key: [choice, …]}` for choice columns whose vocabulary is CLOSED and known here,
     but which the grid contract does not declare.
@@ -654,23 +812,318 @@ def _server_side_vocabularies():
     for the same reason `aios_grid`'s is: this route should not pull the analytics stack at
     module load.
 
-    ⚠ TWO COLUMNS ARE DELIBERATELY ABSENT, and R6's second sentence says to name them rather than
-    let them look handled:
-      · `category` (product) — an OPEN vocabulary read off Odoo's product categories. There is no
-        closed list to declare, and discovering it would mean a pool read on an admin route.
-      · `odoo_status` (customer) — WAS bare for the same reason and is NOT any more: lane E
-        answered `ASK D-15` by declaring `options: ['Active','Archived']` on the CONTRACT, which
-        is the right home (the grid picks a declared list up for free) and is why this function
-        never needed an arm for it. Recorded because the ask, not a guess, is what settled it.
+    ⭐⭐ W40-T06 / OWNER I11+I23 — NINE MORE CHOICE COLUMNS, AND WHY THE OLD REFUSAL EXPIRED.
+    Ruling R5 retyped ten Odoo customer columns off `text`, so nine of them now reach the branch
+    above and D-236 (`category` renders an EMPTY dropdown here) would have been multiplied by
+    nine rather than fixed. `category` was refused in this docstring because "discovering it
+    would mean a pool read on an admin route". That reason was WRONG about the cost, not about
+    the principle: none of the reads below is a pool read. Each is either a `read_group` over
+    `res.partner` (one grouped row per distinct value) or a whole small master table, and the
+    dearest of them was MEASURED at 1.8s cold, once per process.
+
+    ⛔⛔ A VOCABULARY MUST MATCH THE CELL, NOT THE RAW SOURCE, and the pricelist is the proof.
+    `modules/customers._partner_attrs` writes `O.m2o_name(property_product_pricelist)`, which is
+    Odoo's DISPLAY name: the cell reads "Fisch (USD)". `product.pricelist.name` reads "Fisch".
+    A vocabulary built from `name` would therefore offer five options, and every one of them
+    would match ZERO rows. So every arm below reproduces the writer's own expression:
+    `display_name` for an m2o, `.strip().title()` for `city`, the `', '.join(...)` for the m2m
+    `agent`, and `'(none)'` wherever `_partner_attrs` collapses a blank (the set of fields that
+    do is documented in the contract JSON's own `_comment`).
+    MEASURED against real cells over all 5,282 partners, 2026-08-23: country 20 offered / 20
+    observed, state 64 / 64, agent 14 / 13, city 1,254 / 1,245, pricelist 5 / 4,
+    payment_terms 15 / 10, tags 6 / 5. ⚠ Read the direction: NOT ONE observed cell value is
+    missing from what is offered. The overshoot is partners outside the grid's own 24 month
+    population, and it is the SAFE direction. A missing option is the dangerous one, because it
+    silently denies the admin any rule about those rows.
+
+    ⚠ `tags` IS A MULTISELECT, so it is offered as MEMBERS, not as joined cells.
+    `choiceVocabulary` splits a multiselect cell on commas, so "Fisch, Royal" must arrive as
+    "Fisch" and "Royal". `agent` stays a SINGLE select per R5 and therefore keeps its joined
+    combinations. ⛔ NOTE FOR THE OWNER, not acted on here: `agent` is comma joined multi value
+    exactly as `tags` is (13 observed cells are combinations such as "Avi Ash, Martin
+    Pasternak"), so R5's own argument for making Tags a multiselect applies to it too. R5 rules
+    single select, so single select is what this builds.
+
+    ⛔ DEGRADE BY OMITTING THE KEY, NEVER BY RETURNING `[]`. `FilterBuilderPanel::choicesFor`
+    treats a supplied list as authoritative INCLUDING when it is empty, so an empty list asserts
+    "this column has no values". Every arm is therefore isolated in its own try/except and a
+    failed read leaves its key OUT, exactly as the original single-arm version did.
+
+    ⚠ CACHED PER PROCESS, because `_module_fields` runs on every admin GET and on every PUT via
+    `_fold_legacy_scope`. Only SUCCESSES are cached, so a transient Odoo outage cannot pin an
+    empty answer for the life of the worker. STALE WHEN: someone adds or renames a pricelist,
+    payment term, partner tag or product category; a customer moves city, state or country; an
+    agent is assigned or unassigned; a new salesperson takes their first order. None of those is
+    observable from here, and the refresh is a process restart, which a deploy already does.
+
+    ⚠ ONE COLUMN IS STILL DELIBERATELY ABSENT, and R6's second sentence says to name it rather
+    than let it look handled:
+      · `odoo_status` (customer) — WAS bare and is NOT any more: lane E answered `ASK D-15` by
+        declaring `options: ['Active','Archived']` on the CONTRACT, which is the right home (the
+        grid picks a declared list up for free) and is why this function never needed an arm for
+        it. Recorded because the ask, not a guess, is what settled it.
     """
-    try:
+    global _VOCAB_CACHE
+    if _VOCAB_CACHE is not None:
+        return dict(_VOCAB_CACHE)
+
+    out = {}
+
+    def arm(fn):
+        """Run one source. A failure omits its keys and never touches the others."""
+        try:
+            for key, values in (fn() or {}).items():
+                clean = sorted({str(v) for v in values if str(v or "").strip()})
+                if clean:
+                    out[key] = clean
+            return True
+        except Exception:                                                     # noqa: BLE001
+            return False
+
+    def _stock_bucket():
+        # IMPORTED, NEVER RESTATED: the same constant `_bucket()` mints from, so a renamed band
+        # cannot leave a second vocabulary behind [[constant-two-features-share]]. Lazy for the
+        # same reason `aios_grid`'s import is: no analytics stack at module load.
         import modules.inventory as inventory
-        labels = list(inventory.COVERAGE_LABELS or ())
-    except Exception:
-        # A missing analytics import must not take the permission editor down; the dropdown
-        # degrades to today's empty one rather than the page to a 500.
-        return {}
-    return {"stock_bucket": labels} if labels else {}
+        return {"stock_bucket": list(inventory.COVERAGE_LABELS or ())}
+
+    def _categories():
+        import modules.inventory as inventory
+        # W40-T06: the root maps to None now, so "All" cannot reach either list. The sentinel is
+        # what `products.catalogue` and `sales._product_cat` substitute for that None.
+        cats = sorted({v for v in inventory._cat_main_map().values() if v})
+        return {"category": cats + ["(uncategorized)"],
+                "top_category": cats + ["(uncategorized)", BLANK]}
+
+    def _suppliers():
+        """The product `supplier` column's observed values.
+
+        ⛔⛔ THIS ARM EXISTS BECAUSE W40-T06 CREATED THE HOLE IT FILLS. `supplier` was `text`
+        until I18 made it a multiselect, and a choice column with no declared options and no
+        entry here is precisely D-236's empty dropdown. The flip would otherwise have ADDED a
+        tenth blank picker while this ticket was removing nine.
+
+        ⛔⛔ DECISION OWED, AND IT IS VISIBLE ON SCREEN: 18 of the 88 distinct suppliers carry a
+        COMMA INSIDE THE COMPANY NAME ("CANDLE ARTISANS, INC", "BAOBEI INT'L CO.,LTD"), spanning
+        371 product codes. A multiselect cell is by contract a comma-joined SET, and
+        `types.ts::choiceVocabulary` SPLITS it, so the grid's own row-derived picker will offer
+        26 fragments ("CANDLE ARTISANS", "INC") where 18 real suppliers should be. That is a
+        data fact about supplier names, not a bug in the splitter: unlike `tags`, `supplier` is
+        a SINGLE value that merely contains punctuation. This function serves the WHOLE values,
+        which is what the cells actually hold and what an admin means to filter on. The kind
+        itself is the owner's to settle (`select` would make the collision disappear); I18 says
+        multi-select, so multi-select is what the contract carries.
+
+        ⚠ SEED VALUES, NOT LIVE CELLS. `supplier` is an OVERLAY column a user may retype per
+        record, and those edits live in the tenant's workspace, which this route cannot read
+        tenant-blind. So a supplier somebody typed by hand is missing from this list until the
+        mastersheet carries it. Cheap and safe: `supplier_master()` is a local file cached per
+        process, and it degrades to `{}` rather than raising.
+        """
+        import modules.product_data as product_data
+        return {"supplier": [(v.get("supplier") or "").strip()
+                             for v in (product_data.supplier_master() or {}).values()]}
+
+    def _masters():
+        import core.odoo as O
+        got = {}
+        for key, model in (("pricelist", "product.pricelist"),
+                           ("payment_terms", "account.payment.term"),
+                           ("tags", "res.partner.category")):
+            # display_name, never name: see the pricelist proof in the docstring.
+            got[key] = [c["display_name"] for c in O.search_read(model, [], ["display_name"])]
+            if key != "pricelist":       # measured: every customer carries a pricelist
+                got[key] = got[key] + [BLANK]
+        return got
+
+    def _partner_dims():
+        import core.odoo as O
+        rg = lambda field: O.read_group("res.partner", [], ["id"], [field], lazy=False)
+        return {
+            "country": [O.m2o_name(r.get("country_id")) or BLANK for r in rg("country_id")],
+            "state": [O.m2o_name(r.get("state_id")) or BLANK for r in rg("state_id")],
+            # `.strip().title()` is `_partner_attrs`' own expression. Raw mirror values would
+            # offer "NEW YORK" where the cell says "New York": no match, in both directions.
+            "city": [(r.get("city") or "").strip().title() or BLANK for r in rg("city")],
+        }
+
+    def _agents():
+        import core.odoo as O
+        rows = O.search_read("res.partner", [], ["agent_ids"])
+        ids = {i for r in rows for i in (r.get("agent_ids") or [])}
+        names = {p["id"]: p["name"]
+                 for p in O.search_read("res.partner", [("id", "in", list(ids))], ["name"])}
+        return {"agent": [", ".join(n for n in (names.get(i) for i in (r.get("agent_ids") or []))
+                                    if n) or BLANK for r in rows]}
+
+    def _salespeople():
+        # The ORDER TAKER over LTM (`sale.order.user_id`), which is what the column holds, NOT
+        # `res.users`: `modules/customer_data._salesperson_attrs` is the writer, and it reads the
+        # order's taker. Grouped, so the result is one row per distinct person.
+        import core.odoo as O
+        import core.periods as P
+        import modules.sales as S
+        mf, mt = P.ltm(P.today())
+        rows = O.read_group("sale.order", S.order_domain(str(mf), str(mt), None),
+                            ["amount_untaxed:sum"], ["user_id"], lazy=False)
+        return {"salesperson": [O.m2o_name(r.get("user_id")) or BLANK for r in rows]}
+
+    complete = all([arm(source) for source in
+                    (_stock_bucket, _categories, _suppliers, _masters, _partner_dims,
+                     _agents, _salespeople)])
+    if complete:
+        _VOCAB_CACHE = dict(out)
+    return out
+
+
+def _prunable_vocabulary(key, session=None, fields=None):
+    """The field keys `key` HAS right now — or `None` when that is not trustworthy enough to
+    prune a stored permission filter against.
+
+    ⛔⛔ THE RETURN IS A SAFETY DEVICE, NOT A CONVENIENCE. The cascade below DELETES a filter leaf
+    naming a key that is not in this set, so a set that is short by one column revokes a live
+    permission rule — permanently, silently, and in the WIDENING direction. Three separate ways
+    to be short are refused here rather than papered over:
+
+      * a TOPIC whose workspace bucket could not be read (`user_generated_fields` answers `None`,
+        which is exactly why it distinguishes that from `[]`). This is the case that would fire
+        under ordinary store contention, and it is the dangerous one: measured in this tree, a
+        busy DuckDB already takes `_module_fields('product_data')` from 45 rows to 39.
+      * a SURFACE (Assistant, Agents), whose vocabulary is `[]` by design. Pruning against an
+        empty set would drop every leaf of anything stored there.
+      * any key whose schema read RAISES — an unknown module, a `ut_*` database whose definition
+        the store cannot serve.
+
+    ⚠ `fields` is threaded so the ONE `_module_fields` call a caller has already paid for is
+    reused. Recomputing it would double a read that costs a store round-trip per module on a
+    route that already makes one per governed database.
+    """
+    import core.perm_scope as perm_scope
+
+    key = str(key or "")
+    if key in _FIELD_PROVIDER_KEYS:
+        if perm_scope.user_generated_fields(key, st=getattr(session, "runtime", None)) is None:
+            return None
+    elif not key.startswith("ut_"):
+        return None
+    if fields is None:
+        try:
+            fields = _module_fields(key, session=session)
+        except Exception:                                    # noqa: BLE001
+            return None
+    return {f["key"] for f in fields if isinstance(f, dict) and f.get("key")} or None
+
+
+def _prune_stale_filters(block, session=None):
+    """`(block, {module: [dropped keys]})` — owner I16's cascade over a whole stored perms block.
+
+    ⭐⭐ *"If the field is deleted, its permission filter goes with it."* Run at the ADMIN DOOR,
+    on the record, never in the wall: `perm_scope.prune_filter_to_fields`' own docstring carries
+    the reason (`verify_perm_scope`'s "a wall naming a DELETED column denies every row" leg must
+    stay green, and it asserts on `apply_row_scope` directly).
+
+    ⚠ NON-DESTRUCTIVE and entry-wise: an entry with no filter, an entry whose vocabulary will not
+    resolve, and an entry with nothing stale all come back as the object that went in. Only an
+    entry that actually lost a leaf is rebuilt, so a caller can use the returned map as its
+    "is a write needed" test rather than comparing documents.
+    """
+    import core.perm_scope as perm_scope
+
+    out, dropped = dict(block or {}), {}
+    for key, entry in (block or {}).items():
+        if not isinstance(entry, dict) or not entry.get("filter"):
+            continue
+        vocab = _prunable_vocabulary(key, session=session)
+        if vocab is None:
+            continue
+        tree, gone = perm_scope.prune_filter_to_fields(entry["filter"], vocab)
+        if gone:
+            out[key] = dict(entry, filter=tree)
+            dropped[key] = gone
+    return out, dropped
+
+
+def _static_field_providers():
+    """The STATIC contract behind each topic grid, read by TWO callers.
+
+    `_module_fields` builds the picker from it and then APPENDS the user-generated columns;
+    `_row_wall_blind_keys` needs the same set to tell those two apart. A second copy of this map
+    would let them disagree about which columns are the database's own, and the disagreement
+    would show up as a permission filter refused on a column that was never user-generated.
+    """
+    import aios_grid
+
+    return {"customer_data": lambda: aios_grid.FIELDS,
+            "product_data": aios_grid.product_fields}
+
+
+def _leaf_col_ids(nodes):
+    """Every `colId` a filter tree names, at any depth. Groups carry `children`; leaves do not."""
+    found = set()
+    for node in nodes or ():
+        if not isinstance(node, dict):
+            continue
+        if isinstance(node.get("children"), list):
+            found |= _leaf_col_ids(node["children"])
+        elif node.get("colId"):
+            found.add(str(node["colId"]))
+    return found
+
+
+def _row_wall_blind_keys(key, session=None):
+    """User-generated columns of a TOPIC grid, which the row wall structurally cannot answer.
+
+    THE DEFECT THIS REFUSES. W40-T05 taught `_module_fields` to append
+    `perm_scope.user_generated_fields`, so the permission editor now OFFERS a column a user made
+    (owner instruction 16), and this validator accepted a wall naming it. But on the two topic
+    grids the wall runs at `routes_customers.py:277` / `:495` and `routes_products.py:118` as
+    `apply_row_scope(rows, user, MODULE, <the STATIC contract>)`, over PRE-OVERLAY rows: the
+    column is neither declared in that field list nor present on the row, and
+    `filter_eval.permits` DENIES every leaf it cannot answer.
+
+    Measured on the integrated head, one leaf {colId: fld_region, op: eq, value: West}, two rows:
+
+        static contract + pre-overlay rows (THE LIVE CALL SITE) -> []     every row denied
+        column declared + rows carrying the value               -> ['1']  correct
+        column declared + pre-overlay rows                      -> []
+        a DECLARED odoo column, same shape                      -> ['1']  the evaluator is fine
+
+    So an administrator saves a rule, is told it saved, and that account opens an empty grid with
+    nothing on screen saying why. Fail-CLOSED, and one click undoes it, but silent.
+
+    REFUSED AT THE WRITE, WHERE A PERSON IS PRESENT TO FIX IT, which is the same call
+    `_refuse_unshapeable_bu` makes further down this file for the same reason. The alternative was
+    to move the wall after the overlay merge, and that is not a small change: `apply_row_scope`
+    runs before `pids` is taken precisely so a row this account may not see never enters the
+    workspace, the cohorts or the measures. Reshaping that at QA time to fix a silent-deny would
+    trade a visible defect for an invisible one.
+
+    NARROW BY CONSTRUCTION, three ways. Only the two TOPIC grids: a `ut_*` database enforces
+    correctly today, because its stored definition IS its user-generated schema and its rows carry
+    the values. Only the FILTER: `hiddenFields` still accepts these columns, because hiding is
+    applied to the assembled field list, which does have them. And only columns the static
+    contract does NOT declare, so a user column shadowing a real one cannot make the real one
+    unfilterable.
+
+    `user_generated_fields` answers `None` when the vocabulary cannot be read, and `None` is
+    handled by NOT narrowing, which is correct rather than lax: on that same answer
+    `_module_fields` appended nothing, so there is nothing in `filter_keys` to take out.
+
+    THE PROPER FIX IS BOOKED, NOT DONE: teach the three doors to wall AFTER the overlay merge with
+    a field list that declares the column. Until then instruction 16 is delivered for `ut_*`
+    databases and REPORTED as unavailable on the two Odoo topics, which is what CLAUDE.md rule 1
+    demands of a limit that cannot yet be removed.
+    """
+    if key not in _FIELD_PROVIDER_KEYS:
+        return set()
+    import core.perm_scope as perm_scope
+
+    provider = _static_field_providers().get(key)
+    declared = {f.get("key") for f in (provider() if provider else ())
+                if isinstance(f, dict)}
+    found = perm_scope.user_generated_fields(key, st=getattr(session, "runtime", None))
+    return {f["key"] for f in (found or ())
+            if isinstance(f, dict) and f.get("key") and f["key"] not in declared}
 
 
 def _clean_perms(v, governed_keys=None, session=None):
@@ -724,11 +1177,59 @@ def _clean_perms(v, governed_keys=None, session=None):
     for key, raw in v.items():
         if not isinstance(raw, dict):
             raise err(400, "bad_perms", f"{key}: each entry must be an object")
-        valid_keys = {f["key"] for f in _module_fields(key, session=session)}
+        # ⭐⭐ AM-2 — ONE SOURCE, TWO VOCABULARIES, AND THE VALIDATOR READS BOTH. The
+        # picker and this validator still call the SAME function, which is the property
+        # `_module_fields`' docstring exists to protect; what changed is that a field now states
+        # which vocabulary it belongs to, and each consumer reads its own membership instead of
+        # the whole list.
+        #
+        # ⛔ THE SPLIT IS WHY THE METRIC ROWS ARE SAFE TO ADD. `hiddenFields` is validated
+        # against EVERY key (a metric row is hideable — that is I13's whole point), while the
+        # permanent FILTER is validated against `filterable` only. Without the second set,
+        # admitting `measure_margin` would make {"colId": "measure_margin", ...} a storable
+        # permanent wall, and `permits()` answers False for every row that has no such key:
+        # measured, not feared. `clean_filter_tree` takes bare strings and cannot see the flag,
+        # so the narrowing has to happen HERE, at the call.
+        fields_here = _module_fields(key, session=session)
+        valid_keys = {f["key"] for f in fields_here}
+        filter_keys = {f["key"] for f in fields_here if f.get("filterable")}
+        # W40-T05 x W40-T18, see `_row_wall_blind_keys`. A user-generated column of a TOPIC grid
+        # is HIDEABLE (it stays in `valid_keys`) and NOT FILTERABLE, because the row wall on those
+        # two doors runs over pre-overlay rows and denies every leaf it cannot answer.
+        row_wall_blind = _row_wall_blind_keys(key, session)
+        filter_keys -= row_wall_blind
         hidden = raw.get("hiddenFields") or []
         if not isinstance(hidden, list):
             raise err(400, "bad_perms", f"{key}: hiddenFields must be a list")
-        bad = sorted({str(h) for h in hidden} - valid_keys)
+        submitted = {str(h) for h in hidden}
+        # ⛔⛔ A METRIC TICK IS ADMITTED ON ITS PREFIX, NOT ON THE LIVE OFFER, AND THAT CLOSES A
+        # GET/PUT SKEW RATHER THAN WEAKENING THE GUARD.
+        #
+        # `_metric_fields` asks `semantic.entity_measures`, which REFUSES every key while the
+        # mirror cannot be read — measured twice in this tree on 2026-08-23, when another
+        # process held the DuckDB and the offer came back empty. That answer is deliberately not
+        # cached (`_ENTITY_OFFER_CACHE` skips an indeterminate one), so the state recurs freely.
+        # Without this line the sequence is: the editor GETs a payload carrying
+        # `measure_margin`, the admin ticks "Metric - Gross margin $", the PUT lands a moment
+        # later while the store is busy, `valid_keys` has 39 entries instead of 45, and the
+        # administrator is told their own tick *"names unknown fields"*. That is this function's
+        # ONE SOURCE invariant running backwards — the validator rejecting exactly what the
+        # picker offered.
+        #
+        # ⭐ AND ADMITTING IT IS CORRECT, not merely convenient, because the ENFORCEMENT keys off
+        # the measure NAME and not off the offer: `perm_scope._measure_bound_keys` hides every
+        # column whose `measure.key` matches, whether or not the catalogue is answering right now.
+        # So a tick stored during a warm-up walls the right columns the moment they render. A
+        # metric key that never comes back hides nothing, which is the harmless direction; the
+        # refusal is the harmful one.
+        #
+        # ⚠ NARROW BY CONSTRUCTION: only the `measure_` namespace is admitted this way, and only
+        # with a non-empty suffix. Every other unknown key is still refused, because a
+        # `hiddenFields` entry naming nothing reads as a restriction that is not there.
+        _mpre = aios_grid.MEASURE_FIELD_PREFIX
+        metric_ticks = {h for h in submitted
+                        if h.startswith(_mpre) and len(h) > len(_mpre)}
+        bad = sorted(submitted - valid_keys - metric_ticks)
         if bad:
             # A hiddenFields entry naming nothing hides nothing — and reads as a restriction
             # that is not there.
@@ -746,15 +1247,50 @@ def _clean_perms(v, governed_keys=None, session=None):
             if conj not in ("and", "or"):
                 raise err(400, "bad_filter", f"{key}: conj must be 'and' or 'or'")
             nodes = tree["nodes"]
-            cleaned = aios_grid.clean_filter_tree(nodes, valid_keys, cohort_ids=None)
-            if _leaf_count(cleaned) != _leaf_count(nodes):
-                raise err(400, "bad_filter",
-                          f"{key}: the filter contains conditions this module cannot evaluate "
-                          f"(an unknown field, an unknown operator, or a cohort leaf — cohorts "
-                          f"are per-user and cannot be a permanent rule). Refused rather than "
-                          f"saved with the bad conditions silently removed, which would store a "
-                          f"weaker wall than the one on screen.")
-            clean_tree = {"conj": conj, "nodes": cleaned}
+            # ⛔⛔ THE CASCADE DOES **NOT** RUN ON THE SUBMITTED TREE, AND W40-T05 SHIPPED THE
+            # OPPOSITE FOR AN HOUR. It pruned here first, so that an administrator with a stale
+            # tab would not be told their own saved rule was a client error. Sympathetic, and
+            # WRONG: `verify_api`'s leg *"⛔ a filter naming an unknown FIELD -> 400, never
+            # saved-minus-the-bad-leaf"* went red on the very case it exists for — a PUT naming
+            # `ghost` was accepted and stored minus that leaf. This validator is a SECURITY door,
+            # and the sentence the refusal below already carried says why: a wall saved with its
+            # bad conditions silently removed is WEAKER THAN THE ONE ON SCREEN.
+            #
+            # ⭐ SO THE CASCADE LIVES ON THE **STORED** RECORD ONLY, in `get_perms` (see
+            # `_prunable_vocabulary`'s own docstring). That is the honest split, and it is enough
+            # for I16: the leaf disappears when the record is next read, which is the same page
+            # load a stale tab has to do anyway. A leaf in a payload the client just SENT is
+            # refused, loudly, whatever its history — the server cannot tell a deleted column from
+            # a typo in a submission, and only one of those two guesses is safe.
+            # ⛔ AN EMPTIED FILTER IS `None`, NEVER `{"conj": "and", "nodes": []}`. Measured:
+            # `filter_eval.permits` returns True on an empty node list, so an empty-but-present
+            # tree admits every row — while `perm_scope.wall_declared` and `row_scope_applies`
+            # both read it as TRUTHY and answer that a wall applies. A door would then build rows
+            # in order to filter them against nothing, and the editor would paint a rule that is
+            # not there. This also normalises a client that PUTs `{"nodes": []}` to mean "no
+            # filter", which is what it has always meant on screen.
+            if nodes:
+                # Named before the generic refusal below, because "an unknown field" is exactly
+                # what this is NOT: the picker offered it one request ago. The admin needs to be
+                # told which column and why, or they will simply try again.
+                blind = sorted(_leaf_col_ids(nodes) & row_wall_blind)
+                if blind:
+                    raise err(400, "bad_filter",
+                              f"{key}: a permission filter cannot use {blind}. Those columns are "
+                              f"stored per record on top of this database rather than in it, and "
+                              f"the row wall runs before they are merged, so the rule would hide "
+                              f"EVERY row from this account with nothing on screen saying why. "
+                              f"Hide the column instead, or filter on one of the database's own "
+                              f"columns.")
+                cleaned = aios_grid.clean_filter_tree(nodes, filter_keys, cohort_ids=None)
+                if _leaf_count(cleaned) != _leaf_count(nodes):
+                    raise err(400, "bad_filter",
+                              f"{key}: the filter contains conditions this module cannot evaluate "
+                              f"(an unknown field, an unknown operator, or a cohort leaf — cohorts "
+                              f"are per-user and cannot be a permanent rule). Refused rather than "
+                              f"saved with the bad conditions silently removed, which would store "
+                              f"a weaker wall than the one on screen.")
+                clean_tree = {"conj": conj, "nodes": cleaned}
         # ⭐⭐ W38-T19 — `metrics` IS THE FOURTH FIELD OF AN ENTRY, AND ITS DEFAULT IS GRANT.
         # `raw.get("metrics", True)` rather than a required key: a PUT composed by an older
         # client, or a copy of a record written before this ticket, must not read as a
@@ -762,7 +1298,7 @@ def _clean_perms(v, governed_keys=None, session=None):
         # the validator and the wall cannot disagree about what an absent key means.
         out[key] = {"access": bool(raw.get("access", True)),
                     "filter": clean_tree,
-                    "hiddenFields": sorted({str(h) for h in hidden}),
+                    "hiddenFields": sorted(submitted),
                     "metrics": bool(raw.get("metrics", True))}
     _refuse_unshapeable_bu(out)
     return out
@@ -1052,6 +1588,31 @@ def get_perms(username: str, session: Session = Depends(admin_gate)):
     # ⭐⭐ W36-T22 / C2 — EVERY listed database, not an `enforced` subset of them. See
     # `perms.tenant_governable_modules` for why the flag is deleted rather than defaulted.
     governed = [m["key"] for m in modules]
+    # ⭐ ONE `_module_fields` PASS, SHARED BY THE PICKER AND THE CASCADE. It used to be built
+    # inline at the return; hoisted so the prune below reads the SAME vocabulary the payload
+    # offers rather than paying a second store round-trip per database to ask again.
+    fields_by_module = {k: _module_fields(k, session=session) for k in governed}
+    # ⭐⭐ W40-T05 / OWNER I16 — THE CASCADE, AT THE ADMIN DOOR. *"If the field is deleted, its
+    # permission filter goes with it."* A stored leaf naming a column the database no longer has
+    # is not ignored by the wall — `apply_row_scope` uses `permits`, which DENIES what it cannot
+    # answer — so a deleted column silently converts that account's grid to zero rows. Dropping
+    # the leaf here means the editor renders, and the record stores, only rules that still exist.
+    #
+    # ⛔⛔ GUARDED ON `is_migrated`, AND THAT GUARD IS A BU LEAK AWAY FROM OPTIONAL.
+    # `users.set_access(perms=…)` STAMPS `perms_v` in the same read-modify-write, so writing here
+    # would MIGRATE an un-migrated record — and `_fold_legacy_scope` runs only WHILE a record is
+    # un-migrated. A GET would then consume the one chance to fold the legacy `bus`/`agent` scope
+    # in, and the account would silently acquire the other business unit's customers. The
+    # `stored` test alone would very nearly cover it (an un-migrated record carries no perms
+    # block), so the marker is asked explicitly rather than inferred from an empty dict.
+    if stored and perm_scope.is_migrated(rec):
+        _pruned, _gone = _prune_stale_filters(stored, session=session)
+        if _gone:
+            users.set_access(uname, perms=_pruned)
+            # Re-read rather than trust the write: this route's whole job is to report what is
+            # STORED, and a store that took nothing must not be reported as if it had.
+            rec = _registry().get(uname) or rec
+            stored = rec.get("perms") or _pruned
     perms_out = {}
     for k in governed:
         e = stored.get(k)
@@ -1116,7 +1677,7 @@ def get_perms(username: str, session: Session = Depends(admin_gate)):
             # item 11's *"EVERY database should be able to be toggleable by admin"*, and it is
             # the SAME resolver `_clean_perms` validates against, so the picker cannot offer a
             # column the validator will reject.
-            "fields_by_module": {k: _module_fields(k, session=session) for k in governed}}
+            "fields_by_module": fields_by_module}
 
 
 @router.put("/admin/users/{username}/perms")

api/routes_auth.py

@@ -180,7 +180,41 @@ def login(request: Request, response: Response, body: dict = Body(default=None))
         raise err(401, "invalid_credentials", "that username and password do not match")
 
     _clear_failures(throttle_key)
-    value, _claims = aios_session.mint(tenant, user["username"], int(user.get("epoch") or 0))
+
+    # ⭐ WAVE 40, R2 — SINGLE SESSION, NEWEST WINS. Signing in here signs out every session this
+    # account already holds, so a forgotten sign-in on someone else's computer cannot lock the
+    # owner of the account out of it. NO SESSION REGISTRY IS BUILT and none is needed: the cookie
+    # is stateless and carries the epoch it was minted under, `deps._user_for` admits only on an
+    # exact match, so one bump kills every outstanding cookie for this user at once.
+    #
+    # ⛔ MINT FROM THE BUMPED VALUE, NEVER FROM `user["epoch"]` AGAIN. `user` was projected BEFORE
+    # the bump; minting from it would issue every cookie in the product at the OLD epoch, which
+    # `_user_for` refuses on the very next request — "200, then 401 forever".
+    #
+    # TWO IDENTITIES ARE EXEMPT, both by design:
+    #   * `qa_runner` — the synthetic staging identity has no registry record to bump (its epoch is
+    #     derived from APP_PASSWORD), and `verify_api.py` asserts its login path reads and writes
+    #     NOTHING on tenant #0's `users` key, which a bump's read-modify-write would violate.
+    #   * `emergency_master` — `deps._user_for` admits that identity whatever the record's epoch
+    #     says, so a bump revokes nothing there and only risks a store write on the break-glass
+    #     path that exists precisely for a store outage.
+    #
+    # A FAILED BUMP MUST NOT FAIL THE LOGIN. `store.update` raises `StoreWriteRefused` where the
+    # deployment may not write this tenant (mapped to 503 in `main.py`) and `RuntimeError` when the
+    # store is unavailable, so an unguarded bump would turn every sign-in on such a deployment into
+    # a 503. The sign-in stands at the epoch it can prove; only the sign-out-everywhere half is
+    # lost, and the log says so rather than leaving it silent.
+    session_epoch = int(user.get("epoch") or 0)
+    if not (user.get("qa_runner") or user.get("emergency_master")):
+        try:
+            bumped = users.bump_epoch(user["username"])
+            if bumped is not None:
+                session_epoch = int(bumped)
+        except Exception as exc:
+            print(f"[aios-api] login for {user['username']!r}: could not bump the session epoch "
+                  f"({type(exc).__name__}). This sign-in stands, but the account's previous "
+                  f"session was NOT signed out.")
+    value, _claims = aios_session.mint(tenant, user["username"], session_epoch)
     aios_session.set_cookie(response, request, value)
     # Wave 19 (R4): the login stamp. THE RESOLVED username, never the posted identifier — the
     # person may have typed an email address and `users.verify` resolved it to the registry key;
@@ -214,8 +248,9 @@ def logout(request: Request):
 
     ⚠ This clears the BROWSER's copy only — the signed value stays cryptographically valid until
     it expires, which is the honest cost of a stateless session. "Sign me out everywhere" is
-    `core.users.bump_epoch` (a password change already does it); D2's Postgres session mirror
-    makes per-device revocation possible and arrives with C-2.
+    `core.users.bump_epoch` (a password change already does it, and since wave 40's R2 so does
+    every LOGIN — signing in anywhere signs out every other session the account holds); D2's
+    Postgres session mirror makes per-device revocation possible and arrives with C-2.
     """
     out = Response(status_code=204)
     aios_session.clear_cookie(out, request)

api/routes_shares.py

@@ -1,90 +1,111 @@
-"""routes_shares.py — the manage-access surface (wave 20, owner ruling R10, contract C-SHARE).
-
-    GET  /api/v1/share/{kind}/{oid}      -> {owner, entries:[{user,role}], mayAdminister, people}
-    PUT  /api/v1/share/{kind}/{oid}      <- {entries:[{user,role}]}   (REPLACES the set)
-    GET  /api/v1/share/mine              -> {view:[id], folder:[id], database:[id]}
-
-`kind` ∈ view | folder | database | field. Roles are `view` | `edit` — the same two words the
-view rail already speaks, now extended to folders, databases and COLUMNS so there is ONE
-vocabulary in the UI (R10: "the same picker views use").
-
-⭐⭐ **W38-T16 — `field` IS THE FOURTH KIND, AND ITS `oid` IS TOPIC-QUALIFIED: `"<table_key>:<field_key>"`**
-(`shares.field_oid`). A bare column key repeats across databases — `notes` exists on a dozen —
-so a grant stored under one would admit the grantee to every `notes` column in the tenant at
-once. ⛔ THREE functions in this file branch on kind and ALL THREE need the new one, which is not
-obvious because only two of them fail loudly: `_owns_object` (without it a column's own creator
-is 404'd trying to share the thing they just made) and `_object_ref` (without it `route` is None,
-`_notify_new_grantees` returns early, and the grantee is **granted and never told** — owner item
-18's silent half, reopened one kind over). `_can_see_object` stays deliberately CLOSED for
-anything that is not a view.
-
-⛔ **RE-SHARING IS THE OWNER'S, AND THAT IS ENFORCED HERE, NOT IN THE CLIENT.** `PUT` requires
-`shares.may_administer` (owner or admin). A collaborator with `edit` may change an object's
-CONTENT and may not change who else can reach it — otherwise anyone you shared a view with could
-widen it to everyone, or grant themselves ownership and lock you out. The client greys the editor
-for non-administrators; that is a courtesy, and this check is the wall.
-
-⚠ **THE GRANT NEVER WIDENS PAST THE MODULE WALL — ON A GOVERNED MODULE.** `*` ("everyone") means
-every account that can already open the surface: `require_session` plus the topic's own gate run
-first, and for `customer_data` / `product_data` the receiver's own row scope and hidden-field
-closure run BEFORE any foreign view is merged. Sharing there can only narrow-or-equal the set that
-could already reach the data ([[aios-permissioning]]).
-
-⛔⛔ **AND THAT SENTENCE IS FALSE FOR `kind='database'`, WHICH IS WHY IT NOW SAYS "ON A GOVERNED
-MODULE" (W32-T26, audit S-8).** `routes_admin._PERM_MODULES` is `("customer_data","product_data")`
-and `_clean_perms` **400s** on anything else, so **no row filter and no hidden field can even be
-DECLARED for a `ut_*` database** — `routes_tables.py` makes zero `perm_scope` calls and passes
-`hidden_keys=frozenset()`. There is no module wall behind a user table for a grant to be bounded
-by: **this registry IS the wall.** So a `database` grant is ALL-OR-NOTHING — every row, every
-column — and an `*` database grant admits every account in the tenant to all of it.
-That is a real capability, deliberately kept; what was wrong was a docstring promising a second
-wall that does not exist for this kind. Scoping user tables is booked, not done
-(`waves/wave32/sharing-audit.md` S-8).
-
-⚠ **TWO SYSTEMS ANSWER "IS THIS SHARED", AND THEY ARE NOT THE SAME ONE (audit S-4).** THIS
-registry decides who appears in *"Shared with me"* and who may re-share. **`table_store.is_shared`
-— the view's own `permissions` — is what actually decides who may OPEN a view.** A grant here
-whose object is invisible under that one is a row in a list that opens a refusal, which is what
-made item 18 worth auditing. `_entries_or_400` closes the common cause (a name nobody has), but
-the two vocabularies are still two.
-"""
-from fastapi import APIRouter, Body, Depends
-
-import core.shares as shares
-import core.users as users
-from deps import Session, err, require_session
-# ⭐ W32-T28 (C3) — the SHARE notification's topic word, imported from the module that CLASSIFIES
-# it (`routes_alerts.notification_view`) rather than typed again here. The producer and the
-# reader agreeing about one string is the whole difference between an Inbox row that opens the
-# shared database and one that is quietly unclickable.
-from routes_alerts import SHARE_TOPIC as _SHARE_TOPIC
-
-router = APIRouter(prefix="/api/v1")
-
-
-def _kind_or_400(raw):
-    try:
-        return shares._check_kind(raw)
-    except ValueError as e:
-        raise err(400, "bad_kind", str(e))
-
-
-# ── ⭐⭐ WAVE 32 · T26 (owner item 18, ruling R12) — THE WALL THIS FILE SAID IT HAD ─────────────
-#
-# `put_share`'s comment used to justify the first-claim rule with *"reaching this route at all
-# means passing the surface's own wall"*. **There was no such wall.** `kind` and `oid` are free
-# strings off the URL and the only dependency was `require_session`, so any signed-in account
-# could `PUT` a grant on an id it had never seen. Because the 403 sat behind `if rec["owner"]`,
-# an object with no grant record skipped the check entirely and the caller was stamped OWNER —
-# sticky, so **the real creator was then refused on their own view, permanently.** Driven, not
-# argued: `waves/wave32/sharing-audit.md` S-1 carries the four-step transcript.
-#
-# ⚠ AND IT WAS SILENT ON BOTH SIDES. The claimant does not even see the object in their own
-# "Shared with me" (`shared_with` excludes what you own), so nothing appears anywhere until the
-# victim next opens the dialog.
-
-#: The built-in grid topics. A view or folder lives in `{topic}_table_workspace`, and the share
-#: route is not told which topic — so resolving one means asking each.
+"""routes_shares.py — the manage-access surface (wave 20, owner ruling R10, contract C-SHARE).
+
+    GET  /api/v1/share/{kind}/{oid}      -> {owner, entries:[{user,role}], mayAdminister, people}
+    PUT  /api/v1/share/{kind}/{oid}      <- {entries:[{user,role}]}   (REPLACES the set)
+    GET  /api/v1/share/mine              -> {view:[id], folder:[id], database:[id]}
+
+`kind` ∈ view | folder | database | field. Roles are `view` | `edit` — the same two words the
+view rail already speaks, now extended to folders, databases and COLUMNS so there is ONE
+vocabulary in the UI (R10: "the same picker views use").
+
+⭐⭐ **W38-T16 — `field` IS THE FOURTH KIND, AND ITS `oid` IS TOPIC-QUALIFIED: `"<table_key>:<field_key>"`**
+(`shares.field_oid`). A bare column key repeats across databases — `notes` exists on a dozen —
+so a grant stored under one would admit the grantee to every `notes` column in the tenant at
+once. ⛔ THREE functions in this file branch on kind and ALL THREE need the new one, which is not
+obvious because only two of them fail loudly: `_owns_object` (without it a column's own creator
+is 404'd trying to share the thing they just made) and `_object_ref` (without it `route` is None,
+`_notify_new_grantees` returns early, and the grantee is **granted and never told** — owner item
+18's silent half, reopened one kind over). `_can_see_object` stays deliberately CLOSED for
+anything that is not a view.
+
+⭐⭐ **A "Can edit" GRANTEE MAY RE-SHARE A VIEW — OWNER RULING R4, BUILT AS W40-T02** (instruction
+4: *"Edit View so a member can share a View as well, not just an admin"*). This REVERSES the flat
+owner-or-admin sentence that stood here, and the reversal is bounded three ways, all enforced HERE
+and not in the client:
+
+  1. **ONLY `kind='view'`.** `shares.RESHARE_KINDS` is the one spelling of that. `folder`,
+     `database` and `field` still require the owner or an admin, and the paragraph below is why
+     the `database` kind in particular was never a candidate: a `ut_*` grant's blast radius is a
+     whole table, where a view is one saved SELECTION over rows the receiver's own wall governs.
+  2. **A RE-SHARE MAY NEVER EXCEED THE RE-SHARER'S OWN ROLE**, and the strict reading ships: an
+     `edit` grantee may hand out `view` and NEVER `edit`. `shares.max_grantable_role` answers the
+     ceiling, `put_share` enforces it on the DELTA (a name arriving at `edit`, or one raised to
+     it) — never on every row of the body, because the `PUT` REPLACES and `ShareDialog.save`
+     therefore re-sends the whole list with the re-sharer's own `edit` row inside it. Conferring
+     `edit` stays the owner's alone.
+  3. **OWNERSHIP NEVER MOVES.** A caller re-sharing rather than owning passes the EXISTING owner
+     straight through (`put_share` below, stated rather than incidental).
+
+⛔ **SO OF THE TWO FEARS THE OLD SENTENCE NAMED, ONE IS ANSWERED AND ONE IS PRICED.** *"Grant
+themselves ownership and lock you out"* is closed by (3) and by `set_grants`' sticky owner: there
+is no path here by which a grantee becomes an owner. *"Widen a users-scoped view to everyone"* is
+NOT closed — an `edit` grantee may add `*` — it is CAPPED by (2) at `Can view`, on a surface where
+`require_session` plus the topic's own gate plus the receiver's row scope all still run first. That
+is the capability R4 asked for, stated as a cost rather than left as a surprise. A `view` grantee
+still cannot share at all, and still gets `403`. The client greys the editor for non-administrators
+and offers "Can edit" to anyone it greys in; that is a courtesy, and these checks are the wall.
+
+⚠ **THE GRANT NEVER WIDENS PAST THE MODULE WALL — ON A GOVERNED MODULE.** `*` ("everyone") means
+every account that can already open the surface: `require_session` plus the topic's own gate run
+first, and for `customer_data` / `product_data` the receiver's own row scope and hidden-field
+closure run BEFORE any foreign view is merged. Sharing there can only narrow-or-equal the set that
+could already reach the data ([[aios-permissioning]]).
+
+⛔⛔ **AND THAT SENTENCE IS FALSE FOR `kind='database'`, WHICH IS WHY IT NOW SAYS "ON A GOVERNED
+MODULE" (W32-T26, audit S-8).** `routes_admin._PERM_MODULES` is `("customer_data","product_data")`
+and `_clean_perms` **400s** on anything else, so **no row filter and no hidden field can even be
+DECLARED for a `ut_*` database** — `routes_tables.py` makes zero `perm_scope` calls and passes
+`hidden_keys=frozenset()`. There is no module wall behind a user table for a grant to be bounded
+by: **this registry IS the wall.** So a `database` grant is ALL-OR-NOTHING — every row, every
+column — and an `*` database grant admits every account in the tenant to all of it.
+That is a real capability, deliberately kept; what was wrong was a docstring promising a second
+wall that does not exist for this kind. Scoping user tables is booked, not done
+(`waves/wave32/sharing-audit.md` S-8).
+
+⚠ **TWO SYSTEMS ANSWER "IS THIS SHARED", AND THEY ARE NOT THE SAME ONE (audit S-4).** THIS
+registry decides who appears in *"Shared with me"* and who may re-share. **`table_store.is_shared`
+— the view's own `permissions` — is what actually decides who may OPEN a view.** A grant here
+whose object is invisible under that one is a row in a list that opens a refusal, which is what
+made item 18 worth auditing. `_entries_or_400` closes the common cause (a name nobody has), but
+the two vocabularies are still two.
+"""
+from fastapi import APIRouter, Body, Depends
+
+import core.shares as shares
+import core.users as users
+from deps import Session, err, require_session
+# ⭐ W32-T28 (C3) — the SHARE notification's topic word, imported from the module that CLASSIFIES
+# it (`routes_alerts.notification_view`) rather than typed again here. The producer and the
+# reader agreeing about one string is the whole difference between an Inbox row that opens the
+# shared database and one that is quietly unclickable.
+from routes_alerts import SHARE_TOPIC as _SHARE_TOPIC
+
+router = APIRouter(prefix="/api/v1")
+
+
+def _kind_or_400(raw):
+    try:
+        return shares._check_kind(raw)
+    except ValueError as e:
+        raise err(400, "bad_kind", str(e))
+
+
+# ── ⭐⭐ WAVE 32 · T26 (owner item 18, ruling R12) — THE WALL THIS FILE SAID IT HAD ─────────────
+#
+# `put_share`'s comment used to justify the first-claim rule with *"reaching this route at all
+# means passing the surface's own wall"*. **There was no such wall.** `kind` and `oid` are free
+# strings off the URL and the only dependency was `require_session`, so any signed-in account
+# could `PUT` a grant on an id it had never seen. Because the 403 sat behind `if rec["owner"]`,
+# an object with no grant record skipped the check entirely and the caller was stamped OWNER —
+# sticky, so **the real creator was then refused on their own view, permanently.** Driven, not
+# argued: `waves/wave32/sharing-audit.md` S-1 carries the four-step transcript.
+#
+# ⚠ AND IT WAS SILENT ON BOTH SIDES. The claimant does not even see the object in their own
+# "Shared with me" (`shared_with` excludes what you own), so nothing appears anywhere until the
+# victim next opens the dialog.
+
+#: The built-in grid topics. A view or folder lives in `{topic}_table_workspace`, and the share
+#: route is not told which topic — so resolving one means asking each.
 _BUILTIN_TOPICS = ("customer", "product")
 
 
@@ -136,38 +157,38 @@ def _field_owner(session, definition, already_shared):
 
 
 def _topics(session):
-    """Every topic whose workspace could hold a view or folder for this tenant.
-
-    ⚠ `all_defs`, never `all_tables` — the latter is the whole 28.6 MB row payload (~703 ms on
-    tenant #0) to answer a question about KEYS (D-185).
-    """
-    try:
-        import core.user_tables as ut
-        return (*_BUILTIN_TOPICS, *(ut.all_defs(st=session.runtime) or {}))
-    except Exception:                                       # noqa: BLE001
-        return _BUILTIN_TOPICS
-
-
-def _owns_object(session, kind, oid):
-    """May this caller CLAIM an object that has no grant record yet — i.e. do they own it?
-
-    ⛔ THIS GUARDS THE CLAIM, NOT THE READ, AND THAT IS DELIBERATE. Resolving a view means asking
-    each topic's workspace in turn, which is N store reads; making every share call pay that
-    would put a loop on a route the manage-access dialog opens. The dangerous path is the one
-    where a caller is about to be stamped OWNER of something nobody owns — so the resolution runs
-    exactly there, and the common path (a record exists, `may_administer` decides) is untouched.
-    """
-    if session.admin:
-        return True
-    if kind == "field":
-        # ⭐⭐ W38-T16 — A COLUMN'S OWNER IS ITS `createdBy`, WHICH THE CREATE DOOR ALREADY STAMPS
-        # (`routes_tables.patch_shared_cell`) and the DELETE door already reads as its wall (R8 /
-        # D-172: creator-or-admin). Read from the same place by all three, so a column cannot be
-        # deletable by one person and shareable by another.
-        # ⚠ THIS BRANCH IS NOT OPTIONAL AND ITS ABSENCE FAILS SILENTLY IN THE WORST DIRECTION:
-        # a brand-new column has no grant record, so `put_share` falls to this predicate — and
-        # without it the column's own creator is answered `404 no_object` on the first attempt to
-        # share the thing they just made.
+    """Every topic whose workspace could hold a view or folder for this tenant.
+
+    ⚠ `all_defs`, never `all_tables` — the latter is the whole 28.6 MB row payload (~703 ms on
+    tenant #0) to answer a question about KEYS (D-185).
+    """
+    try:
+        import core.user_tables as ut
+        return (*_BUILTIN_TOPICS, *(ut.all_defs(st=session.runtime) or {}))
+    except Exception:                                       # noqa: BLE001
+        return _BUILTIN_TOPICS
+
+
+def _owns_object(session, kind, oid):
+    """May this caller CLAIM an object that has no grant record yet — i.e. do they own it?
+
+    ⛔ THIS GUARDS THE CLAIM, NOT THE READ, AND THAT IS DELIBERATE. Resolving a view means asking
+    each topic's workspace in turn, which is N store reads; making every share call pay that
+    would put a loop on a route the manage-access dialog opens. The dangerous path is the one
+    where a caller is about to be stamped OWNER of something nobody owns — so the resolution runs
+    exactly there, and the common path (a record exists, `may_administer` decides) is untouched.
+    """
+    if session.admin:
+        return True
+    if kind == "field":
+        # ⭐⭐ W38-T16 — A COLUMN'S OWNER IS ITS `createdBy`, WHICH THE CREATE DOOR ALREADY STAMPS
+        # (`routes_tables.patch_shared_cell`) and the DELETE door already reads as its wall (R8 /
+        # D-172: creator-or-admin). Read from the same place by all three, so a column cannot be
+        # deletable by one person and shareable by another.
+        # ⚠ THIS BRANCH IS NOT OPTIONAL AND ITS ABSENCE FAILS SILENTLY IN THE WORST DIRECTION:
+        # a brand-new column has no grant record, so `put_share` falls to this predicate — and
+        # without it the column's own creator is answered `404 no_object` on the first attempt to
+        # share the thing they just made.
         table_key, field_key = shares.split_field_oid(oid)
         if not table_key:
             return False
@@ -175,118 +196,118 @@ def _owns_object(session, kind, oid):
             session, table_key, field_key)
         owner = _field_owner(session, defn, _shared)
         return bool(defn) and owner.lower() == str(session.uname).strip().lower()
-    if kind == "database":
-        # ⚠ `may_open` is THE resolver for a user table (its own docstring says so) and already
-        # admits creator, admin, or a `database` grantee. Re-implementing "who owns a table"
-        # here would be the second definition this wave keeps finding.
-        try:
-            import core.user_tables as ut
-            return bool(ut.may_open(oid, session.uname, is_admin=session.admin,
-                                    st=session.runtime))
-        except Exception:                                   # noqa: BLE001
-            return False
-    try:
-        import core.table_store as table_store
-    except Exception:                                       # noqa: BLE001
-        return False
-    for topic in _topics(session):
-        try:
-            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
-            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
-        except Exception:                                   # noqa: BLE001
-            continue
-        if hit:
-            # `find_view`/`find_folder` answer `(owner_username, …)`. The claim belongs to the
-            # person whose personal stratum holds it — anybody else reaching this line is
-            # exactly the case S-1 describes.
-            return str(hit[0]) == str(session.uname)
-    return False
-
-
-def _can_see_object(session, kind, oid):
-    """May this caller READ an object's grant list — i.e. can they reach the object at all?
-
-    ⛔⛔ THIS IS DELIBERATELY WIDER THAN {@link _owns_object}, AND CONFLATING THE TWO IS A
-    REGRESSION I SHIPPED AND CAUGHT. The first version of T26 guarded BOTH doors with the
-    ownership test, which reads sensibly and is wrong for the read, because **`find_view` searches
-    PERSONAL STRATA ONLY** (its own docstring says so). So a view living in alice's stratum with
-    `permissions.edit = "collaborative"` and no grant record yet — a view bob **can open and edit
-    in the grid** — answered `404` when bob opened its manage-access dialog. Measured before
-    fixing: `table_store._may_see(view, "bob") is True` while `GET /share/view/vc` said
-    `404 no_object`.
-    ⚠ THAT IS THE AUDIT'S OWN S-4 BITING THE AUDIT'S OWN FIX: two systems answer "is this shared",
-    and the wall consulted the grant registry (system A) plus stratum ownership, never the view's
-    `permissions` (system B) — which is the one that actually decides who may OPEN it.
-    ⚠ And it hides the ANSWER, not just the editor. `ViewSidebar`'s Share row is deliberately not
-    gated on edit rights because *"hiding the row from everyone else would hide the ANSWER too —
-    'who has this?' is a fair question for anyone the view was shared with"*. A 404 there tells a
-    legitimate collaborator their view does not exist.
-
-    ⛔ THE CLAIM KEEPS THE NARROW TEST. Being able to SEE an object must not let you become its
-    owner — that is S-1, and widening this predicate onto `put_share` would re-open it.
-    """
-    if _owns_object(session, kind, oid):
-        return True
-    if kind != "view":
-        # A folder carries no per-object visibility flag of its own, and a database's `may_open`
-        # (inside `_owns_object`) already admits grantees. Nothing wider to ask.
-        # ⭐ W38-T16 — AND `field` KEEPS THIS CLOSED, DELIBERATELY. A grantee never reaches here:
-        # `get_share` tests `role is None` first and a grant answers a role, so the only caller
-        # left is an account with no relationship to the column at all. Widening it would let any
-        # signed-in session enumerate who holds which column on a database they cannot open.
-        return False
-    try:
-        import core.table_store as table_store
-        for topic in _topics(session):
-            hit = table_store.make(f"{topic}_table_workspace", st=session.runtime).find_view(oid)
-            if hit:
-                return bool(table_store._may_see(hit[1] if len(hit) > 1 else {},
-                                                 session.uname, is_admin=session.admin))
-    except Exception:                                       # noqa: BLE001
-        return False
-    return False
-
-
-def _entries_or_400(session, entries):
-    """Validate a grant list against the tenant's REAL, ACTIVE accounts — and refuse BY NAME.
-
-    ⛔ `core.shares._clean_entries` silently drops junk, and its docstring argues that correctly:
-    a UI mid-save must not lose the whole list to one malformed row. **But it validates the SHAPE
-    of a string and the role word — never that the user EXISTS, is ACTIVE, or is in this tenant**,
-    so a typo'd name is stored, reported as a successful save, and never reaches anybody. The
-    sharer believes the person has access. That is item 18's plain reading.
-    ⚠ The correct population is computed THREE FUNCTIONS BELOW and served to the picker
-    (`_people`). One route, two populations, and the write door was the permissive one.
-    ⚠ `*` (everyone) is not a user and is admitted deliberately — it is R10's vocabulary for
-    "every account that can already open the surface".
-    """
-    known = {p["username"].strip().lower() for p in _people(session.tenant)}
-    unknown = []
-    for e in entries or ():
-        if not isinstance(e, dict):
-            continue
-        user = str(e.get("user") or "").strip().lower()
-        if user and user != shares.EVERYONE and user not in known:
-            unknown.append(user)
-    if unknown:
-        raise err(400, "unknown_people",
-                  "no active account in this workspace is named "
-                  + ", ".join(sorted(set(unknown)))
-                  + ". Nothing was shared. Pick people from the list rather than typing a name.")
-
-
-@router.get("/share/mine")
-def my_shares(session: Session = Depends(require_session)):
-    """Everything shared WITH me, by kind — the "Shared with me" rail section (R10).
-
-    Registered before `/share/{kind}/{oid}` so the literal path wins the match; FastAPI resolves
-    in declaration order and `mine` would otherwise be read as a `kind`, answering 400 for a URL
-    that is not malformed at all.
-    """
-    return shares.shared_with(session.uname, st=session.runtime)
-
-
-@router.get("/share/{kind}/{oid}")
+    if kind == "database":
+        # ⚠ `may_open` is THE resolver for a user table (its own docstring says so) and already
+        # admits creator, admin, or a `database` grantee. Re-implementing "who owns a table"
+        # here would be the second definition this wave keeps finding.
+        try:
+            import core.user_tables as ut
+            return bool(ut.may_open(oid, session.uname, is_admin=session.admin,
+                                    st=session.runtime))
+        except Exception:                                   # noqa: BLE001
+            return False
+    try:
+        import core.table_store as table_store
+    except Exception:                                       # noqa: BLE001
+        return False
+    for topic in _topics(session):
+        try:
+            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
+            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
+        except Exception:                                   # noqa: BLE001
+            continue
+        if hit:
+            # `find_view`/`find_folder` answer `(owner_username, …)`. The claim belongs to the
+            # person whose personal stratum holds it — anybody else reaching this line is
+            # exactly the case S-1 describes.
+            return str(hit[0]) == str(session.uname)
+    return False
+
+
+def _can_see_object(session, kind, oid):
+    """May this caller READ an object's grant list — i.e. can they reach the object at all?
+
+    ⛔⛔ THIS IS DELIBERATELY WIDER THAN {@link _owns_object}, AND CONFLATING THE TWO IS A
+    REGRESSION I SHIPPED AND CAUGHT. The first version of T26 guarded BOTH doors with the
+    ownership test, which reads sensibly and is wrong for the read, because **`find_view` searches
+    PERSONAL STRATA ONLY** (its own docstring says so). So a view living in alice's stratum with
+    `permissions.edit = "collaborative"` and no grant record yet — a view bob **can open and edit
+    in the grid** — answered `404` when bob opened its manage-access dialog. Measured before
+    fixing: `table_store._may_see(view, "bob") is True` while `GET /share/view/vc` said
+    `404 no_object`.
+    ⚠ THAT IS THE AUDIT'S OWN S-4 BITING THE AUDIT'S OWN FIX: two systems answer "is this shared",
+    and the wall consulted the grant registry (system A) plus stratum ownership, never the view's
+    `permissions` (system B) — which is the one that actually decides who may OPEN it.
+    ⚠ And it hides the ANSWER, not just the editor. `ViewSidebar`'s Share row is deliberately not
+    gated on edit rights because *"hiding the row from everyone else would hide the ANSWER too —
+    'who has this?' is a fair question for anyone the view was shared with"*. A 404 there tells a
+    legitimate collaborator their view does not exist.
+
+    ⛔ THE CLAIM KEEPS THE NARROW TEST. Being able to SEE an object must not let you become its
+    owner — that is S-1, and widening this predicate onto `put_share` would re-open it.
+    """
+    if _owns_object(session, kind, oid):
+        return True
+    if kind != "view":
+        # A folder carries no per-object visibility flag of its own, and a database's `may_open`
+        # (inside `_owns_object`) already admits grantees. Nothing wider to ask.
+        # ⭐ W38-T16 — AND `field` KEEPS THIS CLOSED, DELIBERATELY. A grantee never reaches here:
+        # `get_share` tests `role is None` first and a grant answers a role, so the only caller
+        # left is an account with no relationship to the column at all. Widening it would let any
+        # signed-in session enumerate who holds which column on a database they cannot open.
+        return False
+    try:
+        import core.table_store as table_store
+        for topic in _topics(session):
+            hit = table_store.make(f"{topic}_table_workspace", st=session.runtime).find_view(oid)
+            if hit:
+                return bool(table_store._may_see(hit[1] if len(hit) > 1 else {},
+                                                 session.uname, is_admin=session.admin))
+    except Exception:                                       # noqa: BLE001
+        return False
+    return False
+
+
+def _entries_or_400(session, entries):
+    """Validate a grant list against the tenant's REAL, ACTIVE accounts — and refuse BY NAME.
+
+    ⛔ `core.shares._clean_entries` silently drops junk, and its docstring argues that correctly:
+    a UI mid-save must not lose the whole list to one malformed row. **But it validates the SHAPE
+    of a string and the role word — never that the user EXISTS, is ACTIVE, or is in this tenant**,
+    so a typo'd name is stored, reported as a successful save, and never reaches anybody. The
+    sharer believes the person has access. That is item 18's plain reading.
+    ⚠ The correct population is computed THREE FUNCTIONS BELOW and served to the picker
+    (`_people`). One route, two populations, and the write door was the permissive one.
+    ⚠ `*` (everyone) is not a user and is admitted deliberately — it is R10's vocabulary for
+    "every account that can already open the surface".
+    """
+    known = {p["username"].strip().lower() for p in _people(session.tenant)}
+    unknown = []
+    for e in entries or ():
+        if not isinstance(e, dict):
+            continue
+        user = str(e.get("user") or "").strip().lower()
+        if user and user != shares.EVERYONE and user not in known:
+            unknown.append(user)
+    if unknown:
+        raise err(400, "unknown_people",
+                  "no active account in this workspace is named "
+                  + ", ".join(sorted(set(unknown)))
+                  + ". Nothing was shared. Pick people from the list rather than typing a name.")
+
+
+@router.get("/share/mine")
+def my_shares(session: Session = Depends(require_session)):
+    """Everything shared WITH me, by kind — the "Shared with me" rail section (R10).
+
+    Registered before `/share/{kind}/{oid}` so the literal path wins the match; FastAPI resolves
+    in declaration order and `mine` would otherwise be read as a `kind`, answering 400 for a URL
+    that is not malformed at all.
+    """
+    return shares.shared_with(session.uname, st=session.runtime)
+
+
+@router.get("/share/{kind}/{oid}")
 def get_share(kind: str, oid: str, session: Session = Depends(require_session)):
     kind = _kind_or_400(kind)
     if kind == "field":
@@ -303,50 +324,57 @@ def get_share(kind: str, oid: str, session: Session = Depends(require_session)):
     # a Member who owns an unshared View receives the people picker; a collaborator still does not.
     if not rec["owner"] and not may_admin and _owns_object(session, kind, oid):
         may_admin = True
-    # ⭐ W32-T26 (audit S-3) — A STRANGER LEARNS NOTHING. This route used to answer for ANY id:
-    # who owns it, everyone it is granted to, and the tenant's whole username↔name directory —
-    # to any signed-in session, about objects it cannot open. Now a caller with no role on an
-    # object must prove they can reach it, and gets a 404 otherwise: the same answer a
-    # non-existent id gives, so the route cannot be used to probe which ids are real.
-    # ⚠ `role is None` is the cheap pre-test, so the N-topic resolution below runs only for a
-    # caller who has no relationship with the object at all.
-    if role is None and not _can_see_object(session, kind, oid):
-        raise err(404, "no_object", "no such item, or it is not shared with this account")
-    return {
-        **rec,
-        "role": role,
-        "mayAdminister": may_admin,
-        # ⚠ WAVE 21 (C1 identity fix): grant entries BIND on USERNAMES, so the picker must carry
-        # them. `assignable_people` serves bare display names because `user`-kind CELLS store
-        # display names — that list's shape cannot change without migrating cell values — so
-        # this route serves objects of its own. Existing grants that were written as lowercased
-        # display names are normalised by the wave-21 cleanup script.
-        # ⭐ W32-T26 (audit S-3) — the roster is the EDITOR's data, so it rides only for a caller
-        # who may open the editor. A read-only grantee gets the grant list (their fair question is
-        # "who else has this?") and not a directory of every account in the workspace.
-        "people": _people(session.tenant) if may_admin else [],
-    }
-
-
-def _people(tenant):
-    """[{username, name}] for this tenant — same population as `assignable_people`, with the
-    BINDING identity alongside the display one."""
-    try:
-        reg = users.registry() or {}
-    except Exception:
-        return []
-    want = str(tenant or '').strip().lower()
-    out = []
-    for uname, u in reg.items():
-        if not isinstance(u, dict) or u.get('active') is False:
-            continue
-        if want and str(u.get('tenant') or 'royal-imports').strip().lower() != want:
-            continue
-        out.append({"username": str(uname), "name": str(u.get('name') or uname)})
-    return sorted(out, key=lambda p: p["name"].lower())
-
-
-@router.put("/share/{kind}/{oid}")
+    # ⭐ W32-T26 (audit S-3) — A STRANGER LEARNS NOTHING. This route used to answer for ANY id:
+    # who owns it, everyone it is granted to, and the tenant's whole username↔name directory —
+    # to any signed-in session, about objects it cannot open. Now a caller with no role on an
+    # object must prove they can reach it, and gets a 404 otherwise: the same answer a
+    # non-existent id gives, so the route cannot be used to probe which ids are real.
+    # ⚠ `role is None` is the cheap pre-test, so the N-topic resolution below runs only for a
+    # caller who has no relationship with the object at all.
+    if role is None and not _can_see_object(session, kind, oid):
+        raise err(404, "no_object", "no such item, or it is not shared with this account")
+    return {
+        **rec,
+        "role": role,
+        "mayAdminister": may_admin,
+        # ⚠ WAVE 21 (C1 identity fix): grant entries BIND on USERNAMES, so the picker must carry
+        # them. `assignable_people` serves bare display names because `user`-kind CELLS store
+        # display names — that list's shape cannot change without migrating cell values — so
+        # this route serves objects of its own. Existing grants that were written as lowercased
+        # display names are normalised by the wave-21 cleanup script.
+        # ⭐ W32-T26 (audit S-3) — the roster is the EDITOR's data, so it rides only for a caller
+        # who may open the editor. A read-only grantee gets the grant list (their fair question is
+        # "who else has this?") and not a directory of every account in the workspace.
+        # ⭐⭐ W40-T02 / R4 — AND THAT RULE IS WHY THIS LINE NEEDED NO EDIT. `may_administer` now
+        # answers True for an `edit` grantee on a VIEW, which MOVES that account into "may open
+        # the editor" — so the picker they need arrives by the roster riding on the same flag it
+        # always did. Gating it on anything else (owner, `role == 'owner'`, a fresh predicate)
+        # would be a second answer to a question this file already answers once, and would leave
+        # the new grantee with an editor and no people to put in it. A `view` grantee is still
+        # `may_admin=False` here and still gets `[]`.
+        "people": _people(session.tenant) if may_admin else [],
+    }
+
+
+def _people(tenant):
+    """[{username, name}] for this tenant — same population as `assignable_people`, with the
+    BINDING identity alongside the display one."""
+    try:
+        reg = users.registry() or {}
+    except Exception:
+        return []
+    want = str(tenant or '').strip().lower()
+    out = []
+    for uname, u in reg.items():
+        if not isinstance(u, dict) or u.get('active') is False:
+            continue
+        if want and str(u.get('tenant') or 'royal-imports').strip().lower() != want:
+            continue
+        out.append({"username": str(uname), "name": str(u.get('name') or uname)})
+    return sorted(out, key=lambda p: p["name"].lower())
+
+
+@router.put("/share/{kind}/{oid}")
 def put_share(kind: str, oid: str, body: dict = Body(default=None),
               session: Session = Depends(require_session)):
     kind = _kind_or_400(kind)
@@ -355,31 +383,88 @@ def put_share(kind: str, oid: str, body: dict = Body(default=None),
         if table_key and field_key:
             oid = shares.field_oid(_field_storage_keys(table_key)[2], field_key)
     body = body or {}
-    rec = shares.grants(kind, oid, st=session.runtime)
-    # An object with NO grant record yet has no owner — the first person to share it claims it.
-    # That is safe because reaching this route at all means passing the surface's own wall, and
-    # the alternative (refusing until somebody seeds an owner) would make a brand-new folder
-    # unshareable by the person who just made it.
-    if rec["owner"]:
-        if not shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
-                                     st=session.runtime):
-            raise err(403, "not_owner",
-                      "only the owner of this item (or an administrator) can change who it is "
-                      "shared with")
-    # ⛔⛔ W32-T26 (audit S-1) — THE CLAIM NOW HAS A PRECONDITION. An object with no grant record
-    # is still claimed by the first person to share it — that rule is right, and refusing until
-    # somebody seeds an owner would make a brand-new folder unshareable by the person who just
-    # made it. What was missing is the half the old comment ASSERTED and the code never did: the
-    # claimant has to be able to reach the object. Without this, any signed-in account could
-    # stamp itself owner of an id it had never seen and lock the real creator out for good.
-    elif not _owns_object(session, kind, oid):
-        raise err(404, "no_object", "no such item, or it is not shared with this account")
-    entries = body.get("entries")
+    rec = shares.grants(kind, oid, st=session.runtime)
+    # `claiming` is the "no owner yet, and this caller may become one" branch, hoisted to a name
+    # because TWO decisions below need it: the ceiling (a claimant is about to be the owner, so
+    # their ceiling is an owner's) and the owner written back (D3 — see `set_grants` at the end).
+    claiming = False
+    # An object with NO grant record yet has no owner — the first person to share it claims it.
+    # That is safe because reaching this route at all means passing the surface's own wall, and
+    # the alternative (refusing until somebody seeds an owner) would make a brand-new folder
+    # unshareable by the person who just made it.
+    if rec["owner"]:
+        if not shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
+                                     st=session.runtime):
+            # ⭐ R4 / W40-T02 — `may_administer` now also admits an `edit` grantee on a VIEW, so
+            # the population refused here is narrower than the code word `not_owner` suggests: a
+            # `view` grantee, or an account with an `edit` role on a kind outside
+            # `shares.RESHARE_KINDS`. The code string is kept because clients match on it.
+            raise err(403, "not_owner",
+                      "only the owner of this item (or an administrator) can change who it is "
+                      "shared with")
+    # ⛔⛔ W32-T26 (audit S-1) — THE CLAIM NOW HAS A PRECONDITION. An object with no grant record
+    # is still claimed by the first person to share it — that rule is right, and refusing until
+    # somebody seeds an owner would make a brand-new folder unshareable by the person who just
+    # made it. What was missing is the half the old comment ASSERTED and the code never did: the
+    # claimant has to be able to reach the object. Without this, any signed-in account could
+    # stamp itself owner of an id it had never seen and lock the real creator out for good.
+    elif not _owns_object(session, kind, oid):
+        raise err(404, "no_object", "no such item, or it is not shared with this account")
+    else:
+        claiming = True
+    entries = body.get("entries")
     if not isinstance(entries, list):
         raise err(400, "bad_entries",
                   "entries must be a list of {user, role}. Send [] to un-share, which is how "
                   "revoking is expressed")
     _entries_or_400(session, entries)
+    # ⭐⭐ R4 / W40-T02 — THE CEILING. `may_administer` above now opens this door to an `edit`
+    # grantee on a VIEW, so R4's other half ("a re-share may never exceed the role the re-sharer
+    # holds") needs a check of its own: that caller may hand out `view`, and conferring `edit`
+    # stays the owner's or an administrator's.
+    #
+    # ⛔ AFTER THE ADMISSION, NEVER BEFORE, AND THAT ORDER IS A SECURITY PROPERTY. A caller with
+    # no role at all must keep receiving `404 no_object` (audit S-1/S-3: a stranger learns
+    # nothing, so this route cannot be used to probe which ids are real). A ceiling raised first
+    # would answer that caller `403` and turn the one route hardened against id-probing back into
+    # an oracle that confirms an id exists. It also runs before the `field` promotion below, so a
+    # refusal cannot leave a column promoted with no grant written.
+    #
+    # ⛔ AND IT IS THE DELTA, NOT EVERY ROW OF THE BODY — read off the shipped client, not
+    # assumed. `ShareDialog.save` PUTs the WHOLE list every time ("a body assembled from a delta
+    # would revoke everyone it failed to mention"), so the re-sharer's OWN `{user, role: "edit"}`
+    # row rides in every payload they are able to produce. Refusing per-entry would `403` the
+    # exact re-share this ticket exists to enable, and the only body that would pass is one that
+    # revokes the re-sharer. So what is refused is edit access this caller is CREATING: a name
+    # arriving at `edit`, or an existing `view` grantee raised to it. A row that already stood at
+    # `edit` was the OWNER's decision, and is not this caller's to be refused for.
+    #
+    # ⚠ A CLAIMANT IS AN OWNER. The branch above admits a Member who owns an object that has no
+    # grant record yet, and `set_grants` is about to stamp them owner — asking the registry for
+    # their role here would answer `None` (no record exists to hold one) and refuse the first
+    # `edit` grant on every newly created view. Same predicate as the door, one line apart.
+    ceiling = "edit" if claiming else shares.max_grantable_role(
+        kind, oid, session.uname, is_admin=session.admin, st=session.runtime)
+    if ceiling != "edit":
+        held = {e.get("user"): e.get("role") for e in (rec["entries"] or ())}
+        raised = set()
+        for e in entries:
+            if not isinstance(e, dict):
+                continue
+            who = str(e.get("user") or "").strip().lower()
+            if who and str(e.get("role") or "").strip().lower() == "edit" \
+                    and held.get(who) != "edit":
+                raised.add(who)
+        if raised:
+            noun = {"view": "view", "folder": "folder",
+                    "database": "database", "field": "column"}.get(kind, "item")
+            named = ", ".join("everyone in this workspace" if w == shares.EVERYONE else w
+                              for w in sorted(raised))
+            raise err(403, "grant_exceeds_role",
+                      "you can share this " + noun + " at Can view, which is as far as your own "
+                      "access reaches. Only its owner (or an administrator) can give somebody "
+                      "Can edit, so nothing was saved. Set " + named
+                      + " to Can view and save again.")
     if kind == "field":
         # A field grant is a visibility and edit wall. Promote a private custom
         # field exactly once, then keep the requested Share field role as the
@@ -399,91 +484,101 @@ def put_share(kind: str, oid: str, body: dict = Body(default=None),
         stamped["granted"] = True
         shared_overlay.put_field(shared_key, field_key, stamped, st=session.runtime)
         oid = shares.field_oid(grant_topic, field_key)
-    out = shares.set_grants(kind, oid, entries, owner=rec["owner"] or session.uname,
+    # ⭐⭐ R4 / W40-T02 (D3) — OWNERSHIP NEVER MOVES ON A RE-SHARE, AND IT IS SAID HERE RATHER
+    # THAN LEFT TO FALL OUT. `set_grants`' owner is sticky, so the old `rec["owner"] or
+    # session.uname` already happened not to transfer ownership — incidentally, as a property of
+    # the callee. R4 names ownership transfer as one of the two halves of the old protection that
+    # SURVIVES the widening, and a rule that survives by accident is one the next edit deletes
+    # without noticing. So the branch is explicit: a claimant becomes the owner, and everybody
+    # else — an owner re-saving, an admin, and now an `edit` grantee re-sharing — passes the
+    # EXISTING owner straight back through. `claiming` is the same flag the admission set, so
+    # there is no second answer to "is this person taking ownership".
+    out = shares.set_grants(kind, oid, entries,
+                            owner=session.uname if claiming else rec["owner"],
                             st=session.runtime)
-    _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
-    return out
-
-
-def _notify_new_grantees(session, kind, oid, before, after):
-    """⭐⭐ W32-T28 (owner item 18's last clause, contract C3) — tell the RECEIVER, in their Inbox.
-
-    Owner item 18 ends *"being shared a database notifies the receiver"*. Until now sharing was
-    silent: the grant landed in a rail section the receiver had to notice on their own, which is
-    why "I shared it with you" and "I never saw it" were both true.
-
-    ⛔ WRITTEN ON THE SHARE, NEVER POLLED. `/notifications` re-evaluates view-ALERTS on read
-    because an alert is a live question about rows; a share is an EVENT that happened once, and
-    polling for it would mean re-deriving "was this new?" on every inbox open — the diff below
-    only exists here, at the moment the set changes.
-
-    ⚠ ONLY THE NEWLY ADDED. `PUT` REPLACES the whole entry set (revoking is expressed by absence),
-    so every save re-sends everyone who was already there. Diffing against `before` is what stops
-    a rename or a role change from ringing the bell for people whose access did not change.
-    ⚠ `*` IS NOT NOTIFIED: there is no user to name, and minting one notification per account in
-    the tenant on a single click is a broadcast nobody asked for. The rail still shows it.
-    ⚠ IT NEVER RAISES. A notification that fails must not fail the share that triggered it — the
-    grant is the user's actual intent, and `core.alerts.notify` writes with `flush='async'`.
-    """
-    try:
-        was = {e.get("user") for e in (before or ()) if isinstance(e, dict)}
-        fresh = [str(e.get("user")) for e in (after or ())
-                 if isinstance(e, dict) and e.get("user") not in was
-                 and e.get("user") != shares.EVERYONE]
-        if not fresh:
-            return
-        import core.alerts as alerts
-
-        label, route, view_id = _object_ref(session, kind, oid)
-        if not route:
-            # ⛔ NO ROUTE, NO NOTIFICATION — the receiver would get a row that opens nothing, and
-            # `notification_view` would have to invent a target. Silence is the honest answer
-            # here; the rail still shows the grant under "Shared with me".
-            return
-        sharer = str(session.user.get("name") or session.uname)
-        for user in fresh:
-            # ⚠ THE SHAPE IS `routes_alerts.notification_view`'s SHARE BRANCH, and the two must
-            # agree or the Inbox row is unclickable: `topic` selects the branch and `key` becomes
-            # `alertId`, which that branch reads as the id to open. Both constants are IMPORTED
-            # from there rather than typed again — one vocabulary, one owner.
-            # ⭐⭐ W33-T28 (`ASK C-14`, answered) — `actor` IS THE SENDER, AND IT IS THE ONLY WAY
-            # THE INBOX CAN NAME ONE. An alert and an automation have no person behind them and
-            # are honestly named by their machine; a SHARE has a real person, and only this call
-            # site knows who. ⛔ It is passed as its OWN field rather than recovered from the
-            # `detail` prose below: a sender parsed out of "<name> shared this with you" breaks
-            # the first time the sentence is reworded, silently, in the header
-            # [[grep-output-is-not-source]]. The prose stays as the body; this is the From.
-            alerts.notify(user, label, topic=_SHARE_TOPIC, key=route, row_id=view_id,
-                          detail=f"{sharer} shared this with you", actor=sharer,
-                          st=session.runtime)
-    except Exception:                                       # noqa: BLE001
-        return
-
-
-def _object_ref(session, kind, oid):
-    """`(label, route, view_id)` — what to CALL the shared thing, and where it OPENS.
-
-    ⛔ THE ROUTE IS RESOLVED HERE, NOT SHAPED IN THE CONSUMER, AND THE FIRST VERSION GOT IT
-    WRONG: it put the raw `oid` in the notification's key, so a shared VIEW produced
-    `target: {module: "database", id: "view_42"}` — an instruction to open a database named
-    `view_42`. It read perfectly in the payload and would have opened nothing. **A view is not
-    addressable on its own; it is a SELECTION inside a topic's grid**, so the pair is what has to
-    travel. Caught by looking at the notification the driver actually produced, not by reading
-    the code back.
-
-    ⚠ `label` never falls back to a raw id. A notification headed `ut_leads_3f2a` tells the
-    receiver nothing they can act on, and the id is already in the target.
-    ⚠ An unresolvable object answers `route=None`, and the caller then sends NOTHING rather than
-    a row that opens nowhere.
-    """
-    try:
-        if kind == "field":
-            # ⭐⭐ W38-T16 — A COLUMN IS NOT ADDRESSABLE ON ITS OWN, exactly as a view is not: it
-            # is a column INSIDE a database, so the target that travels is the DATABASE. Without
-            # this branch the function falls through to the view/folder loop, finds nothing,
-            # answers `route=None` — and `_notify_new_grantees` returns EARLY. The grant lands and
-            # the receiver is never told, which is the silent half of owner item 18 reopened one
-            # kind over.
+    _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
+    return out
+
+
+def _notify_new_grantees(session, kind, oid, before, after):
+    """⭐⭐ W32-T28 (owner item 18's last clause, contract C3) — tell the RECEIVER, in their Inbox.
+
+    Owner item 18 ends *"being shared a database notifies the receiver"*. Until now sharing was
+    silent: the grant landed in a rail section the receiver had to notice on their own, which is
+    why "I shared it with you" and "I never saw it" were both true.
+
+    ⛔ WRITTEN ON THE SHARE, NEVER POLLED. `/notifications` re-evaluates view-ALERTS on read
+    because an alert is a live question about rows; a share is an EVENT that happened once, and
+    polling for it would mean re-deriving "was this new?" on every inbox open — the diff below
+    only exists here, at the moment the set changes.
+
+    ⚠ ONLY THE NEWLY ADDED. `PUT` REPLACES the whole entry set (revoking is expressed by absence),
+    so every save re-sends everyone who was already there. Diffing against `before` is what stops
+    a rename or a role change from ringing the bell for people whose access did not change.
+    ⚠ `*` IS NOT NOTIFIED: there is no user to name, and minting one notification per account in
+    the tenant on a single click is a broadcast nobody asked for. The rail still shows it.
+    ⚠ IT NEVER RAISES. A notification that fails must not fail the share that triggered it — the
+    grant is the user's actual intent, and `core.alerts.notify` writes with `flush='async'`.
+    """
+    try:
+        was = {e.get("user") for e in (before or ()) if isinstance(e, dict)}
+        fresh = [str(e.get("user")) for e in (after or ())
+                 if isinstance(e, dict) and e.get("user") not in was
+                 and e.get("user") != shares.EVERYONE]
+        if not fresh:
+            return
+        import core.alerts as alerts
+
+        label, route, view_id = _object_ref(session, kind, oid)
+        if not route:
+            # ⛔ NO ROUTE, NO NOTIFICATION — the receiver would get a row that opens nothing, and
+            # `notification_view` would have to invent a target. Silence is the honest answer
+            # here; the rail still shows the grant under "Shared with me".
+            return
+        sharer = str(session.user.get("name") or session.uname)
+        for user in fresh:
+            # ⚠ THE SHAPE IS `routes_alerts.notification_view`'s SHARE BRANCH, and the two must
+            # agree or the Inbox row is unclickable: `topic` selects the branch and `key` becomes
+            # `alertId`, which that branch reads as the id to open. Both constants are IMPORTED
+            # from there rather than typed again — one vocabulary, one owner.
+            # ⭐⭐ W33-T28 (`ASK C-14`, answered) — `actor` IS THE SENDER, AND IT IS THE ONLY WAY
+            # THE INBOX CAN NAME ONE. An alert and an automation have no person behind them and
+            # are honestly named by their machine; a SHARE has a real person, and only this call
+            # site knows who. ⛔ It is passed as its OWN field rather than recovered from the
+            # `detail` prose below: a sender parsed out of "<name> shared this with you" breaks
+            # the first time the sentence is reworded, silently, in the header
+            # [[grep-output-is-not-source]]. The prose stays as the body; this is the From.
+            alerts.notify(user, label, topic=_SHARE_TOPIC, key=route, row_id=view_id,
+                          detail=f"{sharer} shared this with you", actor=sharer,
+                          st=session.runtime)
+    except Exception:                                       # noqa: BLE001
+        return
+
+
+def _object_ref(session, kind, oid):
+    """`(label, route, view_id)` — what to CALL the shared thing, and where it OPENS.
+
+    ⛔ THE ROUTE IS RESOLVED HERE, NOT SHAPED IN THE CONSUMER, AND THE FIRST VERSION GOT IT
+    WRONG: it put the raw `oid` in the notification's key, so a shared VIEW produced
+    `target: {module: "database", id: "view_42"}` — an instruction to open a database named
+    `view_42`. It read perfectly in the payload and would have opened nothing. **A view is not
+    addressable on its own; it is a SELECTION inside a topic's grid**, so the pair is what has to
+    travel. Caught by looking at the notification the driver actually produced, not by reading
+    the code back.
+
+    ⚠ `label` never falls back to a raw id. A notification headed `ut_leads_3f2a` tells the
+    receiver nothing they can act on, and the id is already in the target.
+    ⚠ An unresolvable object answers `route=None`, and the caller then sends NOTHING rather than
+    a row that opens nowhere.
+    """
+    try:
+        if kind == "field":
+            # ⭐⭐ W38-T16 — A COLUMN IS NOT ADDRESSABLE ON ITS OWN, exactly as a view is not: it
+            # is a column INSIDE a database, so the target that travels is the DATABASE. Without
+            # this branch the function falls through to the view/folder loop, finds nothing,
+            # answers `route=None` — and `_notify_new_grantees` returns EARLY. The grant lands and
+            # the receiver is never told, which is the silent half of owner item 18 reopened one
+            # kind over.
             from routes_alerts import route_for_topic
             table_key, field_key = shares.split_field_oid(oid)
             if not table_key:
@@ -494,39 +589,39 @@ def _object_ref(session, kind, oid):
             except Exception:                               # noqa: BLE001
                 defn = None
             label = str((defn or {}).get("label") or "").strip() or field_key
-            # ⚠ TWO SPELLINGS REACH THIS LINE AND ONE MAP ANSWERS BOTH. `shared_overlay` is keyed
-            # by whatever the calling door already held: a `ut_*` database uses its bare key,
-            # while a registry topic uses `<topic>_table_workspace` (`product_data.TABLE_KEY`).
-            # `route_for_topic` speaks the GRID SCOPE vocabulary (`customer`, not
-            # `customer_data`), so the suffix comes off before it is asked — rather than a second
-            # route table being written here, which is how the two come apart.
+            # ⚠ TWO SPELLINGS REACH THIS LINE AND ONE MAP ANSWERS BOTH. `shared_overlay` is keyed
+            # by whatever the calling door already held: a `ut_*` database uses its bare key,
+            # while a registry topic uses `<topic>_table_workspace` (`product_data.TABLE_KEY`).
+            # `route_for_topic` speaks the GRID SCOPE vocabulary (`customer`, not
+            # `customer_data`), so the suffix comes off before it is asked — rather than a second
+            # route table being written here, which is how the two come apart.
             _WS = "_table_workspace"
             scope = {"customer_data": "customer", "product_data": "product"}.get(table_key)
             if scope is None:
                 scope = table_key[:-len(_WS)] if table_key.endswith(_WS) else table_key
             return (label, route_for_topic(scope) or None, "")
-        if kind == "database":
-            import core.user_tables as ut
-            defn = (ut.all_defs(st=session.runtime) or {}).get(str(oid)) or {}
-            # A user table IS its own route key in both vocabularies (`route_for_topic`).
-            return (str(defn.get("label") or "").strip() or "A database", str(oid), "")
-        import core.table_store as table_store
-        from routes_alerts import route_for_topic
-        for topic in _topics(session):
-            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
-            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
-            if not hit:
-                continue
-            route = route_for_topic(topic)
-            if not route:
-                break
-            row = hit[1] if len(hit) > 1 else {}
-            name = str((row or {}).get("name") or "").strip()
-            # ⚠ Only a VIEW carries a selection. A folder is a rail grouping, so the target opens
-            # the grid and stops there rather than naming a view the receiver did not get.
-            return (name or ("A view" if kind == "view" else "A folder"),
-                    route, str(oid) if kind == "view" else "")
-    except Exception:                                       # noqa: BLE001
-        pass
-    return ({"view": "A view", "folder": "A folder",
-             "field": "A column"}.get(kind, "An item"), None, "")
+        if kind == "database":
+            import core.user_tables as ut
+            defn = (ut.all_defs(st=session.runtime) or {}).get(str(oid)) or {}
+            # A user table IS its own route key in both vocabularies (`route_for_topic`).
+            return (str(defn.get("label") or "").strip() or "A database", str(oid), "")
+        import core.table_store as table_store
+        from routes_alerts import route_for_topic
+        for topic in _topics(session):
+            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
+            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
+            if not hit:
+                continue
+            route = route_for_topic(topic)
+            if not route:
+                break
+            row = hit[1] if len(hit) > 1 else {}
+            name = str((row or {}).get("name") or "").strip()
+            # ⚠ Only a VIEW carries a selection. A folder is a rail grouping, so the target opens
+            # the grid and stops there rather than naming a view the receiver did not get.
+            return (name or ("A view" if kind == "view" else "A folder"),
+                    route, str(oid) if kind == "view" else "")
+    except Exception:                                       # noqa: BLE001
+        pass
+    return ({"view": "A view", "folder": "A folder",
+             "field": "A column"}.get(kind, "An item"), None, "")

platform/aios_grid_fields.json

@@ -1,396 +1,413 @@
-{
-  "_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."
-      },
+{
+  "_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,multiselect,currency,int,date,pct,url} (select = a fixed-choice READ-ONLY brand attribute; dba is the first, wave 2026-08-02. multiselect = one cell holding a comma-joined SET, so a choice list offers the MEMBERS, not the joined string; customer tags and product supplier are the first, wave 40 W40-T06. url = a link cell, GridCellKind.Uri, drawn by cells.ts and opened by CustomerGrid's scheme-guarded click path; maps_url is the first, wave 40 W40-T08). W40-T08 also adds created_on, the uniform records-created DATE column every database carries (owner I24). It is a plain date field and NOT the created_time TYPE on purpose: created_time renders the row-level _created datum and its value never lives at the field's own key, so it is invisible to the semantic topic, to a stored-cell read and to any host-side export, while a date field is an ordinary cell that all three can see. The _created datum still rides every row for a created_time column a user creates. `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 connector attributes display as '(none)' (they are no longer all `text`: W40-T06 retyped eight of them to `select` and `tags` to `multiselect`, and the sentinel is a real member of every one of those vocabularies), 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": "select",
+      "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": "select",
+      "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": "select",
+      "source": "odoo",
+      "default": true,
+      "description": "City on the customer's Odoo address."
+    },
+    {
+      "key": "state",
+      "label": "State",
+      "type": "select",
+      "source": "odoo",
+      "default": true,
+      "description": "State or province on the customer's Odoo address."
+    },
+    {
+      "key": "country",
+      "label": "Country",
+      "type": "select",
+      "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": "maps_url",
+      "label": "Google Maps",
+      "type": "url",
+      "source": "odoo",
+      "default": true,
+      "description": "A Google Maps link to this customer's 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": "multiselect",
+      "source": "odoo",
+      "default": false,
+      "description": "Odoo labels on this customer, comma-separated."
+    },
+    {
+      "key": "pricelist",
+      "label": "Customer price list",
+      "type": "select",
+      "source": "odoo",
+      "default": false,
+      "description": "The price list this customer buys on."
+    },
+    {
+      "key": "payment_terms",
+      "label": "Payment terms",
+      "type": "select",
+      "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": "select",
+      "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": "created_on",
+      "label": "Record created",
+      "type": "date",
+      "source": "odoo",
+      "default": false,
+      "description": "The date this customer record was created in Odoo."
+    },
+    {
+      "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": "multiselect",
+        "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": "price_1",
         "label": "Price 1",
         "type": "currency",
         "source": "odoo",
+        "default": false,
         "description": "Cheapest live price for this SKU, across active pricelists."
       },
       {
@@ -398,6 +415,7 @@
         "label": "Unit 1",
         "type": "text",
         "source": "odoo",
+        "default": false,
         "description": "Package label for Price 1. Blank means Odoo has no package reference for that price."
       },
       {
@@ -405,6 +423,7 @@
         "label": "Price 2",
         "type": "currency",
         "source": "odoo",
+        "default": false,
         "description": "Second-cheapest live price for this SKU."
       },
       {
@@ -412,6 +431,7 @@
         "label": "Unit 2",
         "type": "text",
         "source": "odoo",
+        "default": false,
         "description": "Package label for Price 2."
       },
       {
@@ -419,6 +439,7 @@
         "label": "Price 3",
         "type": "currency",
         "source": "odoo",
+        "default": false,
         "description": "Third-cheapest live price for this SKU."
       },
       {
@@ -426,8 +447,153 @@
         "label": "Unit 3",
         "type": "text",
         "source": "odoo",
+        "default": false,
         "description": "Package label for Price 3."
       },
+      {
+        "key": "price_fisch_t1",
+        "label": "Fisch tier 1 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Fisch price tier 1, cheapest first. Blank when Fisch does not price this SKU."
+      },
+      {
+        "key": "unit_fisch_t1",
+        "label": "Fisch tier 1 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Fisch tier 1 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_fisch_t2",
+        "label": "Fisch tier 2 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Fisch price tier 2. Blank when Fisch prices this SKU at only one tier."
+      },
+      {
+        "key": "unit_fisch_t2",
+        "label": "Fisch tier 2 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Fisch tier 2 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_fisch_t3",
+        "label": "Fisch tier 3 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Fisch price tier 3. Blank when Fisch prices this SKU at fewer than three tiers."
+      },
+      {
+        "key": "unit_fisch_t3",
+        "label": "Fisch tier 3 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Fisch tier 3 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_royal1_t1",
+        "label": "Royal 1 tier 1 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Royal 1 price tier 1, cheapest first. Blank when Royal 1 does not price this SKU."
+      },
+      {
+        "key": "unit_royal1_t1",
+        "label": "Royal 1 tier 1 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Royal 1 tier 1 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_royal1_t2",
+        "label": "Royal 1 tier 2 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Royal 1 price tier 2. Blank when Royal 1 prices this SKU at only one tier."
+      },
+      {
+        "key": "unit_royal1_t2",
+        "label": "Royal 1 tier 2 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Royal 1 tier 2 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_royal1_t3",
+        "label": "Royal 1 tier 3 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Royal 1 price tier 3. Blank when Royal 1 prices this SKU at fewer than three tiers."
+      },
+      {
+        "key": "unit_royal1_t3",
+        "label": "Royal 1 tier 3 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Royal 1 tier 3 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_royal2_t1",
+        "label": "Royal 2 tier 1 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Royal 2 price tier 1, cheapest first. Blank when Royal 2 does not price this SKU."
+      },
+      {
+        "key": "unit_royal2_t1",
+        "label": "Royal 2 tier 1 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Royal 2 tier 1 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_royal2_t2",
+        "label": "Royal 2 tier 2 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Royal 2 price tier 2. Blank when Royal 2 prices this SKU at only one tier."
+      },
+      {
+        "key": "unit_royal2_t2",
+        "label": "Royal 2 tier 2 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Royal 2 tier 2 price. Blank when Odoo names no package."
+      },
+      {
+        "key": "price_royal2_t3",
+        "label": "Royal 2 tier 3 price",
+        "type": "currency",
+        "source": "odoo",
+        "default": false,
+        "description": "Royal 2 price tier 3. Blank when Royal 2 prices this SKU at fewer than three tiers."
+      },
+      {
+        "key": "unit_royal2_t3",
+        "label": "Royal 2 tier 3 unit",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "Package label for the Royal 2 tier 3 price. Blank when Odoo names no package."
+      },
       {
         "key": "pre_book_qty",
         "label": "Pre-book qty",
@@ -444,180 +610,188 @@
       },
       {
         "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": "incoming",
-        "label": "Inbound units",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units already on order and not yet received, from Odoo's own incoming quantity on the product. In the product's STOCK unit of measure, the same unit as On hand, so the two can be added. Days of supply and both cover gap columns all count this as stock (owner, 2026-08-19)."
-      },
-      {
-        "key": "dos",
-        "label": "Days of supply",
-        "type": "int",
-        "source": "odoo",
-        "description": "Days of supply at the trailing twelve month rate, counting ON HAND PLUS INBOUND units as stock; null means it never sells through. Same stock figure as the cover gap columns, so the two cannot disagree about how much you have. They still divide by different rates: this one is the trailing average, the cover gap uses the forward 8 month forecast, so a seasonal SKU reads differently in each. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "cover_gap_d",
-        "label": "Cover gap (days)",
-        "type": "int",
-        "source": "odoo",
-        "default": false,
-        "description": "Days of cover minus supplier lead time. Negative means it runs out before a reorder lands. It counts INBOUND units as stock, exactly as Days of supply now does. The one thing it does differently: the burn rate is the FORWARD 8 month forecast rather than the trailing twelve month average, so a seasonal SKU reads differently here."
-      },
-      {
-        "key": "cover_gap_units",
-        "label": "Cover gap (units)",
-        "type": "int",
-        "source": "odoo",
-        "default": false,
-        "description": "The recommended reorder quantity: units of forecast demand over the lead time that on-hand plus inbound does not cover. POSITIVE means buy this many; negative is surplus units; blank means we cannot say, because the SKU has no lead time on file or no forecast demand. Rounded AWAY from zero, so a real shortfall never rounds down to nothing."
-      },
-      {
-        "key": "demand_fwd",
-        "label": "Forecast units (8 mo)",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units this SKU is expected to sell over the next 8 months, read as the units it actually sold in the same 8 calendar months one year ago. Seasonal on purpose: a flat annual average spreads Valentine's, Mother's Day and Christmas evenly across the year and understates the months buyers actually order for. A SKU too new to appear in that window falls back to its trailing twelve month rate scaled to 8 months. This is the burn rate both cover gap columns divide by, shown so the reorder quantity can be checked."
-      },
-      {
-        "key": "stock_bucket",
-        "label": "Stock status",
-        "type": "select",
-        "source": "odoo",
-        "description": "Dead / excess / healthy bucket, from the same days of supply figure beside it, so it counts inbound units too. One exception on purpose: 'Out of stock' still keys on the REAL shelf, because that is a present tense fact somebody can walk into the warehouse and check. A row can honestly read 'Out of stock' with a days of supply beside it when the replenishment is on the water; Inbound units is why. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "discontinued",
-        "label": "Discontinued",
-        "type": "select",
-        "source": "odoo",
-        "options": [
-          "Yes",
-          "No"
-        ],
-        "description": "Whether Odoo carries the Discontinued product tag on this SKU. Every row gets an explicit Yes or No rather than a blank, because a blank reads as an inactive condition in the filter engine and would silently WIDEN any view that filtered on it."
-      },
-      {
-        "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."
-      }
-    ]
-  }
-}
+        "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": "incoming",
+        "label": "Inbound units",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units already on order and not yet received, from Odoo's own incoming quantity on the product. In the product's STOCK unit of measure, the same unit as On hand, so the two can be added. Days of supply and both cover gap columns all count this as stock (owner, 2026-08-19)."
+      },
+      {
+        "key": "dos",
+        "label": "Days of supply",
+        "type": "int",
+        "source": "odoo",
+        "description": "Days of supply at the trailing twelve month rate, counting ON HAND PLUS INBOUND units as stock. A blank means there is no honest number to print, and Stock status beside it says which of two reasons applies: 'No recent sales' is stock on the shelf that sold nothing in the window, so there is no rate to divide by; 'No stock record' is a product the inventory read returned no row for, so its shelf is unknown rather than empty. A product that sold nothing and holds nothing reads 0, not blank. Same stock figure as the cover gap columns, so the two cannot disagree about how much you have. They still divide by different rates: this one is the trailing average, the cover gap uses the forward 8 month forecast, so a seasonal SKU reads differently in each. A business unit caller gets this column too, re-scoped: the shelf is the whole warehouse's, the rate is that unit's."
+      },
+      {
+        "key": "cover_gap_d",
+        "label": "Cover gap (days)",
+        "type": "int",
+        "source": "odoo",
+        "default": false,
+        "description": "Days of cover minus supplier lead time. Negative means it runs out before a reorder lands. It counts INBOUND units as stock, exactly as Days of supply now does. The one thing it does differently: the burn rate is the FORWARD 8 month forecast rather than the trailing twelve month average, so a seasonal SKU reads differently here."
+      },
+      {
+        "key": "cover_gap_units",
+        "label": "Cover gap (units)",
+        "type": "int",
+        "source": "odoo",
+        "default": false,
+        "description": "The recommended reorder quantity: units of forecast demand over the lead time that on-hand plus inbound does not cover. POSITIVE means buy this many; negative is surplus units; blank means we cannot say, because the SKU has no lead time on file or no forecast demand. Rounded AWAY from zero, so a real shortfall never rounds down to nothing."
+      },
+      {
+        "key": "demand_fwd",
+        "label": "Forecast units (8 mo)",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units this SKU is expected to sell over the next 8 months, read as the units it actually sold in the same 8 calendar months one year ago. Seasonal on purpose: a flat annual average spreads Valentine's, Mother's Day and Christmas evenly across the year and understates the months buyers actually order for. A SKU too new to appear in that window falls back to its trailing twelve month rate scaled to 8 months. This is the burn rate both cover gap columns divide by, shown so the reorder quantity can be checked."
+      },
+      {
+        "key": "stock_bucket",
+        "label": "Stock status",
+        "type": "select",
+        "source": "odoo",
+        "description": "Dead / excess / healthy bucket, from the same days of supply figure beside it, so it counts inbound units too. Two of its values are not coverage bands at all. 'Out of stock' keys on the REAL shelf rather than the inbound-inclusive figure, because that is a present tense fact somebody can walk into the warehouse and check, so a row can honestly read 'Out of stock' with a days of supply beside it when the replenishment is on the water; Inbound units is why. 'No stock record' means the inventory read returned no row for this product, so its shelf is unknown rather than empty: it reads that way for the handful of products carrying no SKU code, and for every row at once if an inventory read fails, which is the case where a blank Days of supply is an outage rather than a slow seller. A business unit caller gets this column too, re-scoped through that unit's own sales rate."
+      },
+      {
+        "key": "discontinued",
+        "label": "Discontinued",
+        "type": "select",
+        "source": "odoo",
+        "options": [
+          "Yes",
+          "No"
+        ],
+        "description": "Whether Odoo carries the Discontinued product tag on this SKU. Every row gets an explicit Yes or No rather than a blank, because a blank reads as an inactive condition in the filter engine and would silently WIDEN any view that filtered on it."
+      },
+      {
+        "key": "created_on",
+        "label": "Record created",
+        "type": "date",
+        "source": "odoo",
+        "default": false,
+        "description": "The date this product record was created in Odoo. Read from the live product.product create_date: the mirror carries write_date and no create_date, so there is no cheaper source. A SKU whose code is on more than one active record takes the EARLIEST of them, because the row is the SKU and that is when it first existed."
+      },
+      {
+        "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/data_binding.py

@@ -263,9 +263,34 @@ def describe(repo=None):
 
     ⚠ Carries no secret: a Space id and a dataset repo id are public names. The DATA is not, and
     none of it is here. The field is session-gated anyway (see `routes_admin.settings`).
+
+    ⭐⭐ W40-T13 (D-333) — IT ALSO NAMES THE STORE BACKEND, WHICH IS THE OTHER HALF OF THE SAME
+    QUESTION AND THE HALF THAT WENT MISSING. `repo` answers "WHICH STORE am I bound to"; after the
+    Postgres cutover the sharper question is "am I READING that store from HF or from Neon", and
+    the payload could not answer it at all. W36-T62's `done-when` said *"/settings reports the pg
+    backend"* and was therefore unmeasurable, which is how a whole cutover shipped with the
+    verification clause pointed at a field that did not exist. It exists now.
     """
     rid = str(repo or '').strip()
+    # ⛔⛔ THE IMPORT IS FUNCTION-LOCAL AND MUST STAY THAT WAY. `core/store.py` imports THIS module
+    # at its own module scope, so pulling `core.store` up to the top of this file is a hard import
+    # cycle that kills the app at boot rather than at a test. Do not "tidy" it upward.
+    #
+    # ⛔ AND AN UNRECOGNISED BACKEND REPORTS `unknown`, NEVER `hf`. `store.backend()` RAISES on a
+    # value it does not know, and this function is called from `routes_admin::_store_binding`
+    # inside a bare `except` whose fallback dict has no `backend` key at all — so a raise here
+    # would delete the field from the payload on exactly the deployment that most needs it. And
+    # defaulting to `hf` would be worse than raising: a misconfigured container would report the
+    # store it is NOT reading, which is the guess this field exists to replace. ImportError rides
+    # the same branch for the same reason: an honest "I could not tell" beats a confident wrong
+    # answer on a surface nobody can inspect from outside (D-160).
+    try:
+        import core.store as store                                # noqa: PLC0415 — cycle, see above
+        store_backend = store.backend()
+    except (RuntimeError, ImportError):
+        store_backend = 'unknown'
     return {
+        'backend': store_backend,
         'deployment': deployment_id(),
         'production': is_production_deployment(),
         'repo': rid,

platform/core/field_permissions.py

@@ -58,6 +58,161 @@ def grant_entries(permissions):
     return []
 
 
+def permissions_from_grants(entries):
+    """⭐⭐ W40-T03 / CONTRACT C4 — THE CLASSIFICATION IS DERIVED FROM THE REGISTRY, NEVER STAMPED.
+
+    Owner instruction 21 (2026-08-23): *"A Field shared with only Karen Ganley shows under Hide
+    Fields as 'Shared with everyone' — it should be 'Shared with me'. Fix the logic. By default
+    every Field created is private until it is shared."*
+
+    The registry (`core/shares.py`) already knows exactly who a column is shared with; the
+    `permissions` bag on the definition is only the WORD the client sections on
+    (`FieldsHidePanel` buckets by `types.fieldEditMode`). Until now those two could disagree,
+    because `promote_field` stamped the bag from a hardcoded fallback BEFORE the request's own
+    grant entries were written. This function is the single place the bag is derived from the
+    grants, so the word on screen and the wall in the registry answer the same question.
+
+    ⛔ CLASSIFICATION IS ABOUT **WHO**, NOT ABOUT **ROLE**, and that is C4's wording rather than an
+    approximation: *"'Shared with me' means grants naming me"*. A `view`-role grantee is a person
+    the column is shared with exactly as an `edit`-role one is, so both count. The role itself is
+    NOT recoverable from this bag and is not meant to be — `shares.role_for` is what answers "may
+    this account change it", on every path that asks (see the four short-circuits named on
+    `reconcile_shared_permissions`).
+
+    ⛔ THE WILDCARD WINS, AND THE NAMED USERS ARE DISCARDED. `*` plus named users is still "shared
+    with everyone" on screen, because everyone can already reach it; carrying the named few
+    alongside would produce a bag that says `users` while the registry admits the room. Discarding
+    them is safe precisely because this bag is not a wall for a shared field: `role_for` keeps the
+    stronger of an everyone-grant and a personal one, so a named user's raised role survives in
+    the registry where it is actually read.
+
+    ⛔ `known_users` IS DELIBERATELY NOT PASSED, HERE OR BY ANY CALLER ON THIS PATH.
+    `clean_permissions` collapses to `{'edit': 'personal'}` when the filtered users list ends up
+    empty, so ONE grantee missing from the user registry would silently reflip a shared column to
+    Private — the owner's defect in the other direction, and just as invisible. `put_share` has
+    already validated every grantee through `_entries_or_400` before the grant is stored, so the
+    filter would only ever fire on a name that door already accepted.
+
+    ⚠ THE USERS LIST IS SORTED, AND THAT IS WHAT MAKES THE RECONCILE IDEMPOTENT rather than merely
+    convergent. `shares._clean_entries` preserves stored insertion order, so two grant sets holding
+    the same people in a different order would otherwise derive two different-but-equal bags and
+    rewrite each other forever on alternating reads (the D-358 egress class).
+    """
+    users = []
+    seen = set()
+    for entry in entries or ():
+        if not isinstance(entry, dict):
+            continue
+        user = str(entry.get("user") or "").strip().lower()
+        if not user or user in seen:
+            continue
+        seen.add(user)
+        if user == shares.EVERYONE:
+            return clean_permissions({"edit": "collaborative"})
+        users.append(user)
+    if not users:
+        return clean_permissions({"edit": "personal"})
+    return clean_permissions({"edit": "users", "users": sorted(users)})
+
+
+def _same_classification(left, right):
+    """Do two canonical bags say the same thing about WHO?
+
+    ⚠ THE USERS LIST IS COMPARED AS A SET, not as a sequence, and that is a write-count decision
+    rather than a nicety. A stored bag minted before the sort above carries the registry's
+    insertion order; comparing sequences would rewrite every such column once for a change no
+    reader can see. `shared_overlay.put_field` is a `flush='sync'` store commit per field, so a
+    difference nobody can observe must not cost one.
+    """
+    if left.get("edit") != right.get("edit"):
+        return False
+    return set(left.get("users") or ()) == set(right.get("users") or ())
+
+
+def reconcile_shared_permissions(shared_key, grant_topic, st=None):
+    """Re-derive every SHARED definition's `permissions` bag from the grant registry. Returns the
+    number of definitions actually rewritten.
+
+    ⭐⭐ THIS IS A **WRITE ON A READ PATH**, ON A TENANT-WIDE STRATUM, AND IT IS DELIBERATE.
+    `routes_customers.py`'s `ROUTE_KIND` comment argues the opposite case for route columns
+    (*"Backfilling every stored route definition on a read is a write nobody asked for, on a
+    tenant-wide stratum, triggered by opening a page"*) and settles it with "re-solving is one
+    click and it is the click the owner is already making". A SHARED FIELD HAS NO SUCH CLICK: the
+    owner's "Fisch Main Catalog" was shared once, months ago, and nothing will ever rewrite its
+    definition again. Leaving it to a future re-share is leaving it wrong forever. C4 also makes
+    the registry AUTHORITATIVE, which a stamp that is never re-derived cannot be. This function is
+    called from `migrate_legacy_fields`, which is already exactly such a pass — it runs
+    `flush='sync'` promotions on the same three read paths — so this adds a kind of write to a
+    door that already makes them, not a new door.
+
+    ⛔ ONLY THE SHARED STRATUM, CHECKED ON `shared`/`granted`. On a PER-USER private field the bag
+    IS the wall and re-deriving it would move a permission. On a shared one it is not, and that is
+    checked rather than reasoned — all four consumers short-circuit on the share marks BEFORE they
+    ever read the bag: `grid_events._may_edit_field_definition` and `::_may_edit_field_value` both
+    take `_field_share_role` on `definition.get('shared') or definition.get('granted')`;
+    `types.mayEditField` and `types.mayEditFieldDefinition` take the same branch in the same order
+    on the client; and `perm_scope.field_grant_hidden` keys off `FIELD_GRANT_MARK` plus
+    `shares.role_for` and never reads the bag at all. Nothing on this path is a permission
+    decision. This is the same fact the `ROUTE_KIND` comment states of its own change: *"AND IT
+    MOVES NO WALL, CHECKED RATHER THAN REASONED."*
+
+    ⛔ NO GRANT RECORD AT ALL MEANS **LEAVE IT ALONE**, and the distinction is why `shares.grants`
+    returning an owner with zero entries is a different answer from returning neither. A record
+    with an owner and no entries is a column somebody has managed and shared with nobody: that is
+    `personal`, positively. A column the registry has never heard of is a column this function
+    knows nothing about, and inventing a classification for it would be guessing in the direction
+    of a visible change.
+
+    ⚠ ONE `put_field` PER CHANGED DEFINITION, and the bound is what makes that acceptable. Only a
+    definition whose stored bag DISAGREES with its grants is rewritten, which in practice is the
+    handful first shared before this derivation existed; steady state is zero writes, proven by
+    the idempotence leg of the harness. `shared_overlay.put_rows`' docstring carries this repo's
+    measured scar for the opposite shape (*"18 writes against one document under the store's
+    coalescing single-flight landed ZERO while answering 200 eighteen times"*), so if a corpus ever
+    makes this pass write in bulk it must become ONE batched write rather than a loop.
+    """
+    bucket = str(shared_key or "").strip()
+    grant_key = str(grant_topic or bucket).strip()
+    if not bucket or st is None:
+        return 0
+    rewritten = 0
+    for field_key, defn in list(shared_overlay.fields(bucket, st=st).items()):
+        # ⚠ EACH DEFINITION IS GUARDED ON ITS OWN. `shares.field_oid` RAISES on an empty key, and
+        # the caller wraps this whole function in one swallowing except — so a single malformed
+        # entry would otherwise skip every REMAINING column, including the one the owner reported,
+        # and report as "nothing to reclassify" with no failure anywhere near the cause.
+        try:
+            if not isinstance(defn, dict):
+                continue
+            if not (defn.get("shared") or defn.get("granted")):
+                continue
+            key = str(field_key or "").strip()
+            if not key:
+                continue
+            record = shares.grants("field", shares.field_oid(grant_key, key), st=st)
+            if not record.get("owner") and not record.get("entries"):
+                continue
+            derived = permissions_from_grants(record.get("entries"))
+            stored = defn.get("permissions")
+            # ⛔ A MISSING BAG IS ALWAYS A DIFFERENCE, EVEN WHEN THE DERIVATION SAYS `personal`.
+            # This is the leg that decides whether the fix is visible at all. The client's own
+            # fallback is `"collaborative"` (`types.cleanFieldPermissions(field.permissions,
+            # "collaborative")`), so a definition carrying NO bag renders as "Shared with
+            # everyone" no matter what the registry says. Comparing canonicalised values would
+            # find `personal == personal` and write nothing, and the column would keep reading
+            # "Shared with everyone" forever. The server must emit an EXPLICIT bag on every
+            # shared definition; absence is not a value the wire can carry.
+            if isinstance(stored, dict) and _same_classification(clean_permissions(stored), derived):
+                continue
+            updated = dict(defn)
+            updated["permissions"] = derived
+            shared_overlay.put_field(bucket, key, updated, st=st)
+            rewritten += 1
+        except Exception:
+            continue
+    return rewritten
+
+
 def _field_is_migratable(field):
     return (isinstance(field, dict) and field.get("custom") is True
             and field.get("source") == "overlay")
@@ -74,13 +229,34 @@ def migrate_legacy_fields(table_key, st=None, known_users=None, grant_topic=None
     grant_key = str(grant_topic or key).strip()
     shared_key = str(shared_key or key).strip()
     if not key or st is None:
-        return {"promoted": 0, "normalized": 0}
+        return {"promoted": 0, "normalized": 0, "reclassified": 0}
+    # ⭐⭐ W40-T03 — RECONCILE THE SHARED STRATUM'S CLASSIFICATION FIRST, IN ITS OWN SWALLOWING
+    # GUARD. This is the ONE seam that reaches every shared-field surface: all three readers
+    # (`routes_customers.shared_fields`, `routes_tables._ut_shared_fields`,
+    # `product_data`) already call this function with the right keys and read the definitions
+    # immediately afterwards, so a reconcile that writes into the shared overlay is picked up by
+    # that same read.
+    #
+    # ⛔ THE GUARD IS NOT DEFENSIVENESS, IT IS A BLAST RADIUS. `routes_customers.shared_fields`
+    # wraps its whole call in a `try/except` that degrades to `{}` — i.e. a raise in here would
+    # blank EVERY shared column on the customer grid and read as "nothing is shared yet". A
+    # classification that fails must leave the previous word on screen, never the page empty.
+    #
+    # ⚠ THE TWO KEYS ARE DIFFERENT STRINGS AND THE ORDER MATTERS. `shared_key` names the BUCKET
+    # (`product_table_workspace__shared`); `grant_key` names the registry TOPIC
+    # (`product_data:<field>`). For the product topic they are not the same value. Swapping them
+    # finds no grant record, the "no record" arm fires for every column, and the reconcile
+    # silently does nothing at all.
+    try:
+        reclassified = reconcile_shared_permissions(shared_key, grant_key, st=st)
+    except Exception:
+        reclassified = 0
     try:
         document = st.get(key) or {}
     except Exception:
-        return {"promoted": 0, "normalized": 0}
+        return {"promoted": 0, "normalized": 0, "reclassified": reclassified}
     if not isinstance(document, dict):
-        return {"promoted": 0, "normalized": 0}
+        return {"promoted": 0, "normalized": 0, "reclassified": reclassified}
 
     promoted = 0
     normalized = 0
@@ -151,7 +327,10 @@ def migrate_legacy_fields(table_key, st=None, known_users=None, grant_topic=None
                                 values.pop(field_key, None)
                 return data
         st.update(key, _remove, flush="sync")
-    return {"promoted": promoted, "normalized": normalized}
+    # ⛔ `promoted` AND `normalized` KEEP THEIR NAMES AND THEIR MEANINGS.
+    # `aios-web/api/verify_field_permissions.py` asserts `result["promoted"] == 1`; renaming or
+    # folding either into the new count would turn a green gate red for a change it never made.
+    return {"promoted": promoted, "normalized": normalized, "reclassified": reclassified}
 
 
 def promote_field(workspace_key, shared_key, grant_topic, owner, field, st=None):
@@ -162,7 +341,36 @@ def promote_field(workspace_key, shared_key, grant_topic, owner, field, st=None)
         return dict(field)
     shared = dict(field)
     shared.update({"shared": True, "granted": True, "source": "overlay", "custom": True})
-    permissions = stored_permissions(shared, fallback="collaborative")
+    # ⭐⭐ W40-T03 / OWNER INSTRUCTION 21 — THE FALLBACK IS `personal`, AND IT IS THE ROOT CAUSE.
+    #
+    # Owner: *"By default every Field created is private until it is shared."*
+    #
+    # ⛔ THE BUG WAS AN ORDERING ONE, WHICH IS WHY IT LOOKED LIKE THE OPPOSITE OF ITSELF.
+    # `routes_shares.put_share` promotes FIRST and writes the request's own grant entries one line
+    # LATER, so on a first share this function cannot see who the field is being shared with. With
+    # `fallback="collaborative"` it therefore stamped `{'edit': 'collaborative'}` on EVERY first
+    # share — Karen-only included — and the bag was never re-derived afterwards. `set_grants`
+    # immediately replaced the transient `*` grant with Karen's, so the WALL was right the whole
+    # time; the permanent lie was the WORD, and the word is what the owner reads under Hide fields.
+    #
+    # ⛔ AN EXPLICIT BAG STILL WINS, AND THAT IS WHAT KEEPS THE OTHER CALLER BYTE-IDENTICAL.
+    # `grid_events.field_upsert` (the field editor's permission picker) sets
+    # `field['permissions']` in BOTH arms of its `may_change_permissions` branch before calling
+    # this, and only reaches it when that bag already says `collaborative` or `users`. The
+    # fallback is never consulted there, so this line moves nothing on that path.
+    #
+    # ⚠ THE CALL SITE CHANGES, NOT `stored_permissions`' OWN DEFAULT. That default answers a
+    # different question — *"what did an old field, written before this vocabulary existed,
+    # mean?"* — and `migrate_legacy_fields` still needs the old answer for its LEGACY promotion
+    # leg, which `verify_field_permissions.py` asserts to the letter.
+    #
+    # ⚠ `set_grants` BELOW IS LEFT IN PLACE. With `personal` it writes `[]` plus an owner, which is
+    # the shape `routes_customers.py`'s route claim states in full: *"the empty entry list is the
+    # point. `set_grants` keeps a record with an owner and no entries, so 'shared with nobody' is
+    # STORED and is a different fact from 'never shared'."* `reconcile_shared_permissions` reads
+    # exactly that difference, so dropping the call would make a freshly promoted column
+    # unclassifiable rather than private.
+    permissions = stored_permissions(shared, fallback="personal")
     shared["permissions"] = permissions
     shared["createdBy"] = str(shared.get("createdBy") or owner).strip().lower()
     shared_overlay.put_field(shared_key, key, shared, st=st)

platform/core/grid_events.py

@@ -420,6 +420,92 @@ def _docs_key(ctx):
 
 
 # ------------------------------------------------------------------ the workspace family (X1 amd.)
+def _grant_marker(ctx, ws):
+    """`has_grants(view_id) -> bool` for this tenant, or None when nothing here is granted at all.
+
+    ⭐⭐ ONE PREDICATE, THREE MERGE LEGS — W40-T01, owner instruction 2, contract C1.
+    `table_workspace` assembles its `views` from three sources (granted / `__shared__` bucket /
+    the caller's own stratum) and a share mark has to mean the SAME thing on all three, or the
+    client is back to branching on who is looking. So the rule lives here once and the registry is
+    read ONCE per workspace read; a closure rather than three calls, because `granted_oids` exists
+    precisely to stop this becoming N reads of the whole grant bucket per rail.
+
+    ⭐⭐ THE ASYMMETRY THIS CLOSES. Owner, verbatim: *"A shared View must show the
+    shared/collaborative icon in EVERY account, not only the recipient's."* Contract C1 states the
+    meaning that makes that true: **`shared` on a view means "this view has grants", not "granted
+    to me"**. The receiver's copy has been stamped since wave 21 (`_granted_views`); the SHARER's
+    copy never was and structurally could not be, because `_granted_views` and `shared_views` both
+    EXCLUDE what the caller owns by design — so the person who did the sharing is the one person
+    the old projection could never tell.
+
+    "Carries a grant" is EITHER of two things, and the folder leg is not optional: a receiver
+    already gets `shared` stamped through `_granted_views`' folder pass (D-37), so answering only
+    the direct-view half here would re-create exactly the asymmetry instruction 2 reports, one
+    level down.
+
+    ⛔ THE SOURCE IS THE R10 GRANT REGISTRY ONLY (`core/shares.py`), AND THE NARROWING IS
+    DELIBERATE — not an oversight for the next reader to "fix". `routes_shares.py`'s own module
+    docstring warns that TWO SYSTEMS answer "is this shared" and they are not the same one (audit
+    S-4): the other is the legacy `__shared__` bucket (`permissions.edit in ('collaborative',
+    'users')`). BUCKET MEMBERSHIP IS NOT A GRANT. A view living in that bucket is asked the same
+    question as any other — does the REGISTRY hold an entry for it — so a `collaborative` view
+    nobody ever granted carries no mark, and that stays booked rather than fixed here: marking it
+    would additionally need an `owner` stamp on that leg to keep the tooltip honest, which is a
+    copy change on a client file outside this ticket.
+
+    ⚠ WHICH IS WHY THE `__shared__` LEG STILL NEEDS ASKING, and it is the corner the own-views
+    leg cannot reach. `save_view` moves a `collaborative`/`users` view OUT of the creator's
+    personal stratum, so its OWNER has no copy in `ws['views']` at all; and `merged.update(shared)`
+    outranks the stamped `granted` copy, so a receiver's mark would be overwritten on the way
+    through. Both are answered by asking this predicate on that leg too. ⛔ The merge PRECEDENCE
+    is untouched — "the everyone-bucket outranks a grant" is deliberate and is not this ticket's
+    to reverse; the fix stamps the copy that wins, it does not re-arbitrate which copy wins.
+
+    ⚠ MEMBERSHIP OF THE ID IS THE WHOLE TEST, and there is one known false positive it cannot
+    see: a PINNED PER-USER id (`all-customers`, `tpl_overview`) exists once per user, so a grant
+    recorded against that id by anybody would mark every user's own copy. That is the same
+    first-match hazard `handle_one` documents at the foreign-view wall (W33-T13). It is decoration
+    on a view nobody shared, never a widening — and `granted_oids` cannot answer "whose" without
+    becoming the N-reads-per-rail shape it exists to avoid. Booked, not papered over.
+
+    ⚠ NO `createdBy` FILTER, on any leg. Ownership is not what this answers — "has grants" is a
+    property of the VIEW, which is the whole of C1 — and re-filtering on `createdBy` would drop
+    the mark off any record whose copy of it is absent or stale, the same class of trap that keeps
+    `scope_view` off the own-views leg. WHO is sharing is answered separately, by `sharedOut`.
+
+    ⚠ THE FOLDER MAP IS THE CALLER'S OWN `itemFolders`, which is the only placement map this read
+    has in hand. That is exact for the own-views leg. For a `__shared__` view it answers the
+    caller's own filing of it, and a folder grant on somebody else's folder cannot reach a view
+    in that bucket anyway (`find_folder` reads the owner's personal stratum, which a shared view
+    has already left) — so the direct-view half is what carries that leg in practice.
+    """
+    import core.shares as shares
+    # The SAME store handle `_granted_views` resolves, and asked for the same reason: the grants
+    # bucket is tenant-scoped and must be read out of the tenant whose workspace this is. Written
+    # as `_tops(ctx).st` rather than `_store_of(ctx)` so the two legs cannot drift on tenancy.
+    st = getattr(_tops(ctx), 'st', None)
+    view_oids = shares.granted_oids('view', st=st)
+    folder_oids = shares.granted_oids('folder', st=st)
+    if not view_oids and not folder_oids:
+        return None                       # nothing in this tenant is granted: no marks, no closure
+    # ⚠ `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, …}`) — reading item
+    # ids off the top level finds the surface NAMES and matches nothing, which is the same trap
+    # `table_store.find_folder` carries a note about. It is already in the payload above, so the
+    # folder leg costs no extra store read.
+    placed = (ws.get('itemFolders') or {}).get('views') or {}
+
+    def _has_grants(view_id):
+        key = str(view_id)
+        if key in view_oids:
+            return True
+        fid = str(placed.get(key) or '')
+        # `fid` truthiness FIRST: '' must never match a grant stored under the empty-string oid,
+        # which would mark every unfiled view at once.
+        return bool(fid and fid in folder_oids)
+
+    return _has_grants
+
+
 def table_workspace(ctx, allowed_pids=None, consume_corrections=True):
     """Durable Airtable-style view/schema/overlay state, with an honest session fallback.
 
@@ -427,6 +513,11 @@ def table_workspace(ctx, allowed_pids=None, consume_corrections=True):
     with them. Own views win a same-id collision — a personal view is the user's own object and
     must never be shadowed by somebody else's share.
 
+    ⭐ W40-T01 (owner instruction 2, contract C1): every view that HAS grants carries
+    `hasShares: True` whoever is asking, and the copy belonging to the account doing the sharing
+    additionally carries `sharedOut: True`. Stamped on ALL THREE merge legs from ONE predicate
+    (`_grant_marker`), on the PROJECTION only, and never written back.
+
     ⚠ `allowed_pids` is a SECURITY parameter, not a convenience. A shared view carries
     `memberPids`, which the writer's scope validated on the way IN — but the READER may have a
     narrower scope. Handing a Fisch-scoped user a view whose member list was built by a
@@ -457,6 +548,69 @@ def table_workspace(ctx, allowed_pids=None, consume_corrections=True):
         except Exception as _ge:
             _tel.error('sharedviews:granted', _ge)
             granted = {}
+        # ⭐⭐ W40-T01 / OWNER INSTRUCTION 2 / CONTRACT C1 — THE SHARE MARKS, ON THE TWO LEGS THAT
+        # ARRIVE UNSTAMPED. `granted` was already stamped by `_granted_views`; these two were not.
+        # ⛔ AND THIS SITS OUTSIDE THE `if shared or granted:` GUARD BELOW, deliberately. Four
+        # traps, all measured, each of which makes the "obvious" placement silently do nothing:
+        #
+        #   ⛔ 1. THAT GUARD IS UNREACHABLE FOR THIS TICKET'S CASE. For the exact fixture the
+        #      owner reports — I own a view, I shared it OUT, nothing is shared TO me — BOTH
+        #      `shared` and `granted` are empty (`shared_views` and `_granted_views` each exclude
+        #      what the caller owns, and a new view defaults to `permissions.edit='personal'` so
+        #      it is not in the `__shared__` bucket either). The whole block is SKIPPED and
+        #      `ws['views']` returns raw. Stamping "on the legs of the merge" is therefore not
+        #      enough: the sharer's leg has to run unconditionally or it never runs at all.
+        #
+        #   ⛔ 2. DO NOT ROUTE THESE THROUGH `scope_view`. Today own views only reach it when the
+        #      caller has shares; make the comprehension unconditional and an own view whose
+        #      `createdBy` is absent or mismatched starts being re-scoped, and `scope_view` with
+        #      `allowed_pids=None` sets `memberPids: []` — the list, wiped, on the user's OWN view.
+        #      Stamp beside that path, never into it. The granted/shared legs keep re-scoping
+        #      exactly as before, and `scope_view` copies (`out = dict(view)`) so the stamps ride.
+        #
+        #   ⛔ 3. `table_store.workspace()` RETURNS A SHALLOW COPY: the outer dict is fresh but each
+        #      view VALUE is a live reference into the cached store document. Mutating one in place
+        #      would poison the cache every other reader shares and could be written back. So a
+        #      marked view is REPLACED with a copy; unmarked ones stay the same references they
+        #      were, and nothing here is ever persisted (the `view_upsert` save path builds its
+        #      record from a fixed key whitelist, so these stamps cannot survive a round trip).
+        #      The `shared` leg is copied at the stamp for the same reason, rather than trusting
+        #      `shared_views`' own `dict(v)` from a distance.
+        #
+        #   ⛔ 4. THE `__shared__` LEG IS NOT OPTIONAL, and it is the corner leg 1 cannot reach.
+        #      `merged.update(shared)` below OUTRANKS the stamped `granted` copy, so a receiver's
+        #      mark would be overwritten on the way through; and the OWNER of such a view has no
+        #      copy in `ws['views']` at all, because `save_view` moves a collaborative/users view
+        #      OUT of the personal stratum. Unmarked in EVERY account: instruction 2's exact
+        #      defect, one corner over. ⛔ The merge PRECEDENCE is untouched — stamping the copy
+        #      that wins is not re-arbitrating which copy wins.
+        #
+        # `hasShares` is the marker, NOT `shared`: the client reads `view.shared` as "granted to
+        # ME" in two live places (it gates `mayEditView` and it groups the "Shared with me"
+        # section), so re-using that key would take the owner's own view away from them.
+        # `sharedOut` says WHO is doing the sharing — always true on the caller's own stratum, and
+        # on the `__shared__` leg only when the record's `createdBy` is this caller. It is what
+        # lets the client word the owner's tooltip as sharing OUT rather than re-using the
+        # receiver-worded copy, which C1 forbids.
+        # Absence is the negative: an unmarked view is left alone rather than stamped False.
+        try:
+            _has_grants = _grant_marker(ctx, ws) if (ws.get('views') or shared) else None
+        except Exception as _me:
+            # A share mark is DECORATION. It must never be the thing that takes down a workspace
+            # read, so it fails the way its two siblings above do: log and carry on unmarked.
+            _tel.error('sharedviews:marks', _me)
+            _has_grants = None
+        if _has_grants:
+            ws['views'] = {
+                vid: ({**v, 'hasShares': True, 'sharedOut': True}
+                      if isinstance(v, dict) and _has_grants(vid) else v)
+                for vid, v in (ws.get('views') or {}).items()}
+            if shared:
+                shared = {
+                    vid: ({**v, 'hasShares': True,
+                           **({'sharedOut': True} if v.get('createdBy') == uname else {})}
+                          if isinstance(v, dict) and _has_grants(vid) else v)
+                    for vid, v in shared.items()}
         if shared or granted:
             merged = dict(granted)
             merged.update(shared)                       # the everyone-bucket outranks a grant
@@ -478,9 +632,16 @@ def _granted_views(ctx, uname):
     The R10 registry stores bare ids, tenant-scoped through the SAME store handle this topic's
     bucket uses; the record itself is fetched out of the OWNER's personal stratum of THIS
     bucket. An id granted on another topic simply finds nothing here and contributes nothing
-    (fail-closed). Each projected view is stamped `shared` / `sharedRole` / `owner` so the
-    client can synthesise the "Shared with me" group and disable edit affordances for
+    (fail-closed). Each projected view is stamped `shared` / `sharedRole` / `owner` / `hasShares`
+    so the client can synthesise the "Shared with me" group and disable edit affordances for
     role=view — the stamps live on the PROJECTION only, never written back to the store.
+    `hasShares` (W40-T01, contract C1) is the viewer-INDEPENDENT one: `shared` still means
+    "granted to me" and only ever appears here, while `hasShares` means "this view has grants"
+    and is stamped on ALL THREE of `table_workspace`'s merge legs — this one, the caller's own
+    stratum, and the `__shared__` bucket — from the single predicate `_grant_marker`.
+    ⚠ A view in BOTH this projection and the `__shared__` bucket keeps the bucket's copy, because
+    `merged.update(shared)` outranks it there; that copy is stamped on its own leg, which is why
+    stamping here is not sufficient on its own.
     `role_for` is asked with is_admin=False deliberately: the stamp reports the GRANT (the
     registry listed only explicit entries), not the caller's rank.
     """
@@ -503,6 +664,12 @@ def _granted_views(ctx, uname):
         v['shared'] = True
         v['sharedRole'] = role
         v['owner'] = owner
+        # ⭐ W40-T01 (C1): the RECEIVER's half of the one marker both sides now carry. `shared`
+        # keeps its old meaning here — "granted to ME" — because the client still reads it that
+        # way; `hasShares` is the viewer-independent fact underneath it, and stamping it on this
+        # leg too is what lets the client draw ONE mark from ONE key instead of branching on who
+        # is looking. No `sharedOut`: this account is not the one sharing it.
+        v['hasShares'] = True
         out[str(vid)] = v
 
     # ⭐ D-37 (2026-08-05) — THE FOLDER LEG. W20's R10 said "a folder share = its views ride
@@ -537,6 +704,8 @@ def _granted_views(ctx, uname):
             v['shared'] = True
             v['sharedRole'] = role
             v['owner'] = owner
+            v['hasShares'] = True         # W40-T01 (C1) — the folder pass carries it too, or a
+                                          # folder share would still be marked on one side only
             # The folder's NAME rides so the client can group these together later; today it
             # renders in the same "Shared with me" group the view leg feeds. Stamps live on the
             # PROJECTION only and are never written back, exactly as above.

platform/core/shares.py

@@ -1,296 +1,414 @@
-"""core/shares.py — ONE grant registry for every shareable object (wave 20, owner ruling R10).
-
-WHAT R10 ASKED FOR: folders and databases share with the **same two-role vocabulary views
-already use** (specific users or everyone; role = view | edit), plus one manage-access editor
-that can add or revoke people later, on any of the three.
-
-WHY A REGISTRY RATHER THAN A FIELD ON EACH OBJECT. A view already carries its own `permissions`
-(`core/table_store.py`) and that stays — moving it would rewrite every stored view for no gain.
-But a FOLDER is a value inside one user's workspace blob and a DATABASE is a `user_tables`
-definition; giving each its own grant field would put the same three-line permission decision in
-three files owned by two sessions, which is how the three drift. One registry, one predicate,
-three callers.
-
-    shares.set_grants(kind, oid, entries, owner=…, st=…)   # replaces the whole grant set
-    shares.grants(kind, oid, st=…)                         # -> {'owner': str, 'entries': [...]}
-    shares.role_for(kind, oid, user, is_admin=…, st=…)     # -> 'owner'|'edit'|'view'|None
-    shares.shared_with(user, kind=…, st=…)                 # -> [oid] this user was granted
-
-THE ROLE VOCABULARY IS TWO WORDS AND THE DEFAULT IS THE NARROW ONE. `view` = may open and read;
-`edit` = may also change the object's CONTENT. Neither ever means "may re-share": changing grants
-is the OWNER's (or an admin's), which is `table_store._may_administer`'s existing rule promoted to
-every kind. A collaborator who could rewrite grants could grant themselves sole ownership of
-somebody else's object, or quietly widen a users-scoped share to everyone.
-
-⛔ AN UNREADABLE GRANT IS NO GRANT. Every path here fails closed — junk in the bucket, a missing
-owner, an unknown role string all resolve to None rather than to a default that opens something.
-[[aios-permissioning]]: no fail-open defaults, ever.
-
-⚠ THE BUCKET IS TENANT-SCOPED THROUGH `st`, like every other product-data write. Passing the
-session's `TenantRuntime` is what keeps Nurilab's grants in Nurilab's store; the module default
-(`core.store`) is tenant #0 and exists for the same reason it does everywhere else — the ~28
-callers that predate multi-tenancy. (This is the D-5/D-16 residency shape, and this module does
-NOT repeat their mistake: `st` is threaded from the first line rather than retrofitted.)
-"""
-import core.store as store
-
-#: The store key. One bucket per tenant holds every kind's grants, because "what am I shared on"
-#: is a question across kinds — the "Shared with me" folder (R10) is exactly that query, and
-#: three separate buckets would make it three reads that can disagree about what a user can see.
-SHARES_KEY = 'object_shares'
-
-#: The shareable kinds. A CLOSED vocabulary: an unknown kind raises rather than creating a new
-#: namespace by typo, which would silently grant nothing to nobody and read as "sharing is broken".
-#:
-#: ⭐⭐ W38-T16 — `field` IS THE FOURTH, AND NOTHING IN THIS FILE BRANCHES ON IT. Every function
-#: below treats `kind` as an opaque bucket key (`_check_kind / grants / set_grants / role_for /
-#: may_see / may_edit / may_administer / shared_with / drop_objects`), so the kind's whole cost
-#: here is this tuple member. That is the point of one registry: the new object's WALL is written
-#: once in `core.perm_scope`, and its DOORS once in `routes_shares.py` — never a fourth
-#: permission decision in a fourth file ([[one-evaluator-per-question]]).
-KINDS = ('view', 'folder', 'database', 'field')
-
-#: `*` is "everyone who can already open the surface". It is NOT "every account on the platform".
-#: Spelled as a single character so it can never collide with a username (usernames are lower-case
-#: and non-empty by `core/users.py`, and are checked against this explicitly below).
-#:
-#: ⛔⛔ **AND WHAT THAT MEANS DEPENDS ON THE KIND — THE LINE THIS NOTE USED TO CARRY WAS FALSE FOR
-#: ONE OF THE THREE** (W33-T30, `waves/wave32/sharing-audit.md` S-8). It read *"the module/table
-#: wall runs FIRST and this never widens past it"*, flatly, and the audit's own words for that are
-#: *"the third docstring in this audit describing a check that is not on the path"*. Corrected
-#: here rather than deleted, because the sentence is TRUE of two kinds and the difference is the
-#: whole point:
-#:   * `kind='view'` / `kind='folder'` on a GOVERNED module (`customer_data`, `product_data`) —
-#:     the sentence holds. `require_session` plus the topic's own gate run first, and the
-#:     receiver's row scope and hidden-field closure are applied BEFORE any foreign view is
-#:     merged, so a grant can only narrow-or-equal what that account could already reach.
-#:   * `kind='database'` on a `ut_*` table — ⭐⭐ **THE SENTENCE HOLDS HERE TOO NOW, AND THAT IS
-#:     W36-T21 / OWNER RULING R6 (audit S-8, CLOSED).** It did not until wave 36, and the reason
-#:     is worth keeping: `routes_admin._clean_perms` 400'd any key outside
-#:     `("customer_data", "product_data")`, so no row filter and no hidden field could even be
-#:     DECLARED for a user table, `routes_tables.py` made zero `perm_scope` calls, and it passed
-#:     `hidden_keys=frozenset()`. A `database` grant was therefore ALL-OR-NOTHING — every row,
-#:     every column — and this registry was the only wall behind it.
-#:
-#: ⭐ WHAT CHANGED: `perm_scope.scoped_table` (contract C1) is the ONE door to any database's
-#: rows. `routes_tables` applies the permanent filter before `pids` is taken and the transitive
-#: hidden-field closure after `workspace_wire`, on EVERY `ut_*` read — the same code that walls
-#: `customer_data` — and a door that cannot apply them REFUSES rather than serving the lot. So a
-#: `database` grant is once again bounded by a second wall: it decides WHETHER an account reaches
-#: the database, and C1 decides WHICH rows and columns it then sees. An `*` grant still admits
-#: every account in the tenant, and each of them still only sees what their own wall allows.
-#:
-#: ⚠ `routes_shares.py`'s module docstring carries the OLD sentence at the other door and is in
-#: no wave-36 fence — the audit's own fix was "say so at both", so one of the two is now stale.
-#: Booked in `mailbox/C.md` (C-14) rather than edited across a fence
-#: [[two-gates-can-assert-opposite-things]].
-EVERYONE = '*'
-
-ROLES = ('view', 'edit')
-
-#: ⛔⛔ A FIELD's OBJECT ID IS TOPIC-QUALIFIED, AND THE SEPARATOR IS DECLARED HERE SO THERE IS ONE
-#: SPELLING OF IT. A bare field key is NOT unique: `notes` exists on a dozen databases, and a
-#: grant stored under it would admit a grantee to every `notes` column in the tenant at once —
-#: the widening direction, silently, forever. `table_key` is the qualifier because it is the same
-#: identifier `shared_overlay.bucket()` already keys the values by, so the grant and the data it
-#: governs are named by the same string ([[one-question-two-normalizers]]).
-#:
-#: ⚠ A `ut_*` key and a registry topic key both match `[a-z0-9_]+` and neither can contain `:`,
-#: so the split below is unambiguous in both directions.
-FIELD_OID_SEP = ':'
-
-
-def field_oid(table_key, field_key):
-    """`"<table_key>:<field_key>"` — the share id of ONE column on ONE database."""
-    table = str(table_key or '').strip()
-    field = str(field_key or '').strip()
-    if not table or not field:
-        raise ValueError('shares.field_oid: a field share names BOTH a database and a column. '
-                         'A bare field key repeats across tables and would grant all of them')
-    return f'{table}{FIELD_OID_SEP}{field}'
-
-
-def split_field_oid(oid):
-    """`(table_key, field_key)` or `(None, None)` for anything that is not a field oid.
-
-    ⛔ FAIL-CLOSED ON JUNK, like every other read here: a caller that cannot learn WHICH database
-    an id names must not fall back to "the one I happen to be looking at", which is how a grant
-    on somebody else's column would be read as a grant on this one.
-    """
-    raw = str(oid or '')
-    table, sep, field = raw.partition(FIELD_OID_SEP)
-    if not sep or not table.strip() or not field.strip() or FIELD_OID_SEP in field:
-        return (None, None)
-    return (table.strip(), field.strip())
-
-
-def _st(st):
-    return st if st is not None else store
-
-
-def _check_kind(kind):
-    k = str(kind or '').strip().lower()
-    if k not in KINDS:
-        raise ValueError(f'{kind!r} is not a shareable kind. Use one of {", ".join(KINDS)}. '
-                         f'This door refuses to invent a namespace from a typo.')
-    return k
-
-
-def _clean_entries(entries):
-    """Normalise + REJECT junk, returning [{'user': str, 'role': 'view'|'edit'}].
-
-    Silently dropping a malformed entry is right here and wrong elsewhere: the caller is a UI
-    that just listed the people it is about to grant, so a rejected row must not abort the whole
-    save — but an entry with an unknown ROLE must not be stored as something else's default
-    either. Dropped, never coerced.
-    """
-    out, seen = [], set()
-    for e in entries or ():
-        if not isinstance(e, dict):
-            continue
-        user = str(e.get('user') or '').strip().lower()
-        role = str(e.get('role') or '').strip().lower()
-        if not user or role not in ROLES or user in seen:
-            continue
-        seen.add(user)
-        out.append({'user': user, 'role': role})
-    return out
-
-
-def grants(kind, oid, st=None):
-    """`{'owner': str|None, 'entries': [{'user','role'}]}` — never raises on a junk bucket."""
-    kind = _check_kind(kind)
-    try:
-        bucket = (_st(st).get(SHARES_KEY) or {}).get(kind) or {}
-        rec = bucket.get(str(oid)) or {}
-    except Exception:
-        return {'owner': None, 'entries': []}
-    if not isinstance(rec, dict):
-        return {'owner': None, 'entries': []}
-    return {'owner': (str(rec.get('owner')).strip().lower() if rec.get('owner') else None),
-            'entries': _clean_entries(rec.get('entries'))}
-
-
-def set_grants(kind, oid, entries, owner=None, st=None):
-    """REPLACE the grant set for one object. Returns the stored record.
-
-    ⚠ REPLACE, NOT MERGE, and that is the contract the UI needs: revoking is expressed by an
-    entry's ABSENCE. A merge-only API cannot remove anybody without a second verb, and the
-    manage-access editor R10 asks for is exactly "here is the list now".
-    """
-    kind = _check_kind(kind)
-    oid = str(oid)
-    clean = _clean_entries(entries)
-    owner_l = str(owner).strip().lower() if owner else None
-
-    def _apply(data):
-        by_kind = dict(data.get(kind) or {})
-        prior = by_kind.get(oid) if isinstance(by_kind.get(oid), dict) else {}
-        # The owner is STICKY: set once, and a later save that omits it must not orphan the
-        # object. An ownerless grant record cannot answer "who may re-share this", so every
-        # administer check would fail closed and the object would become unmanageable.
-        keep_owner = owner_l or (str(prior.get('owner')).strip().lower()
-                                 if prior.get('owner') else None)
-        if not clean and not keep_owner:
-            by_kind.pop(oid, None)          # fully un-shared and unowned: leave no empty husk
-        else:
-            by_kind[oid] = {'owner': keep_owner, 'entries': clean}
-        data[kind] = by_kind
-        return data
-
-    _st(st).update(SHARES_KEY, _apply, flush='async')
-    return grants(kind, oid, st=st)
-
-
-def role_for(kind, oid, user, is_admin=False, st=None):
-    """`'owner'` | `'edit'` | `'view'` | `None` — the caller's effective role, fail-closed.
-
-    An ADMIN reads as `'owner'`: an admin who could not administer an object could not
-    administer the tenant either, which is `table_store._may_administer`'s existing rule and is
-    kept identical here so the two cannot disagree about the same view.
-    """
-    user = str(user or '').strip().lower()
-    if not user:
-        return None
-    rec = grants(kind, oid, st=st)
-    if is_admin or (rec['owner'] and rec['owner'] == user):
-        return 'owner'
-    best = None
-    for e in rec['entries']:
-        if e['user'] == user or e['user'] == EVERYONE:
-            # The STRONGER of the two wins when both a personal and an everyone grant exist:
-            # naming somebody explicitly is how you RAISE them above the room, so an
-            # everyone-view + alice-edit pair must leave alice editing.
-            if e['role'] == 'edit':
-                return 'edit'
-            best = best or 'view'
-    return best
-
-
-def may_see(kind, oid, user, is_admin=False, st=None):
-    return role_for(kind, oid, user, is_admin=is_admin, st=st) is not None
-
-
-def may_edit(kind, oid, user, is_admin=False, st=None):
-    return role_for(kind, oid, user, is_admin=is_admin, st=st) in ('owner', 'edit')
-
-
-def may_administer(kind, oid, user, is_admin=False, st=None):
-    """Only the owner or an admin may change grants or delete. See the module note on why this
-    is deliberately narrower than `may_edit`."""
-    return role_for(kind, oid, user, is_admin=is_admin, st=st) == 'owner'
-
-
-def shared_with(user, kind=None, st=None):
-    """Every object id this user has been granted (excluding what they own).
-
-    This is the "Shared with me" query (R10). It EXCLUDES owned objects deliberately: a folder
-    you made is not something shared *with* you, and listing it there would make the system
-    folder a duplicate of the rail above it.
-    """
-    user = str(user or '').strip().lower()
-    if not user:
-        return {}
-    try:
-        data = _st(st).get(SHARES_KEY) or {}
-    except Exception:
-        return {}
-    out = {}
-    for k in ([_check_kind(kind)] if kind else KINDS):
-        hits = []
-        for oid, rec in (data.get(k) or {}).items():
-            if not isinstance(rec, dict):
-                continue
-            owner = str(rec.get('owner') or '').strip().lower()
-            if owner == user:
-                continue
-            for e in _clean_entries(rec.get('entries')):
-                if e['user'] in (user, EVERYONE):
-                    hits.append(str(oid))
-                    break
-        out[k] = sorted(hits)
-    return out if kind is None else {_check_kind(kind): out[_check_kind(kind)]}
-
-
-def drop_objects(pairs, st=None):
-    """Remove whole grant RECORDS, owner husk included — wave 21, item 6a (C3).
-
-    A deleted object's grants must die with it: `shared_with` would otherwise serve ghost ids
-    into every receiver's "Shared with me" forever, and the ghost would 404 on open. One
-    transaction for the whole sweep — a table delete drops its database grant plus a view
-    grant per view that lived in its bucket."""
-    want = {}
-    for kind, oid in pairs or ():
-        want.setdefault(_check_kind(kind), set()).add(str(oid))
-    if not want:
-        return
-
-    def _apply(data):
-        for kind, oids in want.items():
-            by_kind = data.get(kind)
-            if isinstance(by_kind, dict):
-                for oid in oids:
-                    by_kind.pop(oid, None)
-        return data
-
-    _st(st).update(SHARES_KEY, _apply, flush='async')
+"""core/shares.py — ONE grant registry for every shareable object (wave 20, owner ruling R10).
+
+WHAT R10 ASKED FOR: folders and databases share with the **same two-role vocabulary views
+already use** (specific users or everyone; role = view | edit), plus one manage-access editor
+that can add or revoke people later, on any of the three.
+
+WHY A REGISTRY RATHER THAN A FIELD ON EACH OBJECT. A view already carries its own `permissions`
+(`core/table_store.py`) and that stays — moving it would rewrite every stored view for no gain.
+But a FOLDER is a value inside one user's workspace blob and a DATABASE is a `user_tables`
+definition; giving each its own grant field would put the same three-line permission decision in
+three files owned by two sessions, which is how the three drift. One registry, one predicate,
+three callers.
+
+    shares.set_grants(kind, oid, entries, owner=…, st=…)   # replaces the whole grant set
+    shares.grants(kind, oid, st=…)                         # -> {'owner': str, 'entries': [...]}
+    shares.role_for(kind, oid, user, is_admin=…, st=…)     # -> 'owner'|'edit'|'view'|None
+    shares.max_grantable_role(kind, oid, user, …)          # -> 'edit'|'view'|None (R4's ceiling)
+    shares.shared_with(user, kind=…, st=…)                 # -> [oid] this user was granted
+
+THE ROLE VOCABULARY IS TWO WORDS AND THE DEFAULT IS THE NARROW ONE. `view` = may open and read;
+`edit` = may also change the object's CONTENT.
+
+⭐⭐ AND ON A VIEW, `edit` NOW ALSO MEANS "MAY RE-SHARE" — OWNER RULING R4, instruction 4 (*"Edit
+View so a member can share a View as well, not just an admin"*), built as W40-T02. This REVERSES
+the flat owner-or-admin rule this paragraph used to state, and it reverses it for ONE kind:
+`RESHARE_KINDS` below is where the widening is spelled, once, and `folder` / `database` / `field`
+are untouched — still the owner's or an admin's, for the reason given at that constant.
+
+⛔ WHICH HALF OF THE OLD PROTECTION SURVIVES, BECAUSE THE FEAR IT NAMED WAS REAL AND ONLY HALF OF
+IT IS ANSWERED. The sentence here used to be *"a collaborator who could rewrite grants could grant
+themselves sole ownership of somebody else's object, or quietly widen a users-scoped share to
+everyone"*. Taking those one at a time:
+  * **SOLE OWNERSHIP IS BLOCKED — and now stated rather than incidental.** The owner is STICKY in
+    `set_grants` and `routes_shares.put_share` passes the EXISTING owner straight back through, so
+    a re-share cannot transfer ownership and no grantee can lock the creator out of their own view.
+    Ownership moves for nobody, by any path this registry offers.
+  * **WIDENING IS BOUNDED, NOT BLOCKED, AND THAT IS R4's DELIBERATE COST.** A re-share may never
+    exceed the role the re-sharer holds, and the STRICTER reading of that ships: an `edit` grantee
+    may add somebody — `*` included — at `view`, and can never mint `edit` access for anyone.
+    Handing out `edit` stays the owner's (or an admin's) alone. A `view` grantee still cannot share
+    at all. `max_grantable_role` is that ceiling, and `routes_shares.put_share` is where it bites.
+
+⛔ AN UNREADABLE GRANT IS NO GRANT. Every path here fails closed — junk in the bucket, a missing
+owner, an unknown role string all resolve to None rather than to a default that opens something.
+[[aios-permissioning]]: no fail-open defaults, ever.
+
+⚠ THE BUCKET IS TENANT-SCOPED THROUGH `st`, like every other product-data write. Passing the
+session's `TenantRuntime` is what keeps Nurilab's grants in Nurilab's store; the module default
+(`core.store`) is tenant #0 and exists for the same reason it does everywhere else — the ~28
+callers that predate multi-tenancy. (This is the D-5/D-16 residency shape, and this module does
+NOT repeat their mistake: `st` is threaded from the first line rather than retrofitted.)
+"""
+import core.store as store
+
+#: The store key. One bucket per tenant holds every kind's grants, because "what am I shared on"
+#: is a question across kinds — the "Shared with me" folder (R10) is exactly that query, and
+#: three separate buckets would make it three reads that can disagree about what a user can see.
+SHARES_KEY = 'object_shares'
+
+#: The shareable kinds. A CLOSED vocabulary: an unknown kind raises rather than creating a new
+#: namespace by typo, which would silently grant nothing to nobody and read as "sharing is broken".
+#:
+#: ⭐⭐ W38-T16 — `field` IS THE FOURTH, AND NOTHING IN THIS FILE BRANCHES ON IT. Every function
+#: below treats `kind` as an opaque bucket key (`_check_kind / grants / set_grants / role_for /
+#: may_see / may_edit / may_administer / shared_with / drop_objects`), so the kind's whole cost
+#: here is this tuple member. That is the point of one registry: the new object's WALL is written
+#: once in `core.perm_scope`, and its DOORS once in `routes_shares.py` — never a fourth
+#: permission decision in a fourth file ([[one-evaluator-per-question]]).
+KINDS = ('view', 'folder', 'database', 'field')
+
+#: `*` is "everyone who can already open the surface". It is NOT "every account on the platform".
+#: Spelled as a single character so it can never collide with a username (usernames are lower-case
+#: and non-empty by `core/users.py`, and are checked against this explicitly below).
+#:
+#: ⛔⛔ **AND WHAT THAT MEANS DEPENDS ON THE KIND — THE LINE THIS NOTE USED TO CARRY WAS FALSE FOR
+#: ONE OF THE THREE** (W33-T30, `waves/wave32/sharing-audit.md` S-8). It read *"the module/table
+#: wall runs FIRST and this never widens past it"*, flatly, and the audit's own words for that are
+#: *"the third docstring in this audit describing a check that is not on the path"*. Corrected
+#: here rather than deleted, because the sentence is TRUE of two kinds and the difference is the
+#: whole point:
+#:   * `kind='view'` / `kind='folder'` on a GOVERNED module (`customer_data`, `product_data`) —
+#:     the sentence holds. `require_session` plus the topic's own gate run first, and the
+#:     receiver's row scope and hidden-field closure are applied BEFORE any foreign view is
+#:     merged, so a grant can only narrow-or-equal what that account could already reach.
+#:   * `kind='database'` on a `ut_*` table — ⭐⭐ **THE SENTENCE HOLDS HERE TOO NOW, AND THAT IS
+#:     W36-T21 / OWNER RULING R6 (audit S-8, CLOSED).** It did not until wave 36, and the reason
+#:     is worth keeping: `routes_admin._clean_perms` 400'd any key outside
+#:     `("customer_data", "product_data")`, so no row filter and no hidden field could even be
+#:     DECLARED for a user table, `routes_tables.py` made zero `perm_scope` calls, and it passed
+#:     `hidden_keys=frozenset()`. A `database` grant was therefore ALL-OR-NOTHING — every row,
+#:     every column — and this registry was the only wall behind it.
+#:
+#: ⭐ WHAT CHANGED: `perm_scope.scoped_table` (contract C1) is the ONE door to any database's
+#: rows. `routes_tables` applies the permanent filter before `pids` is taken and the transitive
+#: hidden-field closure after `workspace_wire`, on EVERY `ut_*` read — the same code that walls
+#: `customer_data` — and a door that cannot apply them REFUSES rather than serving the lot. So a
+#: `database` grant is once again bounded by a second wall: it decides WHETHER an account reaches
+#: the database, and C1 decides WHICH rows and columns it then sees. An `*` grant still admits
+#: every account in the tenant, and each of them still only sees what their own wall allows.
+#:
+#: ⚠ `routes_shares.py`'s module docstring carries the OLD sentence at the other door and is in
+#: no wave-36 fence — the audit's own fix was "say so at both", so one of the two is now stale.
+#: Booked in `mailbox/C.md` (C-14) rather than edited across a fence
+#: [[two-gates-can-assert-opposite-things]].
+EVERYONE = '*'
+
+ROLES = ('view', 'edit')
+
+#: ⭐⭐ THE KINDS AN `edit` GRANTEE MAY RE-SHARE — R4 / W40-T02, and it is `view` ALONE.
+#:
+#: R4's words are "may re-share **A VIEW**", and the widening goes no further than the ruling
+#: names. That restraint is the whole reason this is a tuple rather than a bare `role == 'edit'`
+#: arm inside `may_administer`: every predicate in this file treats `kind` as an opaque bucket key
+#: (see the note on `KINDS`), so an UNGATED widening would reach `folder`, `database` and `field`
+#: in the same line — handing an `edit` grantee on a `ut_*` DATABASE the power to re-share the
+#: whole table. The asymmetry is one of blast radius: a view is one saved SELECTION, opened through
+#: the receiver's own module wall and row scope; a database grant admits an account to a database.
+#: `routes_shares.py`'s module docstring carries that argument at the door where it is enforced.
+#:
+#: ⚠ ONE SPELLING, DELIBERATELY. `may_administer` and `max_grantable_role` both consult this, so
+#: "who may open the editor" and "what may they hand out" cannot come apart about the same kind.
+RESHARE_KINDS = ('view',)
+
+#: ⛔⛔ A FIELD's OBJECT ID IS TOPIC-QUALIFIED, AND THE SEPARATOR IS DECLARED HERE SO THERE IS ONE
+#: SPELLING OF IT. A bare field key is NOT unique: `notes` exists on a dozen databases, and a
+#: grant stored under it would admit a grantee to every `notes` column in the tenant at once —
+#: the widening direction, silently, forever. `table_key` is the qualifier because it is the same
+#: identifier `shared_overlay.bucket()` already keys the values by, so the grant and the data it
+#: governs are named by the same string ([[one-question-two-normalizers]]).
+#:
+#: ⚠ A `ut_*` key and a registry topic key both match `[a-z0-9_]+` and neither can contain `:`,
+#: so the split below is unambiguous in both directions.
+FIELD_OID_SEP = ':'
+
+
+def field_oid(table_key, field_key):
+    """`"<table_key>:<field_key>"` — the share id of ONE column on ONE database."""
+    table = str(table_key or '').strip()
+    field = str(field_key or '').strip()
+    if not table or not field:
+        raise ValueError('shares.field_oid: a field share names BOTH a database and a column. '
+                         'A bare field key repeats across tables and would grant all of them')
+    return f'{table}{FIELD_OID_SEP}{field}'
+
+
+def split_field_oid(oid):
+    """`(table_key, field_key)` or `(None, None)` for anything that is not a field oid.
+
+    ⛔ FAIL-CLOSED ON JUNK, like every other read here: a caller that cannot learn WHICH database
+    an id names must not fall back to "the one I happen to be looking at", which is how a grant
+    on somebody else's column would be read as a grant on this one.
+    """
+    raw = str(oid or '')
+    table, sep, field = raw.partition(FIELD_OID_SEP)
+    if not sep or not table.strip() or not field.strip() or FIELD_OID_SEP in field:
+        return (None, None)
+    return (table.strip(), field.strip())
+
+
+def _st(st):
+    return st if st is not None else store
+
+
+def _check_kind(kind):
+    k = str(kind or '').strip().lower()
+    if k not in KINDS:
+        raise ValueError(f'{kind!r} is not a shareable kind. Use one of {", ".join(KINDS)}. '
+                         f'This door refuses to invent a namespace from a typo.')
+    return k
+
+
+def _clean_entries(entries):
+    """Normalise + REJECT junk, returning [{'user': str, 'role': 'view'|'edit'}].
+
+    Silently dropping a malformed entry is right here and wrong elsewhere: the caller is a UI
+    that just listed the people it is about to grant, so a rejected row must not abort the whole
+    save — but an entry with an unknown ROLE must not be stored as something else's default
+    either. Dropped, never coerced.
+    """
+    out, seen = [], set()
+    for e in entries or ():
+        if not isinstance(e, dict):
+            continue
+        user = str(e.get('user') or '').strip().lower()
+        role = str(e.get('role') or '').strip().lower()
+        if not user or role not in ROLES or user in seen:
+            continue
+        seen.add(user)
+        out.append({'user': user, 'role': role})
+    return out
+
+
+def grants(kind, oid, st=None):
+    """`{'owner': str|None, 'entries': [{'user','role'}]}` — never raises on a junk bucket."""
+    kind = _check_kind(kind)
+    try:
+        bucket = (_st(st).get(SHARES_KEY) or {}).get(kind) or {}
+        rec = bucket.get(str(oid)) or {}
+    except Exception:
+        return {'owner': None, 'entries': []}
+    if not isinstance(rec, dict):
+        return {'owner': None, 'entries': []}
+    return {'owner': (str(rec.get('owner')).strip().lower() if rec.get('owner') else None),
+            'entries': _clean_entries(rec.get('entries'))}
+
+
+def set_grants(kind, oid, entries, owner=None, st=None):
+    """REPLACE the grant set for one object. Returns the stored record.
+
+    ⚠ REPLACE, NOT MERGE, and that is the contract the UI needs: revoking is expressed by an
+    entry's ABSENCE. A merge-only API cannot remove anybody without a second verb, and the
+    manage-access editor R10 asks for is exactly "here is the list now".
+    """
+    kind = _check_kind(kind)
+    oid = str(oid)
+    clean = _clean_entries(entries)
+    owner_l = str(owner).strip().lower() if owner else None
+
+    def _apply(data):
+        by_kind = dict(data.get(kind) or {})
+        prior = by_kind.get(oid) if isinstance(by_kind.get(oid), dict) else {}
+        # The owner is STICKY: set once, and a later save that omits it must not orphan the
+        # object. An ownerless grant record cannot answer "who may re-share this", so every
+        # administer check would fail closed and the object would become unmanageable.
+        keep_owner = owner_l or (str(prior.get('owner')).strip().lower()
+                                 if prior.get('owner') else None)
+        if not clean and not keep_owner:
+            by_kind.pop(oid, None)          # fully un-shared and unowned: leave no empty husk
+        else:
+            by_kind[oid] = {'owner': keep_owner, 'entries': clean}
+        data[kind] = by_kind
+        return data
+
+    _st(st).update(SHARES_KEY, _apply, flush='async')
+    return grants(kind, oid, st=st)
+
+
+def role_for(kind, oid, user, is_admin=False, st=None):
+    """`'owner'` | `'edit'` | `'view'` | `None` — the caller's effective role, fail-closed.
+
+    An ADMIN reads as `'owner'`: an admin who could not administer an object could not
+    administer the tenant either, which is `table_store._may_administer`'s existing rule and is
+    kept identical here so the two cannot disagree about the same view.
+    """
+    user = str(user or '').strip().lower()
+    if not user:
+        return None
+    rec = grants(kind, oid, st=st)
+    if is_admin or (rec['owner'] and rec['owner'] == user):
+        return 'owner'
+    best = None
+    for e in rec['entries']:
+        if e['user'] == user or e['user'] == EVERYONE:
+            # The STRONGER of the two wins when both a personal and an everyone grant exist:
+            # naming somebody explicitly is how you RAISE them above the room, so an
+            # everyone-view + alice-edit pair must leave alice editing.
+            if e['role'] == 'edit':
+                return 'edit'
+            best = best or 'view'
+    return best
+
+
+def may_see(kind, oid, user, is_admin=False, st=None):
+    return role_for(kind, oid, user, is_admin=is_admin, st=st) is not None
+
+
+def may_edit(kind, oid, user, is_admin=False, st=None):
+    return role_for(kind, oid, user, is_admin=is_admin, st=st) in ('owner', 'edit')
+
+
+def may_administer(kind, oid, user, is_admin=False, st=None):
+    """May this caller change WHO ELSE reaches the object, and revoke them?
+
+    ⭐⭐ R4 / W40-T02 — AN `edit` GRANTEE ANSWERS TRUE, ON A `RESHARE_KINDS` KIND. Owner
+    instruction 4: *"Edit View so a member can share a View as well, not just an admin"*. That
+    reverses this function's old owner-or-admin rule for exactly one kind; the module note says
+    which half of the protection survives and `RESHARE_KINDS` says why it stops at `view`.
+
+    ⛔ ADMINISTERING IS NOT GRANTING, AND THE SECOND QUESTION HAS ITS OWN PREDICATE. True here
+    means "may open the editor and rewrite the list"; it does NOT mean every role is theirs to
+    hand out. `max_grantable_role` is the ceiling, and R4's two halves are only both honoured if
+    a caller consults both ([[one-evaluator-per-question]]).
+
+    ⛔ THE GATE IS THE KIND, NOT THE ROLE ALONE. `role_for` is deliberately kind-agnostic, so
+    testing `== 'edit'` without `RESHARE_KINDS` would widen all four kinds in one line.
+    """
+    role = role_for(kind, oid, user, is_admin=is_admin, st=st)
+    if role == 'owner':
+        return True
+    return role == 'edit' and _check_kind(kind) in RESHARE_KINDS
+
+
+def max_grantable_role(kind, oid, user, is_admin=False, st=None):
+    """The STRONGEST role this caller may hand SOMEBODY ELSE on this object, fail-closed.
+
+    `'edit'` for the owner or an admin · `'view'` for an `edit` grantee on a `RESHARE_KINDS` kind
+    · `None` for anybody who may not administer the object at all.
+
+    ⭐⭐ WHY A SECOND PREDICATE RATHER THAN A FLAG ON `may_administer` (R4 / W40-T02). R4 grants an
+    `edit` holder the right to re-share and caps it in the same breath: *"a re-share may never
+    exceed the role the re-sharer holds"*. Those are two different questions, and a single boolean
+    answering both is exactly how the cap gets dropped by the next caller that only needs the door.
+
+    ⛔ THE NARROWER OF R4's TWO READINGS SHIPS, AND ON PURPOSE. "Never exceed the role you hold"
+    reads either as *may grant up to and including `edit`* (an edit holder confers edit) or as *may
+    confer strictly less than the owner can*. This returns `'view'` — the second — because it is the
+    FAIL-CLOSED direction. A wrong `'view'` costs the owner one click to raise somebody; a wrong
+    `'edit'` lets a chain of collaborators propagate edit access the owner never approved, with
+    nothing in the store recording who widened it. W40-T02's `done-when` pins the same reading.
+
+    ⚠ THIS CAPS WHAT A CALLER GRANTS, NOT WHAT THE STORED SET ALREADY HOLDS, and the difference is
+    load-bearing. `routes_shares.put_share` enforces it against the DELTA — a name arriving at
+    `edit`, or an existing `view` grantee raised to it — never against every row of a body, because
+    the PUT REPLACES and the client therefore re-sends the whole list, the re-sharer's own `edit`
+    row included. The evidence for that is at the call site, where the body is.
+    """
+    role = role_for(kind, oid, user, is_admin=is_admin, st=st)
+    if role == 'owner':
+        return 'edit'
+    if role == 'edit' and _check_kind(kind) in RESHARE_KINDS:
+        return 'view'
+    return None
+
+
+def shared_with(user, kind=None, st=None):
+    """Every object id this user has been granted (excluding what they own).
+
+    This is the "Shared with me" query (R10). It EXCLUDES owned objects deliberately: a folder
+    you made is not something shared *with* you, and listing it there would make the system
+    folder a duplicate of the rail above it.
+    """
+    user = str(user or '').strip().lower()
+    if not user:
+        return {}
+    try:
+        data = _st(st).get(SHARES_KEY) or {}
+    except Exception:
+        return {}
+    out = {}
+    for k in ([_check_kind(kind)] if kind else KINDS):
+        hits = []
+        for oid, rec in (data.get(k) or {}).items():
+            if not isinstance(rec, dict):
+                continue
+            owner = str(rec.get('owner') or '').strip().lower()
+            if owner == user:
+                continue
+            for e in _clean_entries(rec.get('entries')):
+                if e['user'] in (user, EVERYONE):
+                    hits.append(str(oid))
+                    break
+        out[k] = sorted(hits)
+    return out if kind is None else {_check_kind(kind): out[_check_kind(kind)]}
+
+
+def granted_oids(kind, st=None):
+    """Every object id of one `kind` that carries AT LEAST ONE grant entry — in ONE bucket read.
+
+    ⭐ W40-T01 / OWNER INSTRUCTION 2 ("a shared View must show the shared icon in EVERY account,
+    not only the recipient's"). `shared_with` answers *what was granted TO me* and deliberately
+    EXCLUDES what the caller owns — so it structurally cannot answer the other question a share
+    mark asks: *does this object have grants at all*. That question has no viewer in it, which is
+    why this is a separate function rather than a flag bolted onto `shared_with`.
+
+    ⚠ ONE READ, NOT N — and that is the whole reason this exists rather than a loop at the caller.
+    The obvious spelling is `grants(kind, oid)` per view, and `grants` re-reads the WHOLE bucket
+    on every call; a busy rail carries dozens of views, so painting one icon would cost dozens of
+    full reads of the tenant's entire grant registry. This reads the bucket once and hands back a
+    set the caller tests in O(1).
+
+    ⛔ AN ENTRY IS WHAT COUNTS, NOT A RECORD. `set_grants` keeps an owner-only HUSK after a full
+    revoke — the owner is sticky, deliberately, see its own note — so testing for the record's
+    mere EXISTENCE would leave the mark lit forever after the last person was removed. That is
+    exactly the revoke case, so it is the difference between this being right and being decorative
+    noise. `_clean_entries` is the same normaliser every other read here uses, so a junk entry
+    cannot mark an object either.
+
+    ⛔ FAIL-CLOSED like the rest of this module: an unreadable bucket answers the EMPTY set — no
+    marks — never a default that claims something is shared. An unknown KIND still RAISES, exactly
+    as `grants` / `shared_with` / `drop_objects` do: that is a typo in a caller, not junk in the
+    store, and swallowing it into "nothing is shared" would hide a caller that never works.
+    """
+    kind = _check_kind(kind)
+    try:
+        by_kind = (_st(st).get(SHARES_KEY) or {}).get(kind) or {}
+        rows = list(by_kind.items())
+    except Exception:
+        return set()
+    return {str(oid) for oid, rec in rows
+            if isinstance(rec, dict) and _clean_entries(rec.get('entries'))}
+
+
+def drop_objects(pairs, st=None):
+    """Remove whole grant RECORDS, owner husk included — wave 21, item 6a (C3).
+
+    A deleted object's grants must die with it: `shared_with` would otherwise serve ghost ids
+    into every receiver's "Shared with me" forever, and the ghost would 404 on open. One
+    transaction for the whole sweep — a table delete drops its database grant plus a view
+    grant per view that lived in its bucket."""
+    want = {}
+    for kind, oid in pairs or ():
+        want.setdefault(_check_kind(kind), set()).add(str(oid))
+    if not want:
+        return
+
+    def _apply(data):
+        for kind, oids in want.items():
+            by_kind = data.get(kind)
+            if isinstance(by_kind, dict):
+                for oid in oids:
+                    by_kind.pop(oid, None)
+        return data
+
+    _st(st).update(SHARES_KEY, _apply, flush='async')

platform/core/users.py

@@ -1,24 +1,24 @@
-"""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.
+"""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
 
 
@@ -64,451 +64,488 @@ def qa_identity(username, pw=None):
     return {'username': _QA_USERNAME, 'name': 'QA Runner', 'role': 'user',
             'bus': 'all', 'modules': ['customers'], 'tenant': _QA_TENANT,
             'epoch': qa_epoch, 'qa_runner': True}
-
-
-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 _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, and RETURN the new epoch.
+
+    None when there was no such record: nothing was bumped, and inventing 0 would hand a caller an
+    epoch that no cookie should ever be minted under.
+
+    ⭐ WHY IT RETURNS — WAVE 40, R2 ("signing in on computer B signs computer A out immediately").
+    A login now bumps the epoch and then has to MINT under it, and the minting caller cannot find
+    that number by reading the registry back: between the write and the read another writer (this
+    module's own `touch_login` thread, a second login, an admin edit) can land, and a cookie minted
+    at the wrong epoch is refused by `deps._user_for` on the very next request — a 200 login
+    followed by 401 forever. The write is the only place that knows what it wrote.
+
+    The value comes from the document `store.update` RETURNED rather than from what we tried to
+    write: on the HF backend a cross-process rebase can rebuild that document from a newer copy and
+    replay this closure against it, so the LANDED epoch is the authority. If another process bumped
+    the same account concurrently the landed value is higher than ours, which is still exactly the
+    newest-wins answer R2 asks for. The closure-captured value is the fallback for a store whose
+    `update` returns nothing.
+    """
+    username = (username or '').strip().lower()
+    bumped = {}
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            u['epoch'] = int(u.get('epoch') or 0) + 1
+            bumped['epoch'] = u['epoch']
+        return reg
+    landed = store.update('users', _set)
+    if 'epoch' not in bumped:
+        return None                       # no such record: nothing was revoked, so promise nothing
+    try:
+        rec = (landed or {}).get(username) or {}
+        if rec.get('epoch') is not None:
+            return int(rec['epoch'])
+    except Exception:
+        pass
+    return int(bumped['epoch'])
+
+
+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.
+        #
+        # ⚠ WAVE 40 (R2) — `emergency_master` MARKS THIS DICT SO THE LOGIN CAN SKIP THE EPOCH BUMP.
+        # Every ordinary sign-in now bumps the account's epoch to sign its other sessions out, but
+        # this identity is deliberately NOT epoch-revocable: `deps._user_for`'s master fallback
+        # admits it whatever the record says. A bump here would therefore revoke nothing, while
+        # forcing a store WRITE on the one code path that exists for a store outage. Internal to
+        # the server: `routes_auth._public_user` is a whitelist projection and does not name it.
+        return {'username': 'admin', 'name': 'Administrator', 'role': 'admin', 'bus': 'all',
+                'modules': 'all', 'epoch': int((reg.get('admin') or {}).get('epoch') or 0),
+                'emergency_master': True}
+    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.
-    """
+    """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)})
 
 
@@ -517,67 +554,67 @@ def assignable_identities(tenant=None):
     return [{"username": str(username).strip().lower(),
              "name": str(record.get("name") or username)}
             for username, record in sorted(_tenant_accounts(tenant), key=lambda item: item[0])]
-
-
-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]
+
+
+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/topics/odoo_customers.yml

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

platform/model/topics/odoo_products.yml

@@ -1,52 +1,63 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_products
-label: "Odoo products"
-entity: product.product
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: product_data
-subject: "odoo:product.product"
-grain: "one row per SKU in the active catalogue — a CATALOGUE, not a dated event stream"
-scope:
-  population: "every ACTIVE product, sold or not (measured 5,862). Deliberately not the sales-window universe: that lands at 2,717 and hides ~2,550 SKUs that have never sold in wholesale scope"
-  identity: "the SKU code (`default_code`). ⚠ 33 active products carry NO code and are keyed `pid:<odoo product id>` instead, so every active product has exactly one row and none is dropped"
-  merged: "W33-T44 retired `ut_odoo_products`, which presented this same subject on Odoo's product_id. This topic describes the SURVIVING database, `product_data`"
-  no_date: "a catalogue has no date dimension; ask sales_lines for movement"
-store:
-  table: product_product
-  alias: pp
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-  dims:
-    category: {label: "Category"}
-    supplier: {label: "Supplier"}
-
-# ⭐⭐ 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.
+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS A HAND-MAINTAINED, CURATED SUBSET OF THE GRID'S FIELD
+# CONTRACT, AND NOTHING ENFORCES IT. This comment used to say the block was GENERATED
+# and "held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a field
+# row." MEASURED 2026-08-24: `section_entity_topics` does not exist anywhere in the tree
+# and no gate compares this file to `aios_grid_fields.json`, so that sentence was an
+# unchecked claim forbidding the only edit anyone can actually make
+# ([[a-declared-gate-is-an-unchecked-claim]]).
+#
+# What is TRUE: 9 of the product contract's keys are deliberately absent (D-400 —
+# incoming, cover_gap_units, demand_fwd, discontinued, needs_pricing, march_pricelist,
+# price_changes, closeouts, notes), and no key here is absent from the contract. So a
+# field row IS hand-edited, and the rule is the honest one: the key, type and label must
+# match `aios_grid_fields.json`, because the agent is otherwise trained on a schema the
+# product does not have. Building the missing gate is booked; until it exists, this
+# paragraph is the only thing keeping the two in step.
+key: odoo_products
+label: "Odoo products"
+entity: product.product
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: product_data
+subject: "odoo:product.product"
+grain: "one row per SKU in the active catalogue — a CATALOGUE, not a dated event stream"
+scope:
+  population: "every ACTIVE product, sold or not (measured 5,862). Deliberately not the sales-window universe: that lands at 2,717 and hides ~2,550 SKUs that have never sold in wholesale scope"
+  identity: "the SKU code (`default_code`). ⚠ 33 active products carry NO code and are keyed `pid:<odoo product id>` instead, so every active product has exactly one row and none is dropped"
+  merged: "W33-T44 retired `ut_odoo_products`, which presented this same subject on Odoo's product_id. This topic describes the SURVIVING database, `product_data`"
+  no_date: "a catalogue has no date dimension; ask sales_lines for movement"
+store:
+  table: product_product
+  alias: pp
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+  dims:
+    category: {label: "Category"}
+    supplier: {label: "Supplier"}
+
+# ⭐⭐ 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
@@ -57,81 +68,123 @@ measures:
   # crm.team 7 is not part of either wholesale BU.
   scope_variant: all_channels
   # ⭐ 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.
-fields:
-  - key: code
-    label: "SKU"
-    type: text
-    kind: data
-    means: "The SKU code — the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer."
-  - key: product
-    label: "Product"
-    type: text
-    kind: data
-    means: "Product name as it appears in Odoo."
-  - key: category
-    label: "Category"
-    type: select
-    kind: data
-    means: "Product category; '(uncategorized)' when Odoo carries none."
-  - key: supplier
-    label: "Supplier"
-    type: text
-    kind: data
-    means: "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet."
-  - key: origin_country
-    label: "Country"
-    type: text
-    kind: data
-    means: "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet."
-  - key: lead_days
-    label: "Lead time (days)"
-    type: int
-    kind: data
-    means: "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone."
-  - key: first_cost
-    label: "First cost"
-    type: currency
-    kind: data
-    means: "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone."
-  - key: price_fisch
-    label: "Fisch price"
-    type: currency
-    kind: data
-    means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
-  - key: price_royal_1
-    label: "Royal 1 price"
-    type: currency
-    kind: data
-    means: "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
+  # 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"
+
+# ⭐⭐ W40-T10 / owner item 26 (ruling R7, contract C6) — PER-METRIC CHANNEL SCOPE. Owner:
+# *"Separate revenue and the other Odoo products metrics by Analytics, as a filter under the
+# Metrics field, specific to the Odoo databases."* R7 makes it PER METRIC rather than per grid, so
+# "Revenue (Fisch)" and "Revenue (Amazon)" sit side by side on one grid and answer differently.
+#
+# ⛔ THE CHANNEL IS A BINDING, NOT A MEMBER OF THE SAVED FIELD. C6 words it as part of the stored
+# Metric spec and it CANNOT be one: `aios_grid.clean_measure_field` rebuilds that dict from known
+# members and returns `{key, window}`, so a `channel` member is dropped on save with nothing to
+# notice, and `aios_grid.py` is in no lane's fence. The key survives, so the channel rides the
+# KEY: `semantic._one_binding_offer` derives the suffix and the "(Fisch)" from the variant name,
+# and the catalogue offers `revenue` / `revenue_fisch` / `revenue_royal` / `revenue_amazon` as
+# four distinct keys. No client change: the picker already offers whatever the catalogue offers.
+#
+# ⛔ THESE MUST STAY *AFTER* THE TWO ABOVE. `entity_measure_binding()` and two gates
+# (`verify_product_pool::W39-T11`, `verify_odoo_relational::_prove_entity_measures`) read
+# `bindings[0]` as "the" binding; putting a channel binding first would silently retarget them.
+#
+# ⚠ `not_yet:` is deliberately NOT repeated here. It documents the METRIC and why the wave does
+# not ship it, which is a fact about the metric and not about the channel — copying it four times
+# would be four statements of one thing, and the day one is answered three would go stale.
+#
+# ⭐ COST: one grouped scan PER CHANNEL, because `entity_measure_values` groups by
+# `(topic, dim, scope_variant)`. Four channel columns of the same measure over the same window
+# are four scans, ~0.22 s each against the mirror. A grid carrying one channel costs exactly what
+# it costs today.
+- source: sales_lines
+  dim: product_code
+  scope_variant: channel_fisch
+  keys: [units, revenue, margin, cogs, margin_pct, asp]
+- source: sales_lines
+  dim: product_code
+  scope_variant: channel_royal
+  keys: [units, revenue, margin, cogs, margin_pct, asp]
+# ⛔ `amazon` IS THE EXCLUDED PARTNER, NOT crm.team 7 — measured, and the difference is real:
+# GIFTWARE DEALS carries 24 orders on team 7 AND 2 on team 5, so the partner and the team name
+# different sets. `core/odoo.sale_line_domain` already fences wholesale on the PARTNER, so taking
+# the team here would be a second, disagreeing idea of what Amazon is.
+- source: sales_lines
+  dim: product_code
+  scope_variant: channel_amazon
+  keys: [units, revenue, margin, cogs, margin_pct, asp]
+
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: code
+    label: "SKU"
+    type: text
+    kind: data
+    means: "The SKU code — the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer."
+  - key: product
+    label: "Product"
+    type: text
+    kind: data
+    means: "Product name as it appears in Odoo."
+  - key: category
+    label: "Category"
+    type: select
+    kind: data
+    means: "Product category; '(uncategorized)' when Odoo carries none."
+  - key: supplier
+    label: "Supplier"
+    type: multiselect
+    kind: data
+    means: "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet."
+  - key: origin_country
+    label: "Country"
+    type: text
+    kind: data
+    means: "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet."
+  - key: lead_days
+    label: "Lead time (days)"
+    type: int
+    kind: data
+    means: "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone."
+  - key: first_cost
+    label: "First cost"
+    type: currency
+    kind: data
+    means: "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone."
+  - key: price_fisch
+    label: "Fisch price"
+    type: currency
+    kind: data
+    means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
+  - key: price_royal_1
+    label: "Royal 1 price"
+    type: currency
+    kind: data
+    means: "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
   - key: price_royal_2
     label: "Royal 2 price"
     type: currency
@@ -141,7 +194,7 @@ fields:
     label: "Price 1"
     type: currency
     kind: data
-    means: "Cheapest live package price for this SKU across active pricelists."
+    means: "Cheapest live package price for this SKU pooled across ALL active pricelists and unattributed. Ask the per-list tier fields for what a named list charges."
   - key: unit_1
     label: "Unit 1"
     type: text
@@ -151,7 +204,7 @@ fields:
     label: "Price 2"
     type: currency
     kind: data
-    means: "Second-cheapest live package price for this SKU."
+    means: "Second-cheapest live package price pooled across ALL pricelists, unattributed."
   - key: unit_2
     label: "Unit 2"
     type: text
@@ -161,12 +214,102 @@ fields:
     label: "Price 3"
     type: currency
     kind: data
-    means: "Third-cheapest live package price for this SKU."
+    means: "Third-cheapest live package price pooled across ALL pricelists, unattributed."
   - key: unit_3
     label: "Unit 3"
     type: text
     kind: data
     means: "Package label for Price 3."
+  - key: price_fisch_t1
+    label: "Fisch tier 1 price"
+    type: currency
+    kind: data
+    means: "Fisch price tier 1, cheapest first. Blank when Fisch does not price this SKU."
+  - key: unit_fisch_t1
+    label: "Fisch tier 1 unit"
+    type: text
+    kind: data
+    means: "Package label for the Fisch tier 1 price. Blank when Odoo names no package."
+  - key: price_fisch_t2
+    label: "Fisch tier 2 price"
+    type: currency
+    kind: data
+    means: "Fisch price tier 2. Blank when Fisch prices this SKU at only one tier."
+  - key: unit_fisch_t2
+    label: "Fisch tier 2 unit"
+    type: text
+    kind: data
+    means: "Package label for the Fisch tier 2 price. Blank when Odoo names no package."
+  - key: price_fisch_t3
+    label: "Fisch tier 3 price"
+    type: currency
+    kind: data
+    means: "Fisch price tier 3. Blank when Fisch prices this SKU at fewer than three tiers."
+  - key: unit_fisch_t3
+    label: "Fisch tier 3 unit"
+    type: text
+    kind: data
+    means: "Package label for the Fisch tier 3 price. Blank when Odoo names no package."
+  - key: price_royal1_t1
+    label: "Royal 1 tier 1 price"
+    type: currency
+    kind: data
+    means: "Royal 1 price tier 1, cheapest first. Blank when Royal 1 does not price this SKU."
+  - key: unit_royal1_t1
+    label: "Royal 1 tier 1 unit"
+    type: text
+    kind: data
+    means: "Package label for the Royal 1 tier 1 price. Blank when Odoo names no package."
+  - key: price_royal1_t2
+    label: "Royal 1 tier 2 price"
+    type: currency
+    kind: data
+    means: "Royal 1 price tier 2. Blank when Royal 1 prices this SKU at only one tier."
+  - key: unit_royal1_t2
+    label: "Royal 1 tier 2 unit"
+    type: text
+    kind: data
+    means: "Package label for the Royal 1 tier 2 price. Blank when Odoo names no package."
+  - key: price_royal1_t3
+    label: "Royal 1 tier 3 price"
+    type: currency
+    kind: data
+    means: "Royal 1 price tier 3. Blank when Royal 1 prices this SKU at fewer than three tiers."
+  - key: unit_royal1_t3
+    label: "Royal 1 tier 3 unit"
+    type: text
+    kind: data
+    means: "Package label for the Royal 1 tier 3 price. Blank when Odoo names no package."
+  - key: price_royal2_t1
+    label: "Royal 2 tier 1 price"
+    type: currency
+    kind: data
+    means: "Royal 2 price tier 1, cheapest first. Blank when Royal 2 does not price this SKU."
+  - key: unit_royal2_t1
+    label: "Royal 2 tier 1 unit"
+    type: text
+    kind: data
+    means: "Package label for the Royal 2 tier 1 price. Blank when Odoo names no package."
+  - key: price_royal2_t2
+    label: "Royal 2 tier 2 price"
+    type: currency
+    kind: data
+    means: "Royal 2 price tier 2. Blank when Royal 2 prices this SKU at only one tier."
+  - key: unit_royal2_t2
+    label: "Royal 2 tier 2 unit"
+    type: text
+    kind: data
+    means: "Package label for the Royal 2 tier 2 price. Blank when Odoo names no package."
+  - key: price_royal2_t3
+    label: "Royal 2 tier 3 price"
+    type: currency
+    kind: data
+    means: "Royal 2 price tier 3. Blank when Royal 2 prices this SKU at fewer than three tiers."
+  - key: unit_royal2_t3
+    label: "Royal 2 tier 3 unit"
+    type: text
+    kind: data
+    means: "Package label for the Royal 2 tier 3 price. Blank when Odoo names no package."
   - key: pre_book_qty
     label: "Pre-book qty"
     type: int
@@ -178,67 +321,72 @@ fields:
     kind: data
     means: "Units still owed on confirmed, not-fully-delivered wholesale goods orders, including already-due promises. Delivery-charge service lines are excluded."
   - key: rev_ytd
-    label: "Revenue YTD"
-    type: currency
-    kind: data
-    means: "Year-to-date revenue for this SKU, BU-scoped when the caller is."
-  - key: rev_ly
-    label: "Revenue LY"
-    type: currency
-    kind: data
-    means: "Same period last year — seasonal wholesale compares like for like."
-  - key: yoy_pct
-    label: "YoY %"
-    type: pct
-    kind: data
-    means: "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
-  - key: qty_ytd
-    label: "Units YTD"
-    type: int
-    kind: data
-    means: "Units sold year to date."
-  - key: orders_ytd
-    label: "Orders YTD"
-    type: int
-    kind: data
-    means: "Distinct orders containing this SKU, year to date."
-  - key: on_hand
-    label: "On hand"
-    type: int
-    kind: data
-    means: "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
-  - key: unit_cost
-    label: "Unit cost"
-    type: currency
-    kind: data
-    means: "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
-  - key: inv_value
-    label: "Stock value"
-    type: currency
-    kind: data
-    means: "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
-  - key: qty_ltm
-    label: "Units LTM"
-    type: int
-    kind: data
-    means: "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
-  - key: dos
-    label: "Days of supply"
-    type: int
-    kind: data
-    means: "Days of supply at the LTM rate; null means it never sells through. Consolidated; absent for a BU-scoped caller."
-  - key: cover_gap_d
-    label: "Cover gap (days)"
-    type: int
-    kind: data
-    means: "Days of supply minus lead time. Negative means it runs out before a reorder lands."
-  - key: stock_bucket
-    label: "Stock status"
-    type: select
-    kind: data
-    means: "Dead / excess / healthy bucket from the inventory module. Consolidated; absent for a BU-scoped caller."
-
-ai_context: >
-  The product CATALOGUE — the database labelled 'Odoo products'.
-  Use it for 'what do we sell', 'what does it cost' (first_cost/unit_cost), 'who supplies it', 'what is on hand' and the stock-coverage columns.
-  ⛔ Revenue and unit columns here are WINDOWED SNAPSHOTS (rev_ytd, qty_ltm); for any other window, or for line grain, go to sales_lines.
+    label: "Revenue YTD"
+    type: currency
+    kind: data
+    means: "Year-to-date revenue for this SKU, BU-scoped when the caller is."
+  - key: rev_ly
+    label: "Revenue LY"
+    type: currency
+    kind: data
+    means: "Same period last year — seasonal wholesale compares like for like."
+  - key: yoy_pct
+    label: "YoY %"
+    type: pct
+    kind: data
+    means: "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
+  - key: qty_ytd
+    label: "Units YTD"
+    type: int
+    kind: data
+    means: "Units sold year to date."
+  - key: orders_ytd
+    label: "Orders YTD"
+    type: int
+    kind: data
+    means: "Distinct orders containing this SKU, year to date."
+  - key: on_hand
+    label: "On hand"
+    type: int
+    kind: data
+    means: "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
+  - key: unit_cost
+    label: "Unit cost"
+    type: currency
+    kind: data
+    means: "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
+  - key: inv_value
+    label: "Stock value"
+    type: currency
+    kind: data
+    means: "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
+  - key: qty_ltm
+    label: "Units LTM"
+    type: int
+    kind: data
+    means: "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
+  - key: dos
+    label: "Days of supply"
+    type: int
+    kind: data
+    means: "Days of supply at the trailing twelve month rate, counting on hand plus inbound units as stock. Blank means there is no honest number: either the product sold nothing in the window and Stock status reads 'No recent sales', or the inventory read returned no row for it and Stock status reads 'No stock record'. A product that sold nothing and holds nothing reads 0, not blank. A business unit caller gets this column too, re-scoped: the shelf is the whole warehouse's, the rate is that unit's."
+  - key: cover_gap_d
+    label: "Cover gap (days)"
+    type: int
+    kind: data
+    means: "Days of supply minus lead time. Negative means it runs out before a reorder lands."
+  - key: stock_bucket
+    label: "Stock status"
+    type: select
+    kind: data
+    means: "Dead / excess / healthy bucket from the inventory module, off the same days of supply figure beside it. Two values are not coverage bands: 'Out of stock' keys on the real shelf rather than the inbound-inclusive figure, and 'No stock record' means the inventory read returned no row for this product, so its shelf is unknown rather than empty. A business unit caller gets this column too, re-scoped through that unit's own sales rate."
+  - key: created_on
+    label: "Record created"
+    type: date
+    kind: data
+    means: "The date this product record was created in Odoo. The same uniform records-created column the customer topic carries."
+
+ai_context: >
+  The product CATALOGUE — the database labelled 'Odoo products'.
+  Use it for 'what do we sell', 'what does it cost' (first_cost/unit_cost), 'who supplies it', 'what is on hand' and the stock-coverage columns.
+  ⛔ Revenue and unit columns here are WINDOWED SNAPSHOTS (rev_ytd, qty_ltm); for any other window, or for line grain, go to sales_lines.

platform/modules/customer_data.py

@@ -18,6 +18,9 @@ tie. Persistence: HF store key 'customer_lists'
 The user↔agent link (users.py 'agent' field) scopes the pool to that agent's book; users with
 no link (owner/CFO/admin) see the whole book.
 """
+import re
+from urllib.parse import quote_plus
+
 import core.odoo as O
 import core.periods as P
 import core.store as store
@@ -31,6 +34,57 @@ LIMIT = 500          # honest builder display cap — always shown with the full
 KEY = 'customer_lists'
 TABLE_KEY = 'customer_table_workspace'
 
+# ------------------------------------------------------------------ the Google Maps link
+#: The sentinel every blank connector attribute collapses to (`customers._partner_attrs` writes
+#: it; the client's `CONNECTOR_BLANK` renders it). It is a real, visible value on the grid, NOT a
+#: null — so an address builder that treats it as text pastes the literal string "(none)" into a
+#: query and sends the reader to a place called none.
+BLANK_ATTR = '(none)'
+
+#: A trailing ISO country code in parentheses, as `O.m2o_name(state_id)` yields it: Odoo's state
+#: names read "Texas (US)". ⚠ ANCHORED and UPPERCASE-ONLY on purpose. A greedy "strip the last
+#: parenthetical" would eat a legitimate name that happens to end in brackets, and there is no
+#: reason to risk that for a tidiness fix.
+_STATE_COUNTRY_SUFFIX = re.compile(r'\s*\([A-Z]{2,3}\)$')
+
+#: Google's documented Maps URLs endpoint for a place SEARCH. The same shape the client already
+#: builds for a pin (`customer-grid/mapProjection.ts`), so the two doors agree.
+MAPS_SEARCH_URL = 'https://www.google.com/maps/search/?api=1&query='
+
+
+def _addr_part(v):
+    """One address line, or '' — the sentinel and whitespace both read as absent."""
+    s = str(v or '').strip()
+    return '' if not s or s == BLANK_ATTR else s
+
+
+def maps_url(a):
+    """A Google Maps link to a partner's address, or '' when there is no address to point at.
+
+    ⭐⭐ W40-T08 (owner I27) — SERVER-SIDE, and that is the whole design, per the wave's AM-1. The
+    owner's instruction offered a client Formula as one option; D-115 says a formula column's
+    values exist only in the browser, so the link would be blank in every host-side export and
+    invisible to anything reading the stored cell. Computed here it is an ordinary cell value on
+    the pool row, so it exports, filters and reads back like any other column.
+
+    ⛔ BLANK UNLESS THE ROW CAN ACTUALLY BE LOCATED. The gate is street OR city OR zip: a country
+    alone ("United States") resolves to a link that opens the middle of a continent, which is
+    worse than an empty cell because it looks like an answer. MEASURED 2026-08-23: 140 of 3,641
+    customers have no street, city or zip, and those are the rows this returns '' for.
+
+    ⚠ `state` is stripped of its country suffix. It arrives as `O.m2o_name(state_id)`, i.e.
+    "Texas (US)", and the country is already its own part of the address. Google resolves the
+    string either way, so this is a tidiness call, not a correctness one.
+    """
+    street, street2 = _addr_part(a.get('street')), _addr_part(a.get('street2'))
+    city, zipcode = _addr_part(a.get('city')), _addr_part(a.get('zip'))
+    if not (street or city or zipcode):
+        return ''
+    state = _STATE_COUNTRY_SUFFIX.sub('', _addr_part(a.get('state')))
+    parts = [p for p in (street, street2, city, state, zipcode,
+                         _addr_part(a.get('country'))) if p]
+    return MAPS_SEARCH_URL + quote_plus(', '.join(parts))
+
 # ------------------------------------------------------------------ the metric pool
 # Field metadata for the rule builder: key -> (label, kind). 'num' fields take >=/<=/>/</=,
 # 'text' fields take contains/=. Every field is a column of pool() rows.
@@ -577,6 +631,19 @@ def _pool_build(agent_name, team_id, limit, fast=False):
             # Row-level datum for the `created_time` field type (wave-5 item 11) — rides every
             # row like pid, no column of its own until a user creates one.
             '_created': a.get('created_at', ''),
+            # ⭐⭐ W40-T08 (owner I24) — the DECLARED pre-set date column, beside the row datum
+            # above rather than instead of it. `_created` is only ever readable through a
+            # `created_time` column the user has to create; this is a real cell under its own key,
+            # so it exports, filters and appears in the semantic topic. Truncated the way
+            # `customer_since` is, and for the same reason: a date-typed column compared
+            # ISO-LEXICALLY drifts by the time component if the time is left on.
+            # ⚠ The value is IDENTICAL to `customer_since` on this database, because both come
+            # from `res.partner.create_date`. That is not a duplicate by accident: "Customer
+            # since" is a business fact about the relationship and cannot be the uniform
+            # records-created column I24 asks every database for (Products has no such notion).
+            'created_on': str(a.get('created_at') or '')[:10],
+            # ⭐⭐ W40-T08 (owner I27) — the Google Maps link, replacing the hardcoded "Go" column.
+            'maps_url': maps_url(a),
             'tags': a.get('tags', '(none)'), 'pricelist': a.get('pricelist', '(none)'),
             # AR / credit exposure — composed from the already-reconciled ar.py blocks, so the
             # Customer table and the Collections page cannot disagree.
@@ -679,7 +746,12 @@ def _reconcile_ledger(rows, total, agent_name, team_id):
                 'agent': '(none)', 'street': '(none)', 'street2': '(none)',
                 'city': '(none)', 'state': '(none)', 'country': '(none)',
                 'zip': '(none)', 'payment_terms': '(none)', 'customer_since': '',
-                '_created': '', 'tags': '(none)', 'pricelist': '(none)',
+                # W40-T08 lands on BOTH row templates, which is the warning above being obeyed
+                # rather than restated. A revived row has no address and no create_date to read,
+                # so both are blank — and blank is exactly what `maps_url` returns for an
+                # addressless customer anyway, so the archived rows agree with the live ones.
+                '_created': '', 'created_on': '', 'maps_url': '',
+                'tags': '(none)', 'pricelist': '(none)',
                 'ar_open': 0.0, 'ar_overdue': 0.0, 'ar_outstanding': 0.0, 'ar_exposure': 0.0,
                 'days_to_pay': None,
                 **{k: 0.0 for k in AR_BUCKET_FIELDS.values()},

platform/modules/inventory.py

@@ -14,11 +14,29 @@ import core.periods as P
 
 
 def _cat_main_map():
+    """{category id: MAIN category name}, the SECOND segment of Odoo's `complete_name` path.
+
+    THE ROOT MAPS TO `None`, NOT TO ITS OWN NAME (owner instruction 23, wave 40). Odoo roots the
+    whole category tree at one node whose `complete_name` is the bare word "All", and the old
+    `parts[0]` fallback handed that word out as though it were a category. It is not one: it is
+    the tree's root, and a product filed directly on it is UNCATEGORISED. Exactly one of the 74
+    categories is single segment, so the root is the only value that could ever reach this branch.
+
+    MEASURED live 2026-08-23: 3,334 of 5,841 coded products (57.1%) sit directly on the root, so
+    this is the MAJORITY of the catalogue and not an edge case.
+
+    `None` IS THE CONTRACT, and all three callers already honour it. `inventory._build`,
+    `financial._product_cat` and `sales._product_cat` each read this map through
+    `... or '(uncategorized)'`, which is the sentinel the product grid's own field description
+    already promises: "Product category; '(uncategorized)' when Odoo carries none". So the root's
+    products land on the DECLARED blank value instead of on an invented label, and no caller has
+    to learn a new convention.
+    """
     cats = O.search_read('product.category', [], ['id', 'complete_name'])
     out = {}
     for c in cats:
         parts = [x.strip() for x in (c['complete_name'] or '').split('/')]
-        out[c['id']] = parts[1] if len(parts) >= 2 else (parts[0] if parts else None)
+        out[c['id']] = parts[1] if len(parts) >= 2 else None
     return out
 
 
@@ -220,8 +238,33 @@ def _bucket(dos_raw, on_hand, qty_ltm):
     return _COVERAGE_BUCKETS[-1][0]
 
 
-# the coverage facet, worst→best, for the SKU directory filter
-COVERAGE_LABELS = ['Out of stock'] + [b[0] for b in _COVERAGE_BUCKETS] + ['No recent sales']
+#: ⭐ AM-4 (2026-08-23), BRANCH (c) — WHAT A SKU WITH NO INVENTORY ROW SAYS FOR ITSELF.
+#: `_bucket` never returns this and never can: it is `product_data._dos_with_inbound`'s answer for
+#: `on_hand is None`, a case that returns before `_bucket` is reached. It lives here, named, rather
+#: than as a literal there, because two places must spell it identically — the product row that
+#: carries it, and the permission editor's dropdown, which `routes_admin::
+#: _server_side_vocabularies` fills from the list below.
+#:
+#: ⛔ THE WORDING IS LOAD-BEARING, NOT DECORATION, and AM-4 is explicit about why.
+#: `product_data._inventory_by_code` degrades to `{}` on ANY failure, so during an inventory-read
+#: outage EVERY product in the catalogue renders this label at once. "Stock not tracked" would
+#: then be a catalogue-wide false claim about the warehouse, and "never sold" is false for most of
+#: these rows even on a good day. What is genuinely absent in BOTH cases — the ~33 products with
+#: no `default_code`, and an outage — is the RECORD, so that is what the label names.
+NO_STOCK_RECORD = 'No stock record'
+
+# Every value a `stock_bucket` cell can hold, and the vocabulary the permission editor offers for
+# that column (`routes_admin::_server_side_vocabularies` imports this rather than restating it).
+# The coverage BANDS run worst→best between the two ends; the last two are not on that axis at all
+# — 'No recent sales' is a full shelf nobody is buying from, and `NO_STOCK_RECORD` means there is
+# no reading of the shelf to band in the first place.
+# ⚠ THE ORDER IS FOR A READER OF THIS FILE, NOT A CONTRACT ANY SURFACE HONOURS. Measured
+# 2026-08-24: `routes_admin.py:868` re-sorts every supplied vocabulary alphabetically, and the
+# grid's own dropdown (`types.ts::choiceVocabulary`) discovers values from loaded ROWS and sorts
+# them too. Same SET on both, never this sequence. Do not add a label here expecting it to land in
+# a particular slot on screen.
+COVERAGE_LABELS = (['Out of stock'] + [b[0] for b in _COVERAGE_BUCKETS]
+                   + ['No recent sales', NO_STOCK_RECORD])
 
 
 def sku_inventory(target_days=180, carry_pct=_CARRY_PCT, t=None):

platform/modules/products.py

@@ -289,8 +289,13 @@ def catalogue():
     # to aggregate it (`Fault 2: Cannot aggregate field 'incoming_qty'`), so nothing downstream
     # may push a filter or a read_group on it back to Odoo. It is materialised into the pool here
     # and summed on our side; `validate()` reconciles that sum against purchase-order lines.
+    # ⭐⭐ W40-T08 (owner I24) — `create_date` RIDES THIS READ TOO, for the same reason the two
+    # above do. It has to come from the LIVE record: the DuckDB mirror's `product_product` carries
+    # `write_date` and NO `create_date`, so there is no cheaper source, and this read already pulls
+    # every active product once. MEASURED 2026-08-23 against live Odoo: 5,874 active products, of
+    # which 0 have a null `create_date`, so the column is populated for the whole catalogue.
     prods = O.search_read('product.product', dom,
-                          ['id', 'default_code', 'display_name', 'name',
+                          ['id', 'default_code', 'display_name', 'name', 'create_date',
                            'product_tag_ids', 'incoming_qty'],
                           limit=50000)
     n = O.get_odoo().search_count('product.product', dom)
@@ -323,13 +328,23 @@ def catalogue():
         # downstream in `aios_grid.py` and has to be carried from the source read.
         row = out.setdefault(code, {'product': p.get('display_name') or p.get('name') or code,
                                     'category': code_cat.get(code, '(uncategorized)'),
-                                    'id': p['id'],
+                                    'id': p['id'], 'created_at': '',
                                     'discontinued': 'No', 'incoming': 0.0})
         # ⛔ ACROSS EVERY RECORD SHARING THE CODE, not just the first one that won above. A SKU
         # whose variants are separate records carries its inbound on whichever record the PO named,
         # and 'first record wins' would drop the rest — a buy list that under-counts what is
         # already on the water tells you to re-order stock you have already bought.
         row['incoming'] += float(p.get('incoming_qty') or 0.0)
+        # ⭐ W40-T08 — the EARLIEST create_date across the records sharing this code, not the
+        # first record's. A row here is a SKU, and the honest answer to "when was this record
+        # created" for a merged SKU is when the earliest of its records appeared. Only `2112-12`
+        # is affected today (5,873 active products, 5,872 distinct codes), so this is a one-row
+        # policy call rather than a measurable difference; it is written down because the
+        # first-wins convention above would otherwise read as covering this key too.
+        # ⚠ Lexical `<` is a real date comparison here: Odoo datetimes are fixed-width ISO.
+        _cd = str(p.get('create_date') or '')
+        if _cd and (not row['created_at'] or _cd < row['created_at']):
+            row['created_at'] = _cd
         if disc_tag is not None and disc_tag in (p.get('product_tag_ids') or ()):
             row['discontinued'] = 'Yes'
     return out
@@ -432,6 +447,98 @@ PRICELIST_COLUMNS = (
     ("price_royal_2", "Royal 2"),
 )
 
+#: ⭐⭐ W40-T09 / RULING R6 (owner I25: *"Fisch price and Royal price each have 3 units and 3
+#: prices. Separate them and put all of them in the Odoo fields."*) — HOW MANY (price, unit)
+#: PAIRS EACH DECLARED LIST SHOWS.
+#:
+#: ⛔ THIS CONSTANT IS THE CAP, AND NAMING IT IS THE POINT. `tier_prices_by_code` below returns
+#: EVERY live tier a SKU has; only the WRITE into the grid is limited, and it is limited here in
+#: one place rather than by a `range(1, 4)` inlined at the call site the way the pooled
+#: `price_1..3` block was. MEASURED on the live book 2026-08-24 over 3,996 priced codes: exactly
+#: ONE SKU/list pair exceeds this depth — `6AB` on Fisch, which carries FOUR tiers — so raising
+#: this number to 4 is the whole of the fix if the owner ever wants that fourth cell. Max tiers
+#: observed per list: Fisch 4, Royal 1 3, Royal 2 3, Public Pricelist 1.
+PRICELIST_TIER_DEPTH = 3
+
+
+def _pricelist_slug(col):
+    """`price_royal_1` -> `royal1`, the token the per-list tier keys are built on.
+
+    ⛔ THE UNDERSCORE IS REMOVED DELIBERATELY, and it is not cosmetic. `price_royal_1` ALREADY
+    EXISTS and means "the Royal 1 list's base price", so a tier key of `price_royal_1_t1` shares
+    a prefix with a different column and is ambiguous to anyone diffing the contract by eye.
+    `price_royal1_t1` cannot be mistaken for a suffix of it.
+    """
+    return col[len("price_"):].replace("_", "")
+
+
+#: `[(price_key, unit_key, pricelist_name, tier_no)]` — the 18 columns R6 declares, DERIVED from
+#: `PRICELIST_COLUMNS` so this tenant's list names live in exactly one place. A fourth pricelist
+#: added above becomes six more tier columns here with no second edit.
+PRICELIST_TIER_COLUMNS = tuple(
+    (f"price_{_pricelist_slug(col)}_t{n}", f"unit_{_pricelist_slug(col)}_t{n}", name, n)
+    for col, name in PRICELIST_COLUMNS
+    for n in range(1, PRICELIST_TIER_DEPTH + 1)
+)
+
+
+def per_list_tier_cells(tiers):
+    """One SKU's `tier_prices_by_code` entry -> `{column_key: value}` for all 18 R6 cells.
+
+    ⭐⭐ THE WHOLE OF W40-T09, and it is a GROUP-BY, not a new read. `tier_prices_by_code`
+    already carries the pricelist NAME on every entry, so attributing prices to the list that
+    charges them costs nothing beyond this loop.
+
+    ⛔ **IT NEVER BORROWS.** A list this SKU is not priced on gets `None` in all six of its
+    cells — never the cheapest price from another list, never a fallback. That is R6's negative
+    control and it is the reason the pooled `price_1..3` block could not simply be relabelled:
+    those three are the cheapest three POOLED ACROSS ALL LISTS and unattributed, so on a SKU
+    priced only on Fisch they would put a Fisch price under a Royal heading.
+    MEASURED: `BOUT-WH` has three tiers, all Fisch, on NEITHER Royal list — one SKU that is
+    simultaneously the cheapest-first case and this negative control.
+
+    ⚠ CHEAPEST-FIRST IS GUARANTEED HERE, not inherited. `tier_prices_by_code` does sort its
+    lists globally by price, and a stable group-by would preserve that within each list — but a
+    caller handing in a fixture, or a future change to that sort key, would silently reorder the
+    cells. Sorting the group is one line and makes the guarantee local to the function that
+    makes it. The tiebreak matches the reader's: unit name, then list name.
+
+    ⚠ A LIST NOT IN `PRICELIST_COLUMNS` IS INVISIBLE HERE BY DESIGN — the columns are named
+    after the three lists the contract declares. MEASURED: 3 active SKUs are priced ONLY on
+    Public Pricelist, so they carry all eighteen cells empty. `tier_prices_by_code` still sees
+    those prices; nothing is lost from the honest set, only from these named columns.
+    """
+    grouped = {}
+    for tier in tiers or ():
+        grouped.setdefault(tier.get("pricelist"), []).append(tier)
+    for got in grouped.values():
+        got.sort(key=lambda t: (t.get("unit_price") or 0.0,
+                                str(t.get("unit") or "").lower(),
+                                str(t.get("pricelist") or "").lower()))
+    cells = {}
+    for price_key, unit_key, name, n in PRICELIST_TIER_COLUMNS:
+        got = grouped.get(name) or []
+        tier = got[n - 1] if len(got) >= n else None
+        cells[price_key] = tier.get("unit_price") if tier else None
+        cells[unit_key] = tier.get("unit") if tier else None
+    return cells
+
+
+def tier_cap_overflow(tiers):
+    """`{pricelist_name: how many tiers PRICELIST_TIER_DEPTH hides}` for one SKU, `{}` when none.
+
+    ⭐ STANDING RULE 1's SECOND SENTENCE, in code: *"if there is lag or it can't be done, you
+    need to explicitly tell me why and recommend a fix."* R6 declares three pairs per list, so a
+    fourth tier is dropped — and a dropped tier that nobody counts is the silent cap the rule
+    forbids. `validate_price_and_unit_cells` turns this into a named, reported figure.
+    """
+    counts = {}
+    for tier in tiers or ():
+        counts[tier.get("pricelist")] = counts.get(tier.get("pricelist"), 0) + 1
+    declared = {name for _p, _u, name, _n in PRICELIST_TIER_COLUMNS}
+    return {name: n - PRICELIST_TIER_DEPTH for name, n in counts.items()
+            if name in declared and n > PRICELIST_TIER_DEPTH}
+
 
 def pricelist_by_code():
     """`({code: {column_key: price}}, report)` — the date-valid FIXED base-tier price for each

web/public/sample_customers.json

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

web/src/customer-grid/ColumnMenu.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useRef, useState } from "react";
+import { Fragment, useMemo, useRef, useState } from "react";
 // ⭐ W36-T07 (owner item 10) — the field agent. Its own module for `ColumnMenu`'s own reason:
 // this file pulls the whole grid and cannot load under a node gate, so the chat had to sit
 // where a test can render it.
@@ -8,8 +8,16 @@ import { AnchoredOverlay } from "./OverlaySurface";
 import type { AnchorRect } from "./OverlaySurface";
 import { FieldTypeIcon, MenuLabel } from "./icons";
 import { FieldSelectButton } from "./FieldSelect";
+// ⭐⭐ W40-T24 — the pre-set definition lock. It lives in `display.ts` rather than here because a
+// rule stated inside JSX cannot be LOADED by a node gate; `display.ts`'s header carries the full
+// argument, and `_test/gridUx.test.ts` is what runs it.
+import { columnDefinitionOffer } from "./display";
+// ⭐⭐ W40-T29 — the ADVANCED grouping is a pure function in `types.ts` for the reason
+// `columnDefinitionOffer` sits in `display.ts`: this file imports React, so nothing stated inside
+// it can be LOADED by a node gate, and "which types are advanced" is exactly the kind of decision
+// that must be runnable rather than read back to itself as source text.
 import { CODE_LANGUAGE_LABELS, CODE_LANGUAGES, CREATABLE_TYPES, choiceOptions, choiceRenames,
-  codeLanguageOf, directionLabel, isDerivedLink, isMachineOwned,
+  codeLanguageOf, directionLabel, groupTypePickerRows, isDerivedLink, isMachineOwned,
   isProfileField, parseOptions, ratingMax, ROLLUP_FN_LABELS, ROLLUP_FNS,
   ROLLUP_REF_OPS, mayEditFieldDefinition } from "./types";
 import type { AggName, Field, FieldFormat, FieldScope, FieldType, Measure, RollupCondition, RollupFn,
@@ -18,7 +26,7 @@ import type { LinkTarget, RollupSourceOffer } from "./apiBridge";
 import type { WindowSpec } from "./windows";
 import { normalizeWindow, windowLabel } from "./windows";
 import { WindowPicker } from "../filter-kit";
-import { TYPE_LABELS } from "./iconShapes";
+import { SHARE_SHAPE, TYPE_LABELS } from "./iconShapes";
 import { AGG_LABELS, aggOptions } from "./aggregations";
 import { validateFormula } from "./formulaEngine";
 import { BRAND_SWATCHES, defaultOptionColor, nearestSwatch, normalizeOptionColor,
@@ -135,6 +143,16 @@ interface ColumnMenuProps {
   locked: boolean;
   /** Product-owned preset fields may still drive view actions, but their schema is immutable. */
   schemaLocked?: boolean;
+  /**
+   * ⭐⭐ W40-T24 — the grid is a `ut_*` runtime database rather than an Odoo-backed topic. It
+   * feeds `columnDefinitionOffer` (display.ts), which is this menu's ONE statement of the pre-set
+   * definition lock, and EVERY verdict reads it: a shared-definition column on a user database is
+   * the user's to reshape, and the identical shape on an Odoo-backed topic is not.
+   * ⚠ OPTIONAL and false by default only for the "+" create instance, which has no real subject
+   * column — it passes `locked`, so its verdicts are the closed ones either way. A real column
+   * menu must pass it; defaulting is a convenience for the create door, not a shrug.
+   */
+  isUserTable?: boolean;
   /** Wave-5 item 1 — who is looking. Gates the permissions entry (creator-or-admin). */
   viewer?: Viewer;
   /** Wave-5 item 3 — what the CURRENT VIEW does with this field, so the conditional
@@ -879,8 +897,18 @@ type CreateKind = FieldType | "measure" | "geocode";
  * of them end up disagreeing about what is offered.
  * ⚠ NO DASH of any kind in the label — it reaches the screen, and `web_prose` cannot see a
  * wrapped JSX sentence, so this one is on the author.
+ *
+ * ⭐⭐ W40-T29 (owner instruction 31) — SHORTENED TO ONE NOUN. The label used to carry a trailing
+ * clause naming where the numbers come from, which is the IMPLEMENTATION read out at someone
+ * scanning a list of nouns; every other row in that list is the thing you get, not how it is got,
+ * and the source column is picked one control later anyway. The old wording is not repeated here:
+ * a rename that leaves its own before-picture in a doc block is how the next reader reinstates it,
+ * and `_test/gridUx.test.ts` asserts the whole file is free of it.
+ * ⚠ THE IDENTIFIER STAYS. One producer, one consumer, and `verify_grid_ux.py`'s geocode-door scan
+ * matches `label: GEOCODE_LABEL` BY NAME, so inlining the string here would blind the gate rather
+ * than satisfy it.
  */
-const GEOCODE_LABEL = "Coordinates from an address";
+const GEOCODE_LABEL = "Coordinates";
 const GEOCODE_ADDRESS_TYPES: readonly FieldType[] = ["text", "url", "email", "phone"];
 
 /**
@@ -941,6 +969,11 @@ function TypePicker({
       ? [{ value: "geocode" as CreateKind, label: GEOCODE_LABEL }]
       : []),
   ].filter((r) => !needle || r.label.toLowerCase().includes(needle));
+  // ⭐⭐ W40-T29 (owner instruction 31) — the list stopped being a wall of 22 nouns here, and the
+  // grouping is applied to the ALREADY-FILTERED rows on purpose: one find box still reaches both
+  // groups, and a group the needle empties is dropped by `groupTypePickerRows` heading and all
+  // rather than leaving a label with nothing behind it (R8).
+  const groups = groupTypePickerRows(rows);
   return (
     <div className="cg-type-picker">
       <div className="cg-type-search">
@@ -962,44 +995,64 @@ function TypePicker({
         />
       </div>
       <div className="cg-type-list" role="listbox" aria-label="Field type">
-        {rows.map((r) => (
-          <button
-            key={r.value}
-            type="button"
-            role="option"
-            aria-selected={value === r.value}
-            className={"cg-type-row" + (value === r.value ? " is-on" : "")}
-            onClick={() => onPick(r.value)}
-          >
-            {/* Each row wears the mark its COLUMN will wear. A measure column's real type is
-                currency/int/pct and a geocode column's is `text`, so both pseudo-kinds borrow
-                rather than inventing a glyph no column ever shows (the iconShapes ruling). */}
-            <FieldTypeIcon
-              type={
-                r.value === "measure" ? "currency" : r.value === "geocode" ? "text" : r.value
-              }
-              size={16}
-            />
-            <span className="cg-type-label">{r.label}</span>
-            {value === r.value && (
-              <svg
-                className="cg-type-check"
-                width="14"
-                height="14"
-                viewBox="0 0 16 16"
-                fill="none"
-                aria-hidden="true"
+        {groups.map((group) => (
+          // ⛔ A FRAGMENT, NOT A WRAPPER, and the reason is an accessibility one rather than a
+          // layout one. `.cg-type-list` is the flex column that lays the rows out, so a wrapping
+          // div would need `display: contents` to stay out of the way — which DROPS the element
+          // from the accessibility tree, inside the one container that is claiming to be a
+          // listbox. `FieldSelect.tsx` reached this conclusion first for its own grouped list
+          // ("Pre-set fields" / "Your fields" / "New field"); this follows it rather than
+          // inventing a second answer to a question the codebase already settled.
+          // ⚠ The heading is `role="presentation"` for the same reason: a listbox's children are
+          // options, and a bare div claiming nothing is what keeps the heading out of the option
+          // set while leaving it visible. Arrow-key navigation elsewhere collects
+          // `button.cg-type-row`, so a non-button child is invisible to it by construction.
+          <Fragment key={group.heading ?? "ordinary"}>
+            {group.heading && (
+              <div className="cg-type-group" role="presentation">
+                {group.heading}
+              </div>
+            )}
+            {group.rows.map((r) => (
+              <button
+                key={r.value}
+                type="button"
+                role="option"
+                aria-selected={value === r.value}
+                className={"cg-type-row" + (value === r.value ? " is-on" : "")}
+                onClick={() => onPick(r.value)}
               >
-                <path
-                  d="m3.5 8.5 3 3 6-6.5"
-                  stroke="currentColor"
-                  strokeWidth="1.6"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
+                {/* Each row wears the mark its COLUMN will wear. A measure column's real type is
+                    currency/int/pct and a geocode column's is `text`, so both pseudo-kinds borrow
+                    rather than inventing a glyph no column ever shows (the iconShapes ruling). */}
+                <FieldTypeIcon
+                  type={
+                    r.value === "measure" ? "currency" : r.value === "geocode" ? "text" : r.value
+                  }
+                  size={16}
                 />
-              </svg>
-            )}
-          </button>
+                <span className="cg-type-label">{r.label}</span>
+                {value === r.value && (
+                  <svg
+                    className="cg-type-check"
+                    width="14"
+                    height="14"
+                    viewBox="0 0 16 16"
+                    fill="none"
+                    aria-hidden="true"
+                  >
+                    <path
+                      d="m3.5 8.5 3 3 6-6.5"
+                      stroke="currentColor"
+                      strokeWidth="1.6"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                )}
+              </button>
+            ))}
+          </Fragment>
         ))}
         {rows.length === 0 && <div className="cg-pop-note">No matching type.</div>}
       </div>
@@ -2000,6 +2053,7 @@ export default function ColumnMenu({
   geocodable,
   locked,
   schemaLocked = false,
+  isUserTable = false,
   viewer,
   sortedDir,
   isFiltered,
@@ -2038,6 +2092,18 @@ export default function ColumnMenu({
   measures = [],
   tableKey,
 }: ColumnMenuProps) {
+  /**
+   * ⭐⭐ W40-T24 (owner instruction 18, contract C2) — the pre-set DEFINITION lock, read from the
+   * one place that states it. `display.ts` carries the whole argument, including the measured
+   * reason the lock is spelt `isUserSchemaField` and NOT `isPresetField` (nine product_data
+   * contract columns, Supplier among them, are declared `source: "overlay"` so that their cells
+   * stay typeable, and `isPresetField` answers false for every one).
+   *
+   * ⚠ ONLY `swap` AND `remove` ARE READ HERE, and that is the design, not an omission: `rename`
+   * and `retype` are already enforced at the host by withholding their handlers, and a second
+   * refusal in this file could only subtract from a door the host deliberately opened.
+   */
+  const offer = columnDefinitionOffer(field, { isUserTable, isPrimary: locked });
   const canEditDefinition = !schemaLocked && mayEditFieldDefinition(field, viewer);
   const [pane, setPane] = useState<MenuPane>(
     schemaLocked || (initialPane === "edit" && !canEditDefinition)
@@ -2600,6 +2666,23 @@ export default function ColumnMenu({
    */
   const editingRelational =
     !!onFieldConfig && (field.type === "rollup" || field.type === "link");
+  /**
+   * ⭐⭐ W40-T24 — WHERE THE EDIT PANE'S OPENING FOCUS LANDS, decided ONCE.
+   *
+   * `AnchoredOverlay`'s `initialFocus` is the selector `[data-overlay-autofocus]` and it does
+   * `querySelector(...)?.focus()` — a MISS is silent, and focus then stays on the grid header
+   * button behind the overlay. That is what removing the swap picker from a pre-set column would
+   * have caused: the picker carried `overlayAutofocus={!onRename}`, so on Supplier it WAS the
+   * pane's focus target, and taking it away leaves a dialog nobody's keyboard is inside. The
+   * defect would not show in a screenshot of the fix.
+   *
+   * Precedence, first match wins, exactly as `querySelector` reads the DOM: the editable Name box
+   * · the swap picker · the Description box, which is the one control a pre-set column still owns.
+   * ⚠ It also settles a latent double-marking: an `editingRelational` column with no `onRename`
+   * put the attribute on the Name box AND the picker, and which one won was document order rather
+   * than a decision.
+   */
+  const nameIsFocusTarget = !!onRename || editingRelational;
   const editRollupValid =
     field.type !== "rollup" ||
     (editRollup.source
@@ -2729,10 +2812,15 @@ export default function ColumnMenu({
    * the overlay stratum and user-created columns. Hidden fields included in both: "change this
    * to Notes" is the whole point, and swapping BACK to a hidden custom field is the documented
    * restore path. The locked primary column cannot be swapped.
+   *
+   * ⭐⭐ W40-T24 — NOR CAN A PRE-SET ONE, which is `offer.swap`. This list is what the picker
+   * would contain; `swapOffered` is whether the picker exists at all, and it is read twice (the
+   * control itself, and the focus fallback that has to know whether the control is there).
    */
   const swapOptions = fields.filter((f) => f.key !== field.key);
   const presetSwap = swapOptions.filter((f) => f.source === "odoo" && !f.custom);
   const yourSwap = swapOptions.filter((f) => !(f.source === "odoo" && !f.custom));
+  const swapOffered = offer.swap && swapOptions.length > 0;
 
   // Item 8c — the period draft is valid when it normalizes and differs from what the field
   // already has. Compared through normalizeWindow so `{kind:'ltm'}` and `{kind:'ltm', n:undefined}`
@@ -3099,7 +3187,7 @@ export default function ColumnMenu({
       >
         <PaneHead title="Edit field" sub={typeLine} onClose={onClose} />
         <div className="cg-column-create cg-field-edit">
-          {onRename || editingRelational ? (
+          {nameIsFocusTarget ? (
             <label>
               <span>Name</span>
               <input
@@ -3132,9 +3220,19 @@ export default function ColumnMenu({
                 Default description: {field.description}
               </span>
             )}
+            {/* ⭐⭐ W40-T24 — LAST IN THE FOCUS PRECEDENCE, and the only reason it is marked at
+                all: on a pre-set column the Name box is disabled and the swap picker is now
+                gone, so without this the pane would open with `[data-overlay-autofocus]` matching
+                nothing and the keyboard left outside the dialog. The Description is the one
+                control a pre-set column still owns, which makes it the honest landing spot as
+                well as the available one. `undefined` REMOVES the attribute (React drops it), so
+                exactly one element in the pane ever carries it. */}
             <textarea
               className="cg-input"
               rows={3}
+              data-overlay-autofocus={
+                !nameIsFocusTarget && !swapOffered ? true : undefined
+              }
               value={note}
               placeholder={
                 field.description
@@ -3441,8 +3539,18 @@ export default function ColumnMenu({
               Back
             </button>
           </div>
-          {/* -------- Change field (owner item 9, folded in here by owner item 8) -------- */}
-          {!locked && swapOptions.length > 0 && (
+          {/* -------- Change field (owner item 9, folded in here by owner item 8) --------
+              ⭐⭐ W40-T24 (owner instruction 18, contract C2) — GATED ON THE PRE-SET LOCK, which
+              it never was. The condition here used to be `!locked` alone, and `locked` means
+              "is the pinned primary column" — so every contract column on every grid offered to
+              be redefined into something else, which is the "choose a field dropdown that makes
+              no sense" the owner reported about Supplier and was never only about Supplier.
+              It is the SAME predicate that already withholds the Field-type picker and the
+              editable Name box, which is what makes this pane say one thing about the column
+              instead of three. `offer.swap` carries the `!locked` half (the primary column is the
+              row identity and can never be swapped away); `swapOptions.length > 0` stays because
+              an empty picker is its own fake affordance. */}
+          {swapOffered && (
             <div className="cg-edit-swap">
               <span className="cg-type-title">Change field</span>
               <div className="cg-field-hint">
@@ -3459,8 +3567,10 @@ export default function ColumnMenu({
                   ariaLabel="Change this column to another field"
                   placeholder="Choose a field…"
                   // Focus falls here when the pane has no editable Name (a read-only source
-                  // field): the swap picker is then the pane's first live control.
-                  overlayAutofocus={!onRename}
+                  // field): the swap picker is then the pane's first live control. Second in the
+                  // precedence `nameIsFocusTarget` documents, and reading THAT rather than
+                  // `!onRename` is what keeps the attribute on exactly one element.
+                  overlayAutofocus={!nameIsFocusTarget}
                   value={swapTo || undefined}
                   onChange={setSwapTo}
                   fields={[
@@ -3880,21 +3990,37 @@ export default function ColumnMenu({
             {/* ⛔ AN INLINE NODE, NOT A `MenuIcon` NAME, and that is forced rather than chosen.
                  `MenuLabel`'s prop is `MenuIconName | ReactNode` and `ReactNode` admits any
                  string, so `icon="share"` would COMPILE and paint an empty 16px box forever
-                 (`MENU_ICONS` has no such key, and `icons.tsx` is not this ticket's file). The
-                 three-node graph is the mark every product uses for this verb; it keeps sharing
-                 visually distinct from field editing. */}
+                 (`MENU_ICONS` has no such key, and `icons.tsx` is not this ticket's file).
+                 ⭐⭐ W40-T24 — THE GEOMETRY IS `SHARE_SHAPE`, NOT A THREE-NODE GRAPH ANY MORE.
+                 The argument that stood here — that the graph is "the mark every product uses for
+                 this verb" — was true of a product where it was the only share drawing. It is not
+                 any more: W40-T20 put `SHARE_SHAPE` (two people) on the grid header's shared-field
+                 sprite and W40-T21 put it on Share view and Share folder, so this row was the last
+                 place one verb spoke in a second drawing — a field whose HEADER wears two people,
+                 shared from a row wearing a graph. DESIGN.md §4's "one mark, one meaning" is the
+                 rule and `iconShapes.ts` is the vocabulary; paths as DATA is what stops the two
+                 painters drifting, which is exactly what a hand-written copy here would restart.
+                 ⚠ Rendered the way `ViewSidebar.ShareMark` renders it — same viewBox, same 1.35
+                 stroke, same round caps — so the rail's share and this one are one mark and not
+                 two readings of one array. */}
             <MenuLabel
               icon={
-                <svg width={16} height={16} viewBox="0 0 16 16" fill="none" aria-hidden>
-                  <circle cx="12" cy="3.6" r="1.9" stroke="currentColor" strokeWidth={1.3} />
-                  <circle cx="4" cy="8" r="1.9" stroke="currentColor" strokeWidth={1.3} />
-                  <circle cx="12" cy="12.4" r="1.9" stroke="currentColor" strokeWidth={1.3} />
-                  <path
-                    d="m5.75 7.1 4.5-2.6M5.75 8.9l4.5 2.6"
-                    stroke="currentColor"
-                    strokeWidth={1.3}
-                    strokeLinecap="round"
-                  />
+                <svg width={16} height={16} viewBox="0 0 16 16" aria-hidden>
+                  {SHARE_SHAPE.map((s) =>
+                    s.fill ? (
+                      <path key={s.d} d={s.d} fill="currentColor" />
+                    ) : (
+                      <path
+                        key={s.d}
+                        d={s.d}
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth={1.35}
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                      />
+                    )
+                  )}
                 </svg>
               }
               text="Share field"
@@ -4051,7 +4177,18 @@ export default function ColumnMenu({
             </button>
           </>
         )}
-        {!schemaLocked && onDelete && (
+        {/* ⭐⭐ W40-T24 (contract C2) — `offer.remove` IS THE PRE-SET LOCK, ADDED BESIDE the two
+            conditions that were already here rather than replacing either. `onDelete` asks
+            whether the host wired a delete DOOR at all (it has three, one per stratum) and
+            `schemaLocked` is `CustomerGrid.isSchemaLocked`; AND-ing a third refusal can only
+            subtract, so nothing is duplicated and no working delete is widened.
+            ⚠ On the Odoo grids this is behaviour-neutral: a pre-set column already had no door,
+            so Delete never rendered. What changes is that the absence is now the LOCK's answer
+            rather than a coincidence of wiring, which is the half of D-413 the client can settle.
+            ⚠ The pre-set ROLLUP keeps its Delete, by the 2026-08-09 owner ruling `isSchemaLocked`
+            already carries. `columnDefinitionOffer` restates that exception rather than dropping
+            it — see its note. */}
+        {!schemaLocked && offer.remove && onDelete && (
           <button
             type="button"
             className="is-danger"

web/src/customer-grid/cells.ts

@@ -1,807 +1,815 @@
-// ---------------------------------------------------------------------------
-// customer-grid / cells.ts
-// The ONLY place that turns a (field, value) into a glide GridCell. glide has
-// no per-column formatter — all formatting is per-cell here, in getCellContent.
-//
-//  currency/int -> NumberCell (raw number kept for copy/paste, right-aligned)
-//  pct          -> NumberCell showing v.toFixed(1)+"%" (yoy_pct is already in percent-points)
-//  date         -> TextCell   (locale date string; read-only, no picker in core)
-//  status       -> BubbleCell (Airtable-style colored pill via themeOverride)
-//  checkbox     -> BooleanCell (wave-5 item 11; overlay stores '1' or '')
-//  url          -> UriCell    (renders as a link; opening is CustomerGrid's click path)
-//  phone/email  -> TextCell   (actionable links in the record drawer)
-//  rating       -> Custom     (canvas-drawn stars — SVG/vector paths, NEVER emoji)
-//  created_time -> TextCell   (read-only; the row's `_created`, injected at its key)
-//  formula      -> NumberCell (client-computed, read-only; blank = could not compute)
-//  text/other   -> TextCell
-//
-// Wave-5 item 10: `field.format` shapes the DISPLAY string (thousands /
-// decimals 0..4 / 34.0M abbreviation for numbers; include-time + local|utc
-// for dates). A field with NO format renders byte-identically to before the
-// format existed — parity is asserted by keeping the default paths in terms
-// of the same toLocaleString calls.
-//
-// Editability is the CALLER's decision (permissions + stratum + type); this
-// module just applies the flag it is handed.
-// ---------------------------------------------------------------------------
-
-import { GridCellKind } from "@glideapps/glide-data-grid";
-import type {
-  CustomCell,
-  CustomRenderer,
-  GridCell,
-  Theme,
-} from "@glideapps/glide-data-grid";
-import { assetUrl } from "./catalogData";
-import type { Field } from "./types";
-import { ratingMax } from "./types";
-import {
-  LP_BLUE_TEXT,
-  LP_BLUE_TINT,
-  LP_GREEN_DEEP,
-  LP_GREEN_TINT,
-  LP_RED_DEEP,
-  LP_RED_TINT,
-  LP_YELLOW_DEEP,
-  LP_YELLOW_TINT,
-  STATUS_BUBBLE,
-} from "./theme";
-// ⚠ ALIASED: this module has its own `pickTint` (the bubble table above) and choiceColors has
-// another. C-AVATAR names choiceColors' as the avatar fallback's source, so the two stay
-// distinguishable at the call site rather than one silently shadowing the other.
-import { optionTint, pickTint as choicePickTint } from "./choiceColors";
-import { automationState, avatarInitials, avatarSize, checkboxOn, dateTimeText, formulaIsBlank,
-  codePreview, formulaIsText, jsonPreview, num, numberText, numericIsBlank,
-  userCellPayload } from "./display";
-import type { AutomationState, CellValue, UserCellData } from "./display";
-
-// Wave-7 (item W2): the pure display-string half moved to display.ts so the
-// export builders can run under node without dragging glide along. Re-exported
-// here so every existing import keeps working unchanged.
-export { checkboxOn, dateTimeText, formatDisplay } from "./display";
-// C-AVATAR — the pure halves live in display.ts (node-reachable, so a gate can hold them);
-// re-exported here so callers keep importing "the cell module" for everything avatar-shaped.
-export { avatarInitials, avatarSize, userCellPayload } from "./display";
-export type { UserCellData } from "./display";
-// C5-AUTOFIELD — same arrangement: the string parsing is pure and lives in display.ts (a node
-// gate can hold it); only the canvas tint table below needs this module.
-export { automationDetail, automationState, automationStateLabel } from "./display";
-export type { AutomationState } from "./display";
-// Wave-23 C7 — same arrangement again: the parse, the preview and the pretty-printer are pure
-// (`verify_grid_ux` drives them under node); only the canvas cell below needs this module.
-export { codePreview, jsonParse, jsonPretty, jsonPreview, MAX_JSON_BYTES } from "./display";
-
-/**
- * Wave-18 C5-AUTOFIELD — the cell tint per automation state.
- *
- * Standing brand rule: the PASTEL is the fill and the measured `-deep` variant carries the ink.
- * `bgCell` + `textDark` is that pairing at cell scale, and every combination below is one of the
- * pairs already measured for `STATUS_BUBBLE` (≥ 4.9:1), so nothing new needed measuring.
- *
- * `none` deliberately has NO override: a cell that has never run reads as an ordinary empty
- * cell, because a tint would claim the automation had produced something.
- */
-const AUTOMATION_TINT: Record<AutomationState, Partial<Theme> | undefined> = {
-  ok: { bgCell: LP_GREEN_TINT, textDark: LP_GREEN_DEEP },
-  partial: { bgCell: LP_YELLOW_TINT, textDark: LP_YELLOW_DEEP },
-  blocked: { bgCell: LP_YELLOW_TINT, textDark: LP_YELLOW_DEEP },
-  error: { bgCell: LP_RED_TINT, textDark: LP_RED_DEEP },
-  queued: { bgCell: LP_BLUE_TINT, textDark: LP_BLUE_TEXT },
-  none: undefined,
-};
-
-/** Stable pill tint for a user-defined choice. Hashed from the VALUE, so the same choice keeps
- *  its colour across rows, sessions and users without anyone picking one — and a renamed option
- *  simply gets a new colour rather than inheriting a stale mapping. */
-const PICK_TINTS = [
-  // 2026-07-31 (owner item 7): ONE construction — every pill is a `-tint` wash carrying its
-  // family's `-deep` ink, the standing brand rule ("pastels are fills; text takes the deep
-  // weight"). The old second pass (full pastel + near-black ink) is GONE: it is what read as
-  // "black font on a saturated chip". Six families now — the four C1 hues, the brand purple,
-  // and a neutral grey — all mirrored from index.css tokens; every pairing measures ≥ 5.0:1.
-  { bg: "#EDF3FD", fg: "#4F6079" },   // blue-tint  / LP_BLUE_TEXT
-  { bg: "#EBF6EF", fg: "#35754E" },   // green-tint / green-deep
-  { bg: "#FBF4E0", fg: "#7E6428" },   // yellow-tint/ yellow-deep
-  { bg: "#FCEEEC", fg: "#A3453C" },   // red-tint   / red-deep
-  { bg: "#F1EEFB", fg: "#6B57A8" },   // purple-tint/ purple-deep (--lp-purple family)
-  { bg: "#EEF1F4", fg: "#4B5563" },   // neutral wash / slate — the sixth distinct family
-];
-
-export function pickTint(v: string): { bg: string; fg: string } {
-  let h = 0;
-  for (let i = 0; i < v.length; i += 1) h = (h * 31 + v.charCodeAt(i)) >>> 0;
-  return PICK_TINTS[h % PICK_TINTS.length];
-}
-
-// --- rating: a canvas-drawn star row (owner constant: vector, never emoji) --
-
-export interface RatingCellData {
-  kind: "aios-rating";
-  /** 0 = unset (draws all-empty outlines). */
-  value: number;
-  max: number;
-}
-export type RatingCell = CustomCell<RatingCellData>;
-
-function drawStar(
-  ctx: CanvasRenderingContext2D,
-  cx: number,
-  cy: number,
-  r: number,
-  filled: boolean
-): void {
-  ctx.beginPath();
-  for (let i = 0; i < 10; i += 1) {
-    const rad = (Math.PI / 5) * i - Math.PI / 2;
-    const rr = i % 2 === 0 ? r : r * 0.45;
-    const px = cx + Math.cos(rad) * rr;
-    const py = cy + Math.sin(rad) * rr;
-    if (i === 0) ctx.moveTo(px, py);
-    else ctx.lineTo(px, py);
-  }
-  ctx.closePath();
-  if (filled) {
-    // I7c: C1's yellow is a FILL token (1.38:1) and a star has to be seen, so the
-    // filled star rides the deep amber variant: 3.29:1 on white, clearing the 3:1
-    // non-text bar the old gold #C8A24B never did (it measured 2.41:1).
-    ctx.fillStyle = "#A98A3E";
-    ctx.fill();
-  } else {
-    ctx.strokeStyle = "rgba(118, 143, 182, 0.55)"; // blue-deep outline, empty slots
-    ctx.lineWidth = 1;
-    ctx.stroke();
-  }
-}
-
-// --- user: the assignee AVATAR (wave-14 item 11 / R6 / contract C-AVATAR) -----
-//
-// R6: a grid cell shows the PHOTO OR ICON ONLY — no name text. (Pickers and the record modal
-// are where a name belongs; the column is a glanceable "who owns this", and thirty repetitions
-// of "Farhan Sanyoto" down a column is the thing the owner asked to stop reading.)
-//
-// The name is still the cell's COPY value. An avatar-only cell with no `copyData` makes an
-// assignee column copy as nothing — a real regression that no screenshot shows.
-
-export type UserCell = CustomCell<UserCellData>;
-
-/**
- * Decoded avatar images, keyed by their data URL. `null` = this URL failed to decode, so we
- * stop retrying it and paint the fallback forever (a corrupt stored photo must not spin).
- *
- * ⚠ Module scope, like the tint tables above: an Image per cell per frame would re-decode a
- * base64 payload on every scroll tick.
- */
-const _avatarImgs = new Map<string, HTMLImageElement | null>();
-let _avatarRepaint: (() => void) | undefined;
-
-/**
- * ⚠ THE HALF THAT IS EASY TO FORGET. glide repaints when `getCellContent`'s identity changes —
- * it knows nothing about an `Image.onload` that fires three frames later. Without this hook the
- * fallback initials paint once and STAY, and because the fallback is a deliberate, correct-looking
- * design, nothing on screen says the photo never arrived. (Same shape as wave-13's "honest empty
- * state that made the failure look deliberate".)
- *
- * CustomerGrid calls this once and bumps a counter that is in `useGetCellContent`'s deps.
- */
-export function setAvatarRepaint(fn: (() => void) | undefined): void {
-  _avatarRepaint = fn;
-}
-
-function avatarImage(dataUrl: string): HTMLImageElement | null {
-  const hit = _avatarImgs.get(dataUrl);
-  if (hit !== undefined) return hit;
-  // A DOM-less environment (a node gate, a locked-down embed) has no Image constructor. Cache
-  // the refusal so the fallback is what paints, rather than throwing inside a draw call.
-  if (typeof Image === "undefined") {
-    _avatarImgs.set(dataUrl, null);
-    return null;
-  }
-  const img = new Image();
-  _avatarImgs.set(dataUrl, img);
-  img.onload = () => _avatarRepaint?.();
-  img.onerror = () => {
-    _avatarImgs.set(dataUrl, null);
-    _avatarRepaint?.();
-  };
-  img.src = dataUrl;
-  return img;
-}
-
-/** C-AVATAR — the circle, photo or not. Exported so any other canvas surface paints the same
- *  avatar rather than growing a second almost-matching one. */
-export function drawAvatar(
-  ctx: CanvasRenderingContext2D,
-  cx: number,
-  cy: number,
-  r: number,
-  name: string,
-  photo: string | undefined,
-  fontFamily: string
-): void {
-  const img = photo ? avatarImage(photo) : null;
-  // `complete` alone is not enough: a FAILED decode is also "complete", with a zero natural size.
-  if (img && img.complete && img.naturalWidth > 0) {
-    ctx.save();
-    ctx.beginPath();
-    ctx.arc(cx, cy, r, 0, Math.PI * 2);
-    ctx.clip();
-    // COVER, not contain: a portrait must fill the circle, not sit letterboxed inside it.
-    const scale = Math.max((r * 2) / img.naturalWidth, (r * 2) / img.naturalHeight);
-    const w = img.naturalWidth * scale;
-    const h = img.naturalHeight * scale;
-    ctx.drawImage(img, cx - w / 2, cy - h / 2, w, h);
-    ctx.restore();
-    return;
-  }
-  // The fallback, and it is the DEFAULT state until HOST's C-AVATAR lands — never a broken-image
-  // glyph. Hashed from the full name so one person keeps one colour across rows and sessions.
-  const tint = choicePickTint(name);
-  ctx.save();
-  ctx.beginPath();
-  ctx.arc(cx, cy, r, 0, Math.PI * 2);
-  ctx.fillStyle = tint.bg;
-  ctx.fill();
-  ctx.fillStyle = tint.fg;
-  ctx.font = `600 ${Math.round(r * 0.9)}px ${fontFamily}`;
-  ctx.textAlign = "center";
-  ctx.textBaseline = "middle";
-  ctx.fillText(avatarInitials(name), cx, cy + 0.5);
-  ctx.restore();
-}
-
-/** Registered once on the DataEditor (customRenderers), beside the rating renderer. */
-export const userCellRenderer: CustomRenderer<UserCell> = {
-  kind: GridCellKind.Custom,
-  isMatch: (cell): cell is UserCell =>
-    (cell.data as UserCellData | undefined)?.kind === "aios-user",
-  draw: (args, cell) => {
-    const { ctx, rect, theme } = args;
-    const { name, photo } = cell.data;
-    if (!name) return true; // unassigned paints nothing — an empty circle would look assigned
-    const d = avatarSize(rect.height);
-    const cx = rect.x + theme.cellHorizontalPadding + d / 2;
-    const cy = rect.y + rect.height / 2;
-    // Never paint outside the cell: a column dragged narrow drops the avatar rather than
-    // bleeding it over its neighbour.
-    if (cx + d / 2 > rect.x + rect.width - theme.cellHorizontalPadding) return true;
-    drawAvatar(ctx, cx, cy, d / 2, name, photo, theme.fontFamily);
-    return true;
-  },
-};
-
-// --- image: the record THUMBNAIL (wave-19 R7 / contract C5) -------------------
-//
-// The cell holds a REFERENCE, never bytes (`types.ts: imageRefKind`), so what paints here is an
-// <img> the browser fetches from the asset routes and caches like any other image. Same
-// module-scoped decode cache and same repaint hook as the avatar above, and for the same reason:
-// glide repaints on `getCellContent` identity, and knows nothing about an `onload` three frames
-// later. Without the hook the placeholder paints once and stays — a deliberate-looking empty
-// frame over a picture that did arrive.
-
-export interface ImageCellData {
-  kind: "aios-image";
-  /** The resolved URL, or "" when the cell is empty (paints the placeholder frame). */
-  url: string;
-  /** The raw cell value — the copy/export payload, so a picture column is not invisible in a CSV. */
-  ref: string;
-}
-export type ImageCell = CustomCell<ImageCellData>;
-
-const _cellImgs = new Map<string, HTMLImageElement | null>();
-
-function cellImage(url: string): HTMLImageElement | null {
-  const hit = _cellImgs.get(url);
-  if (hit !== undefined) return hit;
-  if (typeof Image === "undefined") {
-    _cellImgs.set(url, null);
-    return null;
-  }
-  const img = new Image();
-  _cellImgs.set(url, img);
-  img.onload = () => _avatarRepaint?.();
-  img.onerror = () => {
-    // A reference that does not resolve is NOT retried: an unknown SKU code is the ordinary
-    // state of a product with no master on file, and retrying it every repaint would be a
-    // 404 per scroll tick per row.
-    _cellImgs.set(url, null);
-    _avatarRepaint?.();
-  };
-  img.src = url;
-  return img;
-}
-
-/** Registered once on the DataEditor (customRenderers), beside rating and user. */
-export const imageCellRenderer: CustomRenderer<ImageCell> = {
-  kind: GridCellKind.Custom,
-  isMatch: (cell): cell is ImageCell =>
-    (cell.data as ImageCellData | undefined)?.kind === "aios-image",
-  draw: (args, cell) => {
-    const { ctx, rect, theme } = args;
-    const { url } = cell.data;
-    const pad = theme.cellHorizontalPadding;
-    // Square, inset by 3px top and bottom so a tall row shows a bigger picture and a short one
-    // still leaves the grid line visible.
-    const size = Math.max(0, Math.min(rect.height - 6, rect.width - pad * 2));
-    if (size <= 2) return true;              // column dragged too narrow: paint nothing, never bleed
-    const x = rect.x + pad;
-    const y = rect.y + (rect.height - size) / 2;
-    const img = url ? cellImage(url) : null;
-    ctx.save();
-    ctx.beginPath();
-    // A 3px radius, matching the choice pills — one rounding vocabulary across the canvas.
-    const r = Math.min(3, size / 2);
-    ctx.moveTo(x + r, y);
-    ctx.arcTo(x + size, y, x + size, y + size, r);
-    ctx.arcTo(x + size, y + size, x, y + size, r);
-    ctx.arcTo(x, y + size, x, y, r);
-    ctx.arcTo(x, y, x + size, y, r);
-    ctx.closePath();
-    // `complete` alone is not enough — a FAILED decode is also complete, with a zero natural size.
-    if (img && img.complete && img.naturalWidth > 0) {
-      ctx.clip();
-      // CONTAIN, not cover: a product photo cropped to a square loses the thing being sold.
-      // Letterboxing inside the frame is the honest fit for a catalogue picture.
-      const scale = Math.min(size / img.naturalWidth, size / img.naturalHeight);
-      const w = img.naturalWidth * scale;
-      const h = img.naturalHeight * scale;
-      ctx.drawImage(img, x + (size - w) / 2, y + (size - h) / 2, w, h);
-    } else {
-      // The empty frame: a quiet outline, never a broken-image glyph and never a coloured block
-      // that would read as content. Identical whether the cell is empty or the fetch failed —
-      // the record modal is where a user finds out which, in words.
-      ctx.fillStyle = LP_BLUE_TINT;
-      ctx.fill();
-      ctx.strokeStyle = "rgba(118, 143, 182, 0.45)";
-      ctx.lineWidth = 1;
-      ctx.stroke();
-    }
-    ctx.restore();
-    return true;
-  },
-};
-
-/** Registered once on the DataEditor (customRenderers). Pure canvas paths. */
-export const ratingCellRenderer: CustomRenderer<RatingCell> = {
-  kind: GridCellKind.Custom,
-  isMatch: (cell): cell is RatingCell =>
-    (cell.data as RatingCellData | undefined)?.kind === "aios-rating",
-  draw: (args, cell) => {
-    const { ctx, rect, theme } = args;
-    const { value, max } = cell.data;
-    const size = 13;
-    const gap = 3;
-    const cy = rect.y + rect.height / 2;
-    let cx = rect.x + theme.cellHorizontalPadding + size / 2;
-    const maxRight = rect.x + rect.width - theme.cellHorizontalPadding;
-    for (let i = 0; i < max; i += 1) {
-      if (cx + size / 2 > maxRight) break; // never paint outside the cell
-      drawStar(ctx, cx, cy, size / 2, i < value);
-      cx += size + gap;
-    }
-    return true;
-  },
-};
-
-/** Build the cell for one (field, value). `editable` gates overlay + readonly.
- *
- * ⚠ A BLANK numeric cell renders EMPTY, never "$0" (2026-07-27). `''`/null is how a value that
- * could not be computed degrades — a measure column whose store query failed, an overlay number
- * nobody typed, a FORMULA that hit an error — and painting it as $0 would state a number nobody
- * computed. A real 0 arrives as the NUMBER 0 (the pool and the zero-group both emit it) and
- * still renders "$0". Mirrors the blank-vs-zero rule the engine already has (`isBlank`: 0 is
- * NOT blank). */
-export function makeCell(
-  field: Field,
-  v: CellValue,
-  editable: boolean,
-  /** C-AVATAR — username → data URL, straight off `GridWorkspace.userAvatars`. Absent, or a
-   *  username absent from it, paints the initials fallback. */
-  userAvatars?: Record<string, string>
-): GridCell {
-  // ⛔ NO MACHINE WASH (owner item 2, 2026-08-06): *"Remove the light grey highlight for the
-  // column that is supposedly pre-set."* Wave-23 R9 introduced a grey background on every
-  // machine-owned cell; on a `ut_*` database that is EVERY column but one, so the grid read as a
-  // sea of grey with a white stripe rather than as a table. The fact it was trying to state —
-  // *something else fills this column* — is now stated in WORDS where a reader will meet it
-  // (the `Pre-set` chip in Hide fields, `isPresetField`) and enforced where it matters (the
-  // cells refuse the edit, `isMachineWritten`). A label beats a tint the reader has to be taught.
-  return baseCell(field, v, editable, userAvatars);
-}
-
-/* ⛔ THE MACHINE WASH IS RETIRED (owner item 2, 2026-08-06).
-
-   Wave-23 C8/R9 washed every machine-owned cell grey. On the Customer grid that was a handful
-   of columns; on a `ut_*` database it is EVERY column but the identity one, so the owner's
-   Instagram table rendered as a grey sheet with one white stripe. `withMachineWash` and
-   `theme.machineCellTheme` are deleted with it — a composer nothing composes is a subject a gate
-   can still go green on ([[gate-answers-the-wrong-question]]), so the precedence assertions that
-   guarded it were RETARGETED onto the new law rather than dropped: `makeCell` adds no wash, and
-   a machine cell keeps exactly the override it already carried.
-
-   What replaced the signal, because removing it without replacing it would be a loss:
-     · the `Pre-set` chip in Hide fields (`isPresetField`) — the same word Odoo columns use;
-     · the custom-field DOT no longer painted on them (they are not yours to edit);
-     · and the cells genuinely refuse the edit now (`isMachineWritten`), which the wash never did. */
-
-function baseCell(
-  field: Field,
-  v: CellValue,
-  editable: boolean,
-  userAvatars?: Record<string, string>
-): GridCell {
-  const ro = { allowOverlay: editable, readonly: !editable };
-  const blank = v == null || v === "";
-  // ⛔ W29-T81 — A NUMERIC COLUMN HOLDING A NON-NUMBER PAINTS NOTHING, not `0`. `blank` above is
-  // emptiness; this is emptiness OR a value no reader would call a number. The import door can
-  // now put a spreadsheet's "seventeen-ish" in an `int` column, and `num()` answers 0 for it —
-  // a fabricated figure on the canvas beside an honest em-dash in the record panel.
-  const noNumber = numericIsBlank(v);
-
-  switch (field.type) {
-    case "currency":
-      return {
-        kind: GridCellKind.Number,
-        data: noNumber ? undefined : num(v),
-        displayData: noNumber ? "" : "$" + numberText(num(v), field.format),
-        contentAlign: "right",
-        ...ro,
-      };
-    case "int":
-      return {
-        kind: GridCellKind.Number,
-        data: noNumber ? undefined : num(v),
-        displayData: noNumber ? "" : numberText(num(v), field.format),
-        contentAlign: "right",
-        ...ro,
-      };
-    case "formula": {
-      // Computed client-side (formulaEngine.ts) over values ALREADY injected at this key by
-      // CustomerGrid's computedRows. Read-only by nature — the caller passes editable=false.
-      // 2026-07-31 (owner item 2): a formula may now return TEXT (CONCATENATE, &, TEXT(),
-      // TRUE/FALSE) — a non-numeric result renders as a text cell, never as NaN.
-      //
-      // ⛔ THE TEST WAS `!Number.isFinite(num(v))` AND IT NEVER FIRED. `num()` returns 0 for
-      // anything non-finite, so that read `Number.isFinite(0)` — always true — and every text
-      // formula printed as `0` here and in `formatDisplay`, which held its own copy of the same
-      // broken test. `formulaIsText` is now the ONE test, asked of the RAW value, shared by both
-      // renderers precisely because two copies is how they drifted. See its note in display.ts.
-      // ⚠ `formulaIsBlank`, NOT this function's shared `blank` (which is `v === ""`). A formula
-      // returning a SPACE is neither empty by that test nor text by the one below it, so it fell
-      // through to the numeric path and painted `0` — `Number(" ")` is 0. The two predicates are
-      // written to be total over a formula's three states; using only one of them re-opens the
-      // gap in miniature.
-      const formulaBlank = formulaIsBlank(v);
-      if (!formulaBlank && formulaIsText(v)) {
-        return {
-          kind: GridCellKind.Text,
-          data: v,
-          displayData: v,
-          allowOverlay: false,
-          readonly: true,
-        };
-      }
-      const asNum = num(v);
-      return {
-        kind: GridCellKind.Number,
-        data: formulaBlank ? undefined : asNum,
-        displayData: formulaBlank ? "" : numberText(asNum, field.format),
-        contentAlign: "right",
-        allowOverlay: false,
-        readonly: true,
-      };
-    }
-    case "pct":
-      return {
-        kind: GridCellKind.Number,
-        data: noNumber ? undefined : num(v),
-        displayData: noNumber ? "" : num(v).toFixed(1) + "%",
-        contentAlign: "right",
-        ...ro,
-      };
-    /* ⭐ WAVE-26 ITEM 3 — `copyData` IS THE STORED STAMP, and it is not decoration.
-       MEASURED in the installed glide (`data-editor/copy-paste.js::convertCellToBuffer`): a
-       `Text` cell copies as `copyData ?? displayData`, and the text/plain buffer takes that
-       FORMATTED string — so without this line, copying a date puts the DISPLAY string on the
-       clipboard. That was survivable while the display read `8/5/2026` (no space, so
-       `new Date()` re-parsed it); item 3 changed it to `Aug 5, 2026`, whose first space
-       `parseStamp` turns into `AugT5, 2026` — an Invalid Date that renders verbatim forever.
-       ⛔ So a display change silently became a WRITE change, one paste away. The same argument
-       `userCellPayload` records for the assignee cell: a value's clipboard identity is its
-       STORED form, and leaving it to a fallback makes it depend on which buffer the browser
-       hands back (the text/html one carries `gdg-raw-value`, the plain one does not).
-       ⚠ `coerceClipboardValue` normalises a pasted display string as the second half of this;
-       neither is sufficient alone — this one fixes OUR copy, that one fixes Excel's. */
-    case "date":
-      return {
-        kind: GridCellKind.Text,
-        data: String(v ?? ""),
-        displayData: dateTimeText(field, v),
-        copyData: String(v ?? ""),
-        ...ro,
-      };
-    case "created_time":
-      return {
-        kind: GridCellKind.Text,
-        data: String(v ?? ""),
-        displayData: dateTimeText(field, v),
-        copyData: String(v ?? ""),
-        allowOverlay: false,
-        readonly: true,
-      };
-    case "checkbox":
-      // glide toggles a non-readonly BooleanCell on click and reports it through
-      // onCellEdited — no overlay editor involved.
-      return {
-        kind: GridCellKind.Boolean,
-        data: checkboxOn(v),
-        allowOverlay: false,
-        readonly: !editable,
-      };
-    case "url":
-      // Renders as a link. OPENING is CustomerGrid's click path (scheme-guarded);
-      // hoverEffect gives the pointer affordance.
-      return {
-        kind: GridCellKind.Uri,
-        data: String(v ?? ""),
-        hoverEffect: true,
-        ...ro,
-      };
-    case "image": {
-      // Wave-19 R7 / C5. `allowOverlay:false` for the same reason `select` has it: the value is
-      // a REFERENCE that is picked or uploaded, never typed into a cell — the record modal owns
-      // the picker and the upload. `copyData` carries the raw ref so the column is not invisible
-      // in a copy or an export (the lesson the avatar cell booked one wave earlier).
-      const ref = String(v ?? "").trim();
-      return {
-        kind: GridCellKind.Custom,
-        data: {
-          kind: "aios-image",
-          url: ref ? assetUrl(ref, "web") : "",
-          ref,
-        } satisfies ImageCellData,
-        copyData: ref,
-        allowOverlay: false,
-      };
-    }
-    case "json": {
-      // ⭐ Wave-23 C7 (owner item 5) — the compact preview; the DOCUMENT lives in the viewer.
-      //
-      // `allowOverlay: false` for the same reason `select` and `image` carry it: glide's text
-      // overlay is a one-line box, and a one-line box over a 32 KB document is an editor that
-      // can only damage the value — one keystroke in the wrong place and a well-formed payload
-      // becomes unparseable, saved. CustomerGrid opens the viewer on click instead (the same
-      // `onCellClicked` path the pickers use), and THAT is where the raw text is editable, with
-      // parse-on-save.
-      //
-      // ⚠ `readonly` is NOT set, and the difference matters: `allowOverlay:false` means "no
-      // inline editor", while `readonly` would tell glide the CELL cannot change — which would
-      // also block the paste path that legitimately writes a whole document into it.
-      //
-      // ⚠ `copyData` carries the RAW document, never the preview (the lesson the image cell
-      // booked in wave 19). Copy a json column and you get the payload; copy the preview and
-      // you get the sentence "{…} 5 keys", which is not data and cannot be pasted back.
-      const raw = String(v ?? "");
-      const text = jsonPreview(raw);
-      return {
-        kind: GridCellKind.Text,
-        data: text,
-        displayData: text,
-        copyData: raw,
-        allowOverlay: false,
-      };
-    }
-    case "code": {
-      // ⭐ Wave-27 item 13 (R13) — the compact preview; the SNIPPET lives in the editor.
-      //
-      // Every rule the json cell above states applies here for the same reasons, so this is
-      // written the same way rather than differently: `allowOverlay:false` because glide's
-      // one-line text overlay over a multi-line snippet is an editor that can only damage the
-      // value; `readonly` deliberately NOT set, so the paste path that legitimately writes a
-      // whole snippet still works; `copyData` the RAW text, never the preview, or copying a code
-      // column would yield "SELECT * FROM …  +12 more", which is not data and cannot be pasted
-      // back (the lesson the image cell booked in wave 19, and the W26 date-cell repeat of it).
-      const raw = String(v ?? "");
-      const text = codePreview(raw);
-      return {
-        kind: GridCellKind.Text,
-        data: text,
-        displayData: text,
-        copyData: raw,
-        allowOverlay: false,
-      };
-    }
-    case "ai_enrich": {
-      // ⭐⭐ Wave-34 (owner ruling R13) — the AI ENRICHMENT cell. The value is an ordinary stored
-      // string, so this is a Text cell; what it is NOT is a `formula` (recomputed in the browser)
-      // or a `rollup` (read through from another table). Nobody has to be told a number came from
-      // somewhere else here, because the answer is words.
-      //
-      // Written the same way `code` and `json` are, and for their reason rather than a new one:
-      //   · `allowOverlay: false` — glide's ONE-LINE overlay editor over multi-line prose is an
-      //     editor that can only damage the value. The place a person edits an answer is the
-      //     record drawer, which shows the whole thing.
-      //   · `readonly` deliberately NOT set, so the paste path that legitimately writes a whole
-      //     answer still works.
-      //   · `copyData` the RAW text, never the preview, or copying this column would yield
-      //     "Ann is a florist  +2 more", which is not data and cannot be pasted back. That is the
-      //     lesson the image cell booked in wave 19 and the date cell repeated in wave 26.
-      //
-      // ⛔ EDITING IS THE POINT, NOT AN AFTERTHOUGHT, which is why the column is NOT in
-      // `READONLY_CELL_TYPES` and is NOT in `is_computed_cell` server-side: typing over a cell is
-      // what marks it the human's, and `core.user_tables.ai_enrich_human_authored` then protects
-      // it from every automatic run forever.
-      //
-      // ⚠ OWED, AND NAMED RATHER THAN FAKED: this branch cannot paint the agent-written /
-      // human-edited / stale / errored STATE, because `makeCell(field, v, editable, avatars)` is
-      // handed the value and never the row, and the per-cell mark lives in a stratum the row
-      // payload does not carry. The drawer shows the state; the canvas will once the call site in
-      // `CustomerGrid.tsx` (lane C's file) passes it. Rendering a guessed state here would be
-      // worse than none: "done" on a cell nothing has run for is a claim.
-      const raw = String(v ?? "");
-      const text = codePreview(raw);
-      return {
-        kind: GridCellKind.Text,
-        data: text,
-        displayData: text,
-        copyData: raw,
-        allowOverlay: false,
-      };
-    }
-    case "rating": {
-      const max = ratingMax(field);
-      const n = Math.max(0, Math.min(max, Math.round(num(v))));
-      return {
-        kind: GridCellKind.Custom,
-        data: { kind: "aios-rating", value: blank ? 0 : n, max } satisfies RatingCellData,
-        copyData: blank ? "" : String(n),
-        allowOverlay: false,
-      };
-    }
-    case "automation": {
-      // Wave-18 C5-AUTOFIELD. The cell is what the last RUN wrote — `ok · 2026-08-03 14:10 ·
-      // 12 posts` — so it is read-only by NATURE, not by policy: a value typed here would be
-      // overwritten by the next run with nothing anywhere saying so. The column's behaviour is
-      // configured through its gear, the way a formula's expression is.
-      //
-      // A tinted CELL rather than a bubble, and that is the whole design: the state and the
-      // detail are one sentence, and splitting them into two pills would put "2026-08-03 14:10
-      // · 12 posts" in a bubble, which is not what a bubble is for. `bgCell` is the one theme
-      // key glide alpha-blends (theme.ts:172), so the tints below are the flat pastels rather
-      // than anything semi-transparent.
-      const text = String(v ?? "");
-      return {
-        kind: GridCellKind.Text,
-        data: text,
-        displayData: text,
-        allowOverlay: false,
-        readonly: true,
-        themeOverride: AUTOMATION_TINT[automationState(text)],
-      };
-    }
-    case "link": {
-      // ⭐ 2026-08-07 — a relation, painted as ONE bubble saying how many rows it reaches.
-      //
-      // ⛔ NOT one bubble per linked row, and that is a measured decision rather than a
-      // simplification: the cell holds row IDS, and a column of `1,2,3` pills tells a reader
-      // nothing — the ids are not names. Airtable can paint the linked record's PRIMARY value
-      // because it has that row loaded; this client has not loaded the other table at all. So
-      // the honest cell is the COUNT, and the record drawer is where the rows themselves belong.
-      //
-      // ⚠ `copyData` carries the RAW id list, never the "12 posts" sentence — the W26 date-cell
-      // lesson, where a glide Text cell copies `copyData ?? displayData` and the FORMATTED
-      // string silently reached the clipboard and then the paste path. A count is not data and
-      // cannot be pasted back into a relation.
-      const ids = String(v ?? "").split(",").map((s) => s.trim()).filter((s) => s !== "");
-      return {
-        kind: GridCellKind.Bubble,
-        data: ids.length ? [ids.length === 1 ? "1 record" : `${ids.length} records`] : [],
-        copyData: String(v ?? ""),
-        allowOverlay: false,
-      };
-    }
-    case "rollup": {
-      // ⭐ 2026-08-07 — an aggregate the HOST computed. Read-only by nature, exactly like
-      // `formula`: the value is arithmetic, and a value box over arithmetic is an editor that
-      // can only produce a number the next refresh throws away.
-      //
-      // ⚠ BLANK STAYS BLANK. `_rollup_fold` returns "" for "no rows to aggregate" and only the
-      // count family ever returns a real 0 — so painting `0` here for an empty cell would invent
-      // the measurement the server just refused to invent. `num(v)` would do exactly that
-      // (`num("")` is 0), which is why the raw string is rendered rather than a parsed number.
-      // ⭐ 2026-08-10 (owner: *"I want to be able to use commas for numbers so instead of 1000
-      // its 1,000"*) — A ROLLUP IS FORMATTED LIKE ANY OTHER NUMBER, and it was the only numeric
-      // kind that was not. `int` and `currency` have gone through `numberText` since wave 5 and
-      // `formula` since it became a real column; a rollup rendered its raw fold string, so an
-      // "Avg views" column read `1491552.43` while the `Followers` column beside it read
-      // `56,147,007`. Two numeric columns, two dialects, one grid.
-      //
-      // ⚠ THE BLANK RULE IS PRESERVED EXACTLY, and it is why this is a guarded branch rather
-      // than a call. `_rollup_fold` returns "" for "no rows to aggregate" and only the count
-      // family ever returns a real 0, so `num(v)` — which maps "" to 0 — would paint the
-      // measurement the server just refused to invent. A blank stays the empty string, and a
-      // fold that is not a number at all (`concatenate`, `arrayunique`, `latest` over text)
-      // keeps its own text.
-      const raw = String(v ?? "");
-      const asNum = raw.trim() === "" ? NaN : Number(raw);
-      const text = Number.isFinite(asNum) ? numberText(asNum, field.format) : raw;
-      return {
-        kind: GridCellKind.Text,
-        data: text,
-        displayData: text,
-        // ⛔ THE CLIPBOARD TAKES THE RAW NUMBER, NOT THE FORMATTED ONE — wave 26's measured
-        // defect on `date`, where a glide Text cell copies `copyData ?? displayData` and the
-        // formatted string reached the clipboard, so pasting `Aug 5, 2026` into a number column
-        // stored the words. `1,491,552.43` pastes as text everywhere; `1491552.43` pastes as
-        // a number.
-        copyData: raw,
-        allowOverlay: false,
-        readonly: true,
-      };
-    }
-    case "status":
-      return {
-        kind: GridCellKind.Bubble,
-        data: [String(v ?? "")],
-        allowOverlay: false,
-        themeOverride: STATUS_BUBBLE[String(v ?? "").toLowerCase()],
-      };
-    case "user": {
-      // Wave-14 item 11 / R6 — the AVATAR ONLY, no name text. Split out of the `select` branch
-      // below (it was a name pill until this wave) because "who owns this" is a face, not a
-      // sentence, once a column has thirty rows of it.
-      //
-      // Still `allowOverlay:false`, for the same reason `select` is: the value is PICKED, never
-      // typed, and CustomerGrid opens its anchored picker on click (onCellClicked → isPickType,
-      // which already includes `user`, so the click path needs no change).
-      //
-      // ⚠ `copyData` carries the NAME. The cell shows no text, so without this the column would
-      // copy and export as empty — invisible in every screenshot. Built by `userCellPayload` in
-      // display.ts so a node gate can actually assert that (this module imports glide).
-      return {
-        kind: GridCellKind.Custom,
-        ...userCellPayload(String(v ?? ""), userAvatars),
-        allowOverlay: false,
-      };
-    }
-    case "select": {
-      // Picked, never typed. `allowOverlay:false` keeps glide's text editor OUT of the way —
-      // a free-text editor on a constrained field is how a column ends up holding "Done",
-      // "done" and "DONE" as three different values. CustomerGrid opens an anchored picker on
-      // click instead (onCellClicked), which is also why this stays dependency-free: glide's
-      // dropdown cell lives in a separate package we deliberately have not added.
-      const s = String(v ?? "");
-      const tint = optionTint(field, s);
-      return {
-        kind: GridCellKind.Bubble,
-        data: s ? [s] : [],
-        allowOverlay: false,
-        themeOverride: tint ? { bgBubble: tint.bg, textBubble: tint.fg } : undefined,
-      };
-    }
-    case "multiselect": {
-      // The cell holds a comma-joined SET (the `multi` contract the Cohorts column uses), so
-      // every member paints as its own pill. One themeOverride per CELL is all glide offers, so
-      // the pills share the first member's tint rather than each carrying its own.
-      const parts = String(v ?? "")
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s !== "");
-      const tint = parts.length ? optionTint(field, parts[0]) : undefined;
-      return {
-        kind: GridCellKind.Bubble,
-        data: parts,
-        allowOverlay: false,
-        themeOverride: tint ? { bgBubble: tint.bg, textBubble: tint.fg } : undefined,
-      };
-    }
-    default:
-      // text / status-family fallthrough — phone and email ride this branch too: typed as
-      // text in the grid, rendered as actionable tel:/mailto: links in the record drawer.
-      return {
-        kind: GridCellKind.Text,
-        data: String(v ?? ""),
-        displayData: String(v ?? ""),
-        ...ro,
-      };
-  }
-}
+// ---------------------------------------------------------------------------
+// customer-grid / cells.ts
+// The ONLY place that turns a (field, value) into a glide GridCell. glide has
+// no per-column formatter — all formatting is per-cell here, in getCellContent.
+//
+//  currency/int -> NumberCell (raw number kept for copy/paste, right-aligned)
+//  pct          -> NumberCell showing v.toFixed(1)+"%" (yoy_pct is already in percent-points)
+//  date         -> TextCell   (locale date string; read-only, no picker in core)
+//  status       -> BubbleCell (Airtable-style colored pill via themeOverride)
+//  checkbox     -> BooleanCell (wave-5 item 11; overlay stores '1' or '')
+//  url          -> UriCell    (renders as a link; opening is CustomerGrid's click path)
+//  phone/email  -> TextCell   (actionable links in the record drawer)
+//  rating       -> Custom     (canvas-drawn stars — SVG/vector paths, NEVER emoji)
+//  created_time -> TextCell   (read-only; the row's `_created`, injected at its key)
+//  formula      -> NumberCell (client-computed, read-only; blank = could not compute)
+//  text/other   -> TextCell
+//
+// Wave-5 item 10: `field.format` shapes the DISPLAY string (thousands /
+// decimals 0..4 / 34.0M abbreviation for numbers; include-time + local|utc
+// for dates). A field with NO format renders byte-identically to before the
+// format existed — parity is asserted by keeping the default paths in terms
+// of the same toLocaleString calls.
+//
+// Editability is the CALLER's decision (permissions + stratum + type); this
+// module just applies the flag it is handed.
+// ---------------------------------------------------------------------------
+
+import { GridCellKind } from "@glideapps/glide-data-grid";
+import type {
+  CustomCell,
+  CustomRenderer,
+  GridCell,
+  Theme,
+} from "@glideapps/glide-data-grid";
+import { assetUrl } from "./catalogData";
+import type { Field } from "./types";
+import { ratingMax } from "./types";
+import {
+  LP_BLUE_TEXT,
+  LP_BLUE_TINT,
+  LP_GREEN_DEEP,
+  LP_GREEN_TINT,
+  LP_RED_DEEP,
+  LP_RED_TINT,
+  LP_YELLOW_DEEP,
+  LP_YELLOW_TINT,
+  STATUS_BUBBLE,
+} from "./theme";
+// ⚠ ALIASED: this module has its own `pickTint` (the bubble table above) and choiceColors has
+// another. C-AVATAR names choiceColors' as the avatar fallback's source, so the two stay
+// distinguishable at the call site rather than one silently shadowing the other.
+import { optionTint, pickTint as choicePickTint } from "./choiceColors";
+import { automationState, avatarInitials, avatarSize, checkboxOn, dateTimeText, formulaIsBlank,
+  codePreview, formulaIsText, jsonPreview, num, numberText, numericIsBlank,
+  userCellPayload } from "./display";
+import type { AutomationState, CellValue, UserCellData } from "./display";
+
+// Wave-7 (item W2): the pure display-string half moved to display.ts so the
+// export builders can run under node without dragging glide along. Re-exported
+// here so every existing import keeps working unchanged.
+export { checkboxOn, dateTimeText, formatDisplay } from "./display";
+// C-AVATAR — the pure halves live in display.ts (node-reachable, so a gate can hold them);
+// re-exported here so callers keep importing "the cell module" for everything avatar-shaped.
+export { avatarInitials, avatarSize, userCellPayload } from "./display";
+export type { UserCellData } from "./display";
+// C5-AUTOFIELD — same arrangement: the string parsing is pure and lives in display.ts (a node
+// gate can hold it); only the canvas tint table below needs this module.
+export { automationDetail, automationState, automationStateLabel } from "./display";
+export type { AutomationState } from "./display";
+// Wave-23 C7 — same arrangement again: the parse, the preview and the pretty-printer are pure
+// (`verify_grid_ux` drives them under node); only the canvas cell below needs this module.
+export { codePreview, jsonParse, jsonPretty, jsonPreview, MAX_JSON_BYTES } from "./display";
+
+// ⭐ W40-T23 (owner instruction 14) — "typing a letter opens the picker" rests on two pure
+// decisions: which keystroke counts as typing, and which choices a query keeps. Same arrangement
+// as every block above — they live in display.ts so a node gate can EXECUTE them (this file
+// imports `GridCellKind` as a value, so nothing in it is node-reachable), and are re-exported
+// here so callers keep importing "the cell module". Their second consumer is the record
+// drawer's chip row, which is a different control answering the same instruction.
+export { matchChoices, pickerTypeSeed } from "./display";
+
+/**
+ * Wave-18 C5-AUTOFIELD — the cell tint per automation state.
+ *
+ * Standing brand rule: the PASTEL is the fill and the measured `-deep` variant carries the ink.
+ * `bgCell` + `textDark` is that pairing at cell scale, and every combination below is one of the
+ * pairs already measured for `STATUS_BUBBLE` (≥ 4.9:1), so nothing new needed measuring.
+ *
+ * `none` deliberately has NO override: a cell that has never run reads as an ordinary empty
+ * cell, because a tint would claim the automation had produced something.
+ */
+const AUTOMATION_TINT: Record<AutomationState, Partial<Theme> | undefined> = {
+  ok: { bgCell: LP_GREEN_TINT, textDark: LP_GREEN_DEEP },
+  partial: { bgCell: LP_YELLOW_TINT, textDark: LP_YELLOW_DEEP },
+  blocked: { bgCell: LP_YELLOW_TINT, textDark: LP_YELLOW_DEEP },
+  error: { bgCell: LP_RED_TINT, textDark: LP_RED_DEEP },
+  queued: { bgCell: LP_BLUE_TINT, textDark: LP_BLUE_TEXT },
+  none: undefined,
+};
+
+/** Stable pill tint for a user-defined choice. Hashed from the VALUE, so the same choice keeps
+ *  its colour across rows, sessions and users without anyone picking one — and a renamed option
+ *  simply gets a new colour rather than inheriting a stale mapping. */
+const PICK_TINTS = [
+  // 2026-07-31 (owner item 7): ONE construction — every pill is a `-tint` wash carrying its
+  // family's `-deep` ink, the standing brand rule ("pastels are fills; text takes the deep
+  // weight"). The old second pass (full pastel + near-black ink) is GONE: it is what read as
+  // "black font on a saturated chip". Six families now — the four C1 hues, the brand purple,
+  // and a neutral grey — all mirrored from index.css tokens; every pairing measures ≥ 5.0:1.
+  { bg: "#EDF3FD", fg: "#4F6079" },   // blue-tint  / LP_BLUE_TEXT
+  { bg: "#EBF6EF", fg: "#35754E" },   // green-tint / green-deep
+  { bg: "#FBF4E0", fg: "#7E6428" },   // yellow-tint/ yellow-deep
+  { bg: "#FCEEEC", fg: "#A3453C" },   // red-tint   / red-deep
+  { bg: "#F1EEFB", fg: "#6B57A8" },   // purple-tint/ purple-deep (--lp-purple family)
+  { bg: "#EEF1F4", fg: "#4B5563" },   // neutral wash / slate — the sixth distinct family
+];
+
+export function pickTint(v: string): { bg: string; fg: string } {
+  let h = 0;
+  for (let i = 0; i < v.length; i += 1) h = (h * 31 + v.charCodeAt(i)) >>> 0;
+  return PICK_TINTS[h % PICK_TINTS.length];
+}
+
+// --- rating: a canvas-drawn star row (owner constant: vector, never emoji) --
+
+export interface RatingCellData {
+  kind: "aios-rating";
+  /** 0 = unset (draws all-empty outlines). */
+  value: number;
+  max: number;
+}
+export type RatingCell = CustomCell<RatingCellData>;
+
+function drawStar(
+  ctx: CanvasRenderingContext2D,
+  cx: number,
+  cy: number,
+  r: number,
+  filled: boolean
+): void {
+  ctx.beginPath();
+  for (let i = 0; i < 10; i += 1) {
+    const rad = (Math.PI / 5) * i - Math.PI / 2;
+    const rr = i % 2 === 0 ? r : r * 0.45;
+    const px = cx + Math.cos(rad) * rr;
+    const py = cy + Math.sin(rad) * rr;
+    if (i === 0) ctx.moveTo(px, py);
+    else ctx.lineTo(px, py);
+  }
+  ctx.closePath();
+  if (filled) {
+    // I7c: C1's yellow is a FILL token (1.38:1) and a star has to be seen, so the
+    // filled star rides the deep amber variant: 3.29:1 on white, clearing the 3:1
+    // non-text bar the old gold #C8A24B never did (it measured 2.41:1).
+    ctx.fillStyle = "#A98A3E";
+    ctx.fill();
+  } else {
+    ctx.strokeStyle = "rgba(118, 143, 182, 0.55)"; // blue-deep outline, empty slots
+    ctx.lineWidth = 1;
+    ctx.stroke();
+  }
+}
+
+// --- user: the assignee AVATAR (wave-14 item 11 / R6 / contract C-AVATAR) -----
+//
+// R6: a grid cell shows the PHOTO OR ICON ONLY — no name text. (Pickers and the record modal
+// are where a name belongs; the column is a glanceable "who owns this", and thirty repetitions
+// of "Farhan Sanyoto" down a column is the thing the owner asked to stop reading.)
+//
+// The name is still the cell's COPY value. An avatar-only cell with no `copyData` makes an
+// assignee column copy as nothing — a real regression that no screenshot shows.
+
+export type UserCell = CustomCell<UserCellData>;
+
+/**
+ * Decoded avatar images, keyed by their data URL. `null` = this URL failed to decode, so we
+ * stop retrying it and paint the fallback forever (a corrupt stored photo must not spin).
+ *
+ * ⚠ Module scope, like the tint tables above: an Image per cell per frame would re-decode a
+ * base64 payload on every scroll tick.
+ */
+const _avatarImgs = new Map<string, HTMLImageElement | null>();
+let _avatarRepaint: (() => void) | undefined;
+
+/**
+ * ⚠ THE HALF THAT IS EASY TO FORGET. glide repaints when `getCellContent`'s identity changes —
+ * it knows nothing about an `Image.onload` that fires three frames later. Without this hook the
+ * fallback initials paint once and STAY, and because the fallback is a deliberate, correct-looking
+ * design, nothing on screen says the photo never arrived. (Same shape as wave-13's "honest empty
+ * state that made the failure look deliberate".)
+ *
+ * CustomerGrid calls this once and bumps a counter that is in `useGetCellContent`'s deps.
+ */
+export function setAvatarRepaint(fn: (() => void) | undefined): void {
+  _avatarRepaint = fn;
+}
+
+function avatarImage(dataUrl: string): HTMLImageElement | null {
+  const hit = _avatarImgs.get(dataUrl);
+  if (hit !== undefined) return hit;
+  // A DOM-less environment (a node gate, a locked-down embed) has no Image constructor. Cache
+  // the refusal so the fallback is what paints, rather than throwing inside a draw call.
+  if (typeof Image === "undefined") {
+    _avatarImgs.set(dataUrl, null);
+    return null;
+  }
+  const img = new Image();
+  _avatarImgs.set(dataUrl, img);
+  img.onload = () => _avatarRepaint?.();
+  img.onerror = () => {
+    _avatarImgs.set(dataUrl, null);
+    _avatarRepaint?.();
+  };
+  img.src = dataUrl;
+  return img;
+}
+
+/** C-AVATAR — the circle, photo or not. Exported so any other canvas surface paints the same
+ *  avatar rather than growing a second almost-matching one. */
+export function drawAvatar(
+  ctx: CanvasRenderingContext2D,
+  cx: number,
+  cy: number,
+  r: number,
+  name: string,
+  photo: string | undefined,
+  fontFamily: string
+): void {
+  const img = photo ? avatarImage(photo) : null;
+  // `complete` alone is not enough: a FAILED decode is also "complete", with a zero natural size.
+  if (img && img.complete && img.naturalWidth > 0) {
+    ctx.save();
+    ctx.beginPath();
+    ctx.arc(cx, cy, r, 0, Math.PI * 2);
+    ctx.clip();
+    // COVER, not contain: a portrait must fill the circle, not sit letterboxed inside it.
+    const scale = Math.max((r * 2) / img.naturalWidth, (r * 2) / img.naturalHeight);
+    const w = img.naturalWidth * scale;
+    const h = img.naturalHeight * scale;
+    ctx.drawImage(img, cx - w / 2, cy - h / 2, w, h);
+    ctx.restore();
+    return;
+  }
+  // The fallback, and it is the DEFAULT state until HOST's C-AVATAR lands — never a broken-image
+  // glyph. Hashed from the full name so one person keeps one colour across rows and sessions.
+  const tint = choicePickTint(name);
+  ctx.save();
+  ctx.beginPath();
+  ctx.arc(cx, cy, r, 0, Math.PI * 2);
+  ctx.fillStyle = tint.bg;
+  ctx.fill();
+  ctx.fillStyle = tint.fg;
+  ctx.font = `600 ${Math.round(r * 0.9)}px ${fontFamily}`;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  ctx.fillText(avatarInitials(name), cx, cy + 0.5);
+  ctx.restore();
+}
+
+/** Registered once on the DataEditor (customRenderers), beside the rating renderer. */
+export const userCellRenderer: CustomRenderer<UserCell> = {
+  kind: GridCellKind.Custom,
+  isMatch: (cell): cell is UserCell =>
+    (cell.data as UserCellData | undefined)?.kind === "aios-user",
+  draw: (args, cell) => {
+    const { ctx, rect, theme } = args;
+    const { name, photo } = cell.data;
+    if (!name) return true; // unassigned paints nothing — an empty circle would look assigned
+    const d = avatarSize(rect.height);
+    const cx = rect.x + theme.cellHorizontalPadding + d / 2;
+    const cy = rect.y + rect.height / 2;
+    // Never paint outside the cell: a column dragged narrow drops the avatar rather than
+    // bleeding it over its neighbour.
+    if (cx + d / 2 > rect.x + rect.width - theme.cellHorizontalPadding) return true;
+    drawAvatar(ctx, cx, cy, d / 2, name, photo, theme.fontFamily);
+    return true;
+  },
+};
+
+// --- image: the record THUMBNAIL (wave-19 R7 / contract C5) -------------------
+//
+// The cell holds a REFERENCE, never bytes (`types.ts: imageRefKind`), so what paints here is an
+// <img> the browser fetches from the asset routes and caches like any other image. Same
+// module-scoped decode cache and same repaint hook as the avatar above, and for the same reason:
+// glide repaints on `getCellContent` identity, and knows nothing about an `onload` three frames
+// later. Without the hook the placeholder paints once and stays — a deliberate-looking empty
+// frame over a picture that did arrive.
+
+export interface ImageCellData {
+  kind: "aios-image";
+  /** The resolved URL, or "" when the cell is empty (paints the placeholder frame). */
+  url: string;
+  /** The raw cell value — the copy/export payload, so a picture column is not invisible in a CSV. */
+  ref: string;
+}
+export type ImageCell = CustomCell<ImageCellData>;
+
+const _cellImgs = new Map<string, HTMLImageElement | null>();
+
+function cellImage(url: string): HTMLImageElement | null {
+  const hit = _cellImgs.get(url);
+  if (hit !== undefined) return hit;
+  if (typeof Image === "undefined") {
+    _cellImgs.set(url, null);
+    return null;
+  }
+  const img = new Image();
+  _cellImgs.set(url, img);
+  img.onload = () => _avatarRepaint?.();
+  img.onerror = () => {
+    // A reference that does not resolve is NOT retried: an unknown SKU code is the ordinary
+    // state of a product with no master on file, and retrying it every repaint would be a
+    // 404 per scroll tick per row.
+    _cellImgs.set(url, null);
+    _avatarRepaint?.();
+  };
+  img.src = url;
+  return img;
+}
+
+/** Registered once on the DataEditor (customRenderers), beside rating and user. */
+export const imageCellRenderer: CustomRenderer<ImageCell> = {
+  kind: GridCellKind.Custom,
+  isMatch: (cell): cell is ImageCell =>
+    (cell.data as ImageCellData | undefined)?.kind === "aios-image",
+  draw: (args, cell) => {
+    const { ctx, rect, theme } = args;
+    const { url } = cell.data;
+    const pad = theme.cellHorizontalPadding;
+    // Square, inset by 3px top and bottom so a tall row shows a bigger picture and a short one
+    // still leaves the grid line visible.
+    const size = Math.max(0, Math.min(rect.height - 6, rect.width - pad * 2));
+    if (size <= 2) return true;              // column dragged too narrow: paint nothing, never bleed
+    const x = rect.x + pad;
+    const y = rect.y + (rect.height - size) / 2;
+    const img = url ? cellImage(url) : null;
+    ctx.save();
+    ctx.beginPath();
+    // A 3px radius, matching the choice pills — one rounding vocabulary across the canvas.
+    const r = Math.min(3, size / 2);
+    ctx.moveTo(x + r, y);
+    ctx.arcTo(x + size, y, x + size, y + size, r);
+    ctx.arcTo(x + size, y + size, x, y + size, r);
+    ctx.arcTo(x, y + size, x, y, r);
+    ctx.arcTo(x, y, x + size, y, r);
+    ctx.closePath();
+    // `complete` alone is not enough — a FAILED decode is also complete, with a zero natural size.
+    if (img && img.complete && img.naturalWidth > 0) {
+      ctx.clip();
+      // CONTAIN, not cover: a product photo cropped to a square loses the thing being sold.
+      // Letterboxing inside the frame is the honest fit for a catalogue picture.
+      const scale = Math.min(size / img.naturalWidth, size / img.naturalHeight);
+      const w = img.naturalWidth * scale;
+      const h = img.naturalHeight * scale;
+      ctx.drawImage(img, x + (size - w) / 2, y + (size - h) / 2, w, h);
+    } else {
+      // The empty frame: a quiet outline, never a broken-image glyph and never a coloured block
+      // that would read as content. Identical whether the cell is empty or the fetch failed —
+      // the record modal is where a user finds out which, in words.
+      ctx.fillStyle = LP_BLUE_TINT;
+      ctx.fill();
+      ctx.strokeStyle = "rgba(118, 143, 182, 0.45)";
+      ctx.lineWidth = 1;
+      ctx.stroke();
+    }
+    ctx.restore();
+    return true;
+  },
+};
+
+/** Registered once on the DataEditor (customRenderers). Pure canvas paths. */
+export const ratingCellRenderer: CustomRenderer<RatingCell> = {
+  kind: GridCellKind.Custom,
+  isMatch: (cell): cell is RatingCell =>
+    (cell.data as RatingCellData | undefined)?.kind === "aios-rating",
+  draw: (args, cell) => {
+    const { ctx, rect, theme } = args;
+    const { value, max } = cell.data;
+    const size = 13;
+    const gap = 3;
+    const cy = rect.y + rect.height / 2;
+    let cx = rect.x + theme.cellHorizontalPadding + size / 2;
+    const maxRight = rect.x + rect.width - theme.cellHorizontalPadding;
+    for (let i = 0; i < max; i += 1) {
+      if (cx + size / 2 > maxRight) break; // never paint outside the cell
+      drawStar(ctx, cx, cy, size / 2, i < value);
+      cx += size + gap;
+    }
+    return true;
+  },
+};
+
+/** Build the cell for one (field, value). `editable` gates overlay + readonly.
+ *
+ * ⚠ A BLANK numeric cell renders EMPTY, never "$0" (2026-07-27). `''`/null is how a value that
+ * could not be computed degrades — a measure column whose store query failed, an overlay number
+ * nobody typed, a FORMULA that hit an error — and painting it as $0 would state a number nobody
+ * computed. A real 0 arrives as the NUMBER 0 (the pool and the zero-group both emit it) and
+ * still renders "$0". Mirrors the blank-vs-zero rule the engine already has (`isBlank`: 0 is
+ * NOT blank). */
+export function makeCell(
+  field: Field,
+  v: CellValue,
+  editable: boolean,
+  /** C-AVATAR — username → data URL, straight off `GridWorkspace.userAvatars`. Absent, or a
+   *  username absent from it, paints the initials fallback. */
+  userAvatars?: Record<string, string>
+): GridCell {
+  // ⛔ NO MACHINE WASH (owner item 2, 2026-08-06): *"Remove the light grey highlight for the
+  // column that is supposedly pre-set."* Wave-23 R9 introduced a grey background on every
+  // machine-owned cell; on a `ut_*` database that is EVERY column but one, so the grid read as a
+  // sea of grey with a white stripe rather than as a table. The fact it was trying to state —
+  // *something else fills this column* — is now stated in WORDS where a reader will meet it
+  // (the `Pre-set` chip in Hide fields, `isPresetField`) and enforced where it matters (the
+  // cells refuse the edit, `isMachineWritten`). A label beats a tint the reader has to be taught.
+  return baseCell(field, v, editable, userAvatars);
+}
+
+/* ⛔ THE MACHINE WASH IS RETIRED (owner item 2, 2026-08-06).
+
+   Wave-23 C8/R9 washed every machine-owned cell grey. On the Customer grid that was a handful
+   of columns; on a `ut_*` database it is EVERY column but the identity one, so the owner's
+   Instagram table rendered as a grey sheet with one white stripe. `withMachineWash` and
+   `theme.machineCellTheme` are deleted with it — a composer nothing composes is a subject a gate
+   can still go green on ([[gate-answers-the-wrong-question]]), so the precedence assertions that
+   guarded it were RETARGETED onto the new law rather than dropped: `makeCell` adds no wash, and
+   a machine cell keeps exactly the override it already carried.
+
+   What replaced the signal, because removing it without replacing it would be a loss:
+     · the `Pre-set` chip in Hide fields (`isPresetField`) — the same word Odoo columns use;
+     · the custom-field DOT no longer painted on them (they are not yours to edit);
+     · and the cells genuinely refuse the edit now (`isMachineWritten`), which the wash never did. */
+
+function baseCell(
+  field: Field,
+  v: CellValue,
+  editable: boolean,
+  userAvatars?: Record<string, string>
+): GridCell {
+  const ro = { allowOverlay: editable, readonly: !editable };
+  const blank = v == null || v === "";
+  // ⛔ W29-T81 — A NUMERIC COLUMN HOLDING A NON-NUMBER PAINTS NOTHING, not `0`. `blank` above is
+  // emptiness; this is emptiness OR a value no reader would call a number. The import door can
+  // now put a spreadsheet's "seventeen-ish" in an `int` column, and `num()` answers 0 for it —
+  // a fabricated figure on the canvas beside an honest em-dash in the record panel.
+  const noNumber = numericIsBlank(v);
+
+  switch (field.type) {
+    case "currency":
+      return {
+        kind: GridCellKind.Number,
+        data: noNumber ? undefined : num(v),
+        displayData: noNumber ? "" : "$" + numberText(num(v), field.format),
+        contentAlign: "right",
+        ...ro,
+      };
+    case "int":
+      return {
+        kind: GridCellKind.Number,
+        data: noNumber ? undefined : num(v),
+        displayData: noNumber ? "" : numberText(num(v), field.format),
+        contentAlign: "right",
+        ...ro,
+      };
+    case "formula": {
+      // Computed client-side (formulaEngine.ts) over values ALREADY injected at this key by
+      // CustomerGrid's computedRows. Read-only by nature — the caller passes editable=false.
+      // 2026-07-31 (owner item 2): a formula may now return TEXT (CONCATENATE, &, TEXT(),
+      // TRUE/FALSE) — a non-numeric result renders as a text cell, never as NaN.
+      //
+      // ⛔ THE TEST WAS `!Number.isFinite(num(v))` AND IT NEVER FIRED. `num()` returns 0 for
+      // anything non-finite, so that read `Number.isFinite(0)` — always true — and every text
+      // formula printed as `0` here and in `formatDisplay`, which held its own copy of the same
+      // broken test. `formulaIsText` is now the ONE test, asked of the RAW value, shared by both
+      // renderers precisely because two copies is how they drifted. See its note in display.ts.
+      // ⚠ `formulaIsBlank`, NOT this function's shared `blank` (which is `v === ""`). A formula
+      // returning a SPACE is neither empty by that test nor text by the one below it, so it fell
+      // through to the numeric path and painted `0` — `Number(" ")` is 0. The two predicates are
+      // written to be total over a formula's three states; using only one of them re-opens the
+      // gap in miniature.
+      const formulaBlank = formulaIsBlank(v);
+      if (!formulaBlank && formulaIsText(v)) {
+        return {
+          kind: GridCellKind.Text,
+          data: v,
+          displayData: v,
+          allowOverlay: false,
+          readonly: true,
+        };
+      }
+      const asNum = num(v);
+      return {
+        kind: GridCellKind.Number,
+        data: formulaBlank ? undefined : asNum,
+        displayData: formulaBlank ? "" : numberText(asNum, field.format),
+        contentAlign: "right",
+        allowOverlay: false,
+        readonly: true,
+      };
+    }
+    case "pct":
+      return {
+        kind: GridCellKind.Number,
+        data: noNumber ? undefined : num(v),
+        displayData: noNumber ? "" : num(v).toFixed(1) + "%",
+        contentAlign: "right",
+        ...ro,
+      };
+    /* ⭐ WAVE-26 ITEM 3 — `copyData` IS THE STORED STAMP, and it is not decoration.
+       MEASURED in the installed glide (`data-editor/copy-paste.js::convertCellToBuffer`): a
+       `Text` cell copies as `copyData ?? displayData`, and the text/plain buffer takes that
+       FORMATTED string — so without this line, copying a date puts the DISPLAY string on the
+       clipboard. That was survivable while the display read `8/5/2026` (no space, so
+       `new Date()` re-parsed it); item 3 changed it to `Aug 5, 2026`, whose first space
+       `parseStamp` turns into `AugT5, 2026` — an Invalid Date that renders verbatim forever.
+       ⛔ So a display change silently became a WRITE change, one paste away. The same argument
+       `userCellPayload` records for the assignee cell: a value's clipboard identity is its
+       STORED form, and leaving it to a fallback makes it depend on which buffer the browser
+       hands back (the text/html one carries `gdg-raw-value`, the plain one does not).
+       ⚠ `coerceClipboardValue` normalises a pasted display string as the second half of this;
+       neither is sufficient alone — this one fixes OUR copy, that one fixes Excel's. */
+    case "date":
+      return {
+        kind: GridCellKind.Text,
+        data: String(v ?? ""),
+        displayData: dateTimeText(field, v),
+        copyData: String(v ?? ""),
+        ...ro,
+      };
+    case "created_time":
+      return {
+        kind: GridCellKind.Text,
+        data: String(v ?? ""),
+        displayData: dateTimeText(field, v),
+        copyData: String(v ?? ""),
+        allowOverlay: false,
+        readonly: true,
+      };
+    case "checkbox":
+      // glide toggles a non-readonly BooleanCell on click and reports it through
+      // onCellEdited — no overlay editor involved.
+      return {
+        kind: GridCellKind.Boolean,
+        data: checkboxOn(v),
+        allowOverlay: false,
+        readonly: !editable,
+      };
+    case "url":
+      // Renders as a link. OPENING is CustomerGrid's click path (scheme-guarded);
+      // hoverEffect gives the pointer affordance.
+      return {
+        kind: GridCellKind.Uri,
+        data: String(v ?? ""),
+        hoverEffect: true,
+        ...ro,
+      };
+    case "image": {
+      // Wave-19 R7 / C5. `allowOverlay:false` for the same reason `select` has it: the value is
+      // a REFERENCE that is picked or uploaded, never typed into a cell — the record modal owns
+      // the picker and the upload. `copyData` carries the raw ref so the column is not invisible
+      // in a copy or an export (the lesson the avatar cell booked one wave earlier).
+      const ref = String(v ?? "").trim();
+      return {
+        kind: GridCellKind.Custom,
+        data: {
+          kind: "aios-image",
+          url: ref ? assetUrl(ref, "web") : "",
+          ref,
+        } satisfies ImageCellData,
+        copyData: ref,
+        allowOverlay: false,
+      };
+    }
+    case "json": {
+      // ⭐ Wave-23 C7 (owner item 5) — the compact preview; the DOCUMENT lives in the viewer.
+      //
+      // `allowOverlay: false` for the same reason `select` and `image` carry it: glide's text
+      // overlay is a one-line box, and a one-line box over a 32 KB document is an editor that
+      // can only damage the value — one keystroke in the wrong place and a well-formed payload
+      // becomes unparseable, saved. CustomerGrid opens the viewer on click instead (the same
+      // `onCellClicked` path the pickers use), and THAT is where the raw text is editable, with
+      // parse-on-save.
+      //
+      // ⚠ `readonly` is NOT set, and the difference matters: `allowOverlay:false` means "no
+      // inline editor", while `readonly` would tell glide the CELL cannot change — which would
+      // also block the paste path that legitimately writes a whole document into it.
+      //
+      // ⚠ `copyData` carries the RAW document, never the preview (the lesson the image cell
+      // booked in wave 19). Copy a json column and you get the payload; copy the preview and
+      // you get the sentence "{…} 5 keys", which is not data and cannot be pasted back.
+      const raw = String(v ?? "");
+      const text = jsonPreview(raw);
+      return {
+        kind: GridCellKind.Text,
+        data: text,
+        displayData: text,
+        copyData: raw,
+        allowOverlay: false,
+      };
+    }
+    case "code": {
+      // ⭐ Wave-27 item 13 (R13) — the compact preview; the SNIPPET lives in the editor.
+      //
+      // Every rule the json cell above states applies here for the same reasons, so this is
+      // written the same way rather than differently: `allowOverlay:false` because glide's
+      // one-line text overlay over a multi-line snippet is an editor that can only damage the
+      // value; `readonly` deliberately NOT set, so the paste path that legitimately writes a
+      // whole snippet still works; `copyData` the RAW text, never the preview, or copying a code
+      // column would yield "SELECT * FROM …  +12 more", which is not data and cannot be pasted
+      // back (the lesson the image cell booked in wave 19, and the W26 date-cell repeat of it).
+      const raw = String(v ?? "");
+      const text = codePreview(raw);
+      return {
+        kind: GridCellKind.Text,
+        data: text,
+        displayData: text,
+        copyData: raw,
+        allowOverlay: false,
+      };
+    }
+    case "ai_enrich": {
+      // ⭐⭐ Wave-34 (owner ruling R13) — the AI ENRICHMENT cell. The value is an ordinary stored
+      // string, so this is a Text cell; what it is NOT is a `formula` (recomputed in the browser)
+      // or a `rollup` (read through from another table). Nobody has to be told a number came from
+      // somewhere else here, because the answer is words.
+      //
+      // Written the same way `code` and `json` are, and for their reason rather than a new one:
+      //   · `allowOverlay: false` — glide's ONE-LINE overlay editor over multi-line prose is an
+      //     editor that can only damage the value. The place a person edits an answer is the
+      //     record drawer, which shows the whole thing.
+      //   · `readonly` deliberately NOT set, so the paste path that legitimately writes a whole
+      //     answer still works.
+      //   · `copyData` the RAW text, never the preview, or copying this column would yield
+      //     "Ann is a florist  +2 more", which is not data and cannot be pasted back. That is the
+      //     lesson the image cell booked in wave 19 and the date cell repeated in wave 26.
+      //
+      // ⛔ EDITING IS THE POINT, NOT AN AFTERTHOUGHT, which is why the column is NOT in
+      // `READONLY_CELL_TYPES` and is NOT in `is_computed_cell` server-side: typing over a cell is
+      // what marks it the human's, and `core.user_tables.ai_enrich_human_authored` then protects
+      // it from every automatic run forever.
+      //
+      // ⚠ OWED, AND NAMED RATHER THAN FAKED: this branch cannot paint the agent-written /
+      // human-edited / stale / errored STATE, because `makeCell(field, v, editable, avatars)` is
+      // handed the value and never the row, and the per-cell mark lives in a stratum the row
+      // payload does not carry. The drawer shows the state; the canvas will once the call site in
+      // `CustomerGrid.tsx` (lane C's file) passes it. Rendering a guessed state here would be
+      // worse than none: "done" on a cell nothing has run for is a claim.
+      const raw = String(v ?? "");
+      const text = codePreview(raw);
+      return {
+        kind: GridCellKind.Text,
+        data: text,
+        displayData: text,
+        copyData: raw,
+        allowOverlay: false,
+      };
+    }
+    case "rating": {
+      const max = ratingMax(field);
+      const n = Math.max(0, Math.min(max, Math.round(num(v))));
+      return {
+        kind: GridCellKind.Custom,
+        data: { kind: "aios-rating", value: blank ? 0 : n, max } satisfies RatingCellData,
+        copyData: blank ? "" : String(n),
+        allowOverlay: false,
+      };
+    }
+    case "automation": {
+      // Wave-18 C5-AUTOFIELD. The cell is what the last RUN wrote — `ok · 2026-08-03 14:10 ·
+      // 12 posts` — so it is read-only by NATURE, not by policy: a value typed here would be
+      // overwritten by the next run with nothing anywhere saying so. The column's behaviour is
+      // configured through its gear, the way a formula's expression is.
+      //
+      // A tinted CELL rather than a bubble, and that is the whole design: the state and the
+      // detail are one sentence, and splitting them into two pills would put "2026-08-03 14:10
+      // · 12 posts" in a bubble, which is not what a bubble is for. `bgCell` is the one theme
+      // key glide alpha-blends (theme.ts:172), so the tints below are the flat pastels rather
+      // than anything semi-transparent.
+      const text = String(v ?? "");
+      return {
+        kind: GridCellKind.Text,
+        data: text,
+        displayData: text,
+        allowOverlay: false,
+        readonly: true,
+        themeOverride: AUTOMATION_TINT[automationState(text)],
+      };
+    }
+    case "link": {
+      // ⭐ 2026-08-07 — a relation, painted as ONE bubble saying how many rows it reaches.
+      //
+      // ⛔ NOT one bubble per linked row, and that is a measured decision rather than a
+      // simplification: the cell holds row IDS, and a column of `1,2,3` pills tells a reader
+      // nothing — the ids are not names. Airtable can paint the linked record's PRIMARY value
+      // because it has that row loaded; this client has not loaded the other table at all. So
+      // the honest cell is the COUNT, and the record drawer is where the rows themselves belong.
+      //
+      // ⚠ `copyData` carries the RAW id list, never the "12 posts" sentence — the W26 date-cell
+      // lesson, where a glide Text cell copies `copyData ?? displayData` and the FORMATTED
+      // string silently reached the clipboard and then the paste path. A count is not data and
+      // cannot be pasted back into a relation.
+      const ids = String(v ?? "").split(",").map((s) => s.trim()).filter((s) => s !== "");
+      return {
+        kind: GridCellKind.Bubble,
+        data: ids.length ? [ids.length === 1 ? "1 record" : `${ids.length} records`] : [],
+        copyData: String(v ?? ""),
+        allowOverlay: false,
+      };
+    }
+    case "rollup": {
+      // ⭐ 2026-08-07 — an aggregate the HOST computed. Read-only by nature, exactly like
+      // `formula`: the value is arithmetic, and a value box over arithmetic is an editor that
+      // can only produce a number the next refresh throws away.
+      //
+      // ⚠ BLANK STAYS BLANK. `_rollup_fold` returns "" for "no rows to aggregate" and only the
+      // count family ever returns a real 0 — so painting `0` here for an empty cell would invent
+      // the measurement the server just refused to invent. `num(v)` would do exactly that
+      // (`num("")` is 0), which is why the raw string is rendered rather than a parsed number.
+      // ⭐ 2026-08-10 (owner: *"I want to be able to use commas for numbers so instead of 1000
+      // its 1,000"*) — A ROLLUP IS FORMATTED LIKE ANY OTHER NUMBER, and it was the only numeric
+      // kind that was not. `int` and `currency` have gone through `numberText` since wave 5 and
+      // `formula` since it became a real column; a rollup rendered its raw fold string, so an
+      // "Avg views" column read `1491552.43` while the `Followers` column beside it read
+      // `56,147,007`. Two numeric columns, two dialects, one grid.
+      //
+      // ⚠ THE BLANK RULE IS PRESERVED EXACTLY, and it is why this is a guarded branch rather
+      // than a call. `_rollup_fold` returns "" for "no rows to aggregate" and only the count
+      // family ever returns a real 0, so `num(v)` — which maps "" to 0 — would paint the
+      // measurement the server just refused to invent. A blank stays the empty string, and a
+      // fold that is not a number at all (`concatenate`, `arrayunique`, `latest` over text)
+      // keeps its own text.
+      const raw = String(v ?? "");
+      const asNum = raw.trim() === "" ? NaN : Number(raw);
+      const text = Number.isFinite(asNum) ? numberText(asNum, field.format) : raw;
+      return {
+        kind: GridCellKind.Text,
+        data: text,
+        displayData: text,
+        // ⛔ THE CLIPBOARD TAKES THE RAW NUMBER, NOT THE FORMATTED ONE — wave 26's measured
+        // defect on `date`, where a glide Text cell copies `copyData ?? displayData` and the
+        // formatted string reached the clipboard, so pasting `Aug 5, 2026` into a number column
+        // stored the words. `1,491,552.43` pastes as text everywhere; `1491552.43` pastes as
+        // a number.
+        copyData: raw,
+        allowOverlay: false,
+        readonly: true,
+      };
+    }
+    case "status":
+      return {
+        kind: GridCellKind.Bubble,
+        data: [String(v ?? "")],
+        allowOverlay: false,
+        themeOverride: STATUS_BUBBLE[String(v ?? "").toLowerCase()],
+      };
+    case "user": {
+      // Wave-14 item 11 / R6 — the AVATAR ONLY, no name text. Split out of the `select` branch
+      // below (it was a name pill until this wave) because "who owns this" is a face, not a
+      // sentence, once a column has thirty rows of it.
+      //
+      // Still `allowOverlay:false`, for the same reason `select` is: the value is PICKED, never
+      // typed, and CustomerGrid opens its anchored picker on click (onCellClicked → isPickType,
+      // which already includes `user`, so the click path needs no change).
+      //
+      // ⚠ `copyData` carries the NAME. The cell shows no text, so without this the column would
+      // copy and export as empty — invisible in every screenshot. Built by `userCellPayload` in
+      // display.ts so a node gate can actually assert that (this module imports glide).
+      return {
+        kind: GridCellKind.Custom,
+        ...userCellPayload(String(v ?? ""), userAvatars),
+        allowOverlay: false,
+      };
+    }
+    case "select": {
+      // Picked, never typed. `allowOverlay:false` keeps glide's text editor OUT of the way —
+      // a free-text editor on a constrained field is how a column ends up holding "Done",
+      // "done" and "DONE" as three different values. CustomerGrid opens an anchored picker on
+      // click instead (onCellClicked), which is also why this stays dependency-free: glide's
+      // dropdown cell lives in a separate package we deliberately have not added.
+      const s = String(v ?? "");
+      const tint = optionTint(field, s);
+      return {
+        kind: GridCellKind.Bubble,
+        data: s ? [s] : [],
+        allowOverlay: false,
+        themeOverride: tint ? { bgBubble: tint.bg, textBubble: tint.fg } : undefined,
+      };
+    }
+    case "multiselect": {
+      // The cell holds a comma-joined SET (the `multi` contract the Cohorts column uses), so
+      // every member paints as its own pill. One themeOverride per CELL is all glide offers, so
+      // the pills share the first member's tint rather than each carrying its own.
+      const parts = String(v ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+      const tint = parts.length ? optionTint(field, parts[0]) : undefined;
+      return {
+        kind: GridCellKind.Bubble,
+        data: parts,
+        allowOverlay: false,
+        themeOverride: tint ? { bgBubble: tint.bg, textBubble: tint.fg } : undefined,
+      };
+    }
+    default:
+      // text / status-family fallthrough — phone and email ride this branch too: typed as
+      // text in the grid, rendered as actionable tel:/mailto: links in the record drawer.
+      return {
+        kind: GridCellKind.Text,
+        data: String(v ?? ""),
+        displayData: String(v ?? ""),
+        ...ro,
+      };
+  }
+}

web/src/customer-grid/display.ts

@@ -1,777 +1,950 @@
-// ---------------------------------------------------------------------------
-// customer-grid / display.ts
-// The pure DISPLAY-STRING half of cells.ts, split out in wave 7 (item W2): the
-// export builders run under node in the verify gates, and importing them
-// through cells.ts dragged the whole glide-data-grid package into a plain
-// script. Everything here depends only on types.ts. cells.ts re-exports these
-// names, so every existing import keeps working; the formatting is the same
-// bytes it was — this is a move, not a change.
-// ---------------------------------------------------------------------------
-
-import type { Field, FieldFormat } from "./types";
-import { ratingMax } from "./types";
-
-export type CellValue = string | number | null | undefined;
-
-// --- C-AVATAR (wave-14 item 11): the two PURE halves of the assignee avatar ---
-// They live here rather than in cells.ts for this module's founding reason: cells.ts imports
-// glide, so nothing in it can be reached by a node gate. The canvas drawing stays there; the
-// arithmetic and the string handling — the parts that can be wrong in ways a screenshot of one
-// avatar will not show — are here, and `cells.ts` re-exports both.
-
-/**
- * Up to two letters for the fallback circle.
- *
- * ⚠ The LOCAL PART only. Usernames in this tenant are email-shaped, and splitting
- * "fsanyoto@gmail.com" on its separators gives ["fsanyoto@gmail", "com"] → "FC" — a person's
- * avatar reading as their mail provider. Cutting at "@" first gives "FS".
- *
- * ⚠ A HYPHEN IS NOT A SEPARATOR. Space, dot and underscore divide a given name from a family
- * name in a username; a hyphen almost always JOINS a compound one — Jo-Anne, Marie-Claire,
- * Al-Rashid. Treating it as a separator turns "jo-anne_smith" into "JA", which is not that
- * person's initials and is wrong in the one way nobody can spot: it looks like initials.
- */
-export function avatarInitials(name: string): string {
-  const local = name.split("@")[0];
-  const parts = local.trim().split(/[\s._]+/).filter(Boolean);
-  if (parts.length === 0) return "?";
-  if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase();
-  return (parts[0][0] + parts[1][0]).toUpperCase();
-}
-
-/**
- * The avatar's diameter for a row of `height` px: 22 on a comfortable row, never larger, and
- * never so small it stops being a face. Bounded on BOTH sides on purpose — a `tall` row (48px)
- * must not grow a 42px portrait, and a `short` one (28px) must not shrink to a dot.
- */
-export function avatarSize(height: number): number {
-  return Math.max(14, Math.min(22, height - 6));
-}
-
-export interface UserCellData {
-  kind: "aios-user";
-  /** The assignee's username. "" = unassigned; the cell then paints nothing at all. */
-  name: string;
-  /** C-AVATAR data URL, when the workspace served one for this user. */
-  photo?: string;
-}
-
-/**
- * The `user` cell's payload — HERE rather than inline in `cells.ts` for one reason: `copyData`.
- *
- * ⚠ R6 removed the NAME from the cell, so the cell renders no text at all. glide's copy and
- * export take `copyData`, which means an assignee column silently copies and exports as EMPTY
- * unless it is set — a real regression that appears in no screenshot, because the screenshot
- * shows the avatar working perfectly. `cells.ts` imports glide and is therefore unreachable from
- * a node gate; this is, so the claim can actually be asserted.
- */
-export function userCellPayload(
-  name: string,
-  userAvatars?: Record<string, string>
-): { data: UserCellData; copyData: string } {
-  return {
-    data: { kind: "aios-user", name, photo: userAvatars?.[name] },
-    copyData: name,
-  };
-}
-
-/**
- * The number to PAINT, with `0` as the fallback every existing caller already relies on.
- *
- * ⛔⛔ IT MUST PARSE THE SAME WAY THE FOLD DOES, AND FOR ONE COMMIT IT DID NOT. This was a bare
- * `Number(v)`, so `"1,234.50"` → `NaN` → **0**: the canvas painted `$0` while the totals row
- * underneath counted 1,234.5. The T81 fix that introduced `numericIsBlank` made the BLANK
- * decision consistent and left the VALUE on this function, so the cell stopped being blank and
- * started being a fabricated zero — the exact defect T81 exists to kill, one step to the right.
- * ⚠ Caught by an adversarial read, NOT by the leg named "the fold counts exactly what the cell
- * shows" — which only ever called `computeAggs` and never evaluated what the cell shows. A test
- * whose NAME makes a claim its assertion does not is worse than no test.
- * ⚠ REACHABLE, and by more than one path: the import door refuses-without-rewriting (so `$45`
- * is storable by design, and `api_api` asserts it imports), and `automation_engine._rollup_fold`
- * returns raw source cells as STRINGS for `latest`/`min`/`max`.
- */
-export function num(v: CellValue): number {
-  return numericOrUndefined(v) ?? 0;
-}
-
-/**
- * ⛔ W29-T81 — HAS THIS NUMERIC CELL NOTHING TO SHOW? Blank, or a stored value that is not a
- * number at all.
- *
- * `num()` above answers **0** for anything unparseable, which is a measurement where there was
- * none. That is survivable for a column only this app writes; it stopped being survivable when
- * the import door began accepting rows from a spreadsheet — a `qty` column holding
- * "seventeen-ish" painted `0` on the canvas while the record panel honestly showed an em-dash.
- * Two surfaces disagreeing about the same cell, and the one that looks authoritative is the one
- * making the number up.
- *
- * ⚠ The FOLD was already right (`aggregations.numOf` skips what will not parse), so the totals
- * row never counted these — it is the painted cell alone. Same family as `formulaIsText` below,
- * asked of the RAW value for the same reason.
- * ⚠ `"  "` is blank, not a zero: `Number("  ")` is 0, which is how a whitespace cell becomes a
- * number nobody typed.
- */
-export function numericIsBlank(v: CellValue): boolean {
-  return numericOrUndefined(v) === undefined;
-}
-
-/**
- * ⛔⛔ THE ONE NUMERIC READING OF A STORED CELL, and it has to be one.
- *
- * `numericIsBlank` decides whether the CANVAS paints anything; `aggregations.numOf` decides
- * whether the TOTALS ROW counts it. They were written separately and normalised differently —
- * this one trimmed, that one stripped `$`, `,` and spaces — so `"1,234.50"` painted BLANK in the
- * cell and was COUNTED in the total underneath it. That is T81's own defect ("two surfaces
- * disagreeing about one cell") reintroduced in the opposite direction, by the fix for it, and no
- * test could see it because every value in the legs was comma-free.
- *
- * ⚠ Human spellings are ACCEPTED here on purpose. `coerceClipboardValue` canonicalises what the
- * UI writes, but the import door refuses-without-rewriting by design, so a `"$45"` posted by curl
- * is storable — and the honest reading of that cell is 45 on BOTH surfaces, never 45 in the total
- * and nothing in the cell ([[one-evaluator-per-question]]).
- */
-export function numericOrUndefined(v: CellValue): number | undefined {
-  if (v === null || v === undefined || v === "") return undefined;
-  if (typeof v === "number") return Number.isFinite(v) ? v : undefined;
-  const cleaned = String(v).replace(/[$,\s]/g, "");
-  if (cleaned === "") return undefined;          // "  " is blank, not the zero `Number("")` gives
-  const n = Number(cleaned);
-  return Number.isFinite(n) ? n : undefined;
-}
-
-/**
- * ⛔ IS THIS FORMULA RESULT TEXT? — and it must be asked of the RAW value.
- *
- * A formula may return text since 2026-07-31 (owner item 2: CONCATENATE, `&`, TEXT(),
- * TRUE/FALSE, and any `IF(cond, "yes", "no")`). Both renderers tried to detect that with
- * `!Number.isFinite(num(v))` — and `num()` above returns **0** for anything non-finite, so the
- * test was `Number.isFinite(0)`, which is always true. The text branch therefore never ran in
- * EITHER renderer, and every text-returning formula printed as `0`: on the canvas, in the list,
- * on kanban cards, in the record panel and in all four export formats.
- *
- * The feature had never worked. It surfaced by rendering the owner's own Buy signal formula
- * through the shipped bundle rather than by asking whether the code looked right.
- *
- * ONE function, exported, called by both `formatDisplay` and `makeCell` — they are meant to be
- * one rendering, and the way they drifted was each holding its own copy of this test.
- * `Number("")` is 0, so the empty case is excluded explicitly rather than relied upon.
- *
- * A TYPE PREDICATE, not a bare boolean: `makeCell` builds a `TextCell` from the value straight
- * after this test, and without the narrowing the caller has to re-assert the string it just
- * proved — which is the kind of cast that outlives the reason for it.
- */
-export function formulaIsText(v: CellValue): v is string {
-  return typeof v === "string" && v.trim() !== "" && !Number.isFinite(Number(v));
-}
-
-/**
- * ⛔ AND THE BLANK TEST HAS TO AGREE WITH IT, or a value falls between the two.
- *
- * `formulaIsText` excludes whitespace-only strings (a `"  "` result is not TEXT worth painting).
- * The callers' own blank guard was `v === ""`, which does not catch `"  "` — so a formula
- * returning a space matched NEITHER, fell through to the numeric path, and printed `0`, because
- * `Number(" ")` is 0. The exact bug this pair was written to fix, surviving in a narrower case.
- *
- * A formula's result is therefore one of exactly three things, and these two predicates make the
- * three TOTAL: blank (null, empty, or whitespace), text, or a number. Reachable in practice —
- * `CONCATENATE(" ", "")` is a space, and so is `TRIM()` of one.
- */
-export function formulaIsBlank(v: CellValue): boolean {
-  return v == null || (typeof v === "string" && v.trim() === "");
-}
-
-/** A checkbox cell's boolean, out of the overlay's '1'-or-empty contract. */
-export function checkboxOn(v: CellValue | boolean): boolean {
-  return v === "1" || v === 1 || v === true;
-}
-
-/**
- * Item 10 — the number DISPLAY string. With no format: exactly the pre-wave-5
- * rendering (toLocaleString). `abbrev` wins over decimals when the magnitude
- * calls for it (34.0M — one decimal, k/M/B); `thousands: false` drops the
- * separators; `decimals` fixes 0..4 places.
- */
-export function numberText(v: number, fmt: FieldFormat | undefined): string {
-  if (fmt?.abbrev && Math.abs(v) >= 1000) {
-    const abs = Math.abs(v);
-    const [div, suffix] =
-      abs >= 1e9 ? [1e9, "B"] : abs >= 1e6 ? [1e6, "M"] : [1e3, "k"];
-    return (v / div).toFixed(1) + suffix;
-  }
-  const d =
-    fmt && Number.isInteger(fmt.decimals) && (fmt.decimals as number) >= 0 &&
-    (fmt.decimals as number) <= 4
-      ? (fmt.decimals as number)
-      : null;
-  const thousands = fmt?.thousands !== false;
-  if (d != null)
-    return thousands
-      ? v.toLocaleString(undefined, {
-          minimumFractionDigits: d,
-          maximumFractionDigits: d,
-        })
-      : v.toFixed(d);
-  return thousands ? v.toLocaleString() : String(v);
-}
-
-/**
- * Parse a stored date/datetime string. Odoo datetimes arrive as
- * "YYYY-MM-DD HH:MM:SS" and are UTC by Odoo convention, so a time-carrying
- * value with no zone gets a Z; a bare date keeps today's parse (UTC midnight)
- * so format-less rendering stays byte-identical to the pre-wave-5 path.
- *
- * ⭐ EXPORTED in wave 29 (W29-T30) because the xlsx writer needs a Date to turn
- * into an Excel serial, and the alternative was a SECOND date parser in
- * `export.ts` — two evaluators for one question, which is how the two drift and
- * a stamp exports as a different day than it renders
- * ([[one-evaluator-per-question]]). It stays the only parser in this module.
- */
-export function parseStamp(raw: string): Date | null {
-  const s = raw.includes(" ") ? raw.replace(" ", "T") : raw;
-  const iso =
-    /T\d{2}:\d{2}/.test(s) && !/(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(s) ? s + "Z" : s;
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime()) ? null : d;
-}
-
-/** A BARE calendar day: the shape Odoo sends for a `date`, and the shape wave 26's migration
- *  converted the Instagram preset stamps into. `parseStamp` gives it UTC midnight. */
-const BARE_DAY = /^\d{4}-\d{2}-\d{2}$/;
-
-/**
- * Is this stored value a calendar DAY rather than an INSTANT? — the question that decides which
- * clock renders it (see `dateTimeText`).
- *
- * Exported, and it is the whole reason the test for this is worth anything: the alternative is
- * asserting a rendered string, which depends on the machine's timezone — so the check would pass
- * on the owner's box (+07:00, where the two clocks agree on the day) and could only ever go red
- * somewhere else. A predicate is the same decision with no ambient state in it.
- *
- * ⚠ The SHAPE OF THE RAW STRING, never `field.type`: wave 26 re-typed columns that hold full ISO
- * stamps to `date`, so one `date` field can carry both shapes at once during a migration.
- */
-export function isBareDay(v: CellValue): boolean {
-  return BARE_DAY.test(String(v ?? "").trim());
-}
-
-/**
- * ⭐ Wave-26 item 3 (owner, R3) — the day, spelled. `Aug 5, 2026`, never `8/5/2026` and never
- * the raw stamp. One vocabulary for the date half whether or not a time follows it, so a
- * `date` column and a `created_time` column in the same table read alike.
- */
-const DAY_PARTS = { year: "numeric", month: "short", day: "numeric" } as const;
-
-/**
- * Item 10 — the date DISPLAY string. `time` includes the time of day
- * (created_time defaults to true — a creation stamp without its time reads as
- * a duplicate of nothing); `tz: 'utc'` renders the tenant-neutral clock.
- * Unparseable input renders VERBATIM rather than "Invalid Date" — the raw
- * string is at least true.
- *
- * ⭐ WAVE 26 ITEM 3 (owner, via R3). The complaint was literal: cells read
- * `2026-08-05T14:03:11+07:00`. SESSION A's half re-typed the Instagram preset
- * columns from `text` to `date` (which is what routed them here at all) and
- * migrated the stored cells to bare `YYYY-MM-DD`; this half is that a date must
- * READ as one. Two changes, and the second is the one that is not cosmetic:
- *
- * ⛔ **A BARE `YYYY-MM-DD` IS A CALENDAR DAY, NOT AN INSTANT, so it renders in
- * UTC.** `parseStamp` gives a bare date UTC midnight, so rendering it in the
- * viewer's local zone shows the PREVIOUS DAY to everyone west of Greenwich — a
- * value stored as the 5th reading as the 4th, silently, for a whole hemisphere.
- * `ui/fmt.ts:date()` already refused to inherit this and its comment names this
- * function as the holdout; it is no longer one. The tenant runs at +07:00, where
- * the two agree, which is exactly why it could sit here unnoticed — and why the
- * US market in COMMERCIALIZATION_PLAN C1b would have met it first.
- *
- * A value that CARRIES a time is a real instant and keeps the existing zone
- * behaviour (local, or UTC when the field says so): shifting those to UTC would
- * introduce the same off-by-a-day from the other direction.
- */
-export function dateTimeText(
-  // ⚠ STRUCTURAL, not `Field`: this reads exactly two members, and item 8's post rows hold a
-  // raw `posted_at` with no column behind it. Widening the parameter (rather than fabricating a
-  // fake Field at the call site) is what lets the posts list render its days through the SAME
-  // formatter as a date cell instead of growing a second one. Every existing caller passes a
-  // `Field`, which is assignable.
-  field: { type: Field["type"]; format?: FieldFormat },
-  v: CellValue
-): string {
-  if (v == null || v === "") return "";
-  const raw = String(v);
-  const d = parseStamp(raw);
-  if (!d) return raw;
-  const fmt = field.format;
-  const withTime = fmt?.time ?? field.type === "created_time";
-  const utc = fmt?.tz === "utc" || isBareDay(raw);
-  const zone = utc ? { timeZone: "UTC" as const } : undefined;
-  return withTime
-    ? d.toLocaleString(undefined, {
-        ...DAY_PARTS,
-        hour: "numeric",
-        minute: "2-digit",
-        second: "2-digit",
-        ...zone,
-      })
-    : d.toLocaleDateString(undefined, { ...DAY_PARTS, ...zone });
-}
-
-/**
- * The plain-string rendering of one (field, value), mirroring makeCell's
- * displayData. Reused by the record-detail panel and the W2 export builders so
- * a value reads identically on the canvas, in the panel and in a file. Returns
- * "" for empty so callers can substitute their own placeholder.
- */
-/**
- * Wave-18 C5-AUTOFIELD — the STATE word of an automation cell.
- *
- * An automation cell holds one machine-written line: `state · when · detail`, e.g.
- * `ok · 2026-08-03 14:10 · 12 posts`. The state is the first token, and every surface that
- * paints the cell — canvas tint, record modal, the rail — reads it through HERE rather than
- * re-splitting the string, because two parsers of one format is how the canvas and the panel
- * end up disagreeing about whether a run succeeded (the exact way `formula` broke above).
- *
- * `"none"` is the honest answer for a cell nothing has written yet — NOT "ok". A column that
- * has never run must not look like a column that ran and found nothing.
- */
-export type AutomationState = "ok" | "partial" | "error" | "blocked" | "queued" | "none";
-
-const AUTOMATION_STATES: AutomationState[] = ["ok", "partial", "error", "blocked", "queued"];
-
-export function automationState(v: CellValue): AutomationState {
-  const head = String(v ?? "").split("·")[0].trim().toLowerCase();
-  return (AUTOMATION_STATES as string[]).includes(head)
-    ? (head as AutomationState)
-    : "none";
-}
-
-/** Everything after the state word — the timestamp and the run's own detail. */
-export function automationDetail(v: CellValue): string {
-  const parts = String(v ?? "").split("·");
-  return parts.length > 1 ? parts.slice(1).join("·").trim() : "";
-}
-
-/** Sentence-cased state, for anywhere a word reads better than a token. */
-export function automationStateLabel(v: CellValue): string {
-  const s = automationState(v);
-  return s === "none" ? "Not run yet" : s[0].toUpperCase() + s.slice(1);
-}
-
-/**
- * ⭐ Wave-23 C7 (owner item 5) — THE JSON PREVIEW: what a 200px cell says about a document.
- *
- * `MAX_JSON_BYTES` is the contract's ceiling, mirrored from the host's write validation so the
- * viewer can refuse a paste with the same number the server would (a client that lets you type
- * 40 KB and then shows you a server refusal has wasted the edit).
- *
- * The four cases, and each one is a decision rather than a formatting preference:
- *   · **a single-pair object shows THE PAIR.** `{handle: "royalimports"}` is more useful than
- *     "1 key" and it is the shape most machine writes actually have. Past one pair the pairs
- *     stop fitting and the honest answer is the count.
- *   · **many keys / many items → `{…} N keys` / `[…] N items`.** Showing the FIRST pair of a
- *     twelve-key object would let a reader take one arbitrary value — whichever key the writer's
- *     serializer happened to emit first — for the cell's content.
- *   · **a bare scalar renders as itself.** `12`, `"ok"`, `true` and `null` are all valid JSON
- *     documents, and wrapping them in braces would describe a shape they do not have.
- *   · ⛔ **text that does not parse renders AS ITSELF, never as a shape.** The host validates on
- *     write, so this only happens to a value that predates the validation or arrived another
- *     way — and the one thing the preview must never do is claim a document is well-formed. The
- *     viewer's raw tab is where such a value gets read and repaired.
- *
- * Blank stays blank: an empty json cell is a document nobody has written, and `{}` is a document
- * somebody wrote that is empty. Two different facts, two different cells.
- */
-export const MAX_JSON_BYTES = 32 * 1024;
-
-/**
- * ⭐ WAVE 31 · T22 (D-173) — is this parsed value the SERVER'S STAND-IN for a document it did not
- * send, and if so how big was the real one? Returns a short size string, or null.
- *
- * ⛔ THE SHAPE IS `routes_tables._thin_json`'s OWN, and it is matched on `_truncated === true`
- * plus a numeric `bytes` — never on the key alone, because a person's own document could contain
- * a `_truncated` key and must not be reported as absent. `_url` is deliberately NOT required: the
- * viewer keys its fetch on it, but a preview that refused to warn when it was missing would go
- * quiet in exactly the degraded case that most needs a warning.
- */
-export function truncatedDoc(value: unknown): string | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const v = value as Record<string, unknown>;
-  if (v._truncated !== true) return null;
-  const bytes = typeof v.bytes === "number" && isFinite(v.bytes) ? Math.max(0, v.bytes) : 0;
-  if (!bytes) return "not shown";
-  return bytes >= 1024 ? `${Math.round(bytes / 1024).toLocaleString()} KB not shown`
-                       : `${bytes.toLocaleString()} bytes not shown`;
-}
-
-/** Does this text parse as JSON? The ONE test, shared by the preview, the cell and the viewer's
- *  save — three copies of a try/catch is how they end up disagreeing about `""` or `NaN`. */
-export function jsonParse(v: CellValue): { ok: boolean; value?: unknown } {
-  const s = String(v ?? "").trim();
-  if (s === "") return { ok: false };
-  try {
-    return { ok: true, value: JSON.parse(s) as unknown };
-  } catch {
-    return { ok: false };
-  }
-}
-
-/**
- * ⭐ WAVE-27 item 13 (R13) — one compact line for a CODE cell.
- *
- * Deliberately NOT `jsonPreview`, and the difference is the whole reason `code` is its own kind:
- * a json preview SUMMARISES a parsed document ("{…} 5 keys"), which it can only do because the
- * value is guaranteed to parse. A snippet has no structure to summarise and often does not parse
- * at all — half-written SQL is the normal state of one — so the honest preview is the first
- * non-blank LINE, clipped, plus the line count when there is more underneath. That way the cell
- * says what the snippet starts with AND that there is more, instead of inventing a shape for it.
- */
-export function codePreview(v: CellValue): string {
-  const raw = String(v ?? "");
-  if (raw.trim() === "") return "";
-  const lines = raw.split("\n");
-  const firstIdx = lines.findIndex((l) => l.trim() !== "");
-  const first = clip((lines[firstIdx < 0 ? 0 : firstIdx] ?? "").trim(), 60);
-  // The count is of REAL lines, so a snippet padded with blank lines does not claim depth it
-  // does not have — and it is checkable against what opening the editor shows
-  // ([[no-unverifiable-aggregates]]).
-  const n = lines.filter((l) => l.trim() !== "").length;
-  return n > 1 ? `${first}  +${n - 1} more` : first;
-}
-
-/**
- * ⭐⭐ W37-T14 / T15 — THE TWO SHAPES WAVE 37 ADDED, READ AS WHAT THEY ARE.
- *
- * ⛔ FOUND BY QA ON THE DEPLOYED BUILD, not by a gate: `1.5BOPP`'s Units cell rendered
- * **`[…] 2 items`** and its Tier prices cell the same way, because both are `type: "json"` and
- * both fell through to the generic array branch below. The server was serving the right data the
- * whole time — `[{name:"SLEEVE",qty:12},{name:"Master",qty:144}]` — and the grid said nothing
- * about it. A column whose entire job is to show which units a SKU sells in, showing a count of
- * items, is the [[permitted-is-not-answerable]] shape in the RENDER layer.
- *
- * ⚠ KEYED ON THE SHAPE, NEVER ON THE COLUMN KEY. A key test (`field.key === "units"`) would
- * miss the same document on a user database, on a rollup, or under any rename — and this file
- * has no access to the field anyway. Both shapes are exact: EVERY element must be an object
- * carrying exactly the pair, so an unrelated array of objects still falls through to the generic
- * branch and is not silently relabelled.
- *
- * ⚠ `×` is U+00D7 MULTIPLICATION SIGN and `·` is U+00B7 MIDDLE DOT — neither is an em or en
- * dash, so this copy is inside standing rule 2 rather than an exception to it.
- */
-function namedPairList(value: unknown): string | null {
-  if (!Array.isArray(value) || value.length === 0) return null;
-  const rows = value as Record<string, unknown>[];
-  const every = (a: string, b: string) =>
-    rows.every(
-      (r) =>
-        r !== null &&
-        typeof r === "object" &&
-        !Array.isArray(r) &&
-        typeof r[a] === "string" &&
-        typeof r[b] === "number",
-    );
-  // W37-T15 — units of measure: the NAME and its conversion factor, which is the whole point.
-  if (every("name", "qty"))
-    return rows.map((r) => `${String(r.name)} ×${trimNum(r.qty as number)}`).join(" · ");
-  // W37-T14 — the pricelists that really price this SKU today, each with its price.
-  if (every("pricelist", "unit_price"))
-    return rows
-      .map((r) => `${String(r.pricelist)} $${numberText(r.unit_price as number, { decimals: 2 })}`)
-      .join(" · ");
-  return null;
-}
-
-/** `12` not `12.0`, and `1.5` kept — a conversion factor is a count far more often than not. */
-function trimNum(n: number): string {
-  return Number.isFinite(n) ? String(Number(n.toFixed(4))) : String(n);
-}
-
-/** One compact line for a json cell. See the note above for why each case reads as it does. */
-export function jsonPreview(v: CellValue): string {
-  const raw = String(v ?? "").trim();
-  if (raw === "") return "";
-  const parsed = jsonParse(raw);
-  // ⚠ First line only, and clipped: an unparseable value is often a whole pasted response, and
-  // a cell is not where a 4 KB blob gets read. It is shown rather than hidden because the
-  // reader has to be able to see that the column holds something the app could not open.
-  if (!parsed.ok) return clip(raw.split("\n")[0], 60);
-  const value = parsed.value;
-  // ⭐ ITEM 8 — a posts window says what it holds. Before wave 26 this document fell through to
-  // the generic object branch and every creator's `posts` cell read `{…} 4 keys`, which is true
-  // about JSON and says nothing about the record.
-  // ⚠ The ARRAY LENGTH, never the document's own `n`: the count in a cell has to be checkable
-  // against what opening it shows ([[no-unverifiable-aggregates]]).
-  // ⭐⭐ WAVE 31 · T22 (D-173) — A DOCUMENT THE LIST DID NOT SEND SAYS SO, WITH ITS SIZE.
-  //
-  // ⛔ THE SWALLOW, and it is one branch below this one. `routes_tables._thin_json` replaces an
-  // oversized `json` cell with a stand-in — `{_truncated, bytes, _url}` — so the big document
-  // does not ride a list response (measured: `source_payload` was 95.6–98.5% of every IG grid's
-  // bytes). That stand-in is itself valid JSON with three keys, so it fell through to the generic
-  // object branch and the cell read **`{…} 3 keys`** — a confident, checkable-looking claim about
-  // a document that is not there, and indistinguishable from a real three-key document. R6's
-  // second sentence applies to our own wire: a value we declined to send is reported, never
-  // disguised.
-  // ⚠ THE SIZE IS THE SERVER'S OWN `bytes`, not a guess, and it is what makes the cell honest —
-  // "this column holds 41 KB you have not been shown" is a different fact from "3 keys".
-  const thinned = truncatedDoc(value);
-  if (thinned) return `{…} ${thinned}`;
-  const shown = postsWindowOf(value);
-  if (shown)
-    return shown.posts.length === 0
-      ? "No posts"
-      : `${shown.posts.length} post${shown.posts.length === 1 ? "" : "s"}`;
-  // ⭐ W37-T14/T15 — the two known shapes read as themselves; anything else keeps the old count.
-  const pairs = namedPairList(value);
-  if (pairs) return clip(pairs, 60);
-  if (Array.isArray(value))
-    return value.length === 0 ? "[]" : `[…] ${value.length} item${value.length === 1 ? "" : "s"}`;
-  if (value !== null && typeof value === "object") {
-    const keys = Object.keys(value as Record<string, unknown>);
-    if (keys.length === 0) return "{}";
-    if (keys.length === 1)
-      return clip(`{${keys[0]}: ${scalarText((value as Record<string, unknown>)[keys[0]])}}`, 60);
-    return `{…} ${keys.length} keys`;
-  }
-  return clip(scalarText(value), 60);
-}
-
-/** The day, spelled, for a caller holding a raw value and no column — the posts list's
- *  `posted_at`. Routed through `dateTimeText` so it can never drift from a date CELL. */
-export function dayText(v: CellValue): string {
-  return dateTimeText({ type: "date" }, v);
-}
-
-/* ═══ ⭐ WAVE 26 ITEM 8 (contract C2) — THE `posts` WINDOW ═══
-   The preset `posts` cell holds ONE object written by the engine's `posts_window`:
-
-     { n, metrics, as_of, posts: [{ shortcode, url, posted_at, type, caption,
-                                    views?, likes?, comments? }] }
-
-   Two laws come with it and both are enforced below rather than in the components:
-
-   ⛔ `metrics: false` ⇒ views/likes/comments are ABSENT KEYS, NEVER 0. A reader must render an
-      absent metric as NOTHING. Coercing it to a number here — `Number(p.views) || 0` is the
-      natural thing to type — would fabricate a measurement, which is the engine's own
-      blank-never-zero law broken at the display seam, silently and plausibly (a creator with no
-      metrics bought would read as a creator with no engagement).
-
-   ⛔ IT IS A WINDOW, NOT THE HISTORY. `ut_ig_posts` / `ut_ig_post_snapshots` accumulate; this
-      cell is the last N (R1/R3 — "one store for one series"). So nothing here may present the
-      cell as a total.
-
-   ⚠ DETECTED BY SHAPE, never by the field's key. A user may name a column `posts`, and the
-   preset key is not a contract the renderer can see from the value alone. An object carrying a
-   `posts` ARRAY OF OBJECTS is what makes "3 posts" a true sentence about it, whoever wrote it.
-   ═══ */
-export interface PostSummary {
-  shortcode?: string;
-  url?: string;
-  posted_at?: string;
-  type?: string;
-  caption?: string;
-  /** ⛔ `undefined` when the metric was not bought. Never 0 — see the note above. */
-  views?: number;
-  likes?: number;
-  comments?: number;
-}
-
-export interface PostsWindow {
-  /** The engine's own count. May differ from `posts.length`; readers show the LENGTH, because
-   *  that is the number a reader can check against what is in front of them. */
-  n: number;
-  metrics: boolean;
-  as_of?: string;
-  posts: PostSummary[];
-}
-
-function str(v: unknown): string | undefined {
-  return typeof v === "string" && v !== "" ? v : undefined;
-}
-
-/** ⛔ A number ONLY when the key really holds one. `undefined` for absent, for null, and for a
- *  non-numeric — anything else invents a measurement. */
-function metric(v: unknown): number | undefined {
-  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
-}
-
-/** The window behind an ALREADY-PARSED value, or null when this is not one. */
-export function postsWindowOf(value: unknown): PostsWindow | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
-  const doc = value as Record<string, unknown>;
-  const rows = doc.posts;
-  if (!Array.isArray(rows)) return null;
-  if (!rows.every((r) => r !== null && typeof r === "object" && !Array.isArray(r))) return null;
-  const posts: PostSummary[] = rows.map((r) => {
-    const p = r as Record<string, unknown>;
-    return {
-      shortcode: str(p.shortcode),
-      url: str(p.url),
-      posted_at: str(p.posted_at),
-      type: str(p.type),
-      caption: str(p.caption),
-      views: metric(p.views),
-      likes: metric(p.likes),
-      comments: metric(p.comments),
-    };
-  });
-  return {
-    n: typeof doc.n === "number" ? doc.n : posts.length,
-    metrics: doc.metrics === true,
-    as_of: str(doc.as_of),
-    posts,
-  };
-}
-
-/** The window behind a stored CELL, or null. */
-export function postsWindow(v: CellValue): PostsWindow | null {
-  const parsed = jsonParse(v);
-  return parsed.ok ? postsWindowOf(parsed.value) : null;
-}
-
-/** A nested value, small enough to sit inside a one-pair preview. Objects and arrays collapse
- *  to their own marks rather than recursing — a preview that unfolds is not a preview. */
-function scalarText(v: unknown): string {
-  if (v === null) return "null";
-  if (Array.isArray(v)) return `[…] ${v.length}`;
-  if (typeof v === "object") return `{…} ${Object.keys(v as object).length}`;
-  return typeof v === "string" ? v : String(v);
-}
-
-/** ⚠ An ellipsis CHARACTER, not three dots: the grid's canvas measures text and three periods
- *  are three glyphs wide. Same mark the group-bar fitter uses. */
-function clip(s: string, n: number): string {
-  return s.length <= n ? s : s.slice(0, n - 1) + "…";
-}
-
-/**
- * The document, indented for the viewer's pretty tab. Returns the RAW TEXT UNCHANGED when it
- * does not parse — re-indenting is not repair, and handing a reader a "prettified" version of
- * something the app could not read would hide the only thing they need to see.
- */
-export function jsonPretty(v: CellValue): string {
-  const raw = String(v ?? "");
-  const parsed = jsonParse(raw);
-  return parsed.ok ? JSON.stringify(parsed.value, null, 2) : raw;
-}
-
-/**
- * Wave-5 item 11 — the actionable link behind a url/email/phone value, or null when the value
- * does not parse as one (the raw text still shows; a link that goes nowhere is worse than no
- * link). url without a scheme gets https://; `javascript:` can never come out of here.
- *
- * ⭐ MOVED here from `RecordDetail.tsx` for wave-26 item 11, when the KANBAN CARD became a
- * second surface that needs it. Two copies of a scheme guard is how one of them ends up
- * accepting `javascript:` — the same argument that moved `formatDisplay`'s formula test into one
- * function after the canvas and the panel had drifted. It is also the only reason this claim is
- * testable at all: both call sites are React components, and this module is glide-free and
- * React-free, so a node gate can reach it.
- */
-export function actionHref(field: Field, v: CellValue): string | null {
-  const s = String(v ?? "").trim();
-  if (!s) return null;
-  if (field.type === "url") {
-    if (/^https?:\/\//i.test(s)) return s;
-    if (/^[\w-]+(\.[\w-]+)+/.test(s)) return `https://${s}`;
-    return null;
-  }
-  if (field.type === "email")
-    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s) ? `mailto:${s}` : null;
-  if (field.type === "phone") {
-    const digits = s.replace(/[\s().-]/g, "");
-    return /^\+?\d{5,}$/.test(digits) ? `tel:${digits}` : null;
-  }
-  return null;
-}
-
-export function formatDisplay(field: Field, v: CellValue): string {
-  switch (field.type) {
-    case "currency":
-      return v == null || v === "" ? "" : "$" + numberText(num(v), field.format);
-    case "formula": {
-      // ⛔ A FORMULA MAY RETURN TEXT (owner item 2, 2026-07-31 — CONCATENATE, `&`, TEXT(),
-      // and any `IF(cond, "yes", "no")`). `makeCell` learned that; this function did not, and
-      // the two are supposed to be one rendering. So every surface that reads THIS one —
-      // ListView, KanbanView, the calendar's summary cells, the record-detail panel and ALL
-      // FOUR export formats — printed a text result as `0`, because `num("Buy now")` is NaN.
-      // The canvas showed the words and the file showed a zero, for the same cell.
-      //
-      // Found by rendering the owner's own Buy signal formula through the shipped bundle
-      // (_qa_owner_20260803). The branch below is `makeCell`'s test, verbatim: a non-blank,
-      // non-numeric STRING is its own display.
-      // The three states, in the one order that makes them total — see `formulaIsBlank`.
-      if (formulaIsBlank(v)) return "";
-      if (formulaIsText(v)) return v;
-      return numberText(num(v), field.format);
-    }
-    case "int":
-      return v == null || v === "" ? "" : numberText(num(v), field.format);
-    case "pct":
-      return v == null || v === "" ? "" : num(v).toFixed(1) + "%";
-    case "date":
-    case "created_time":
-      return dateTimeText(field, v);
-    case "checkbox":
-      return checkboxOn(v) ? "Checked" : "";
-    case "rating": {
-      const n = num(v);
-      return n >= 1 ? `${Math.round(n)} of ${ratingMax(field)}` : "";
-    }
-    case "json":
-      // Wave-23 C7 — the SAME compact line the canvas cell paints. Explicit here rather than
-      // left to `default` for the reason the `formula` note above records: this function feeds
-      // ListView, KanbanView, the calendar, the record panel and all four EXPORT formats, and
-      // falling through would dump a whole 32 KB document into a CSV cell.
-      return jsonPreview(v);
-    case "code":
-      // ⭐ Wave-27 item 13 (R13) — the same compact line the canvas cell paints, and explicit
-      // for `json`'s exact reason: a snippet is multi-LINE, and falling through to `default`
-      // would put raw newlines into a CSV cell, a kanban card and a calendar chip.
-      return codePreview(v);
-    case "ai_enrich":
-      // ⭐⭐ Wave-34 (owner ruling R13) — an enrichment answer is model-authored PROSE and can run
-      // to several lines, so it is explicit here for exactly the reason `json` and `code` are:
-      // this function feeds ListView, KanbanView, the calendar, the record panel and all four
-      // EXPORT formats, and `default` would put raw newlines into a CSV cell.
-      // ⚠ `codePreview` is REUSED rather than given a prose-flavoured twin. Its "first line
-      // +N more" is already this product's one way of saying "a multi-line value in a one-line
-      // slot", and the count is checkable against what the drawer shows; a second helper would
-      // be a second answer to one question ([[one-question-two-normalizers]]).
-      return codePreview(v);
-    case "automation":
-      // The machine-written line, verbatim. Explicit rather than left to the `default` branch
-      // below: `formula` fell through a default once and printed every text result as `0` for
-      // months, and the lesson recorded there is that a type whose rendering is deliberate
-      // should SAY so where a reader looks for it.
-      return String(v ?? "");
-    case "metric":
-      // Wave-22 C7 — a server-computed number over the master snapshot series. BLANK IS A
-      // STATE, never zero: the engine sends "" when the window holds no snapshots, and
-      // rendering that as 0 would fabricate a measurement (the engine's own blank-never-zero
-      // law, kept at the display seam too).
-      return v == null || v === "" ? "" : numberText(num(v), field.format);
-    case "rollup": {
-      // ⭐ WAVE 29 (W29-T30) — THE MISSING CASE. `rollup` fell through to `default` and printed
-      // its raw fold string, so ONE cell rendered two ways: the canvas showed `1,491,552.43`
-      // (`cells.ts`'s rollup branch, comma-fixed 2026-08-10 on the owner's instruction) while
-      // every CSV, PDF, JSON-display and Excel export showed `1491552.43`. Same family as D-121
-      // (the record panel ignoring a field's format) — three surfaces, one concept.
-      //
-      // ⛔ THE BLANK RULE IS THE POINT, and it is why this is a guarded branch and not a call to
-      // `numberText(num(v), ...)`. `_rollup_fold` returns "" for "no rows to aggregate" and only
-      // the count family ever returns a real 0, so `num("")` — which is 0 — would paint the
-      // measurement the server just refused to invent. A fold that is not a number at all
-      // (`concatenate`, `arrayunique`, `latest` over text) keeps its own text.
-      // ⇒ Mirrors `cells.ts`'s branch line for line, deliberately: one concept, one rendering.
-      const raw = String(v ?? "");
-      const asNum = raw.trim() === "" ? NaN : Number(raw);
-      return Number.isFinite(asNum) ? numberText(asNum, field.format) : raw;
-    }
-    case "multiselect":
-      // The comma-joined SET, read back with breathing room ("A, B" not "A,B").
-      return String(v ?? "")
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s !== "")
-        .join(", ");
-    default:
-      return String(v ?? "");
-  }
-}
+// ---------------------------------------------------------------------------
+// customer-grid / display.ts
+// The pure DISPLAY-STRING half of cells.ts, split out in wave 7 (item W2): the
+// export builders run under node in the verify gates, and importing them
+// through cells.ts dragged the whole glide-data-grid package into a plain
+// script. Everything here depends only on types.ts. cells.ts re-exports these
+// names, so every existing import keeps working; the formatting is the same
+// bytes it was — this is a move, not a change.
+//
+// ⚠ W40-T24 — `columnDefinitionOffer` at the foot of this file is NOT a display
+// string, and it is here on purpose rather than by drift. It is a decision the
+// Edit-field pane takes, and the pane lives in `ColumnMenu.tsx`, which imports
+// React and therefore cannot be LOADED by the node gates — a rule stated only
+// inside JSX is a rule no gate can run. Its natural home is `types.ts` beside
+// the two predicates it composes; that file belongs to another lane this wave,
+// so it lives in the nearest module that is both node-reachable and already
+// imported by `_test/gridUx.test.ts`. If types.ts is ever free, move it there
+// and leave a re-export: what must not happen is a second copy.
+// ---------------------------------------------------------------------------
+
+import type { Field, FieldFormat } from "./types";
+import { isUserSchemaField, ratingMax } from "./types";
+
+export type CellValue = string | number | null | undefined;
+
+// --- C-AVATAR (wave-14 item 11): the two PURE halves of the assignee avatar ---
+// They live here rather than in cells.ts for this module's founding reason: cells.ts imports
+// glide, so nothing in it can be reached by a node gate. The canvas drawing stays there; the
+// arithmetic and the string handling — the parts that can be wrong in ways a screenshot of one
+// avatar will not show — are here, and `cells.ts` re-exports both.
+
+/**
+ * Up to two letters for the fallback circle.
+ *
+ * ⚠ The LOCAL PART only. Usernames in this tenant are email-shaped, and splitting
+ * "fsanyoto@gmail.com" on its separators gives ["fsanyoto@gmail", "com"] → "FC" — a person's
+ * avatar reading as their mail provider. Cutting at "@" first gives "FS".
+ *
+ * ⚠ A HYPHEN IS NOT A SEPARATOR. Space, dot and underscore divide a given name from a family
+ * name in a username; a hyphen almost always JOINS a compound one — Jo-Anne, Marie-Claire,
+ * Al-Rashid. Treating it as a separator turns "jo-anne_smith" into "JA", which is not that
+ * person's initials and is wrong in the one way nobody can spot: it looks like initials.
+ */
+export function avatarInitials(name: string): string {
+  const local = name.split("@")[0];
+  const parts = local.trim().split(/[\s._]+/).filter(Boolean);
+  if (parts.length === 0) return "?";
+  if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase();
+  return (parts[0][0] + parts[1][0]).toUpperCase();
+}
+
+/**
+ * The avatar's diameter for a row of `height` px: 22 on a comfortable row, never larger, and
+ * never so small it stops being a face. Bounded on BOTH sides on purpose — a `tall` row (48px)
+ * must not grow a 42px portrait, and a `short` one (28px) must not shrink to a dot.
+ */
+export function avatarSize(height: number): number {
+  return Math.max(14, Math.min(22, height - 6));
+}
+
+export interface UserCellData {
+  kind: "aios-user";
+  /** The assignee's username. "" = unassigned; the cell then paints nothing at all. */
+  name: string;
+  /** C-AVATAR data URL, when the workspace served one for this user. */
+  photo?: string;
+}
+
+/**
+ * The `user` cell's payload — HERE rather than inline in `cells.ts` for one reason: `copyData`.
+ *
+ * ⚠ R6 removed the NAME from the cell, so the cell renders no text at all. glide's copy and
+ * export take `copyData`, which means an assignee column silently copies and exports as EMPTY
+ * unless it is set — a real regression that appears in no screenshot, because the screenshot
+ * shows the avatar working perfectly. `cells.ts` imports glide and is therefore unreachable from
+ * a node gate; this is, so the claim can actually be asserted.
+ */
+export function userCellPayload(
+  name: string,
+  userAvatars?: Record<string, string>
+): { data: UserCellData; copyData: string } {
+  return {
+    data: { kind: "aios-user", name, photo: userAvatars?.[name] },
+    copyData: name,
+  };
+}
+
+/**
+ * The number to PAINT, with `0` as the fallback every existing caller already relies on.
+ *
+ * ⛔⛔ IT MUST PARSE THE SAME WAY THE FOLD DOES, AND FOR ONE COMMIT IT DID NOT. This was a bare
+ * `Number(v)`, so `"1,234.50"` → `NaN` → **0**: the canvas painted `$0` while the totals row
+ * underneath counted 1,234.5. The T81 fix that introduced `numericIsBlank` made the BLANK
+ * decision consistent and left the VALUE on this function, so the cell stopped being blank and
+ * started being a fabricated zero — the exact defect T81 exists to kill, one step to the right.
+ * ⚠ Caught by an adversarial read, NOT by the leg named "the fold counts exactly what the cell
+ * shows" — which only ever called `computeAggs` and never evaluated what the cell shows. A test
+ * whose NAME makes a claim its assertion does not is worse than no test.
+ * ⚠ REACHABLE, and by more than one path: the import door refuses-without-rewriting (so `$45`
+ * is storable by design, and `api_api` asserts it imports), and `automation_engine._rollup_fold`
+ * returns raw source cells as STRINGS for `latest`/`min`/`max`.
+ */
+export function num(v: CellValue): number {
+  return numericOrUndefined(v) ?? 0;
+}
+
+/**
+ * ⛔ W29-T81 — HAS THIS NUMERIC CELL NOTHING TO SHOW? Blank, or a stored value that is not a
+ * number at all.
+ *
+ * `num()` above answers **0** for anything unparseable, which is a measurement where there was
+ * none. That is survivable for a column only this app writes; it stopped being survivable when
+ * the import door began accepting rows from a spreadsheet — a `qty` column holding
+ * "seventeen-ish" painted `0` on the canvas while the record panel honestly showed an em-dash.
+ * Two surfaces disagreeing about the same cell, and the one that looks authoritative is the one
+ * making the number up.
+ *
+ * ⚠ The FOLD was already right (`aggregations.numOf` skips what will not parse), so the totals
+ * row never counted these — it is the painted cell alone. Same family as `formulaIsText` below,
+ * asked of the RAW value for the same reason.
+ * ⚠ `"  "` is blank, not a zero: `Number("  ")` is 0, which is how a whitespace cell becomes a
+ * number nobody typed.
+ */
+export function numericIsBlank(v: CellValue): boolean {
+  return numericOrUndefined(v) === undefined;
+}
+
+/**
+ * ⛔⛔ THE ONE NUMERIC READING OF A STORED CELL, and it has to be one.
+ *
+ * `numericIsBlank` decides whether the CANVAS paints anything; `aggregations.numOf` decides
+ * whether the TOTALS ROW counts it. They were written separately and normalised differently —
+ * this one trimmed, that one stripped `$`, `,` and spaces — so `"1,234.50"` painted BLANK in the
+ * cell and was COUNTED in the total underneath it. That is T81's own defect ("two surfaces
+ * disagreeing about one cell") reintroduced in the opposite direction, by the fix for it, and no
+ * test could see it because every value in the legs was comma-free.
+ *
+ * ⚠ Human spellings are ACCEPTED here on purpose. `coerceClipboardValue` canonicalises what the
+ * UI writes, but the import door refuses-without-rewriting by design, so a `"$45"` posted by curl
+ * is storable — and the honest reading of that cell is 45 on BOTH surfaces, never 45 in the total
+ * and nothing in the cell ([[one-evaluator-per-question]]).
+ */
+export function numericOrUndefined(v: CellValue): number | undefined {
+  if (v === null || v === undefined || v === "") return undefined;
+  if (typeof v === "number") return Number.isFinite(v) ? v : undefined;
+  const cleaned = String(v).replace(/[$,\s]/g, "");
+  if (cleaned === "") return undefined;          // "  " is blank, not the zero `Number("")` gives
+  const n = Number(cleaned);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * ⛔ IS THIS FORMULA RESULT TEXT? — and it must be asked of the RAW value.
+ *
+ * A formula may return text since 2026-07-31 (owner item 2: CONCATENATE, `&`, TEXT(),
+ * TRUE/FALSE, and any `IF(cond, "yes", "no")`). Both renderers tried to detect that with
+ * `!Number.isFinite(num(v))` — and `num()` above returns **0** for anything non-finite, so the
+ * test was `Number.isFinite(0)`, which is always true. The text branch therefore never ran in
+ * EITHER renderer, and every text-returning formula printed as `0`: on the canvas, in the list,
+ * on kanban cards, in the record panel and in all four export formats.
+ *
+ * The feature had never worked. It surfaced by rendering the owner's own Buy signal formula
+ * through the shipped bundle rather than by asking whether the code looked right.
+ *
+ * ONE function, exported, called by both `formatDisplay` and `makeCell` — they are meant to be
+ * one rendering, and the way they drifted was each holding its own copy of this test.
+ * `Number("")` is 0, so the empty case is excluded explicitly rather than relied upon.
+ *
+ * A TYPE PREDICATE, not a bare boolean: `makeCell` builds a `TextCell` from the value straight
+ * after this test, and without the narrowing the caller has to re-assert the string it just
+ * proved — which is the kind of cast that outlives the reason for it.
+ */
+export function formulaIsText(v: CellValue): v is string {
+  return typeof v === "string" && v.trim() !== "" && !Number.isFinite(Number(v));
+}
+
+/**
+ * ⛔ AND THE BLANK TEST HAS TO AGREE WITH IT, or a value falls between the two.
+ *
+ * `formulaIsText` excludes whitespace-only strings (a `"  "` result is not TEXT worth painting).
+ * The callers' own blank guard was `v === ""`, which does not catch `"  "` — so a formula
+ * returning a space matched NEITHER, fell through to the numeric path, and printed `0`, because
+ * `Number(" ")` is 0. The exact bug this pair was written to fix, surviving in a narrower case.
+ *
+ * A formula's result is therefore one of exactly three things, and these two predicates make the
+ * three TOTAL: blank (null, empty, or whitespace), text, or a number. Reachable in practice —
+ * `CONCATENATE(" ", "")` is a space, and so is `TRIM()` of one.
+ */
+export function formulaIsBlank(v: CellValue): boolean {
+  return v == null || (typeof v === "string" && v.trim() === "");
+}
+
+/** A checkbox cell's boolean, out of the overlay's '1'-or-empty contract. */
+export function checkboxOn(v: CellValue | boolean): boolean {
+  return v === "1" || v === 1 || v === true;
+}
+
+/**
+ * Item 10 — the number DISPLAY string. With no format: exactly the pre-wave-5
+ * rendering (toLocaleString). `abbrev` wins over decimals when the magnitude
+ * calls for it (34.0M — one decimal, k/M/B); `thousands: false` drops the
+ * separators; `decimals` fixes 0..4 places.
+ */
+export function numberText(v: number, fmt: FieldFormat | undefined): string {
+  if (fmt?.abbrev && Math.abs(v) >= 1000) {
+    const abs = Math.abs(v);
+    const [div, suffix] =
+      abs >= 1e9 ? [1e9, "B"] : abs >= 1e6 ? [1e6, "M"] : [1e3, "k"];
+    return (v / div).toFixed(1) + suffix;
+  }
+  const d =
+    fmt && Number.isInteger(fmt.decimals) && (fmt.decimals as number) >= 0 &&
+    (fmt.decimals as number) <= 4
+      ? (fmt.decimals as number)
+      : null;
+  const thousands = fmt?.thousands !== false;
+  if (d != null)
+    return thousands
+      ? v.toLocaleString(undefined, {
+          minimumFractionDigits: d,
+          maximumFractionDigits: d,
+        })
+      : v.toFixed(d);
+  return thousands ? v.toLocaleString() : String(v);
+}
+
+/**
+ * Parse a stored date/datetime string. Odoo datetimes arrive as
+ * "YYYY-MM-DD HH:MM:SS" and are UTC by Odoo convention, so a time-carrying
+ * value with no zone gets a Z; a bare date keeps today's parse (UTC midnight)
+ * so format-less rendering stays byte-identical to the pre-wave-5 path.
+ *
+ * ⭐ EXPORTED in wave 29 (W29-T30) because the xlsx writer needs a Date to turn
+ * into an Excel serial, and the alternative was a SECOND date parser in
+ * `export.ts` — two evaluators for one question, which is how the two drift and
+ * a stamp exports as a different day than it renders
+ * ([[one-evaluator-per-question]]). It stays the only parser in this module.
+ */
+export function parseStamp(raw: string): Date | null {
+  const s = raw.includes(" ") ? raw.replace(" ", "T") : raw;
+  const iso =
+    /T\d{2}:\d{2}/.test(s) && !/(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(s) ? s + "Z" : s;
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** A BARE calendar day: the shape Odoo sends for a `date`, and the shape wave 26's migration
+ *  converted the Instagram preset stamps into. `parseStamp` gives it UTC midnight. */
+const BARE_DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Is this stored value a calendar DAY rather than an INSTANT? — the question that decides which
+ * clock renders it (see `dateTimeText`).
+ *
+ * Exported, and it is the whole reason the test for this is worth anything: the alternative is
+ * asserting a rendered string, which depends on the machine's timezone — so the check would pass
+ * on the owner's box (+07:00, where the two clocks agree on the day) and could only ever go red
+ * somewhere else. A predicate is the same decision with no ambient state in it.
+ *
+ * ⚠ The SHAPE OF THE RAW STRING, never `field.type`: wave 26 re-typed columns that hold full ISO
+ * stamps to `date`, so one `date` field can carry both shapes at once during a migration.
+ */
+export function isBareDay(v: CellValue): boolean {
+  return BARE_DAY.test(String(v ?? "").trim());
+}
+
+/**
+ * ⭐ Wave-26 item 3 (owner, R3) — the day, spelled. `Aug 5, 2026`, never `8/5/2026` and never
+ * the raw stamp. One vocabulary for the date half whether or not a time follows it, so a
+ * `date` column and a `created_time` column in the same table read alike.
+ */
+const DAY_PARTS = { year: "numeric", month: "short", day: "numeric" } as const;
+
+/**
+ * Item 10 — the date DISPLAY string. `time` includes the time of day
+ * (created_time defaults to true — a creation stamp without its time reads as
+ * a duplicate of nothing); `tz: 'utc'` renders the tenant-neutral clock.
+ * Unparseable input renders VERBATIM rather than "Invalid Date" — the raw
+ * string is at least true.
+ *
+ * ⭐ WAVE 26 ITEM 3 (owner, via R3). The complaint was literal: cells read
+ * `2026-08-05T14:03:11+07:00`. SESSION A's half re-typed the Instagram preset
+ * columns from `text` to `date` (which is what routed them here at all) and
+ * migrated the stored cells to bare `YYYY-MM-DD`; this half is that a date must
+ * READ as one. Two changes, and the second is the one that is not cosmetic:
+ *
+ * ⛔ **A BARE `YYYY-MM-DD` IS A CALENDAR DAY, NOT AN INSTANT, so it renders in
+ * UTC.** `parseStamp` gives a bare date UTC midnight, so rendering it in the
+ * viewer's local zone shows the PREVIOUS DAY to everyone west of Greenwich — a
+ * value stored as the 5th reading as the 4th, silently, for a whole hemisphere.
+ * `ui/fmt.ts:date()` already refused to inherit this and its comment names this
+ * function as the holdout; it is no longer one. The tenant runs at +07:00, where
+ * the two agree, which is exactly why it could sit here unnoticed — and why the
+ * US market in COMMERCIALIZATION_PLAN C1b would have met it first.
+ *
+ * A value that CARRIES a time is a real instant and keeps the existing zone
+ * behaviour (local, or UTC when the field says so): shifting those to UTC would
+ * introduce the same off-by-a-day from the other direction.
+ */
+export function dateTimeText(
+  // ⚠ STRUCTURAL, not `Field`: this reads exactly two members, and item 8's post rows hold a
+  // raw `posted_at` with no column behind it. Widening the parameter (rather than fabricating a
+  // fake Field at the call site) is what lets the posts list render its days through the SAME
+  // formatter as a date cell instead of growing a second one. Every existing caller passes a
+  // `Field`, which is assignable.
+  field: { type: Field["type"]; format?: FieldFormat },
+  v: CellValue
+): string {
+  if (v == null || v === "") return "";
+  const raw = String(v);
+  const d = parseStamp(raw);
+  if (!d) return raw;
+  const fmt = field.format;
+  const withTime = fmt?.time ?? field.type === "created_time";
+  const utc = fmt?.tz === "utc" || isBareDay(raw);
+  const zone = utc ? { timeZone: "UTC" as const } : undefined;
+  return withTime
+    ? d.toLocaleString(undefined, {
+        ...DAY_PARTS,
+        hour: "numeric",
+        minute: "2-digit",
+        second: "2-digit",
+        ...zone,
+      })
+    : d.toLocaleDateString(undefined, { ...DAY_PARTS, ...zone });
+}
+
+/**
+ * The plain-string rendering of one (field, value), mirroring makeCell's
+ * displayData. Reused by the record-detail panel and the W2 export builders so
+ * a value reads identically on the canvas, in the panel and in a file. Returns
+ * "" for empty so callers can substitute their own placeholder.
+ */
+/**
+ * Wave-18 C5-AUTOFIELD — the STATE word of an automation cell.
+ *
+ * An automation cell holds one machine-written line: `state · when · detail`, e.g.
+ * `ok · 2026-08-03 14:10 · 12 posts`. The state is the first token, and every surface that
+ * paints the cell — canvas tint, record modal, the rail — reads it through HERE rather than
+ * re-splitting the string, because two parsers of one format is how the canvas and the panel
+ * end up disagreeing about whether a run succeeded (the exact way `formula` broke above).
+ *
+ * `"none"` is the honest answer for a cell nothing has written yet — NOT "ok". A column that
+ * has never run must not look like a column that ran and found nothing.
+ */
+export type AutomationState = "ok" | "partial" | "error" | "blocked" | "queued" | "none";
+
+const AUTOMATION_STATES: AutomationState[] = ["ok", "partial", "error", "blocked", "queued"];
+
+export function automationState(v: CellValue): AutomationState {
+  const head = String(v ?? "").split("·")[0].trim().toLowerCase();
+  return (AUTOMATION_STATES as string[]).includes(head)
+    ? (head as AutomationState)
+    : "none";
+}
+
+/** Everything after the state word — the timestamp and the run's own detail. */
+export function automationDetail(v: CellValue): string {
+  const parts = String(v ?? "").split("·");
+  return parts.length > 1 ? parts.slice(1).join("·").trim() : "";
+}
+
+/** Sentence-cased state, for anywhere a word reads better than a token. */
+export function automationStateLabel(v: CellValue): string {
+  const s = automationState(v);
+  return s === "none" ? "Not run yet" : s[0].toUpperCase() + s.slice(1);
+}
+
+/**
+ * ⭐ Wave-23 C7 (owner item 5) — THE JSON PREVIEW: what a 200px cell says about a document.
+ *
+ * `MAX_JSON_BYTES` is the contract's ceiling, mirrored from the host's write validation so the
+ * viewer can refuse a paste with the same number the server would (a client that lets you type
+ * 40 KB and then shows you a server refusal has wasted the edit).
+ *
+ * The four cases, and each one is a decision rather than a formatting preference:
+ *   · **a single-pair object shows THE PAIR.** `{handle: "royalimports"}` is more useful than
+ *     "1 key" and it is the shape most machine writes actually have. Past one pair the pairs
+ *     stop fitting and the honest answer is the count.
+ *   · **many keys / many items → `{…} N keys` / `[…] N items`.** Showing the FIRST pair of a
+ *     twelve-key object would let a reader take one arbitrary value — whichever key the writer's
+ *     serializer happened to emit first — for the cell's content.
+ *   · **a bare scalar renders as itself.** `12`, `"ok"`, `true` and `null` are all valid JSON
+ *     documents, and wrapping them in braces would describe a shape they do not have.
+ *   · ⛔ **text that does not parse renders AS ITSELF, never as a shape.** The host validates on
+ *     write, so this only happens to a value that predates the validation or arrived another
+ *     way — and the one thing the preview must never do is claim a document is well-formed. The
+ *     viewer's raw tab is where such a value gets read and repaired.
+ *
+ * Blank stays blank: an empty json cell is a document nobody has written, and `{}` is a document
+ * somebody wrote that is empty. Two different facts, two different cells.
+ */
+export const MAX_JSON_BYTES = 32 * 1024;
+
+/**
+ * ⭐ WAVE 31 · T22 (D-173) — is this parsed value the SERVER'S STAND-IN for a document it did not
+ * send, and if so how big was the real one? Returns a short size string, or null.
+ *
+ * ⛔ THE SHAPE IS `routes_tables._thin_json`'s OWN, and it is matched on `_truncated === true`
+ * plus a numeric `bytes` — never on the key alone, because a person's own document could contain
+ * a `_truncated` key and must not be reported as absent. `_url` is deliberately NOT required: the
+ * viewer keys its fetch on it, but a preview that refused to warn when it was missing would go
+ * quiet in exactly the degraded case that most needs a warning.
+ */
+export function truncatedDoc(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value as Record<string, unknown>;
+  if (v._truncated !== true) return null;
+  const bytes = typeof v.bytes === "number" && isFinite(v.bytes) ? Math.max(0, v.bytes) : 0;
+  if (!bytes) return "not shown";
+  return bytes >= 1024 ? `${Math.round(bytes / 1024).toLocaleString()} KB not shown`
+                       : `${bytes.toLocaleString()} bytes not shown`;
+}
+
+/** Does this text parse as JSON? The ONE test, shared by the preview, the cell and the viewer's
+ *  save — three copies of a try/catch is how they end up disagreeing about `""` or `NaN`. */
+export function jsonParse(v: CellValue): { ok: boolean; value?: unknown } {
+  const s = String(v ?? "").trim();
+  if (s === "") return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(s) as unknown };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * ⭐ WAVE-27 item 13 (R13) — one compact line for a CODE cell.
+ *
+ * Deliberately NOT `jsonPreview`, and the difference is the whole reason `code` is its own kind:
+ * a json preview SUMMARISES a parsed document ("{…} 5 keys"), which it can only do because the
+ * value is guaranteed to parse. A snippet has no structure to summarise and often does not parse
+ * at all — half-written SQL is the normal state of one — so the honest preview is the first
+ * non-blank LINE, clipped, plus the line count when there is more underneath. That way the cell
+ * says what the snippet starts with AND that there is more, instead of inventing a shape for it.
+ */
+export function codePreview(v: CellValue): string {
+  const raw = String(v ?? "");
+  if (raw.trim() === "") return "";
+  const lines = raw.split("\n");
+  const firstIdx = lines.findIndex((l) => l.trim() !== "");
+  const first = clip((lines[firstIdx < 0 ? 0 : firstIdx] ?? "").trim(), 60);
+  // The count is of REAL lines, so a snippet padded with blank lines does not claim depth it
+  // does not have — and it is checkable against what opening the editor shows
+  // ([[no-unverifiable-aggregates]]).
+  const n = lines.filter((l) => l.trim() !== "").length;
+  return n > 1 ? `${first}  +${n - 1} more` : first;
+}
+
+/**
+ * ⭐⭐ W37-T14 / T15 — THE TWO SHAPES WAVE 37 ADDED, READ AS WHAT THEY ARE.
+ *
+ * ⛔ FOUND BY QA ON THE DEPLOYED BUILD, not by a gate: `1.5BOPP`'s Units cell rendered
+ * **`[…] 2 items`** and its Tier prices cell the same way, because both are `type: "json"` and
+ * both fell through to the generic array branch below. The server was serving the right data the
+ * whole time — `[{name:"SLEEVE",qty:12},{name:"Master",qty:144}]` — and the grid said nothing
+ * about it. A column whose entire job is to show which units a SKU sells in, showing a count of
+ * items, is the [[permitted-is-not-answerable]] shape in the RENDER layer.
+ *
+ * ⚠ KEYED ON THE SHAPE, NEVER ON THE COLUMN KEY. A key test (`field.key === "units"`) would
+ * miss the same document on a user database, on a rollup, or under any rename — and this file
+ * has no access to the field anyway. Both shapes are exact: EVERY element must be an object
+ * carrying exactly the pair, so an unrelated array of objects still falls through to the generic
+ * branch and is not silently relabelled.
+ *
+ * ⚠ `×` is U+00D7 MULTIPLICATION SIGN and `·` is U+00B7 MIDDLE DOT — neither is an em or en
+ * dash, so this copy is inside standing rule 2 rather than an exception to it.
+ */
+function namedPairList(value: unknown): string | null {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  const rows = value as Record<string, unknown>[];
+  const every = (a: string, b: string) =>
+    rows.every(
+      (r) =>
+        r !== null &&
+        typeof r === "object" &&
+        !Array.isArray(r) &&
+        typeof r[a] === "string" &&
+        typeof r[b] === "number",
+    );
+  // W37-T15 — units of measure: the NAME and its conversion factor, which is the whole point.
+  if (every("name", "qty"))
+    return rows.map((r) => `${String(r.name)} ×${trimNum(r.qty as number)}`).join(" · ");
+  // W37-T14 — the pricelists that really price this SKU today, each with its price.
+  if (every("pricelist", "unit_price"))
+    return rows
+      .map((r) => `${String(r.pricelist)} $${numberText(r.unit_price as number, { decimals: 2 })}`)
+      .join(" · ");
+  return null;
+}
+
+/** `12` not `12.0`, and `1.5` kept — a conversion factor is a count far more often than not. */
+function trimNum(n: number): string {
+  return Number.isFinite(n) ? String(Number(n.toFixed(4))) : String(n);
+}
+
+/** One compact line for a json cell. See the note above for why each case reads as it does. */
+export function jsonPreview(v: CellValue): string {
+  const raw = String(v ?? "").trim();
+  if (raw === "") return "";
+  const parsed = jsonParse(raw);
+  // ⚠ First line only, and clipped: an unparseable value is often a whole pasted response, and
+  // a cell is not where a 4 KB blob gets read. It is shown rather than hidden because the
+  // reader has to be able to see that the column holds something the app could not open.
+  if (!parsed.ok) return clip(raw.split("\n")[0], 60);
+  const value = parsed.value;
+  // ⭐ ITEM 8 — a posts window says what it holds. Before wave 26 this document fell through to
+  // the generic object branch and every creator's `posts` cell read `{…} 4 keys`, which is true
+  // about JSON and says nothing about the record.
+  // ⚠ The ARRAY LENGTH, never the document's own `n`: the count in a cell has to be checkable
+  // against what opening it shows ([[no-unverifiable-aggregates]]).
+  // ⭐⭐ WAVE 31 · T22 (D-173) — A DOCUMENT THE LIST DID NOT SEND SAYS SO, WITH ITS SIZE.
+  //
+  // ⛔ THE SWALLOW, and it is one branch below this one. `routes_tables._thin_json` replaces an
+  // oversized `json` cell with a stand-in — `{_truncated, bytes, _url}` — so the big document
+  // does not ride a list response (measured: `source_payload` was 95.6–98.5% of every IG grid's
+  // bytes). That stand-in is itself valid JSON with three keys, so it fell through to the generic
+  // object branch and the cell read **`{…} 3 keys`** — a confident, checkable-looking claim about
+  // a document that is not there, and indistinguishable from a real three-key document. R6's
+  // second sentence applies to our own wire: a value we declined to send is reported, never
+  // disguised.
+  // ⚠ THE SIZE IS THE SERVER'S OWN `bytes`, not a guess, and it is what makes the cell honest —
+  // "this column holds 41 KB you have not been shown" is a different fact from "3 keys".
+  const thinned = truncatedDoc(value);
+  if (thinned) return `{…} ${thinned}`;
+  const shown = postsWindowOf(value);
+  if (shown)
+    return shown.posts.length === 0
+      ? "No posts"
+      : `${shown.posts.length} post${shown.posts.length === 1 ? "" : "s"}`;
+  // ⭐ W37-T14/T15 — the two known shapes read as themselves; anything else keeps the old count.
+  const pairs = namedPairList(value);
+  if (pairs) return clip(pairs, 60);
+  if (Array.isArray(value))
+    return value.length === 0 ? "[]" : `[…] ${value.length} item${value.length === 1 ? "" : "s"}`;
+  if (value !== null && typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>);
+    if (keys.length === 0) return "{}";
+    if (keys.length === 1)
+      return clip(`{${keys[0]}: ${scalarText((value as Record<string, unknown>)[keys[0]])}}`, 60);
+    return `{…} ${keys.length} keys`;
+  }
+  return clip(scalarText(value), 60);
+}
+
+/** The day, spelled, for a caller holding a raw value and no column — the posts list's
+ *  `posted_at`. Routed through `dateTimeText` so it can never drift from a date CELL. */
+export function dayText(v: CellValue): string {
+  return dateTimeText({ type: "date" }, v);
+}
+
+/* ═══ ⭐ WAVE 26 ITEM 8 (contract C2) — THE `posts` WINDOW ═══
+   The preset `posts` cell holds ONE object written by the engine's `posts_window`:
+
+     { n, metrics, as_of, posts: [{ shortcode, url, posted_at, type, caption,
+                                    views?, likes?, comments? }] }
+
+   Two laws come with it and both are enforced below rather than in the components:
+
+   ⛔ `metrics: false` ⇒ views/likes/comments are ABSENT KEYS, NEVER 0. A reader must render an
+      absent metric as NOTHING. Coercing it to a number here — `Number(p.views) || 0` is the
+      natural thing to type — would fabricate a measurement, which is the engine's own
+      blank-never-zero law broken at the display seam, silently and plausibly (a creator with no
+      metrics bought would read as a creator with no engagement).
+
+   ⛔ IT IS A WINDOW, NOT THE HISTORY. `ut_ig_posts` / `ut_ig_post_snapshots` accumulate; this
+      cell is the last N (R1/R3 — "one store for one series"). So nothing here may present the
+      cell as a total.
+
+   ⚠ DETECTED BY SHAPE, never by the field's key. A user may name a column `posts`, and the
+   preset key is not a contract the renderer can see from the value alone. An object carrying a
+   `posts` ARRAY OF OBJECTS is what makes "3 posts" a true sentence about it, whoever wrote it.
+   ═══ */
+export interface PostSummary {
+  shortcode?: string;
+  url?: string;
+  posted_at?: string;
+  type?: string;
+  caption?: string;
+  /** ⛔ `undefined` when the metric was not bought. Never 0 — see the note above. */
+  views?: number;
+  likes?: number;
+  comments?: number;
+}
+
+export interface PostsWindow {
+  /** The engine's own count. May differ from `posts.length`; readers show the LENGTH, because
+   *  that is the number a reader can check against what is in front of them. */
+  n: number;
+  metrics: boolean;
+  as_of?: string;
+  posts: PostSummary[];
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/** ⛔ A number ONLY when the key really holds one. `undefined` for absent, for null, and for a
+ *  non-numeric — anything else invents a measurement. */
+function metric(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/** The window behind an ALREADY-PARSED value, or null when this is not one. */
+export function postsWindowOf(value: unknown): PostsWindow | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  const doc = value as Record<string, unknown>;
+  const rows = doc.posts;
+  if (!Array.isArray(rows)) return null;
+  if (!rows.every((r) => r !== null && typeof r === "object" && !Array.isArray(r))) return null;
+  const posts: PostSummary[] = rows.map((r) => {
+    const p = r as Record<string, unknown>;
+    return {
+      shortcode: str(p.shortcode),
+      url: str(p.url),
+      posted_at: str(p.posted_at),
+      type: str(p.type),
+      caption: str(p.caption),
+      views: metric(p.views),
+      likes: metric(p.likes),
+      comments: metric(p.comments),
+    };
+  });
+  return {
+    n: typeof doc.n === "number" ? doc.n : posts.length,
+    metrics: doc.metrics === true,
+    as_of: str(doc.as_of),
+    posts,
+  };
+}
+
+/** The window behind a stored CELL, or null. */
+export function postsWindow(v: CellValue): PostsWindow | null {
+  const parsed = jsonParse(v);
+  return parsed.ok ? postsWindowOf(parsed.value) : null;
+}
+
+/** A nested value, small enough to sit inside a one-pair preview. Objects and arrays collapse
+ *  to their own marks rather than recursing — a preview that unfolds is not a preview. */
+function scalarText(v: unknown): string {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return `[…] ${v.length}`;
+  if (typeof v === "object") return `{…} ${Object.keys(v as object).length}`;
+  return typeof v === "string" ? v : String(v);
+}
+
+/** ⚠ An ellipsis CHARACTER, not three dots: the grid's canvas measures text and three periods
+ *  are three glyphs wide. Same mark the group-bar fitter uses. */
+function clip(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}
+
+/**
+ * The document, indented for the viewer's pretty tab. Returns the RAW TEXT UNCHANGED when it
+ * does not parse — re-indenting is not repair, and handing a reader a "prettified" version of
+ * something the app could not read would hide the only thing they need to see.
+ */
+export function jsonPretty(v: CellValue): string {
+  const raw = String(v ?? "");
+  const parsed = jsonParse(raw);
+  return parsed.ok ? JSON.stringify(parsed.value, null, 2) : raw;
+}
+
+/**
+ * Wave-5 item 11 — the actionable link behind a url/email/phone value, or null when the value
+ * does not parse as one (the raw text still shows; a link that goes nowhere is worse than no
+ * link). url without a scheme gets https://; `javascript:` can never come out of here.
+ *
+ * ⭐ MOVED here from `RecordDetail.tsx` for wave-26 item 11, when the KANBAN CARD became a
+ * second surface that needs it. Two copies of a scheme guard is how one of them ends up
+ * accepting `javascript:` — the same argument that moved `formatDisplay`'s formula test into one
+ * function after the canvas and the panel had drifted. It is also the only reason this claim is
+ * testable at all: both call sites are React components, and this module is glide-free and
+ * React-free, so a node gate can reach it.
+ */
+export function actionHref(field: Field, v: CellValue): string | null {
+  const s = String(v ?? "").trim();
+  if (!s) return null;
+  if (field.type === "url") {
+    if (/^https?:\/\//i.test(s)) return s;
+    if (/^[\w-]+(\.[\w-]+)+/.test(s)) return `https://${s}`;
+    return null;
+  }
+  if (field.type === "email")
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s) ? `mailto:${s}` : null;
+  if (field.type === "phone") {
+    const digits = s.replace(/[\s().-]/g, "");
+    return /^\+?\d{5,}$/.test(digits) ? `tel:${digits}` : null;
+  }
+  return null;
+}
+
+export function formatDisplay(field: Field, v: CellValue): string {
+  switch (field.type) {
+    case "currency":
+      return v == null || v === "" ? "" : "$" + numberText(num(v), field.format);
+    case "formula": {
+      // ⛔ A FORMULA MAY RETURN TEXT (owner item 2, 2026-07-31 — CONCATENATE, `&`, TEXT(),
+      // and any `IF(cond, "yes", "no")`). `makeCell` learned that; this function did not, and
+      // the two are supposed to be one rendering. So every surface that reads THIS one —
+      // ListView, KanbanView, the calendar's summary cells, the record-detail panel and ALL
+      // FOUR export formats — printed a text result as `0`, because `num("Buy now")` is NaN.
+      // The canvas showed the words and the file showed a zero, for the same cell.
+      //
+      // Found by rendering the owner's own Buy signal formula through the shipped bundle
+      // (_qa_owner_20260803). The branch below is `makeCell`'s test, verbatim: a non-blank,
+      // non-numeric STRING is its own display.
+      // The three states, in the one order that makes them total — see `formulaIsBlank`.
+      if (formulaIsBlank(v)) return "";
+      if (formulaIsText(v)) return v;
+      return numberText(num(v), field.format);
+    }
+    case "int":
+      return v == null || v === "" ? "" : numberText(num(v), field.format);
+    case "pct":
+      return v == null || v === "" ? "" : num(v).toFixed(1) + "%";
+    case "date":
+    case "created_time":
+      return dateTimeText(field, v);
+    case "checkbox":
+      return checkboxOn(v) ? "Checked" : "";
+    case "rating": {
+      const n = num(v);
+      return n >= 1 ? `${Math.round(n)} of ${ratingMax(field)}` : "";
+    }
+    case "json":
+      // Wave-23 C7 — the SAME compact line the canvas cell paints. Explicit here rather than
+      // left to `default` for the reason the `formula` note above records: this function feeds
+      // ListView, KanbanView, the calendar, the record panel and all four EXPORT formats, and
+      // falling through would dump a whole 32 KB document into a CSV cell.
+      return jsonPreview(v);
+    case "code":
+      // ⭐ Wave-27 item 13 (R13) — the same compact line the canvas cell paints, and explicit
+      // for `json`'s exact reason: a snippet is multi-LINE, and falling through to `default`
+      // would put raw newlines into a CSV cell, a kanban card and a calendar chip.
+      return codePreview(v);
+    case "ai_enrich":
+      // ⭐⭐ Wave-34 (owner ruling R13) — an enrichment answer is model-authored PROSE and can run
+      // to several lines, so it is explicit here for exactly the reason `json` and `code` are:
+      // this function feeds ListView, KanbanView, the calendar, the record panel and all four
+      // EXPORT formats, and `default` would put raw newlines into a CSV cell.
+      // ⚠ `codePreview` is REUSED rather than given a prose-flavoured twin. Its "first line
+      // +N more" is already this product's one way of saying "a multi-line value in a one-line
+      // slot", and the count is checkable against what the drawer shows; a second helper would
+      // be a second answer to one question ([[one-question-two-normalizers]]).
+      return codePreview(v);
+    case "automation":
+      // The machine-written line, verbatim. Explicit rather than left to the `default` branch
+      // below: `formula` fell through a default once and printed every text result as `0` for
+      // months, and the lesson recorded there is that a type whose rendering is deliberate
+      // should SAY so where a reader looks for it.
+      return String(v ?? "");
+    case "metric":
+      // Wave-22 C7 — a server-computed number over the master snapshot series. BLANK IS A
+      // STATE, never zero: the engine sends "" when the window holds no snapshots, and
+      // rendering that as 0 would fabricate a measurement (the engine's own blank-never-zero
+      // law, kept at the display seam too).
+      return v == null || v === "" ? "" : numberText(num(v), field.format);
+    case "rollup": {
+      // ⭐ WAVE 29 (W29-T30) — THE MISSING CASE. `rollup` fell through to `default` and printed
+      // its raw fold string, so ONE cell rendered two ways: the canvas showed `1,491,552.43`
+      // (`cells.ts`'s rollup branch, comma-fixed 2026-08-10 on the owner's instruction) while
+      // every CSV, PDF, JSON-display and Excel export showed `1491552.43`. Same family as D-121
+      // (the record panel ignoring a field's format) — three surfaces, one concept.
+      //
+      // ⛔ THE BLANK RULE IS THE POINT, and it is why this is a guarded branch and not a call to
+      // `numberText(num(v), ...)`. `_rollup_fold` returns "" for "no rows to aggregate" and only
+      // the count family ever returns a real 0, so `num("")` — which is 0 — would paint the
+      // measurement the server just refused to invent. A fold that is not a number at all
+      // (`concatenate`, `arrayunique`, `latest` over text) keeps its own text.
+      // ⇒ Mirrors `cells.ts`'s branch line for line, deliberately: one concept, one rendering.
+      const raw = String(v ?? "");
+      const asNum = raw.trim() === "" ? NaN : Number(raw);
+      return Number.isFinite(asNum) ? numberText(asNum, field.format) : raw;
+    }
+    case "multiselect":
+      // The comma-joined SET, read back with breathing room ("A, B" not "A,B").
+      return String(v ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "")
+        .join(", ");
+    default:
+      return String(v ?? "");
+  }
+}
+
+// --- W40-T23: the two rules behind "typing a letter opens the picker" ---------
+// MOVED here from cells.ts, for this module's founding reason and no other: cells.ts imports
+// `GridCellKind` as a VALUE, so nothing in it can be reached by a node gate, and these two are
+// exactly the kind of decision that can be wrong in ways a screenshot will never show — which
+// keystroke counts as typing, and which choices a query keeps. cells.ts re-exports both, so
+// every existing import keeps working; the bodies are the same bytes they were — this is a
+// move, not a change.
+//
+// Their consumers are two DIFFERENT controls — the grid's anchored picker and the record
+// drawer's chip row — which is the whole reason they are functions rather than expressions
+// inside one handler. One rule, two surfaces, no second copy to drift.
+
+/**
+ * The character a keystroke should SEED a choice picker with, or `null` when the keystroke is
+ * not somebody typing.
+ *
+ * ⛔ THE `null` CASES ARE THE CONTRACT, not the leftovers. `Ctrl+C` must still copy, `Enter`
+ * must still walk the column, `ContextMenu` must still open the header menu — each of those is
+ * a live branch of `onGridKeyDown` that this predicate has to decline before it runs.
+ *
+ * · one code point only, so every named key (`Enter`, `ArrowDown`, `Tab`, `F2`, `ContextMenu`)
+ *   is rejected by LENGTH rather than by a list somebody has to keep complete;
+ * · no Ctrl / Meta / Alt, which is what keeps `Ctrl+C` a copy and `Alt+F` a menu;
+ * · SHIFT IS DELIBERATELY NOT TESTED — `Shift+V` is a capital V, and a guard copied from the
+ *   Enter branch (where Shift means "go up") would ship a feature that works on `v` and not on
+ *   `V`;
+ * · a SPACE is refused. It reads as "no filter" anyway once trimmed, and in the record drawer
+ *   Space is the key that ACTIVATES the focused chip — a bare keystroke must never write a
+ *   value.
+ */
+export function pickerTypeSeed(
+  key: string,
+  mods: { ctrlKey?: boolean; metaKey?: boolean; altKey?: boolean }
+): string | null {
+  if (mods.ctrlKey || mods.metaKey || mods.altKey) return null;
+  // `[...key]` counts CODE POINTS, not UTF-16 units: an astral character arrives as a
+  // length-2 string and is one keystroke, so `key.length === 1` would silently refuse it.
+  const chars = [...key];
+  if (chars.length !== 1) return null;
+  if (key === " ") return null;
+  return key;
+}
+
+/**
+ * Which choices survive a query. The house rule, verbatim from `FieldSelect.tsx`: trimmed,
+ * case-insensitive, SUBSTRING (not prefix) — so "v" finds "Delivered" as well as "Void", which
+ * is what a person means by "filter to options containing v".
+ *
+ * An empty (or all-whitespace) query returns the list unchanged, so the seeded and unseeded
+ * pickers are the same component in the same state rather than two code paths.
+ *
+ * ⚠ Returns a COPY, never the input array: the grid maps over the result every render, and a
+ * caller that sorted or spliced an alias of the field's own choice list would be editing the
+ * column definition through a filter.
+ */
+export function matchChoices(
+  choices: readonly string[],
+  query: string
+): string[] {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return [...choices];
+  return choices.filter((choice) => choice.toLowerCase().includes(needle));
+}
+
+// ---------------------------------------------------------------------------
+// ⭐⭐ W40-T24 — THE PRE-SET COLUMN'S DEFINITION LOCK, STATED ONCE
+// ---------------------------------------------------------------------------
+
+/** The four definition verbs the Edit-field pane and the column menu can offer. */
+export interface ColumnDefinitionOffer {
+  /** "Change field" — point this column slot at a different field, or at a new one. */
+  swap: boolean;
+  /** The editable Name box in the Edit-field pane. */
+  rename: boolean;
+  /** The Field-type picker in the Edit-field pane. */
+  retype: boolean;
+  /** The "Delete field" row. Spelt `remove` only because `delete` reads as the operator. */
+  remove: boolean;
+}
+
+/**
+ * ⭐⭐ W40-T24 (owner instruction 18, contract C2) — **WHICH DEFINITION CONTROLS DOES THIS
+ * COLUMN OFFER?** One function, one answer, so the four verbs cannot drift apart.
+ *
+ * Owner, verbatim: *"the Supplier field is wrong. Editable at record level, yes, but 'Edit
+ * field' offers a 'Choose field' dropdown that makes no sense. Audit every pre-set field so the
+ * structure is standard: a pre-set field's definition is not editable and shows no 'choose a
+ * field' dropdown."* The complaint arrived about Supplier and was never about Supplier: the swap
+ * picker was gated on `!locked` alone, and `locked` means "is the pinned primary column". Zero
+ * pre-set awareness, so EVERY contract column on every grid carried the same exposure, and a fix
+ * written for Supplier would have been the wrong shape of fix.
+ *
+ * ⛔⛔ **THE LOCK IS `isUserSchemaField`, AND `isPresetField` CANNOT DO THIS JOB — MEASURED, NOT
+ * ASSUMED.** The obvious reach is for the predicate that carries the word, and it is wrong here.
+ * `platform/aios_grid_fields.json` declares NINE product_data contract columns —
+ * `supplier`, `origin_country`, `lead_days`, `first_cost`, `needs_pricing`, `march_pricelist`,
+ * `price_changes`, `closeouts`, `notes` — as `{"source": "overlay", "shared": true}` with no
+ * `custom` and no `preset` key. That is deliberate and it is what makes their CELLS typeable
+ * (`mayEditField` requires `source === "overlay"`), which is the owner's *"editable at record
+ * level, yes"*. Run `isPresetField` over any of them and it answers **false**: it recognises the
+ * Odoo-sourced stratum and the machine-owned one, and the overlay-stratum contract columns are
+ * neither. Gate the swap picker on it and Supplier — the column the instruction names — keeps
+ * the dropdown. ⚠ So the two predicates are NOT complements and the choice is not a matter of
+ * taste: one of them is false for the subject of the ticket.
+ *
+ *   · `isUserSchemaField` — *is this column's shape THIS user's to change?* False for all nine
+ *     of those, false for the Odoo-sourced columns (Category, Agent), false for a machine-owned
+ *     automation column, and TRUE for a `custom_` overlay column the user made and for every
+ *     `ut_*` shared-definition column. That is the pre-set line drawn exactly where C2 draws it.
+ *   · `isPresetField` — *is this column filled FOR you?* Still the right predicate for the
+ *     PRE-SET CHIP and the custom-field dot, which is what it was written for. It answers a
+ *     question about where the VALUES come from; this lock is about who owns the DEFINITION, and
+ *     the nine columns above are the proof that those are different sets.
+ *
+ * ⛔ **THE SWAP TAKES THE SAME PREDICATE AS RETYPE, WHICH IS THE POINT.** `CustomerGrid.
+ * changeField` only rewrites `config.order`/`config.visible`, so the swap is mechanically a view
+ * edit — but it sits INSIDE the Edit-field pane, and a pane whose Name box is disabled and whose
+ * type picker is absent while a third control offers to make this column something else is
+ * incoherent whatever the plumbing does. One predicate for all of the pane's definition verbs is
+ * what makes the pane say one thing.
+ *
+ * ⛔ **`rename` AND `retype` ARE REPORTED HERE, ENFORCED AT THE HOST — DELIBERATELY.** The host
+ * withholds the `onRename`/`onRetype` PROPS (`CustomerGrid.tsx`, the `onRetype=` and `onRename=`
+ * prop chains at the `<ColumnMenu>` render), and a control whose handler is undefined is not
+ * rendered at all. Enforcing the same refusal a second time inside the menu could only SUBTRACT
+ * from columns that work today — the Destination column's rename (owner item 3/6, 2026-08-23)
+ * reaches the pane through the route branch, not through the stratum — and two enforcement
+ * points that agree today are how one silently becomes the other's contradiction. So these two
+ * fields mirror the host's real rule, route carve-out included, and exist so a node gate can
+ * assert what the JSX does. If the host chain changes, this changes with it.
+ *
+ * ⛔ **`remove` IS THE LOCK'S VERDICT ONLY.** Whether a delete DOOR exists at all is a separate
+ * question the host answers three different ways (per-user overlay, `ut_*` shared definition,
+ * route order), and `ColumnMenu` keeps `onDelete &&` plus its `schemaLocked` prop beside this.
+ * AND-ing can only subtract, so nothing here duplicates `CustomerGrid.isSchemaLocked` — which is
+ * not exported, and copying it out would be D-413's disease in a fresh location.
+ * ⚠ THE ROLLUP CLAUSE IS AN OWNER RULING, NOT A HACK (2026-08-09): *"No rollup field should be
+ * uneditable, everything is custom and changeable always."* A rollup holds no data of its own —
+ * it is a question asked of other rows, and re-asking it costs nothing — so deleting a pre-set
+ * one destroys no measurement. `isSchemaLocked` carries the SAME exception in the same words
+ * (`&& field.type !== "rollup"`); dropping it here would revoke a live ruling by accident.
+ *
+ * @param opts.isUserTable the grid is a `ut_*` runtime database, not an Odoo-backed topic.
+ * @param opts.isPrimary this is the pinned primary column (the menu's `locked` prop) — the row
+ *   identity, which can never be swapped away whatever else is true of it.
+ */
+export function columnDefinitionOffer(
+  field: Field,
+  opts: { isUserTable: boolean; isPrimary: boolean }
+): ColumnDefinitionOffer {
+  const ownShape = isUserSchemaField(field, opts.isUserTable);
+  // The route order column's own rename and delete doors. Matched on the DECLARED `kind`, never
+  // on the `route_` key prefix — the server declares the kind precisely so nobody has to read a
+  // key as a type, and the host's own chain matches it the same way.
+  const routeOrder = field.shared === true && field.kind === "route_order" && !opts.isPrimary;
+  return {
+    swap: !opts.isPrimary && ownShape,
+    rename: ownShape || routeOrder,
+    retype: ownShape,
+    remove: ownShape || routeOrder || field.type === "rollup",
+  };
+}

web/src/customer-grid/export.ts

@@ -27,7 +27,7 @@
 // the installed build) — so a Blob URL + a[download] click works in the embed.
 // ---------------------------------------------------------------------------
 
-import type { Field, Row } from "./types";
+import type { Field, Row, VisibleRow } from "./types";
 import {
   formatDisplay,
   formulaIsBlank,
@@ -47,6 +47,108 @@ export const EXPORT_LABELS: Record<ExportFormat, string> = {
   json: "JSON",
 };
 
+// --------------------------------------------------------------- grouping
+//
+// ⭐ WAVE 40, OWNER INSTRUCTION 22 (W40-T26) — *"A grouped View exported to Excel
+// must show the grouping in the Excel file."* Until now the export ran its
+// pipeline with `groupBy` hardcoded to null, so a view grouped by City exported
+// as one undifferentiated block and the file said nothing the screen said.
+//
+// ⭐ AMENDMENT AM-3 (2026-08-23) IS THE CONTRACT: this ships VISIBLE grouping,
+// not COLLAPSIBLE grouping. A labelled band row carrying the group value and its
+// count precedes each block. Excel's +/- outline gutter needs `sheetFormatPr`,
+// `outlineLevel` and friends in a strict `CT_Worksheet` element order; that is
+// booked as a follow-up rather than built here, and NOTHING below invents a new
+// OOXML element — the bands are ordinary text rows through the existing
+// `rowXml()`/`cell()` helpers, which is why the container's invariants hold.
+
+/** One VISIBLE group block: the bucket the pipeline formed, its band text and
+ *  the rows that belong to it, in the order the grid paints them. */
+export interface ExportGroup {
+  /** The bucket key exactly as `groupRows` formed it (the trimmed cell text; ""
+   *  for the blank bucket, "1"/"" for a checkbox, ONE member of a multi cell). */
+  key: string;
+  /** The grid's own group-bar label for that key — "(empty)", "Checked",
+   *  "Unchecked" or the cell text. Used verbatim when the key has no display
+   *  rendering of its own, so the file never shows a nameless band. */
+  label: string;
+  /** The bucket's size, from the pipeline. Equal to `rows.length` here: the
+   *  export always runs with an EMPTY collapsed set, so no bucket is folded. */
+  count: number;
+  rows: Row[];
+}
+
+/** The grouped shape handed to a builder. `field` is the column the view is
+ *  grouped BY, so a band renders its value the same way that value renders in
+ *  its own column (see `bandText`); absent if the field has gone missing. */
+export interface ExportGrouping {
+  field?: Field;
+  blocks: ExportGroup[];
+}
+
+/**
+ * ⭐ WHICH FORMATS CARRY GROUPING, and it is a DECISION rather than an accident.
+ *
+ * EXCEL ONLY. The owner's words are "exported to Excel" and the ticket's
+ * `done-when` names the xlsx; the other three are left exactly as they are, in
+ * both the grouped and ungrouped case:
+ *
+ *   · JSON is a RAW-VALUE contract — `{ fields, rows }` where every row is a
+ *     record carrying its stable pid. A band has no pid, and grouping a MULTI
+ *     field lists one record under EVERY member of its cell, so feeding the
+ *     bucketed walk into this builder would put duplicate pids into a
+ *     machine-readable file. That is a data defect, not a feature.
+ *   · PDF is a paginated table: a band row is a layout change (band fill, page
+ *     breaks, the repeated header) of exactly the kind AM-3 defers.
+ *   · CSV has no band vocabulary and its rows would silently REORDER.
+ *
+ * ⛔ It selects which BUILDER receives the grouped structure. It must never
+ * decide which ROWS were matched: `exportRows` runs its record pipeline
+ * identically for all four formats, so the same view exported twice always
+ * carries the same records.
+ */
+export function groupingApplies(format: ExportFormat): boolean {
+  return format === "xlsx";
+}
+
+/**
+ * ⛔⛔ THE SENTINEL WALK — the half of instruction 22 that is invisible from the
+ * outside, and the reason unhardcoding a `groupBy` on its own changes NOTHING.
+ *
+ * A grouped pipeline result is not a tree. It is a FLAT `VisibleRow[]`
+ * interleaving `data` rows with `group-header` / `group-footer` sentinels, and
+ * every caller in the grid narrows it with a `kind === "data"` filter that
+ * throws all of them away. The export did the same. So: a header OPENS a block,
+ * a footer CLOSES it, and a data row joins whichever block is open.
+ *
+ * ⚠ A data row arriving with NO open block is skipped rather than inventing an
+ * unnamed bucket for it. `groupRows` always emits a header first, so this is a
+ * defensive branch and not a case in the product — but a nameless band is worse
+ * than a missing one, because it looks deliberate.
+ *
+ * ⚠ A footer only ever ENDS a block, so the table-wide total footer the grid
+ * appends under `TOTAL_GROUP_KEY` cannot open a phantom group here.
+ *
+ * Lives in `export.ts` rather than inline at the call site so a node gate can
+ * reach it: this walk is exactly the kind of thing that is wrong in a way no
+ * screenshot shows.
+ */
+export function toExportGroups(bucketed: VisibleRow[]): ExportGroup[] {
+  const blocks: ExportGroup[] = [];
+  let block: ExportGroup | null = null;
+  for (const vr of bucketed) {
+    if (vr.kind === "group-header") {
+      block = { key: vr.groupKey, label: vr.label, count: vr.count, rows: [] };
+      blocks.push(block);
+    } else if (vr.kind === "group-footer") {
+      block = null;
+    } else if (block) {
+      block.rows.push(vr.record);
+    }
+  }
+  return blocks;
+}
+
 // ------------------------------------------------------------------ filename
 
 /** `<view or cohort name> - <today>.<ext>` — `today` is the PAYLOAD's string
@@ -319,12 +421,18 @@ function buildStyles(codes: string[]): string {
 /** A minimal SpreadsheetML workbook: one sheet, NUMERIC kinds written as real
  *  numbers with a number format that reproduces the grid's rendering, everything
  *  else an inline string carrying the DISPLAY value (contract C2 — what the grid
- *  shows is what the file says). */
+ *  shows is what the file says).
+ *
+ *  ⭐ W40-T26. `grouping` is OPTIONAL and absent means UNGROUPED: the body is
+ *  then built from `rows` by the same expression as before, so an ungrouped
+ *  export is byte-identical to the pre-grouping writer. Present, it replaces the
+ *  flat body with band-then-block, and `rows` is not read. */
 export function buildXlsx(
   fields: Field[],
   rows: Row[],
   name: string,
-  today: string | undefined
+  today: string | undefined,
+  grouping?: ExportGrouping
 ): Uint8Array {
   const enc = new TextEncoder();
   const styles = styleTable();
@@ -378,11 +486,45 @@ export function buildXlsx(
   }
 
   const rowXml = (cells: string[]) => `<row>${cells.join("")}</row>`;
-  const body = [
-    // The header row is LABELS — text, and it stays text.
-    rowXml(fields.map((f) => cell(f.label))),
-    ...rows.map((r) => rowXml(fields.map((f) => dataCell(f, r[f.key])))),
-  ].join("");
+  const dataRow = (r: Row) => rowXml(fields.map((f) => dataCell(f, r[f.key])));
+
+  /**
+   * ⭐ W40-T26 / AM-3 — THE BAND'S TEXT: the group's VALUE and its COUNT, and
+   * nothing else. Not a sentence about grouping (DESIGN.md §4), not the canvas's
+   * ▼/▶ marker (there is nothing to collapse in a file), no dash of any kind.
+   *
+   * ⭐ THE VALUE GOES THROUGH `formatDisplay`, THE SAME FUNCTION EVERY OTHER
+   * EXPORTED VALUE GOES THROUGH. A date bucket's key is the raw "2026-07-28" and
+   * that column's own cells arrive in Excel as serials rendered "Jul 28, 2026";
+   * printing the key verbatim would make one file say the same value two ways.
+   *
+   * ⛔ AND IT FALLS BACK, because `formatDisplay` returns "" for exactly the
+   * buckets that most need a name: the blank bucket ("" -> "(empty)") and an
+   * unchecked checkbox ("" -> "Unchecked"). The pipeline's own label is the
+   * grid's group-bar wording, so the fallback is the screen's answer rather than
+   * a second one invented here.
+   */
+  const bandText = (g: ExportGroup): string => {
+    const shown = grouping?.field ? formatDisplay(grouping.field, g.key) : "";
+    return `${shown || g.label} (${g.count.toLocaleString()})`;
+  };
+
+  // The header row is LABELS — text, and it stays text.
+  const bodyRows = [rowXml(fields.map((f) => cell(f.label)))];
+  if (grouping) {
+    // A band is ONE text cell. Cells carry no `r` attribute in this writer, so
+    // position is order and a one-cell row lands in column A — the same
+    // mechanism every other row here already relies on. No merge, no span:
+    // `mergeCells` is a new CT_Worksheet element and AM-3 defers that class of
+    // change.
+    for (const g of grouping.blocks) {
+      bodyRows.push(rowXml([cell(bandText(g))]));
+      for (const r of g.rows) bodyRows.push(dataRow(r));
+    }
+  } else {
+    for (const r of rows) bodyRows.push(dataRow(r));
+  }
+  const body = bodyRows.join("");
   const sheet =
     `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
     `<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">` +
@@ -590,13 +732,20 @@ export function triggerDownload(filename: string, blob: Blob): void {
   window.setTimeout(() => URL.revokeObjectURL(url), 4000);
 }
 
-/** One door for all four formats: build, wrap, download. */
+/** One door for all four formats: build, wrap, download.
+ *
+ *  ⭐ W40-T26. `grouping` reaches the xlsx builder and nothing else — see
+ *  `groupingApplies` for why, and note that the CALLER has already decided: it
+ *  passes `undefined` for every format that does not carry bands, so the three
+ *  other builders are called with exactly the arguments they were called with
+ *  before this ticket existed. */
 export function runExport(
   format: ExportFormat,
   name: string,
   today: string | undefined,
   fields: Field[],
-  rows: Row[]
+  rows: Row[],
+  grouping?: ExportGrouping
 ): void {
   const filename = exportFilename(name, today, format);
   if (format === "csv") {
@@ -617,7 +766,7 @@ export function runExport(
   if (format === "xlsx") {
     triggerDownload(
       filename,
-      new Blob([buildXlsx(fields, rows, name, today).buffer as ArrayBuffer], {
+      new Blob([buildXlsx(fields, rows, name, today, grouping).buffer as ArrayBuffer], {
         type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
       })
     );

web/src/customer-grid/folders.ts

@@ -1,492 +1,572 @@
-// ---------------------------------------------------------------------------
-// customer-grid / folders.ts
-// Wave-8 I11c (contract C4) — the folder MODEL for the Views and Cohorts rails,
-// pure and React-free so verify_folders.py can run it under node.
-//
-// One level, deliberately. Nesting brings cycle-checking, move-into-your-own-
-// descendant, and recursive delete semantics with it; the owner asked for
-// folders you can drag things into, and a flat model is the whole of that.
-//
-// THE PART THAT IS EASY TO GET WRONG — the echo. Folder operations ride the
-// same once-by-id event log as everything else, so between the emit and the
-// host's echo there is a window where the payload still describes the world as
-// it was BEFORE the click. Render that naively and a just-deleted folder
-// reappears for one round trip (the "delete blip"), a rename flickers back to
-// the old name, and a dragged view jumps home. So this module reconciles the
-// host's copy against this browser's own recent stamps, exactly as
-// optimism.ts::reconcileFields does for fields — same ECHO_RECENT_MS window,
-// same rule that a STALE stamp yields to the host (divergence is not an echo).
-// ---------------------------------------------------------------------------
-
-import { ECHO_RECENT_MS } from "./viewEcho";
-import type { GridFolder } from "./types";
-
-/** What this browser did recently, by folder id / item id. Values are epoch ms
- *  from THIS machine's clock — both sides of every comparison are local, so
- *  this is not the tenant-day rule (that one is about two ENGINES agreeing). */
-export interface FolderStamps {
-  created?: Record<string, number>;
-  renamed?: Record<string, { at: number; name: string }>;
-  deleted?: Record<string, number>;
-  /** itemId -> {at, folderId} for a drag this browser just performed. */
-  moved?: Record<string, { at: number; folderId: string | null }>;
-  /**
-   * WAVE 20 item 19 (C-FOLDER-REORDER) — the FULL folder order this browser just set.
-   *
-   * ONE stamp, not one per folder, because a reorder is one decision about a list: the
-   * order the user dropped into is the order they want, and reconstructing it from N
-   * per-folder stamps would let two of them age out at different moments and leave a
-   * sequence nobody ever chose. The host answers with `order` NUMBERS on each folder
-   * (that is the durable form); this is what to render until it does.
-   */
-  ordered?: { at: number; order: string[] };
-  /**
-   * ⭐ WAVE 27 · OWNER ITEM 5 (contract C7) — the FULL VIEW order this browser just set.
-   *
-   * A separate stamp from `ordered` above, deliberately, even though both are "a list this
-   * browser dragged into shape": they age independently and they are different decisions. One
-   * stamp holding both would make reordering a folder revive a view order the user had already
-   * let go of, and vice versa — the exact "a sequence nobody ever chose" failure `ordered`'s own
-   * note refuses one level down.
-   */
-  orderedViews?: { at: number; order: string[] };
-}
-
-export const FOLDER_STAMP_MAX = 64;
-
-const isRecent = (t: number | undefined, now: number): boolean =>
-  typeof t === "number" && now - t <= ECHO_RECENT_MS;
-
-/** Drop stamps past the echo window so the map cannot grow without bound and a
- *  long-lived tab cannot keep asserting an edit nobody remembers. */
-export function pruneFolderStamps(stamps: FolderStamps | undefined, now: number): FolderStamps {
-  const out: FolderStamps = {};
-  const keepNum = (rec: Record<string, number> | undefined) => {
-    if (!rec) return undefined;
-    const kept = Object.entries(rec).filter(([, t]) => isRecent(t, now));
-    return kept.length ? Object.fromEntries(kept.slice(-FOLDER_STAMP_MAX)) : undefined;
-  };
-  const keepObj = <T extends { at: number }>(rec: Record<string, T> | undefined) => {
-    if (!rec) return undefined;
-    const kept = Object.entries(rec).filter(([, v]) => isRecent(v.at, now));
-    return kept.length ? Object.fromEntries(kept.slice(-FOLDER_STAMP_MAX)) : undefined;
-  };
-  const created = keepNum(stamps?.created);
-  const renamed = keepObj(stamps?.renamed);
-  const deleted = keepNum(stamps?.deleted);
-  const moved = keepObj(stamps?.moved);
-  if (created) out.created = created;
-  if (renamed) out.renamed = renamed;
-  if (deleted) out.deleted = deleted;
-  if (moved) out.moved = moved;
-  // Item 19: a single stamp, so it is kept or dropped whole — pruning it by halves is
-  // exactly the partial sequence the field's own note refuses.
-  if (isRecent(stamps?.ordered?.at, now) && stamps?.ordered) out.ordered = stamps.ordered;
-  // Item 5 (C7): the same rule for the VIEW order, kept or dropped whole for the same reason.
-  if (isRecent(stamps?.orderedViews?.at, now) && stamps?.orderedViews)
-    out.orderedViews = stamps.orderedViews;
-  return out;
-}
-
-/**
- * ⭐ WAVE 27 · OWNER ITEM 5 (contract C7) — the rail's view order, as this browser last set it.
- *
- * ⛔ WHY IT IS NEEDED AT ALL: the server assembles view order (`aios_grid.py:1602-1647`) and the
- * echo is one round trip behind the drop. Without this the row springs back to its old place the
- * instant the workspace refreshes, which reads as "the drag did not work" — the NO-BLIP law's
- * subject, applied to a sequence instead of to a value.
- *
- * ⚠ PAST THE ECHO WINDOW THE SERVER WINS, unconditionally. That asymmetry is the whole design of
- * this module: inside the window a local drag is newer truth; outside it, a difference between
- * the copies is divergence between SESSIONS, and the durable store decides.
- *
- * ⛔ IDS THE STAMP DOES NOT NAME KEEP THEIR SERVER ORDER, appended after the named ones — the
- * same rule the host applies to a `folder_reorder` payload. A view created in another tab since
- * the drop is not evidence that the drop was wrong; dropping it would be this function deleting
- * a view from the rail to defend a sequence.
- */
-export function applyViewOrder<T extends { id: string }>(
-  views: T[],
-  stamps: FolderStamps | undefined,
-  now: number
-): T[] {
-  const stamp = stamps?.orderedViews;
-  if (!stamp || !isRecent(stamp.at, now) || !Array.isArray(stamp.order)) return views;
-  const byId = new Map(views.map((v) => [v.id, v]));
-  const out: T[] = [];
-  const placed = new Set<string>();
-  for (const id of stamp.order) {
-    const v = byId.get(id);
-    if (!v || placed.has(id)) continue;
-    placed.add(id);
-    out.push(v);
-  }
-  for (const v of views) if (!placed.has(v.id)) out.push(v);
-  return out;
-}
-
-/**
- * The host's folder list, corrected by what this browser just did.
- *
- *   deleted recently  -> DROP it, even though the echo still lists it
- *                        (the tombstone rule; without this a deleted folder
- *                        blinks back for one round trip)
- *   renamed recently  -> keep OUR name until the echo carries it
- *   created recently  -> keep OURS if the echo has not caught up yet
- *
- * Everything stale yields to the host: past the window, a difference between
- * the copies is divergence between sessions, and host state is the durable
- * truth. That asymmetry is the whole design.
- */
-export function reconcileFolders(
-  hostFolders: GridFolder[] | undefined,
-  localFolders: GridFolder[] | undefined,
-  stamps: FolderStamps | undefined,
-  now: number
-): GridFolder[] {
-  const host = hostFolders ?? [];
-  const out: GridFolder[] = [];
-  const seen = new Set<string>();
-
-  for (const f of host) {
-    if (isRecent(stamps?.deleted?.[f.id], now)) continue; // tombstone
-    seen.add(f.id);
-    const rename = stamps?.renamed?.[f.id];
-    out.push(isRecent(rename?.at, now) && rename ? { ...f, name: rename.name } : f);
-  }
-
-  // A folder this browser created that the echo has not yet returned. Skipped
-  // when it was also deleted since — creating and deleting inside one window
-  // must net to nothing, not to a ghost.
-  for (const f of localFolders ?? []) {
-    if (seen.has(f.id)) continue;
-    if (!isRecent(stamps?.created?.[f.id], now)) continue;
-    if (isRecent(stamps?.deleted?.[f.id], now)) continue;
-    out.push(f);
-  }
-
-  out.sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || a.name.localeCompare(b.name));
-
-  // ── WAVE 20 item 19 (C-FOLDER-REORDER): this browser's drag, until the echo carries it.
-  //
-  // Applied AFTER the host sort and as a SEPARATE pass, both deliberately:
-  //   · the host's `order` numbers are the durable truth and stay the base sequence, so a
-  //     folder the stamp never names keeps exactly the place the server gave it;
-  //   · `Array.prototype.sort` is stable (ES2019), so every unnamed folder — one created in
-  //     another tab between the drag and the echo, say — holds its relative position at the
-  //     end instead of being flung to the front by a missing rank.
-  // A stamped id that has since been DELETED needs no handling: the tombstone pass above
-  // already dropped it, and `rank` is only ever consulted for folders that survived.
-  const ordered = stamps?.ordered;
-  if (isRecent(ordered?.at, now) && ordered) {
-    const rank = new Map(ordered.order.map((id, i) => [id, i]));
-    out.sort(
-      (a, b) =>
-        (rank.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
-        (rank.get(b.id) ?? Number.MAX_SAFE_INTEGER)
-    );
-  }
-  return out;
-}
-
-/**
- * Where an item actually belongs right now: this browser's recent drag wins
- * over the host's echo, and a folder that no longer exists resolves to ROOT.
- *
- * The second half matters as much as the first. `folder_delete` moves contents
- * to root host-side, but the client sees the folder vanish one render before
- * the items' `folderId` is rewritten — and an item pointing at a folder nobody
- * renders would simply not appear in any group. Resolving a dangling ref to
- * root is what stops a folder delete from making views look deleted too.
- */
-export function resolveFolderId(
-  itemId: string,
-  hostFolderId: string | null | undefined,
-  folders: GridFolder[],
-  stamps: FolderStamps | undefined,
-  now: number
-): string | null {
-  const moved = stamps?.moved?.[itemId];
-  const id = isRecent(moved?.at, now) && moved ? moved.folderId : (hostFolderId ?? null);
-  if (id == null) return null;
-  // ⚠ W32-T27 — the RESERVED root placement is not a dangling reference. It names no folder by
-  // design, so the `folders.some(...)` test below would null it and hand the item straight back
-  // to the Shared bucket, re-creating item 20 one layer down from where it was fixed.
-  if (id === ROOT_FOLDER_ID) return ROOT_FOLDER_ID;
-  return folders.some((f) => f.id === id) ? id : null;
-}
-
-export interface FolderGroup<T> {
-  folder: GridFolder | null; // null = the root group
-  items: T[];
-}
-
-/**
- * WAVE 20 item 18 / WAVE 21 item 9 (ruling R12, contract C1) — the SYNTHETIC folder
- * that every view shared WITH you appears under.
- *
- * ⛔ IT IS NOT A STORED FOLDER, and nothing may ever write one with this id. It has no
- * record in `folders`, no `order`, no icon, and the rail refuses every action on it
- * (`ViewSidebar` suppresses the row menu for exactly this id): it cannot be renamed into
- * something else, duplicated into a second copy of other people's work, or deleted. It is a
- * READING of the view list — "these arrived by grant" — rendered as a group because that is
- * the only shape this rail has for "a set of views with something in common".
- *
- * Declared HERE rather than in the component (where it lived through wave 20) so the
- * synthesis below is pure, and `verify_folders.py` can run it under node like every other
- * rule in this file. A constant a gate cannot reach is a contract nobody checks.
- */
-export const SHARED_FOLDER_ID = "__shared__";
-export const SHARED_FOLDER_NAME = "Shared with me";
-
-/**
- * ⭐⭐ WAVE 34 · T25 (ruling R11) — A SHARED **FOLDER** GETS ITS OWN GROUP, under this prefix.
- *
- * R11: *"A folder (with the Views inside it) can be shared with a team member."* Everything below
- * the client already worked and was VERIFIED before this was written: `core/shares.py::KINDS` has
- * carried `'folder'` since wave 20, the rail already offers "Share folder", and
- * `grid_events.py::_granted_views` has projected each granted folder's views since `D-37`. What
- * did not work is the last inch: every shared view landed in ONE flat "Shared with me" group, so
- * the receiver got loose views and **the folder itself was invisible**.
- *
- * ⭐ The name has been on the wire the whole time. `_granted_views` stamps
- * `v['sharedFolder'] = <folder name>` with the comment *"so the client can group these together
- * later"*, and a census found ZERO readers of it anywhere in `web/src` — a flag shipped without
- * its reader. This is the reader.
- *
- * ⚠ A PREFIX RATHER THAN ONE RESERVED ID, because there can be several: two colleagues can each
- * share a folder with you. {@link isSyntheticFolderId} is what every affordance must ask instead
- * of comparing against `SHARED_FOLDER_ID` — a rail that suppressed actions on one synthetic group
- * and offered them on another would emit `item_move`/`folder_rename` against a folder id that
- * exists in nobody's store.
- *
- * ⛔⛔ THE KEY IS **OWNER + NAME**, NOT NAME, AND THE FIRST DRAFT OF THIS FUNCTION GOT IT WRONG.
- * It keyed on the folder name alone while the comment right here claimed to handle two colleagues
- * sharing folders with the SAME NAME — so those two folders merged into ONE group, and the head's
- * `title` (which reads the first item's `owner`) misattributed every view from the second sharer.
- * Per-view `sharedRole` was never affected, so nothing leaked; what broke was the rail telling you
- * whose work you were reading, which is the entire point of the group. **A comment that describes
- * the case the code does not handle is worse than no comment**, because it is what a reviewer
- * checks against. Found by this ticket's own verifier reading the two side by side.
- *
- * ⛔ NOTHING MAY EVER WRITE ONE. Like `SHARED_FOLDER_ID` these ids are a READING of the view list,
- * not a record: no `order`, no icon, no row in `folders`.
- */
-export const SHARED_FOLDER_PREFIX = "__sharedfld__:";
-
-/**
- * The synthetic group id for a folder somebody shared with you.
- *
- * ⚠ `owner` FIRST and separated by a character usernames cannot contain. `core/users.py` keeps
- * usernames lower-case and non-empty; a folder NAME is free text and can contain anything a user
- * types, `:` included. Putting the free-text half last means no pair of (owner, name) can spell
- * another pair's id, whatever somebody calls a folder.
- */
-export function sharedFolderGroupId(owner: string, name: string): string {
-  return `${SHARED_FOLDER_PREFIX}${owner}:${name}`;
-}
-
-/**
- * Is this group id SYNTHESISED rather than stored? True for "Shared with me" and for every
- * shared-folder group. Every drag, drop, rename and delete affordance in the rail asks this.
- */
-export function isSyntheticFolderId(id: string | null | undefined): boolean {
-  return id === SHARED_FOLDER_ID
-    || (typeof id === "string" && id.startsWith(SHARED_FOLDER_PREFIX));
-}
-
-/**
- * ⭐⭐ WAVE 32 · T27 (owner item 20) — **"FILED AT ROOT", AS A VALUE.**
- *
- * Owner: *a shared View cannot be moved out of the Shared folder.* The cause is that **root was
- * represented by ABSENCE at every layer**, and absence cannot distinguish two different facts:
- *
- *   · `folderId == null` because the receiver never filed this view — it should show under
- *     "Shared with me", which is where a grant LANDS;
- *   · `folderId == null` because the receiver deliberately dragged it OUT of that group.
- *
- * `groupByFolder` had to guess, and it guessed "shared" — so filing a shared view at root put it
- * straight back where it came from. **The root bucket was unreachable for a shared view by
- * construction**, which is exactly why only folder→folder moves ever appeared to work.
- *
- * ⛔ THE SENTINEL IS STORED, NOT DERIVED, AND THAT IS THE WHOLE FIX. Both other layers wrote the
- * same absence and must both learn this value: `core/grid_events.py`'s `item_move` branch
- * (`if target is None: cur.pop(item_id, None)  # back to the root`) and
- * `aios_grid.clean_item_folders`, whose own docstring states the defect one level deeper —
- * *"nothing stores 'this item is in no folder'"*. A client-only fix is impossible; there is
- * nothing to read back.
- *
- * ⚠ It is a RESERVED id in the same namespace as real folder ids, so `resolveFolderId` must pass
- * it through rather than treating it as dangling, and `clean_item_folders` must admit it beside
- * `fid in fids`. It is deliberately NOT rendered as a group: {@link groupByFolder} maps it onto
- * the ordinary root bucket, so nothing in the rail ever shows the word.
- */
-export const ROOT_FOLDER_ID = "__root__";
-
-/**
- * Group items into folders + a root bucket, in folder order, root LAST.
- *
- * Root last because the rails are read top-down and folders are the structure
- * the user made; ungrouped items are the leftovers. Every item appears exactly
- * once — a grouping that can drop an item would make a view look deleted.
- *
- * ⭐ WAVE 21 item 9 (R12/C1) — `isShared` adds the synthetic "Shared with me" group,
- * AFTER root, and three things about it are deliberate:
- *
- *   · **After root, not before it.** C1 says LAST in as many words. It reads correctly
- *     too: the rail is "my folders, my loose views, and then other people's".
- *   · **A shared view the receiver has FILED still goes to their folder.** The `__shared__`
- *     group is where a grant LANDS, not a cage it stays in — the rail's own note calls
- *     moving out "per-receiver placement" and that must keep working. So the synthetic
- *     group collects only the shared views that resolved to ROOT.
- *   · **An empty group does not render.** A folder head with nothing under it says "here is
- *     something you cannot reach" — the same reason `foldNav` drops empty nav folders.
- *
- * Omitting `isShared` leaves the function byte-identical to the pre-wave-21 one, which is
- * what every existing caller (the cohort rail, the tests) still gets.
- */
-export function groupByFolder<T>(
-  items: T[],
-  folders: GridFolder[],
-  folderIdOf: (item: T) => string | null,
-  isShared?: (item: T) => boolean,
-  /**
-   * ⭐ WAVE 34 · T25 (R11) — the folder a shared item arrived through, if it did.
-   *
-   * Returns the folder's NAME and its OWNER, because the pair is the identity: the wire carries
-   * no folder id for a grant (`_granted_views` stamps a name and an owner, never an id), and the
-   * name alone is not unique across sharers.
-   *
-   * Optional, so every existing caller (the cohort rail, the tests) keeps the pre-T25 shape
-   * byte-for-byte: with it omitted, every shared item falls into the flat "Shared with me"
-   * group exactly as before. Supplied, the shared views SPLIT by the folder that carried them,
-   * and the folder finally appears on the receiver's screen.
-   */
-  sharedFolderOf?: (item: T) => { name: string; owner: string } | null
-): FolderGroup<T>[] {
-  const buckets = new Map<string, T[]>(folders.map((f) => [f.id, []]));
-  const root: T[] = [];
-  const shared: T[] = [];
-  /** synthetic group id -> {name, views}. Keyed by OWNER+NAME; see `SHARED_FOLDER_PREFIX`. */
-  const sharedFolders = new Map<string, { name: string; items: T[] }>();
-  for (const item of items) {
-    const id = folderIdOf(item);
-    const bucket = id == null ? undefined : buckets.get(id);
-    if (bucket) bucket.push(item);
-    // ⭐⭐ W32-T27 (owner item 20) — THE ROOT BUCKET IS REACHABLE FOR A SHARED VIEW NOW.
-    // `ROOT_FOLDER_ID` is the receiver saying "I filed this at the top level"; absence still
-    // means "this arrived by grant and I have not filed it". Before this line the two were one
-    // value, `isShared` won, and a shared view dragged to root returned to "Shared with me" on
-    // the next render — the owner's item 20, in one branch.
-    else if (id === ROOT_FOLDER_ID) root.push(item);
-    else if (isShared?.(item)) {
-      // ⭐ W34-T25 (R11): a shared view that arrived through a FOLDER goes to that folder's own
-      // group; one that was granted directly still goes to the flat "Shared with me". The two
-      // are different facts and the receiver can see which is which.
-      const via = sharedFolderOf?.(item);
-      const name = via ? String(via.name || "").trim() : "";
-      const owner = via ? String(via.owner || "").trim() : "";
-      // ⚠ BOTH halves required. A folder name with no owner cannot be told apart from another
-      // sharer's folder of the same name, so it falls back to the flat group rather than
-      // inventing a group that might merge two people's work under one person's label.
-      if (name && owner) {
-        const key = sharedFolderGroupId(owner, name);
-        const bucket2 = sharedFolders.get(key);
-        if (bucket2) bucket2.items.push(item);
-        else sharedFolders.set(key, { name, items: [item] });
-      } else shared.push(item);
-    }
-    else root.push(item);
-  }
-  const out: FolderGroup<T>[] = folders.map((f) => ({ folder: f, items: buckets.get(f.id) ?? [] }));
-  out.push({ folder: null, items: root });
-  if (shared.length)
-    out.push({ folder: { id: SHARED_FOLDER_ID, name: SHARED_FOLDER_NAME }, items: shared });
-  // ⚠ SORTED, not first-seen. A Map preserves insertion order, which here is the order the VIEWS
-  // happen to arrive in — so one view moving could reorder whole folders in the rail for no reason
-  // a reader could name. Sorting on the composite ID (owner first) is stable across every payload
-  // AND groups one colleague's folders together, which reads better than interleaving two people's
-  // folders alphabetically by name.
-  for (const key of [...sharedFolders.keys()].sort((a, b) => a.localeCompare(b))) {
-    const grp = sharedFolders.get(key)!;
-    out.push({ folder: { id: key, name: grp.name }, items: grp.items });
-  }
-  return out;
-}
-
-/**
- * WAVE 20 item 19 (C-FOLDER-REORDER) — where a dragged folder lands: the full order with
- * `draggedId` moved to sit immediately BEFORE `beforeId`, or last when that is null (the
- * drop on the ungrouped section below every folder).
- *
- * Here rather than inside the rail because it is the only part of the drag a test can hold:
- * the drop handler is DOM, the emit is the caller's, and this is the arithmetic that decides
- * what the user sees. `null` means "emit nothing" — an unknown id, or a drop that changes
- * nothing. Returning the unchanged array instead would be worse than useless: the caller
- * cannot tell it apart from a real reorder, so every no-op drag would write the store, bump
- * every reader's payload, and reconcile to the identical list.
- *
- * ⚠ The dragged id is REMOVED BEFORE the target index is read. Taking the index first and
- * splicing after is the classic off-by-one here: dragging a folder DOWNWARD would land it one
- * place short of where it was dropped, and only in that direction — the shape of bug that
- * survives a demo and gets reported as "it sometimes doesn't move".
- */
-export function reorderFolderIds(
-  ids: string[],
-  draggedId: string,
-  beforeId: string | null
-): string[] | null {
-  if (!ids.includes(draggedId)) return null;
-  // ⛔ DROPPED ON ITSELF. Without this the id is filtered out, `indexOf` cannot find its own
-  // target, and the "not found" branch sends the folder to the END — so releasing a drag over
-  // the folder you picked up would quietly move it to the bottom of the rail. Found by this
-  // function's own gate the minute the arithmetic left the component; the drop handler's
-  // indicator suppresses the same case visually, which is exactly why it would never have
-  // been noticed there.
-  if (beforeId === draggedId) return null;
-  const rest = ids.filter((id) => id !== draggedId);
-  const found = beforeId ? rest.indexOf(beforeId) : -1;
-  const at = found < 0 ? rest.length : found;
-  const next = [...rest.slice(0, at), draggedId, ...rest.slice(at)];
-  if (next.length === ids.length && next.every((id, i) => id === ids[i])) return null;
-  return next;
-}
-
-/**
- * ⭐⭐ WAVE 34 · T22 (ruling R4, `D-249`) — MAY THIS VIEWER FILE THIS VIEW INTO A FOLDER?
- *
- * ⛔ NOT THE SAME QUESTION AS `mayEditView`, AND CONFLATING THEM IS THE DEFECT. The rail gated its
- * `draggable` on `mayEditView`, which fail-closes on a shared view whose role is not `edit` — so a
- * read-only shared view could not BEGIN a drag, and the owner's report is that a view cannot be
- * taken out of a folder. Filing is not a content edit: it writes a PLACEMENT into the receiver's
- * own workspace stratum and never touches the owner's object.
- *
- * ⭐ THE SERVER ALREADY AGREED, IN TWO PLACES, BEFORE THIS FUNCTION EXISTED. `grid_events.py::
- * table_workspace` merges granted views into `ws['views']`, which is the very set `item_move`'s
- * own-ids test reads — so the write this drag produces is ACCEPTED today. And the `view_reorder`
- * branch beside it carries the rule in prose: *"NO OWNERSHIP FILTER … refusing ids they do not own
- * would make exactly those un-draggable, which is the half of sharing people notice."* The client
- * was the only refuser, and it was refusing a write the server was ready to take.
- *
- * ⚠ `mayEdit` IS A PARAMETER, NOT AN IMPORT, and that is deliberate: this module is
- * "pure and React-free so verify_folders.py can run it under node" (see the header), and its only
- * imports today are one constant and one type. Taking the verdict rather than the resolver keeps
- * the truth table testable in isolation and keeps this file's dependency surface where its own
- * header promised it would stay.
- *
- * ⚠ USE IT ONLY AT THE DRAG SITE. Every other affordance the rail gates on `mayEditView` — rename,
- * description, delete, permissions — really is a content edit on somebody else's object, and the
- * server really does refuse those.
- */
-export function mayFileView(view: { shared?: boolean }, mayEdit: boolean): boolean {
-  return view.shared === true || mayEdit;
-}
-
-/** A fresh folder id. Client-generated, like every other id in this component. */
-export function newFolderId(): string {
-  const rand =
-    typeof crypto !== "undefined" && "randomUUID" in crypto
-      ? crypto.randomUUID().slice(0, 8)
-      : Math.random().toString(36).slice(2, 10);
-  return `fld_${rand}`;
-}
+// ---------------------------------------------------------------------------
+// customer-grid / folders.ts
+// Wave-8 I11c (contract C4) — the folder MODEL for the Views and Cohorts rails,
+// pure and React-free so verify_folders.py can run it under node.
+//
+// One level, deliberately. Nesting brings cycle-checking, move-into-your-own-
+// descendant, and recursive delete semantics with it; the owner asked for
+// folders you can drag things into, and a flat model is the whole of that.
+//
+// THE PART THAT IS EASY TO GET WRONG — the echo. Folder operations ride the
+// same once-by-id event log as everything else, so between the emit and the
+// host's echo there is a window where the payload still describes the world as
+// it was BEFORE the click. Render that naively and a just-deleted folder
+// reappears for one round trip (the "delete blip"), a rename flickers back to
+// the old name, and a dragged view jumps home. So this module reconciles the
+// host's copy against this browser's own recent stamps, exactly as
+// optimism.ts::reconcileFields does for fields — same ECHO_RECENT_MS window,
+// same rule that a STALE stamp yields to the host (divergence is not an echo).
+// ---------------------------------------------------------------------------
+
+import { ECHO_RECENT_MS } from "./viewEcho";
+import type { GridFolder } from "./types";
+
+/** What this browser did recently, by folder id / item id. Values are epoch ms
+ *  from THIS machine's clock — both sides of every comparison are local, so
+ *  this is not the tenant-day rule (that one is about two ENGINES agreeing). */
+export interface FolderStamps {
+  created?: Record<string, number>;
+  renamed?: Record<string, { at: number; name: string }>;
+  deleted?: Record<string, number>;
+  /** itemId -> {at, folderId} for a drag this browser just performed. */
+  moved?: Record<string, { at: number; folderId: string | null }>;
+  /**
+   * WAVE 20 item 19 (C-FOLDER-REORDER) — the FULL folder order this browser just set.
+   *
+   * ONE stamp, not one per folder, because a reorder is one decision about a list: the
+   * order the user dropped into is the order they want, and reconstructing it from N
+   * per-folder stamps would let two of them age out at different moments and leave a
+   * sequence nobody ever chose. The host answers with `order` NUMBERS on each folder
+   * (that is the durable form); this is what to render until it does.
+   */
+  ordered?: { at: number; order: string[] };
+  /**
+   * ⭐ WAVE 27 · OWNER ITEM 5 (contract C7) — the FULL VIEW order this browser just set.
+   *
+   * A separate stamp from `ordered` above, deliberately, even though both are "a list this
+   * browser dragged into shape": they age independently and they are different decisions. One
+   * stamp holding both would make reordering a folder revive a view order the user had already
+   * let go of, and vice versa — the exact "a sequence nobody ever chose" failure `ordered`'s own
+   * note refuses one level down.
+   */
+  orderedViews?: { at: number; order: string[] };
+}
+
+export const FOLDER_STAMP_MAX = 64;
+
+const isRecent = (t: number | undefined, now: number): boolean =>
+  typeof t === "number" && now - t <= ECHO_RECENT_MS;
+
+/** Drop stamps past the echo window so the map cannot grow without bound and a
+ *  long-lived tab cannot keep asserting an edit nobody remembers. */
+export function pruneFolderStamps(stamps: FolderStamps | undefined, now: number): FolderStamps {
+  const out: FolderStamps = {};
+  const keepNum = (rec: Record<string, number> | undefined) => {
+    if (!rec) return undefined;
+    const kept = Object.entries(rec).filter(([, t]) => isRecent(t, now));
+    return kept.length ? Object.fromEntries(kept.slice(-FOLDER_STAMP_MAX)) : undefined;
+  };
+  const keepObj = <T extends { at: number }>(rec: Record<string, T> | undefined) => {
+    if (!rec) return undefined;
+    const kept = Object.entries(rec).filter(([, v]) => isRecent(v.at, now));
+    return kept.length ? Object.fromEntries(kept.slice(-FOLDER_STAMP_MAX)) : undefined;
+  };
+  const created = keepNum(stamps?.created);
+  const renamed = keepObj(stamps?.renamed);
+  const deleted = keepNum(stamps?.deleted);
+  const moved = keepObj(stamps?.moved);
+  if (created) out.created = created;
+  if (renamed) out.renamed = renamed;
+  if (deleted) out.deleted = deleted;
+  if (moved) out.moved = moved;
+  // Item 19: a single stamp, so it is kept or dropped whole — pruning it by halves is
+  // exactly the partial sequence the field's own note refuses.
+  if (isRecent(stamps?.ordered?.at, now) && stamps?.ordered) out.ordered = stamps.ordered;
+  // Item 5 (C7): the same rule for the VIEW order, kept or dropped whole for the same reason.
+  if (isRecent(stamps?.orderedViews?.at, now) && stamps?.orderedViews)
+    out.orderedViews = stamps.orderedViews;
+  return out;
+}
+
+/**
+ * ⭐ WAVE 27 · OWNER ITEM 5 (contract C7) — the rail's view order, as this browser last set it.
+ *
+ * ⛔ WHY IT IS NEEDED AT ALL: the server assembles view order (`aios_grid.py:1602-1647`) and the
+ * echo is one round trip behind the drop. Without this the row springs back to its old place the
+ * instant the workspace refreshes, which reads as "the drag did not work" — the NO-BLIP law's
+ * subject, applied to a sequence instead of to a value.
+ *
+ * ⚠ PAST THE ECHO WINDOW THE SERVER WINS, unconditionally. That asymmetry is the whole design of
+ * this module: inside the window a local drag is newer truth; outside it, a difference between
+ * the copies is divergence between SESSIONS, and the durable store decides.
+ *
+ * ⛔ IDS THE STAMP DOES NOT NAME KEEP THEIR SERVER ORDER, appended after the named ones — the
+ * same rule the host applies to a `folder_reorder` payload. A view created in another tab since
+ * the drop is not evidence that the drop was wrong; dropping it would be this function deleting
+ * a view from the rail to defend a sequence.
+ */
+export function applyViewOrder<T extends { id: string }>(
+  views: T[],
+  stamps: FolderStamps | undefined,
+  now: number
+): T[] {
+  const stamp = stamps?.orderedViews;
+  if (!stamp || !isRecent(stamp.at, now) || !Array.isArray(stamp.order)) return views;
+  const byId = new Map(views.map((v) => [v.id, v]));
+  const out: T[] = [];
+  const placed = new Set<string>();
+  for (const id of stamp.order) {
+    const v = byId.get(id);
+    if (!v || placed.has(id)) continue;
+    placed.add(id);
+    out.push(v);
+  }
+  for (const v of views) if (!placed.has(v.id)) out.push(v);
+  return out;
+}
+
+/**
+ * The host's folder list, corrected by what this browser just did.
+ *
+ *   deleted recently  -> DROP it, even though the echo still lists it
+ *                        (the tombstone rule; without this a deleted folder
+ *                        blinks back for one round trip)
+ *   renamed recently  -> keep OUR name until the echo carries it
+ *   created recently  -> keep OURS if the echo has not caught up yet
+ *
+ * Everything stale yields to the host: past the window, a difference between
+ * the copies is divergence between sessions, and host state is the durable
+ * truth. That asymmetry is the whole design.
+ */
+export function reconcileFolders(
+  hostFolders: GridFolder[] | undefined,
+  localFolders: GridFolder[] | undefined,
+  stamps: FolderStamps | undefined,
+  now: number
+): GridFolder[] {
+  const host = hostFolders ?? [];
+  const out: GridFolder[] = [];
+  const seen = new Set<string>();
+
+  for (const f of host) {
+    if (isRecent(stamps?.deleted?.[f.id], now)) continue; // tombstone
+    seen.add(f.id);
+    const rename = stamps?.renamed?.[f.id];
+    out.push(isRecent(rename?.at, now) && rename ? { ...f, name: rename.name } : f);
+  }
+
+  // A folder this browser created that the echo has not yet returned. Skipped
+  // when it was also deleted since — creating and deleting inside one window
+  // must net to nothing, not to a ghost.
+  for (const f of localFolders ?? []) {
+    if (seen.has(f.id)) continue;
+    if (!isRecent(stamps?.created?.[f.id], now)) continue;
+    if (isRecent(stamps?.deleted?.[f.id], now)) continue;
+    out.push(f);
+  }
+
+  out.sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || a.name.localeCompare(b.name));
+
+  // ── WAVE 20 item 19 (C-FOLDER-REORDER): this browser's drag, until the echo carries it.
+  //
+  // Applied AFTER the host sort and as a SEPARATE pass, both deliberately:
+  //   · the host's `order` numbers are the durable truth and stay the base sequence, so a
+  //     folder the stamp never names keeps exactly the place the server gave it;
+  //   · `Array.prototype.sort` is stable (ES2019), so every unnamed folder — one created in
+  //     another tab between the drag and the echo, say — holds its relative position at the
+  //     end instead of being flung to the front by a missing rank.
+  // A stamped id that has since been DELETED needs no handling: the tombstone pass above
+  // already dropped it, and `rank` is only ever consulted for folders that survived.
+  const ordered = stamps?.ordered;
+  if (isRecent(ordered?.at, now) && ordered) {
+    const rank = new Map(ordered.order.map((id, i) => [id, i]));
+    out.sort(
+      (a, b) =>
+        (rank.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
+        (rank.get(b.id) ?? Number.MAX_SAFE_INTEGER)
+    );
+  }
+  return out;
+}
+
+/**
+ * Where an item actually belongs right now: this browser's recent drag wins
+ * over the host's echo, and a folder that no longer exists resolves to ROOT.
+ *
+ * The second half matters as much as the first. `folder_delete` moves contents
+ * to root host-side, but the client sees the folder vanish one render before
+ * the items' `folderId` is rewritten — and an item pointing at a folder nobody
+ * renders would simply not appear in any group. Resolving a dangling ref to
+ * root is what stops a folder delete from making views look deleted too.
+ */
+export function resolveFolderId(
+  itemId: string,
+  hostFolderId: string | null | undefined,
+  folders: GridFolder[],
+  stamps: FolderStamps | undefined,
+  now: number
+): string | null {
+  const moved = stamps?.moved?.[itemId];
+  const id = isRecent(moved?.at, now) && moved ? moved.folderId : (hostFolderId ?? null);
+  if (id == null) return null;
+  // ⚠ W32-T27 — the RESERVED root placement is not a dangling reference. It names no folder by
+  // design, so the `folders.some(...)` test below would null it and hand the item straight back
+  // to the Shared bucket, re-creating item 20 one layer down from where it was fixed.
+  if (id === ROOT_FOLDER_ID) return ROOT_FOLDER_ID;
+  return folders.some((f) => f.id === id) ? id : null;
+}
+
+export interface FolderGroup<T> {
+  folder: GridFolder | null; // null = the root group
+  items: T[];
+  /**
+   * ⭐⭐ WAVE 40 · T28 (owner instruction 30) — THE PIN GROUP: unfiled default views, ABOVE
+   * every folder.
+   *
+   * ⛔ IT IS A SECOND `folder: null` GROUP, and that is why this flag exists rather than a
+   * reserved folder id. The pin group and the ungrouped section are both "views in no folder",
+   * so neither can carry a heading and neither may be given a synthetic id — an id would be
+   * emitted by the rail's own drag surfaces (`item_move`, `folder_reorder`) against a folder
+   * that exists in nobody's store, which is the failure {@link isSyntheticFolderId} was
+   * introduced to stop. A flag says "this bucket renders first" and says nothing else, so the
+   * rail can key, class and drop-guard the two apart without either becoming a place.
+   *
+   * ⚠ ABSENT on every other group, never `false`, so a caller that does not pass `isPinned`
+   * gets output that is byte-identical (JSON included) to the pre-T28 shape.
+   */
+  pinned?: true;
+}
+
+/**
+ * WAVE 20 item 18 / WAVE 21 item 9 (ruling R12, contract C1) — the SYNTHETIC folder
+ * that every view shared WITH you appears under.
+ *
+ * ⛔ IT IS NOT A STORED FOLDER, and nothing may ever write one with this id. It has no
+ * record in `folders`, no `order`, no icon, and the rail refuses every action on it
+ * (`ViewSidebar` suppresses the row menu for exactly this id): it cannot be renamed into
+ * something else, duplicated into a second copy of other people's work, or deleted. It is a
+ * READING of the view list — "these arrived by grant" — rendered as a group because that is
+ * the only shape this rail has for "a set of views with something in common".
+ *
+ * Declared HERE rather than in the component (where it lived through wave 20) so the
+ * synthesis below is pure, and `verify_folders.py` can run it under node like every other
+ * rule in this file. A constant a gate cannot reach is a contract nobody checks.
+ */
+export const SHARED_FOLDER_ID = "__shared__";
+export const SHARED_FOLDER_NAME = "Shared with me";
+
+/**
+ * ⭐⭐ WAVE 34 · T25 (ruling R11) — A SHARED **FOLDER** GETS ITS OWN GROUP, under this prefix.
+ *
+ * R11: *"A folder (with the Views inside it) can be shared with a team member."* Everything below
+ * the client already worked and was VERIFIED before this was written: `core/shares.py::KINDS` has
+ * carried `'folder'` since wave 20, the rail already offers "Share folder", and
+ * `grid_events.py::_granted_views` has projected each granted folder's views since `D-37`. What
+ * did not work is the last inch: every shared view landed in ONE flat "Shared with me" group, so
+ * the receiver got loose views and **the folder itself was invisible**.
+ *
+ * ⭐ The name has been on the wire the whole time. `_granted_views` stamps
+ * `v['sharedFolder'] = <folder name>` with the comment *"so the client can group these together
+ * later"*, and a census found ZERO readers of it anywhere in `web/src` — a flag shipped without
+ * its reader. This is the reader.
+ *
+ * ⚠ A PREFIX RATHER THAN ONE RESERVED ID, because there can be several: two colleagues can each
+ * share a folder with you. {@link isSyntheticFolderId} is what every affordance must ask instead
+ * of comparing against `SHARED_FOLDER_ID` — a rail that suppressed actions on one synthetic group
+ * and offered them on another would emit `item_move`/`folder_rename` against a folder id that
+ * exists in nobody's store.
+ *
+ * ⛔⛔ THE KEY IS **OWNER + NAME**, NOT NAME, AND THE FIRST DRAFT OF THIS FUNCTION GOT IT WRONG.
+ * It keyed on the folder name alone while the comment right here claimed to handle two colleagues
+ * sharing folders with the SAME NAME — so those two folders merged into ONE group, and the head's
+ * `title` (which reads the first item's `owner`) misattributed every view from the second sharer.
+ * Per-view `sharedRole` was never affected, so nothing leaked; what broke was the rail telling you
+ * whose work you were reading, which is the entire point of the group. **A comment that describes
+ * the case the code does not handle is worse than no comment**, because it is what a reviewer
+ * checks against. Found by this ticket's own verifier reading the two side by side.
+ *
+ * ⛔ NOTHING MAY EVER WRITE ONE. Like `SHARED_FOLDER_ID` these ids are a READING of the view list,
+ * not a record: no `order`, no icon, no row in `folders`.
+ */
+export const SHARED_FOLDER_PREFIX = "__sharedfld__:";
+
+/**
+ * The synthetic group id for a folder somebody shared with you.
+ *
+ * ⚠ `owner` FIRST and separated by a character usernames cannot contain. `core/users.py` keeps
+ * usernames lower-case and non-empty; a folder NAME is free text and can contain anything a user
+ * types, `:` included. Putting the free-text half last means no pair of (owner, name) can spell
+ * another pair's id, whatever somebody calls a folder.
+ */
+export function sharedFolderGroupId(owner: string, name: string): string {
+  return `${SHARED_FOLDER_PREFIX}${owner}:${name}`;
+}
+
+/**
+ * Is this group id SYNTHESISED rather than stored? True for "Shared with me" and for every
+ * shared-folder group. Every drag, drop, rename and delete affordance in the rail asks this.
+ */
+export function isSyntheticFolderId(id: string | null | undefined): boolean {
+  return id === SHARED_FOLDER_ID
+    || (typeof id === "string" && id.startsWith(SHARED_FOLDER_PREFIX));
+}
+
+/**
+ * ⭐⭐ WAVE 32 · T27 (owner item 20) — **"FILED AT ROOT", AS A VALUE.**
+ *
+ * Owner: *a shared View cannot be moved out of the Shared folder.* The cause is that **root was
+ * represented by ABSENCE at every layer**, and absence cannot distinguish two different facts:
+ *
+ *   · `folderId == null` because the receiver never filed this view — it should show under
+ *     "Shared with me", which is where a grant LANDS;
+ *   · `folderId == null` because the receiver deliberately dragged it OUT of that group.
+ *
+ * `groupByFolder` had to guess, and it guessed "shared" — so filing a shared view at root put it
+ * straight back where it came from. **The root bucket was unreachable for a shared view by
+ * construction**, which is exactly why only folder→folder moves ever appeared to work.
+ *
+ * ⛔ THE SENTINEL IS STORED, NOT DERIVED, AND THAT IS THE WHOLE FIX. Both other layers wrote the
+ * same absence and must both learn this value: `core/grid_events.py`'s `item_move` branch
+ * (`if target is None: cur.pop(item_id, None)  # back to the root`) and
+ * `aios_grid.clean_item_folders`, whose own docstring states the defect one level deeper —
+ * *"nothing stores 'this item is in no folder'"*. A client-only fix is impossible; there is
+ * nothing to read back.
+ *
+ * ⚠ It is a RESERVED id in the same namespace as real folder ids, so `resolveFolderId` must pass
+ * it through rather than treating it as dangling, and `clean_item_folders` must admit it beside
+ * `fid in fids`. It is deliberately NOT rendered as a group: {@link groupByFolder} maps it onto
+ * the ordinary root bucket, so nothing in the rail ever shows the word.
+ */
+export const ROOT_FOLDER_ID = "__root__";
+
+/**
+ * Group items into folders + a root bucket, in folder order, root LAST.
+ *
+ * Root last because the rails are read top-down and folders are the structure
+ * the user made; ungrouped items are the leftovers. Every item appears exactly
+ * once — a grouping that can drop an item would make a view look deleted.
+ *
+ * ⭐⭐ WAVE 40 · T28 (owner instruction 30) — WITH ONE BUCKET IN FRONT OF THE FOLDERS. The
+ * unfiled DEFAULT views lift out of the leftovers and render first, because they are not
+ * leftovers: they are the row every user lands on. See `isPinned` below for the whole rule,
+ * including the stored value that makes "unless the user moves it down" answerable. Omitting
+ * that predicate leaves this function byte-identical to the pre-T28 one, root LAST included,
+ * which is what the cohort rail and every existing test still get.
+ *
+ * ⭐ WAVE 21 item 9 (R12/C1) — `isShared` adds the synthetic "Shared with me" group,
+ * AFTER root, and three things about it are deliberate:
+ *
+ *   · **After root, not before it.** C1 says LAST in as many words. It reads correctly
+ *     too: the rail is "my folders, my loose views, and then other people's".
+ *   · **A shared view the receiver has FILED still goes to their folder.** The `__shared__`
+ *     group is where a grant LANDS, not a cage it stays in — the rail's own note calls
+ *     moving out "per-receiver placement" and that must keep working. So the synthetic
+ *     group collects only the shared views that resolved to ROOT.
+ *   · **An empty group does not render.** A folder head with nothing under it says "here is
+ *     something you cannot reach" — the same reason `foldNav` drops empty nav folders.
+ *
+ * Omitting `isShared` leaves the function byte-identical to the pre-wave-21 one, which is
+ * what every existing caller (the cohort rail, the tests) still gets.
+ */
+export function groupByFolder<T>(
+  items: T[],
+  folders: GridFolder[],
+  folderIdOf: (item: T) => string | null,
+  isShared?: (item: T) => boolean,
+  /**
+   * ⭐ WAVE 34 · T25 (R11) — the folder a shared item arrived through, if it did.
+   *
+   * Returns the folder's NAME and its OWNER, because the pair is the identity: the wire carries
+   * no folder id for a grant (`_granted_views` stamps a name and an owner, never an id), and the
+   * name alone is not unique across sharers.
+   *
+   * Optional, so every existing caller (the cohort rail, the tests) keeps the pre-T25 shape
+   * byte-for-byte: with it omitted, every shared item falls into the flat "Shared with me"
+   * group exactly as before. Supplied, the shared views SPLIT by the folder that carried them,
+   * and the folder finally appears on the receiver's screen.
+   */
+  sharedFolderOf?: (item: T) => { name: string; owner: string } | null,
+  /**
+   * ⭐⭐ WAVE 40 · T28 (owner instruction 30) — IS THIS VIEW A DEFAULT THAT PINS TO THE TOP?
+   *
+   * Owner: *"when it is not in a folder it must sit at the very top above all folders unless
+   * the user moves it down."* The rail passes `isUndeletableView`, so the three ids nobody can
+   * delete — the per-database default, Starred, and the IG Overview — are the pinned set. A
+   * PREDICATE rather than an id list for the same reason `mayFileView` takes a verdict: this
+   * module is "pure and React-free so verify_folders.py can run it under node" (see the header)
+   * and its only imports are one constant and one type. Importing the id set would point this
+   * file at `types.ts` for a decision the caller already knows the answer to.
+   *
+   * ⛔⛔ THE PIN ASKS FOR **ABSENCE**, NOT FOR THE ROOT SENTINEL, AND THAT IS WHERE "UNLESS THE
+   * USER MOVES IT DOWN" LIVES. W32-T27 split the one meaning of "root" into two stored values
+   * precisely so this question could be asked: `folderId == null` is *"nobody has ever placed
+   * this"*, and {@link ROOT_FOLDER_ID} is *"the user dragged it here on purpose"*. So the pin
+   * engages on the first and YIELDS on the second — drag the default view down onto the
+   * ungrouped section and `item_move` stores the sentinel, the lift stops applying, and it
+   * renders among the ordinary loose views where it was dropped. Filing it into a folder is the
+   * same yield by the instruction's own words. Both are DURABLE: the sentinel survives
+   * `aios_grid.clean_item_folders`, so the placement outlives the session that made it.
+   *
+   * ⚠ Deleting the folder a pinned view was filed into DROPS the placement (contents fall to
+   * root by absence, not by sentinel — `grid_events.py`'s `folder_delete`), so the pin
+   * re-engages. That is the only path back to the top, and it is a consequence rather than a
+   * feature: nothing in the rail today clears a placement to absence.
+   */
+  isPinned?: (item: T) => boolean
+): FolderGroup<T>[] {
+  const buckets = new Map<string, T[]>(folders.map((f) => [f.id, []]));
+  const root: T[] = [];
+  const shared: T[] = [];
+  /** W40-T28 — unfiled pinned views, in the order they arrived, rendered above every folder. */
+  const pinned: T[] = [];
+  /** synthetic group id -> {name, views}. Keyed by OWNER+NAME; see `SHARED_FOLDER_PREFIX`. */
+  const sharedFolders = new Map<string, { name: string; items: T[] }>();
+  for (const item of items) {
+    const id = folderIdOf(item);
+    const bucket = id == null ? undefined : buckets.get(id);
+    // ⭐⭐ W40-T28 (owner instruction 30) — AN UNFILED DEFAULT LIFTS OUT OF THE ROOT BUCKET.
+    //
+    // ⛔⛔ `id == null` IS THE WHOLE OF "UNLESS THE USER MOVES IT DOWN", AND IT IS TESTED HERE
+    // — FIRST — RATHER THAN INHERITED FROM THE CHAIN BELOW. Placed after the other branches this
+    // clause reads identically and DOES NOTHING: a folder id is taken by `buckets`, the root
+    // sentinel by its own branch, and a dangling ref was nulled by `resolveFolderId` long before
+    // this line, so `id` is already absent by the time control arrives and the test can be
+    // deleted with no observable change. A rule no mutation can break is a rule no gate is
+    // checking ([[a-declared-gate-is-an-unchecked-claim]]) — so the placement question is asked
+    // where its answer still decides something, and `verify_folders.py` can red it on its own leg.
+    //
+    // ⚠ WHAT ABSENCE MEANS IS W32-T27's SPLIT, reused rather than reinvented: `folderId == null`
+    // is "nobody has ever placed this", {@link ROOT_FOLDER_ID} is "the user dragged it here on
+    // purpose". So the pin engages on the first and yields to the second — drop the default view
+    // onto the ungrouped section and `item_move` stores the sentinel, the lift stops applying,
+    // and it renders among the loose views where it was dropped. Filing it into a folder is the
+    // same yield by the instruction's own words.
+    //
+    // ⚠ `!isShared` KEEPS THE GRANT BRANCH UNTOUCHED. A pinned view is per-user system state and
+    // can never BE a grant, so the two cannot collide in practice — the guard is what makes that
+    // a structural fact rather than an assumption, and it is why every shared-grouping leg stays
+    // byte-identical to the pre-T28 one.
+    if (id == null && !isShared?.(item) && isPinned?.(item)) pinned.push(item);
+    else if (bucket) bucket.push(item);
+    // ⭐⭐ W32-T27 (owner item 20) — THE ROOT BUCKET IS REACHABLE FOR A SHARED VIEW NOW.
+    // `ROOT_FOLDER_ID` is the receiver saying "I filed this at the top level"; absence still
+    // means "this arrived by grant and I have not filed it". Before this line the two were one
+    // value, `isShared` won, and a shared view dragged to root returned to "Shared with me" on
+    // the next render — the owner's item 20, in one branch.
+    else if (id === ROOT_FOLDER_ID) root.push(item);
+    else if (isShared?.(item)) {
+      // ⭐ W34-T25 (R11): a shared view that arrived through a FOLDER goes to that folder's own
+      // group; one that was granted directly still goes to the flat "Shared with me". The two
+      // are different facts and the receiver can see which is which.
+      const via = sharedFolderOf?.(item);
+      const name = via ? String(via.name || "").trim() : "";
+      const owner = via ? String(via.owner || "").trim() : "";
+      // ⚠ BOTH halves required. A folder name with no owner cannot be told apart from another
+      // sharer's folder of the same name, so it falls back to the flat group rather than
+      // inventing a group that might merge two people's work under one person's label.
+      if (name && owner) {
+        const key = sharedFolderGroupId(owner, name);
+        const bucket2 = sharedFolders.get(key);
+        if (bucket2) bucket2.items.push(item);
+        else sharedFolders.set(key, { name, items: [item] });
+      } else shared.push(item);
+    }
+    else root.push(item);
+  }
+  const out: FolderGroup<T>[] = folders.map((f) => ({ folder: f, items: buckets.get(f.id) ?? [] }));
+  // ⭐⭐ W40-T28 — IN FRONT OF EVERY FOLDER, which is the half of instruction 30 this module owns.
+  // ⚠ An EMPTY pin group is never emitted, the same rule the shared group carries: a bucket with
+  // nothing in it is a section the user cannot reach, and here it would also be a phantom second
+  // root the rail would have to render around.
+  if (pinned.length) out.unshift({ folder: null, items: pinned, pinned: true });
+  out.push({ folder: null, items: root });
+  if (shared.length)
+    out.push({ folder: { id: SHARED_FOLDER_ID, name: SHARED_FOLDER_NAME }, items: shared });
+  // ⚠ SORTED, not first-seen. A Map preserves insertion order, which here is the order the VIEWS
+  // happen to arrive in — so one view moving could reorder whole folders in the rail for no reason
+  // a reader could name. Sorting on the composite ID (owner first) is stable across every payload
+  // AND groups one colleague's folders together, which reads better than interleaving two people's
+  // folders alphabetically by name.
+  for (const key of [...sharedFolders.keys()].sort((a, b) => a.localeCompare(b))) {
+    const grp = sharedFolders.get(key)!;
+    out.push({ folder: { id: key, name: grp.name }, items: grp.items });
+  }
+  return out;
+}
+
+/**
+ * WAVE 20 item 19 (C-FOLDER-REORDER) — where a dragged folder lands: the full order with
+ * `draggedId` moved to sit immediately BEFORE `beforeId`, or last when that is null (the
+ * drop on the ungrouped section below every folder).
+ *
+ * Here rather than inside the rail because it is the only part of the drag a test can hold:
+ * the drop handler is DOM, the emit is the caller's, and this is the arithmetic that decides
+ * what the user sees. `null` means "emit nothing" — an unknown id, or a drop that changes
+ * nothing. Returning the unchanged array instead would be worse than useless: the caller
+ * cannot tell it apart from a real reorder, so every no-op drag would write the store, bump
+ * every reader's payload, and reconcile to the identical list.
+ *
+ * ⚠ The dragged id is REMOVED BEFORE the target index is read. Taking the index first and
+ * splicing after is the classic off-by-one here: dragging a folder DOWNWARD would land it one
+ * place short of where it was dropped, and only in that direction — the shape of bug that
+ * survives a demo and gets reported as "it sometimes doesn't move".
+ */
+export function reorderFolderIds(
+  ids: string[],
+  draggedId: string,
+  beforeId: string | null
+): string[] | null {
+  if (!ids.includes(draggedId)) return null;
+  // ⛔ DROPPED ON ITSELF. Without this the id is filtered out, `indexOf` cannot find its own
+  // target, and the "not found" branch sends the folder to the END — so releasing a drag over
+  // the folder you picked up would quietly move it to the bottom of the rail. Found by this
+  // function's own gate the minute the arithmetic left the component; the drop handler's
+  // indicator suppresses the same case visually, which is exactly why it would never have
+  // been noticed there.
+  if (beforeId === draggedId) return null;
+  const rest = ids.filter((id) => id !== draggedId);
+  const found = beforeId ? rest.indexOf(beforeId) : -1;
+  const at = found < 0 ? rest.length : found;
+  const next = [...rest.slice(0, at), draggedId, ...rest.slice(at)];
+  if (next.length === ids.length && next.every((id, i) => id === ids[i])) return null;
+  return next;
+}
+
+/**
+ * ⭐⭐ WAVE 34 · T22 (ruling R4, `D-249`) — MAY THIS VIEWER FILE THIS VIEW INTO A FOLDER?
+ *
+ * ⛔ NOT THE SAME QUESTION AS `mayEditView`, AND CONFLATING THEM IS THE DEFECT. The rail gated its
+ * `draggable` on `mayEditView`, which fail-closes on a shared view whose role is not `edit` — so a
+ * read-only shared view could not BEGIN a drag, and the owner's report is that a view cannot be
+ * taken out of a folder. Filing is not a content edit: it writes a PLACEMENT into the receiver's
+ * own workspace stratum and never touches the owner's object.
+ *
+ * ⭐ THE SERVER ALREADY AGREED, IN TWO PLACES, BEFORE THIS FUNCTION EXISTED. `grid_events.py::
+ * table_workspace` merges granted views into `ws['views']`, which is the very set `item_move`'s
+ * own-ids test reads — so the write this drag produces is ACCEPTED today. And the `view_reorder`
+ * branch beside it carries the rule in prose: *"NO OWNERSHIP FILTER … refusing ids they do not own
+ * would make exactly those un-draggable, which is the half of sharing people notice."* The client
+ * was the only refuser, and it was refusing a write the server was ready to take.
+ *
+ * ⚠ `mayEdit` IS A PARAMETER, NOT AN IMPORT, and that is deliberate: this module is
+ * "pure and React-free so verify_folders.py can run it under node" (see the header), and its only
+ * imports today are one constant and one type. Taking the verdict rather than the resolver keeps
+ * the truth table testable in isolation and keeps this file's dependency surface where its own
+ * header promised it would stay.
+ *
+ * ⚠ USE IT ONLY AT THE DRAG SITE. Every other affordance the rail gates on `mayEditView` — rename,
+ * description, delete, permissions — really is a content edit on somebody else's object, and the
+ * server really does refuse those.
+ */
+export function mayFileView(view: { shared?: boolean }, mayEdit: boolean): boolean {
+  return view.shared === true || mayEdit;
+}
+
+/** A fresh folder id. Client-generated, like every other id in this component. */
+export function newFolderId(): string {
+  const rand =
+    typeof crypto !== "undefined" && "randomUUID" in crypto
+      ? crypto.randomUUID().slice(0, 8)
+      : Math.random().toString(36).slice(2, 10);
+  return `fld_${rand}`;
+}

web/src/customer-grid/iconShapes.ts

@@ -1,355 +1,355 @@
-// ---------------------------------------------------------------------------
-// customer-grid / iconShapes.ts
-// Wave-8 items I18 + I20 — ONE geometry source for the grid's icon vocabulary,
-// rendered by TWO very different painters:
-//
-//   - React  <FieldTypeIcon> / <ModeIcon>  — DOM svg in panels, popovers, menus
-//   - glide  headerIcons sprites           — canvas, drawn from an SVG *string*
-//
-// Glide's sprite API takes a function returning SVG SOURCE, so a header icon can
-// never be a React component. Keeping the paths as DATA (IconShape[]) and giving
-// each painter its own thin renderer is what stops the two from drifting — the
-// alternative (hand-copying every path into a template literal) guarantees the
-// header and the panel eventually disagree about what a "date" looks like.
-//
-// Geometry rules: 16x16 viewBox, stroke-based, 1.35 stroke, round caps/joins,
-// currentColor. Vector paths only — NEVER emoji (owner constant).
-// ---------------------------------------------------------------------------
-
-import type { AggName, DisplayMode, FieldType, FolderShape, FolderTone } from "./types";
-import {
-  LP_BLUE,
-  LP_BLUE_DEEP,
-  LP_GREEN,
-  LP_GREEN_DEEP,
-  LP_LINE,
-  LP_MUTED,
-  LP_RED,
-  LP_RED_DEEP,
-  LP_YELLOW,
-  LP_YELLOW_DEEP,
-} from "./theme";
-
-/** One drawing primitive. `fill: true` fills the path instead of stroking it
- *  (the rating star is the only shape that reads better solid). */
-export type IconShape = { d: string; fill?: boolean };
-
-/** A circle as a path — two half-arcs. Sprites are SVG *source*, so every shape
- *  has to survive being serialized into a string; paths do, <circle> elements
- *  would need a second serializer branch for no benefit. */
-const circle = (cx: number, cy: number, r: number): string =>
-  `M${cx - r} ${cy}a${r} ${r} 0 1 0 ${r * 2} 0a${r} ${r} 0 1 0 ${-r * 2} 0`;
-
-const CALENDAR: IconShape[] = [
-  { d: "M3.2 4.6h9.6v8.2H3.2z" },
-  { d: "M3.2 7.2h9.6" },
-  { d: "M5.8 3v3.2" },
-  { d: "M10.2 3v3.2" },
-];
-
-/**
- * Field type → icon geometry. A TOTAL record on purpose: adding a FieldType
- * without an icon is a compile error, not a silently blank header.
- */
-export const TYPE_SHAPES: Record<FieldType, IconShape[]> = {
-  text: [{ d: "M3 5h10M3 8h10M3 11h6" }],
-  status: [{ d: "M4 13V3.5h7.6L10.1 6l1.5 2.5H4" }],
-  currency: [
-    { d: "M8 2.8v10.4" },
-    { d: "M10.6 5.4A2.6 2.6 0 0 0 8.2 4.2H7.4a2 2 0 0 0 0 4h1.2a2 2 0 0 1 0 4H7.8a2.6 2.6 0 0 1-2.4-1.4" },
-  ],
-  int: [{ d: "M6.2 3L4.8 13M11.2 3l-1.4 10M3.4 6.2h9.2M2.9 9.8h9.2" }],
-  date: CALENDAR,
-  pct: [
-    { d: circle(4.6, 4.6, 1.6) },
-    { d: circle(11.4, 11.4, 1.6) },
-    { d: "M12.2 3.9L3.8 12.3" },
-  ],
-  select: [{ d: "M3.2 3.8h9.6v8.4H3.2z" }, { d: "M6.2 7.2l1.8 1.8 1.8-1.8" }],
-  user: [
-    { d: circle(8, 6, 2.4) },
-    { d: "M3.6 13c0-2.4 2-3.8 4.4-3.8s4.4 1.4 4.4 3.8" },
-  ],
-  multiselect: [
-    { d: "M3 4.6h2.2v2.2H3zM3 9.2h2.2v2.2H3z" },
-    { d: "M7.2 5.7h6M7.2 10.3h6" },
-  ],
-  checkbox: [{ d: "M3.4 3.4h9.2v9.2H3.4z" }, { d: "M5.8 8.1l1.8 1.9 3.4-3.9" }],
-  phone: [
-    { d: "M5.1 3.2L7 5.1 5.6 7a7.2 7.2 0 0 0 3.4 3.4l1.9-1.4 1.9 1.9-1.5 1.6c-3 .5-8.3-4.8-7.8-7.8z" },
-  ],
-  email: [{ d: "M3 4.4h10v7.2H3z" }, { d: "M3 4.9l5 3.9 5-3.9" }],
-  url: [
-    { d: "M7 5.4L8.4 4a2.6 2.6 0 0 1 3.7 3.7L10.7 9" },
-    { d: "M9 10.6L7.6 12a2.6 2.6 0 0 1-3.7-3.7L5.3 7" },
-    { d: "M6.2 9.8l3.6-3.6" },
-  ],
-  rating: [
-    {
-      d: "M8 2.9l1.63 3.3 3.64.53-2.63 2.57.62 3.63L8 11.24 4.74 12.93l.62-3.63L2.73 6.73l3.64-.53z",
-      fill: true,
-    },
-  ],
-  created_time: [{ d: circle(8, 8, 5.2) }, { d: "M8 4.9v3.4l2.3 1.4" }],
-  formula: [
-    { d: "M5.6 12.8V5.4a2 2 0 0 1 3.2-1.6" },
-    { d: "M4.2 7.6h4.6" },
-    { d: "M10.2 8.4l3 3.4M13.2 8.4l-3 3.4" },
-  ],
-  // Wave-18 C5-AUTOFIELD (D's spec, applied by C as client-vocab registrar). A 290° cycle ring
-  // with an arrowhead, wrapped around a solid run-triangle: a job that runs, repeatedly.
-  // Deliberately NOT a bolt (`FOLDER_SHAPE_PATHS.bolt` already means "Priority") and not a clock
-  // (`created_time` owns the closed rim + hands).
-  automation: [
-    { d: "M10.8 4.1A4.8 4.8 0 1 1 5.3 4.1" },
-    { d: "M4.2 6L5.3 4.1 3.1 4.5" },
-    { d: "M6.9 6.1L9.8 8 6.9 9.9z", fill: true },
-  ],
-  // Wave-22 C7 (added by C as client-vocab registrar, the W18 automation precedent). A rising
-  // series on an axis: a measure OVER TIME, which is what a metric field is. Deliberately not
-  // the formula fx (that computes over the ROW) and not a bare number (int owns ##).
-  metric: [
-    { d: "M3.2 3.2v9.6h9.6" },
-    { d: "M5 10.4l2.4-2.6 1.9 1.5 3.1-3.9" },
-  ],
-  // Wave-23 C7 — TWO BRACES facing each other with a dot between them: the universal mark for
-  // "a structured document", and the one glyph in this table that draws its own SYNTAX rather
-  // than a picture of what the value means. Deliberately not a document page (nothing here owns
-  // that yet, but a page reads as a file/attachment, which a json cell is not) and not a tree
-  // of nodes (too fine to survive 16px). The centre dot is what keeps the two braces from
-  // reading as parentheses at small sizes.
-  json: [
-    { d: "M6.4 3.2c-1.5 0-1.5 3.4-1.5 3.4S4.8 8 3.4 8s1.5 1.4 1.5 1.4 0 3.4 1.5 3.4" },
-    { d: "M9.6 3.2c1.5 0 1.5 3.4 1.5 3.4s.1 1.4 1.5 1.4-1.5 1.4-1.5 1.4 0 3.4-1.5 3.4" },
-    { d: circle(8, 8, 0.85), fill: true },
-  ],
-  // ⭐ Wave-27 item 13 (R13) — THE ANGLE BRACKETS, the mark every editor on earth uses for
-  // "this is source". Drawn as two chevrons with a slash leaning between them, which is what
-  // separates it from `json` two entries up: json draws BRACES (a document's own syntax), code
-  // draws BRACKETS (a snippet's). Deliberately not a terminal prompt (that reads as "run this",
-  // and R13 is explicit there is no execution engine) and not a page of lines (`list` mode and
-  // `text` already trade on that reading).
-  code: [
-    { d: "M5.6 4.9 2.6 8l3 3.1" },
-    { d: "M10.4 4.9 13.4 8l-3 3.1" },
-    { d: "M9.1 3.6 6.9 12.4" },
-  ],
-  // Wave-19 R7 — a framed picture: the mount, a sun, and the hill line every photo glyph
-  // resolves to at 16px. Drawn on the same 16-unit grid as its neighbours.
-  image: [
-    { d: "M2.6 3.4h10.8v9.2H2.6z" },
-    { d: circle(6, 6.3, 1.1) },
-    { d: "M2.6 10.6L6.1 7.6l2.5 2.1 2.2-1.8 2.6 2.2" },
-  ],
-  // ⭐ 2026-08-07 — TWO INTERLOCKING CHAIN LINKS, the one glyph everybody already reads as
-  // "this points at something else". Drawn as two rounded rectangles overlapping at the centre
-  // rather than as an arrow into a box: an arrow would mean navigation, and a link column is a
-  // relation that exists in both directions whether or not you follow it.
-  link: [
-    { d: "M6.6 5.2H4.9a2.8 2.8 0 000 5.6h1.7" },
-    { d: "M9.4 5.2h1.7a2.8 2.8 0 010 5.6H9.4" },
-    { d: "M5.6 8h4.8" },
-  ],
-  // ⭐ 2026-08-07 — THREE BARS FOLDING INTO ONE, read top-to-bottom: many linked values
-  // collapsing to a single aggregate. Deliberately not a sigma (too fine at 16px, and it would
-  // claim SUM when the function is chosen per column) and not a funnel (that is filtering,
-  // which is what `limit` does — a different half of the same field).
-  rollup: [
-    { d: "M3.2 4.4h9.6" },
-    { d: "M4.8 8h6.4" },
-    { d: "M6.6 11.6h2.8" },
-  ],
-  // ⭐ WAVE 34 · T53 (R13), drawn by C on F's ask (`F-2`) — AI ENRICHMENT.
-  // The SPARKLE, because it is the product's own AI mark already: `Shell.tsx::SparkIcon` wears it
-  // on the Assistant rail row, so a column the AI fills reads as the same family rather than as a
-  // second vocabulary for one idea. Deliberately NOT the `automation` cycle-ring two entries up
-  // (that means "a job that runs, repeatedly", and an enrichment can be manual) and not a robot
-  // head (`Shell.tsx::RobotIcon` claims that for the Agents MODULE; a field is not a module).
-  // ⚠ TWO stars, not one: a lone four-point star at 16px with a 1.35 stroke reads as a plus sign.
-  // The small companion is what makes the mark say "sparkle".
-  ai_enrich: [
-    { d: "M6.6 2.6l1.3 3.1 3.1 1.3-3.1 1.3-1.3 3.1-1.3-3.1L2.2 7l3.1-1.3z" },
-    { d: "M11.9 9.8l.7 1.6 1.6.7-1.6.7-.7 1.6-.7-1.6-1.6-.7 1.6-.7z" },
-  ],
-};
-
-/**
- * Display mode → icon geometry (I18). Also total: the wave-8 Dashboard mode
- * cannot land in DISPLAY_MODES without the compiler demanding its icon here.
- */
-export const MODE_SHAPES: Record<DisplayMode, IconShape[]> = {
-  grid: [
-    { d: "M2.6 3.4h10.8v9.2H2.6z" },
-    { d: "M2.6 6.5h10.8M2.6 9.5h10.8M6.4 3.4v9.2M10 3.4v9.2" },
-  ],
-  list: [{ d: "M3 4.6h1.4M6.4 4.6h6.6M3 8h1.4M6.4 8h6.6M3 11.4h1.4M6.4 11.4h6.6" }],
-  // I19c — a framed set of bars: "several charts", not "one chart".
-  chart: [
-    { d: "M2.6 3.4h10.8v9.2H2.6z" },
-    { d: "M5.4 10.6V7.2M8 10.6V5.4M10.6 10.6V8.6" },
-  ],
-  // I10 (C2) — the LEGACY key. Kept so this record stays total over DisplayMode, which is
-  // what makes "accept 'dashboard' on read forever" a compile-time guarantee rather than a
-  // promise. Same drawing: a stored 'dashboard' IS a chart.
-  dashboard: [
-    { d: "M2.6 3.4h10.8v9.2H2.6z" },
-    { d: "M5.4 10.6V7.2M8 10.6V5.4M10.6 10.6V8.6" },
-  ],
-  calendar: CALENDAR,
-  kanban: [{ d: "M2.8 3.4h3.1v9.2H2.8zM6.5 3.4h3.1v6.2H6.5zM10.2 3.4h3.1v7.6h-3.1z" }],
-  map: [
-    { d: "M8 2.6a3.6 3.6 0 0 1 3.6 3.6c0 2.7-3.6 7.2-3.6 7.2S4.4 8.9 4.4 6.2A3.6 3.6 0 0 1 8 2.6z" },
-    { d: circle(8, 6.1, 1.3) },
-  ],
-  // 2026-08-02 item 7 — the time-series view. Drawn as a framed grid with a trend running
-  // through it, because that is literally what the panel is: metric ROWS x bucket COLUMNS with
-  // a per-row line toggle. Deliberately not the plain `line` chart mark — a chart view and a
-  // time-series table must not be the same picture in the same rail.
-  timeseries: [
-    { d: "M2.6 3.4h10.8v9.2H2.6z" },
-    { d: "M2.6 6.6h10.8M6.2 3.4v9.2" },
-    { d: "M7.2 10.8l2-2.4 1.6 1.2 1.8-2.6" },
-  ],
-  // Wave-18 C6-CATALOG — an OPEN BOOK: two facing leaves with a spine between them, and a
-  // product block sitting on the left one. Every other mode in this table draws a way of
-  // arranging RECORDS; this one has to read as a printed artifact, so it is the only mark here
-  // with a spine and a gutter. Deliberately not a page-with-lines (`list` owns that reading) and
-  // not a framed grid (`grid`/`chart`/`timeseries` share the frame).
-  catalog: [
-    { d: "M2.4 4.2h4.6a1.6 1.6 0 0 1 1 .4l0 8a1.6 1.6 0 0 0-1-.4H2.4z" },
-    { d: "M13.6 4.2H9a1.6 1.6 0 0 0-1 .4l0 8a1.6 1.6 0 0 1 1-.4h4.6z" },
-    { d: "M3.9 6.4h2.3v2.8H3.9z" },
-  ],
-  // Wave-23 C9 — a SHEET WITH A WRITING LINE: two filled answer bars and an empty rule beneath
-  // them. Every other mode here draws a way of ARRANGING records that already exist; this one
-  // has to read as a record being MADE, so it is the only mark whose bottom line is open.
-  // Deliberately not a clipboard (nothing else here has a frame with a tab) and not a pencil
-  // (an edit affordance means something else app-wide).
-  // ⭐ Wave-27 C3 (owner item 8) — a CARD WITH TWO ARROWS LEAVING IT, left and right. Every
-  // other mark here draws an arrangement of many records; this one has to read as ONE record
-  // with two exits, because that is exactly what the deck is. Deliberately not a stack of cards
-  // (that is a lane, and `kanban` owns it) and not a hand or a gesture glyph (nothing else in
-  // this vocabulary draws a body part, and it would read as "drag" rather than "decide").
-  swipe: [
-    { d: "M5.4 3.4h5.2v9.2H5.4z" },
-    { d: "M3.6 8H1.4M2.8 6.8 1.4 8l1.4 1.2" },
-    { d: "M12.4 8h2.2M13.2 6.8 14.6 8l-1.4 1.2" },
-  ],
-  form: [
-    { d: "M3.4 2.8h9.2v10.4H3.4z" },
-    { d: "M5.6 5.6h4.8" },
-    { d: "M5.6 8h4.8" },
-    { d: "M5.6 10.6h2.6" },
-  ],
-  // W36-T04 — angle brackets over a baseline: the universal mark for "this is code", and the one
-  // shape in this table that is about the AUTHORING rather than about the arrangement of rows.
-  script: [
-    { d: "M6 5.4 3.2 8l2.8 2.6M10 5.4 12.8 8 10 10.6" },
-    { d: "M2.6 3.4h10.8v9.2H2.6z" },
-  ],
-};
-
-/**
- * Wave-9 I16 — one mark per CHART KIND. Total over `ChartKind`, so a kind added to C2's
- * vocabulary cannot ship without a drawing.
- *
- * ⚠ The owner asked for an icon on every chart-type option, and the wave-8 ruling stands:
- * an `<option>` cannot render SVG and unicode glyphs are gate-banned, so the chart-type
- * picker is NOT a native `<select>` — it is a radio-row list like the mode switcher, which
- * is the only shape that can carry a real mark.
- *
- * The key type is a string union declared here rather than imported from chartData.ts: this
- * module is a leaf (types + theme only) and chartData imports IT, not the reverse.
- */
-export type ChartKindKey = "bar" | "line" | "area" | "donut" | "kpi" | "table";
-export const CHART_KIND_SHAPES: Record<ChartKindKey, IconShape[]> = {
-  bar: [{ d: "M3.2 12.8V7.4M6.4 12.8V4.2M9.6 12.8V8.8M12.8 12.8V5.8" }],
-  line: [
-    { d: "M2.6 11.2l3.2-3.4 2.6 2 4.9-5.2" },
-    { d: circle(5.8, 7.8, 0.9) },
-    { d: circle(8.4, 9.8, 0.9) },
-  ],
-  area: [
-    { d: "M2.6 12.4V9.2l3.2-3.2 2.6 2 4.9-4.6v9z" },
-    { d: "M2.6 9.2l3.2-3.2 2.6 2 4.9-4.6" },
-  ],
-  donut: [{ d: circle(8, 8, 5) }, { d: circle(8, 8, 2.1) }],
-  // A single big number: the KPI card. Drawn as a framed value rather than a glyph, so it
-  // reads as "one number" beside four marks that all read as "a distribution".
-  kpi: [{ d: "M2.6 3.8h10.8v8.4H2.6z" }, { d: "M5.4 9.6V6.4l1.9 3.2V6.4M9.4 6.4v3.2h1.8" }],
-  // Wave-16 C-CHARTCAP: a group-by aggregate table. Framed like the KPI (it is a card of
-  // values, not a distribution), with a header band and a column rule.
-  table: [
-    { d: "M2.6 3.4h10.8v9.2H2.6z" },
-    { d: "M2.6 6.2h10.8M7.2 6.2v6.4M2.6 9.4h10.8" },
-  ],
-};
-
-export const CHART_KIND_LABELS: Record<ChartKindKey, string> = {
-  bar: "Bar",
-  line: "Line",
-  area: "Area",
-  donut: "Donut",
-  kpi: "Single value",
-  table: "Table",
-};
-
-/** I16 — the pastel each chart kind wears, same family rule as MODE_TONE. */
-export const CHART_KIND_TONE: Record<ChartKindKey, FolderTone> = {
-  bar: "blue",
-  line: "green",
-  area: "green",
-  donut: "yellow",
-  kpi: "neutral",
-  table: "neutral",
-};
-
-/**
- * Wave-9 contract C5 (I15) — folder icon geometry. TOTAL over `FolderShape`, so a shape key
- * added to the wire contract in types.ts cannot ship without a drawing.
- *
- * Same 16x16 stroke vocabulary as everything above: these have to sit beside a mode icon in
- * the same rail and read as one family. `folder` is first because it is the default every
- * pre-wave-9 folder falls back to (I14: "existing folders get the folder icon").
- */
-export const FOLDER_SHAPE_PATHS: Record<FolderShape, IconShape[]> = {
-  folder: [{ d: "M2.4 12.6V4.2a.6.6 0 0 1 .6-.6h3.2l1.5 1.7h5.3a.6.6 0 0 1 .6.6v6.7a.6.6 0 0 1-.6.6H3a.6.6 0 0 1-.6-.6z" }],
-  star: [
-    { d: "M8 2.9l1.63 3.3 3.64.53-2.63 2.57.62 3.63L8 11.24 4.74 12.93l.62-3.63L2.73 6.73l3.64-.53z" },
-  ],
-  flag: [
-    { d: "M4.2 13.4V2.9" },
-    { d: "M4.2 3.4h7.6l-1.5 2.6 1.5 2.6H4.2z" },
-  ],
-  tag: [
-    { d: "M2.9 8.2V3.5a.6.6 0 0 1 .6-.6h4.7l5 5-5.3 5.3z" },
-    { d: circle(5.6, 5.6, 1) },
-  ],
-  bookmark: [{ d: "M4.4 2.9h7.2v10.4L8 10.7l-3.6 2.6z" }],
-  // Four of the host's shapes ALREADY exist in this file as a mode or a field-type mark.
-  // Reusing the geometry rather than drawing a second "chart" is the whole point of the
-  // one-source rule: a folder labelled Chart and the Chart view must not be two pictures.
-  grid: MODE_SHAPES.grid,
-  chart: MODE_SHAPES.dashboard,
-  map: MODE_SHAPES.map,
-  users: TYPE_SHAPES.user,
-  clock: TYPE_SHAPES.created_time,
-  heart: [{ d: "M8 13.1S2.7 9.8 2.7 6.4a2.9 2.9 0 0 1 5.3-1.6 2.9 2.9 0 0 1 5.3 1.6c0 3.4-5.3 6.7-5.3 6.7z" }],
-  bolt: [{ d: "M9.1 2.4L4.2 9.1h3.3l-.6 4.5 4.9-6.7H8.5z" }],
-};
-
-/**
- * Tone key → the pastel it FILLS with, and the -d weight it STROKES with.
- *
- * Both, not one: a folder mark is a ~14px glyph, and [[loopable-brand-palette]] is explicit
- * that a base pastel at that size smudges — LP_BLUE measures 1.88:1 on white. So the pastel
- * is the fill (a tinted body reads as "coloured") and the measured -deep variant carries the
- * outline (an outline that reads at all).
- *
- * The default tone is `neutral` — HOST's C5 key, not "grey". The whitelist is SHARED between
- * the two ends, so the name matters more than the word: a tone the host does not recognise
- * degrades to the default and the user's choice silently disappears on reload.
- */
+// ---------------------------------------------------------------------------
+// customer-grid / iconShapes.ts
+// Wave-8 items I18 + I20 — ONE geometry source for the grid's icon vocabulary,
+// rendered by TWO very different painters:
+//
+//   - React  <FieldTypeIcon> / <ModeIcon>  — DOM svg in panels, popovers, menus
+//   - glide  headerIcons sprites           — canvas, drawn from an SVG *string*
+//
+// Glide's sprite API takes a function returning SVG SOURCE, so a header icon can
+// never be a React component. Keeping the paths as DATA (IconShape[]) and giving
+// each painter its own thin renderer is what stops the two from drifting — the
+// alternative (hand-copying every path into a template literal) guarantees the
+// header and the panel eventually disagree about what a "date" looks like.
+//
+// Geometry rules: 16x16 viewBox, stroke-based, 1.35 stroke, round caps/joins,
+// currentColor. Vector paths only — NEVER emoji (owner constant).
+// ---------------------------------------------------------------------------
+
+import type { AggName, DisplayMode, FieldType, FolderShape, FolderTone } from "./types";
+import {
+  LP_BLUE,
+  LP_BLUE_DEEP,
+  LP_GREEN,
+  LP_GREEN_DEEP,
+  LP_LINE,
+  LP_MUTED,
+  LP_RED,
+  LP_RED_DEEP,
+  LP_YELLOW,
+  LP_YELLOW_DEEP,
+} from "./theme";
+
+/** One drawing primitive. `fill: true` fills the path instead of stroking it
+ *  (the rating star is the only shape that reads better solid). */
+export type IconShape = { d: string; fill?: boolean };
+
+/** A circle as a path — two half-arcs. Sprites are SVG *source*, so every shape
+ *  has to survive being serialized into a string; paths do, <circle> elements
+ *  would need a second serializer branch for no benefit. */
+const circle = (cx: number, cy: number, r: number): string =>
+  `M${cx - r} ${cy}a${r} ${r} 0 1 0 ${r * 2} 0a${r} ${r} 0 1 0 ${-r * 2} 0`;
+
+const CALENDAR: IconShape[] = [
+  { d: "M3.2 4.6h9.6v8.2H3.2z" },
+  { d: "M3.2 7.2h9.6" },
+  { d: "M5.8 3v3.2" },
+  { d: "M10.2 3v3.2" },
+];
+
+/**
+ * Field type → icon geometry. A TOTAL record on purpose: adding a FieldType
+ * without an icon is a compile error, not a silently blank header.
+ */
+export const TYPE_SHAPES: Record<FieldType, IconShape[]> = {
+  text: [{ d: "M3 5h10M3 8h10M3 11h6" }],
+  status: [{ d: "M4 13V3.5h7.6L10.1 6l1.5 2.5H4" }],
+  currency: [
+    { d: "M8 2.8v10.4" },
+    { d: "M10.6 5.4A2.6 2.6 0 0 0 8.2 4.2H7.4a2 2 0 0 0 0 4h1.2a2 2 0 0 1 0 4H7.8a2.6 2.6 0 0 1-2.4-1.4" },
+  ],
+  int: [{ d: "M6.2 3L4.8 13M11.2 3l-1.4 10M3.4 6.2h9.2M2.9 9.8h9.2" }],
+  date: CALENDAR,
+  pct: [
+    { d: circle(4.6, 4.6, 1.6) },
+    { d: circle(11.4, 11.4, 1.6) },
+    { d: "M12.2 3.9L3.8 12.3" },
+  ],
+  select: [{ d: "M3.2 3.8h9.6v8.4H3.2z" }, { d: "M6.2 7.2l1.8 1.8 1.8-1.8" }],
+  user: [
+    { d: circle(8, 6, 2.4) },
+    { d: "M3.6 13c0-2.4 2-3.8 4.4-3.8s4.4 1.4 4.4 3.8" },
+  ],
+  multiselect: [
+    { d: "M3 4.6h2.2v2.2H3zM3 9.2h2.2v2.2H3z" },
+    { d: "M7.2 5.7h6M7.2 10.3h6" },
+  ],
+  checkbox: [{ d: "M3.4 3.4h9.2v9.2H3.4z" }, { d: "M5.8 8.1l1.8 1.9 3.4-3.9" }],
+  phone: [
+    { d: "M5.1 3.2L7 5.1 5.6 7a7.2 7.2 0 0 0 3.4 3.4l1.9-1.4 1.9 1.9-1.5 1.6c-3 .5-8.3-4.8-7.8-7.8z" },
+  ],
+  email: [{ d: "M3 4.4h10v7.2H3z" }, { d: "M3 4.9l5 3.9 5-3.9" }],
+  url: [
+    { d: "M7 5.4L8.4 4a2.6 2.6 0 0 1 3.7 3.7L10.7 9" },
+    { d: "M9 10.6L7.6 12a2.6 2.6 0 0 1-3.7-3.7L5.3 7" },
+    { d: "M6.2 9.8l3.6-3.6" },
+  ],
+  rating: [
+    {
+      d: "M8 2.9l1.63 3.3 3.64.53-2.63 2.57.62 3.63L8 11.24 4.74 12.93l.62-3.63L2.73 6.73l3.64-.53z",
+      fill: true,
+    },
+  ],
+  created_time: [{ d: circle(8, 8, 5.2) }, { d: "M8 4.9v3.4l2.3 1.4" }],
+  formula: [
+    { d: "M5.6 12.8V5.4a2 2 0 0 1 3.2-1.6" },
+    { d: "M4.2 7.6h4.6" },
+    { d: "M10.2 8.4l3 3.4M13.2 8.4l-3 3.4" },
+  ],
+  // Wave-18 C5-AUTOFIELD (D's spec, applied by C as client-vocab registrar). A 290° cycle ring
+  // with an arrowhead, wrapped around a solid run-triangle: a job that runs, repeatedly.
+  // Deliberately NOT a bolt (`FOLDER_SHAPE_PATHS.bolt` already means "Priority") and not a clock
+  // (`created_time` owns the closed rim + hands).
+  automation: [
+    { d: "M10.8 4.1A4.8 4.8 0 1 1 5.3 4.1" },
+    { d: "M4.2 6L5.3 4.1 3.1 4.5" },
+    { d: "M6.9 6.1L9.8 8 6.9 9.9z", fill: true },
+  ],
+  // Wave-22 C7 (added by C as client-vocab registrar, the W18 automation precedent). A rising
+  // series on an axis: a measure OVER TIME, which is what a metric field is. Deliberately not
+  // the formula fx (that computes over the ROW) and not a bare number (int owns ##).
+  metric: [
+    { d: "M3.2 3.2v9.6h9.6" },
+    { d: "M5 10.4l2.4-2.6 1.9 1.5 3.1-3.9" },
+  ],
+  // Wave-23 C7 — TWO BRACES facing each other with a dot between them: the universal mark for
+  // "a structured document", and the one glyph in this table that draws its own SYNTAX rather
+  // than a picture of what the value means. Deliberately not a document page (nothing here owns
+  // that yet, but a page reads as a file/attachment, which a json cell is not) and not a tree
+  // of nodes (too fine to survive 16px). The centre dot is what keeps the two braces from
+  // reading as parentheses at small sizes.
+  json: [
+    { d: "M6.4 3.2c-1.5 0-1.5 3.4-1.5 3.4S4.8 8 3.4 8s1.5 1.4 1.5 1.4 0 3.4 1.5 3.4" },
+    { d: "M9.6 3.2c1.5 0 1.5 3.4 1.5 3.4s.1 1.4 1.5 1.4-1.5 1.4-1.5 1.4 0 3.4-1.5 3.4" },
+    { d: circle(8, 8, 0.85), fill: true },
+  ],
+  // ⭐ Wave-27 item 13 (R13) — THE ANGLE BRACKETS, the mark every editor on earth uses for
+  // "this is source". Drawn as two chevrons with a slash leaning between them, which is what
+  // separates it from `json` two entries up: json draws BRACES (a document's own syntax), code
+  // draws BRACKETS (a snippet's). Deliberately not a terminal prompt (that reads as "run this",
+  // and R13 is explicit there is no execution engine) and not a page of lines (`list` mode and
+  // `text` already trade on that reading).
+  code: [
+    { d: "M5.6 4.9 2.6 8l3 3.1" },
+    { d: "M10.4 4.9 13.4 8l-3 3.1" },
+    { d: "M9.1 3.6 6.9 12.4" },
+  ],
+  // Wave-19 R7 — a framed picture: the mount, a sun, and the hill line every photo glyph
+  // resolves to at 16px. Drawn on the same 16-unit grid as its neighbours.
+  image: [
+    { d: "M2.6 3.4h10.8v9.2H2.6z" },
+    { d: circle(6, 6.3, 1.1) },
+    { d: "M2.6 10.6L6.1 7.6l2.5 2.1 2.2-1.8 2.6 2.2" },
+  ],
+  // ⭐ 2026-08-07 — TWO INTERLOCKING CHAIN LINKS, the one glyph everybody already reads as
+  // "this points at something else". Drawn as two rounded rectangles overlapping at the centre
+  // rather than as an arrow into a box: an arrow would mean navigation, and a link column is a
+  // relation that exists in both directions whether or not you follow it.
+  link: [
+    { d: "M6.6 5.2H4.9a2.8 2.8 0 000 5.6h1.7" },
+    { d: "M9.4 5.2h1.7a2.8 2.8 0 010 5.6H9.4" },
+    { d: "M5.6 8h4.8" },
+  ],
+  // ⭐ 2026-08-07 — THREE BARS FOLDING INTO ONE, read top-to-bottom: many linked values
+  // collapsing to a single aggregate. Deliberately not a sigma (too fine at 16px, and it would
+  // claim SUM when the function is chosen per column) and not a funnel (that is filtering,
+  // which is what `limit` does — a different half of the same field).
+  rollup: [
+    { d: "M3.2 4.4h9.6" },
+    { d: "M4.8 8h6.4" },
+    { d: "M6.6 11.6h2.8" },
+  ],
+  // ⭐ WAVE 34 · T53 (R13), drawn by C on F's ask (`F-2`) — AI ENRICHMENT.
+  // The SPARKLE, because it is the product's own AI mark already: `Shell.tsx::SparkIcon` wears it
+  // on the Assistant rail row, so a column the AI fills reads as the same family rather than as a
+  // second vocabulary for one idea. Deliberately NOT the `automation` cycle-ring two entries up
+  // (that means "a job that runs, repeatedly", and an enrichment can be manual) and not a robot
+  // head (`Shell.tsx::RobotIcon` claims that for the Agents MODULE; a field is not a module).
+  // ⚠ TWO stars, not one: a lone four-point star at 16px with a 1.35 stroke reads as a plus sign.
+  // The small companion is what makes the mark say "sparkle".
+  ai_enrich: [
+    { d: "M6.6 2.6l1.3 3.1 3.1 1.3-3.1 1.3-1.3 3.1-1.3-3.1L2.2 7l3.1-1.3z" },
+    { d: "M11.9 9.8l.7 1.6 1.6.7-1.6.7-.7 1.6-.7-1.6-1.6-.7 1.6-.7z" },
+  ],
+};
+
+/**
+ * Display mode → icon geometry (I18). Also total: the wave-8 Dashboard mode
+ * cannot land in DISPLAY_MODES without the compiler demanding its icon here.
+ */
+export const MODE_SHAPES: Record<DisplayMode, IconShape[]> = {
+  grid: [
+    { d: "M2.6 3.4h10.8v9.2H2.6z" },
+    { d: "M2.6 6.5h10.8M2.6 9.5h10.8M6.4 3.4v9.2M10 3.4v9.2" },
+  ],
+  list: [{ d: "M3 4.6h1.4M6.4 4.6h6.6M3 8h1.4M6.4 8h6.6M3 11.4h1.4M6.4 11.4h6.6" }],
+  // I19c — a framed set of bars: "several charts", not "one chart".
+  chart: [
+    { d: "M2.6 3.4h10.8v9.2H2.6z" },
+    { d: "M5.4 10.6V7.2M8 10.6V5.4M10.6 10.6V8.6" },
+  ],
+  // I10 (C2) — the LEGACY key. Kept so this record stays total over DisplayMode, which is
+  // what makes "accept 'dashboard' on read forever" a compile-time guarantee rather than a
+  // promise. Same drawing: a stored 'dashboard' IS a chart.
+  dashboard: [
+    { d: "M2.6 3.4h10.8v9.2H2.6z" },
+    { d: "M5.4 10.6V7.2M8 10.6V5.4M10.6 10.6V8.6" },
+  ],
+  calendar: CALENDAR,
+  kanban: [{ d: "M2.8 3.4h3.1v9.2H2.8zM6.5 3.4h3.1v6.2H6.5zM10.2 3.4h3.1v7.6h-3.1z" }],
+  map: [
+    { d: "M8 2.6a3.6 3.6 0 0 1 3.6 3.6c0 2.7-3.6 7.2-3.6 7.2S4.4 8.9 4.4 6.2A3.6 3.6 0 0 1 8 2.6z" },
+    { d: circle(8, 6.1, 1.3) },
+  ],
+  // 2026-08-02 item 7 — the time-series view. Drawn as a framed grid with a trend running
+  // through it, because that is literally what the panel is: metric ROWS x bucket COLUMNS with
+  // a per-row line toggle. Deliberately not the plain `line` chart mark — a chart view and a
+  // time-series table must not be the same picture in the same rail.
+  timeseries: [
+    { d: "M2.6 3.4h10.8v9.2H2.6z" },
+    { d: "M2.6 6.6h10.8M6.2 3.4v9.2" },
+    { d: "M7.2 10.8l2-2.4 1.6 1.2 1.8-2.6" },
+  ],
+  // Wave-18 C6-CATALOG — an OPEN BOOK: two facing leaves with a spine between them, and a
+  // product block sitting on the left one. Every other mode in this table draws a way of
+  // arranging RECORDS; this one has to read as a printed artifact, so it is the only mark here
+  // with a spine and a gutter. Deliberately not a page-with-lines (`list` owns that reading) and
+  // not a framed grid (`grid`/`chart`/`timeseries` share the frame).
+  catalog: [
+    { d: "M2.4 4.2h4.6a1.6 1.6 0 0 1 1 .4l0 8a1.6 1.6 0 0 0-1-.4H2.4z" },
+    { d: "M13.6 4.2H9a1.6 1.6 0 0 0-1 .4l0 8a1.6 1.6 0 0 1 1-.4h4.6z" },
+    { d: "M3.9 6.4h2.3v2.8H3.9z" },
+  ],
+  // Wave-23 C9 — a SHEET WITH A WRITING LINE: two filled answer bars and an empty rule beneath
+  // them. Every other mode here draws a way of ARRANGING records that already exist; this one
+  // has to read as a record being MADE, so it is the only mark whose bottom line is open.
+  // Deliberately not a clipboard (nothing else here has a frame with a tab) and not a pencil
+  // (an edit affordance means something else app-wide).
+  // ⭐ Wave-27 C3 (owner item 8) — a CARD WITH TWO ARROWS LEAVING IT, left and right. Every
+  // other mark here draws an arrangement of many records; this one has to read as ONE record
+  // with two exits, because that is exactly what the deck is. Deliberately not a stack of cards
+  // (that is a lane, and `kanban` owns it) and not a hand or a gesture glyph (nothing else in
+  // this vocabulary draws a body part, and it would read as "drag" rather than "decide").
+  swipe: [
+    { d: "M5.4 3.4h5.2v9.2H5.4z" },
+    { d: "M3.6 8H1.4M2.8 6.8 1.4 8l1.4 1.2" },
+    { d: "M12.4 8h2.2M13.2 6.8 14.6 8l-1.4 1.2" },
+  ],
+  form: [
+    { d: "M3.4 2.8h9.2v10.4H3.4z" },
+    { d: "M5.6 5.6h4.8" },
+    { d: "M5.6 8h4.8" },
+    { d: "M5.6 10.6h2.6" },
+  ],
+  // W36-T04 — angle brackets over a baseline: the universal mark for "this is code", and the one
+  // shape in this table that is about the AUTHORING rather than about the arrangement of rows.
+  script: [
+    { d: "M6 5.4 3.2 8l2.8 2.6M10 5.4 12.8 8 10 10.6" },
+    { d: "M2.6 3.4h10.8v9.2H2.6z" },
+  ],
+};
+
+/**
+ * Wave-9 I16 — one mark per CHART KIND. Total over `ChartKind`, so a kind added to C2's
+ * vocabulary cannot ship without a drawing.
+ *
+ * ⚠ The owner asked for an icon on every chart-type option, and the wave-8 ruling stands:
+ * an `<option>` cannot render SVG and unicode glyphs are gate-banned, so the chart-type
+ * picker is NOT a native `<select>` — it is a radio-row list like the mode switcher, which
+ * is the only shape that can carry a real mark.
+ *
+ * The key type is a string union declared here rather than imported from chartData.ts: this
+ * module is a leaf (types + theme only) and chartData imports IT, not the reverse.
+ */
+export type ChartKindKey = "bar" | "line" | "area" | "donut" | "kpi" | "table";
+export const CHART_KIND_SHAPES: Record<ChartKindKey, IconShape[]> = {
+  bar: [{ d: "M3.2 12.8V7.4M6.4 12.8V4.2M9.6 12.8V8.8M12.8 12.8V5.8" }],
+  line: [
+    { d: "M2.6 11.2l3.2-3.4 2.6 2 4.9-5.2" },
+    { d: circle(5.8, 7.8, 0.9) },
+    { d: circle(8.4, 9.8, 0.9) },
+  ],
+  area: [
+    { d: "M2.6 12.4V9.2l3.2-3.2 2.6 2 4.9-4.6v9z" },
+    { d: "M2.6 9.2l3.2-3.2 2.6 2 4.9-4.6" },
+  ],
+  donut: [{ d: circle(8, 8, 5) }, { d: circle(8, 8, 2.1) }],
+  // A single big number: the KPI card. Drawn as a framed value rather than a glyph, so it
+  // reads as "one number" beside four marks that all read as "a distribution".
+  kpi: [{ d: "M2.6 3.8h10.8v8.4H2.6z" }, { d: "M5.4 9.6V6.4l1.9 3.2V6.4M9.4 6.4v3.2h1.8" }],
+  // Wave-16 C-CHARTCAP: a group-by aggregate table. Framed like the KPI (it is a card of
+  // values, not a distribution), with a header band and a column rule.
+  table: [
+    { d: "M2.6 3.4h10.8v9.2H2.6z" },
+    { d: "M2.6 6.2h10.8M7.2 6.2v6.4M2.6 9.4h10.8" },
+  ],
+};
+
+export const CHART_KIND_LABELS: Record<ChartKindKey, string> = {
+  bar: "Bar",
+  line: "Line",
+  area: "Area",
+  donut: "Donut",
+  kpi: "Single value",
+  table: "Table",
+};
+
+/** I16 — the pastel each chart kind wears, same family rule as MODE_TONE. */
+export const CHART_KIND_TONE: Record<ChartKindKey, FolderTone> = {
+  bar: "blue",
+  line: "green",
+  area: "green",
+  donut: "yellow",
+  kpi: "neutral",
+  table: "neutral",
+};
+
+/**
+ * Wave-9 contract C5 (I15) — folder icon geometry. TOTAL over `FolderShape`, so a shape key
+ * added to the wire contract in types.ts cannot ship without a drawing.
+ *
+ * Same 16x16 stroke vocabulary as everything above: these have to sit beside a mode icon in
+ * the same rail and read as one family. `folder` is first because it is the default every
+ * pre-wave-9 folder falls back to (I14: "existing folders get the folder icon").
+ */
+export const FOLDER_SHAPE_PATHS: Record<FolderShape, IconShape[]> = {
+  folder: [{ d: "M2.4 12.6V4.2a.6.6 0 0 1 .6-.6h3.2l1.5 1.7h5.3a.6.6 0 0 1 .6.6v6.7a.6.6 0 0 1-.6.6H3a.6.6 0 0 1-.6-.6z" }],
+  star: [
+    { d: "M8 2.9l1.63 3.3 3.64.53-2.63 2.57.62 3.63L8 11.24 4.74 12.93l.62-3.63L2.73 6.73l3.64-.53z" },
+  ],
+  flag: [
+    { d: "M4.2 13.4V2.9" },
+    { d: "M4.2 3.4h7.6l-1.5 2.6 1.5 2.6H4.2z" },
+  ],
+  tag: [
+    { d: "M2.9 8.2V3.5a.6.6 0 0 1 .6-.6h4.7l5 5-5.3 5.3z" },
+    { d: circle(5.6, 5.6, 1) },
+  ],
+  bookmark: [{ d: "M4.4 2.9h7.2v10.4L8 10.7l-3.6 2.6z" }],
+  // Four of the host's shapes ALREADY exist in this file as a mode or a field-type mark.
+  // Reusing the geometry rather than drawing a second "chart" is the whole point of the
+  // one-source rule: a folder labelled Chart and the Chart view must not be two pictures.
+  grid: MODE_SHAPES.grid,
+  chart: MODE_SHAPES.dashboard,
+  map: MODE_SHAPES.map,
+  users: TYPE_SHAPES.user,
+  clock: TYPE_SHAPES.created_time,
+  heart: [{ d: "M8 13.1S2.7 9.8 2.7 6.4a2.9 2.9 0 0 1 5.3-1.6 2.9 2.9 0 0 1 5.3 1.6c0 3.4-5.3 6.7-5.3 6.7z" }],
+  bolt: [{ d: "M9.1 2.4L4.2 9.1h3.3l-.6 4.5 4.9-6.7H8.5z" }],
+};
+
+/**
+ * Tone key → the pastel it FILLS with, and the -d weight it STROKES with.
+ *
+ * Both, not one: a folder mark is a ~14px glyph, and [[loopable-brand-palette]] is explicit
+ * that a base pastel at that size smudges — LP_BLUE measures 1.88:1 on white. So the pastel
+ * is the fill (a tinted body reads as "coloured") and the measured -deep variant carries the
+ * outline (an outline that reads at all).
+ *
+ * The default tone is `neutral` — HOST's C5 key, not "grey". The whitelist is SHARED between
+ * the two ends, so the name matters more than the word: a tone the host does not recognise
+ * degrades to the default and the user's choice silently disappears on reload.
+ */
 export const FOLDER_TONE_PAINT: Record<FolderTone, { fill: string; stroke: string }> = {
   neutral: { fill: LP_LINE, stroke: LP_MUTED },
   blue: { fill: LP_BLUE, stroke: LP_BLUE_DEEP },
@@ -368,456 +368,491 @@ export function folderTonePaint(tone: unknown): { fill: string; stroke: string }
   return (typeof tone === "string" ? FOLDER_TONE_PAINT[tone as FolderTone] : undefined)
     ?? FOLDER_TONE_PAINT.neutral;
 }
-
-export const FOLDER_TONE_LABELS: Record<FolderTone, string> = {
-  neutral: "Neutral",
-  blue: "Blue",
-  green: "Green",
-  yellow: "Yellow",
-  red: "Red",
-};
-
-export const FOLDER_SHAPE_LABELS: Record<FolderShape, string> = {
-  folder: "Folder",
-  star: "Star",
-  flag: "Flag",
-  tag: "Tag",
-  bookmark: "Bookmark",
-  grid: "Table",
-  chart: "Chart",
-  map: "Map",
-  users: "People",
-  clock: "Clock",
-  heart: "Heart",
-  bolt: "Priority",
-};
-
-/**
- * Wave-9 I14 — the tone each CREATABLE view type wears in the "+ Create new…" flyout.
- *
- * The owner asked for "pastel-coloured icons", and a flyout where every row is the same grey
- * is a list you read rather than scan. Assigned by family, not by rotation: the two
- * record-shaped modes (grid/list) share blue, the two time-shaped ones (calendar/kanban)
- * share yellow, chart is green because it is the analytical one, map is red because it is
- * the geographic one. Folder is grey — it is not a view, and the flyout's last row should
- * not compete with the six above it.
- */
-/**
- * Human labels for every display mode. Moved here from viewModes.tsx in wave 9 so the label
- * sits beside the geometry, the way TYPE_LABELS does — the mode switcher, the create flyout
- * and the create prompt now read ONE table instead of three. C2's "Dashboard" → "Chart"
- * rename is a single line here as a direct result.
- */
-export const MODE_LABELS: Record<DisplayMode, string> = {
-  grid: "Grid",
-  chart: "Chart",
-  // Legacy: never OFFERED (it is not in CREATABLE_MODES) but still labelled, because a view
-  // read before normalisation must never render a blank switcher chip.
-  dashboard: "Chart",
-  list: "List",
-  calendar: "Calendar",
-  kanban: "Kanban",
-  map: "Map",
-  timeseries: "Time series",
-  catalog: "Catalog",
-  // Wave-23 C9 — the mode that COLLECTS records. "Form", the word the whole product uses for
-  // it (the public page, the share panel, the `form_submitted` trigger); a synonym here would
-  // be the one surface calling it something else.
-  form: "Form",
-  // ⭐ Wave-27 C3 (item 8) — the owner's own word for it. Not "Triage" or "Review": the gesture
-  // IS the name here, and the two candidates both collide with vocabulary this product already
-  // spends elsewhere (a `review` automation decision, the retired review lanes).
-  swipe: "Swipe",
-  // W36-T04 — the owner's own words are "code script"; "Script" is the half that is not implied
-  // by the icon, and the product has no other surface competing for the noun.
-  //
-  // ⭐⭐ W37-T41 (owner ruling, 2026-08-19) — RENAMED TO "Custom", and the one-word form is the
-  // ruling rather than a shortening of it. Every wave-37 governing text calls this surface the
-  // "Custom View": PRD items 10 / R2, T41's own `done-when`, D-391, and `ScriptViewPanel`'s
-  // shipped copy ("Picking Custom View mints a view with an EMPTY source"). "Script" was the
-  // product calling one thing two names, which is the defect `swipe`'s label note warns about
-  // one table up.
-  //
-  // ⛔ IT IS NOT SPELLED "Custom View" HERE, and the reason is this table's job rather than a
-  // preference. Every value is a KIND NOUN that four call sites COMPOSE into a phrase:
-  // `ViewSidebar` renders `New ${MODE_LABELS[creating].toLowerCase()} view` (:1060), the same
-  // string as the flyout's aria-label (:1045), `${MODE_LABELS[mode]} view, locked` (:1619) and
-  // `It also stays a ${MODE_LABELS[mode].toLowerCase()}.` (:1626). A label already carrying the
-  // noun reads "New custom view view" at two of them. One word keeps the create prompt reading
-  // "New custom view", the locked aria-label reading "Custom view, locked", and the picker row
-  // reading "Custom" beside Grid, Chart and Map, which are kind nouns too.
-  script: "Custom",
-};
-
-/**
- * I14 — the view types the "+ Create new…" flyout OFFERS, in the order it lists them.
- *
- * Deliberately NOT `DISPLAY_MODES`, and deliberately here rather than inside ViewSidebar.tsx:
- * C2 makes `'dashboard'` a mode that stays READABLE forever (every view saved before the
- * rename sits in it) while ceasing to be OFFERABLE once `'chart'` exists — one list cannot
- * express both. Living in this pure data module means the gate can assert the offered set
- * without importing a React component, and I10 becomes a one-line edit in one file.
- */
-// 2026-08-02 item 7 — `timeseries` was deliberately held OUT of this list until the host
-// accepted the name, because a mode may be READABLE before it is OFFERABLE (the same split C2
-// wrote for 'dashboard', running forwards): `aios_grid._clean_display` drops a mode it does
-// not know, so offering it early would let a user create a view that silently reverts to a
-// grid on the next read with nothing going red. HOST posted "ACCEPTANCE LANDED" with
-// `DISPLAY_MODES += timeseries`, so it is offerable now.
-//
-// wave17 GRID, owner item 10 — THE ORDER BELOW IS THE OWNER'S, stated verbatim:
-// Grid · Chart · Calendar · Kanban · Time series · Map · List.
-//
-// ⚠ It supersedes the two orderings this list has carried before it, and the reasoning that
-// produced them is now WRONG rather than merely outranked, so it is not left here to be
-// re-applied: `timeseries` was "listed last… it belongs beside Chart", and `list` sat second
-// as the other record-shaped mode. The owner put Time series FIFTH and List LAST. An order is
-// a product decision, so it is asserted in `verify_icons` rather than left to a comment —
-// nothing else on screen would go red if a future edit re-sorted it "sensibly".
-// Wave-18 C6-CATALOG — `catalog` was held out of this list until `aios_grid.DISPLAY_MODES`
-// accepted the name, the same hold `timeseries` and `chart` served before it. SESSION A posted
-// "C6 HOST MIRROR APPLIED — you may flip CREATABLE_MODES now" (2026-08-03), so it is offerable.
-// It lands LAST by contract: the owner's seven-mode order above is a product decision and the
-// new mode joins the end of it rather than being sorted into it.
-// ⭐ Wave-27 C3 (owner item 8) — `swipe` is HELD OUT of this list, and the reason corrects a
-// mistake this file made an hour earlier.
-//
-// ⛔ THE HOLD WAS NEVER ONLY ABOUT THE TWO REGISTRIES. It was first written as "do not offer a
-// mode the HOST has not accepted", and one session owning both registries this wave genuinely
-// does close that half — which is what made it tempting to skip. But the rule the hold really
-// encodes is broader and this wave proved it: **do not offer a mode whose CONSUMER does not
-// exist.** `swipe` was briefly listed here while `CustomerGrid`'s mode dispatch had no branch
-// for it, so picking "Swipe" wrote a mode the host now happily PERSISTS, and the body rendered
-// a grid under a chip reading "View · Swipe" — surviving reload, with the agreement leg green
-// because it only ever compared two lists.
-//
-// So the hold stood until `SwipeView` was mounted (contract C3), and it was not a mailbox
-// handshake: `verify_icons` DERIVES the condition — either `swipe` is absent here, or
-// `CustomerGrid.tsx` mounts `SwipeView`. `form` (wave-23) is the same defect from the other
-// direction, sitting unoffered because its host mirror never landed (DEBT D-90).
-//
-// ⛔ THE HOLD OUTLIVED THE WAVE, AND THAT IS THE LESSON WORTH MORE THAN THE FEATURE.
-// Wave 27 closed with the mount NEVER LANDING. `SwipeView.tsx` shipped, the server accepted
-// `swipe`, all four maps above carried it, 50 gates were green, the wave-27 mailbox recorded
-// "RESOLVED BY C (swipe mounted)", the close-out booked D-102 — a negative control FOR the
-// swipe carry — and the owner could not find the view because **nothing imported the file.**
-// The derived gate could not catch it: its condition is a DISJUNCTION and **absence satisfies
-// it**, so the unshipped state was permanently green ([[gate-can-report-green-on-nothing]]).
-// A hold that is safe to leave in place is a hold nothing forces you to lift.
-// The audit query that found it, after the battery did not: for each artifact a wave adds, grep
-// for its CONSUMER — who imports/mounts/registers it — excluding the file itself, `_test/`, css
-// and comments. `SwipeView` had four hits and three were prose.
-// Mounted 2026-08-09 (`CustomerGrid.tsx`, `displayMode === "swipe"`), so `swipe` is offerable.
-// It lands LAST, by `catalog`'s rule: the owner's mode order is a product decision and a new
-// mode joins the end of it rather than being sorted into it.
-export const CREATABLE_MODES: DisplayMode[] = [
-  "grid",
-  "chart",
-  "calendar",
-  "kanban",
-  "timeseries",
-  "map",
-  "list",
-  "catalog",
-  "swipe",
-  // Mounted 2026-08-11 (`CustomerGrid.tsx`, `displayMode === "form"` renders `FormInterface`), so
-  // `form` is offerable and its `HELD_MODES` entry came out in the same edit — the hold's own text
-  // named this mount as its release condition. ⚠ Found by `verify_icons.py::mode_parity` law E
-  // during /validate-wave, NOT by the lane that mounted it: T29 mounted the component and T41 built
-  // the Interface group, and between them the DOOR was never opened — the wave's biggest new
-  // surface was unreachable behind two green tickets.
-  "form",
-  // ⭐⭐ W37-T41 (owner item 10 / R2) — `script` JOINS THE OFFER, and this is the release of the
-  // longest-held entry in this file. The hold's own release condition, written into
-  // `icons.test.ts::HELD_MODES`, named THREE things that had to land in one change: the name
-  // joins this list, `CustomerGrid.tsx` gains a `displayMode === "script"` branch, and the
-  // HELD_MODES entry comes out. All three are in this change.
-  //
-  // ⛔ AND A FOURTH THAT THE HOLD DID NOT NAME, which is the one that decides whether the
-  // feature works: `CustomerGrid.tsx::createView` had to learn that picking this mode mints a
-  // SCRIPT VIEW through `createScriptView` rather than persisting a workspace view. A script
-  // view is not a workspace view (it is its source and its version history, in E's own
-  // per-database store), so the three hops above alone would have offered the mode, written
-  // `config.display.mode = "script"` into a stored view, left `activeScriptId` null and drawn
-  // nothing, with `mode_parity` GREEN. That is wave 27's `swipe` defect exactly, reached
-  // through a different door.
-  // ⚠ OFFERED ONLY WHERE IT CAN EXIST. `ViewSidebar` takes `scriptable` and drops this row
-  // when it is false: script views are listed and resolved only on `ut_*` databases
-  // (`CustomerGrid`'s `scriptRows` effect gates on `hostWorkspace && isUserTable`), so offering
-  // it on a pool scope would mint a view the rail can never show
-  // ([[permitted-is-not-answerable]]). It lands LAST by `catalog`'s rule.
-  "script",
-];
-
-/**
- * ⭐ WAVE-29 R6 (owner item 10) — the kind dropdown splits under TWO headers, and the strings are
- * the owner's own: exactly `View` and `Interface`. Not "View as" (what the popover said before),
- * not "Custom interface".
- *
- * The line the two groups draw: a **View** ARRANGES the records — the same rows, re-shaped (a
- * grid, a board, a chart). An **Interface** is a SURFACE BUILT OVER them: a map is a picture of the
- * world with records placed on it, a catalog is a published artifact, a form is a door records come
- * IN through and shows no records at all.
- *
- * ⭐ WAVE-33 item 9 AMENDED THAT LINE, and the owner drew it one notch differently than R6 did:
- * `swipe` and `timeseries` moved from View to Interface. The reading that makes both rulings one
- * rule — and the one the next mode should be grouped by — is **what the surface is FOR**, not how
- * many rows it shows. A deck triages records one at a time and WRITES to them; a trend answers a
- * question about a measure over time; neither hands you the row set re-shaped, which is what every
- * remaining View does. ⚠ Do NOT re-derive the split from `MODE_TONE` below: the tones still say
- * `catalog`/`form` are neutral because they arrange nothing, and `swipe`/`timeseries` are toned,
- * so tone and group are no longer the same cut. Group membership lives HERE and only here.
- *
- * ⚠ TOTAL over `DisplayMode`, so tsc refuses a new mode with no group rather than letting it
- * vanish from the dropdown: membership is derived by FILTERING `CREATABLE_MODES` through this
- * map, and a mode whose group label matched nothing would silently stop being offered while
- * every existing check (paintable, labelled, toned, unique, ordered) stayed green.
- * `dashboard` is grouped like the `chart` it is the legacy spelling of — it is never offered, and
- * a partial map is a worse answer than an unused entry.
- */
-export const MODE_GROUP_LABELS = ["View", "Interface"] as const;
-export type ModeGroup = (typeof MODE_GROUP_LABELS)[number];
-
-export const MODE_GROUP: Record<DisplayMode, ModeGroup> = {
-  grid: "View",
-  list: "View",
-  kanban: "View",
-  calendar: "View",
-  chart: "View",
-  dashboard: "View",
-  // ⭐ WAVE-33 item 9 (owner, verbatim): "Let's move Swipe and Time-series under Interface instead
-  // of under View, when a user toggle it." See the amended taxonomy note above — a deck and a
-  // trend are both surfaces a person WORKS IN, not re-shapings of the row set.
-  timeseries: "Interface",
-  swipe: "Interface",
-  map: "Interface",
-  catalog: "Interface",
-  form: "Interface",
-  // W36-T04 — "Interface", by the W33 item-9 taxonomy: a script view is a surface somebody WORKS
-  // IN (writes, runs, reads an answer), not a re-shaping of the row set.
-  script: "Interface",
-};
-
-/**
- * The offered modes, split into R6's two groups — DERIVED, never a third hand-written list.
- *
- * ⚠ ORDER: R6 names each group's MEMBERS; the order inside a group stays `CREATABLE_MODES`', which
- * is the wave-17 owner ruling ("Grid · Chart · Calendar · Kanban · Time series · Map · List") and
- * is separately asserted. The two rulings are compatible read this way and only this way: R6 moved
- * `map` out of the run of views, so wave-17's single sequence can no longer exist as one list, but
- * every pair it ordered is still in that relative order here.
- */
-export const CREATABLE_GROUPS: readonly { label: ModeGroup; modes: DisplayMode[] }[] =
-  MODE_GROUP_LABELS.map((label) => ({
-    label,
-    modes: CREATABLE_MODES.filter((m) => MODE_GROUP[m] === label),
-  }));
-
-export const MODE_TONE: Record<DisplayMode, FolderTone> = {
-  grid: "blue",
-  list: "blue",
-  chart: "green",
-  dashboard: "green",
-  calendar: "yellow",
-  kanban: "yellow",
-  map: "red",
-  // Green with `chart`: it is the other analytical mode, and the two belong to one family.
-  timeseries: "green",
-  // Wave-18 C6-CATALOG — NEUTRAL, and it is the honest pick rather than the leftover one. The
-  // four colour tones each name a family of ways to arrange records (blue = tabular, green =
-  // analytical, yellow = board/date, red = spatial); a catalog arranges nothing — it is a
-  // published artifact. Giving it a colour would file it under a family it is not in.
-  catalog: "neutral",
-  // Wave-23 C9 — NEUTRAL, and for `catalog`'s reason rather than by elimination: the four tones
-  // name families of ways to ARRANGE records (blue tabular, green analytical, yellow
-  // board/date, red spatial). A form arranges nothing — it is a door records come in through —
-  // so giving it a colour would file it under a family it is not in.
-  form: "neutral",
-  // ⭐ Wave-27 C3 — YELLOW, with `kanban`, and this is a family claim rather than a leftover:
-  // a swipe deck writes the SAME single-select a kanban stacks by (R2 binds it to one), so the
-  // two are one family seen at two zooms — all the lanes at once, or one card at a time. Filing
-  // it neutral (the `catalog`/`form` reasoning) would be wrong for the opposite reason those
-  // two are neutral: this mode does arrange records, and it arranges them by the board's field.
-  swipe: "yellow",
-  // W36-T04 — NEUTRAL, by `catalog`'s and `form`'s rule rather than by elimination: the four
-  // tones name families of ways to ARRANGE records (blue tabular, green analytical, yellow
-  // board/date, red spatial). A script arranges nothing; it emits whatever it computes.
-  script: "neutral",
-};
-
-/**
- * Human labels for every field type. Lives here beside the icons so the two
- * halves of "how a field type presents itself" stay in one file (ColumnMenu
- * imports it rather than keeping a second copy).
- */
-export const TYPE_LABELS: Record<FieldType, string> = {
-  // ⭐ WAVE-29 item 3 — the owner's own words: "Change 'Single line text' to 'Text', keep it
-  // simple for the Field type". Airtable's phrase described the column's SHAPE (one line, versus
-  // its long-text sibling); this product has no multi-line text kind, so the qualifier
-  // distinguished the type from nothing and only made the commonest row in the menu the longest.
-  // ✅ The STORED key is `"text"` and always was — the old string was never persisted anywhere,
-  // client or server, so this is a label change with no migration behind it.
-  text: "Text",
-  select: "Single select",
-  multiselect: "Multi select",
-  user: "Assignee",
-  int: "Number",
-  currency: "Currency",
-  pct: "Percent",
-  date: "Date",
-  checkbox: "Checkbox",
-  phone: "Phone number",
-  email: "Email",
-  url: "URL",
-  rating: "Rating",
-  created_time: "Created time",
-  formula: "Formula",
-  // Wave-18 C5-AUTOFIELD (D's spec, applied by C).
-  automation: "Automation",
-  // Wave-22 C7 — spawned by automations (not in CREATABLE_TYPES), so this label mostly shows
-  // on headers and the field gear, not the create menu.
-  metric: "Metric",
-  // Wave-19 R7 — the picture column.
-  image: "Image",
-  // Wave-23 C7 — the structured-document column. "JSON" rather than "Structured data": it is
-  // the word on the wire, in the viewer's raw tab and in every error the server can return, and
-  // a friendlier synonym would be the only place in the product using a different one.
-  json: "JSON",
-  // ⭐ 2026-08-07 — Airtable's own wording, deliberately. "Link to another record" is what a
-  // person migrating from Airtable searches this menu for, and inventing a synonym ("Relation",
-  // "Reference") would make the feature they came for look absent.
-  link: "Link to another record",
-  rollup: "Rollup",
-  // ⭐ Wave-27 item 13 (R13) — "Code", not "Snippet" or "Source": it is the word the field kind
-  // is called everywhere else in this wave (the ruling, the language picker, the viewer header),
-  // and it says what the column holds without implying the product will run it.
-  code: "Code",
-  // ⭐ WAVE 34 · T53 (R13), on F's ask (`F-2`) — the owner's own noun for the kind: "a field kind
-  // called AI enrichment". Not "AI field" (every field in an AI-built view would qualify) and not
-  // "Generate" (that names the verb, and the column's value is the point, not the act).
-  ai_enrich: "AI enrichment",
-  status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
-};
-
-/**
- * ⭐ WAVE-29 C7 (item 17) — THE COLUMN-SUMMARY vocabulary: what a field's `agg` may be, which is
- * what the totals row and the per-group subtotals compute. Server twin:
- * `platform/aios_grid.py::FIELD_AGGS`, and `verify_icons.py::agg_parity` reads BOTH FILES and
- * compares them name-for-name in order — the cross-language boundary is the one a type cannot
- * police, so it gets a gate.
- *
- * ⛔ ONE CLIENT LIST, IMPORTED — never re-declared. `aggregations.ts` and the field editor import
- * from here rather than keeping their own copy, which is why this lives in the pure data module
- * beside `TYPE_LABELS` and `CREATABLE_MODES`: a second client list would need a second gate, and
- * the two would drift in the direction nobody is watching. C7 says "C publishes, E mirrors"; a
- * mirror that is an import cannot fall out of step at all.
- *
- * ⛔ NOT the chart vocabulary. `CHART_AGGS` (`aios_grid.py`, `viz/chartData.ts`) spells it `avg`
- * and gatekeeps a STORED value — renaming it would silently turn saved charts into sums. This
- * list spells it `average`, matching `ROLLUP_FNS` (16 names, live in production), so a column
- * summary and a rollup fold say the same word for the same operation.
- *
- * ⚠ `median` is net-new — in neither `CHART_AGGS` nor `ROLLUP_FNS`.
- * ⚠ `count` counts ROWS in the scope, not non-blank cells.
- * ⚠ Which types may carry which: `sum/average/median/min/max` are numeric-only and the evaluator
- * for that is ALREADY `isNumericFieldType` (types.ts) — do not write a second one. `count` is
- * legal on any type.
- */
-// ⭐ W29-T74 — an ALIAS of `types.AggName`, not a fifth copy of the union. `Field.agg` is typed
-// `AggName`, so a second literal here would be a type that has to be kept in step by eye with a
-// type the compiler already owns — the same defect as the array below, one level up.
-export type FieldAgg = AggName;
-
-/** ORDERED — the order is the picker's order, on both engines. */
-export const FIELD_AGGS: readonly FieldAgg[] = [
-  "sum",
-  "average",
-  "median",
-  "min",
-  "max",
-  "count",
-];
-
-/**
- * Human labels, in the summary bar's own compact register (Airtable's wording).
- *
- * ⚠ `FIELD_AGG_LABELS`, not `AGG_LABELS`, and the prefix is load-bearing: `viewModes.tsx` already
- * has a module-local `AGG_LABELS` for the CALENDAR summary picker over `CHART_AGGS`, where the
- * same five names wear different words ("Total", "Lowest", "Highest") for a day cell. Two tables
- * called `AGG_LABELS` describing two vocabularies is how a future import lands on the wrong one.
- */
-export const FIELD_AGG_LABELS: Record<FieldAgg, string> = {
-  sum: "Sum",
-  average: "Average",
-  median: "Median",
-  min: "Min",
-  max: "Max",
-  count: "Count",
-};
-
-
-// ------------------------------------------------------------ glide sprites
-
-/** Serialize one shape to SVG source in an explicit colour (canvas sprites get
- *  no `currentColor` — glide hands the painter the theme colours directly). */
-function shapeSource(s: IconShape, color: string): string {
-  return s.fill
-    ? `<path d="${s.d}" fill="${color}"/>`
-    : `<path d="${s.d}" fill="none" stroke="${color}" stroke-width="1.35" ` +
-        `stroke-linecap="round" stroke-linejoin="round"/>`;
-}
-
-function sprite(shapes: IconShape[]) {
-  return ({ fgColor }: { fgColor: string }) =>
-    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">` +
-    shapes.map((s) => shapeSource(s, fgColor)).join("") +
-    `</svg>`;
-}
-
-/** Glide header-icon NAME for a field type — the `icon` a GridColumn asks for. */
-export function typeIconName(type: FieldType): string {
-  return `t_${type}`;
-}
-
-/**
- * The sprite map handed to <DataEditor headerIcons>. One entry per field type
- * (I20 draws the type mark in every column header), built from the same shapes
- * the React icons use.
- *
- * Colour: glide's "normal" variant paints with `theme.fgIconHeader`, which is
- * why theme.ts must set it — the library default is #FFFFFF, i.e. invisible on
- * our header (that was I21's actual bug, not a too-pale hex of ours).
- */
-export const TYPE_SPRITES: Record<string, ({ fgColor }: { fgColor: string }) => string> =
-  Object.fromEntries(
-    (Object.keys(TYPE_SHAPES) as FieldType[]).map((t) => [typeIconName(t), sprite(TYPE_SHAPES[t])])
-  );
-
-/**
- * The header sprite map handed to <DataEditor headerIcons>. Two families:
- *
- *   t_<type>   wave-8 I20 - the field-TYPE mark, drawn in EVERY column header,
- *              from the same shapes the React icons use. Painted by glide in
- *              `theme.fgIconHeader`.
- *   aiosInfo   wave-5 item 6, restyled by wave-9 I3 - the description (i).
- *              OUTLINE ONLY: a dark-grey ring with a transparent interior, per
- *              the owner. It still deliberately IGNORES the colours glide hands
- *              it, for the reason wave-8 recorded - glide's "special" variant is
- *              accentColor behind bgHeader, which under the C1 pastels is a pale
- *              glyph on a pale disc, i.e. I21 in a new costume.
- *              ⚠ It is NO LONGER a column `overlayIcon`. Glide draws an overlay
- *              at a hard-coded offset from the TYPE mark on the far LEFT of the
- *              header (drawHeaderInner: `drawX + 9`), and I3 wants it RIGHT-
- *              aligned. It is now painted by CustomerGrid's `drawHeader`
- *              callback at `infoMarkRect()` - see overlayPlacement.ts.
- */
-export const HEADER_ICONS: Record<string, (c: { fgColor: string; bgColor: string }) => string> = {
-  ...TYPE_SPRITES,
-  aiosInfo: () =>
-    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">` +
-    `<circle cx="8" cy="8" r="6.1" fill="none" stroke="${LP_MUTED}" stroke-width="1.25"/>` +
-    `<path d="M8 7.4v3.5" fill="none" stroke="${LP_MUTED}" stroke-width="1.4" ` +
-    `stroke-linecap="round"/>` +
-    `<circle cx="8" cy="5.1" r="0.85" fill="${LP_MUTED}"/>` +
-    `</svg>`,
-};
+
+export const FOLDER_TONE_LABELS: Record<FolderTone, string> = {
+  neutral: "Neutral",
+  blue: "Blue",
+  green: "Green",
+  yellow: "Yellow",
+  red: "Red",
+};
+
+export const FOLDER_SHAPE_LABELS: Record<FolderShape, string> = {
+  folder: "Folder",
+  star: "Star",
+  flag: "Flag",
+  tag: "Tag",
+  bookmark: "Bookmark",
+  grid: "Table",
+  chart: "Chart",
+  map: "Map",
+  users: "People",
+  clock: "Clock",
+  heart: "Heart",
+  bolt: "Priority",
+};
+
+/**
+ * Wave-9 I14 — the tone each CREATABLE view type wears in the "+ Create new…" flyout.
+ *
+ * The owner asked for "pastel-coloured icons", and a flyout where every row is the same grey
+ * is a list you read rather than scan. Assigned by family, not by rotation: the two
+ * record-shaped modes (grid/list) share blue, the two time-shaped ones (calendar/kanban)
+ * share yellow, chart is green because it is the analytical one, map is red because it is
+ * the geographic one. Folder is grey — it is not a view, and the flyout's last row should
+ * not compete with the six above it.
+ */
+/**
+ * Human labels for every display mode. Moved here from viewModes.tsx in wave 9 so the label
+ * sits beside the geometry, the way TYPE_LABELS does — the mode switcher, the create flyout
+ * and the create prompt now read ONE table instead of three. C2's "Dashboard" → "Chart"
+ * rename is a single line here as a direct result.
+ */
+export const MODE_LABELS: Record<DisplayMode, string> = {
+  grid: "Grid",
+  chart: "Chart",
+  // Legacy: never OFFERED (it is not in CREATABLE_MODES) but still labelled, because a view
+  // read before normalisation must never render a blank switcher chip.
+  dashboard: "Chart",
+  list: "List",
+  calendar: "Calendar",
+  kanban: "Kanban",
+  map: "Map",
+  timeseries: "Time series",
+  catalog: "Catalog",
+  // Wave-23 C9 — the mode that COLLECTS records. "Form", the word the whole product uses for
+  // it (the public page, the share panel, the `form_submitted` trigger); a synonym here would
+  // be the one surface calling it something else.
+  form: "Form",
+  // ⭐ Wave-27 C3 (item 8) — the owner's own word for it. Not "Triage" or "Review": the gesture
+  // IS the name here, and the two candidates both collide with vocabulary this product already
+  // spends elsewhere (a `review` automation decision, the retired review lanes).
+  swipe: "Swipe",
+  // W36-T04 — the owner's own words are "code script"; "Script" is the half that is not implied
+  // by the icon, and the product has no other surface competing for the noun.
+  //
+  // ⭐⭐ W37-T41 (owner ruling, 2026-08-19) — RENAMED TO "Custom", and the one-word form is the
+  // ruling rather than a shortening of it. Every wave-37 governing text calls this surface the
+  // "Custom View": PRD items 10 / R2, T41's own `done-when`, D-391, and `ScriptViewPanel`'s
+  // shipped copy ("Picking Custom View mints a view with an EMPTY source"). "Script" was the
+  // product calling one thing two names, which is the defect `swipe`'s label note warns about
+  // one table up.
+  //
+  // ⛔ IT IS NOT SPELLED "Custom View" HERE, and the reason is this table's job rather than a
+  // preference. Every value is a KIND NOUN that four call sites COMPOSE into a phrase:
+  // `ViewSidebar` renders `New ${MODE_LABELS[creating].toLowerCase()} view` (:1060), the same
+  // string as the flyout's aria-label (:1045), `${MODE_LABELS[mode]} view, locked` (:1619) and
+  // `It also stays a ${MODE_LABELS[mode].toLowerCase()}.` (:1626). A label already carrying the
+  // noun reads "New custom view view" at two of them. One word keeps the create prompt reading
+  // "New custom view", the locked aria-label reading "Custom view, locked", and the picker row
+  // reading "Custom" beside Grid, Chart and Map, which are kind nouns too.
+  script: "Custom",
+};
+
+/**
+ * I14 — the view types the "+ Create new…" flyout OFFERS, in the order it lists them.
+ *
+ * Deliberately NOT `DISPLAY_MODES`, and deliberately here rather than inside ViewSidebar.tsx:
+ * C2 makes `'dashboard'` a mode that stays READABLE forever (every view saved before the
+ * rename sits in it) while ceasing to be OFFERABLE once `'chart'` exists — one list cannot
+ * express both. Living in this pure data module means the gate can assert the offered set
+ * without importing a React component, and I10 becomes a one-line edit in one file.
+ */
+// 2026-08-02 item 7 — `timeseries` was deliberately held OUT of this list until the host
+// accepted the name, because a mode may be READABLE before it is OFFERABLE (the same split C2
+// wrote for 'dashboard', running forwards): `aios_grid._clean_display` drops a mode it does
+// not know, so offering it early would let a user create a view that silently reverts to a
+// grid on the next read with nothing going red. HOST posted "ACCEPTANCE LANDED" with
+// `DISPLAY_MODES += timeseries`, so it is offerable now.
+//
+// wave17 GRID, owner item 10 — THE ORDER BELOW IS THE OWNER'S, stated verbatim:
+// Grid · Chart · Calendar · Kanban · Time series · Map · List.
+//
+// ⚠ It supersedes the two orderings this list has carried before it, and the reasoning that
+// produced them is now WRONG rather than merely outranked, so it is not left here to be
+// re-applied: `timeseries` was "listed last… it belongs beside Chart", and `list` sat second
+// as the other record-shaped mode. The owner put Time series FIFTH and List LAST. An order is
+// a product decision, so it is asserted in `verify_icons` rather than left to a comment —
+// nothing else on screen would go red if a future edit re-sorted it "sensibly".
+// Wave-18 C6-CATALOG — `catalog` was held out of this list until `aios_grid.DISPLAY_MODES`
+// accepted the name, the same hold `timeseries` and `chart` served before it. SESSION A posted
+// "C6 HOST MIRROR APPLIED — you may flip CREATABLE_MODES now" (2026-08-03), so it is offerable.
+// It lands LAST by contract: the owner's seven-mode order above is a product decision and the
+// new mode joins the end of it rather than being sorted into it.
+// ⭐ Wave-27 C3 (owner item 8) — `swipe` is HELD OUT of this list, and the reason corrects a
+// mistake this file made an hour earlier.
+//
+// ⛔ THE HOLD WAS NEVER ONLY ABOUT THE TWO REGISTRIES. It was first written as "do not offer a
+// mode the HOST has not accepted", and one session owning both registries this wave genuinely
+// does close that half — which is what made it tempting to skip. But the rule the hold really
+// encodes is broader and this wave proved it: **do not offer a mode whose CONSUMER does not
+// exist.** `swipe` was briefly listed here while `CustomerGrid`'s mode dispatch had no branch
+// for it, so picking "Swipe" wrote a mode the host now happily PERSISTS, and the body rendered
+// a grid under a chip reading "View · Swipe" — surviving reload, with the agreement leg green
+// because it only ever compared two lists.
+//
+// So the hold stood until `SwipeView` was mounted (contract C3), and it was not a mailbox
+// handshake: `verify_icons` DERIVES the condition — either `swipe` is absent here, or
+// `CustomerGrid.tsx` mounts `SwipeView`. `form` (wave-23) is the same defect from the other
+// direction, sitting unoffered because its host mirror never landed (DEBT D-90).
+//
+// ⛔ THE HOLD OUTLIVED THE WAVE, AND THAT IS THE LESSON WORTH MORE THAN THE FEATURE.
+// Wave 27 closed with the mount NEVER LANDING. `SwipeView.tsx` shipped, the server accepted
+// `swipe`, all four maps above carried it, 50 gates were green, the wave-27 mailbox recorded
+// "RESOLVED BY C (swipe mounted)", the close-out booked D-102 — a negative control FOR the
+// swipe carry — and the owner could not find the view because **nothing imported the file.**
+// The derived gate could not catch it: its condition is a DISJUNCTION and **absence satisfies
+// it**, so the unshipped state was permanently green ([[gate-can-report-green-on-nothing]]).
+// A hold that is safe to leave in place is a hold nothing forces you to lift.
+// The audit query that found it, after the battery did not: for each artifact a wave adds, grep
+// for its CONSUMER — who imports/mounts/registers it — excluding the file itself, `_test/`, css
+// and comments. `SwipeView` had four hits and three were prose.
+// Mounted 2026-08-09 (`CustomerGrid.tsx`, `displayMode === "swipe"`), so `swipe` is offerable.
+// It lands LAST, by `catalog`'s rule: the owner's mode order is a product decision and a new
+// mode joins the end of it rather than being sorted into it.
+export const CREATABLE_MODES: DisplayMode[] = [
+  "grid",
+  "chart",
+  "calendar",
+  "kanban",
+  "timeseries",
+  "map",
+  "list",
+  "catalog",
+  "swipe",
+  // Mounted 2026-08-11 (`CustomerGrid.tsx`, `displayMode === "form"` renders `FormInterface`), so
+  // `form` is offerable and its `HELD_MODES` entry came out in the same edit — the hold's own text
+  // named this mount as its release condition. ⚠ Found by `verify_icons.py::mode_parity` law E
+  // during /validate-wave, NOT by the lane that mounted it: T29 mounted the component and T41 built
+  // the Interface group, and between them the DOOR was never opened — the wave's biggest new
+  // surface was unreachable behind two green tickets.
+  "form",
+  // ⭐⭐ W37-T41 (owner item 10 / R2) — `script` JOINS THE OFFER, and this is the release of the
+  // longest-held entry in this file. The hold's own release condition, written into
+  // `icons.test.ts::HELD_MODES`, named THREE things that had to land in one change: the name
+  // joins this list, `CustomerGrid.tsx` gains a `displayMode === "script"` branch, and the
+  // HELD_MODES entry comes out. All three are in this change.
+  //
+  // ⛔ AND A FOURTH THAT THE HOLD DID NOT NAME, which is the one that decides whether the
+  // feature works: `CustomerGrid.tsx::createView` had to learn that picking this mode mints a
+  // SCRIPT VIEW through `createScriptView` rather than persisting a workspace view. A script
+  // view is not a workspace view (it is its source and its version history, in E's own
+  // per-database store), so the three hops above alone would have offered the mode, written
+  // `config.display.mode = "script"` into a stored view, left `activeScriptId` null and drawn
+  // nothing, with `mode_parity` GREEN. That is wave 27's `swipe` defect exactly, reached
+  // through a different door.
+  // ⚠ OFFERED ONLY WHERE IT CAN EXIST. `ViewSidebar` takes `scriptable` and drops this row
+  // when it is false: script views are listed and resolved only on `ut_*` databases
+  // (`CustomerGrid`'s `scriptRows` effect gates on `hostWorkspace && isUserTable`), so offering
+  // it on a pool scope would mint a view the rail can never show
+  // ([[permitted-is-not-answerable]]). It lands LAST by `catalog`'s rule.
+  "script",
+];
+
+/**
+ * ⭐ WAVE-29 R6 (owner item 10) — the kind dropdown splits under TWO headers, and the strings are
+ * the owner's own: exactly `View` and `Interface`. Not "View as" (what the popover said before),
+ * not "Custom interface".
+ *
+ * The line the two groups draw: a **View** ARRANGES the records — the same rows, re-shaped (a
+ * grid, a board, a chart). An **Interface** is a SURFACE BUILT OVER them: a map is a picture of the
+ * world with records placed on it, a catalog is a published artifact, a form is a door records come
+ * IN through and shows no records at all.
+ *
+ * ⭐ WAVE-33 item 9 AMENDED THAT LINE, and the owner drew it one notch differently than R6 did:
+ * `swipe` and `timeseries` moved from View to Interface. The reading that makes both rulings one
+ * rule — and the one the next mode should be grouped by — is **what the surface is FOR**, not how
+ * many rows it shows. A deck triages records one at a time and WRITES to them; a trend answers a
+ * question about a measure over time; neither hands you the row set re-shaped, which is what every
+ * remaining View does. ⚠ Do NOT re-derive the split from `MODE_TONE` below: the tones still say
+ * `catalog`/`form` are neutral because they arrange nothing, and `swipe`/`timeseries` are toned,
+ * so tone and group are no longer the same cut. Group membership lives HERE and only here.
+ *
+ * ⚠ TOTAL over `DisplayMode`, so tsc refuses a new mode with no group rather than letting it
+ * vanish from the dropdown: membership is derived by FILTERING `CREATABLE_MODES` through this
+ * map, and a mode whose group label matched nothing would silently stop being offered while
+ * every existing check (paintable, labelled, toned, unique, ordered) stayed green.
+ * `dashboard` is grouped like the `chart` it is the legacy spelling of — it is never offered, and
+ * a partial map is a worse answer than an unused entry.
+ */
+export const MODE_GROUP_LABELS = ["View", "Interface"] as const;
+export type ModeGroup = (typeof MODE_GROUP_LABELS)[number];
+
+export const MODE_GROUP: Record<DisplayMode, ModeGroup> = {
+  grid: "View",
+  list: "View",
+  kanban: "View",
+  calendar: "View",
+  chart: "View",
+  dashboard: "View",
+  // ⭐ WAVE-33 item 9 (owner, verbatim): "Let's move Swipe and Time-series under Interface instead
+  // of under View, when a user toggle it." See the amended taxonomy note above — a deck and a
+  // trend are both surfaces a person WORKS IN, not re-shapings of the row set.
+  timeseries: "Interface",
+  swipe: "Interface",
+  map: "Interface",
+  catalog: "Interface",
+  form: "Interface",
+  // W36-T04 — "Interface", by the W33 item-9 taxonomy: a script view is a surface somebody WORKS
+  // IN (writes, runs, reads an answer), not a re-shaping of the row set.
+  script: "Interface",
+};
+
+/**
+ * The offered modes, split into R6's two groups — DERIVED, never a third hand-written list.
+ *
+ * ⚠ ORDER: R6 names each group's MEMBERS; the order inside a group stays `CREATABLE_MODES`', which
+ * is the wave-17 owner ruling ("Grid · Chart · Calendar · Kanban · Time series · Map · List") and
+ * is separately asserted. The two rulings are compatible read this way and only this way: R6 moved
+ * `map` out of the run of views, so wave-17's single sequence can no longer exist as one list, but
+ * every pair it ordered is still in that relative order here.
+ */
+export const CREATABLE_GROUPS: readonly { label: ModeGroup; modes: DisplayMode[] }[] =
+  MODE_GROUP_LABELS.map((label) => ({
+    label,
+    modes: CREATABLE_MODES.filter((m) => MODE_GROUP[m] === label),
+  }));
+
+export const MODE_TONE: Record<DisplayMode, FolderTone> = {
+  grid: "blue",
+  list: "blue",
+  chart: "green",
+  dashboard: "green",
+  calendar: "yellow",
+  kanban: "yellow",
+  map: "red",
+  // Green with `chart`: it is the other analytical mode, and the two belong to one family.
+  timeseries: "green",
+  // Wave-18 C6-CATALOG — NEUTRAL, and it is the honest pick rather than the leftover one. The
+  // four colour tones each name a family of ways to arrange records (blue = tabular, green =
+  // analytical, yellow = board/date, red = spatial); a catalog arranges nothing — it is a
+  // published artifact. Giving it a colour would file it under a family it is not in.
+  catalog: "neutral",
+  // Wave-23 C9 — NEUTRAL, and for `catalog`'s reason rather than by elimination: the four tones
+  // name families of ways to ARRANGE records (blue tabular, green analytical, yellow
+  // board/date, red spatial). A form arranges nothing — it is a door records come in through —
+  // so giving it a colour would file it under a family it is not in.
+  form: "neutral",
+  // ⭐ Wave-27 C3 — YELLOW, with `kanban`, and this is a family claim rather than a leftover:
+  // a swipe deck writes the SAME single-select a kanban stacks by (R2 binds it to one), so the
+  // two are one family seen at two zooms — all the lanes at once, or one card at a time. Filing
+  // it neutral (the `catalog`/`form` reasoning) would be wrong for the opposite reason those
+  // two are neutral: this mode does arrange records, and it arranges them by the board's field.
+  swipe: "yellow",
+  // W36-T04 — NEUTRAL, by `catalog`'s and `form`'s rule rather than by elimination: the four
+  // tones name families of ways to ARRANGE records (blue tabular, green analytical, yellow
+  // board/date, red spatial). A script arranges nothing; it emits whatever it computes.
+  script: "neutral",
+};
+
+/**
+ * Human labels for every field type. Lives here beside the icons so the two
+ * halves of "how a field type presents itself" stay in one file (ColumnMenu
+ * imports it rather than keeping a second copy).
+ */
+export const TYPE_LABELS: Record<FieldType, string> = {
+  // ⭐ WAVE-29 item 3 — the owner's own words: "Change 'Single line text' to 'Text', keep it
+  // simple for the Field type". Airtable's phrase described the column's SHAPE (one line, versus
+  // its long-text sibling); this product has no multi-line text kind, so the qualifier
+  // distinguished the type from nothing and only made the commonest row in the menu the longest.
+  // ✅ The STORED key is `"text"` and always was — the old string was never persisted anywhere,
+  // client or server, so this is a label change with no migration behind it.
+  text: "Text",
+  select: "Single select",
+  multiselect: "Multi select",
+  user: "Assignee",
+  int: "Number",
+  currency: "Currency",
+  pct: "Percent",
+  date: "Date",
+  checkbox: "Checkbox",
+  phone: "Phone number",
+  email: "Email",
+  url: "URL",
+  rating: "Rating",
+  created_time: "Created time",
+  formula: "Formula",
+  // Wave-18 C5-AUTOFIELD (D's spec, applied by C).
+  automation: "Automation",
+  // Wave-22 C7 — spawned by automations (not in CREATABLE_TYPES), so this label mostly shows
+  // on headers and the field gear, not the create menu.
+  metric: "Metric",
+  // Wave-19 R7 — the picture column.
+  image: "Image",
+  // Wave-23 C7 — the structured-document column. "JSON" rather than "Structured data": it is
+  // the word on the wire, in the viewer's raw tab and in every error the server can return, and
+  // a friendlier synonym would be the only place in the product using a different one.
+  json: "JSON",
+  // ⭐ 2026-08-07 — Airtable's own wording, deliberately. "Link to another record" is what a
+  // person migrating from Airtable searches this menu for, and inventing a synonym ("Relation",
+  // "Reference") would make the feature they came for look absent.
+  link: "Link to another record",
+  rollup: "Rollup",
+  // ⭐ Wave-27 item 13 (R13) — "Code", not "Snippet" or "Source": it is the word the field kind
+  // is called everywhere else in this wave (the ruling, the language picker, the viewer header),
+  // and it says what the column holds without implying the product will run it.
+  code: "Code",
+  // ⭐ WAVE 34 · T53 (R13), on F's ask (`F-2`) — the owner's own noun for the kind: "a field kind
+  // called AI enrichment". Not "AI field" (every field in an AI-built view would qualify) and not
+  // "Generate" (that names the verb, and the column's value is the point, not the act).
+  ai_enrich: "AI enrichment",
+  status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
+};
+
+/**
+ * ⭐ WAVE-29 C7 (item 17) — THE COLUMN-SUMMARY vocabulary: what a field's `agg` may be, which is
+ * what the totals row and the per-group subtotals compute. Server twin:
+ * `platform/aios_grid.py::FIELD_AGGS`, and `verify_icons.py::agg_parity` reads BOTH FILES and
+ * compares them name-for-name in order — the cross-language boundary is the one a type cannot
+ * police, so it gets a gate.
+ *
+ * ⛔ ONE CLIENT LIST, IMPORTED — never re-declared. `aggregations.ts` and the field editor import
+ * from here rather than keeping their own copy, which is why this lives in the pure data module
+ * beside `TYPE_LABELS` and `CREATABLE_MODES`: a second client list would need a second gate, and
+ * the two would drift in the direction nobody is watching. C7 says "C publishes, E mirrors"; a
+ * mirror that is an import cannot fall out of step at all.
+ *
+ * ⛔ NOT the chart vocabulary. `CHART_AGGS` (`aios_grid.py`, `viz/chartData.ts`) spells it `avg`
+ * and gatekeeps a STORED value — renaming it would silently turn saved charts into sums. This
+ * list spells it `average`, matching `ROLLUP_FNS` (16 names, live in production), so a column
+ * summary and a rollup fold say the same word for the same operation.
+ *
+ * ⚠ `median` is net-new — in neither `CHART_AGGS` nor `ROLLUP_FNS`.
+ * ⚠ `count` counts ROWS in the scope, not non-blank cells.
+ * ⚠ Which types may carry which: `sum/average/median/min/max` are numeric-only and the evaluator
+ * for that is ALREADY `isNumericFieldType` (types.ts) — do not write a second one. `count` is
+ * legal on any type.
+ */
+// ⭐ W29-T74 — an ALIAS of `types.AggName`, not a fifth copy of the union. `Field.agg` is typed
+// `AggName`, so a second literal here would be a type that has to be kept in step by eye with a
+// type the compiler already owns — the same defect as the array below, one level up.
+export type FieldAgg = AggName;
+
+/** ORDERED — the order is the picker's order, on both engines. */
+export const FIELD_AGGS: readonly FieldAgg[] = [
+  "sum",
+  "average",
+  "median",
+  "min",
+  "max",
+  "count",
+];
+
+/**
+ * Human labels, in the summary bar's own compact register (Airtable's wording).
+ *
+ * ⚠ `FIELD_AGG_LABELS`, not `AGG_LABELS`, and the prefix is load-bearing: `viewModes.tsx` already
+ * has a module-local `AGG_LABELS` for the CALENDAR summary picker over `CHART_AGGS`, where the
+ * same five names wear different words ("Total", "Lowest", "Highest") for a day cell. Two tables
+ * called `AGG_LABELS` describing two vocabularies is how a future import lands on the wrong one.
+ */
+export const FIELD_AGG_LABELS: Record<FieldAgg, string> = {
+  sum: "Sum",
+  average: "Average",
+  median: "Median",
+  min: "Min",
+  max: "Max",
+  count: "Count",
+};
+
+
+// ------------------------------------------------------------ glide sprites
+
+/** Serialize one shape to SVG source in an explicit colour (canvas sprites get
+ *  no `currentColor` — glide hands the painter the theme colours directly). */
+function shapeSource(s: IconShape, color: string): string {
+  return s.fill
+    ? `<path d="${s.d}" fill="${color}"/>`
+    : `<path d="${s.d}" fill="none" stroke="${color}" stroke-width="1.35" ` +
+        `stroke-linecap="round" stroke-linejoin="round"/>`;
+}
+
+function sprite(shapes: IconShape[]) {
+  return ({ fgColor }: { fgColor: string }) =>
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">` +
+    shapes.map((s) => shapeSource(s, fgColor)).join("") +
+    `</svg>`;
+}
+
+/** Glide header-icon NAME for a field type — the `icon` a GridColumn asks for. */
+export function typeIconName(type: FieldType): string {
+  return `t_${type}`;
+}
+
+/**
+ * The sprite map handed to <DataEditor headerIcons>. One entry per field type
+ * (I20 draws the type mark in every column header), built from the same shapes
+ * the React icons use.
+ *
+ * Colour: glide's "normal" variant paints with `theme.fgIconHeader`, which is
+ * why theme.ts must set it — the library default is #FFFFFF, i.e. invisible on
+ * our header (that was I21's actual bug, not a too-pale hex of ours).
+ */
+export const TYPE_SPRITES: Record<string, ({ fgColor }: { fgColor: string }) => string> =
+  Object.fromEntries(
+    (Object.keys(TYPE_SHAPES) as FieldType[]).map((t) => [typeIconName(t), sprite(TYPE_SHAPES[t])])
+  );
+
+/**
+ * The header sprite map handed to <DataEditor headerIcons>. Two families:
+ *
+ *   t_<type>   wave-8 I20 - the field-TYPE mark, drawn in EVERY column header,
+ *              from the same shapes the React icons use. Painted by glide in
+ *              `theme.fgIconHeader`.
+ *   aiosInfo   wave-5 item 6, restyled by wave-9 I3 - the description (i).
+ *              OUTLINE ONLY: a dark-grey ring with a transparent interior, per
+ *              the owner. It still deliberately IGNORES the colours glide hands
+ *              it, for the reason wave-8 recorded - glide's "special" variant is
+ *              accentColor behind bgHeader, which under the C1 pastels is a pale
+ *              glyph on a pale disc, i.e. I21 in a new costume.
+ *              ⚠ It is NO LONGER a column `overlayIcon`. Glide draws an overlay
+ *              at a hard-coded offset from the TYPE mark on the far LEFT of the
+ *              header (drawHeaderInner: `drawX + 9`), and I3 wants it RIGHT-
+ *              aligned. It is now painted by CustomerGrid's `drawHeader`
+ *              callback at `infoMarkRect()` - see overlayPlacement.ts.
+ */
+/**
+ * ⭐ W40-T20 — THE share glyph: two people, one behind the other. The ONE geometry for "this is
+ * shared", as data, so the canvas sprite below and any React consumer paint the same shape
+ * instead of two hand-copied SVGs that drift.
+ *
+ * ⛔ NOT A PADLOCK. `LockMark` (icons.tsx) is a padlock body plus a shackle and it means a LOCK
+ * (DESIGN.md §4, THE THREE LOCKS). A share is a different fact about a column and wears a
+ * different mark, which is the whole of "one mark, one meaning" — D-254 is what happens when it
+ * does not.
+ *
+ * Traced off the rail's `.cg-view-shared` mark (ViewSidebar.tsx) at the same viewBox, so a shared
+ * VIEW in the rail and a shared FIELD in a header say "shared" with the same drawing. The head is
+ * an arc path rather than a `<circle>` because `IconShape` is path data and one serializer
+ * (`shapeSource`) paints the entire vocabulary.
+ */
+export const SHARE_SHAPE: IconShape[] = [
+  // The near figure: head, then shoulders.
+  { d: "M5.6 3.4a2.2 2.2 0 1 1 0 4.4 2.2 2.2 0 1 1 0-4.4" },
+  { d: "M1.9 12.6c0-2 1.7-3.2 3.7-3.2s3.7 1.2 3.7 3.2" },
+  // The far figure, cropped by the near one: half a head and a shoulder.
+  { d: "M10.6 4.1a2.2 2.2 0 0 1 0 4.2M11.4 9.7c1.6.3 2.7 1.4 2.7 2.9" },
+];
+
+export const HEADER_ICONS: Record<string, (c: { fgColor: string; bgColor: string }) => string> = {
+  ...TYPE_SPRITES,
+  /**
+   * ⭐ W40-T20 — the shared-field mark, drawn by `CustomerGrid.drawGridHeader` on the innermost
+   * slot of `headerMarkFit`'s strip.
+   *
+   * It IGNORES the colours glide hands it, for exactly the reason `aiosInfo` does and recorded in
+   * that entry's note: glide's variants resolve to the accent behind `bgHeader`, which under the
+   * C1 pastels is a pale glyph on a pale disc. LP_MUTED keeps it legible on every header state.
+   */
+  aiosShared: () =>
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">` +
+    SHARE_SHAPE.map((s) => shapeSource(s, LP_MUTED)).join("") +
+    `</svg>`,
+  aiosInfo: () =>
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">` +
+    `<circle cx="8" cy="8" r="6.1" fill="none" stroke="${LP_MUTED}" stroke-width="1.25"/>` +
+    `<path d="M8 7.4v3.5" fill="none" stroke="${LP_MUTED}" stroke-width="1.4" ` +
+    `stroke-linecap="round"/>` +
+    `<circle cx="8" cy="5.1" r="0.85" fill="${LP_MUTED}"/>` +
+    `</svg>`,
+};

web/src/customer-grid/overlayPlacement.ts

@@ -213,6 +213,18 @@ export function fitGroupLabel(
 export const CUSTOM_MARK_SIZE = 6;
 /** Clearance BETWEEN two marks in the strip. */
 export const HEADER_MARK_GAP = 6;
+/**
+ * ⭐ W40-T20 — the SHARE mark, the strip's third slot: "this field is shared, so what you type
+ * here is what everyone with access to this table reads".
+ *
+ * 13px is the size `ViewSidebar` renders the same two-people glyph at, so one concept reads at
+ * one weight wherever the product says it.
+ *
+ * ⛔ IT IS NOT A PADLOCK AND IT IS NOT `LockMark`. A share and a lock are different facts about a
+ * column (DESIGN.md §4, THE THREE LOCKS: a share says who else can see the column, a lock says
+ * what may be changed), and one glyph carrying both meanings is D-254 in a second surface.
+ */
+export const SHARE_MARK_SIZE = 13;
 
 /**
  * R11 — where the header's right-hand marks go, laid out from the OUTSIDE IN.
@@ -257,16 +269,83 @@ export function headerMarkLayout(
   return out;
 }
 
-/** The strip's ORDER, in one place: (i) outermost, the user-created dot inboard of it. Both the
- *  truncation reserve and the drawing path read this, so they cannot disagree about how many
- *  marks a column carries or which is which. */
-export function headerMarkSizes(hasInfoMark: boolean, isCustomField: boolean): number[] {
+/** The strip's ORDER, in one place: (i) outermost, the user-created dot inboard of it, the share
+ *  mark innermost. Both the truncation reserve and the drawing path read this, so they cannot
+ *  disagree about how many marks a column carries or which is which.
+ *
+ *  ⭐ W40-T20 — `isSharedField` is OPTIONAL and defaults to false, deliberately: every pre-T20
+ *  call site asks the two-boolean question and must keep getting the two-boolean answer. The
+ *  share mark goes LAST because last is INNERMOST, and innermost is the slot `headerMarkFit`
+ *  gives up first — so a column too tight for three marks loses the new one rather than the two
+ *  that shipped before it. */
+export function headerMarkSizes(
+  hasInfoMark: boolean,
+  isCustomField: boolean,
+  isSharedField = false
+): number[] {
   const out: number[] = [];
   if (hasInfoMark) out.push(INFO_MARK_SIZE);
   if (isCustomField) out.push(CUSTOM_MARK_SIZE);
+  if (isSharedField) out.push(SHARE_MARK_SIZE);
   return out;
 }
 
+/**
+ * ⭐ W40-T20 — does this field's header carry a share mark? THE rule, in one exported place.
+ *
+ * It lives here rather than inside `CustomerGrid.drawGridHeader` for the reason the rest of this
+ * module exists: a decision buried in a React canvas callback is unobservable to anything but a
+ * screenshot, and this one has two consumers (the drawer, and the label reserve) that must never
+ * answer it differently.
+ *
+ * ⚠ STRUCTURALLY TYPED ON PURPOSE. This module imports nothing — that is what lets a gate compile
+ * it with tsc and run it under node — so it takes the one property it reads rather than `Field`.
+ *
+ * ⛔ `shared` means "this definition lives in the tenant-wide field stratum", i.e. THIS FIELD HAS
+ * BEEN SHARED — not "somebody shared it WITH ME" (contract C1). The server stamps it on the
+ * owner's own copy too (`routes_customers._merge_shared_fields`, `shares.role_for` returning
+ * `"owner"`), so the mark reads as "this column is shared" for everyone who can see it, and the
+ * copy that explains it must not be worded as though the reader were only ever the receiver.
+ */
+export function hasShareMark(field: { shared?: boolean }): boolean {
+  return field.shared === true;
+}
+
+/**
+ * ⭐ W40-T20 — the strip that DEGRADES, and the ONE function both the drawer and the label
+ * reserve go through.
+ *
+ * Why it had to exist. `headerMarkLayout` is ALL-OR-NOTHING by contract, and that contract is
+ * what stops the reserve and the drawer disagreeing (see its note). It is also why a third mark
+ * could not simply be appended: on a column with room for exactly two, asking for three returns
+ * `null`, and the (i) and the user-created dot — both shipped, both gated — would have vanished
+ * to make room for a mark that was then not drawn either. Adding a feature by deleting two is
+ * not adding a feature.
+ *
+ * So the strip gives way from the INSIDE, one droppable slot at a time. `droppable` is how many
+ * TRAILING slots may be surrendered; everything ahead of them keeps the all-or-nothing behaviour
+ * it shipped with. **`droppable = 0` is exactly `headerMarkLayout`** — which is why every
+ * pre-T20 caller, and every negative control aimed at that function, is untouched by this.
+ *
+ * Returns the surviving layout AND how many slots survived, because a drawer needs to know which
+ * marks it may paint, not merely where they would have gone.
+ */
+export function headerMarkFit(
+  header: { x: number; y: number; width: number; height: number },
+  menuSlotWidth: number,
+  sizes: readonly number[],
+  droppable = 0
+): { layout: { x: number; y: number; size: number }[]; kept: number } | null {
+  // Never below one mark: a strip that "degrades" to nothing is the all-or-nothing answer, and
+  // `headerMarkLayout` already gives that by returning null.
+  const floor = Math.max(1, sizes.length - Math.max(0, droppable));
+  for (let kept = sizes.length; kept >= floor; kept--) {
+    const layout = headerMarkLayout(header, menuSlotWidth, sizes.slice(0, kept));
+    if (layout) return { layout, kept };
+  }
+  return null;
+}
+
 // ------------------------------------------------- owner item 16: the header title vs the (i)
 
 /**
@@ -310,13 +389,22 @@ export function headerLabelSpace(
    * the label gets reserved room for only one of them.
    */
   marks: boolean | readonly number[],
-  menuSlotWidth = HEADER_MENU_SLOT
+  menuSlotWidth = HEADER_MENU_SLOT,
+  /**
+   * ⭐ W40-T20 — how many TRAILING marks this column is willing to give up, passed straight to
+   * `headerMarkFit`. It defaults to 0, so every pre-T20 caller keeps the all-or-nothing reserve
+   * it had; a caller that asks for a droppable share mark must say so here too, or it reserves
+   * room for a strip the drawer will not paint.
+   */
+  droppable = 0
 ): number | null {
   const sizes = marks === true ? [INFO_MARK_SIZE] : marks === false ? [] : marks;
-  // The INNERMOST mark is the one the label must clear, and `headerMarkLayout` is all-or-nothing,
-  // so this is still ONE geometry source queried twice rather than two copies of the arithmetic.
-  const layout = headerMarkLayout({ x: 0, y: 0, width, height: 32 }, menuSlotWidth, sizes);
-  if (!layout) return null;
+  // The INNERMOST mark is the one the label must clear, and the strip is fitted through
+  // `headerMarkFit` — the SAME function the drawer uses — so the reserve is taken against the
+  // marks that actually SURVIVE the column's width, never against the ones merely asked for.
+  const fit = headerMarkFit({ x: 0, y: 0, width, height: 32 }, menuSlotWidth, sizes, droppable);
+  if (!fit) return null;
+  const layout = fit.layout;
   return Math.max(0, layout[layout.length - 1].x - HEADER_LABEL_X - HEADER_LABEL_GAP);
 }
 
@@ -423,45 +511,76 @@ export function expandButtonRect(
   return { x, y, size };
 }
 
-// ------------------------------------------------ W35-T29 (R5): the record star, on the row
+// -------------------------------- the record star, BESIDE the Expand (owner instruction 29)
 
 /** Smaller than the Expand button: a mark, not an action with a destination. */
 export const STAR_BTN_SIZE = 18;
-/** From the LEFT edge of the primary cell, mirroring `EXPAND_BTN_INSET` at the other end. */
-export const STAR_BTN_INSET = 4;
+/**
+ * The clear space between the star and the Expand it now sits against.
+ *
+ * 4px is not a taste call: it is `.cg-detail-nav`'s own `gap`, which is what a group of adjacent
+ * icon buttons already measures elsewhere in this grid, and it is on `DESIGN.md` §4's 4/8 grid.
+ */
+export const STAR_BTN_GAP = 4;
 
 /**
- * ⭐⭐ W35-T29 (R5) — where the row's star sits: **at the LEFT end of the primary cell**, which is
- * the gutter position in this product. Airtable puts the row's own marks there; our Expand button
- * already occupies the RIGHT end of the same cell (`expandButtonRect`), so the two book-end the
- * primary cell and neither can land on the other.
- *
- * ⛔ THE SAME BOUNDS, FROM THE SAME SOURCE. `primary` is glide's own `getBounds(0, row)`, so
- * freeze, horizontal scroll and row-height mode are handled by the component that owns them
- * rather than re-derived here — and because the button is a real `<button>` over the canvas, this
- * rect IS the hit test. A canvas-DRAWN star would need a second copy of this arithmetic for its
- * click target, which is the shape [[ui-invisible-to-assertions]] names.
- *
- * ⚠ ITS MINIMA ARE ITS OWN AND ARE LOWER THAN THE EXPAND'S. This mark is smaller and sits where
- * the text starts rather than where it ends, so a row that cannot carry the Expand can still
- * carry this. Sharing `EXPAND_BTN_MIN_ROW` would have hidden the star on exactly the compact row
- * heights a long list is read at.
- *
- * `null` when the row is too short, or when the rect would fall outside the grid's own box —
- * absent rather than clamped, for the same reason the Expand is: a clamped `position: fixed`
- * button sits at the edge pointing at a row whose cell is somewhere else.
+ * ⭐⭐ OWNER INSTRUCTION 29 (wave 40, 2026-08-24) — where the row's star sits: **immediately to
+ * the LEFT of the Expand button**, at the right end of the primary cell, level with it.
+ *
+ * ⛔ THIS REVERSES W35-T29 (R5, R6), AND THE OLD ARGUMENT IS RECORDED HERE RATHER THAN DELETED,
+ * because a reversed ruling whose reasoning is left standing is how the next session restores it.
+ * R5 put the star at the LEFT end of the primary cell and the Expand at the right, deliberately:
+ * Airtable keeps a row's own marks in the gutter, and book-ending the cell meant neither control
+ * could ever land on the other. That was a real design, it shipped, and the owner has now ruled
+ * against it: *"The star label on a record must sit exactly beside and to the LEFT of the record
+ * expand icon, on every database."* Beside beats book-ended. The two are now ONE CLUSTER at the
+ * right end, and everything below follows from that single fact.
+ *
+ * ⛔ DERIVED FROM THE EXPAND, NOT COMPUTED ALONGSIDE IT. This function asks `expandButtonRect`
+ * where its neighbour is and steps left from the answer. That is what makes "beside" a property
+ * rather than a coincidence: two independent copies of the same arithmetic drift, and this file
+ * exists because that drift is invisible to tsc, to the build and to a screenshot taken at one
+ * size ([[ui-invisible-to-assertions]]).
+ *
+ * ⛔ ITS MINIMA ARE THE EXPAND'S NOW, AND THAT REPLACES THE OPPOSITE CLAIM R5 MADE HERE. The old
+ * comment argued the star should keep LOWER minima than the Expand, so "a row that cannot carry
+ * the Expand can still carry this", and warned that sharing `EXPAND_BTN_MIN_ROW` would hide the
+ * star "on exactly the compact row heights a long list is read at". That protection was sound for
+ * a mark living at the far end of the cell and is incoherent for one anchored to the Expand: a
+ * star placed beside a button that is not there is a mark floating where its neighbour should be.
+ * It also protected a case this product cannot produce. `CustomerGrid.ROW_PX` is the whole set of
+ * data-row heights and it is `{ short: 28, medium: 34, tall: 48 }` — every one of them clears
+ * `EXPAND_BTN_MIN_ROW` (26), so the band the old minima defended (20..25px) is empty. Deleting
+ * the second height gate rather than re-tuning it is what makes "both or neither" structural.
+ *
+ * ⚠ THE WIDTH GATE IS THIS FUNCTION'S OWN, AND IT IS DELIBERATELY STRICTER THAN THE EXPAND'S.
+ * Two controls plus a readable name need more of the cell than one did, so the star refuses at a
+ * width the Expand still accepts. The asymmetry is on purpose and runs only in this direction:
+ * item 17 removed the click that used to open a record, so the Expand is the ONLY pointer route
+ * to one and must not disappear from a narrow primary column to keep a mark company.
+ *
+ * `null` when the Expand is absent for any reason, when the cell is too narrow for the pair, or
+ * when the star's own rect would fall outside the grid's box — absent rather than clamped, for
+ * the reason the Expand is: a clamped `position: fixed` button sits at the edge pointing at a row
+ * whose cell is somewhere else.
  */
 export function starButtonRect(
   primary: { x: number; y: number; width: number; height: number },
   box?: { x: number; y: number; width: number; height: number },
   size = STAR_BTN_SIZE,
-  inset = STAR_BTN_INSET
+  gap = STAR_BTN_GAP
 ): { x: number; y: number; size: number } | null {
-  if (primary.height < size + 2) return null;
-  // It must leave room for a readable label beside it, or the mark covers the name it marks.
-  if (primary.width < size + inset * 2 + EXPAND_BTN_MIN_LABEL) return null;
-  const x = Math.round(primary.x + inset);
-  const y = Math.round(primary.y + (primary.height - size) / 2);
+  // No Expand, no star. The row height gate, the label gate and the box clamp are all inherited
+  // from this one call, so the two controls cannot disagree about whether the row carries them.
+  const expand = expandButtonRect(primary, box);
+  if (!expand) return null;
+  // Room for BOTH controls, their gap, the gutter at either side, and a name still worth reading.
+  if (primary.width < EXPAND_BTN_SIZE + EXPAND_BTN_INSET * 2 + gap + size + EXPAND_BTN_MIN_LABEL)
+    return null;
+  const x = expand.x - gap - size;
+  // Level with its neighbour BY CONSTRUCTION: the same centre whatever the two sizes are, so
+  // "beside" means level and not merely adjacent, and no second centring rule can drift.
+  const y = expand.y + Math.round((expand.size - size) / 2);
   if (box) {
     if (x < box.x || x + size > box.x + box.width) return null;
     if (y < box.y || y + size > box.y + box.height) return null;

web/src/customer-grid/rowStar.css

@@ -1,80 +1,87 @@
-/* ---------------------------------------------------------------------------
-   customer-grid / rowStar.css — W35-T29 (rulings R5, R6), the record star.
-
-   ⛔ ITS OWN SHEET, AND THE REASON IS OWNERSHIP RATHER THAN TIDINESS. `.cg-row-expand`, the hover
-   control this one sits beside, lives in `index.css`, which belongs to another lane this wave. A
-   new surface brings its own stylesheet (the wave's own rule) and a change to an existing
-   `.cg-*` rule is that lane's ticket.
-
-   ⚠ IMPORTED BY `CustomerGrid.tsx`, the module that RENDERS these classes — never by a lazy
-   parent. W35-T22 in this same wave was exactly that mistake one directory over: `query.css` was
-   imported only by a `lazy()` page while the component drawing its classes shipped in another
-   chunk, so the rail painted unstyled for a network round trip.
-   --------------------------------------------------------------------------- */
-
-/* The hover control at the LEFT end of the primary cell, mirroring the Expand button at its
-   right end. Both are real DOM buttons laid over the canvas at glide's own bounds, so the rect
-   IS the hit test and there is no second copy of the geometry to drift from the drawing. */
-.cg-row-star {
-  position: fixed;
-  z-index: 55;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0;
-  border: 1px solid transparent;
-  border-radius: var(--lp-r-sm);
-  background: transparent;
-  color: var(--lp-muted);
-  cursor: pointer;
-}
-
-/* ⛔ A STARRED ROW'S MARK IS NOT HOVER-ONLY. The hover control is how you SET one; a row that is
-   already starred has to say so while the pointer is elsewhere, or the grid cannot answer the
-   question the feature exists for. D-253 is a booked defect whose whole content is "satisfied
-   only on hover" — this is that lesson applied to a mark rather than to an explanation.
-   The always-on mark is drawn by the same button with `is-on`; the caller keeps it mounted for a
-   starred row whether or not the pointer is over it. */
-.cg-row-star.is-on {
-  color: var(--lp-yellow-deep);
-}
-
-.cg-row-star:hover {
-  border-color: var(--lp-line);
-  background: var(--cg-white);
-  color: var(--lp-yellow-deep);
-}
-
-.cg-row-star:focus-visible {
-  outline: 2px solid var(--lp-blue-deep);
-  outline-offset: 1px;
-}
-
-.cg-row-star:disabled {
-  cursor: default;
-  opacity: 0.55;
-}
-
-/* The drawer's own copy of the control (`RecordDetail`), which is in the flow rather than over a
-   canvas — so it takes the colour rules above and none of the positioning.
-   ⭐ OWNER ITEM 12 (2026-08-23) — it now sits INSIDE `.cg-detail-nav`, beside the prev/next keys,
-   so it is sized and bordered like them: a group of three buttons reads as a group only if the
-   third one is the same shape. The border is transparent until hover, which is what still tells
-   an ACTION apart from the two NAVIGATION keys beside it. */
-.cg-detail-star {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 28px;
-  height: 28px;
-  padding: 0;
-  border: 1px solid transparent;
-  border-radius: var(--lp-r-md);
-  background: transparent;
-  color: var(--lp-muted);
-  cursor: pointer;
-}
-
-.cg-detail-star.is-on { color: var(--lp-yellow-deep); }
-.cg-detail-star:hover { border-color: var(--lp-line); color: var(--lp-yellow-deep); }
-.cg-detail-star:disabled { cursor: default; opacity: 0.55; }
+/* ---------------------------------------------------------------------------
+   customer-grid / rowStar.css — W35-T29 (rulings R5, R6), the record star.
+
+   ⛔ ITS OWN SHEET, AND THE REASON IS OWNERSHIP RATHER THAN TIDINESS. `.cg-row-expand`, the hover
+   control this one sits beside, lives in `index.css`, which belongs to another lane this wave. A
+   new surface brings its own stylesheet (the wave's own rule) and a change to an existing
+   `.cg-*` rule is that lane's ticket.
+
+   ⚠ IMPORTED BY `CustomerGrid.tsx`, the module that RENDERS these classes — never by a lazy
+   parent. W35-T22 in this same wave was exactly that mistake one directory over: `query.css` was
+   imported only by a `lazy()` page while the component drawing its classes shipped in another
+   chunk, so the rail painted unstyled for a network round trip.
+   --------------------------------------------------------------------------- */
+
+/* ⭐ The hover control IMMEDIATELY TO THE LEFT OF THE EXPAND BUTTON, at the right end of the
+   primary cell and level with it — owner instruction 29 (wave 40, 2026-08-24). It REVERSES
+   W35-T29 (R5, R6), which deliberately put this mark at the LEFT end so the two book-ended
+   the cell; that line stood right here and is gone because the code no longer does it.
+   Both are real DOM buttons laid over the canvas at glide's own bounds, so the rect IS the
+   hit test and there is no second copy of the geometry to drift from the drawing.
+
+   ⚠ NO GEOMETRY LIVES IN THIS SHEET. `left`/`top`/`width`/`height` are written inline from
+   `starButtonRect`, which now derives them from `expandButtonRect` — so the reversal is a
+   change of arithmetic, not of style, and nothing here had to move with it. */
+.cg-row-star {
+  position: fixed;
+  z-index: 55;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--lp-r-sm);
+  background: transparent;
+  color: var(--lp-muted);
+  cursor: pointer;
+}
+
+/* ⛔ A STARRED ROW'S MARK IS NOT HOVER-ONLY. The hover control is how you SET one; a row that is
+   already starred has to say so while the pointer is elsewhere, or the grid cannot answer the
+   question the feature exists for. D-253 is a booked defect whose whole content is "satisfied
+   only on hover" — this is that lesson applied to a mark rather than to an explanation.
+   The always-on mark is drawn by the same button with `is-on`; the caller keeps it mounted for a
+   starred row whether or not the pointer is over it. */
+.cg-row-star.is-on {
+  color: var(--lp-yellow-deep);
+}
+
+.cg-row-star:hover {
+  border-color: var(--lp-line);
+  background: var(--cg-white);
+  color: var(--lp-yellow-deep);
+}
+
+.cg-row-star:focus-visible {
+  outline: 2px solid var(--lp-blue-deep);
+  outline-offset: 1px;
+}
+
+.cg-row-star:disabled {
+  cursor: default;
+  opacity: 0.55;
+}
+
+/* The drawer's own copy of the control (`RecordDetail`), which is in the flow rather than over a
+   canvas — so it takes the colour rules above and none of the positioning.
+   ⭐ OWNER ITEM 12 (2026-08-23) — it now sits INSIDE `.cg-detail-nav`, beside the prev/next keys,
+   so it is sized and bordered like them: a group of three buttons reads as a group only if the
+   third one is the same shape. The border is transparent until hover, which is what still tells
+   an ACTION apart from the two NAVIGATION keys beside it. */
+.cg-detail-star {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--lp-r-md);
+  background: transparent;
+  color: var(--lp-muted);
+  cursor: pointer;
+}
+
+.cg-detail-star.is-on { color: var(--lp-yellow-deep); }
+.cg-detail-star:hover { border-color: var(--lp-line); color: var(--lp-yellow-deep); }
+.cg-detail-star:disabled { cursor: default; opacity: 0.55; }

web/src/customer-grid/types.ts

@@ -201,6 +201,81 @@ export const CREATABLE_TYPES: readonly FieldType[] = [
   "ai_enrich",
 ];
 
+/**
+ * ⭐⭐ W40-T29 (owner instruction 31) — WHICH CREATE KINDS READ AS ADVANCED. Three of them, and
+ * the whole discipline of this block is that the answer is a PRESENTATION grouping and nothing
+ * else.
+ *
+ * ⛔ THE LIST ABOVE IS NOT PARTITIONED, AND MUST NEVER BE. `CREATABLE_TYPES` is one half of a
+ * cross-language contract `verify_fields_contract.py` diffs against `aios_grid.CUSTOM_FIELD_TYPES`,
+ * and the `json` scar recorded in its own comment is exactly what happens when a type reaches every
+ * table except that one: real, documented, unreachable, with every individual file internally
+ * consistent. Lifting `automation` and `json` out of it into an "advanced list" would reproduce
+ * that failure deliberately. So the grouping is applied to the ROWS the picker has already built,
+ * at render time, and the contract array is READ, never rewritten.
+ *
+ * ⚠ `automation` and `json` are typed `FieldType`, so a typo fails `tsc`. `geocode` cannot be:
+ * it is a PSEUDO-KIND (see `Field.geocode` for why five vocabularies stay untouched by it) and no
+ * compiler can hold it. The asymmetry is honest rather than an oversight, and it is the reason the
+ * exported set below is `string[]` while its first half is not.
+ */
+const ADVANCED_FIELD_KINDS: readonly FieldType[] = ["automation", "json"];
+
+/** The advanced set the picker groups on: the two real types above plus the geocode pseudo-kind,
+ *  which joins by VALUE because it cannot join by type. */
+export const ADVANCED_CREATE_KINDS: readonly string[] = [...ADVANCED_FIELD_KINDS, "geocode"];
+
+/**
+ * The group's heading. ONE WORD: `DESIGN.md` §4 forbids over-explaining, so the list does not get
+ * a sentence about what makes a type advanced.
+ * ⚠ Not "ADVANCED" — `CLAUDE.md` bans ALL-CAPS app chrome. The owner spelled it in capitals in
+ * instruction 31; that is emphasis in prose, not a label.
+ */
+export const ADVANCED_TYPES_HEADING = "Advanced";
+
+/** A run of field-type picker rows under an optional heading. `heading: null` is the ordinary
+ *  group, deliberately unlabelled: naming the majority case is chrome nobody reads, and the
+ *  divider under it already says where the ordinary list ends. */
+export interface TypePickerGroup<T> {
+  heading: string | null;
+  rows: T[];
+}
+
+/**
+ * ⭐⭐ W40-T29 — split a flat field-type picker list into the ordinary rows and the advanced ones.
+ *
+ * It lives in this file, and not in `ColumnMenu.tsx` where it is rendered, for the reason
+ * `display.ts`'s header states at length: `ColumnMenu.tsx` imports React and therefore cannot be
+ * LOADED by the node gates, so a rule stated inside JSX is a rule no gate can run. `columnDefinitionOffer`
+ * had to settle for `display.ts` because this file was held by another lane that wave; the two
+ * belong together and this one made it home.
+ *
+ * ⛔ A STABLE PARTITION, NEVER A SORT. Each group keeps the order it was handed, so the ordinary
+ * group reads in `CREATABLE_TYPES`' own order and the advanced group in the order those three
+ * happen to sit in the caller's list. Re-ordering here would be a second opinion about a
+ * vocabulary that already has an owner, and the day someone reorders the contract array the
+ * picker would silently disagree with it.
+ *
+ * ⛔ AN EMPTY GROUP IS OMITTED ENTIRELY, and that is R8's fake-affordance rule rather than
+ * tidiness: the caller filters this list through a find box, so typing "text" empties the advanced
+ * group, and a heading left standing over nothing is a label with nothing behind it. Deciding it
+ * here rather than in JSX is also what makes the behaviour runnable by a node gate instead of
+ * being an accident of a CSS `:empty` selector.
+ */
+export function groupTypePickerRows<T extends { value: string }>(
+  rows: readonly T[]
+): TypePickerGroup<T>[] {
+  const ordinary: T[] = [];
+  const advanced: T[] = [];
+  for (const row of rows) {
+    (ADVANCED_CREATE_KINDS.includes(row.value) ? advanced : ordinary).push(row);
+  }
+  const out: TypePickerGroup<T>[] = [];
+  if (ordinary.length) out.push({ heading: null, rows: ordinary });
+  if (advanced.length) out.push({ heading: ADVANCED_TYPES_HEADING, rows: advanced });
+  return out;
+}
+
 /**
  * ⭐ Wave-19 R7 / C5 — THE THREE THINGS AN `image` CELL MAY HOLD, and how each resolves.
  *
@@ -3397,6 +3472,35 @@ export interface SavedView {
   /** C1 — whose view this is, when it is not mine. The username, so it matches what every
    *  grant is stored against (see `shareModel.parsePeople`'s note on the two shapes). */
   owner?: string;
+  /**
+   * ⭐⭐ WAVE 40 · AM-5 (owner instruction 2) — THIS VIEW HAS GRANTS, WHOEVER IS ASKING.
+   *
+   * Viewer-INDEPENDENT, and it is what draws the share mark. C1 was written as "redefine
+   * `shared` to mean this view has grants"; AM-5 settles it as a NEW key instead, because
+   * redefining `shared` would have locked an owner out of their own view through
+   * `mayEditView` and moved it into the recipient's "Shared with me" group. So `shared`
+   * keeps meaning "granted TO me" and this means "somebody can see this".
+   *
+   * ⛔ ABSENCE IS THE NEGATIVE. Nothing is ever stamped `false`; a view with no grants
+   * simply carries neither key. Produced by `platform/core/grid_events.py::_grant_marker`
+   * on all three merge legs from one predicate, and derived on every read from the grant
+   * registry rather than stored.
+   *
+   * ⚠ IT DOES NOT IMPLY `sharedRole`. A view living BOTH in the legacy `__shared__` bucket
+   * and in the grant registry reaches the recipient with `hasShares` and no role stamp,
+   * because the bucket leg outranks the granted copy. `viewShareMark` has a third branch
+   * for exactly that, and it must not be collapsed into the other two.
+   */
+  hasShares?: boolean;
+  /**
+   * ⭐ WAVE 40 · AM-5 — THIS ACCOUNT IS THE ONE SHARING IT OUT.
+   *
+   * Only ever on the sharer's copy, which is how the owner's tooltip can read as sharing OUT
+   * without reusing the receiver wording C1 forbids. Unconditional on the caller's own
+   * stratum, `createdBy == uname` on the `__shared__` leg, and NEVER on a view arriving
+   * through `_granted_views`.
+   */
+  sharedOut?: boolean;
   /** C4 — the folder this view sits in; null/absent = root. */
   folderId?: string | null;
   id: string;
@@ -3477,6 +3581,62 @@ export function allViewName(scope: string): string {
   return scope === "product" ? "All products" : "All customers";
 }
 
+/**
+ * ⭐⭐ WAVE 40 · T28 (owner instruction 30) — WHAT THE PINNED SYSTEM VIEW IS CALLED ON SCREEN.
+ *
+ * Owner: *"Rename 'All customers' and every other undeletable default view to 'Default view'."*
+ * Per assumption A2 that is the PER-DATABASE default ONLY. `UNDELETABLE_VIEW_IDS` holds three
+ * ids, and renaming all three would put three rows reading "Default view" in one rail, which is
+ * a worse rail than the one the instruction is fixing. Starred and IG Overview keep the names
+ * their own servers mint; they pin to the top beside this one and are told apart by their names.
+ */
+export const DEFAULT_VIEW_NAME = "Default view";
+
+/**
+ * ⛔ THE HOST'S OWN MINTS, DERIVED RATHER THAN RE-SPELLED, so the three nouns keep exactly one
+ * home on this side of the wire. `aios_grid.views_from_defs(system_name=…)` produces the same
+ * three strings; this set is what {@link viewDisplayName} recognises as "still the mint, nobody
+ * has renamed it".
+ */
+const SYSTEM_VIEW_MINTS = new Set([
+  allViewName("customer"),
+  allViewName("product"),
+  allViewName("ut_"),
+]);
+
+/**
+ * ⭐⭐ WAVE 40 · T28 — the name to PAINT for a view, which is not always the name stored on it.
+ *
+ * ⛔ A DISPLAY RULE, NOT A RENAME, and that distinction is the whole reason this function exists
+ * instead of a changed `allViewName`. `views_from_defs` still mints the system view as "All
+ * customers" / "All products" / "All records", and that host half is in NO lane's fence this
+ * wave. A client that minted a different string would disagree with the echo and repaint the
+ * rail on every workspace arrival — the flicker `allViewName`'s own note refuses one paragraph
+ * up. Resolving at the point of PAINT collapses both spellings onto ONE output, so the rail
+ * shows the same characters whether the name came from this browser's mint or from the host's
+ * echo, and there is no frame in which the two differ. When the host half lands, "Default view"
+ * is not in the mint set and passes through verbatim, so the two stay in step through the change.
+ *
+ * ⛔ IT MUST NOT CLOBBER A USER'S RENAME, and `all-customers` really IS renamable — this was
+ * checked rather than assumed. `grid_events.py`'s `view_upsert` exempts it from the reserved-name
+ * list by id (`if view_id != 'all-customers'`), and a saved record under the pinned id REPLACES
+ * the projection through the ordinary saved-config overlay, so a rename of the default view
+ * persists and means what it says. The override therefore fires only while the stored name is
+ * STILL one of the mints — or empty, which is what a half-assembled workspace carries. Anything
+ * a person typed passes through unchanged.
+ *
+ * ⚠ SCOPE-FREE, deliberately. The rail has no `scope` prop, and threading one in would give this
+ * decision two homes; more importantly a stale echo carrying another topic's noun must still
+ * resolve, rather than leaking "All records" onto a customer rail for one round trip.
+ *
+ * ⚠ ONLY `ALL_VIEW_ID`. A2 in one line: every other id, undeletable or not, keeps its own name.
+ */
+export function viewDisplayName(view: Pick<SavedView, "id" | "name">): string {
+  if (view.id !== ALL_VIEW_ID) return view.name;
+  const stored = view.name ?? "";
+  return stored === "" || SYSTEM_VIEW_MINTS.has(stored) ? DEFAULT_VIEW_NAME : stored;
+}
+
 /**
  * The ONE rule for "this view cannot be deleted", mirroring what the host actually enforces
  * (`app.py:5410` refuses `view_delete` for `all-customers`). The client hides exactly what
@@ -3746,7 +3906,10 @@ export function viewEditMode(view: Pick<SavedView, "permissions">): ViewEditMode
  * at the host, not merely hidden here.
  */
 export function mayEditView(
-  view: Pick<SavedView, "permissions" | "createdBy" | "shared" | "sharedRole">,
+  // `owner` joined this Pick with wave 40's C1 and STAYS, although the guard below no longer
+  // reads it: the field is part of what a caller must be able to hand this function, and
+  // narrowing the type back would be a second change with its own blast radius.
+  view: Pick<SavedView, "permissions" | "createdBy" | "shared" | "sharedRole" | "owner">,
   viewer: Viewer | undefined
 ): boolean {
   /**
@@ -3772,6 +3935,31 @@ export function mayEditView(
    * ONE place, three consumers: the rail's row menu, the rail's drag, and the grid's own
    * delete/config-write guards all ask this function. Putting the rule in any one of them
    * would leave the other two offering an edit the server refuses.
+   *
+   * ⭐⭐ WAVE 40 · CONTRACT C1 (owner instruction 2) — THIS GUARD BRIEFLY READ
+   * `view.shared && view.owner && …`, AND THE `&& view.owner` IS GONE AGAIN. Recorded rather
+   * than quietly reverted, because the reasoning that added it was sound and only its PREMISE
+   * was wrong, and the next person reading C1 will reach for it again.
+   *
+   * The premise was that C1 would REDEFINE `shared` to mean "this view has grants" and stamp it
+   * on the sharer's own leg too. On such a leg there is no `sharedRole` (ownership is not a
+   * grant), `?? "view"` would read read-only, and this line would have locked an owner out of
+   * every view they had ever shared. `owner` was added as the discriminator, since it already
+   * means "whose view this is, WHEN IT IS NOT MINE".
+   *
+   * ⛔ BUT `shared` WAS NEVER REDEFINED. AM-5 settles C1 the other way: the marker is a NEW
+   * key, `hasShares`, and `shared` / `sharedRole` / `owner` keep meaning "granted TO me, and on
+   * what terms". Verified in the server, not inferred: `core/grid_events.py` writes `shared` on
+   * exactly two lines, both inside `_granted_views`, both after `if owner == uname: continue`,
+   * and both stamping `sharedRole` and `owner` in the same three statements. The sharer's own
+   * leg gets `hasShares` and `sharedOut` and NEVER `shared`.
+   *
+   * ⛔ SO THE EXTRA CONDITION PROTECTED AGAINST NOTHING AND COST A FAIL-CLOSED CHECK. With it,
+   * any `shared` view reaching the client without an `owner` fell through and read as EDITABLE.
+   * `folders.test` had asserted the opposite since wave 21 and went red on all four of its C1
+   * legs — "a view-role share is NOT editable", "…not by an ADMIN either", "…and not via the
+   * unstamped-createdBy escape hatch", "a shared view with NO role reads as read-only". The
+   * gate was right. Read those four names as this line's negative control.
    */
   if (view.shared && (view.sharedRole ?? "view") !== "edit") return false;
   const mode = viewEditMode(view);

web/src/customer-grid/useGridColumns.ts

@@ -1,422 +1,483 @@
-import { useCallback, useMemo } from "react";
-import type { GridColumn, Theme } from "@glideapps/glide-data-grid";
-import type { Field, FilterNode, ViewConfig } from "./types";
-import { isFilterGroup, isRuleActive, measureColumnIndex, ruleColumnKeys } from "./types";
-import { typeIconName } from "./iconShapes";
-import { fitHeaderTitle, headerLabelSpace, headerMarkSizes } from "./overlayPlacement";
-import { COLUMN_TONE_THEME, INVOLVED_HEADER_FONT, lightTheme } from "./theme";
-import type { ControlTone } from "./theme";
-
-const DEFAULT_WIDTH = 150;
-
-/**
- * Owner item 16 — measure header text in GLIDE'S OWN HEADER FONT.
- *
- * ⚠ NOT the cell font. Glide's `headerFontStyle` is "600 13px" and its `baseFontStyle` is
- * "13px" (`common/styles.js:73-75`); semibold is materially wider, so measuring with the cell
- * font under-measures, under-truncates, and leaves the label running under the (i) — the exact
- * defect this item is about, surviving a fix that looked correct in the diff.
- *
- * ⚠⚠ Wave-14 item 2 adds the SAME trap one weight up. An involved column paints its header at
- * **700** (`INVOLVED_HEADER_FONT`), so measuring every column at 600 would under-truncate
- * exactly the filtered/sorted/grouped columns — the ones the owner is looking at. Hence TWO
- * cached contexts, and both font strings are read off the theme layer rather than retyped here:
- * a literal in this file is a copy that can drift from the one glide actually paints with, which
- * is the whole failure mode above.
- *
- * ⚠ Wave-15 R5 gave each control its OWN hue, so there are now three involved-column themes
- * instead of one. They deliberately share `INVOLVED_HEADER_FONT`, so ONE bold context still
- * measures all three correctly — but the constant, not any one of the three theme objects, is
- * what this reads. Picking `COLUMN_TONE_THEME.filter.headerFontStyle` would have measured every
- * involved column against whichever tone happened to be listed first.
- *
- * One lazily-built offscreen context per weight, the same shape as CustomerGrid's
- * `measureCellText`. A context can legitimately be null (a headless canvas, a locked-down
- * embed); 0 then measures as "everything fits" and no title is truncated, which is the safe
- * direction to fail — a title that slightly overlaps beats one silently cut to "C…".
- */
-const _hdrCtx: Record<"base" | "bold", CanvasRenderingContext2D | null | undefined> = {
-  base: undefined,
-  bold: undefined,
-};
-function measureHeaderText(text: string, bold = false): number {
-  const slot = bold ? "bold" : "base";
-  if (_hdrCtx[slot] === undefined) {
-    const ctx = document.createElement("canvas").getContext("2d");
-    if (ctx) {
-      const style =
-        (bold ? INVOLVED_HEADER_FONT : lightTheme.headerFontStyle) ?? "600 13px";
-      ctx.font = `${style} ${lightTheme.fontFamily ?? "Inter, sans-serif"}`;
-    }
-    _hdrCtx[slot] = ctx;
-  }
-  const ctx = _hdrCtx[slot];
-  return ctx ? ctx.measureText(text).width : 0;
-}
-
-/** The (i) is drawn for exactly this condition — `CustomerGrid.drawGridHeader` resolves the
- *  same one from the same field, so the reserve and the mark can never disagree. */
-function hasInfoMark(field: Field): boolean {
-  return !!(field.note || field.description);
-}
-
-/** Every column key an ACTIVE filter rule names, anywhere in the tree. Inactive (half-typed)
- *  rules are skipped: a rule that is not narrowing anything must not tint a column as though
- *  it were — that is the same "it looks like it is working" lie the engine refuses to tell.
- *
- *  ⚠ Wave-20 item 2: the key a rule NAMES is not always the column it is ABOUT — a measure
- *  condition carries the MEASURE key. `ruleColumnKeys` is the one resolution (types.ts); it
- *  is what stopped a filtered-and-sorted measure column wearing the sort hue. */
-function filteredKeys(
-  nodes: FilterNode[],
-  out: Set<string>,
-  measureCols: Map<string, string[]>
-): void {
-  for (const node of nodes ?? []) {
-    if (isFilterGroup(node)) {
-      filteredKeys(node.children, out, measureCols);
-      continue;
-    }
-    if (isRuleActive(node)) for (const key of ruleColumnKeys(node, measureCols)) out.add(key);
-  }
-}
-
-/**
- * The column's theme override, or `undefined` — glide's fast path for "no override" is an absent
- * object, so an empty `{}` would cost a ~35-key theme merge per column per frame.
- *
- * ⚠ Wave-14 item 1 (R11): a user-created field contributes no theme. Its yellow header wash is
- * dead and its replacement is a painted DOT, not a background — so the only thing that can put a
- * themeOverride on a column is being INVOLVED in a control.
- *
- * ⚠ Wave-15 R5: the returned object is one of the three SHARED `COLUMN_TONE_THEME` references
- * (never a fresh object), which is what keeps glide's theme merge cache-friendly across frames.
- *
- * ⛔ Wave-29 R8 (2026-08-11): those three references now carry **HEADER keys only**. glide builds a
- * header theme from the column override alone and a cell theme from column → row → cell
- * (`data-grid-render.header.js:59`, `common/styles.js mergeAndRealizeTheme`), so the tone reaching
- * a column theme is exactly how a sort used to repaint record bodies. With no `bgCell` in the
- * table there is no longer a path from "this column is sorted" to a cell's background at all —
- * which is a property of what `COLUMN_TONE_THEME` CONTAINS, not of anything this function does.
- * A body wash belongs to `getRowThemeOverride` (status) or the cell itself (automation).
- */
-function columnTheme(tone: ControlTone | undefined): Partial<Theme> | undefined {
-  return tone ? COLUMN_TONE_THEME[tone] : undefined;
-}
-
-/**
- * Owner item 22 — key → which control involves it, or absent.
- *
- * ⚠ ONE tone per column, and the precedence is a decision, not an accident: **filter > sort >
- * group** (owner R6, wave 15). A filter changes WHICH ROWS you are looking at; when a column is
- * doing two jobs the header names the most consequential one. Blending two tints would produce a
- * third colour that matches no chip in the toolbar, which is worse than picking.
- *
- * ⚠ THE PRECEDENCE IS THE WRITE ORDER BELOW, and it reads backwards: later `set` calls WIN, so
- * the least important control is written FIRST. It was `sort, group, filter` — i.e. filter >
- * group > sort — until R6 named the order explicitly; getting this wrong is a one-line edit that
- * changes a colour on screen and nothing else, so it is stated here rather than left to be
- * re-derived from the sequence.
- */
-/* wave17 GRID — item 2 / owner R5. EXPORTED, and only since the row band died.
-   `activeControlTone` used to sit below this function and restate the same precedence for the
-   whole-table band; the band was its only consumer, so R5 took both. That left the surviving
-   precedence — the one that still paints — asserted by nothing, because `verify_icons` was
-   testing the twin. Exported so the gate can reach the function that is actually on screen. */
-export function columnTones(
-  config: ViewConfig,
-  /* wave20 item 2 — the FIELDS, because a measure condition names its measure and only the
-     field list can say which column displays it. Defaulted so the signature stays callable
-     with a config alone (the pre-wave-20 gate legs), and because a caller with no fields
-     legitimately has no measure columns to resolve. */
-  fields: Field[] = []
-): Map<string, ControlTone> {
-  const out = new Map<string, ControlTone>();
-  if (config.groupBy) out.set(config.groupBy, "group");
-  for (const s of config.sorts ?? []) out.set(s.colId, "sort");
-  const filtered = new Set<string>();
-  filteredKeys(config.filters ?? [], filtered, measureColumnIndex(fields));
-  for (const key of filtered) out.set(key, "filter");
-  return out;
-}
-
-/**
- * ⭐ WAVE 30 (owner item 2 scouting) — THE OVERLAY ARM IS GONE, and the arithmetic is the reason.
- *
- * This read `field.default !== false || field.source === "overlay"`. The second arm was written
- * when `overlay` meant "a column a user added here", and those columns have no `default` key at
- * all — so the arm was a belt-and-braces no-op for them. Then `user_tables._clean_field` started
- * stamping `source: "overlay"` on EVERY `ut_*` field, and every connected database became a `ut_*`
- * one: the exception quietly became the rule and swallowed the first arm entirely.
- *
- * ⛔ WHAT THAT COST, measured on the live orders grid: `odoo_relational.order_fields` declares
- * `default: False` on `odoo_id`, `state`, `customer_link` and `partner_id`, and every one of them
- * opened SHOWN. The grid arrives wide, and "Hide fields" reads inactive because
- * `shownCount === fields.length` — so the control that says "some columns are hidden" says the
- * opposite of what its own table declares. A second instance of [[fallback-that-became-the-rule]].
- *
- * ⚠ DROPPING THE ARM DOES NOT HIDE USER COLUMNS, and this is the check that matters before
- * believing the fix. A column somebody created carries no `default` key, `undefined !== false` is
- * true, and it stays visible. `_clean_field` also keeps `default` ONLY when it is `True`, so a
- * `ut_*` column can never arrive carrying `default: false` by accident — only a shipped field
- * CONTRACT (which is written straight into the store, bypassing that validator) can declare it.
- *
- * ⚠ THIS PREDICATE HAS A SERVER TWIN and the twin is the one that decides on first open:
- * `platform/aios_grid.py:_default_view_config` carries the same expression and builds the "All
- * records" system view the client pins as its landing default. Fixing one side alone changes
- * nothing a user sees — see `mailbox/F.md` F-1 ([[one-question-two-normalizers]] across two
- * languages).
- */
-function isDefaultVisible(field: Field): boolean {
-  if (field.default === false) return false;
-  /**
-   * ⭐⭐ OWNER, 2026-08-23 — A NEW VIEW SHOWS THE DATABASE'S OWN COLUMNS AND NOTHING ELSE.
-   *
-   * Owner: *"when any new View is created only shareable pre-set data should show. Shared to me
-   * or Shared to everyone should be auto hidden."*
-   *
-   * ⛔ `custom || shared` IS THE WHOLE PREDICATE, and it is chosen because it is exactly the
-   * membership test `FieldsHidePanel` already uses to draw its two SHARED sections:
-   *     "Shared with me"       (field.custom || field.shared) && fieldEditMode === "users"
-   *     "Shared with everyone" (field.custom || field.shared) && fieldEditMode === "collaborative"
-   * Both sections are subsets of `custom || shared`, so hiding on that flag hides both by
-   * construction rather than by keeping a second list of section names in step with the panel.
-   *
-   * ⚠ IT ALSO HIDES THE UNTITLED SECTION'S CREATED COLUMNS, and that is deliberate rather than
-   * over-reach. A route order carries `shared: true` with `edit: personal`, so it is filed under
-   * no heading at all — and 52 of them landed on the customer grid the same day this was asked
-   * for. The owner's first sentence is the rule ("ONLY pre-set data shows"); the second names the
-   * two headings, it does not bound the set.
-   *
-   * ⚠ MEASURED ON THE LIVE CUSTOMER GRID before it was written: of 105 fields, 77 opened SHOWN.
-   * 52 route columns, 14 collaborative `custom_*`, 3 `measure_*`, one legacy route and 7 plain
-   * Odoo columns. After this, the 7 remain — which is precisely what
-   * `aios_grid_fields.json` declares as `default: true`, i.e. the contract's own answer before
-   * anybody's columns piled on top of it.
-   *
-   * ⛔⛔ A STORED VIEW IS UNTOUCHED. `normalizeConfig` spreads the saved `config` OVER this
-   * base, so a view that already recorded its own `visible` keeps it. What moves is a view born
-   * without one: the "All records" system view, a new view, a cohort view.
-   */
-  if (field.custom === true || field.shared === true) return false;
-  return true;
-}
-
-export function defaultViewConfig(fields: Field[]): ViewConfig {
-  const shown = fields.filter(isDefaultVisible).map((field) => field.key);
-  const hidden = fields.filter((field) => !isDefaultVisible(field)).map((field) => field.key);
-  return {
-    filters: [],
-    filterConj: "and",
-    sorts: [],
-    groupBy: null,
-    colorBy: null,
-    rowHeightMode: "short",
-    order: [...shown, ...hidden],
-    visible: shown,
-    widths: {},
-    memberPids: [],
-  };
-}
-
-function reconcileOrder(order: string[], fields: Field[]): string[] {
-  const valid = new Set(fields.map((field) => field.key));
-  const kept = order.filter((key, index) => valid.has(key) && order.indexOf(key) === index);
-  for (const field of fields) if (!kept.includes(field.key)) kept.push(field.key);
-  const locked = fields.find((field) => field.pinned)?.key ?? fields[0]?.key;
-  if (locked && kept[0] !== locked) {
-    const without = kept.filter((key) => key !== locked);
-    return [locked, ...without];
-  }
-  return kept;
-}
-
-function reconcileVisible(visible: string[], fields: Field[], lockedKey: string): Set<string> {
-  const valid = new Set(fields.map((field) => field.key));
-  const out = new Set(visible.filter((key) => valid.has(key)));
-  if (out.size === 0) {
-    for (const field of fields) if (isDefaultVisible(field)) out.add(field.key);
-  }
-  if (lockedKey) out.add(lockedKey);
-  return out;
-}
-
-export interface GridColumnsApi {
-  visibleCols: GridColumn[];
-  fieldByKey: Map<string, Field>;
-  order: string[];
-  visible: Set<string>;
-  widths: Record<string, number>;
-  lockedKey: string;
-  onColumnResize: (col: GridColumn, newSize: number) => void;
-  onColumnMoved: (from: number, to: number) => void;
-  onColumnProposeMove: (from: number, to: number) => boolean;
-  setColumnVisible: (key: string, show: boolean) => void;
-  insertColumn: (key: string, anchorKey: string | null, side: "left" | "right" | "end") => void;
-}
-
-/**
- * Controlled column adapter. ViewConfig is the durable source of truth, so
- * choosing a saved view is one atomic state change instead of a chain of hook
- * setters that can flash or overwrite one another.
- */
-export function useGridColumns(
-  fields: Field[],
-  config: ViewConfig,
-  onConfig: (next: ViewConfig) => void
-): GridColumnsApi {
-  const fieldByKey = useMemo(
-    () => new Map(fields.map((field) => [field.key, field])),
-    [fields]
-  );
-  const lockedKey = useMemo(
-    () => fields.find((field) => field.pinned)?.key ?? fields[0]?.key ?? "",
-    [fields]
-  );
-  const order = useMemo(() => reconcileOrder(config.order, fields), [config.order, fields]);
-  const visible = useMemo(
-    () => reconcileVisible(config.visible, fields, lockedKey),
-    [config.visible, fields, lockedKey]
-  );
-
-  // Item 22 — recomputed only when the three controls move, not on every width drag.
-  // Wave-20 item 2 adds `fields`: a measure condition can only be resolved to the column that
-  // displays it, and a new measure column must re-tint without waiting for a control to move.
-  const tones = useMemo(
-    () => columnTones(config, fields),
-    [config.filters, config.sorts, config.groupBy, fields]  // eslint-disable-line react-hooks/exhaustive-deps
-  );
-
-  const visibleCols = useMemo<GridColumn[]>(
-    () =>
-      order
-        .filter((key) => visible.has(key))
-        .map((key) => {
-          const field = fieldByKey.get(key)!;
-          const width = config.widths[key] ?? DEFAULT_WIDTH;
-          // Wave-14 item 2 — an INVOLVED column's header paints at 700, so it must be MEASURED
-          // at 700. `tones` is already a dep of this memo, so this costs nothing.
-          const involved = tones.has(key);
-          // R11 — the marks this header carries, in the strip's canonical order. Both this
-          // reserve and `CustomerGrid.drawGridHeader`'s painting read `headerMarkSizes`, so a
-          // column can never reserve room for one mark and then be given two.
-          const marks = headerMarkSizes(hasInfoMark(field), field.source === "overlay");
-          return {
-            id: key,
-            // Owner item 16 — ELLIPSISED so the title can never run under the (i). Glide
-            // truncates nothing: `drawHeaderInner` calls `fillText(c.title, …)` with no clip
-            // and no max width, so on a narrow column the name simply painted through the
-            // mark. Shortening the title glide is given is the whole fix — the alternative,
-            // clipping inside `drawHeader`, cuts mid-glyph with no ellipsis to say it did.
-            // The FULL name stays reachable: CustomerGrid's header tip leads with it whenever
-            // this returns something shorter than `field.label`.
-            title: fitHeaderTitle(
-              field.label,
-              headerLabelSpace(width, marks),
-              (text) => measureHeaderText(text, involved)
-            ),
-            width,
-            hasMenu: true,
-            menuIcon: "dots",
-            // Wave-8 I20 — the field-TYPE mark leads every header, so the column says what
-            // KIND of thing it holds before you read a single cell (same geometry as the
-            // Fields panel's rows — icons.tsx).
-            icon: typeIconName(field.type),
-            // Wave-9 I3 — the (i) is NO LONGER `overlayIcon`. Glide draws an overlay at a
-            // hard-coded offset from the TYPE mark (drawHeaderInner: `drawX + 9`), i.e.
-            // pinned to the far LEFT of the header, and no prop moves it; the owner asked
-            // for it right-aligned and centred with the field name. It is drawn instead by
-            // CustomerGrid's `drawHeader` callback, which resolves the same
-            // `field.note || field.description` condition from the field itself.
-            // The hover text is still CustomerGrid's floating tip (pointer-events: none —
-            // a tooltip must never swallow the next click, [[ui-invisible-to-assertions]]).
-            // Wave-14 R4 — being INVOLVED in a filter/sort/group is the only thing that tints a
-            // column now, and all three tint it the same faint warm grey; the hue that says
-            // WHICH control lives on the toolbar chip. User-created ownership moved out of the
-            // theme entirely and is the dot drawn in the mark strip (R11).
-            themeOverride: columnTheme(tones.get(key)),
-          };
-        }),
-    [order, visible, config.widths, fieldByKey, tones]
-  );
-
-  const onColumnResize = useCallback(
-    (column: GridColumn, newSize: number) => {
-      if (!column.id) return;
-      onConfig({
-        ...config,
-        widths: { ...config.widths, [column.id]: Math.round(newSize) },
-      });
-    },
-    [config, onConfig]
-  );
-
-  const onColumnMoved = useCallback(
-    (from: number, to: number) => {
-      if (from === 0 || to === 0) return;
-      const visibleKeys = order.filter((key) => visible.has(key));
-      if (
-        from < 0 ||
-        from >= visibleKeys.length ||
-        to < 0 ||
-        to >= visibleKeys.length
-      )
-        return;
-      const movedKeys = visibleKeys.slice();
-      const [moved] = movedKeys.splice(from, 1);
-      movedKeys.splice(to, 0, moved);
-      let index = 0;
-      const nextOrder = order.map((key) =>
-        visible.has(key) ? movedKeys[index++] : key
-      );
-      onConfig({ ...config, order: nextOrder });
-    },
-    [config, onConfig, order, visible]
-  );
-
-  const onColumnProposeMove = useCallback(
-    (from: number, to: number) => from !== 0 && to !== 0,
-    []
-  );
-
-  const setColumnVisible = useCallback(
-    (key: string, show: boolean) => {
-      if (!show && key === lockedKey) return;
-      const next = new Set(visible);
-      if (show) next.add(key);
-      else next.delete(key);
-      onConfig({ ...config, visible: [...next] });
-    },
-    [config, lockedKey, onConfig, visible]
-  );
-
-  const insertColumn = useCallback(
-    (key: string, anchorKey: string | null, side: "left" | "right" | "end") => {
-      const nextOrder = order.filter((item) => item !== key);
-      if (side === "end" || !anchorKey) {
-        nextOrder.push(key);
-      } else {
-        const anchor = Math.max(0, nextOrder.indexOf(anchorKey));
-        nextOrder.splice(anchor + (side === "right" ? 1 : 0), 0, key);
-      }
-      const nextVisible = new Set(visible);
-      nextVisible.add(key);
-      onConfig({ ...config, order: nextOrder, visible: [...nextVisible] });
-    },
-    [config, onConfig, order, visible]
-  );
-
-  return {
-    visibleCols,
-    fieldByKey,
-    order,
-    visible,
-    widths: config.widths,
-    lockedKey,
-    onColumnResize,
-    onColumnMoved,
-    onColumnProposeMove,
-    setColumnVisible,
-    insertColumn,
-  };
-}
+import { useCallback, useMemo } from "react";
+import type { GridColumn, Theme } from "@glideapps/glide-data-grid";
+import type { Field, FilterNode, ViewConfig } from "./types";
+import { isFilterGroup, isMachineOwned, isRuleActive, measureColumnIndex,
+  ruleColumnKeys } from "./types";
+import { typeIconName } from "./iconShapes";
+import { fitHeaderTitle, hasShareMark, HEADER_MENU_SLOT, headerLabelSpace,
+  headerMarkSizes } from "./overlayPlacement";
+import { COLUMN_TONE_THEME, INVOLVED_HEADER_FONT, lightTheme } from "./theme";
+import type { ControlTone } from "./theme";
+
+const DEFAULT_WIDTH = 150;
+
+/**
+ * Owner item 16 — measure header text in GLIDE'S OWN HEADER FONT.
+ *
+ * ⚠ NOT the cell font. Glide's `headerFontStyle` is "600 13px" and its `baseFontStyle` is
+ * "13px" (`common/styles.js:73-75`); semibold is materially wider, so measuring with the cell
+ * font under-measures, under-truncates, and leaves the label running under the (i) — the exact
+ * defect this item is about, surviving a fix that looked correct in the diff.
+ *
+ * ⚠⚠ Wave-14 item 2 adds the SAME trap one weight up. An involved column paints its header at
+ * **700** (`INVOLVED_HEADER_FONT`), so measuring every column at 600 would under-truncate
+ * exactly the filtered/sorted/grouped columns — the ones the owner is looking at. Hence TWO
+ * cached contexts, and both font strings are read off the theme layer rather than retyped here:
+ * a literal in this file is a copy that can drift from the one glide actually paints with, which
+ * is the whole failure mode above.
+ *
+ * ⚠ Wave-15 R5 gave each control its OWN hue, so there are now three involved-column themes
+ * instead of one. They deliberately share `INVOLVED_HEADER_FONT`, so ONE bold context still
+ * measures all three correctly — but the constant, not any one of the three theme objects, is
+ * what this reads. Picking `COLUMN_TONE_THEME.filter.headerFontStyle` would have measured every
+ * involved column against whichever tone happened to be listed first.
+ *
+ * One lazily-built offscreen context per weight, the same shape as CustomerGrid's
+ * `measureCellText`. A context can legitimately be null (a headless canvas, a locked-down
+ * embed); 0 then measures as "everything fits" and no title is truncated, which is the safe
+ * direction to fail — a title that slightly overlaps beats one silently cut to "C…".
+ */
+const _hdrCtx: Record<"base" | "bold", CanvasRenderingContext2D | null | undefined> = {
+  base: undefined,
+  bold: undefined,
+};
+function measureHeaderText(text: string, bold = false): number {
+  const slot = bold ? "bold" : "base";
+  if (_hdrCtx[slot] === undefined) {
+    const ctx = document.createElement("canvas").getContext("2d");
+    if (ctx) {
+      const style =
+        (bold ? INVOLVED_HEADER_FONT : lightTheme.headerFontStyle) ?? "600 13px";
+      ctx.font = `${style} ${lightTheme.fontFamily ?? "Inter, sans-serif"}`;
+    }
+    _hdrCtx[slot] = ctx;
+  }
+  const ctx = _hdrCtx[slot];
+  return ctx ? ctx.measureText(text).width : 0;
+}
+
+/** The (i) is drawn for exactly this condition. */
+function hasInfoMark(field: Field): boolean {
+  return !!(field.note || field.description);
+}
+
+/**
+ * The user-created-field DOT's condition — owner item 4 (2026-08-06): *"why is the Field still
+ * have the Dot at the header to mark its a custom editable field?"*
+ *
+ * ⛔ `!isMachineOwned` is half of the rule, and it is the half that USED TO BE MISSING FROM THIS
+ * FILE. `source === "overlay"` alone is true of every column in a `ut_*` database, including the
+ * ones an automation spawns and fills, so the reserve kept room for a dot the drawer refused to
+ * paint. Nothing went red: over-reserving only shortens a title slightly, which is why it sat
+ * here through two waves. It is fixed by DELETION of the second copy, not by a second correction
+ * that could drift again — see `headerMarksFor`.
+ */
+function hasCustomMark(field: Field): boolean {
+  return field.source === "overlay" && !isMachineOwned(field);
+}
+
+/**
+ * ⭐ W40-T20 — THE header mark strip a field carries, resolved ONCE for both of its readers: this
+ * module's truncation RESERVE and `CustomerGrid.drawGridHeader`'s PAINTING.
+ *
+ * ⛔ WHY IT IS A FUNCTION AND NOT A COMMENT. What stood here before was the claim *"both this
+ * reserve and drawGridHeader's painting read `headerMarkSizes`, so a column can never reserve
+ * room for one mark and then be given two"* — and it was FALSE IN TWO WAYS at once. The two call
+ * sites each resolved the booleans themselves, and they had already diverged on the dot
+ * (`hasCustomMark` above); adding the share mark would have diverged them a second time, on the
+ * mark whose whole purpose is to sit INNERMOST, i.e. exactly where a wrong reserve lets a title
+ * paint through a glyph. A shared resolver is the only version of that sentence that stays true
+ * when the next mark is added.
+ *
+ * ⚠ `droppable` TRAVELS WITH `sizes` for the same reason. They are two halves of one answer:
+ * reserving for a strip of three while the drawer paints two puts the label's right edge in the
+ * wrong place, and reserving for three while the drawer ALSO refuses all three (the `droppable`
+ * mismatch) returns `null`, which means "do not truncate at all" and paints the full label
+ * straight through both surviving marks. Passing one without the other is worse than passing
+ * neither, so neither is passed alone.
+ */
+export function headerMarksFor(field: Field): {
+  info: boolean;
+  custom: boolean;
+  shared: boolean;
+  sizes: number[];
+  droppable: number;
+} {
+  const info = hasInfoMark(field);
+  const custom = hasCustomMark(field);
+  const shared = hasShareMark(field);
+  return {
+    info,
+    custom,
+    shared,
+    sizes: headerMarkSizes(info, custom, shared),
+    // Only the share mark may be given up, and only because it is innermost. See `headerMarkFit`.
+    droppable: shared ? 1 : 0,
+  };
+}
+
+/** Every column key an ACTIVE filter rule names, anywhere in the tree. Inactive (half-typed)
+ *  rules are skipped: a rule that is not narrowing anything must not tint a column as though
+ *  it were — that is the same "it looks like it is working" lie the engine refuses to tell.
+ *
+ *  ⚠ Wave-20 item 2: the key a rule NAMES is not always the column it is ABOUT — a measure
+ *  condition carries the MEASURE key. `ruleColumnKeys` is the one resolution (types.ts); it
+ *  is what stopped a filtered-and-sorted measure column wearing the sort hue. */
+function filteredKeys(
+  nodes: FilterNode[],
+  out: Set<string>,
+  measureCols: Map<string, string[]>
+): void {
+  for (const node of nodes ?? []) {
+    if (isFilterGroup(node)) {
+      filteredKeys(node.children, out, measureCols);
+      continue;
+    }
+    if (isRuleActive(node)) for (const key of ruleColumnKeys(node, measureCols)) out.add(key);
+  }
+}
+
+/**
+ * The column's theme override, or `undefined` — glide's fast path for "no override" is an absent
+ * object, so an empty `{}` would cost a ~35-key theme merge per column per frame.
+ *
+ * ⚠ Wave-14 item 1 (R11): a user-created field contributes no theme. Its yellow header wash is
+ * dead and its replacement is a painted DOT, not a background — so the only thing that can put a
+ * themeOverride on a column is being INVOLVED in a control.
+ *
+ * ⚠ Wave-15 R5: the returned object is one of the three SHARED `COLUMN_TONE_THEME` references
+ * (never a fresh object), which is what keeps glide's theme merge cache-friendly across frames.
+ *
+ * ⛔ Wave-29 R8 (2026-08-11): those three references now carry **HEADER keys only**. glide builds a
+ * header theme from the column override alone and a cell theme from column → row → cell
+ * (`data-grid-render.header.js:59`, `common/styles.js mergeAndRealizeTheme`), so the tone reaching
+ * a column theme is exactly how a sort used to repaint record bodies. With no `bgCell` in the
+ * table there is no longer a path from "this column is sorted" to a cell's background at all —
+ * which is a property of what `COLUMN_TONE_THEME` CONTAINS, not of anything this function does.
+ * A body wash belongs to `getRowThemeOverride` (status) or the cell itself (automation).
+ */
+function columnTheme(tone: ControlTone | undefined): Partial<Theme> | undefined {
+  return tone ? COLUMN_TONE_THEME[tone] : undefined;
+}
+
+/**
+ * Owner item 22 — key → which control involves it, or absent.
+ *
+ * ⚠ ONE tone per column, and the precedence is a decision, not an accident: **filter > sort >
+ * group** (owner R6, wave 15). A filter changes WHICH ROWS you are looking at; when a column is
+ * doing two jobs the header names the most consequential one. Blending two tints would produce a
+ * third colour that matches no chip in the toolbar, which is worse than picking.
+ *
+ * ⚠ THE PRECEDENCE IS THE WRITE ORDER BELOW, and it reads backwards: later `set` calls WIN, so
+ * the least important control is written FIRST. It was `sort, group, filter` — i.e. filter >
+ * group > sort — until R6 named the order explicitly; getting this wrong is a one-line edit that
+ * changes a colour on screen and nothing else, so it is stated here rather than left to be
+ * re-derived from the sequence.
+ */
+/* wave17 GRID — item 2 / owner R5. EXPORTED, and only since the row band died.
+   `activeControlTone` used to sit below this function and restate the same precedence for the
+   whole-table band; the band was its only consumer, so R5 took both. That left the surviving
+   precedence — the one that still paints — asserted by nothing, because `verify_icons` was
+   testing the twin. Exported so the gate can reach the function that is actually on screen. */
+export function columnTones(
+  config: ViewConfig,
+  /* wave20 item 2 — the FIELDS, because a measure condition names its measure and only the
+     field list can say which column displays it. Defaulted so the signature stays callable
+     with a config alone (the pre-wave-20 gate legs), and because a caller with no fields
+     legitimately has no measure columns to resolve. */
+  fields: Field[] = []
+): Map<string, ControlTone> {
+  const out = new Map<string, ControlTone>();
+  if (config.groupBy) out.set(config.groupBy, "group");
+  for (const s of config.sorts ?? []) out.set(s.colId, "sort");
+  const filtered = new Set<string>();
+  filteredKeys(config.filters ?? [], filtered, measureColumnIndex(fields));
+  for (const key of filtered) out.set(key, "filter");
+  return out;
+}
+
+/**
+ * ⭐ WAVE 30 (owner item 2 scouting) — THE OVERLAY ARM IS GONE, and the arithmetic is the reason.
+ *
+ * This read `field.default !== false || field.source === "overlay"`. The second arm was written
+ * when `overlay` meant "a column a user added here", and those columns have no `default` key at
+ * all — so the arm was a belt-and-braces no-op for them. Then `user_tables._clean_field` started
+ * stamping `source: "overlay"` on EVERY `ut_*` field, and every connected database became a `ut_*`
+ * one: the exception quietly became the rule and swallowed the first arm entirely.
+ *
+ * ⛔ WHAT THAT COST, measured on the live orders grid: `odoo_relational.order_fields` declares
+ * `default: False` on `odoo_id`, `state`, `customer_link` and `partner_id`, and every one of them
+ * opened SHOWN. The grid arrives wide, and "Hide fields" reads inactive because
+ * `shownCount === fields.length` — so the control that says "some columns are hidden" says the
+ * opposite of what its own table declares. A second instance of [[fallback-that-became-the-rule]].
+ *
+ * ⚠ DROPPING THE ARM DOES NOT HIDE USER COLUMNS, and this is the check that matters before
+ * believing the fix. A column somebody created carries no `default` key, `undefined !== false` is
+ * true, and it stays visible. `_clean_field` also keeps `default` ONLY when it is `True`, so a
+ * `ut_*` column can never arrive carrying `default: false` by accident — only a shipped field
+ * CONTRACT (which is written straight into the store, bypassing that validator) can declare it.
+ *
+ * ⚠ THIS PREDICATE HAS A SERVER TWIN and the twin is the one that decides on first open:
+ * `platform/aios_grid.py:_default_view_config` carries the same expression and builds the "All
+ * records" system view the client pins as its landing default. Fixing one side alone changes
+ * nothing a user sees — see `mailbox/F.md` F-1 ([[one-question-two-normalizers]] across two
+ * languages).
+ */
+function isDefaultVisible(field: Field): boolean {
+  if (field.default === false) return false;
+  /**
+   * ⭐⭐ OWNER, 2026-08-23 — A NEW VIEW SHOWS THE DATABASE'S OWN COLUMNS AND NOTHING ELSE.
+   *
+   * Owner: *"when any new View is created only shareable pre-set data should show. Shared to me
+   * or Shared to everyone should be auto hidden."*
+   *
+   * ⛔ `custom || shared` IS THE WHOLE PREDICATE, and it is chosen because it is exactly the
+   * membership test `FieldsHidePanel` already uses to draw its two SHARED sections:
+   *     "Shared with me"       (field.custom || field.shared) && fieldEditMode === "users"
+   *     "Shared with everyone" (field.custom || field.shared) && fieldEditMode === "collaborative"
+   * Both sections are subsets of `custom || shared`, so hiding on that flag hides both by
+   * construction rather than by keeping a second list of section names in step with the panel.
+   *
+   * ⚠ IT ALSO HIDES THE UNTITLED SECTION'S CREATED COLUMNS, and that is deliberate rather than
+   * over-reach. A route order carries `shared: true` with `edit: personal`, so it is filed under
+   * no heading at all — and 52 of them landed on the customer grid the same day this was asked
+   * for. The owner's first sentence is the rule ("ONLY pre-set data shows"); the second names the
+   * two headings, it does not bound the set.
+   *
+   * ⚠ MEASURED ON THE LIVE CUSTOMER GRID before it was written: of 105 fields, 77 opened SHOWN.
+   * 52 route columns, 14 collaborative `custom_*`, 3 `measure_*`, one legacy route and 7 plain
+   * Odoo columns. After this, the 7 remain — which is precisely what
+   * `aios_grid_fields.json` declares as `default: true`, i.e. the contract's own answer before
+   * anybody's columns piled on top of it.
+   *
+   * ⛔⛔ A STORED VIEW IS UNTOUCHED. `normalizeConfig` spreads the saved `config` OVER this
+   * base, so a view that already recorded its own `visible` keeps it. What moves is a view born
+   * without one: the "All records" system view, a new view, a cohort view.
+   */
+  if (field.custom === true || field.shared === true) return false;
+  return true;
+}
+
+export function defaultViewConfig(fields: Field[]): ViewConfig {
+  const shown = fields.filter(isDefaultVisible).map((field) => field.key);
+  const hidden = fields.filter((field) => !isDefaultVisible(field)).map((field) => field.key);
+  return {
+    filters: [],
+    filterConj: "and",
+    sorts: [],
+    groupBy: null,
+    colorBy: null,
+    rowHeightMode: "short",
+    order: [...shown, ...hidden],
+    visible: shown,
+    widths: {},
+    memberPids: [],
+  };
+}
+
+function reconcileOrder(order: string[], fields: Field[]): string[] {
+  const valid = new Set(fields.map((field) => field.key));
+  const kept = order.filter((key, index) => valid.has(key) && order.indexOf(key) === index);
+  for (const field of fields) if (!kept.includes(field.key)) kept.push(field.key);
+  const locked = fields.find((field) => field.pinned)?.key ?? fields[0]?.key;
+  if (locked && kept[0] !== locked) {
+    const without = kept.filter((key) => key !== locked);
+    return [locked, ...without];
+  }
+  return kept;
+}
+
+function reconcileVisible(visible: string[], fields: Field[], lockedKey: string): Set<string> {
+  const valid = new Set(fields.map((field) => field.key));
+  const out = new Set(visible.filter((key) => valid.has(key)));
+  if (out.size === 0) {
+    for (const field of fields) if (isDefaultVisible(field)) out.add(field.key);
+  }
+  if (lockedKey) out.add(lockedKey);
+  return out;
+}
+
+export interface GridColumnsApi {
+  visibleCols: GridColumn[];
+  fieldByKey: Map<string, Field>;
+  order: string[];
+  visible: Set<string>;
+  widths: Record<string, number>;
+  lockedKey: string;
+  onColumnResize: (col: GridColumn, newSize: number) => void;
+  onColumnMoved: (from: number, to: number) => void;
+  onColumnProposeMove: (from: number, to: number) => boolean;
+  setColumnVisible: (key: string, show: boolean) => void;
+  insertColumn: (key: string, anchorKey: string | null, side: "left" | "right" | "end") => void;
+}
+
+/**
+ * Controlled column adapter. ViewConfig is the durable source of truth, so
+ * choosing a saved view is one atomic state change instead of a chain of hook
+ * setters that can flash or overwrite one another.
+ */
+export function useGridColumns(
+  fields: Field[],
+  config: ViewConfig,
+  onConfig: (next: ViewConfig) => void
+): GridColumnsApi {
+  const fieldByKey = useMemo(
+    () => new Map(fields.map((field) => [field.key, field])),
+    [fields]
+  );
+  const lockedKey = useMemo(
+    () => fields.find((field) => field.pinned)?.key ?? fields[0]?.key ?? "",
+    [fields]
+  );
+  const order = useMemo(() => reconcileOrder(config.order, fields), [config.order, fields]);
+  const visible = useMemo(
+    () => reconcileVisible(config.visible, fields, lockedKey),
+    [config.visible, fields, lockedKey]
+  );
+
+  // Item 22 — recomputed only when the three controls move, not on every width drag.
+  // Wave-20 item 2 adds `fields`: a measure condition can only be resolved to the column that
+  // displays it, and a new measure column must re-tint without waiting for a control to move.
+  const tones = useMemo(
+    () => columnTones(config, fields),
+    [config.filters, config.sorts, config.groupBy, fields]  // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const visibleCols = useMemo<GridColumn[]>(
+    () =>
+      order
+        .filter((key) => visible.has(key))
+        .map((key) => {
+          const field = fieldByKey.get(key)!;
+          const width = config.widths[key] ?? DEFAULT_WIDTH;
+          // Wave-14 item 2 — an INVOLVED column's header paints at 700, so it must be MEASURED
+          // at 700. `tones` is already a dep of this memo, so this costs nothing.
+          const involved = tones.has(key);
+          // R11 / W40-T20 — the marks this header carries, in the strip's canonical order. This
+          // reserve and `CustomerGrid.drawGridHeader`'s painting call the SAME resolver, so a
+          // column cannot reserve room for one strip and then be given a different one. That is
+          // a property of `headerMarksFor` being one function, not of two call sites agreeing.
+          const marks = headerMarksFor(field);
+          return {
+            id: key,
+            // Owner item 16 — ELLIPSISED so the title can never run under the (i). Glide
+            // truncates nothing: `drawHeaderInner` calls `fillText(c.title, …)` with no clip
+            // and no max width, so on a narrow column the name simply painted through the
+            // mark. Shortening the title glide is given is the whole fix — the alternative,
+            // clipping inside `drawHeader`, cuts mid-glyph with no ellipsis to say it did.
+            // The FULL name stays reachable: CustomerGrid's header tip leads with it whenever
+            // this returns something shorter than `field.label`.
+            // ⚠ W40-T20 — `menuSlotWidth` is passed EXPLICITLY so `droppable` can be. It is the
+            // constant that was already defaulting here, so the number is unchanged; what changes
+            // is that the reserve now clears the marks the drawer actually paints rather than the
+            // ones it was asked for.
+            title: fitHeaderTitle(
+              field.label,
+              headerLabelSpace(width, marks.sizes, HEADER_MENU_SLOT, marks.droppable),
+              (text) => measureHeaderText(text, involved)
+            ),
+            width,
+            hasMenu: true,
+            menuIcon: "dots",
+            // Wave-8 I20 — the field-TYPE mark leads every header, so the column says what
+            // KIND of thing it holds before you read a single cell (same geometry as the
+            // Fields panel's rows — icons.tsx).
+            icon: typeIconName(field.type),
+            // Wave-9 I3 — the (i) is NO LONGER `overlayIcon`. Glide draws an overlay at a
+            // hard-coded offset from the TYPE mark (drawHeaderInner: `drawX + 9`), i.e.
+            // pinned to the far LEFT of the header, and no prop moves it; the owner asked
+            // for it right-aligned and centred with the field name. It is drawn instead by
+            // CustomerGrid's `drawHeader` callback, which resolves the same
+            // `field.note || field.description` condition from the field itself.
+            // The hover text is still CustomerGrid's floating tip (pointer-events: none —
+            // a tooltip must never swallow the next click, [[ui-invisible-to-assertions]]).
+            // Wave-14 R4 — being INVOLVED in a filter/sort/group is the only thing that tints a
+            // column now, and all three tint it the same faint warm grey; the hue that says
+            // WHICH control lives on the toolbar chip. User-created ownership moved out of the
+            // theme entirely and is the dot drawn in the mark strip (R11).
+            themeOverride: columnTheme(tones.get(key)),
+          };
+        }),
+    [order, visible, config.widths, fieldByKey, tones]
+  );
+
+  const onColumnResize = useCallback(
+    (column: GridColumn, newSize: number) => {
+      if (!column.id) return;
+      onConfig({
+        ...config,
+        widths: { ...config.widths, [column.id]: Math.round(newSize) },
+      });
+    },
+    [config, onConfig]
+  );
+
+  const onColumnMoved = useCallback(
+    (from: number, to: number) => {
+      if (from === 0 || to === 0) return;
+      const visibleKeys = order.filter((key) => visible.has(key));
+      if (
+        from < 0 ||
+        from >= visibleKeys.length ||
+        to < 0 ||
+        to >= visibleKeys.length
+      )
+        return;
+      const movedKeys = visibleKeys.slice();
+      const [moved] = movedKeys.splice(from, 1);
+      movedKeys.splice(to, 0, moved);
+      let index = 0;
+      const nextOrder = order.map((key) =>
+        visible.has(key) ? movedKeys[index++] : key
+      );
+      onConfig({ ...config, order: nextOrder });
+    },
+    [config, onConfig, order, visible]
+  );
+
+  const onColumnProposeMove = useCallback(
+    (from: number, to: number) => from !== 0 && to !== 0,
+    []
+  );
+
+  const setColumnVisible = useCallback(
+    (key: string, show: boolean) => {
+      if (!show && key === lockedKey) return;
+      const next = new Set(visible);
+      if (show) next.add(key);
+      else next.delete(key);
+      onConfig({ ...config, visible: [...next] });
+    },
+    [config, lockedKey, onConfig, visible]
+  );
+
+  const insertColumn = useCallback(
+    (key: string, anchorKey: string | null, side: "left" | "right" | "end") => {
+      const nextOrder = order.filter((item) => item !== key);
+      if (side === "end" || !anchorKey) {
+        nextOrder.push(key);
+      } else {
+        const anchor = Math.max(0, nextOrder.indexOf(anchorKey));
+        nextOrder.splice(anchor + (side === "right" ? 1 : 0), 0, key);
+      }
+      const nextVisible = new Set(visible);
+      nextVisible.add(key);
+      onConfig({ ...config, order: nextOrder, visible: [...nextVisible] });
+    },
+    [config, onConfig, order, visible]
+  );
+
+  return {
+    visibleCols,
+    fieldByKey,
+    order,
+    visible,
+    widths: config.widths,
+    lockedKey,
+    onColumnResize,
+    onColumnMoved,
+    onColumnProposeMove,
+    setColumnVisible,
+    insertColumn,
+  };
+}

web/src/filter-kit/FieldsHidePanel.tsx

@@ -14,7 +14,9 @@
 // ---------------------------------------------------------------------------
 
 import { useState } from "react";
-import type { Field } from "../customer-grid/types";
+// ⚠ W40-T16 — the bare `Field` type import is GONE, not misplaced: the prop below is
+// `PermsField[]` now, which extends it, so importing both would leave one unread and
+// `tsconfig.app.json`'s `noUnusedLocals` reds the build on exactly that.
 // ⭐ WAVE 30 item 2 (R5) — `fieldLabel` is the ONE resolver for a field's NAME, and every read
 // of `f.label` in this file goes through it. `Field.label` is declared `string` and arrives
 // over the WIRE, where nothing enforces that; the search filter below did
@@ -28,12 +30,25 @@ import type { Field } from "../customer-grid/types";
 import { fieldEditMode, fieldLabel, isPresetField } from "../customer-grid/types";
 import { FieldTypeIcon } from "../customer-grid/icons";
 import { TYPE_LABELS } from "../customer-grid/iconShapes";
+// ⭐⭐ W40-T16 (owner instruction 13) — A METRIC IS A ROW LIKE ANY OTHER, and the ONE thing that
+// makes it read differently is its NAME. `metricLabel` is that rule, declared once beside the
+// flag it depends on, and it is a pure string function so this panel does not acquire a runtime
+// dependency on anything the permission editor fetches or holds.
+// ⚠ THE FIRST IMPORT FROM `settings/**` INTO THE KIT, and it is deliberately the leaf:
+// `permsModel.ts` imports nothing at runtime (its only import is `import type`), so the module
+// graph stays acyclic and `verify_ui.py`'s render smoke — which mounts `PermsEditor` and reaches
+// this file through it — still resolves under bare node.
+import type { PermsField } from "../settings/permsModel";
+import { metricLabel, presetHideFields } from "../settings/permsModel";
 
 export interface FieldsHidePanelProps {
   /** Owner item 23 — in the view's COLUMN ORDER, not definition order. Dragging a row here
    *  rewrites `config.order`, so a list showing a different sequence from the one it edits
-   *  would move a field to a position the user never pointed at. */
-  fields: Field[];
+   *  would move a field to a position the user never pointed at.
+   *  ⭐ W40-T16 — `PermsField[]`, which is `Field` plus an OPTIONAL metric flag. The grid
+   *  toolbar keeps passing `Field[]` and keeps compiling, because an optional extra key makes
+   *  the two assignable; its fields never carry the flag, so no metric row can appear there. */
+  fields: PermsField[];
   /** The keys that are HIDDEN. Every field not named here renders as shown. */
   hidden: ReadonlySet<string>;
   onToggle: (key: string) => void;
@@ -52,6 +67,27 @@ export interface FieldsHidePanelProps {
    *  affordance renders for them at all. */
   deletableKeys?: ReadonlySet<string>;
   onDeleteField?: (key: string) => void;
+  /**
+   * ⭐⭐ W40-T17 (owner instruction 15) — DOES THIS MOUNT FILE ROWS UNDER "Shared with me" AND
+   * "Shared with everyone"? Absent means YES, which is the grid's behaviour and every behaviour
+   * this panel has ever had. The manage-user permission editor passes `false`, because a
+   * permission is set on the database's own pre-set columns and on nothing else: owner, verbatim,
+   * *"stop displaying 'Shared with me' / 'Shared with everyone' fields under Hide Fields -
+   * permission on pre-set Fields only."*
+   *
+   * ⛔ A PROP WITH A SAFE DEFAULT, NEVER AN UNCONDITIONAL REMOVAL, AND THE REASON IS THAT THIS
+   * PANEL SERVES TWO MOUNTS. `customer-grid/Toolbar.tsx` mounts it for the grid, where the two
+   * sections were ADDED on purpose by the 2026-08-21 hotfix and are what a user reads to tell
+   * their own columns from the tenant's. Deleting them here would silently take a shipped
+   * affordance off a surface this ticket never looked at, and no diff of the permission editor
+   * would show it. The grid passes nothing and is therefore untouched, byte for byte.
+   *
+   * ⚠ `false` DOES NOT MERELY DROP TWO SECTIONS. It swaps the whole membership question for
+   * AM-2's: `permsModel::presetHideFields`, i.e. `metric || !custom`. Filing the same rows under
+   * one untitled heading would still list somebody's personal column as a thing an admin can
+   * permission, which is the half of instruction 15 the section titles only made visible.
+   */
+  sharedSections?: boolean;
 }
 
 /**
@@ -72,6 +108,10 @@ export function FieldsHidePanel({
   onFieldOrder,
   deletableKeys,
   onDeleteField,
+  // ⭐⭐ W40-T17 — THE DEFAULT IS THE WHOLE SAFETY PROPERTY. `true` here is what makes the grid's
+  // mount need no edit at all: `customer-grid/Toolbar.tsx` passes no `sharedSections`, so it
+  // renders the three sections below exactly as it did before this ticket.
+  sharedSections = true,
 }: FieldsHidePanelProps) {
   const [query, setQuery] = useState("");
   /** W9 — destructive, so the trash arms first (the grid's confirm pattern): first
@@ -83,16 +123,52 @@ export function FieldsHidePanel({
    *  that slot. */
   const [dragKey, setDragKey] = useState<string | null>(null);
   const [overKey, setOverKey] = useState<string | null>(null);
+  /**
+   * ⭐⭐ W40-T16 (owner instruction 13) — HOW A ROW IS NAMED, in one place, for the same reason
+   * wave 30's R5 put `fieldLabel` in one place: this panel reads a field's name at SIX sites (the
+   * search filter, three grip aria-labels, the visible label and two delete aria-labels), and a
+   * name resolved differently at any one of them means what a user SEARCHES and what they READ
+   * answer the same question differently.
+   *
+   * ⚠ `fieldLabel` STAYS THE RESOLVER. This adds the metric prefix on top of it and nothing else,
+   * so a label-less definition arriving over the wire is still guarded exactly as before.
+   * A field with no metric flag comes back byte-identical to `fieldLabel(f)` — which is what
+   * keeps the GRID's mount of this panel unchanged, since grid fields never carry the flag.
+   */
+  const rowLabel = (f: PermsField): string =>
+    f.isMetric ? metricLabel(fieldLabel(f)) : fieldLabel(f);
   const q = query.trim().toLowerCase();
-  const shown = q ? fields.filter((f) => fieldLabel(f).toLowerCase().includes(q)) : fields;
-  const sections = [
-    { key: "personal", title: "", fields: shown.filter((field) =>
-      (!field.custom && !field.shared) || fieldEditMode(field) === "personal") },
-    { key: "me", title: "Shared with me", fields: shown.filter((field) =>
-      (field.custom || field.shared) && fieldEditMode(field) === "users") },
-    { key: "everyone", title: "Shared with everyone", fields: shown.filter((field) =>
-      (field.custom || field.shared) && fieldEditMode(field) === "collaborative") },
-  ];
+  const shown = q ? fields.filter((f) => rowLabel(f).toLowerCase().includes(q)) : fields;
+  /**
+   * ⭐⭐ W40-T17 (owner instruction 15) — TWO MOUNTS, TWO QUESTIONS, ONE PANEL.
+   *
+   * The GRID asks "whose column is this?" and answers it with three sections, because a person
+   * looking at their own table needs to tell their columns from the tenant's. The PERMISSION
+   * EDITOR asks "which columns may an admin set a rule on?", and AM-2 answers that with
+   * `metric || !custom` — the database's own pre-set columns, plus every bound measure. They are
+   * not the same list narrowed; they are different questions with different answers.
+   *
+   * ⛔ THE THREE-SECTION ARM IS UNCHANGED AND MUST STAY SPELLED EXACTLY THIS WAY.
+   * `verify_map.py`'s `private-by-default-is-anchored` leg reads this file for the literal
+   * `fieldEditMode(field) === "collaborative"`: it is what pins "Shared with everyone" to the
+   * `collaborative` answer, so a route column stamped `edit: personal` is filed as private by
+   * rule rather than by luck. Rename the parameter or move the predicate and that gate reports a
+   * fact about route columns going stale, one surface away from here.
+   *
+   * ⚠ THE NARROW ARM RENDERS ONE UNTITLED SECTION, which is what the first section has always
+   * been. No heading appears and no heading disappears: `section.title` is falsy, so the rows sit
+   * directly under the search box exactly as the personal rows do on the grid today.
+   */
+  const sections = sharedSections
+    ? [
+        { key: "personal", title: "", fields: shown.filter((field) =>
+          (!field.custom && !field.shared) || fieldEditMode(field) === "personal") },
+        { key: "me", title: "Shared with me", fields: shown.filter((field) =>
+          (field.custom || field.shared) && fieldEditMode(field) === "users") },
+        { key: "everyone", title: "Shared with everyone", fields: shown.filter((field) =>
+          (field.custom || field.shared) && fieldEditMode(field) === "collaborative") },
+      ]
+    : [{ key: "personal", title: "", fields: presetHideFields(shown) }];
   /**
    * Item 23 — reorder is OFF while a search is narrowing the list. Dropping "City" above
    * "State" in a list that is hiding the eight fields between them means nothing the user can
@@ -209,10 +285,10 @@ export function FieldsHidePanel({
                 draggable={canReorder && !locked}
                 aria-label={
                   locked
-                    ? `${fieldLabel(f)} is always first`
+                    ? `${rowLabel(f)} is always first`
                     : canReorder
-                      ? `Reorder ${fieldLabel(f)}: drag, or use the arrow keys`
-                      : `Reorder ${fieldLabel(f)} (clear the search first)`
+                      ? `Reorder ${rowLabel(f)}: drag, or use the arrow keys`
+                      : `Reorder ${rowLabel(f)} (clear the search first)`
                 }
                 title={
                   canReorder && !locked
@@ -262,7 +338,7 @@ export function FieldsHidePanel({
                   draws (icons.tsx). Titled, because this list is where the icon
                   vocabulary is learned. */}
               <FieldTypeIcon type={f.type} title={TYPE_LABELS[f.type]} />
-              <span className="cg-check-label">{fieldLabel(f)}</span>
+              <span className="cg-check-label">{rowLabel(f)}</span>
               {/* ⭐ OWNER ITEM 3 (2026-08-06): *"it doesn't show pre-set when I hide fields just
                   like how Odoo fields are. This is always the standard label."* Right — the chip
                   asked `source === "odoo"`, so a column an AUTOMATION fills (source `overlay`)
@@ -283,7 +359,7 @@ export function FieldsHidePanel({
                   type="button"
                   className={"cg-check-del" + (armed ? " is-armed" : "")}
                   aria-label={
-                    armed ? `Permanently delete ${fieldLabel(f)}?` : `Delete ${fieldLabel(f)}`
+                    armed ? `Permanently delete ${rowLabel(f)}?` : `Delete ${rowLabel(f)}`
                   }
                   title={armed ? undefined : "Removes this field and its values on every row."}
                   onClick={(e) => {
@@ -317,7 +393,24 @@ export function FieldsHidePanel({
             })}
           </div>
         ))}
-        {shown.length === 0 && (
+        {/* ⭐⭐ W40-T17 — GATED ON WHAT THE SECTIONS ACTUALLY HOLD, not on `shown`, and the two
+            stopped being the same question the moment a mount could narrow the vocabulary. On the
+            narrow arm a query matching only somebody's own columns leaves `shown` non-empty and
+            every section EMPTY: a search box with nothing under it and no sentence saying why,
+            which reads as a broken panel rather than as a search that found nothing.
+            ⛔ THE GRID IS UNAFFECTED, BY PARTITION RATHER THAN BY LUCK. `fieldEditMode` answers
+            exactly one of `personal` / `users` / `collaborative` (`types.ts::FIELD_EDIT_MODES`),
+            and the three predicates above split on that answer, so every field lands in exactly
+            one section and `sections.every(empty)` is TRUE precisely when `shown` is empty. Same
+            render, same condition, one fewer way to paint a blank.
+            ⚠ THE SENTENCE IS UNCHANGED, AND THE ONE CASE IT WOULD NOT FIT IS NAMED RATHER THAN
+            ASSUMED AWAY. With no query at all, this branch needs a module whose EVERY field is
+            `custom` and none a metric. No such module exists: an Odoo topic's columns are the
+            contract in `aios_grid.FIELDS`, and a `ut_*` database's are stamped `source: overlay`
+            by `core.user_tables._clean_field`, which never writes `custom`. A new copy for a
+            state nothing can reach would be a paragraph the empty-state rule (DESIGN.md §4)
+            exists to refuse; if a wire ever makes it reachable, that is when it earns a line. */}
+        {sections.every((section) => section.fields.length === 0) && (
           <div className="cg-builder-empty">No field matches your search.</div>
         )}
       </div>

web/src/filter-kit/FilterBuilderPanel.tsx

@@ -36,6 +36,14 @@ import type { AnchorMode } from "../customer-grid/windows";
 import { ANCHOR_LABELS, ANCHOR_MODES, MAX_N } from "../customer-grid/windows";
 import { FieldSelectButton } from "../customer-grid/FieldSelect";
 import type { FieldSelectItem } from "../customer-grid/FieldSelect";
+// ⭐ W40-T18 — the deleted-column vocabulary. Same direction `filter-kit/FieldsHidePanel.tsx`
+// already imports `metricLabel` / `presetHideFields` from: `settings/permsModel` is a PURE model
+// module with no runtime import of its own, it is already in the grid bundle because that panel
+// mounts in the grid toolbar, and putting these three beside it is what lets `perms.test.ts`
+// assert them under bare node — nothing in this file can be imported by that harness.
+import {
+  DELETED_FIELD_NOTE, isDeletedFieldRef, withDeletedFieldLabel,
+} from "../settings/permsModel";
 import { WindowPicker } from "./WindowPicker";
 import {
   COHORT_OP_LIST, DEFAULT_DATE_WINDOW, DEFAULT_WINDOW, MEASURE_MARK, MEASURE_OP_LIST,
@@ -543,6 +551,18 @@ function LeafRow({
   // C4 — the view-membership leaf, on exactly the terms the cohort leaf above it runs.
   const isView = rule.colId === VIEW_FIELD;
   const hasViews = viewChoices.length > 0;
+  // ⭐⭐ W40-T18 (owner instruction 16) — THE CONDITION WHOSE COLUMN IS GONE.
+  //
+  // `withCurrentField` resolves the current key against `fieldByKey`, the COMPLETE list, and
+  // appends whatever it finds so a narrowed picker never orphans history. When it finds nothing
+  // it appends the RAW KEY as the label. That row is the defect: `custom_1723489` reads as a
+  // field name, and an admin cannot tell a deleted column from a badly named one.
+  //
+  // ⛔ MEASURE-SHAPED RULES ARE EXCLUDED. `isMeasureRule` is a test of the rule's SHAPE (it
+  // carries a window), so a measure whose key has gone would otherwise be named a deleted
+  // COLUMN, which it is not. It keeps today's rendering; see the handoff.
+  const goneColumn = !isMeasure
+    && isDeletedFieldRef(rule.colId, fieldByKey, measureByKey, [COHORT_FIELD, VIEW_FIELD]);
   const t = isMeasure
     ? measureByKey.get(rule.colId)?.type ?? "currency"
     : fieldByKey.get(rule.colId)?.type ?? "text";
@@ -639,6 +659,27 @@ function LeafRow({
   const offeredOps = withCurrent(canRank ? [...opList, ...RANK_OPS] : opList, opValue);
   const plainOps = offeredOps.filter((op) => !isRankOp(op));
   const rankedOps = offeredOps.filter((op) => isRankOp(op));
+  // ⭐⭐ W40-T18 — HOW A GONE COLUMN READS, in three parts and no new CSS.
+  //
+  // (1) THE ROW. `withCurrentField` has already synthesised a picker row labelled with the raw
+  //     key; `withDeletedFieldLabel` rewrites that one row to the word and moves the key into
+  //     the muted `hint` line `FieldSelect` paints under a label. Nothing is removed from the
+  //     list and no condition is dropped: this panel edits live permission records, and a rule
+  //     that vanishes on render is a rule nobody decided to delete.
+  const offeredFields = goneColumn
+    ? withDeletedFieldLabel(
+        withCurrentField(fields, rule.colId, fieldByKey, measureByKey, hasCohorts), rule.colId)
+    : withCurrentField(fields, rule.colId, fieldByKey, measureByKey, hasCohorts);
+  // (2) THE MARK. `is-missing` is index.css's OWN state for "set to something this table cannot
+  //     offer" — amber border, amber label — and it is APPENDED rather than written fresh
+  //     because this panel also mounts in the grid toolbar, while every lane-G stylesheet loads
+  //     with the settings modal alone. The button paints that state unaided when a value
+  //     resolves to no row; it cannot here, precisely because a row was synthesised for it, so
+  //     the caller says it instead.
+  const fieldClass = "cg-cond-field" + (goneColumn ? " is-missing" : "");
+  // (3) THE NAME A SCREEN READER HEARS, which `aria-label` supplies INSTEAD of the visible
+  //     label — so the state and the key both belong in it or neither is announced at all.
+  const fieldAria = goneColumn ? `Field, deleted column ${rule.colId}` : "Field";
 
   return (
     <span className={"cg-cond-row" + (isMeasure ? " is-measure" : "")
@@ -650,12 +691,13 @@ function LeafRow({
           adds the type MARK to each row and takes NO grouping with it: the marks are what the
           optgroup was reaching for, and they say it per row instead of splitting the list. */}
       <FieldSelectButton
-        className="cg-cond-field"
-        ariaLabel="Field"
+        className={fieldClass}
+        ariaLabel={fieldAria}
+        title={goneColumn ? DELETED_FIELD_NOTE : undefined}
         value={rule.colId}
         onChange={onField}
         fields={[
-          ...withCurrentField(fields, rule.colId, fieldByKey, measureByKey, hasCohorts),
+          ...offeredFields,
           ...measures.map((m) => ({ key: m.key, label: m.label, type: MEASURE_MARK })),
           // A cohort leaf asks about membership of a SET, which is the multiselect mark's
           // own meaning — the vocabulary already had the right glyph for it.

web/src/filter-kit/ops.ts

@@ -1,400 +1,426 @@
-// ---------------------------------------------------------------------------
-// filter-kit / ops.ts
-// The filter/sort operator VOCABULARY — which operators each field type offers,
-// and how each one reads to a human.
-//
-// Extracted verbatim from customer-grid/Toolbar.tsx (wave 15, contract C-KIT) so
-// the permission editor and the grid toolbar offer ONE vocabulary rather than two
-// that drift. The matching engine (matchFilter/makeComparator in useVisibleRows)
-// and its Python mirrors (filter_sql.py, filter_eval.py) are the other halves of
-// the same contract; these are only the labels the popovers render.
-// ---------------------------------------------------------------------------
-
-import type {
-  Conjunction,
-  Field,
-  FieldType,
-  FilterNode,
-  FilterOp,
-  FilterRule,
-  Measure,
-} from "../customer-grid/types";
-import {
-  COHORT_FIELD, COHORT_OPS, MEASURE_OPS, MEASURE_PAIR_OPS, isFilterGroup,
-  isDateFamilyType, isNumericFieldType, isRankOp, normalizeCohortOp,
-} from "../customer-grid/types";
-import type { CohortOp } from "../customer-grid/types";
-import type { FieldSelectItem, FieldSelectType } from "../customer-grid/FieldSelect";
-import type { WindowKind, WindowSpec } from "../customer-grid/windows";
-
-// The type families live in types.ts (ONE definition for every UI surface); the engine keeps
-// its own deliberately self-contained copies — see isNumericFieldType's doc.
-export const isNumericType = isNumericFieldType;
-export const isDateFamily = isDateFamilyType;
-
-/**
- * Operators offered for a field type (first = the default for new conditions).
- * Mirrors Airtable's own per-type sets, verified against the live product
- * (2026-07-25): a text field offers exactly contains / does not contain / is /
- * is not / is empty / is not empty. Every type ends with the two value-free ops.
- *
- * NOTE on isEmpty over the Customer List contract: several Odoo-derived money
- * columns (revenue_ytd, revenue_ly, at_risk, ltm_rev, orders_24m, est_missed) are
- * built with 0.0/0 defaults in customer_list.pool(), so "is empty" correctly
- * matches NOTHING there — 0 is a real value, not a blank. The columns where it
- * genuinely bites are last_order (''), days_since, typical_gap_days, yoy_pct, and
- * every overlay field (notes / custom) — "customers with no notes yet" is the
- * common case. Offered on all types anyway, exactly as Airtable does.
- *
- * ⚠ AND the SENTINEL columns, which are a third case and the one that surprises:
- * agent · city · state · country · zip · payment_terms · pricelist · tags all
- * collapse a blank to the STRING '(none)' in `_partner_attrs`, so grouping has no
- * null bucket. `isEmpty` tests `value === ""`, so on these it matches nothing even
- * though 76 customers have no country and 79 no zip — the blanks are found with
- * `is` `(none)`, which is also what the cell visibly says. Each of those fields
- * carries that sentence as its column `note`, because a source comment is not
- * where the person filtering is looking. DATE attributes keep '' instead
- * (customer_since, last_order): '(none)' in a date column would sort and compare
- * as text against ISO dates.
- */
-export function opsForType(t: FieldType): FilterOp[] {
-  // Wave-5: a checkbox stores '1' or blank, so "is checked" IS `isNotEmpty` and "is
-  // unchecked" IS `isEmpty` — the honest mapping onto the existing vocabulary (no new
-  // FilterOp, the filter_sql lock-step untouched). Both are value-free, so no value control
-  // renders. First = the default: "is checked".
-  if (t === "checkbox") return ["isNotEmpty", "isEmpty"];
-  if (isNumericType(t))
-    return ["gte", "gt", "lte", "lt", "eq", "neq", "between", "isEmpty", "isNotEmpty"];
-  if (isDateFamily(t))
-    // Owner item 3, in the order they asked for it. `between` is GONE from the offer — "is
-    // within" plus a custom range says the same thing and reads better — but it stays in the
-    // ENGINE, because saved views hold it. `legacyOps` below is what keeps such a view
-    // rendering its own operator instead of silently showing the first one in this list.
-    return ["eq", "within", "lt", "gt", "lte", "gte", "neq", "isEmpty", "isNotEmpty"];
-  // `select` and `user` are picked from a fixed list, so they behave like `status`: is / is
-  // not / empty. `contains` on a chosen value is a substring test against a closed vocabulary —
-  // it would find "Done" inside "Not done" and read as a bug.
-  if (t === "status" || t === "select" || t === "user")
-    return ["eq", "neq", "isEmpty", "isNotEmpty"];
-  // A `multiselect` cell is a comma-joined SET, so the useful question is membership — "has" —
-  // which is the EXISTING `contains` op over the joined string (no new engine vocabulary; the
-  // ops are mirrored in filter_sql.py and inventing one here would break the lock-step). The
-  // value is still picked from the declared options, so the substring caveat above is bounded
-  // by the user's own choice list. `eq` reads "is exactly": the whole set is that one choice.
-  if (t === "multiselect")
-    return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"];
-  // ⭐ Wave-23 C7 — `json` gets EXACTLY the two value-free ops, and the omissions are the
-  // decision. `contains` over a serialized document is a substring test against punctuation and
-  // key names: `contains "12"` would match a key `id_12`, a value 12, a timestamp and a
-  // fragment of 5120, and every one of those reads as a working filter. `eq` is worse — two
-  // documents that mean the same thing differ by key order and whitespace, so "is" would answer
-  // false for a record that plainly matches. "Has anything been captured here yet" is the
-  // question a json column can answer soundly, and it is the one people actually ask.
-  //
-  // ⚠ NO NEW OPERATOR ENTERS EITHER ENGINE. `isEmpty`/`isNotEmpty` already exist in
-  // `filter_sql.py` (:76, and :112's VALUE_FREE_OPS) and `filter_eval.py` (:260-262), and both
-  // are TYPE-INDEPENDENT — they test blankness before any type dispatch — so the lock-step is
-  // untouched and nothing on the server had to move for this line. (The contract's prose spells
-  // them `is_empty`/`is_not_empty`; the runtimes do not. The names come from the code.)
-  if (t === "json") return ["isNotEmpty", "isEmpty"];
-  // Wave-18 C5-AUTOFIELD — `automation` lands HERE, on the text ops, and that is the whole
-  // v1 answer. Its cell is one machine-written line (`ok · 2026-08-03 14:10 · 12 posts`), so
-  // `contains ok` and `contains error` are the two questions anyone actually asks of the
-  // column, and both are already sound over a string. Nothing new enters the operator
-  // vocabulary, so the `filter_sql.py` lock-step is untouched — a new op for "state is" would
-  // have to be mirrored in the Python engine, and the substring answer is the same answer.
-  return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"]; // text
-}
-
-/**
- * C-OPS — the RANK operators, worded so the row still reads as a sentence.
- *
- * The unit lives in the OPERATOR, not beside the box: "top" followed by a bare 10 is ambiguous
- * between ten records and ten percent, so `top N` and `top N%` are two operators and the box
- * supplies N. The alternative — a "%" suffix element after the input — would put a second
- * thing in the value slot that every gate locating `.cg-cond-val` would have to know about.
- *
- * ⚠ AND THEY ARE SHORT ON PURPOSE. A 136px `.cg-select` has ~97.9px of readable width (see
- * `cohortOpLabel` below, and `withCurrentField` below) — about 15 characters of 12.5px Inter.
- * "is in the bottom N%" is 19 and would have shipped CLIPPED, which no assertion here can see
- * and no screenshot in this session could catch. Dropping the "is " costs nothing: the numeric
- * operators beside these are bare glyphs (`≥ > ≤ <`), so the row already reads without one,
- * and the `Ranked` divider carries the "these are a different kind of question" signal. Fifth
- * time this control has outgrown a label; the label gives way, never the control.
- */
-export const RANK_OP_LABELS: Record<string, string> = {
-  topN: "top N",
-  bottomN: "bottom N",
-  inTopPct: "top N%",
-  inBottomPct: "bottom N%",
-  aboveAvg: "above average",
-  belowAvg: "below average",
-  inQuartile: "in quartile",
-  inDecile: "in decile",
-};
-
-/**
- * The value a rank op starts at when it is chosen.
- *
- * Seeded rather than left blank, and this is a deliberate break from how the other operators
- * behave: a blank value makes a rule INACTIVE, so `is in the top N` with nothing typed would
- * sit in the builder narrowing nothing, and "the filter I just added does nothing" reads as a
- * broken control rather than as an unfinished sentence. Every rank op has an obvious default —
- * ten, or the top slice — so there is a right answer to seed. The two averages take none.
- */
-export function rankDefault(op: FilterOp): string {
-  switch (op) {
-    case "topN":
-    case "bottomN":
-    case "inTopPct":
-    case "inBottomPct":
-    case "inDecile":
-      return "10";
-    case "inQuartile":
-      return "4";
-    default:
-      return ""; // aboveAvg / belowAvg — value-free
-  }
-}
-
-/* ⛔ `hasRankCondition` LIVED HERE AND IS DELETED WITH THE PARAGRAPH IT GATED (wave 34, R5).
-   Its whole job was to decide whether to draw the builder's rank explainer; the owner has
-   removed that paragraph, and the predicate had exactly one caller besides its own recursion.
-   ⚠ `isRankOp` stays: `opLabel` below still calls it. `isMeasureRule` was `hasRankCondition`'s
-   ONLY use in this module, so THIS FILE'S IMPORT of it went too — the symbol itself lives on in
-   `types.ts` with plenty of callers, including `FilterBuilderPanel` two files over. The
-   distinction matters: an unused IMPORT is dead weight here, an unused EXPORT would be dead code
-   there, and only one of those was true.
-   ⚠⚠ THIS COMMENT'S FIRST DRAFT SAID BOTH SYMBOLS "STAY, they have many callers" — and `tsc`
-   refuted it in the next run. That is the THIRD time in one session a confident claim about who
-   calls a symbol was wrong within a minute of writing it. The habit worth keeping is not "be more
-   careful"; it is that the compiler answers this question for free, so ask it before asserting. */
-
-/** Human label for an operator, read naturally per field type. */
-export function opLabel(op: FilterOp, t: FieldType): string {
-  // Rank first and type-independently: a rank op means the same thing on every numeric
-  // family, and a view whose column has since changed type must still SAY what it holds
-  // rather than falling through to a raw key.
-  if (isRankOp(op)) return RANK_OP_LABELS[op] ?? op;
-  // Checkbox first: its two value-free ops READ as states, not as blankness — the storage
-  // contract ('1' or blank) is an implementation detail the sentence must not leak.
-  if (t === "checkbox") {
-    if (op === "isNotEmpty") return "is checked";
-    if (op === "isEmpty") return "is unchecked";
-  }
-  // Type-independent: Airtable words these identically for every field type.
-  if (op === "isEmpty") return "is empty";
-  if (op === "isNotEmpty") return "is not empty";
-  if (isDateFamily(t)) {
-    switch (op) {
-      case "eq":
-        return "is";
-      case "neq":
-        return "is not";
-      case "within":
-        return "is within";
-      case "lt":
-        return "is before";
-      case "lte":
-        return "is on or before";
-      case "gt":
-        return "is after";
-      case "gte":
-        return "is on or after";
-      case "between":
-        return "is between";      // no longer offered; still rendered for a saved view
-    }
-  }
-  if (isNumericType(t)) {
-    switch (op) {
-      case "gte":
-        return "≥"; // ≥
-      case "gt":
-        return ">";
-      case "lte":
-        return "≤"; // ≤
-      case "lt":
-        return "<";
-      case "eq":
-        return "=";
-      case "neq":
-        return "≠"; // ≠
-      case "between":
-        return "is between";
-      default:
-        return op;
-    }
-  }
-  if (t === "multiselect") {
-    // Membership wording over the joined-set cell. "has" IS `contains` (see opsForType) — only
-    // the label changes, so the engine and its Python mirror stay untouched.
-    switch (op) {
-      case "contains":
-        return "has";
-      case "doesNotContain":
-        return "does not have";
-      case "eq":
-        return "is exactly";
-      case "neq":
-        return "is not exactly";
-      default:
-        return op;
-    }
-  }
-  // text / status. (Airtable suffixes value-taking ops with "…" in the OPEN
-  // dropdown only; a native <select> shows one string in both states, so we use
-  // the closed-state wording — which is what's on screen almost all the time.)
-  switch (op) {
-    case "contains":
-      return "contains";
-    case "doesNotContain":
-      return "does not contain";
-    case "eq":
-      return "is";
-    case "neq":
-      return "is not";
-    default:
-      return op;
-  }
-}
-
-/**
- * The offered list, PLUS whatever the rule is actually set to.
- *
- * A `<select>` whose `value` is not among its `<option>`s renders the FIRST option instead —
- * so a saved view holding a dropped operator (a date `between`) or a column that has since left
- * the filter list (`at_risk`, once its measure replacement shipped) would display something the
- * rule does not say, and the first edit would silently rewrite it to that. Painted, plausible,
- * and wrong: the class of failure a screenshot catches and an assertion does not.
- */
-export function withCurrent<T extends string>(offered: readonly T[], current: T | undefined): T[] {
-  return current && !offered.includes(current) ? [...offered, current] : [...offered];
-}
-
-/** A group's summary line, mirroring Airtable's wording. */
-export function groupSummary(conj: Conjunction): string {
-  return conj === "or"
-    ? "Any of the following are true…"
-    : "All of the following are true…";
-}
-
-/**
- * CG-8 — the operators a MEASURE condition may use, and why they are not `opsForType`.
- *
- * A measure is answered by a SQL `HAVING`, and `harness/measure_filter.OPS` has exactly six
- * comparisons. `between` would need two, and `isEmpty`/`isNotEmpty` have no meaning for a sum
- * that is defined to be 0 when there is nothing to add up — the resolver refuses all three by
- * name. Offering them here would produce a condition the server can only reject.
- *
- * The owner's "dates between X and Y" is the WINDOW's between, not the value's, and that is the
- * `custom` window kind — so nothing is lost.
- */
-export const MEASURE_OP_LIST: FilterOp[] = [...MEASURE_OPS];
-
-/** CG-9 — narrower still when the other side is a measure. `=` and `≠` between two sums of
- *  floats match nobody and everybody respectively; see types.ts MEASURE_PAIR_OPS. */
-export const MEASURE_PAIR_OP_LIST: FilterOp[] = [...MEASURE_PAIR_OPS];
-
-/**
- * A cohort condition names a SET of cohorts (owner, 2026-07-27), so its operators are set
- * operators. `eq`/`neq` are not offered — the validator rewrites them to `anyOf`/`noneOf`, and
- * `withCurrent` would otherwise show a legacy view an operator it can never choose again.
- */
-export const COHORT_OP_LIST: CohortOp[] = [...COHORT_OPS];
-
-/**
- * ⚠ "is part of any of" measures ~96px at 12.5px Inter against the 97.9px of readable width a
- * 136px select actually has (136 - 20.1 arrow - 16 padding - 2 border) — inside the box only
- * until a fallback font renders it. Airtable's own wording for a multi-select is shorter and
- * says the same thing, so the LABEL gives way, not the control. Third time this rule has been
- * applied; see the "(not filterable)" and "the 75th percentile" clippings before it.
- */
-export function cohortOpLabel(op: FilterOp | CohortOp): string {
-  switch (normalizeCohortOp(op)) {
-    case "allOf":
-      return "is all of";
-    case "noneOf":
-      return "is none of";
-    default:
-      return "is any of";
-  }
-}
-
-/** Item 20 — the mark a MEASURE row wears in every picker on this surface. Named once so the
- *  three lists that offer measures cannot drift into two different glyphs for one concept. */
-export const MEASURE_MARK: FieldSelectType = "measure";
-
-/** A measure condition is identified by its window, so a new one needs a default window. */
-export const DEFAULT_WINDOW: WindowSpec = { kind: "ltm" };
-
-/** The default RANGE for `is within` — the owner's first example ("the past month"). */
-export const DEFAULT_DATE_WINDOW: WindowSpec = { kind: "past_month" };
-
-/**
- * The ranges `is within` offers, in the owner's own order (item 3, 2026-07-26):
- * the past number of days · the past week · the past month · the past year · this calendar
- * week · this calendar month · this calendar year.
- *
- * Plus `custom`, which is not a nicety: dropping `between` from the date operators would
- * otherwise remove the ability to ask for two exact dates at all. The remaining kinds
- * (yesterday, last_quarter, ytd_last_year, the forward-looking ones…) stay available to a
- * MEASURE's window, where they make sense; "last order is within year to date, last year" is a
- * question nobody asks.
- */
-export const WITHIN_KINDS: WindowKind[] = [
-  "last_n_days", "past_week", "past_month", "past_year",
-  "this_week", "this_month", "this_year", "custom",
-];
-
-/**
- * The field dropdown's COLUMN half, plus the column the rule is actually set to if the picker
- * no longer offers it. See `withCurrent` — a select whose value is missing from its options
- * silently displays a different field than the rule holds. This is not hypothetical: the
- * shipped "Win-back" list filters `at_risk`, which left the filter list the day its measure
- * replacement arrived.
- */
-export function withCurrentField(
-  fields: Field[],
-  current: string,
-  fieldByKey: Map<string, Field>,
-  measureByKey: Map<string, Measure>,
-  hasCohorts: boolean
-): FieldSelectItem[] {
-  // Item 20: the rows carry their TYPE now, because the picker paints the type mark. Same
-  // list, same order, same `withCurrent` rule — only the shape of a row grew a field.
-  const out: FieldSelectItem[] = fields.map((f) => ({
-    key: f.key, label: f.label, type: f.type,
-  }));
-  const known = new Set(out.map((o) => o.key));
-  if (!current || known.has(current) || measureByKey.has(current)) return out;
-  if (current === COHORT_FIELD && hasCohorts) return out;
-  // The field's OWN label, with no "(not filterable)" annotation: the select is ~170px and the
-  // suffix CLIPPED to "At risk $ (not filter" — a truncated parenthetical reads as a rendering
-  // bug, and the property that matters is that the condition says what it says. Found by
-  // reading the screenshot; every assertion in the run was green.
-  const f = fieldByKey.get(current);
-  out.push({ key: current, label: f ? f.label : current, type: f?.type });
-  return out;
-}
-
-/** Ids only have to be unique within one view's tree; they never leave this browser's view. */
-let ruleSeq = 0;
-export function newRuleId(): string {
-  ruleSeq += 1;
-  return `r${Date.now().toString(36)}${ruleSeq.toString(36)}`;
-}
-
-/** A fresh leaf condition on the first available field. */
-export function newCondition(fields: Field[]): FilterRule | null {
-  const f0 = fields[0];
-  if (!f0) return null;
-  return { colId: f0.key, op: opsForType(f0.type)[0], value: "" };
-}
-
-/** Total LEAF conditions in a filter tree (groups contribute their contents). */
-export function countConditions(nodes: FilterNode[]): number {
-  let n = 0;
-  for (const node of nodes)
-    n += isFilterGroup(node) ? countConditions(node.children) : 1;
-  return n;
-}
+// ---------------------------------------------------------------------------
+// filter-kit / ops.ts
+// The filter/sort operator VOCABULARY — which operators each field type offers,
+// and how each one reads to a human.
+//
+// Extracted verbatim from customer-grid/Toolbar.tsx (wave 15, contract C-KIT) so
+// the permission editor and the grid toolbar offer ONE vocabulary rather than two
+// that drift. The matching engine (matchFilter/makeComparator in useVisibleRows)
+// and its Python mirrors (filter_sql.py, filter_eval.py) are the other halves of
+// the same contract; these are only the labels the popovers render.
+// ---------------------------------------------------------------------------
+
+import type {
+  Conjunction,
+  Field,
+  FieldType,
+  FilterNode,
+  FilterOp,
+  FilterRule,
+  Measure,
+} from "../customer-grid/types";
+import {
+  COHORT_FIELD, COHORT_OPS, MEASURE_OPS, MEASURE_PAIR_OPS, isFilterGroup,
+  isDateFamilyType, isNumericFieldType, isRankOp, normalizeCohortOp,
+} from "../customer-grid/types";
+import type { CohortOp } from "../customer-grid/types";
+import type { FieldSelectItem, FieldSelectType } from "../customer-grid/FieldSelect";
+import type { WindowKind, WindowSpec } from "../customer-grid/windows";
+
+// The type families live in types.ts (ONE definition for every UI surface); the engine keeps
+// its own deliberately self-contained copies — see isNumericFieldType's doc.
+export const isNumericType = isNumericFieldType;
+export const isDateFamily = isDateFamilyType;
+
+/**
+ * Operators offered for a field type (first = the default for new conditions).
+ * Mirrors Airtable's own per-type sets, verified against the live product
+ * (2026-07-25): a text field offers exactly contains / does not contain / is /
+ * is not / is empty / is not empty. Every type ends with the two value-free ops.
+ *
+ * NOTE on isEmpty over the Customer List contract: several Odoo-derived money
+ * columns (revenue_ytd, revenue_ly, at_risk, ltm_rev, orders_24m, est_missed) are
+ * built with 0.0/0 defaults in customer_list.pool(), so "is empty" correctly
+ * matches NOTHING there — 0 is a real value, not a blank. The columns where it
+ * genuinely bites are last_order (''), days_since, typical_gap_days, yoy_pct, and
+ * every overlay field (notes / custom) — "customers with no notes yet" is the
+ * common case. Offered on all types anyway, exactly as Airtable does.
+ *
+ * ⚠ AND the SENTINEL columns, which are a third case and the one that surprises:
+ * agent · city · state · country · zip · payment_terms · pricelist · tags all
+ * collapse a blank to the STRING '(none)' in `_partner_attrs`, so grouping has no
+ * null bucket. `isEmpty` tests `value === ""`, so on these it matches nothing even
+ * though 76 customers have no country and 79 no zip — the blanks are found with
+ * `is` `(none)`, which is also what the cell visibly says. Each of those fields
+ * carries that sentence as its column `note`, because a source comment is not
+ * where the person filtering is looking. DATE attributes keep '' instead
+ * (customer_since, last_order): '(none)' in a date column would sort and compare
+ * as text against ISO dates.
+ */
+export function opsForType(t: FieldType): FilterOp[] {
+  // Wave-5: a checkbox stores '1' or blank, so "is checked" IS `isNotEmpty` and "is
+  // unchecked" IS `isEmpty` — the honest mapping onto the existing vocabulary (no new
+  // FilterOp, the filter_sql lock-step untouched). Both are value-free, so no value control
+  // renders. First = the default: "is checked".
+  if (t === "checkbox") return ["isNotEmpty", "isEmpty"];
+  if (isNumericType(t))
+    return ["gte", "gt", "lte", "lt", "eq", "neq", "between", "isEmpty", "isNotEmpty"];
+  if (isDateFamily(t))
+    // Owner item 3, in the order they asked for it. `between` is GONE from the offer — "is
+    // within" plus a custom range says the same thing and reads better — but it stays in the
+    // ENGINE, because saved views hold it. `legacyOps` below is what keeps such a view
+    // rendering its own operator instead of silently showing the first one in this list.
+    return ["eq", "within", "lt", "gt", "lte", "gte", "neq", "isEmpty", "isNotEmpty"];
+  // `select` and `user` are picked from a fixed list, so they behave like `status`: is / is
+  // not / empty. `contains` on a chosen value is a substring test against a closed vocabulary —
+  // it would find "Done" inside "Not done" and read as a bug.
+  if (t === "status" || t === "select" || t === "user")
+    return ["eq", "neq", "isEmpty", "isNotEmpty"];
+  // A `multiselect` cell is a comma-joined SET, so the useful question is membership — "has" —
+  // which is the EXISTING `contains` op over the joined string (no new engine vocabulary; the
+  // ops are mirrored in filter_sql.py and inventing one here would break the lock-step). The
+  // value is still picked from the declared options, so the substring caveat above is bounded
+  // by the user's own choice list. `eq` reads "is exactly": the whole set is that one choice.
+  if (t === "multiselect")
+    return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"];
+  // ⭐ Wave-23 C7 — `json` gets EXACTLY the two value-free ops, and the omissions are the
+  // decision. `contains` over a serialized document is a substring test against punctuation and
+  // key names: `contains "12"` would match a key `id_12`, a value 12, a timestamp and a
+  // fragment of 5120, and every one of those reads as a working filter. `eq` is worse — two
+  // documents that mean the same thing differ by key order and whitespace, so "is" would answer
+  // false for a record that plainly matches. "Has anything been captured here yet" is the
+  // question a json column can answer soundly, and it is the one people actually ask.
+  //
+  // ⚠ NO NEW OPERATOR ENTERS EITHER ENGINE. `isEmpty`/`isNotEmpty` already exist in
+  // `filter_sql.py` (:76, and :112's VALUE_FREE_OPS) and `filter_eval.py` (:260-262), and both
+  // are TYPE-INDEPENDENT — they test blankness before any type dispatch — so the lock-step is
+  // untouched and nothing on the server had to move for this line. (The contract's prose spells
+  // them `is_empty`/`is_not_empty`; the runtimes do not. The names come from the code.)
+  if (t === "json") return ["isNotEmpty", "isEmpty"];
+  // Wave-18 C5-AUTOFIELD — `automation` lands HERE, on the text ops, and that is the whole
+  // v1 answer. Its cell is one machine-written line (`ok · 2026-08-03 14:10 · 12 posts`), so
+  // `contains ok` and `contains error` are the two questions anyone actually asks of the
+  // column, and both are already sound over a string. Nothing new enters the operator
+  // vocabulary, so the `filter_sql.py` lock-step is untouched — a new op for "state is" would
+  // have to be mirrored in the Python engine, and the substring answer is the same answer.
+  return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"]; // text
+}
+
+/**
+ * C-OPS — the RANK operators, worded so the row still reads as a sentence.
+ *
+ * The unit lives in the OPERATOR, not beside the box: "top" followed by a bare 10 is ambiguous
+ * between ten records and ten percent, so `top N` and `top N%` are two operators and the box
+ * supplies N. The alternative — a "%" suffix element after the input — would put a second
+ * thing in the value slot that every gate locating `.cg-cond-val` would have to know about.
+ *
+ * ⚠ AND THEY ARE SHORT ON PURPOSE. A 136px `.cg-select` has ~97.9px of readable width (see
+ * `cohortOpLabel` below, and `withCurrentField` below) — about 15 characters of 12.5px Inter.
+ * "is in the bottom N%" is 19 and would have shipped CLIPPED, which no assertion here can see
+ * and no screenshot in this session could catch. Dropping the "is " still costs nothing, and
+ * instruction 19 SHARPENED that argument rather than refuting it: the four numeric comparisons
+ * beside these were bare glyphs (`≥ > ≤ <`) and are now prefix-free WORDS ("more than",
+ * "less than or equal to"), so the row still reads without an "is " — and those words are
+ * longer than the glyphs they replaced, so this control has LESS spare room than when the
+ * width above was measured, not more. (Only those four are prefix-free; `eq` / `neq` /
+ * `between` still read "is" / "is not" / "is between", and the rank ops sit beside all of
+ * them.) The `Ranked` divider carries the "these are a different kind of question" signal.
+ * Fifth time this control has outgrown a label; the label gives way, never the control.
+ */
+export const RANK_OP_LABELS: Record<string, string> = {
+  topN: "top N",
+  bottomN: "bottom N",
+  inTopPct: "top N%",
+  inBottomPct: "bottom N%",
+  aboveAvg: "above average",
+  belowAvg: "below average",
+  inQuartile: "in quartile",
+  inDecile: "in decile",
+};
+
+/**
+ * The value a rank op starts at when it is chosen.
+ *
+ * Seeded rather than left blank, and this is a deliberate break from how the other operators
+ * behave: a blank value makes a rule INACTIVE, so `is in the top N` with nothing typed would
+ * sit in the builder narrowing nothing, and "the filter I just added does nothing" reads as a
+ * broken control rather than as an unfinished sentence. Every rank op has an obvious default —
+ * ten, or the top slice — so there is a right answer to seed. The two averages take none.
+ */
+export function rankDefault(op: FilterOp): string {
+  switch (op) {
+    case "topN":
+    case "bottomN":
+    case "inTopPct":
+    case "inBottomPct":
+    case "inDecile":
+      return "10";
+    case "inQuartile":
+      return "4";
+    default:
+      return ""; // aboveAvg / belowAvg — value-free
+  }
+}
+
+/* ⛔ `hasRankCondition` LIVED HERE AND IS DELETED WITH THE PARAGRAPH IT GATED (wave 34, R5).
+   Its whole job was to decide whether to draw the builder's rank explainer; the owner has
+   removed that paragraph, and the predicate had exactly one caller besides its own recursion.
+   ⚠ `isRankOp` stays: `opLabel` below still calls it. `isMeasureRule` was `hasRankCondition`'s
+   ONLY use in this module, so THIS FILE'S IMPORT of it went too — the symbol itself lives on in
+   `types.ts` with plenty of callers, including `FilterBuilderPanel` two files over. The
+   distinction matters: an unused IMPORT is dead weight here, an unused EXPORT would be dead code
+   there, and only one of those was true.
+   ⚠⚠ THIS COMMENT'S FIRST DRAFT SAID BOTH SYMBOLS "STAY, they have many callers" — and `tsc`
+   refuted it in the next run. That is the THIRD time in one session a confident claim about who
+   calls a symbol was wrong within a minute of writing it. The habit worth keeping is not "be more
+   careful"; it is that the compiler answers this question for free, so ask it before asserting. */
+
+/**
+ * Human label for an operator, read naturally per field type.
+ *
+ * ⭐ Instruction 19 (wave 40) — a numeric comparison reads as WORDS, never as a symbol, because
+ * "non-mathematical people get them confused". C5 makes this the ONE operator-label map, so the
+ * grid filter builder, the permission filter builder, view filters and measure conditions all
+ * changed together and no surface hand-writes an operator string of its own. (A measure
+ * condition needs no separate map: `FilterBuilderPanel` resolves its type from the measure
+ * itself and falls back to `currency`, and `MEASURE_OPS` offers exactly the six comparisons
+ * below, so a measure row reads its label off this same numeric branch.)
+ *
+ * ⚠ NO leading "is " on the four comparisons, unlike `automation/CondBuilder.tsx::OP_WORDS`
+ * whose voice otherwise sets the house standard here. These labels already outrun the control
+ * that renders them; W40-T30 widens `.cg-select` in `index.css` for "less than or equal to"
+ * exactly, and an "is " prefix would outrun the wider control too. This file does not own that
+ * width, and it must not buy itself slack by abbreviating: "at least" / "at most" are shorter
+ * and are precisely the shorthand instruction 19 exists to remove.
+ *
+ * `gte` is "more than or equal to", not "greater than or equal to", so one axis carries one
+ * vocabulary. "more than" and "less than" are the owner's own two examples; a set learned once
+ * beats two synonyms for the same direction, which is the whole point of the instruction.
+ */
+export function opLabel(op: FilterOp, t: FieldType): string {
+  // Rank first and type-independently: a rank op means the same thing on every numeric
+  // family, and a view whose column has since changed type must still SAY what it holds
+  // rather than falling through to a raw key.
+  if (isRankOp(op)) return RANK_OP_LABELS[op] ?? op;
+  // Checkbox first: its two value-free ops READ as states, not as blankness — the storage
+  // contract ('1' or blank) is an implementation detail the sentence must not leak.
+  if (t === "checkbox") {
+    if (op === "isNotEmpty") return "is checked";
+    if (op === "isEmpty") return "is unchecked";
+  }
+  // Type-independent: Airtable words these identically for every field type.
+  if (op === "isEmpty") return "is empty";
+  if (op === "isNotEmpty") return "is not empty";
+  if (isDateFamily(t)) {
+    switch (op) {
+      case "eq":
+        return "is";
+      case "neq":
+        return "is not";
+      case "within":
+        return "is within";
+      case "lt":
+        return "is before";
+      case "lte":
+        return "is on or before";
+      case "gt":
+        return "is after";
+      case "gte":
+        return "is on or after";
+      case "between":
+        return "is between";      // no longer offered; still rendered for a saved view
+    }
+  }
+  if (isNumericType(t)) {
+    switch (op) {
+      case "gte":
+        return "more than or equal to";
+      case "gt":
+        return "more than";
+      case "lte":
+        return "less than or equal to";
+      case "lt":
+        return "less than";
+      case "eq":
+        return "is";
+      case "neq":
+        return "is not";
+      case "between":
+        return "is between";
+      default:
+        return op;
+    }
+  }
+  if (t === "multiselect") {
+    // Membership wording over the joined-set cell. "has" IS `contains` (see opsForType) — only
+    // the label changes, so the engine and its Python mirror stay untouched.
+    switch (op) {
+      case "contains":
+        return "has";
+      case "doesNotContain":
+        return "does not have";
+      case "eq":
+        return "is exactly";
+      case "neq":
+        return "is not exactly";
+      default:
+        return op;
+    }
+  }
+  // text / status. (Airtable suffixes value-taking ops with "…" in the OPEN
+  // dropdown only; a native <select> shows one string in both states, so we use
+  // the closed-state wording — which is what's on screen almost all the time.)
+  switch (op) {
+    case "contains":
+      return "contains";
+    case "doesNotContain":
+      return "does not contain";
+    case "eq":
+      return "is";
+    case "neq":
+      return "is not";
+    default:
+      return op;
+  }
+}
+
+/**
+ * The offered list, PLUS whatever the rule is actually set to.
+ *
+ * A `<select>` whose `value` is not among its `<option>`s renders the FIRST option instead —
+ * so a saved view holding a dropped operator (a date `between`) or a column that has since left
+ * the filter list (`at_risk`, once its measure replacement shipped) would display something the
+ * rule does not say, and the first edit would silently rewrite it to that. Painted, plausible,
+ * and wrong: the class of failure a screenshot catches and an assertion does not.
+ */
+export function withCurrent<T extends string>(offered: readonly T[], current: T | undefined): T[] {
+  return current && !offered.includes(current) ? [...offered, current] : [...offered];
+}
+
+/** A group's summary line, mirroring Airtable's wording. */
+export function groupSummary(conj: Conjunction): string {
+  return conj === "or"
+    ? "Any of the following are true…"
+    : "All of the following are true…";
+}
+
+/**
+ * CG-8 — the operators a MEASURE condition may use, and why they are not `opsForType`.
+ *
+ * A measure is answered by a SQL `HAVING`, and `harness/measure_filter.OPS` has exactly six
+ * comparisons. `between` would need two, and `isEmpty`/`isNotEmpty` have no meaning for a sum
+ * that is defined to be 0 when there is nothing to add up — the resolver refuses all three by
+ * name. Offering them here would produce a condition the server can only reject.
+ *
+ * The owner's "dates between X and Y" is the WINDOW's between, not the value's, and that is the
+ * `custom` window kind — so nothing is lost.
+ */
+export const MEASURE_OP_LIST: FilterOp[] = [...MEASURE_OPS];
+
+/** CG-9 — narrower still when the other side is a measure. `=` and `≠` between two sums of
+ *  floats match nobody and everybody respectively; see types.ts MEASURE_PAIR_OPS. */
+export const MEASURE_PAIR_OP_LIST: FilterOp[] = [...MEASURE_PAIR_OPS];
+
+/**
+ * A cohort condition names a SET of cohorts (owner, 2026-07-27), so its operators are set
+ * operators. `eq`/`neq` are not offered — the validator rewrites them to `anyOf`/`noneOf`, and
+ * `withCurrent` would otherwise show a legacy view an operator it can never choose again.
+ */
+export const COHORT_OP_LIST: CohortOp[] = [...COHORT_OPS];
+
+/**
+ * ⚠ "is part of any of" measures ~96px at 12.5px Inter against the 97.9px of readable width a
+ * 136px select actually has (136 - 20.1 arrow - 16 padding - 2 border) — inside the box only
+ * until a fallback font renders it. Airtable's own wording for a multi-select is shorter and
+ * says the same thing, so the LABEL gives way, not the control. Third time this rule has been
+ * applied; see the "(not filterable)" and "the 75th percentile" clippings before it.
+ */
+export function cohortOpLabel(op: FilterOp | CohortOp): string {
+  switch (normalizeCohortOp(op)) {
+    case "allOf":
+      return "is all of";
+    case "noneOf":
+      return "is none of";
+    default:
+      return "is any of";
+  }
+}
+
+/** Item 20 — the mark a MEASURE row wears in every picker on this surface. Named once so the
+ *  three lists that offer measures cannot drift into two different glyphs for one concept. */
+export const MEASURE_MARK: FieldSelectType = "measure";
+
+/** A measure condition is identified by its window, so a new one needs a default window. */
+export const DEFAULT_WINDOW: WindowSpec = { kind: "ltm" };
+
+/** The default RANGE for `is within` — the owner's first example ("the past month"). */
+export const DEFAULT_DATE_WINDOW: WindowSpec = { kind: "past_month" };
+
+/**
+ * The ranges `is within` offers, in the owner's own order (item 3, 2026-07-26):
+ * the past number of days · the past week · the past month · the past year · this calendar
+ * week · this calendar month · this calendar year.
+ *
+ * Plus `custom`, which is not a nicety: dropping `between` from the date operators would
+ * otherwise remove the ability to ask for two exact dates at all. The remaining kinds
+ * (yesterday, last_quarter, ytd_last_year, the forward-looking ones…) stay available to a
+ * MEASURE's window, where they make sense; "last order is within year to date, last year" is a
+ * question nobody asks.
+ */
+export const WITHIN_KINDS: WindowKind[] = [
+  "last_n_days", "past_week", "past_month", "past_year",
+  "this_week", "this_month", "this_year", "custom",
+];
+
+/**
+ * The field dropdown's COLUMN half, plus the column the rule is actually set to if the picker
+ * no longer offers it. See `withCurrent` — a select whose value is missing from its options
+ * silently displays a different field than the rule holds. This is not hypothetical: the
+ * shipped "Win-back" list filters `at_risk`, which left the filter list the day its measure
+ * replacement arrived.
+ */
+export function withCurrentField(
+  fields: Field[],
+  current: string,
+  fieldByKey: Map<string, Field>,
+  measureByKey: Map<string, Measure>,
+  hasCohorts: boolean
+): FieldSelectItem[] {
+  // Item 20: the rows carry their TYPE now, because the picker paints the type mark. Same
+  // list, same order, same `withCurrent` rule — only the shape of a row grew a field.
+  const out: FieldSelectItem[] = fields.map((f) => ({
+    key: f.key, label: f.label, type: f.type,
+  }));
+  const known = new Set(out.map((o) => o.key));
+  if (!current || known.has(current) || measureByKey.has(current)) return out;
+  if (current === COHORT_FIELD && hasCohorts) return out;
+  // The field's OWN label, with no "(not filterable)" annotation: the select is ~170px and the
+  // suffix CLIPPED to "At risk $ (not filter" — a truncated parenthetical reads as a rendering
+  // bug, and the property that matters is that the condition says what it says. Found by
+  // reading the screenshot; every assertion in the run was green.
+  const f = fieldByKey.get(current);
+  out.push({ key: current, label: f ? f.label : current, type: f?.type });
+  return out;
+}
+
+/** Ids only have to be unique within one view's tree; they never leave this browser's view. */
+let ruleSeq = 0;
+export function newRuleId(): string {
+  ruleSeq += 1;
+  return `r${Date.now().toString(36)}${ruleSeq.toString(36)}`;
+}
+
+/** A fresh leaf condition on the first available field. */
+export function newCondition(fields: Field[]): FilterRule | null {
+  const f0 = fields[0];
+  if (!f0) return null;
+  return { colId: f0.key, op: opsForType(f0.type)[0], value: "" };
+}
+
+/** Total LEAF conditions in a filter tree (groups contribute their contents). */
+export function countConditions(nodes: FilterNode[]): number {
+  let n = 0;
+  for (const node of nodes)
+    n += isFilterGroup(node) ? countConditions(node.children) : 1;
+  return n;
+}

web/src/settings/DatabasePermsPane.tsx

@@ -0,0 +1,174 @@
+// ---------------------------------------------------------------------------
+// settings / DatabasePermsPane.tsx — ONE DATABASE'S RULE, given the whole pane.
+// (wave 40, owner instruction 7 · W40-T14.)
+//
+// ⭐ WHY IT EXISTS, IN THE OWNER'S OWN WORDS: *"Manage user, Access section: show
+// only the Database, with just a checkbox and an Edit button (put the Metrics
+// field toggle under there). Edit opens the whole database's Fields and Filters
+// to toggle, with a Back button to return."*
+//
+// ⚠ THE PARENTHESIS IN THAT QUOTE IS SUPERSEDED, AND ONLY THE PARENTHESIS. Owner instruction 13
+// (W40-T16) folded the Metrics toggle one level further in: it is no longer a box "under there"
+// but one CHECKBOX PER METRIC inside this pane's Hide-fields list. The room, the Back button and
+// the Fields/Filters pairing are instruction 7's and are unchanged. Read the quote as the reason
+// this file exists, never as a description of the controls it draws today.
+//
+// What it replaces is a single-row INLINE ACCORDION. That shape was right when
+// the list was two databases and the panels were the only thing under them; it
+// is wrong now, because a filter builder and a field list opened inside a row of
+// a list of every database the tenant has are two menus that failed to close.
+// A rule about one database gets a room, and the room says which database.
+//
+// ⛔ IT OWNS NO STATE AND WRITES NOTHING. Every value comes from the caller's
+// DRAFT and every change goes back out as a callback, exactly as
+// `ModulePermsList` does — `PermsEditor` holds the draft, the confirm and the
+// PUT. This component is a layout and a set of handlers, so the account page
+// keeps one source of truth for what is about to be saved.
+//
+// ⛔⛔ THE `lockedKey` / `hideableKeys` PAIR BELOW IS LOAD-BEARING AND ITS
+// FAILURE IS SILENT. Drop either and one click on "Hide all" hides the database's
+// own identity column: a record whose faithful enforcement is a table of blank
+// rows, which the server's PUT validation ACCEPTS because the identity column is
+// a perfectly known field key. Both halves ship together or the pane is a defect.
+// ---------------------------------------------------------------------------
+
+import { FilterBuilderPanel, FieldsHidePanel } from "../filter-kit";
+import type { FilterTree } from "../customer-grid/types";
+import type { PermsModule, PermsRecord } from "./permsModel";
+import { filterOf, hiddenSetFor, hideAllKeys, identityKey, showAllKeys } from "./permsModel";
+import "./perms.css";
+
+export interface DatabasePermsPaneProps {
+  /** The database being edited: its label titles the pane, its fields feed both panels. */
+  module: PermsModule;
+  /**
+   * ⚠ THE WHOLE DRAFT, keyed by module, NOT this module's entry. `filterOf` and `hiddenSetFor`
+   * are where "an absent filter is an empty tree" and "absent hidden fields is an empty set" are
+   * spelled, once; taking a bare entry would make this file spell them a second time, and two
+   * spellings of one default are what those helpers exist to prevent.
+   */
+  entries: PermsRecord;
+  /** Return to the account page. The SAME function the account page's Escape handler calls. */
+  onBack: () => void;
+  onFilter: (next: FilterTree | null) => void;
+  onToggleHidden: (fieldKey: string) => void;
+  onSetHidden: (keys: string[]) => void;
+  /*
+   * ⭐⭐ W40-T16 (OWNER INSTRUCTION 13) — `onMetrics` IS GONE FROM THIS PANE, AND SO IS THE BOX
+   * IT DREW. Owner, verbatim: *"Fold 'Metrics fields (lookback measures over this database)' into
+   * the 'Hide fields' checkboxes, one row per metric, named 'Metric - Revenue', 'Metric - Order'
+   * and so on, so a user can check the ones the permissioning is limited to."*
+   *
+   * ⛔ A DELETION RATHER THAN A HIDE, because the control it replaces answered a COARSER
+   * question. One box said "this account may build measures over this database, or may not";
+   * the Hide-fields list below now carries one checkbox per bound measure, so the same admin
+   * decides WHICH ones. Leaving the blanket box beside them would put two controls on one screen
+   * that can contradict each other, and the record has no way to express the contradiction.
+   *
+   * ⚠ THE CAPABILITY ITSELF IS UNTOUCHED. `PermsEntry.metrics` still rides the wire, still parses
+   * (`parseEntry`) and is still emitted (`toPutBody`), because a record written before this
+   * ticket may carry an explicit revocation. What honours it here is `hiddenSetFor` below, on the
+   * READ side: a blanket `metrics: false` paints every metric row as hidden without rewriting
+   * anybody's stored rule. See the note at that call.
+   */
+  /** People this tenant can name in a `user` condition. Absent ⇒ the panel says so. */
+  userOptions?: string[];
+}
+
+export function DatabasePermsPane({
+  module,
+  entries,
+  onBack,
+  onFilter,
+  onToggleHidden,
+  onSetHidden,
+  userOptions,
+}: DatabasePermsPaneProps) {
+  return (
+    <div className="set-dbperm">
+      <div className="set-dbperm-head">
+        {/* ⛔ ONE WORD, AND THE SHORTNESS IS FORCED RATHER THAN CHOSEN. The account's own exit,
+            "Back to accounts", is rendered by `PermsEditor` DIRECTLY ABOVE this pane and stays
+            there while the room is open. Spelling this one "Back to account" would put two
+            controls one letter apart on one screen, going to different places, which is a worse
+            room than either label is a good one. Position already says where this one goes: it
+            sits on the database title's line, so it leaves the database. `DESIGN.md` §4 asks for
+            the shorter label wherever the longer one is narration, and here it also happens to
+            be the only unambiguous one. */}
+        <button type="button" className="set-secondary set-dbperm-back" onClick={onBack}>
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden focusable="false">
+            <path
+              d="M9.5 4 5.5 8l4 4"
+              stroke="currentColor"
+              strokeWidth={1.3}
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+          Back
+        </button>
+        {/* The pane says which database it is about. Without it every one of these rooms looks
+            identical, and the reader's only clue is what they clicked a scroll ago. */}
+        <h4 className="set-h4 set-dbperm-title">{module.label}</h4>
+      </div>
+
+      {/* THE KIT'S OWN PANELS (contract C-KIT), not lookalikes: the same two the grid toolbar
+          mounts, so an admin writes a condition with the control they already know and there is
+          one condition grammar in the product rather than two that drift within a wave.
+          They STACK here rather than sitting side by side: the pane is theirs alone now, and a
+          filter and a field list read as two decisions taken in order, not one wide row. */}
+      <div className="set-dbperm-panels">
+        <div className="cg-pop set-perm-pop">
+          <FilterBuilderPanel
+            fields={module.fields}
+            filters={filterOf(entries, module.key)}
+            onChange={onFilter}
+            userOptions={userOptions}
+          />
+        </div>
+        <div className="cg-pop set-perm-pop">
+          {/* ⭐⭐ W40-T16 — THIS LIST IS WHERE THE METRICS RULE NOW LIVES. `module.fields` carries
+              C3's `measure_`-namespaced pseudo-fields, `permsModel::parseField` marks each one,
+              and the panel draws it as an ordinary checkbox named "Metric - Revenue". Checking it
+              puts that field's key into `hiddenFields` through the same `onToggle` every other
+              row uses, so there is no second write path for a metric and no second record shape.
+              ⛔ `hiddenSetFor`, NOT `hiddenSet`, AND THE DIFFERENCE IS THE MIGRATION. A record
+              written before this ticket can carry a blanket `metrics: false` (W38-T19's box), and
+              the control that wrote it is gone from this pane. The union paints every metric row
+              as hidden for such a record, so the old revocation is HONOURED on screen rather than
+              silently reading as a grant. It is a read-side union on purpose: folding it into
+              `hiddenFields` would edit somebody's stored rule as a side effect of opening a page. */}
+          <FieldsHidePanel
+            fields={module.fields}
+            hidden={hiddenSetFor(entries, module.key, module.fields)}
+            onToggle={onToggleHidden}
+            /* ⭐⭐ W40-T17 (OWNER INSTRUCTION 15) — THE ONE PROP THAT MAKES THIS MOUNT DIFFER
+               FROM THE GRID'S. Owner, verbatim: *"stop displaying 'Shared with me' / 'Shared
+               with everyone' fields under Hide Fields - permission on pre-set Fields only."*
+               `false` drops both sections AND swaps the membership rule for AM-2's
+               `metric || !custom`, so this list is the database's own columns plus its bound
+               measures and nothing else.
+               ⛔ IT IS PASSED HERE AND NOWHERE ELSE. `customer-grid/Toolbar.tsx` mounts the same
+               panel and passes no `sharedSections`, so the grid keeps all three sections exactly
+               as the 2026-08-21 hotfix left them. That is the whole reason this is a prop rather
+               than a deletion: the two surfaces are supposed to differ now. */
+            sharedSections={false}
+            // ⛔⛔ BOTH HALVES OF THE TRAP, and neither is decoration. `lockedKey` disables the
+            // identity column's own checkbox; `hideableKeys` is what keeps "Hide all" from
+            // including it anyway. One without the other still ships blank rows.
+            lockedKey={identityKey(module.fields)}
+            /* ⭐⭐ W40-T17 — THE BULK ACTIONS REACH EXACTLY WHAT THIS ROOM LISTS, and the
+               narrowing above is what owes them the change: a list showing four rows whose
+               "Show all" clears hidden state for seven fields would WIDEN a permission through
+               a control that never displayed the columns it just revealed. `showAllKeys`
+               subtracts the governed keys instead of emptying the record; `hideAllKeys` adds
+               them without disturbing what the record hides elsewhere. Both strip the identity
+               key, so the trap above stays closed from this side too. */
+            onHideAll={() => onSetHidden(hideAllKeys(entries, module.key, module.fields))}
+            onShowAll={() => onSetHidden(showAllKeys(entries, module.key, module.fields))}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

web/src/settings/ModulePermsList.tsx

@@ -30,7 +30,8 @@ import type { ReactNode } from "react";
 import { FilterBuilderPanel, FieldsHidePanel } from "../filter-kit";
 import type { FilterTree } from "../customer-grid/types";
 import type { PermsModule, PermsRecord } from "./permsModel";
-import { filterOf, hiddenSet, hideableKeys, identityKey, moduleSummary } from "./permsModel";
+import { filterOf, hiddenSetFor, hideAllKeys, identityKey, moduleSummary,
+         showAllKeys } from "./permsModel";
 import "./perms.css";
 
 export interface ModulePermsListProps {
@@ -54,10 +55,32 @@ export interface ModulePermsListProps {
    * reds `web_ui` on a build break in a file that ticket may not repair.
    */
   onMetrics?: (key: string, on: boolean) => void;
+  /**
+   * ⭐⭐ W40-T14 (owner instruction 7) — THE DRILL-IN. When supplied, the row is a checkbox and
+   * ONE way in: this opens a full-pane editor of that database's Fields and Filters, and the row
+   * renders no summary, no accordion, no inline panels, no Metrics box and no `headExtra`. Owner,
+   * verbatim: *"show only the Database, with just a checkbox and an Edit button (put the Metrics
+   * field toggle under there)"*.
+   *
+   * ⛔ OPTIONAL FOR THE SAME FORCED REASON `onMetrics` IS. `manage-agent/ManageAgentPane.tsx`
+   * mounts this component and is outside W40-T14's fence; a required prop stops it compiling in a
+   * file this ticket may not repair. Absent ⇒ every branch below is the accordion this file has
+   * always rendered, byte for byte.
+   */
+  onEdit?: (key: string) => void;
   /** People this tenant can name in a `user` condition. Absent ⇒ the panel says so. */
   userOptions?: string[];
-  /** Anything the CALLER wants in a row's head — the account editor's "Copy to…"
-   *  door. Returning null is the normal case and costs the row nothing. */
+  /**
+   * Anything the CALLER wants in a row's head. Returning null is the normal case and costs the
+   * row nothing.
+   *
+   * ⚠ NO CALLER SUPPLIES IT TODAY, AND THE PROP IS KEPT ANYWAY. It carried the account editor's
+   * per-row "Copy to" door, which owner instruction 7 DELETED (W40-T14) — the account-level
+   * "Apply this access to…" survives and is the whole copy affordance now. What is left here is
+   * a seam, declared because `manage-agent/ManageAgentPane.tsx` mounts this same component from
+   * outside that ticket's fence and removing a prop is a breaking change to a file it may not
+   * repair. A drilled row ignores it regardless: `onEdit` means "a checkbox and one way in".
+   */
   headExtra?: (m: PermsModule) => ReactNode;
   /** Shown when the tenant governs nothing at all. */
   emptyNote?: string;
@@ -71,10 +94,15 @@ export function ModulePermsList({
   onToggleHidden,
   onSetHidden,
   onMetrics,
+  onEdit,
   userOptions,
   headExtra,
   emptyNote,
 }: ModulePermsListProps) {
+  // ⭐ W40-T14 — WHICH MODE, read ONCE. Every branch below asks this same question, and a second
+  // spelling of it (`onEdit !== undefined` here, `!!onEdit` there) is how two of them come to
+  // disagree about which room they are in.
+  const drilled = onEdit !== undefined;
   // ⭐ Owner item 11: *"the database should not show all immediately the detail
   // (for filter or hide fields)"*. Single-valued rather than a Set, deliberately
   // — the complaint was a wall of panels, and an accordion cannot become one by
@@ -127,8 +155,25 @@ export function ModulePermsList({
                   controls keeps every new one off that rule — one flex child in,
                   one flex child out. */}
               <span className="set-perm-headend">
-                <span className="set-perm-sum">{moduleSummary(entry, schemaless)}</span>
-                {canDetail ? (
+                {/* ⭐ W40-T14 — the summary, the accordion and `headExtra` are the ACCORDION
+                    room's furniture. The drill-in row is "a checkbox and one way in", so it
+                    renders the Edit button in their place and nothing else. */}
+                {drilled ? null : (
+                  <span className="set-perm-sum">{moduleSummary(entry, schemaless)}</span>
+                )}
+                {canDetail && drilled ? (
+                  // ⛔ `canDetail` (= `on && !schemaless`), NOT unconditional: a database nobody
+                  // may open has no rule to edit, and a schemaless surface has no fields and no
+                  // filter — the help paragraph below already says so for that second case.
+                  <button
+                    type="button"
+                    className="set-secondary set-perm-edit"
+                    onClick={() => onEdit(m.key)}
+                  >
+                    Edit
+                  </button>
+                ) : null}
+                {canDetail && !drilled ? (
                   <button
                     type="button"
                     className="set-secondary set-perm-disclose"
@@ -138,7 +183,7 @@ export function ModulePermsList({
                     {shown ? "Hide detail" : "Conditions and fields"}
                   </button>
                 ) : null}
-                {headExtra?.(m) ?? null}
+                {drilled ? null : headExtra?.(m) ?? null}
               </span>
             </div>
 
@@ -154,7 +199,28 @@ export function ModulePermsList({
                 `space-between` and lives in `index.css`, which this ticket's fence
                 does not contain; a new flex child there would need CSS that cannot
                 be written, so the box takes its own line under the head. */}
-            {on && !schemaless && onMetrics ? (
+            {/* ⭐ W40-T14 — `!drilled &&` is the whole change here. Owner instruction 7 moved this
+                box INTO the database's own pane ("put the Metrics field toggle under there"), so
+                the drill-in row must not draw a second one.
+                ⭐⭐ W40-T16 — AND AFTER THIS TICKET THE BOX BELOW RENDERS NOWHERE AT ALL. Owner
+                instruction 13 folded the blanket toggle into the HIDE-FIELDS list, one checkbox
+                per metric, and `DatabasePermsPane`'s copy is deleted; `PermsEditor` passes
+                `onEdit` for every account row, so `!drilled` suppresses this one. ⛔ AND THE
+                OTHER CALLER DOES NOT MOUNT IT EITHER — MEASURED, not assumed:
+                `manage-agent/ManageAgentPane.tsx` passes exactly `modules, entries, onAccess,
+                onFilter, onToggleHidden, onSetHidden, userOptions, emptyNote`, and no
+                `onMetrics`. So nothing in the UI writes `PermsEntry.metrics` any more.
+                ⚠ THAT IS INSTRUCTION 13, NOT A DEFECT: a blanket control REPLACED by finer ones
+                is the whole ask. The boolean survives as a legacy value — read by `parseEntry`,
+                emitted by `toPutBody`, honoured on screen by `hiddenSetFor` — and every record
+                written from here on carries it GRANTED.
+                ⛔ THE JSX IS KEPT AS A SEAM, DELIBERATELY AND WITH ITS COST NAMED. It is what
+                lets a future room govern the capability without re-deriving the prop, and it
+                carries `verify_ui.py`'s `t19-unmounted` / `t19-control-gone` controls, the only
+                two in that file built from code that actually shipped broken. Deleting it is
+                legal — nothing passes the prop, so `tsc` would not notice — but it is a decision
+                to take out loud, in the same change as those two gate blocks, never a tidy-up. */}
+            {!drilled && on && !schemaless && onMetrics ? (
               <label className="set-check">
                 <input
                   type="checkbox"
@@ -179,7 +245,10 @@ export function ModulePermsList({
               </p>
             ) : null}
 
-            {canDetail && shown ? (
+            {/* ⚠ `!drilled` is written even though `openDetail` can never leave `null` in that
+                mode (nothing renders the disclosure that sets it). An invariant held by an absent
+                button is one refactor away from being false; the gate on the thing itself is not. */}
+            {!drilled && canDetail && shown ? (
               <div className="set-perm-panels">
                 <div className="cg-pop set-perm-pop">
                   <FilterBuilderPanel
@@ -190,9 +259,15 @@ export function ModulePermsList({
                   />
                 </div>
                 <div className="cg-pop set-perm-pop">
+                  {/* ⭐ W40-T16 — `hiddenSetFor`, the same resolver the manage-user pane uses.
+                      ONE spelling of "which keys read as hidden": this room's fields carry no
+                      metric flag today (the agent editor's payload has no `measure_` pseudo-
+                      fields), so the union adds nothing here and the accordion is unchanged.
+                      It is written anyway because the alternative is two answers to one question
+                      in two files, which is the drift this component was extracted to prevent. */}
                   <FieldsHidePanel
                     fields={m.fields}
-                    hidden={hiddenSet(entries, m.key)}
+                    hidden={hiddenSetFor(entries, m.key, m.fields)}
                     onToggle={(key) => onToggleHidden(m.key, key)}
                     // ⚠ `lockedKey` IS NOT OPTIONAL HERE, whatever the prop says.
                     // Absent, the panel locks nothing and one click on "Hide all"
@@ -201,8 +276,23 @@ export function ModulePermsList({
                     // validation would accept because the identity column is a
                     // perfectly KNOWN field key.
                     lockedKey={identityKey(m.fields)}
-                    onHideAll={() => onSetHidden(m.key, hideableKeys(m.fields))}
-                    onShowAll={() => onSetHidden(m.key, [])}
+                    /* ⭐⭐ W40-T17 (owner instruction 15) — UNCONDITIONAL HERE, NOT A SECOND
+                        PROP, AND THAT IS WHAT THIS COMPONENT IS. `ModulePermsList` IS the
+                        permissioning list: every mount of it — the account editor's Access
+                        section and `manage-agent/ManageAgentPane` alike — is editing the same
+                        `perms` record through the same wall, so its panel is always a
+                        permissioning panel and there is no caller for whom the shared sections
+                        would be right. Owner: *"stop displaying 'Shared with me' / 'Shared with
+                        everyone' fields under Hide Fields - permission on pre-set Fields only."*
+                        That is a sentence about permissioning, not about one screen.
+                        ⚠ IT IS ALSO WHAT KEEPS THE TWO ROOMS IDENTICAL. This file exists because
+                        the owner ruled manage-agent is *"the same exact layout"* as manage user
+                        (wave 33); gating one room and not the other would put the divergence
+                        inside the very component extracted to prevent it — and LATENTLY, since
+                        neither section fills up until the server ships `custom`/`shared`. */
+                    sharedSections={false}
+                    onHideAll={() => onSetHidden(m.key, hideAllKeys(entries, m.key, m.fields))}
+                    onShowAll={() => onSetHidden(m.key, showAllKeys(entries, m.key, m.fields))}
                   />
                 </div>
               </div>

web/src/settings/perms.css

@@ -23,10 +23,13 @@
   flex: none;
 }
 
-/* Smaller than a primary action and quieter than `Copy to…`: this button reveals
-   detail, it does not commit anything. It borrows `.set-secondary`'s border,
-   surface and focus ring rather than restating them — a second definition of the
-   button chrome is a second place for the focus ring to go missing. */
+/* Smaller and quieter than a primary action: this button reveals detail, it does
+   not commit anything. It borrows `.set-secondary`'s border, surface and focus
+   ring rather than restating them — a second definition of the button chrome is a
+   second place for the focus ring to go missing.
+   ⚠ STILL LIVE, and only in the agent editor. Wave 40 replaced the account
+   editor's accordion with a full-pane room (`.set-perm-edit` below); the agent
+   editor mounts the same list without `onEdit` and keeps this disclosure. */
 .set-perm-disclose {
   font-size: var(--lp-fs-2xs);
   padding: 3px 9px;
@@ -40,8 +43,174 @@
   color: var(--lp-blue-deep);
 }
 
+/* ── wave 40, owner instruction 7 (W40-T14): the row's ONE way in, and the room
+   it opens ──────────────────────────────────────────────────────────────────
+ *
+ * WHY THE ACCORDION BECAME A ROOM. Wave 33's disclosure answered "show every
+ * database, not every panel", and it did — while the list was two rows. It is now
+ * every database the tenant has, and a filter builder unfolded inside one row of
+ * that list reads as a menu that failed to close. Owner: *"Edit opens the whole
+ * database's Fields and Filters to toggle, with a Back button to return."*
+ */
+
+/* Sized and quietened like the disclosure it replaces, and borrowing
+   `.set-secondary`'s border, surface and focus ring for the same reason that one
+   does: a second definition of the button chrome is a second place for the focus
+   ring to go missing. */
+.set-perm-edit {
+  font-size: var(--lp-fs-2xs);
+  padding: 3px 9px;
+  white-space: nowrap;
+}
+
+/* The way out and the name of the room share one line, so the reader learns
+   where they are and how to leave in a single glance. `baseline` rather than
+   `center`: the title's cap height should sit on the button's label, which is
+   the alignment every other head on this page uses. */
+.set-dbperm-head {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  margin-bottom: 16px;
+}
+/* The chevron rides with the words rather than beside them. */
+.set-dbperm-back { display: inline-flex; align-items: center; gap: 6px; flex: none; }
+/* `.set-h4` carries block margins meant for a heading that starts a section; here
+   it is a flex item on the head's own line. */
+.set-dbperm-title { margin: 0; min-width: 0; }
+/* ⭐ W40-T16 — `.set-dbperm-metrics` IS DELETED WITH THE BOX IT SPACED. Owner instruction 13
+   folded the blanket Metrics checkbox into the Hide-fields list as one row per metric, so the
+   rule had no element left to apply to. A rule that matches nothing is how a stylesheet ends up
+   describing a screen that no longer exists. */
+
+/* THE PANELS STACK, one decision per eye level. A grid rather than a column flex
+   box on purpose: `.set-perm-pop` carries `flex: 1 1 320px` for the side-by-side
+   accordion, and flex properties are inert on a GRID item, so this container gets
+   the stacking it wants without redefining a rule that belongs to `index.css`. */
+.set-dbperm-panels {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 14px;
+}
+
+/* ── wave 40, owner instructions 8 + 9 + 10 (W40-T15): the account page stops
+   shouting, and Save sits where the hand is ──────────────────────────────────
+ *
+ * Three complaints, one page. The header put an exit, a person and two chips on
+ * one flex row; the reset-password control was split across a two-column grid
+ * with its consequence read BEFORE the button that causes it; and a long access
+ * list had its only Save at the bottom.
+ *
+ * ⛔ EVERY SELECTOR BELOW THAT OVERRIDES AN `index.css` DEFAULT CARRIES TWO
+ * CLASSES ON PURPOSE. A single-class rule here would tie at 0-1-0 with the rule
+ * it means to beat, and the winner would then be vite's import order across two
+ * stylesheets — a thing no reader of either file can see. Nothing in `index.css`
+ * is edited or restated; these only bound the new arrangement.
+ */
+
+/* --- instruction 9c: the way out is page chrome, on its own line ----------- */
+/* The quiet-button register this system already uses (`.shell-newfolder`: muted
+   ink, wash on hover, nothing else), with the native chrome reset in the BASE
+   rule as `DESIGN.md` §4 requires. ⚠ `font: inherit` FIRST and the size after
+   it: a shorthand declared below its own longhands re-expands and undoes them,
+   which is the Alerts-button scar `verify_ui.py`'s R5b cascade check exists to
+   catch. The negative left margin is optical, not spacing — it pulls the
+   chevron out to the page's text edge so the label starts where the title does. */
+.set-perm-back {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  border: 0;
+  background: transparent;
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+  color: var(--lp-muted);
+  padding: 4px 8px;
+  margin: 0 0 10px -8px;
+  border-radius: var(--lp-r-sm);
+  cursor: pointer;
+}
+.set-perm-back:hover { background: var(--lp-wash); color: var(--lp-ink); }
+.set-perm-back:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 1px; }
+
+/* The identity is the page TITLE now, so it owns the space under the head
+   rather than sharing a row with the exit. */
+.set-perm-ident { margin-bottom: 16px; }
+/* The chips sit beside the name, which is where `index.css` already argued they
+   belong: pushed to the far end they read as a status of the dialog rather than
+   of the person.
+   ⚠ `baseline`, NOT the `center` the old head used, and the difference is which
+   sibling the chip is beside. On that row the chip sat next to a TWO-LINE block
+   (name over username) and index.css records the reason for centring it: a chip
+   top-aligned against two lines looks dropped. Here its sibling is the one-line
+   title, so the chip's text sits on the title's baseline, which is the alignment
+   `.set-perm-modhead` and `.set-dbperm-head` already use for a heading and a
+   smaller control on one line. The username moved out of this row entirely. */
+.set-perm-nameline {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+/* --- instruction 9a + 9b: the password group reads top to bottom ----------- */
+/* Label, box and button on one line and one baseline; the consequence under
+   them. `flex-end` rather than `baseline` because the label sits ABOVE the box:
+   what has to line up is the bottom of the input and the bottom of the button,
+   which are both 32px tall. */
+.set-pw-row {
+  display: flex;
+  align-items: flex-end;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+/* `.set-field` carries 13px of bottom margin meant for stacked form rows; here
+   it would lift the box off the button's baseline. The width keeps the box the
+   size a password is, instead of letting it stretch the whole card. */
+.set-pw-group .set-pw-field { flex: 1 1 220px; max-width: 320px; margin-bottom: 0; }
+/* The gap goes ABOVE the sentence now that the sentence is last. */
+.set-perms .set-pw-note { margin: 8px 0 0; }
+
+/* --- instruction 10: Save access at the head of the section too ------------ */
+/* The trailing controls of the Access head, grouped as ONE flex child so
+   `index.css`'s `space-between` on `.set-perm-sect` still sees exactly two. */
+.set-perm-sectend {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex: none;
+}
+/* Sized to the copy door beside it rather than to the 32px action row at the
+   bottom of the page: controls sharing a row share a height (`DESIGN.md` §4),
+   and this one is riding a heading's line. It stays `.set-primary` in colour,
+   because it commits the same write the bottom button commits. */
+.set-perms .set-perm-savetop {
+  height: 28px;
+  padding: 0 12px;
+  font-size: var(--lp-fs-2xs);
+}
+
+/* --- instruction 8: "Database" and "Module" ------------------------------- */
+/* A label for a group of cards, one step quieter than the `Access` heading it
+   sits under, so the reader gets the hierarchy from weight rather than from
+   indentation. Sentence case: the product has no ALL-CAPS chrome.
+   ⚠ The bottom margin is deliberately small because `.set-perm-mod` brings 14px
+   of its own top margin and adjacent margins collapse to the larger — anything
+   under 14px here has no effect at all, so 4px says "as tight as the card
+   allows" rather than pretending to a number the layout cannot honour. */
+.set-perms .set-perm-group {
+  margin: 22px 0 4px;
+  font-size: var(--lp-fs-2xs);
+  color: var(--lp-muted);
+}
+
 @media (max-width: 640px) {
   /* The head wraps before the label truncates: a database name is the one thing
      in this row that cannot be guessed from context. */
   .set-perm-headend { flex-wrap: wrap; justify-content: flex-end; }
+  .set-dbperm-head { flex-wrap: wrap; }
+  /* The Access heading keeps its own line and the two controls take the next
+     one, rather than the copy door and Save being crushed into a strip beside
+     the word. */
+  .set-perm-sectend { flex-wrap: wrap; justify-content: flex-end; }
 }