Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,5 +1,5 @@
 {
- "current": "c2d4c3a",
+ "current": "85374f1",
  "releases": [
   {
    "version": "v29",

VERSION

@@ -1 +1 @@
-c2d4c3a
+85374f1

api/routes_admin.py

@@ -755,9 +755,15 @@ def _clean_perms(v, governed_keys=None, session=None):
                           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}
+        # ⭐⭐ 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
+        # revocation. `perm_scope.may_metrics` applies the identical rule on the read side, so
+        # 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({str(h) for h in hidden}),
+                    "metrics": bool(raw.get("metrics", True))}
     _refuse_unshapeable_bu(out)
     return out
 
@@ -1078,8 +1084,16 @@ def get_perms(username: str, session: Session = Depends(admin_gate)):
         _default = (perm_scope.nav_may_open(users._public(uname, rec), k)
                     if any(m.get("surface") and m["key"] == k for m in modules) else
                     perm_scope.may_read(users._public(uname, rec), k, st=session.runtime))
-        perms_out[k] = e if isinstance(e, dict) else {
-            "access": bool(_default), "filter": None, "hiddenFields": []}
+        # ⭐⭐ W38-T19 — `metrics` RIDES EVERY ENTRY, BACKFILLED TO GRANTED ON A RECORD WRITTEN
+        # BEFORE THE KEY EXISTED. The wire is TOTAL on purpose: the client's own parse already
+        # reads an absent key as granted, so this line changes no rendering — what it changes is
+        # what a HUMAN reads off the payload while debugging, and what the PUT round-trips. The
+        # stored dict is copied rather than mutated: `rec` is the live registry record and
+        # stamping a key onto it here would write a permission nobody saved.
+        perms_out[k] = (dict(e, metrics=bool(e.get("metrics", True)))
+                        if isinstance(e, dict) else
+                        {"access": bool(_default), "filter": None, "hiddenFields": [],
+                         "metrics": True})
     return {"username": uname,
             "perms": perms_out,
             # S3 ask 2 — the marker rides the GET. An absent module entry means DENY on a

api/routes_customers.py

@@ -1,376 +1,834 @@
-"""routes_customers.py — X2's read + write of the customer table, BU-SCOPED (EXIT-3b / EXIT-2a).
-
-Two things happen here that did not happen in the pre-wave `main.py`:
-
-  1. **ROWS ARE SCOPED TO THE SESSION.** The old `/api/customers` served `cl.pool()` — the whole
-     book, to anyone holding the shared APP_PASSWORD. Now the pool is built with
-     `(team_id, agent_name)` derived from the USER RECORD, so a Royal-only user never receives a
-     Fisch row and an agent-linked login never receives another rep's book. The scope is applied
-     at the QUERY, not as a post-filter, so there is no moment at which the other BU's rows exist
-     in this response.
-
-  2. **THE OVERLAY FORK IS GONE.** `aios-web/api/data/overlay.json` was a SECOND writable home
-     for the same user-owned fields the Streamlit app keeps in the tenant store — two truths, and
-     whichever process you asked last was right. Reads and writes now both go through
-     `modules.customer_data`'s table-workspace functions: ONE store (C1c, ARCHITECTURE §1a rule 3).
-
-⚠ ONE STORE IS NOT YET ONE CACHE (strangler-period, booked honestly). `core.store.get()` is
-cache-first per PROCESS, so a write from the Streamlit container is invisible to a running API
-container until its cache is refreshed, and vice versa. Deleting the fork removes the second
-SOURCE OF TRUTH; it does not make the two runtimes coherent. The fix is X4/Postgres (task C-4,
-owner-blocked on B-3), and no test here may claim read-your-writes ACROSS runtimes — a TestClient
-proof is single-process and would report green on exactly the thing that is still broken.
-"""
-import time
-
-from fastapi import APIRouter, Body, Depends
-
-import scope_cache
-from deps import Session, err, module_gate, perms
-
-router = APIRouter(prefix="/api/v1")
-
-#: The surface these routes serve. Both legs are gated on it, so a user without the grant gets a
-#: 403 rather than an empty table that looks like "you have no customers".
-MODULE = "customer_data"
-
-_CACHE_TTL = 900       # the pool build is slow (Odoo + reconciliation); 15 min, as before
-
-
-def _pool_rows(session: Session):
-    """The reconciled Odoo pool for this session's SCOPE — the slow part, and the only part that
-    may be shared between users.
-
-    ⛔ WHAT MAY BE CACHED HERE, AND WHY THE LINE IS EXACTLY HERE. The cache key is
-    `(team_id, agent)` and the cached value is the raw pool: Odoo-source columns only. That is
-    genuinely scope-shaped — two users with the same BU and the same book are asking the same
-    question, and `cl.pool()` is expensive (an Odoo pull plus reconciliation).
-
-    The FULL PAYLOAD is NOT cacheable on this key, and caching it here was a real defect I shipped
-    and then removed. `fields` comes from `fields_from_workspace(ws)` — that user's own `custom_`
-    and `measure_` columns — and every overlay cell comes from `ws['overlays']`; the table
-    workspace is read as `data[username]` and written as `patch_table_overlay(uname, …)`, i.e.
-    PER USER. So two Royal-only users with no agent link share `(6, None)` and the second one
-    would have been served the FIRST one's private notes and private columns. The scope key was
-    right for the pool and wrong for everything wrapped around it.
-
-    It survived a green 129-check battery because every fixture user had a DISTINCT
-    `(team_id, agent)` pair, so no two of them ever collided on the key — the test set could not
-    express the bug. `verify_api.py` now carries a same-scope second user for exactly this.
-    """
-    rt = session.runtime
-    team_id, agent = _team_agent(session)
-    return _pool_for(rt, team_id, agent)
-
-
-def _pool_for(rt, team_id, agent):
-    """The cached pool for an explicit scope — session-free so the prewarm thread and the
-    stale-refresh path can call it. STALE-WHILE-REFRESH (scope_cache): once a copy exists no
-    request blocks on the 10–30s Odoo rebuild again; only a scope's FIRST-ever build does.
-
-    DEBT-2 (2026-08-04): while the tenant's RESOLVED Odoo source is PAUSED this path never
-    goes live — it serves the in-process copy at any age, else the persisted pause-time
-    snapshot (restart-safe), else answers 503. Never a WIDER scope's snapshot: handing a
-    scoped user the consolidated rows would widen their book, which is worse than an error."""
-    import modules.customer_data as cl
-    import routes_keychain
-
-    key = ("pool", team_id, agent)
-
-    if routes_keychain.odoo_paused(rt):
-        hit = rt.pool_cache.get(key)
-        if hit:
-            return hit[1]
-        snap = routes_keychain.load_pool_snapshot(rt, team_id, agent)
-        if snap is not None:
-            rt.pool_cache[key] = snap          # seed, so the memo stamps stay coherent
-            return snap[1]
-        raise err(503, "connector_paused",
-                  "this data source is paused and no snapshot exists for your scope — "
-                  "an admin can resume it under Settings → Connectors")
-
-    def _build():
-        # ⚠ THE SCOPE GOES INTO THE BUILDER. `pool(agent_name, team_id)` is the same reconciled
-        # builder the Streamlit page uses — passing the scope here is what makes the isolation a
-        # property of the QUERY instead of a filter someone can forget to apply downstream.
-        return cl.pool(agent, team_id)
-
-    def _evict():
-        # Bounded: a scope cache that only ever grows is a memory leak in a shared process.
-        if len(rt.pool_cache) > 16:
-            for stale in sorted(rt.pool_cache, key=lambda k: rt.pool_cache[k][0])[:8]:
-                rt.pool_cache.pop(stale, None)
-
-    return scope_cache.get(rt.pool_cache, key, _CACHE_TTL, _build, _evict)
-
-
-def warm_default(rt):
-    """Boot prewarm: the consolidated pool `(None, None)` — the scope every admin and every
-    all-BU account lands on. Called from main.py's prewarm thread only."""
-    _pool_for(rt, None, None)
-
-
-def _team_agent(session: Session):
-    """The `(team_id, agent)` this session's POOL is built with — ONE derivation point, used by
-    `_pool_rows` and `grid_assembly` alike, so the cache key and the query can never disagree.
-
-    ⛔ WAVE 15 R1: THIS NOW COMES FROM THE PERMANENT FILTER (C-PERM amendment 3). `team_id` is
-    not a row filter — `customer_data._pool_build` passes it into `cust._cust_rev` three times
-    and into `_cadence_bulk`, so it decides what `rev`/`ly`/`ltm`/`aov`/`status` MEAN. Enforcing
-    a BU purely as a post-filter would keep the row list right and silently consolidate every
-    number. So the pushdown survives as a DERIVATION OF the declared filter rather than a second
-    wall beside it, and `perm_scope.derive_pool_scope` falls back to the legacy `bus`/`agent`
-    derivation for any record the migration has not reached yet.
-    """
-    import core.perm_scope as perm_scope
-    return perm_scope.derive_pool_scope(session.user, MODULE)
-
-
-def _pool_stamp(rt, team_id, agent):
-    """The cached pool's build timestamp — the DATA STAMP in every measure-memo key, so a pool
-    refresh invalidates the memoised answers exactly when the underlying rows changed."""
-    entry = rt.pool_cache.get(("pool", team_id, agent))
-    return entry[0] if isinstance(entry, tuple) and entry else 0
-
-
-def _measure_err(tag, e):
-    try:
-        import harness.telemetry as _tel
-        _tel.error(f"api:{tag}", e)
-    except Exception:
-        pass
-
-
-def grid_assembly(session: Session, scope: str = "customer", storage_key: str = "",
-                  consume_corrections: bool = True):
-    """ONE assembly of this session's grid state, shared by `/customers`, `/workspace` and the
-    events route (2026-07-31 — the standalone measure gap, owner item 1).
-
-    What it adds over the pre-wave hand-rolled `_payload` loop, and why it replaced it:
-
-      * rows go through `aios_grid.rows_from_pool` — the SAME builder the embedded host uses,
-        so `lat`/`lon` (the Map view's data), `_created` and every derived column ride each row
-        by construction instead of by a second loop that drifts. The hand loop was written to
-        mirror the pre-Map contract and silently dropped the coordinates: the shell's Map view
-        had nothing to plot ("the Map no longer works").
-      * `derived` carries the cohort column's cells AND the measure columns' values, resolved
-        through `core.measure_resolve` (EXIT-5's extraction of the `_cl_measure_*` family).
-        Without them every measure column the owner built rendered BLANK in the shell.
-      * `measures` (the offer) and `measure_sets` (condition answers) are computed here so the
-        events route can finally validate measure fields/conditions instead of refusing them
-        (an empty `measure_offer` made `clean_measure_field` reject every create over HTTP).
-
-    Memos live on the TENANT RUNTIME (`rt.measure_memo` / `rt.mset_memo`) — bounded by the
-    module's own clear-past-cap rule, keyed on (stamp, scope, pool identity, question), nothing
-    user-shaped in them.
-    """
-    import aios_grid
-    from core import grid_events, measure_resolve
-
-    import core.perm_scope as perm_scope
-
-    rt = session.runtime
-    team_id, agent = _team_agent(session)
-    rows_src = _pool_for(rt, team_id, agent)
-    # ⛔ THE ROW WALL, APPLIED BEFORE `pids` IS TAKEN. Everything downstream is bounded by that
-    # frozenset — `allowed_pids` for the workspace, cohort membership, measure resolution — so
-    # scoping here means a row this account may not see never enters ANY of them, rather than
-    # being filtered out of one payload and surviving in another.
-    #
-    # Evaluated against the CANONICAL field list, not the per-user assembled one, for two
-    # reasons: the assembled list is not built yet (it needs `pids`), and a permanent filter may
-    # only ever name a canonical field anyway — `routes_admin._clean_perms` validates it against
-    # exactly this schema and 400s otherwise. `permits()` denies on anything it cannot answer.
-    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, aios_grid.FIELDS)
-    pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
-    ws = grid_events.table_workspace(
-        _ctx_for(session, pids), allowed_pids=pids,
-        consume_corrections=consume_corrections)
-    workspace, fields, views, lists = aios_grid.workspace_wire(
-        ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key)
-    # THE FIELD WALL — a TRANSITIVE closure (C-PERM amendment 5), so hiding a field also hides
-    # every formula computed FROM it. Formulas evaluate in the browser from `{ref}`s, so
-    # shipping a dependent formula while withholding its input either leaks the input through
-    # the formula's value or silently computes a wrong one; only removing both is coherent.
-    # Applied AFTER workspace_wire because custom + measure columns are what it must cover.
-    hidden = perm_scope.hidden_keys(session.user, MODULE, fields)
-    if hidden:
-        fields = [f for f in fields if f.get("key") not in hidden]
-        # The field LIST and the ROW payload are two different wires. Narrowing only the first
-        # would leave the value sitting in the second, where anything can read it.
-        rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
-
-    today = time.strftime("%Y-%m-%d")
-    stamp = _pool_stamp(rt, team_id, agent)
-    measures = measure_resolve.offer(team_id, on_error=_measure_err)
-    measure_sets = measure_resolve.condition_sets(
-        [v.get("config") or {} for v in (views or [])], None, team_id, pids, today, stamp,
-        rt.mset_memo, on_error=_measure_err)
-    # The derived channel: cohort membership cells + measure column values, ONE dict — the
-    # same read-only channel the embed host hands to rows_from_pool.
-    derived = aios_grid.cohort_cells(lists)
-    # ⭐ W33-T43 / owner item 12 ("One unique ID per database always"). The customer grid carried
-    # NO Odoo id column at all, while its retiring twin `ut_odoo_customers` carried `partner_id`
-    # as its join key — so the merge would have lost the one value every Odoo document joins on.
-    #
-    # ⛔ IT IS DERIVED, NOT A POOL COLUMN, AND THAT IS THE WHOLE POINT: a customer row's `pid` IS
-    # the `res.partner` id (`modules/customer_data.pool` mints it that way and the identity is
-    # asserted against Odoo in that module). Adding it to the pool would be a SECOND source for
-    # one fact, which is the class of defect item 12 is about. This channel exists for exactly
-    # this — a value the host knows per render and the pool has no business storing.
-    for pid in pids:
-        derived.setdefault(pid, {})["partner_id"] = pid
-    for pid, cells in measure_resolve.column_values(
-            fields, team_id, pids, today, stamp, rt.measure_memo,
-            on_error=_measure_err).items():
-        derived.setdefault(pid, {}).update(cells)
-
-    return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
-            "fields": fields, "views": views, "lists": lists, "derived": derived,
-            "measures": measures, "measure_sets": measure_sets, "today": today,
-            "team_id": team_id}
-
-
-def _payload(session: Session):
-    """`{fields, rows, today, docs, pulled_at}` — X2's shape, which `verify_fields_contract.py`
-    referees. Rows are now built by `aios_grid.rows_from_pool` (embed == standalone by
-    construction); see `grid_assembly` for what that fixed.
-
-    ⭐ `docs` joined the shape in wave 30 (W30-T37 / contract C4). Named here rather than left to
-    the reader because a docstring that still lists the OLD shape is a stale comment on correct
-    code — this repo's D-73 — and it is the first thing anyone greps to learn the payload.
-
-    ⚠ `rows_src` is the SHARED cached list — `rows_from_pool` reads it and builds NEW dicts,
-    never mutating a cached row (the same-scope-second-user leak rule).
-    """
-    import aios_grid
-
-    g = grid_assembly(session)
-    rows = aios_grid.rows_from_pool(
-        g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
-    # ⭐ C4 / D-138 (W30-T37) — THE DOCUMENTS PRODUCER FOR THE CUSTOMER SCOPE. The write door
-    # (`doc_add`/`doc_fetch`/`doc_delete`) never stopped working and every client half is
-    # complete; what vanished with `app.py` at EXIT-6 was the only thing that ever set this key.
-    # All six `onDoc*` handlers in `CustomerGrid.tsx` read `payload?.docs ? … : undefined`, so an
-    # ABSENT key — not a broken one — is what has been switching the whole feature off.
-    #
-    # ⛔ IMPORTED, NEVER RE-SERIALISED. `core.grid_events.docs_for` is the ONE serialiser and
-    # `routes_tables` (the `ut_*` scope) calls the SAME function with the same argument order.
-    # A matching pair here is precisely how the wave-29 close-out reintroduced its own defect in
-    # the opposite direction inside a single commit ([[one-question-two-normalizers]]).
-    # ⚠ `g["pids"]` is the row set this session is ALREADY scoped to — `docs_for` has no
-    # "every document in the tenant" mode to reach for, deliberately.
-    from core import grid_events as _ge
-    return {"fields": g["fields"], "rows": rows,
-            # `today` rides the payload because every relative date condition must resolve against
-            # the TENANT's day, never the browser's — a client that falls back to its own clock
-            # disagrees with the server for everyone west of it.
-            "today": g["today"],
-            "docs": _ge.docs_for(g["pids"], scope_key="customer", uname=session.uname,
-                                 admin=session.admin, st=session.runtime),
-            "pulled_at": time.strftime("%Y-%m-%d %H:%M")}
-
-
-def _ctx_for(session: Session, pids):
-    """An EventCtx for the READ path — no fallback workspace, so a store outage is a 503 rather
-    than a phantom in-memory workspace an API request cannot persist."""
-    from core import grid_events
-    return grid_events.EventCtx(
-        uname=session.uname, allowed_pids=frozenset(pids or ()), fields=[],
-        # C-PERM: the write wall's field half. Computed from the CANONICAL contract because
-        # `fields=[]` here — the closure only needs the schema, not this user's column list.
-        hidden_keys=_hidden_for(session),
-        admin=session.admin, fallback_ws=None, seen_ids={})
-
-
-
-def _hidden_for(session: Session):
-    """The fields this session's permissions hide — the write wall's half of C-PERM.
-
-    Read paths strip these from both wires so they cannot be SEEN; this is what stops them
-    being WRITTEN by a caller who knows the key. Evaluated against the canonical contract, the
-    same schema `routes_admin._clean_perms` validates a hiddenFields entry against.
-    """
-    import aios_grid
-    import core.perm_scope as perm_scope
-
-    return perm_scope.hidden_keys(session.user, MODULE, aios_grid.FIELDS)
-
-def allowed_pids(session: Session):
-    """The pids this session may touch — the POOL's own ids, so the write wall and the read scope
-    can never disagree.
-
-    Reads `_pool_rows` rather than `_payload`: the wall only needs identities, and going through
-    the full payload would pay for a workspace read and a row assembly on every write.
-
-    ⛔ THE PERMANENT FILTER APPLIES HERE TOO, AND FORGETTING IT IS A WRITE-WITHOUT-READ HOLE.
-    `_pool_rows` is built with the DERIVED pushdown, which expresses only what a `(team_id,
-    agent)` pair can express. Any part of the wall the pushdown cannot carry — `revenue > 1000`,
-    a nested group, a condition on any other column — leaves the pool WIDER than the filter. Read
-    paths close that gap with `apply_row_scope`; without the same call here the write wall would
-    be the wider set, and a restricted user could PATCH a row this API will not show them.
-    Same function, same order as `grid_assembly`, so the two walls cannot drift.
-    """
-    import core.perm_scope as perm_scope
-    import aios_grid
-
-    rows = perm_scope.apply_row_scope(_pool_rows(session), session.user, MODULE,
-                                      aios_grid.FIELDS)
-    return frozenset(r["pid"] for r in rows if r.get("pid") is not None)
-
-
-@router.get("/customers")
-def customers(session: Session = Depends(module_gate(MODULE))):
-    return _payload(session)
-
-
-@router.patch("/customers/{pid}")
-def patch_customer(pid: int, body: dict = Body(default=None),
-                   session: Session = Depends(module_gate(MODULE))):
-    """Write the EDITABLE overlay stratum only — Odoo stays read-only, forever.
-
-    Routed through `core.grid_events.handle_one` as an `overlay_patch` event rather than writing
-    the store directly: that handler is where the per-key `permissions.edit` wall, the pid wall
-    and the truncation rules live, and a second implementation of those would be a second set of
-    them to keep in step. The response reports what was ACCEPTED, which is not always what was
-    asked for.
-    """
-    from core import grid_events
-
-    updates = dict(body or {})
-    if not updates:
-        raise err(400, "empty_patch", "no fields to update")
-    pool = allowed_pids(session)
-    if pid not in pool:
-        # 403, not 404: the pid may well exist — it is simply not in this session's book, and
-        # saying "no such customer" would confirm the opposite to anyone who guessed right.
-        raise err(403, "out_of_scope", "that customer is not in your book")
-    payload = _payload(session)
-    ctx = grid_events.EventCtx(
-        uname=session.uname, allowed_pids=pool, fields=payload["fields"],
-        admin=session.admin, fallback_ws=None, seen_ids={},
-        hidden_keys=_hidden_for(session))
-    try:
-        grid_events.handle_one(
-            {"id": f"patch:{pid}:{time.time_ns()}", "type": "overlay_patch",
-             "pid": pid, "updates": updates}, ctx)
-    except grid_events.StoreUnavailable:
-        raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — your change was not saved")
-
-    # What actually landed, read back from the store rather than echoed from the request: a
-    # refused key or a truncated value must not be reported as accepted.
-    stored = (grid_events.table_workspace(_ctx_for(session, pool), allowed_pids=None)
-              .get("overlays") or {}).get(str(pid)) or {}
-    accepted = {k: stored.get(k) for k in updates if k in stored}
-    refused = sorted(k for k in updates if k not in accepted or stored.get(k) != str(updates[k]))
-    # No cache to patch: the overlay stratum is re-read from the store on every `_payload`, so
-    # read-your-writes within this runtime is a property of the design rather than of a
-    # write-through step somebody has to remember. (It was a write-through step while the whole
-    # payload was cached on a scope key — the arrangement that leaked one user's notes to
-    # another. See `_pool_rows`.) Cross-RUNTIME coherence is still not claimed: the module
-    # docstring says why, and Postgres is the fix.
-    out = {"ok": True, "pid": pid, "updates": accepted}
-    if refused:
-        out["refused"] = refused
-    return out
+"""routes_customers.py — X2's read + write of the customer table, BU-SCOPED (EXIT-3b / EXIT-2a).
+
+Two things happen here that did not happen in the pre-wave `main.py`:
+
+  1. **ROWS ARE SCOPED TO THE SESSION.** The old `/api/customers` served `cl.pool()` — the whole
+     book, to anyone holding the shared APP_PASSWORD. Now the pool is built with
+     `(team_id, agent_name)` derived from the USER RECORD, so a Royal-only user never receives a
+     Fisch row and an agent-linked login never receives another rep's book. The scope is applied
+     at the QUERY, not as a post-filter, so there is no moment at which the other BU's rows exist
+     in this response.
+
+  2. **THE OVERLAY FORK IS GONE.** `aios-web/api/data/overlay.json` was a SECOND writable home
+     for the same user-owned fields the Streamlit app keeps in the tenant store — two truths, and
+     whichever process you asked last was right. Reads and writes now both go through
+     `modules.customer_data`'s table-workspace functions: ONE store (C1c, ARCHITECTURE §1a rule 3).
+
+⚠ ONE STORE IS NOT YET ONE CACHE (strangler-period, booked honestly). `core.store.get()` is
+cache-first per PROCESS, so a write from the Streamlit container is invisible to a running API
+container until its cache is refreshed, and vice versa. Deleting the fork removes the second
+SOURCE OF TRUTH; it does not make the two runtimes coherent. The fix is X4/Postgres (task C-4,
+owner-blocked on B-3), and no test here may claim read-your-writes ACROSS runtimes — a TestClient
+proof is single-process and would report green on exactly the thing that is still broken.
+"""
+import time
+
+from fastapi import APIRouter, Body, Depends
+
+import scope_cache
+from deps import Session, err, module_gate, perms
+
+router = APIRouter(prefix="/api/v1")
+
+#: The surface these routes serve. Both legs are gated on it, so a user without the grant gets a
+#: 403 rather than an empty table that looks like "you have no customers".
+MODULE = "customer_data"
+
+_CACHE_TTL = 900       # the pool build is slow (Odoo + reconciliation); 15 min, as before
+
+
+def _pool_rows(session: Session):
+    """The reconciled Odoo pool for this session's SCOPE — the slow part, and the only part that
+    may be shared between users.
+
+    ⛔ WHAT MAY BE CACHED HERE, AND WHY THE LINE IS EXACTLY HERE. The cache key is
+    `(team_id, agent)` and the cached value is the raw pool: Odoo-source columns only. That is
+    genuinely scope-shaped — two users with the same BU and the same book are asking the same
+    question, and `cl.pool()` is expensive (an Odoo pull plus reconciliation).
+
+    The FULL PAYLOAD is NOT cacheable on this key, and caching it here was a real defect I shipped
+    and then removed. `fields` comes from `fields_from_workspace(ws)` — that user's own `custom_`
+    and `measure_` columns — and every overlay cell comes from `ws['overlays']`; the table
+    workspace is read as `data[username]` and written as `patch_table_overlay(uname, …)`, i.e.
+    PER USER. So two Royal-only users with no agent link share `(6, None)` and the second one
+    would have been served the FIRST one's private notes and private columns. The scope key was
+    right for the pool and wrong for everything wrapped around it.
+
+    It survived a green 129-check battery because every fixture user had a DISTINCT
+    `(team_id, agent)` pair, so no two of them ever collided on the key — the test set could not
+    express the bug. `verify_api.py` now carries a same-scope second user for exactly this.
+    """
+    rt = session.runtime
+    team_id, agent = _team_agent(session)
+    return _pool_for(rt, team_id, agent)
+
+
+def _pool_for(rt, team_id, agent):
+    """The cached pool for an explicit scope — session-free so the prewarm thread and the
+    stale-refresh path can call it. STALE-WHILE-REFRESH (scope_cache): once a copy exists no
+    request blocks on the 10–30s Odoo rebuild again; only a scope's FIRST-ever build does.
+
+    DEBT-2 (2026-08-04): while the tenant's RESOLVED Odoo source is PAUSED this path never
+    goes live — it serves the in-process copy at any age, else the persisted pause-time
+    snapshot (restart-safe), else answers 503. Never a WIDER scope's snapshot: handing a
+    scoped user the consolidated rows would widen their book, which is worse than an error."""
+    import modules.customer_data as cl
+    import routes_keychain
+
+    key = ("pool", team_id, agent)
+
+    if routes_keychain.odoo_paused(rt):
+        hit = rt.pool_cache.get(key)
+        if hit:
+            return hit[1]
+        snap = routes_keychain.load_pool_snapshot(rt, team_id, agent)
+        if snap is not None:
+            rt.pool_cache[key] = snap          # seed, so the memo stamps stay coherent
+            return snap[1]
+        raise err(503, "connector_paused",
+                  "this data source is paused and no snapshot exists for your scope — "
+                  "an admin can resume it under Settings → Connectors")
+
+    def _build():
+        # ⚠ THE SCOPE GOES INTO THE BUILDER. `pool(agent_name, team_id)` is the same reconciled
+        # builder the Streamlit page uses — passing the scope here is what makes the isolation a
+        # property of the QUERY instead of a filter someone can forget to apply downstream.
+        return cl.pool(agent, team_id)
+
+    def _evict():
+        # Bounded: a scope cache that only ever grows is a memory leak in a shared process.
+        if len(rt.pool_cache) > 16:
+            for stale in sorted(rt.pool_cache, key=lambda k: rt.pool_cache[k][0])[:8]:
+                rt.pool_cache.pop(stale, None)
+
+    return scope_cache.get(rt.pool_cache, key, _CACHE_TTL, _build, _evict)
+
+
+def warm_default(rt):
+    """Boot prewarm: the consolidated pool `(None, None)` — the scope every admin and every
+    all-BU account lands on. Called from main.py's prewarm thread only."""
+    _pool_for(rt, None, None)
+
+
+def _team_agent(session: Session):
+    """The `(team_id, agent)` this session's POOL is built with — ONE derivation point, used by
+    `_pool_rows` and `grid_assembly` alike, so the cache key and the query can never disagree.
+
+    ⛔ WAVE 15 R1: THIS NOW COMES FROM THE PERMANENT FILTER (C-PERM amendment 3). `team_id` is
+    not a row filter — `customer_data._pool_build` passes it into `cust._cust_rev` three times
+    and into `_cadence_bulk`, so it decides what `rev`/`ly`/`ltm`/`aov`/`status` MEAN. Enforcing
+    a BU purely as a post-filter would keep the row list right and silently consolidate every
+    number. So the pushdown survives as a DERIVATION OF the declared filter rather than a second
+    wall beside it, and `perm_scope.derive_pool_scope` falls back to the legacy `bus`/`agent`
+    derivation for any record the migration has not reached yet.
+    """
+    import core.perm_scope as perm_scope
+    return perm_scope.derive_pool_scope(session.user, MODULE)
+
+
+def _pool_stamp(rt, team_id, agent):
+    """The cached pool's build timestamp — the DATA STAMP in every measure-memo key, so a pool
+    refresh invalidates the memoised answers exactly when the underlying rows changed."""
+    entry = rt.pool_cache.get(("pool", team_id, agent))
+    return entry[0] if isinstance(entry, tuple) and entry else 0
+
+
+def _measure_err(tag, e):
+    try:
+        import harness.telemetry as _tel
+        _tel.error(f"api:{tag}", e)
+    except Exception:
+        pass
+
+
+# ══════════════════════════ THE TENANT-WIDE STRATUM, ON THE CUSTOMER TOPIC (W38-T20 / D-425) ══
+#
+# ⛔⛔ WHY THIS FILE GREW A SHARED STRATUM AT ALL. `core/shared_overlay.py` has been generic since
+# W29-T62, `routes_products.py` has merged it since W30-T36 and `routes_tables.py` since W38-T16 —
+# and the CUSTOMER topic had neither a write door nor a read merge. Every user-created column here
+# lives in `data[username]`, so two accounts looking at "the same" column are looking at two
+# columns. That is fine for a private note and fatal for a ROUTE ORDER: a visit sequence one rep
+# can see and their colleague cannot is not a plan, it is a rumour.
+#
+# ⛔ ONE SPELLING OF THE BUCKET. `modules.customer_data.TABLE_KEY` is the per-user workspace key
+# and `shared_overlay.bucket()` derives `<key>__shared` from it. Resolving it here rather than
+# writing the string means the write door and the read merge cannot disagree about where the
+# values live — which is exactly the failure T16 found on the materialised `ut_*` tables, where
+# `patch_shared_cell` wrote into a bucket no reader ever opened.
+
+
+def _shared_key():
+    """The store key this topic's per-user AND tenant-wide strata are both named from."""
+    import modules.customer_data as cl
+    return cl.TABLE_KEY
+
+
+def shared_fields(st=None):
+    """`{field_key: Field}` — the columns this topic shares tenant-wide.
+
+    Unscoped on purpose, exactly as `shared_overlay.fields` is: a shared column's EXISTENCE is
+    tenant-wide by definition. WHO MAY SEE IT is a separate question, answered one layer up by
+    `perm_scope.hidden_keys` (the per-field grant wall T16 landed), and WHOSE ROWS by `cells`.
+    """
+    from core import shared_overlay
+    try:
+        return shared_overlay.fields(_shared_key(), st=st)
+    except Exception:                                       # noqa: BLE001
+        # Lenient like every other display read: an unreachable store degrades to "nothing is
+        # shared yet", never to a 500 on a grid that would otherwise render. The WALL does not
+        # degrade with it — `field_grant_hidden` hides a marked column it cannot resolve.
+        return {}
+
+
+def shared_cells(pids, st=None):
+    """`{"<pid>": {key: value}}` for the rows named by `pids`, and ONLY those.
+
+    ⛔ `pids` IS THE ROW WALL, PASSED AND NEVER DEFAULTED. `shared_overlay.cells` refuses an
+    "everything" read by signature for this reason; the set handed in is the one `grid_assembly`
+    has already narrowed with `apply_row_scope`, so a cell belonging to the other BU has nothing
+    to attach itself to.
+    """
+    from core import shared_overlay
+    try:
+        return shared_overlay.cells(_shared_key(), list(pids or ()), st=st)
+    except Exception:                                       # noqa: BLE001
+        return {}
+
+
+def _merge_shared_fields(fields, defs):
+    """`fields` PLUS the tenant-wide columns this topic declares — `routes_tables._ut_shared_fields`
+    on the customer topic.
+
+    ⚠ MERGED BEFORE THE WALL, NEVER AFTER. `hidden_keys` is a TRANSITIVE closure, so it must run
+    on the WHOLE contract: a formula over a shared column that reads a hidden one sits outside the
+    closure's reach otherwise and carries the hidden value out wearing a second name. It is also
+    the only order in which `field_grant_hidden` can ever see the `granted` marker at all — merge
+    afterwards and the per-field wall is inert while every test still passes.
+    ⚠ A key the canonical contract already declares WINS. A shared column is an ADDITION to this
+    database's contract, never a redefinition of a column it already has.
+    """
+    if not defs:
+        return fields
+    have = {f.get("key") for f in (fields or ()) if isinstance(f, dict)}
+    return list(fields or ()) + [dict(f, source="overlay")
+                                 for k, f in defs.items() if k not in have]
+
+
+def grid_assembly(session: Session, scope: str = "customer", storage_key: str = "",
+                  consume_corrections: bool = True):
+    """ONE assembly of this session's grid state, shared by `/customers`, `/workspace` and the
+    events route (2026-07-31 — the standalone measure gap, owner item 1).
+
+    What it adds over the pre-wave hand-rolled `_payload` loop, and why it replaced it:
+
+      * rows go through `aios_grid.rows_from_pool` — the SAME builder the embedded host uses,
+        so `lat`/`lon` (the Map view's data), `_created` and every derived column ride each row
+        by construction instead of by a second loop that drifts. The hand loop was written to
+        mirror the pre-Map contract and silently dropped the coordinates: the shell's Map view
+        had nothing to plot ("the Map no longer works").
+      * `derived` carries the cohort column's cells AND the measure columns' values, resolved
+        through `core.measure_resolve` (EXIT-5's extraction of the `_cl_measure_*` family).
+        Without them every measure column the owner built rendered BLANK in the shell.
+      * `measures` (the offer) and `measure_sets` (condition answers) are computed here so the
+        events route can finally validate measure fields/conditions instead of refusing them
+        (an empty `measure_offer` made `clean_measure_field` reject every create over HTTP).
+
+    Memos live on the TENANT RUNTIME (`rt.measure_memo` / `rt.mset_memo`) — bounded by the
+    module's own clear-past-cap rule, keyed on (stamp, scope, pool identity, question), nothing
+    user-shaped in them.
+    """
+    import aios_grid
+    from core import grid_events, measure_resolve
+
+    import core.perm_scope as perm_scope
+
+    rt = session.runtime
+    team_id, agent = _team_agent(session)
+    rows_src = _pool_for(rt, team_id, agent)
+    # ⛔ THE ROW WALL, APPLIED BEFORE `pids` IS TAKEN. Everything downstream is bounded by that
+    # frozenset — `allowed_pids` for the workspace, cohort membership, measure resolution — so
+    # scoping here means a row this account may not see never enters ANY of them, rather than
+    # being filtered out of one payload and surviving in another.
+    #
+    # Evaluated against the CANONICAL field list, not the per-user assembled one, for two
+    # reasons: the assembled list is not built yet (it needs `pids`), and a permanent filter may
+    # only ever name a canonical field anyway — `routes_admin._clean_perms` validates it against
+    # exactly this schema and 400s otherwise. `permits()` denies on anything it cannot answer.
+    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, aios_grid.FIELDS)
+    pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
+    # ⭐ W38-T20 — THE COLUMN DEFINITIONS ARE READ **ONCE** PER ASSEMBLY AND THREADED, because
+    # `core.store.get` deep-copies whatever it hands back on every call. Three consumers want this
+    # dict on one request (the write ctx's wall, the read merge, and the closure), and letting each
+    # take its own copy is the shape D-214 spent a whole ticket removing one document over.
+    _defs = shared_fields(st=rt)
+    ws = grid_events.table_workspace(
+        _ctx_for(session, pids, defs=_defs), allowed_pids=pids,
+        consume_corrections=consume_corrections)
+    # ⭐⭐ W38-T20 / D-425 — THE TENANT-WIDE CELLS, LAYERED OVER THE PER-USER ONES, IN THE
+    # ASSEMBLY SO EVERY CONSUMER SEES ONE TRUTH. `routes_grid`'s /workspace route serves
+    # `workspace["overlays"] = g["ws"].get("overlays")` verbatim and `_payload` hands the same
+    # dict to `rows_from_pool`, so merging HERE reaches both without touching either file.
+    #
+    # ⚠ SAFE TO MUTATE, and checked rather than assumed (the same check `product_assembly`
+    # records): `table_workspace` reads through `store.get`, which deep-copies, so `ws` is a
+    # detached copy and nothing writes it back. A shared value can never leak INTO the per-user
+    # bucket by way of this merge.
+    # ⚠ SHARED WINS PER KEY. The whole point of the stratum is that every reader sees the same
+    # number, so a per-user leftover under the same key is stale by construction. It is also what
+    # makes D-423 recoverable rather than permanent: a pre-fix per-user edit is shadowed, not
+    # promoted.
+    _shared = shared_cells(pids, st=rt)
+    if _shared:
+        _ov = dict(ws.get("overlays") or {})
+        for _pid, _cells in _shared.items():
+            _ov[_pid] = {**(_ov.get(_pid) or {}), **_cells}
+        ws["overlays"] = _ov
+    workspace, fields, views, lists = aios_grid.workspace_wire(
+        ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key)
+    # ⭐⭐ W38-T20 — AND THE COLUMN DEFINITIONS, BEFORE THE WALL. See `_merge_shared_fields`: this
+    # position is load-bearing twice, once for the transitive closure and once because it is the
+    # only order in which the per-field grant marker is ever presented to `hidden_keys`.
+    fields = _merge_shared_fields(fields, _defs)
+    # THE FIELD WALL — a TRANSITIVE closure (C-PERM amendment 5), so hiding a field also hides
+    # every formula computed FROM it. Formulas evaluate in the browser from `{ref}`s, so
+    # shipping a dependent formula while withholding its input either leaks the input through
+    # the formula's value or silently computes a wrong one; only removing both is coherent.
+    # Applied AFTER workspace_wire because custom + measure columns are what it must cover.
+    # ⭐ W38-T20 — `st=rt` IS NOT TIDINESS. `perm_scope.field_grant_hidden` resolves a marked
+    # column against `object_shares`, and without a tenant handle it reads the module-default
+    # bucket: on any tenant but #0 that finds no grant, and no grant on a MARKED column means
+    # HIDDEN. So an unthreaded `st` UNDER-shares (a grantee cannot see their own column) rather
+    # than over-shares — visible and reportable, but still wrong, and `visible_fields`' own note
+    # requires the two calls to agree about it.
+    hidden = perm_scope.hidden_keys(session.user, MODULE, fields, st=rt)
+    if hidden:
+        fields = [f for f in fields if f.get("key") not in hidden]
+        # The field LIST and the ROW payload are two different wires. Narrowing only the first
+        # would leave the value sitting in the second, where anything can read it.
+        rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
+        # ⛔⛔ AND THE OVERLAY DICT IS A THIRD WIRE, WHICH IS NEW THIS TICKET AND WAS A HOLE
+        # BEFORE IT. `rows_from_pool` iterates `fields`, so a narrowed contract already keeps a
+        # hidden key off a ROW — but `/workspace` serves `ws["overlays"]` RAW, and that dict is
+        # where both the per-user cells and (as of the merge above) the tenant-wide ones sit.
+        # One narrowing cannot speak for a wire it never touches; `routes_tables` writes the same
+        # sentence over its own `shared_cells`, and `routes_odoo_tables` over its `overlays`.
+        # ⚠ `ws` AND NOT `workspace`: `routes_grid.workspace` copies the dict ACROSS
+        # (`workspace["overlays"] = g["ws"].get("overlays")`) after this returns, so narrowing the
+        # source is what reaches the wire. Narrowing the copy would be narrowing a key that gets
+        # overwritten a moment later.
+        _ov = ws.get("overlays") or {}
+        if _ov:
+            ws["overlays"] = {pid: {k: v for k, v in (cells or {}).items() if k not in hidden}
+                              for pid, cells in _ov.items()}
+
+    today = time.strftime("%Y-%m-%d")
+    stamp = _pool_stamp(rt, team_id, agent)
+    # ⭐⭐ W38-T19 — THE METRICS CAPABILITY, AND THIS GRAIN NEEDS **THREE** GUARDS WHERE THE
+    # OTHER TWO NEED ONE. `routes_products` and `routes_tables` funnel their cells and their
+    # condition answers through helpers that short-circuit on an empty `offer`, so emptying the
+    # offer there stops the whole feature. `core.measure_resolve` does not take an offer at all:
+    # `condition_sets` and `column_values` both re-derive their work from the caller's OWN saved
+    # views and field list. So gating only the offer here would take the Metric kind off the
+    # picker and refuse new creates while an EXISTING Metric column kept computing and an
+    # EXISTING measure condition kept resolving — a revoked capability still answering, on the
+    # grain with the most of them. Three calls, one predicate.
+    may_metrics = perm_scope.may_metrics(session.user, MODULE)
+    measures = measure_resolve.offer(team_id, on_error=_measure_err) if may_metrics else []
+    measure_sets = measure_resolve.condition_sets(
+        [v.get("config") or {} for v in (views or [])], None, team_id, pids, today, stamp,
+        rt.mset_memo, on_error=_measure_err) if may_metrics else {}
+    # The derived channel: cohort membership cells + measure column values, ONE dict — the
+    # same read-only channel the embed host hands to rows_from_pool.
+    derived = aios_grid.cohort_cells(lists)
+    # ⭐ W33-T43 / owner item 12 ("One unique ID per database always"). The customer grid carried
+    # NO Odoo id column at all, while its retiring twin `ut_odoo_customers` carried `partner_id`
+    # as its join key — so the merge would have lost the one value every Odoo document joins on.
+    #
+    # ⛔ IT IS DERIVED, NOT A POOL COLUMN, AND THAT IS THE WHOLE POINT: a customer row's `pid` IS
+    # the `res.partner` id (`modules/customer_data.pool` mints it that way and the identity is
+    # asserted against Odoo in that module). Adding it to the pool would be a SECOND source for
+    # one fact, which is the class of defect item 12 is about. This channel exists for exactly
+    # this — a value the host knows per render and the pool has no business storing.
+    for pid in pids:
+        derived.setdefault(pid, {})["partner_id"] = pid
+    # ⭐⭐ W38-T19 — SKIPPED ENTIRELY WHEN THE CAPABILITY IS REVOKED, rather than filtered after.
+    # `column_values` selects its own subjects (`isinstance(f.get('measure'), dict)`) off the
+    # field list, so there is no argument that could narrow it; not calling it is the narrowing.
+    # ⚠ THE COLUMN STAYS AND ITS CELLS GO BLANK, which is this channel's OWN documented degrade
+    # ("blank is could not compute, 0 is a real zero") and is what the product and user-table
+    # grains already do under an empty offer. Deleting the column instead would be a second,
+    # louder behaviour for the same fact on one surface out of three, and it would destroy a
+    # definition the admin can restore with one tick.
+    for pid, cells in (measure_resolve.column_values(
+            fields, team_id, pids, today, stamp, rt.measure_memo,
+            on_error=_measure_err) if may_metrics else {}).items():
+        derived.setdefault(pid, {}).update(cells)
+
+    return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
+            "fields": fields, "views": views, "lists": lists, "derived": derived,
+            "measures": measures, "measure_sets": measure_sets, "today": today,
+            "team_id": team_id}
+
+
+def _payload(session: Session):
+    """`{fields, rows, today, docs, pulled_at}` — X2's shape, which `verify_fields_contract.py`
+    referees. Rows are now built by `aios_grid.rows_from_pool` (embed == standalone by
+    construction); see `grid_assembly` for what that fixed.
+
+    ⭐ `docs` joined the shape in wave 30 (W30-T37 / contract C4). Named here rather than left to
+    the reader because a docstring that still lists the OLD shape is a stale comment on correct
+    code — this repo's D-73 — and it is the first thing anyone greps to learn the payload.
+
+    ⚠ `rows_src` is the SHARED cached list — `rows_from_pool` reads it and builds NEW dicts,
+    never mutating a cached row (the same-scope-second-user leak rule).
+    """
+    import aios_grid
+
+    g = grid_assembly(session)
+    rows = aios_grid.rows_from_pool(
+        g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
+    # ⭐ C4 / D-138 (W30-T37) — THE DOCUMENTS PRODUCER FOR THE CUSTOMER SCOPE. The write door
+    # (`doc_add`/`doc_fetch`/`doc_delete`) never stopped working and every client half is
+    # complete; what vanished with `app.py` at EXIT-6 was the only thing that ever set this key.
+    # All six `onDoc*` handlers in `CustomerGrid.tsx` read `payload?.docs ? … : undefined`, so an
+    # ABSENT key — not a broken one — is what has been switching the whole feature off.
+    #
+    # ⛔ IMPORTED, NEVER RE-SERIALISED. `core.grid_events.docs_for` is the ONE serialiser and
+    # `routes_tables` (the `ut_*` scope) calls the SAME function with the same argument order.
+    # A matching pair here is precisely how the wave-29 close-out reintroduced its own defect in
+    # the opposite direction inside a single commit ([[one-question-two-normalizers]]).
+    # ⚠ `g["pids"]` is the row set this session is ALREADY scoped to — `docs_for` has no
+    # "every document in the tenant" mode to reach for, deliberately.
+    from core import grid_events as _ge
+    return {"fields": g["fields"], "rows": rows,
+            # `today` rides the payload because every relative date condition must resolve against
+            # the TENANT's day, never the browser's — a client that falls back to its own clock
+            # disagrees with the server for everyone west of it.
+            "today": g["today"],
+            "docs": _ge.docs_for(g["pids"], scope_key="customer", uname=session.uname,
+                                 admin=session.admin, st=session.runtime),
+            "pulled_at": time.strftime("%Y-%m-%d %H:%M")}
+
+
+def _ctx_for(session: Session, pids, defs=None):
+    """An EventCtx for the READ path — no fallback workspace, so a store outage is a 503 rather
+    than a phantom in-memory workspace an API request cannot persist.
+
+    `defs` (W38-T20) is this topic's tenant-wide column definitions when the caller already holds
+    them; absent, they are read. One read per assembly rather than one per question asked of it.
+    """
+    from core import grid_events
+    return grid_events.EventCtx(
+        uname=session.uname, allowed_pids=frozenset(pids or ()), fields=[],
+        # C-PERM: the write wall's field half. Computed from the CANONICAL contract PLUS the
+        # tenant-wide columns, because `fields=[]` here — the closure only needs the schema, not
+        # this user's column list, and a runtime column is part of that schema now.
+        hidden_keys=_hidden_for(session, defs=defs),
+        admin=session.admin, fallback_ws=None, seen_ids={})
+
+
+
+def _hidden_for(session: Session, defs=None):
+    """The fields this session's permissions hide — the write wall's half of C-PERM.
+
+    Read paths strip these from both wires so they cannot be SEEN; this is what stops them
+    being WRITTEN by a caller who knows the key. Evaluated against the canonical contract, the
+    same schema `routes_admin._clean_perms` validates a hiddenFields entry against.
+
+    ⭐⭐ W38-T20 — AND THE TENANT-WIDE COLUMNS ARE PART OF THAT CONTRACT NOW, WHICH IS A WALL AND
+    NOT A COMPLETENESS TIDY-UP. `patch_customer` builds its ctx with `fields=payload["fields"]`,
+    which carries the merged shared columns, so `grid_events.handle_one` would happily accept an
+    `overlay_patch` naming one. The canonical list cannot mention them (they are created at
+    runtime), so a wall computed from `aios_grid.FIELDS` alone answers "not hidden" for every
+    grant-governed column and the write door is open to a reader who was never granted it.
+    ⚠ Widening the field list can only ever ADD to the hidden set, never remove from it: the
+    closure hides what it is told to hide plus whatever depends on it.
+    """
+    import aios_grid
+    import core.perm_scope as perm_scope
+
+    if defs is None:
+        defs = shared_fields(st=session.runtime)
+    return perm_scope.hidden_keys(
+        session.user, MODULE, _merge_shared_fields(list(aios_grid.FIELDS), defs),
+        st=session.runtime)
+
+def allowed_pids(session: Session):
+    """The pids this session may touch — the POOL's own ids, so the write wall and the read scope
+    can never disagree.
+
+    Reads `_pool_rows` rather than `_payload`: the wall only needs identities, and going through
+    the full payload would pay for a workspace read and a row assembly on every write.
+
+    ⛔ THE PERMANENT FILTER APPLIES HERE TOO, AND FORGETTING IT IS A WRITE-WITHOUT-READ HOLE.
+    `_pool_rows` is built with the DERIVED pushdown, which expresses only what a `(team_id,
+    agent)` pair can express. Any part of the wall the pushdown cannot carry — `revenue > 1000`,
+    a nested group, a condition on any other column — leaves the pool WIDER than the filter. Read
+    paths close that gap with `apply_row_scope`; without the same call here the write wall would
+    be the wider set, and a restricted user could PATCH a row this API will not show them.
+    Same function, same order as `grid_assembly`, so the two walls cannot drift.
+    """
+    import core.perm_scope as perm_scope
+    import aios_grid
+
+    rows = perm_scope.apply_row_scope(_pool_rows(session), session.user, MODULE,
+                                      aios_grid.FIELDS)
+    return frozenset(r["pid"] for r in rows if r.get("pid") is not None)
+
+
+@router.get("/customers")
+def customers(session: Session = Depends(module_gate(MODULE))):
+    return _payload(session)
+
+
+@router.patch("/customers/{pid}")
+def patch_customer(pid: int, body: dict = Body(default=None),
+                   session: Session = Depends(module_gate(MODULE))):
+    """Write the EDITABLE overlay stratum only — Odoo stays read-only, forever.
+
+    Routed through `core.grid_events.handle_one` as an `overlay_patch` event rather than writing
+    the store directly: that handler is where the per-key `permissions.edit` wall, the pid wall
+    and the truncation rules live, and a second implementation of those would be a second set of
+    them to keep in step. The response reports what was ACCEPTED, which is not always what was
+    asked for.
+    """
+    from core import grid_events
+
+    updates = dict(body or {})
+    if not updates:
+        raise err(400, "empty_patch", "no fields to update")
+    pool = allowed_pids(session)
+    if pid not in pool:
+        # 403, not 404: the pid may well exist — it is simply not in this session's book, and
+        # saying "no such customer" would confirm the opposite to anyone who guessed right.
+        raise err(403, "out_of_scope", "that customer is not in your book")
+    payload = _payload(session)
+    ctx = grid_events.EventCtx(
+        uname=session.uname, allowed_pids=pool, fields=payload["fields"],
+        admin=session.admin, fallback_ws=None, seen_ids={},
+        hidden_keys=_hidden_for(session))
+    try:
+        grid_events.handle_one(
+            {"id": f"patch:{pid}:{time.time_ns()}", "type": "overlay_patch",
+             "pid": pid, "updates": updates}, ctx)
+    except grid_events.StoreUnavailable:
+        raise err(503, "store_unavailable",
+                  "the tenant store is unavailable — your change was not saved")
+
+    # What actually landed, read back from the store rather than echoed from the request: a
+    # refused key or a truncated value must not be reported as accepted.
+    stored = (grid_events.table_workspace(_ctx_for(session, pool), allowed_pids=None)
+              .get("overlays") or {}).get(str(pid)) or {}
+    accepted = {k: stored.get(k) for k in updates if k in stored}
+    refused = sorted(k for k in updates if k not in accepted or stored.get(k) != str(updates[k]))
+    # No cache to patch: the overlay stratum is re-read from the store on every `_payload`, so
+    # read-your-writes within this runtime is a property of the design rather than of a
+    # write-through step somebody has to remember. (It was a write-through step while the whole
+    # payload was cached on a scope key — the arrangement that leaked one user's notes to
+    # another. See `_pool_rows`.) Cross-RUNTIME coherence is still not claimed: the module
+    # docstring says why, and Postgres is the fix.
+    out = {"ok": True, "pid": pid, "updates": accepted}
+    if refused:
+        out["refused"] = refused
+    return out
+
+
+# ══════════════════════════════════ THE ROUTE-ORDER COLUMN (W38-T20 / ruling R7 / contract C1) ══
+#
+# ⛔⛔ WHY THIS IS A DOOR HERE AND NOT A KIND IN THE COLUMN MENU. `ColumnMenu.onCreate` is the only
+# persistence the menu has, and it lands a PER-USER `custom_` column through
+# `aios_grid._field_extras`, which is a strict allowlist: a route-order bag created that way is
+# silently stripped and its values are private to their author. That is the wave-19 `image`
+# failure verbatim ("created, named, configured, gone", recorded in `_clean_geocode`'s own
+# docstring) plus a done-when clause that cannot hold, because a colleague reading a per-user
+# stratum gets a clean 200 with nothing in it. The `geocode` pseudo-kind is the precedent for the
+# PICKER; its persistence half does not transfer.
+#
+# ⭐ SO THE COLUMN IS BORN SHARED. `shared_overlay.put_field` stores the definition verbatim (no
+# allowlist), which is what lets the input fingerprint ride the DEFINITION rather than the rows —
+# `shared_overlay._value` RAISES on a dict, so `{order, inputsHash}` could never be one cell, and
+# one solve fingerprints the whole cohort identically anyway, so per-row would be the same string
+# written N times.
+#
+# ⭐ AND THE NUMBER ON THE RECORD IS THE INVERSE OF THE PLANNER'S ANSWER. `mapProjection.planRoute`
+# returns `order`, where `order[i]` is WHICH STOP is visited i-th; the cell holds the RANK. The
+# client inverts it with `routeRanks` (gated in `map.test.ts` at the desktop shape, over a fixture
+# chosen so the two differ); this door then refuses anything that is not a clean 1..N, so a
+# truncated or double-posted body cannot land as a half-route.
+
+#: The key prefix every route-order column wears. `custom_` and `measure_` are the two existing
+#: created-column namespaces and both are PER USER; this one is tenant-wide, so it takes its own
+#: rather than borrowing a prefix whose readers assume a per-user home.
+ROUTE_KEY_PREFIX = "route_"
+
+#: The marker on the stored definition that says WHAT this column is. Read by the GET below and by
+#: the client; never inferred from the key, because a prefix is a naming convention and a
+#: convention is not a declaration.
+ROUTE_KIND = "route_order"
+
+#: ⛔⛔ THE TOPIC A FIELD GRANT IS NAMED UNDER, AND IT IS **NOT** THE STORE BUCKET. Two namespaces
+#: meet on this column and they are spelled differently:
+#:
+#:    the STRATUM lives at `shared_overlay.bucket(customer_data.TABLE_KEY)`
+#:                       = `customer_table_workspace__shared`
+#:    the GRANT is named `shares.field_oid(<what hidden_keys was passed>, key)`
+#:                       = `customer_data:<key>`
+#:
+#: `perm_scope.hidden_keys(user, module, fields)` hands its `module` argument straight through to
+#: `field_grant_hidden`, which builds the oid from it. On a `ut_*` database the module argument IS
+#: the table key, so W38-T16 never had to tell them apart; on a REGISTRY topic they differ, and a
+#: door that claims the grant under the bucket name writes a record the wall will never look for.
+#: MEASURED, not reasoned: the first run of this ticket's gate did exactly that, and user B was
+#: refused a column that had been shared with them through the real share door, with a 200 at
+#: every step ([[one-question-two-normalizers]]).
+SHARE_TOPIC = MODULE
+
+
+def _route_slug(label):
+    """A stable store key from a human label. Lower case, non-alphanumerics collapsed to `_`."""
+    import re as _re
+    slug = _re.sub(r"[^a-z0-9]+", "_", str(label or "").strip().lower()).strip("_")
+    return f"{ROUTE_KEY_PREFIX}{slug[:48]}" if slug else ""
+
+
+def _route_defs(session: Session):
+    """This topic's route-order columns MINUS the ones this session was not granted.
+
+    ⛔ THE WALL IS THE SAME ONE THE GRID USES, NOT A SECOND OPINION. `hidden_keys` is where T16
+    put the per-field grant check, so filtering on it here means the listing, the grid contract
+    and the row payload agree by construction. A column a reader cannot see must not appear here
+    either: the done-when says *does not see the field at all*, and a picker that names a column
+    whose values are withheld has already leaked its existence.
+    """
+    import aios_grid
+    import core.perm_scope as perm_scope
+
+    all_defs = shared_fields(st=session.runtime) or {}
+    defs = {k: v for k, v in all_defs.items()
+            if isinstance(v, dict) and v.get("kind") == ROUTE_KIND}
+    if not defs:
+        return {}
+    hide = perm_scope.hidden_keys(
+        session.user, MODULE, _merge_shared_fields(list(aios_grid.FIELDS), all_defs),
+        st=session.runtime)
+    return {k: v for k, v in defs.items() if k not in hide}
+
+
+@router.get("/customers/route-order")
+def route_order_list(session: Session = Depends(module_gate(MODULE))):
+    """The route-order columns this session may see, with the fingerprint each was solved from.
+
+    ⭐⭐ THE FINGERPRINT IS WHY THIS ROUTE EXISTS RATHER THAN THE CLIENT READING `fields`.
+    Staleness is DERIVED, never stored: what is written down is the INPUT FINGERPRINT the numbers
+    were produced from, so *is this order still current* is a question asked at READ time against
+    what is on screen NOW, and can never itself be out of date. A stored `stale: true` is a fact
+    about a moment that has already passed.
+    """
+    out = []
+    for key, defn in sorted(_route_defs(session).items()):
+        route = defn.get("route") if isinstance(defn.get("route"), dict) else {}
+        out.append({
+            "key": key,
+            "label": defn.get("label") or key,
+            "inputsHash": str(route.get("inputsHash") or ""),
+            "roundTrip": bool(route.get("roundTrip")),
+            "startPid": route.get("startPid"),
+            "stops": route.get("stops"),
+            "solvedAt": route.get("solvedAt") or "",
+            "solvedBy": defn.get("createdBy") or "",
+            # Who may re-solve it. The same creator-or-admin wall the write door enforces, said on
+            # the way out so the client can grey the control instead of discovering a 403.
+            "mine": bool(session.admin
+                         or str(defn.get("createdBy") or "") == session.uname),
+        })
+    return {"fields": out}
+
+
+@router.post("/customers/route-order")
+def route_order_write(body: dict = Body(default=None),
+                      session: Session = Depends(module_gate(MODULE))):
+    """Create (or re-solve) a tenant-wide route-order column and fill it, in ONE call.
+
+    `{label, field?, ranks: {"<pid>": <int>}, inputsHash, roundTrip?, startPid?, stops?}`
+
+    ⛔ THE DEFINITION IS WRITTEN FIRST AND THE GRANT CLAIMED SECOND, which is `patch_shared_cell`'s
+    order and it is deliberate: the window where a column is MARKED and UNCLAIMED fails CLOSED
+    (governed, nobody granted, so only an admin and the creator see it, and an admin can share
+    it). The other order would leave a grant record pointing at nothing.
+
+    ⛔ RE-SOLVING IS CREATOR-OR-ADMIN, WHICH CREATING IS NOT. Writing these numbers changes what
+    every account in the workspace reads, at once, for the whole cohort. That is the wall
+    `routes_tables.delete_shared_field` already applies to the destructive half of this stratum,
+    and a new door does not get to inherit the loose half of an asymmetry somebody has flagged.
+    A permitted teammate READS the numbers; they do not silently re-plan somebody's day.
+    """
+    from core import shared_overlay
+    import core.perm_scope as perm_scope
+    from routes_grid import MAX_BULK_ROWS
+
+    body = body if isinstance(body, dict) else {}
+    label = " ".join(str(body.get("label") or "").split())[:120]
+    key = str(body.get("field") or "").strip() or _route_slug(label)
+    if not key:
+        raise err(400, "bad_request", "a name is required for the route order column")
+    if not key.startswith(ROUTE_KEY_PREFIX):
+        raise err(400, "bad_field_key",
+                  f"a route order column's key starts with '{ROUTE_KEY_PREFIX}', so it cannot "
+                  f"collide with a column this database already owns")
+    import aios_grid
+    if key in {f.get("key") for f in aios_grid.FIELDS}:
+        raise err(400, "field_key_taken",
+                  "this database already has a column with that key")
+
+    defs = shared_fields(st=session.runtime) or {}
+    existing = defs.get(key) if isinstance(defs.get(key), dict) else None
+    if existing is not None:
+        # ⛔⛔ A REFUSAL MUST NOT DESCRIBE A COLUMN THE CALLER CANNOT SEE. The two refusals below
+        # name the column's KIND and its CREATOR, which is exactly the information the field wall
+        # exists to withhold: a stranger who guesses the key would otherwise learn that a route
+        # order exists on this database and who planned it. `routes_shares._can_see_object` makes
+        # the same choice for the same reason (a non-grantee gets the answer a non-existent id
+        # gets). The name is already taken either way, so the honest refusal says only that.
+        if key in perm_scope.hidden_keys(
+                session.user, MODULE,
+                _merge_shared_fields(list(aios_grid.FIELDS), defs), st=session.runtime):
+            raise err(400, "field_key_taken",
+                      "that column name is already in use on this database")
+        if existing.get("kind") != ROUTE_KIND:
+            raise err(400, "not_a_route_column",
+                      "that column is shared but it is not a route order column, so re-solving "
+                      "it would overwrite values this door did not write")
+        owner = str(existing.get("createdBy") or "")
+        if not session.admin and owner != session.uname:
+            raise err(403, "forbidden",
+                      f"a route order can be re-solved by the person who planned it or by an "
+                      f"administrator. This one was planned by {owner or 'somebody else'}, and "
+                      f"re-solving it would change the visit numbers for every account at once")
+
+    raw = body.get("ranks")
+    if not isinstance(raw, dict) or not raw:
+        raise err(400, "bad_ranks", 'expected {ranks: {"<pid>": <visit number>}}')
+    # ⛔ REPORTED, NEVER TRUNCATED (standing rule 1's second sentence, and `MAX_BULK_ROWS`' own
+    # note). The ceiling is `routes_grid`'s so there is ONE of them, not two that drift.
+    if len(raw) > MAX_BULK_ROWS:
+        raise err(400, "too_many_rows",
+                  f"at most {MAX_BULK_ROWS} records per route; this one carried {len(raw)}")
+
+    pool = allowed_pids(session)
+    ranks, not_in_pool, bad_value = {}, [], []
+    for raw_pid, value in raw.items():
+        try:
+            pid = int(raw_pid)
+        except (TypeError, ValueError):
+            not_in_pool.append(str(raw_pid)[:40])
+            continue
+        # ⚠ THE POOL IS THE WALL, and it is the SAME predicate the read path applies
+        # (`apply_row_scope` inside `allowed_pids`), so a caller cannot number a record they
+        # could not be shown, including one in the other business unit.
+        if pid not in pool:
+            not_in_pool.append(str(raw_pid)[:40])
+            continue
+        # ⛔ A BOOL IS AN `int` IN PYTHON and `True` would store as a visit number 1. Excluded by
+        # name rather than by hoping nobody sends one.
+        if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+            bad_value.append(str(raw_pid)[:40])
+            continue
+        ranks[pid] = value
+
+    # ⛔⛔ A PARTLY HONOURED ROUTE IS NOT A ROUTE, AND THIS REFUSES THE WHOLE CALL RATHER THAN
+    # WRITING THE PART IT COULD. Caught by this ticket's own gate: a body carrying one record
+    # outside the caller's book still produced a clean 1..N over what was left, so the door minted
+    # a permanent tenant-wide column and filled it with a SHORTER route than the one that was
+    # solved. Every number in it was plausible and the day was wrong.
+    # ⚠ REPORTED, WITH THE SAMPLE, which is standing rule 1's second sentence: the refusal names
+    # what it could not take, so the caller can fix it rather than guess.
+    if not_in_pool:
+        raise err(400, "rows_not_in_your_book",
+                  f"{len(not_in_pool)} of those records are not in your book, so the route "
+                  f"cannot be written as it was solved. First few: "
+                  f"{', '.join(sorted(not_in_pool)[:5])}")
+    if bad_value:
+        raise err(400, "rows_not_a_visit_number",
+                  f"a visit number is a whole number from 1 upwards; {len(bad_value)} records "
+                  f"carried something else. First few: {', '.join(sorted(bad_value)[:5])}")
+    if not ranks:
+        raise err(400, "no_rows_in_your_book",
+                  "none of those records are in your book, so there is nothing to number")
+    # ⛔ A ROUTE IS A SEQUENCE, SO THE NUMBERS ARE 1..N WITH NO REPEAT AND NO GAP. A body that
+    # arrives truncated, doubled or partly applied would otherwise land as a plausible half
+    # route: every row carrying a number, and the day in the wrong order.
+    seq = sorted(ranks.values())
+    if seq != list(range(1, len(seq) + 1)):
+        raise err(400, "not_a_sequence",
+                  f"a route order is the numbers 1 to {len(seq)}, each used once. This one "
+                  f"carried {len(seq)} records numbered up to {seq[-1]} with "
+                  f"{len(seq) - len(set(seq))} repeated")
+
+    stamp = time.strftime("%Y-%m-%d %H:%M")
+    defn = {
+        "key": key,
+        "label": label or (existing or {}).get("label") or key,
+        # ⛔ `int`, NEVER `text`. A text column sorts 1, 10, 11, 2 — fully populated, entirely
+        # plausible, wrong, and named by no gate. `patch_shared_cell` defaults to text; this door
+        # cannot.
+        "type": "int",
+        "source": "overlay",
+        "shared": True,
+        "kind": ROUTE_KIND,
+        # ⭐⭐ THE PER-FIELD GRANT MARKER (T16). It is an EXPLICIT write-once declaration and it is
+        # what makes the wall fail CLOSED: a grant wall has the opposite absence-polarity to a
+        # deny wall, so keying visibility on "does a grant record exist" would publish this column
+        # to the whole tenant on one unreadable read of `object_shares`. Stamped, never inferred.
+        perm_scope.FIELD_GRANT_MARK: True,
+        "createdBy": (existing or {}).get("createdBy") or session.uname,
+        # ⭐ THE FINGERPRINT RIDES THE DEFINITION, ONCE. One `planRoute` run solves the whole
+        # cohort, so this string is identical for every record in it; per row it would be the same
+        # value written N times, and `shared_overlay._value` raises on a dict anyway.
+        "route": {
+            "inputsHash": str(body.get("inputsHash") or "")[:64],
+            "roundTrip": bool(body.get("roundTrip")),
+            "startPid": int(body["startPid"]) if isinstance(body.get("startPid"), int)
+                        and not isinstance(body.get("startPid"), bool) else None,
+            "stops": len(ranks),
+            "solvedAt": stamp,
+        },
+    }
+    shared_overlay.put_field(_shared_key(), key, defn, st=session.runtime)
+    if existing is None:
+        try:
+            import core.shares as shares
+            # ⚠ 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". Without the owner the column is unmanageable: `may_administer` fails closed
+            # on an ownerless record, so nobody could ever share it.
+            shares.set_grants("field", shares.field_oid(SHARE_TOPIC, key), [],
+                              owner=session.uname, st=session.runtime)
+        except Exception:                                   # noqa: BLE001
+            # The mark is already written, so a failed claim fails CLOSED: governed, nobody
+            # granted, admin-and-creator only. Recoverable. The other order is not.
+            pass
+
+    # ⛔ AND THE RECORDS THAT LOST THEIR NUMBER ARE CLEARED. A re-solve over a SMALLER cohort
+    # would otherwise leave the previous run's ranks sitting on the records that dropped out —
+    # plausible integers, from a route nobody is driving. `""` is the house spelling of an empty
+    # overlay cell (`rows_from_pool` defaults an absent one to exactly that), so this needs no new
+    # vocabulary and no tombstone nobody else reads.
+    stale = {}
+    for raw_pid, cells in (shared_cells(pool, st=session.runtime) or {}).items():
+        if not isinstance(cells, dict) or cells.get(key) in (None, ""):
+            continue
+        try:
+            gone = int(raw_pid)
+        except (TypeError, ValueError):
+            continue
+        if gone not in ranks:
+            stale[gone] = {key: ""}
+    written = shared_overlay.put_rows(
+        _shared_key(), {**{p: {key: v} for p, v in ranks.items()}, **stale},
+        st=session.runtime)
+
+    out = {"ok": True, "field": key, "label": defn["label"], "type": "int",
+           "stops": len(ranks), "cleared": len(stale),
+           "rows_written": len(written), "inputsHash": defn["route"]["inputsHash"],
+           "solvedAt": stamp}
+    return out

api/routes_nav.py

@@ -867,8 +867,22 @@ def save_nav_prefs(body: dict = Body(default=None),
 @router.get("/nav/schema/{key}")
 def nav_schema(key: str, session: Session = Depends(require_session)):
     """The database's schema drawer payload: its field contract + the semantic measures this
-    session may build with. Fail-closed on the SAME predicate as the nav — a key the session
-    may not open answers 403, never a redacted schema."""
+    session may build with.
+
+    TWO WALLS, ANSWERING TWO QUESTIONS, AND THEY FAIL DIFFERENTLY ON PURPOSE. The DATABASE wall
+    is the same predicate the nav uses — a key this session may not open answers 403, never a
+    redacted schema. The FIELD wall runs *after* it, on a database this session may open, and
+    its whole job is to narrow: the drawer serves the columns this reader receives everywhere
+    else, and no more.
+
+    ⭐⭐ W38-T18 — THE FIELD WALL IS NEW HERE AND THIS DOOR IS WHERE IT WAS MISSING. Every grid
+    door has stripped hidden columns from both wires since W36-T21; the schema drawer beside them
+    served the raw contract to anyone `require`/`may_open` admitted. Owner instruction 10 —
+    *"Metrics field lookback and value must abide by the Filter permissioning"* — is satisfied on
+    the picker side already (the condition kit takes `fields` as a PROP off a payload that is
+    walled upstream), so this route is the one place the same reader could still learn the name,
+    the label and the VALUE VOCABULARY of a column their grid refuses them.
+    """
     # Wave 18 C3-UT: a user table's schema is its own definition, walled by ITS predicate
     # (`may_open`) rather than the module grant machinery — `session.require` would 403 every
     # ut key because a user table is deliberately not a module.
@@ -878,6 +892,25 @@ def nav_schema(key: str, session: Session = Depends(require_session)):
         if not defn or not user_tables.may_open(key, session.uname, session.admin,
                                                 st=session.runtime):
             raise err(403, "forbidden", "that database belongs to another user")
+        # ⭐⭐ W38-T18 — THE FIELD WALL ON A `ut_*` DATABASE, WHICH THIS DOOR HAS NEVER RUN.
+        # `may_open` answers *IF* you reach the database and says nothing about WHICH COLUMNS, so
+        # this drawer handed `defn["fields"]` whole to every account it admitted. The bypass is
+        # older than this ticket (it dates to the wall itself); what changed is the CATEGORY it
+        # leaks — since W38-T16 a hidden `ut_*` column means an administrator's `hiddenFields`
+        # *or* a column granted away, and a share door whose schema drawer still names the column
+        # tells the ungranted reader exactly what they were refused.
+        # ⚠ MERGED BEFORE THE WALL, NEVER AFTER — the same order `routes_tables.ut_assembly`
+        # runs, and for the reason `_ut_shared_fields` gives one door over: the closure must see
+        # the WHOLE contract, or a definition field whose formula reads a hidden tenant-wide
+        # column sits outside its reach and carries that value out wearing a second name.
+        # ⛔ ONLY THE DEFINITION'S OWN FIELDS ARE RETURNED. This drawer has never published the
+        # shared stratum and this ticket is not where it starts; widening the list handed to the
+        # closure can only ever ADD to the hidden set, never remove from it.
+        import routes_tables as _rt
+        base = list(defn.get("fields") or [])
+        hidden = _rt._ut_hidden(session, key,
+                                _rt._ut_shared_fields(session, key, base),
+                                st=session.runtime)
         # WAVE 19 (R8) — the drawer wears the RENAMED name. A rail that says one thing and a
         # schema panel opened from it that says another is the drift a rename is supposed to
         # remove, not create.
@@ -888,7 +921,7 @@ def nav_schema(key: str, session: Session = Depends(require_session)):
                 "fields": [{"key": f["key"], "label": f["label"], "type": f["type"],
                             "source": f.get("source") or "overlay",
                             "description": str(f.get("description") or "")}
-                           for f in (defn.get("fields") or [])],
+                           for f in base if f.get("key") not in hidden],
                 "measures": []}
     session.require(key)
     pages = perms.nav_pages(session.user) or []
@@ -899,7 +932,26 @@ def nav_schema(key: str, session: Session = Depends(require_session)):
     if key in ("customer_data", "cohort", "customers"):
         try:
             import aios_grid
+            import routes_customers as _rc
+            # ⭐⭐ W38-T18 — THE FIELD WALL ON THE CUSTOMER CONTRACT, AND THE `options` LINE FOUR
+            # ROWS DOWN IS WHY IT IS A LEAK RATHER THAN AN UNTIDINESS. A schema drawer that names
+            # a hidden column has told the reader it exists; one that ships `options` has handed
+            # them the VALUE VOCABULARY of every choice and status column their grid refuses —
+            # the set of statuses the business uses, read straight off a door with no wall.
+            # ⛔ `_hidden_for` IS REUSED, NOT RE-DERIVED, and the difference is not cosmetic.
+            # `hidden_keys(user, MODULE, aios_grid.FIELDS)` is the obvious spelling and it is
+            # INCOMPLETE: that function's own docstring records that a wall computed from the
+            # canonical list alone answers "not hidden" for every runtime column, so the
+            # tenant-wide stratum never reaches the closure and a formula over a hidden column
+            # comes back. One evaluator, one caller, no second idea of what this session hides.
+            # ⚠ INSIDE THE `try`, DELIBERATELY. If the wall cannot be computed the route already
+            # answers with an empty contract rather than a full one — fail-closed is the only
+            # direction a schema door may fail, and the gate's ADMIN control is what stops that
+            # silent empty being mistaken for a wall that worked.
+            hidden = _rc._hidden_for(session)
             for f in aios_grid.FIELDS:
+                if f["key"] in hidden:
+                    continue
                 entry = {"key": f["key"], "label": f["label"], "type": f["type"],
                          "source": f["source"],
                          "description": str(f.get("description") or "")}
@@ -911,8 +963,19 @@ def nav_schema(key: str, session: Session = Depends(require_session)):
     measures = []
     try:
         from core import measure_resolve
+        import core.perm_scope as _perm_scope
         team_id = perms.scope_team_id(session.user)
-        for m in measure_resolve.offer(team_id) or []:
+        # ⭐⭐ W38-T19 — THE METRICS CAPABILITY REACHES THIS DRAWER TOO, AND IT IS THE ONE DOOR
+        # THE THREE GRID ASSEMBLIES DO NOT SPEAK FOR. This route calls `measure_resolve.offer`
+        # ITSELF rather than reading a `measures` key off an assembly, so a wall applied in
+        # `routes_customers` / `routes_products` / `routes_tables` narrows every grid and leaves
+        # the panel beside them naming the full lookback catalogue — the same one-door-short
+        # shape W38-T18 fixed for FIELDS in this very function, one key over.
+        # ⚠ THE UT_ BRANCH ABOVE RETURNS BEFORE THIS AND ALREADY SERVES `[]`, so there is
+        # nothing to narrow there; if it ever starts publishing an offer, it needs this line.
+        _offer = ((measure_resolve.offer(team_id) or [])
+                  if _perm_scope.may_metrics(session.user, key) else [])
+        for m in _offer:
             measures.append({"key": str(m.get("key") or ""),
                              "label": str(m.get("label") or m.get("key") or ""),
                              "type": str(m.get("type") or "")})

api/routes_products.py

@@ -137,8 +137,22 @@ def _measure_stamp(rt, team_id):
     return entry[0] if isinstance(entry, tuple) and entry else 0
 
 
-def product_measures():
-    """The measure OFFER for this database, or `[]` when the semantic layer cannot answer.
+def product_measures(session):
+    """The measure OFFER for this SESSION on this database, or `[]`.
+
+    ⭐⭐ W38-T19 — `session` IS REQUIRED, NOT DEFAULTED, AND THAT IS THE POINT OF THE EDIT. This
+    function was PRINCIPAL-BLIND: it answered the same catalogue to every caller, so there was
+    nothing for a per-user capability to be consulted by. A `session=None` default would have
+    left the old call shape working and silently ungated — the fail-open spelling of the same
+    bug, and the one `_module_fields` in `routes_admin` was rewritten to refuse. A caller with
+    no principal cannot ask this question and must not get an answer.
+
+    ⛔ EMPTYING THE OFFER IS THE WHOLE WALL ON THIS GRAIN, and it is three refusals rather than
+    one: `_measure_cells` and `_measure_condition_sets` both return `{}` for a falsy `offer`, and
+    `routes_grid` passes this list into `clean_measure_field` as the ADMISSION set, which
+    fail-closes `measure_not_offered` on a create. The client's `offerMeasure={measures.length >
+    0}` then takes the Metric kind off the picker for the same reason it hides it on a database
+    with no binding.
 
     ⭐⭐ W37-T10 / owner item 4 (R1) — this is what turns `measures: []` into a real catalogue.
     Owner: *"Odoo products should have a lookbsck metrics like sales etc."* The list is DERIVED
@@ -150,6 +164,9 @@ def product_measures():
     client's own rule (`offerMeasure={measures.length > 0}`) then hides the Metric kind rather
     than offering a column that could only render blank.
     """
+    import core.perm_scope as perm_scope
+    if not perm_scope.may_metrics(session.user, MODULE):
+        return []
     try:
         from harness import semantic as sem
         return sem.entity_measures(SEM_TOPIC)
@@ -349,7 +366,7 @@ def product_assembly(session: Session, scope: str = "product", storage_key: str
 
     today = time.strftime("%Y-%m-%d")
     stamp = _measure_stamp(session.runtime, team_id)
-    measures = product_measures()
+    measures = product_measures(session)
 
     # R9: the Cohorts column's cells, built from THIS topic's lists. ⭐ W37-T10 — the measure
     # half of this same read-only channel is no longer empty; the customer assembly merges its

api/routes_shares.py

@@ -4,9 +4,19 @@
     PUT  /api/v1/share/{kind}/{oid}      <- {entries:[{user,role}]}   (REPLACES the set)
     GET  /api/v1/share/mine              -> {view:[id], folder:[id], database:[id]}
 
-`kind` ∈ view | folder | database. Roles are `view` | `edit` — the same two words the view rail
-already speaks, now extended to folders and databases so there is ONE vocabulary in the UI
-(R10: "the same picker views use").
+`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
@@ -102,6 +112,24 @@ def _owns_object(session, kind, oid):
     """
     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
+        try:
+            import core.shared_overlay as shared_overlay
+            defn = (shared_overlay.fields(table_key, st=session.runtime) or {}).get(field_key)
+        except Exception:                                   # noqa: BLE001
+            return False
+        return bool(defn) and str(defn.get("createdBy") or "") == str(session.uname)
     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"
@@ -157,6 +185,10 @@ def _can_see_object(session, kind, oid):
     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
@@ -195,7 +227,7 @@ def _entries_or_400(session, entries):
         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.")
+                  + ". Nothing was shared. Pick people from the list rather than typing a name.")
 
 
 @router.get("/share/mine")
@@ -286,7 +318,7 @@ def put_share(kind: str, oid: str, body: dict = Body(default=None),
     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 "
+                  "entries must be a list of {user, role}. Send [] to un-share, which is how "
                   "revoking is expressed")
     _entries_or_400(session, entries)
     out = shares.set_grants(kind, oid, entries, owner=rec["owner"] or session.uname,
@@ -367,6 +399,32 @@ def _object_ref(session, kind, oid):
     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:
+                return ("A column", None, "")
+            try:
+                import core.shared_overlay as shared_overlay
+                defn = (shared_overlay.fields(table_key, st=session.runtime) or {}).get(field_key)
+            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.
+            _WS = "_table_workspace"
+            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 {}
@@ -390,4 +448,5 @@ def _object_ref(session, kind, oid):
                     route, str(oid) if kind == "view" else "")
     except Exception:                                       # noqa: BLE001
         pass
-    return ({"view": "A view", "folder": "A folder"}.get(kind, "An item"), None, "")
+    return ({"view": "A view", "folder": "A folder",
+             "field": "A column"}.get(kind, "An item"), None, "")

api/routes_tables.py

@@ -429,11 +429,36 @@ def patch_shared_cell(table_key: str, pid: int, body: dict = Body(default=None),
         raise err(400, "bad_request", "a field key is required")
     _defn_or_refuse(session, table_key)
     from core import shared_overlay
+    import core.perm_scope as perm_scope
     if not shared_overlay.is_shared(table_key, key, st=session.runtime):
+        # ⭐⭐ W38-T16 / R7 — A COLUMN IS BORN OWNED AND PRIVATE, AND THIS IS THE PRODUCT CHANGE.
+        # Until now this door minted a column every account in the tenant could read, with no way
+        # to say who. `granted` marks it as governed by `core.shares` (see
+        # `perm_scope.FIELD_GRANT_MARK` for why an explicit marker and not the absence of a grant
+        # record), and the grant record below claims it for the creator.
+        #
+        # ⚠ THE EMPTY ENTRY LIST IS THE POINT, NOT A PLACEHOLDER. `set_grants` keeps a record that
+        # has an owner and no entries, so "shared with nobody" is STORED and is a different fact
+        # from "never shared" — the same explicit-resolution shape `perms_v` uses. Without the
+        # owner the column would be unmanageable: `may_administer` fails closed on an ownerless
+        # record, so nobody could ever share or re-share it.
+        # ⚠ COLUMNS THAT PREDATE THIS CARRY NO MARK and stay tenant-wide, unchanged. Reading
+        # their absence as "granted to nobody" would blank every existing shared column at once.
         shared_overlay.put_field(table_key, key, {
             "key": key, "label": str(body.get("label") or key), "source": "overlay",
             "type": str(body.get("type") or "text"), "shared": True,
+            perm_scope.FIELD_GRANT_MARK: True,
             "createdBy": session.uname}, st=session.runtime)
+        try:
+            import core.shares as shares
+            shares.set_grants("field", shares.field_oid(table_key, key), [],
+                              owner=session.uname, st=session.runtime)
+        except Exception:                                   # noqa: BLE001
+            # ⛔ THE MARK IS ALREADY WRITTEN, SO A FAILED CLAIM FAILS **CLOSED**: the column is
+            # governed and nobody holds a grant, i.e. only an admin sees it. That is recoverable
+            # (an admin can share it) and the other order is not — a marked column with a claim
+            # that landed first and a definition that did not would be a grant on nothing.
+            pass
     try:
         # ⚠ `put_cell`, not `put_cells` — this door writes exactly ONE cell, and the singular is
         # the API that says so. It delegates to the plural, so both stay reachable through the one
@@ -477,6 +502,18 @@ def delete_shared_field(table_key: str, field_key: str,
                   f"was added by {owner or 'somebody else'}, and dropping it would delete the "
                   f"value for every account")
     dropped = shared_overlay.drop_field(table_key, str(field_key), st=session.runtime)
+    # ⭐⭐ W38-T16 — THE GRANTS DIE WITH THE COLUMN, which is `shares.drop_objects`' whole reason
+    # for existing (wave 21, C3): a deleted object's grants would otherwise serve a ghost id into
+    # every receiver's "Shared with me" forever, and the ghost 404s on open. It matters twice as
+    # much for a field, because `drop_field` scrubs the CELLS so the key can be re-used — and a
+    # surviving grant record would silently re-arm on the next column that took the name.
+    # ⚠ R8 / D-172 IS UNCHANGED ABOVE: delete is creator-or-admin. This ticket did not widen it.
+    try:
+        import core.shares as shares
+        shares.drop_objects([("field", shares.field_oid(table_key, str(field_key)))],
+                            st=session.runtime)
+    except Exception:                                       # noqa: BLE001
+        pass
     return {"ok": True, "dropped": bool(dropped),
             "fields": list(shared_overlay.fields(table_key, st=session.runtime))}
 
@@ -617,7 +654,7 @@ def ut_write_ctx(session: Session, table_key: str):
     # `:2021`); this ctx passed `frozenset()`, so a hidden column was hidden on the READ and fully
     # writable on the EVENTS transport — a wall on one wire and not the other is the shape
     # `strip_row`'s own note warns about, with the sign flipped.
-    hidden = _ut_hidden(session, table_key, fields_base)
+    hidden = _ut_hidden(session, table_key, fields_base, st=lent)
     ctx = grid_events.EventCtx(
         uname=session.uname, allowed_pids=pids, fields=[], hidden_keys=hidden,
         admin=session.admin, fallback_ws=None, seen_ids={}, st=session.runtime,
@@ -626,7 +663,13 @@ def ut_write_ctx(session: Session, table_key: str):
     workspace, fields, views, lists = aios_grid.workspace_wire(
         ws, session.uname, set(pids), defs={}, scope_key=table_key, storage_key="",
         fields_base=fields_base)
-    fields, _rows, hidden = _ut_field_wall(session, table_key, fields, [])
+    # ⭐⭐ W38-T16 — THE SHARED COLUMNS JOIN THE **WRITE** CTX'S CONTRACT TOO, and for the reason
+    # W36-T21 gave one wall over: `grid_events` refuses a key by asking `ctx.hidden_keys`, so a
+    # column missing from this list is a column the events transport does not know it must
+    # refuse. The read door narrowing a name the write door has never heard of is the same
+    # one-wire wall with the sign flipped.
+    fields = _ut_shared_fields(session, table_key, fields)
+    fields, _rows, hidden = _ut_field_wall(session, table_key, fields, [], st=lent)
     return {"rows_src": [], "pids": pids, "ws": ws, "workspace": workspace,
             "fields": fields, "views": views, "lists": lists, "hidden": hidden,
             "derived": aios_grid.cohort_cells(lists),
@@ -645,25 +688,74 @@ def ut_write_ctx(session: Session, table_key: str):
             # `resolved_ids` (from `measure_sets`) only makes `view_upsert` answer "rerender",
             # so the next `/workspace` — which DOES compute the sets, in `ut_assembly` — resolves
             # it. Conservative in the right direction: one extra repaint, never a dropped filter.
-            "measures": ut_measures(table_key),
+            # ⭐⭐ W38-T19 — THE CAPABILITY IS APPLIED HERE TOO, and this is the site that makes
+            # the refusal REAL rather than cosmetic: `routes_grid` reads this list as
+            # `measure_offer`, and `clean_measure_field` fail-closes `measure_not_offered` over
+            # an empty one. A picker hidden on the read door with this list still full would be
+            # a control that only stops the honest.
+            "measures": ut_measures(table_key, session),
             "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
             # ⭐ W31-T20 — the write door reads this to refuse a PID-BEARING event loudly rather
             # than letting `allowed_pids` swallow it as a no-op. See `routes_grid`'s ut_ branch.
             "limits": limits, "defn": defn}
 
 
-def _ut_hidden(session, table_key, fields):
+def _ut_hidden(session, table_key, fields, st=None):
     """The hidden-field closure for THIS session on THIS database — C1's field half, once.
 
     ⚠ Named rather than inlined at its four call sites for the reason `may_open`'s own note gives:
     four spellings of one wall is how two of them come apart. `perm_scope.hidden_keys` is the ONE
     evaluator; this is just the `ut_*` caller's shorthand for it.
+
+    ⭐ W38-T16 — `st` IS THE LEND THE CALLER ALREADY HOLDS, and passing it is free rather than
+    merely tidy: the closure's field-grant leg resolves against `object_shares`, which is exactly
+    the bucket `ut_assembly`'s own lend note says the pass is already serving.
     """
     import core.perm_scope as perm_scope
-    return perm_scope.hidden_keys(session.user, table_key, fields)
+    return perm_scope.hidden_keys(session.user, table_key, fields, st=st)
+
+
+def _ut_shared_fields(session, table_key, fields):
+    """`fields` PLUS this database's TENANT-WIDE columns — the read-side merge, W38-T16.
+
+    ⛔⛔ WHY THIS DID NOT EXIST AND WHY THAT WAS A HOLE. `patch_shared_cell` has written into
+    `<key>__shared` for any `ut_*` database since W30-T28, and only the READ-THROUGH door
+    (`routes_odoo_tables`) ever merged that stratum back. So a shared column written on a
+    MATERIALISED user table went into the store and was readable by nobody, through any door —
+    complete, correct, and invisible ([[reachable-is-not-the-same-as-built]]). This is the other
+    half of that door.
+
+    ⚠ MERGED BEFORE THE WALL, NEVER AFTER, and `routes_odoo_tables` learned this the same way:
+    the hidden closure must run on the WHOLE contract, or a formula in a shared column that reads
+    a hidden one sits outside its reach and carries the hidden value out wearing a second name.
+    ⚠ A key the definition already declares WINS. A shared column is an addition to a database's
+    contract, never a redefinition of a column that database already has.
+    """
+    from core import shared_overlay
+    defs = shared_overlay.fields(table_key, st=session.runtime) or {}
+    if not defs:
+        return fields
+    have = {f.get("key") for f in (fields or ()) if isinstance(f, dict)}
+    return list(fields or ()) + [dict(f, source="overlay")
+                                 for k, f in defs.items() if k not in have]
+
 
+def _ut_shared_cells(session, table_key, pids):
+    """`{"<pid>": {key: value}}` for the TENANT-WIDE stratum, over THIS session's row set.
 
-def _ut_field_wall(session, table_key, fields, rows_src):
+    ⛔ `pids` IS THE ROW WALL AND IT IS PASSED, NOT DEFAULTED — `shared_overlay.cells` refuses an
+    "everything" read by signature for exactly this reason, and the set handed in is the one
+    `scoped_pool`/`scoped_pids` already narrowed. A cell for a row this session may not see
+    therefore has nothing to attach to.
+    """
+    from core import shared_overlay
+    try:
+        return shared_overlay.cells(table_key, list(pids or ()), st=session.runtime)
+    except Exception:                                       # noqa: BLE001
+        return {}
+
+
+def _ut_field_wall(session, table_key, fields, rows_src, st=None):
     """`(fields, rows_src, hidden)` with the hidden closure removed from BOTH wires.
 
     ⭐⭐ W36-T21 — the same three lines `routes_customers.grid_assembly` runs for `customer_data`,
@@ -682,7 +774,7 @@ def _ut_field_wall(session, table_key, fields, rows_src):
     path with nothing to say ([[one-question-two-normalizers]]).
     """
     import core.perm_scope as perm_scope
-    hide = perm_scope.hidden_keys(session.user, table_key, fields)
+    hide = perm_scope.hidden_keys(session.user, table_key, fields, st=st)
     if not hide:
         return fields, rows_src, frozenset()
     fields = [f for f in fields if f.get("key") not in hide]
@@ -740,7 +832,7 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
     ops = _ops(session, table_key, st=st)
     # ⭐⭐ W36-T21 — the WRITE half of the field wall. `frozenset()` here meant a column an
     # administrator had hidden was still writable through the events transport.
-    hidden = _ut_hidden(session, table_key, fields_base)
+    hidden = _ut_hidden(session, table_key, fields_base, st=st)
     ctx = grid_events.EventCtx(
         uname=session.uname, allowed_pids=pids, fields=[], hidden_keys=hidden,
         admin=session.admin, fallback_ws=None, seen_ids={},
@@ -753,16 +845,31 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
     workspace, fields, views, lists = aios_grid.workspace_wire(
         ws, session.uname, set(pids), defs={}, scope_key=table_key,
         storage_key=storage_key, fields_base=fields_base)
+    # ⭐⭐ W38-T16 — THE TENANT-WIDE STRATUM, ON A MATERIALISED GRID. Merged HERE, between
+    # `workspace_wire` and the wall, which is `routes_odoo_tables`' own position for the same two
+    # lines and for the same reason: the closure must be recomputed on the MERGED contract or a
+    # formula in a shared column reaches past it.
+    fields = _ut_shared_fields(session, table_key, fields)
+    # ⚠ THE CELLS COST A READ, SO THE ENVELOPE ARM DOES NOT PAY IT. `with_rows=False` renders no
+    # row at all (D-174), and `cells()` over the whole pid set would be a scoped read whose
+    # result nothing consumes. The COLUMNS still merge above: `/workspace` needs the contract.
+    shared_cells = _ut_shared_cells(session, table_key, pids) if with_rows else {}
     # ⭐⭐ W36-T21 / R6 — the READ half, in `grid_assembly`'s own position: after `workspace_wire`,
     # so the closure covers this user's `custom_` and `measure_` columns too.
-    fields, rows_src, hidden = _ut_field_wall(session, table_key, fields, rows_src)
+    fields, rows_src, hidden = _ut_field_wall(session, table_key, fields, rows_src, st=st)
+    if hidden and shared_cells:
+        # ⛔ BOTH WIRES, AND THE SHARED STRATUM IS A THIRD ONE. `strip_row` above cleaned the
+        # DEFINITION rows; these cells arrived by a different door and one narrowing cannot speak
+        # for both — the same sentence `routes_odoo_tables` writes over its own `overlays` dict.
+        shared_cells = {pid: {k: v for k, v in cells.items() if k not in hidden}
+                        for pid, cells in shared_cells.items()}
 
     # ⭐⭐ W37-T12 / owner item 4 (R1) — `measures` IS NO LONGER UNCONDITIONALLY EMPTY. A database
     # whose entity topic declares a `measures:` binding (today `ut_odoo_agents`) serves a real
     # lookback catalogue AND the cells to go with it; every other user table still serves `[]`,
     # which is the honest answer for a hand-typed one rather than a descope.
     today = time.strftime("%Y-%m-%d")
-    measures = ut_measures(table_key)
+    measures = ut_measures(table_key, session)
     derived = aios_grid.cohort_cells(lists)          # R9: this table's own lists
     for _pid, _cells in _ut_measure_cells(table_key, fields, pids, today, measures,
                                           session.runtime.measure_memo).items():
@@ -771,6 +878,10 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
     return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
             "fields": fields, "views": views, "lists": lists, "hidden": hidden,
             "derived": derived,
+            # ⭐ W38-T16 — ALWAYS PRESENT, `{}` when this database shares nothing. A key a
+            # consumer has to test for is a key a consumer forgets to test for, and the consumer
+            # here (`table_rows`) is layering strata in a fixed order.
+            "shared_cells": shared_cells,
             "measures": measures,
             "measure_sets": _ut_measure_sets(table_key, views, measures, pids, today),
             "today": today,
@@ -787,8 +898,18 @@ def _ut_measure_err(tag, e):
         pass
 
 
-def ut_measures(table_key):
-    """The lookback-measure OFFER for a user database, or `[]` — W37-T12 / owner item 4 (R1).
+def ut_measures(table_key, session):
+    """The lookback-measure OFFER for a user database FOR THIS SESSION, or `[]` — W37-T12 /
+    owner item 4 (R1), narrowed by the metrics capability in W38-T19.
+
+    ⭐⭐ W38-T19 — `session` IS REQUIRED, NOT DEFAULTED. The function was PRINCIPAL-BLIND, so a
+    per-user capability had nothing to be consulted by. Defaulting it would leave both existing
+    call sites compiling and silently ungated, which is the fail-open spelling of the bug rather
+    than a fix for it — the argument `_module_fields` in `routes_admin` records for its own
+    `session`. ⛔ AND BOTH CALL SITES MATTER, WHICH IS EASY TO GET HALF RIGHT: `ut_assembly` is
+    the READ and `ut_write_ctx` is the door `routes_grid` turns into `clean_measure_field`'s
+    admission set. Gating only the read would take the kind off the picker and leave the CREATE
+    working for anyone who posts the event.
 
     ⭐ THE SAME ENGINE THE PRODUCT GRID USES (`semantic.entity_measures`), reached through the
     topic that DESCRIBES this database. A table with no entity topic, or a topic with no
@@ -800,6 +921,9 @@ def ut_measures(table_key):
     so a list here would be a second definition of one fact — the argument `_rollup_source_offer`
     makes about itself one screen down.
     """
+    import core.perm_scope as perm_scope
+    if not perm_scope.may_metrics(session.user, table_key):
+        return []
     try:
         from harness import semantic as sem
         topic = sem.topic_for_grid(table_key)
@@ -1346,6 +1470,16 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
         if isinstance(_ov, dict):
             _cells.update(_ov)
         merged[_pid] = _cells
+    # ⭐⭐ W38-T16 — THE TENANT-WIDE STRATUM GOES ON TOP, and the order is the contract rather
+    # than a preference. A shared column is one the whole permitted audience must read the SAME
+    # value in — that is the entire reason `shared_overlay` exists — so a stale per-user value
+    # left under the same key must not win. `routes_odoo_tables` layers the two in this exact
+    # order (`overlays.setdefault(pid, {}).update(cells)`) and the two doors must agree.
+    # ⛔ NEVER `setdefault` ON `merged`: these cells are already narrowed to this session's pids,
+    # but inventing a row id here would put a row in the payload that `rows_src` never admitted.
+    for _pid, _cells in (g.get("shared_cells") or {}).items():
+        if str(_pid) in merged and isinstance(_cells, dict):
+            merged[str(_pid)].update(_cells)
     # ⭐⭐ 2026-08-10 (owner: *"wth is going on, why does it take forever to load now?"*) — THE
     # JSON DOCUMENTS DO NOT RIDE THE LIST.
     #

platform/core/shares.py

@@ -41,7 +41,14 @@ 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".
-KINDS = ('view', 'folder', 'database')
+#:
+#: ⭐⭐ 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
@@ -81,6 +88,41 @@ 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
@@ -89,8 +131,8 @@ def _st(st):
 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'refusing to invent a namespace from a typo.')
+        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
 
 

platform/core/store_pg.py

@@ -40,6 +40,8 @@ import json
 import os
 import threading
 
+import core.data_binding as data_binding
+
 _URL_ENV = 'DATABASE_URL'
 _LOCK = threading.RLock()
 _POOL = {'pool': None, 'url': None, 'schema': None}
@@ -49,6 +51,19 @@ def _url():
     return os.environ.get(_URL_ENV) or None
 
 
+def _effective_slug(tenant_slug=None):
+    """The tenant this call ACTUALLY addresses, after every default has been applied.
+
+    ⛔⛔ IT IS A SEPARATE FUNCTION BECAUSE THE DEFAULT IS THE HAZARD, AND THE GUARD HAS TO SEE THE
+    SAME ONE THE SQL DOES. `_schema_for` used to inline this chain, so the fallback to tenant #0
+    happened *inside* the address builder where nothing else could observe it: a process that was
+    handed no slug at all silently addressed `t_royal_imports` — Royal Imports' real business
+    data — and the only code that knew had already turned it into an identifier. Resolving once,
+    here, is what lets `write_refusal` below refuse the DEFAULT rather than only an explicit slug.
+    """
+    return (tenant_slug or os.environ.get('AIOS_TENANT') or 'royal-imports').strip().lower()
+
+
 def _schema_for(tenant_slug=None):
     """`t_<slug>` with `-` normalised to `_` (a hyphen is not legal in an unquoted identifier).
 
@@ -57,8 +72,133 @@ def _schema_for(tenant_slug=None):
     to tenant #0 so the default behaviour is unchanged, the same rule `harness.datastore.path_for`
     follows for the DuckDB filename.
     """
-    slug = (tenant_slug or os.environ.get('AIOS_TENANT') or 'royal-imports').strip().lower()
-    return 't_' + slug.replace('-', '_')
+    return 't_' + _effective_slug(tenant_slug).replace('-', '_')
+
+
+# =============================================================================================
+# ⛔⛔ THE WRITE GUARD — D-353. WHY IT KEYS ON A TENANT SLUG AND NOT ON A REPO ID.
+#
+# `core/data_binding.py` is *"the one enforcement door"* and `core/store.py` calls it from six
+# places. This file called it from ZERO, and the settings pane said so out loud: staging reported
+# `writable: false, refusal: "fsanyoto/loopable was not given pg:t_royal_imports"` **while product
+# writes on that same build succeeded** (wave-36 QA, F12). The banner was comparing a pg address
+# against HF-repo-shaped literals — a comparison that can never match — and nothing on the write
+# path was consulting anything at all.
+#
+# ⛔ SO THE OBVIOUS PORT IS THE WRONG ONE, AND IT IS WRONG IN THE DANGEROUS DIRECTION. Matching
+# `PgStore.repo` (`pg:t_royal_imports`) against `data_binding.PRODUCTION_STORES` (HF dataset ids)
+# never hits rule 2, never hits rule 3's allowlist either, and lands on rule 4 — so it refuses
+# EVERY write from every non-production deployment, including the legitimate ones, while the one
+# case it was written for (a staging build on tenant #0's rows) is refused for the wrong reason
+# and would be "fixed" by adding the pg address to an allowlist. A guard that fires on everything
+# gets its allowlist widened until it fires on nothing.
+#
+# ⛔⛔ AND THE REPO ID CANNOT DISCRIMINATE HERE EVEN IN PRINCIPLE. Under `hf`, isolation rides on
+# the address: two deployments write two different dataset repos, so comparing repo strings is
+# comparing destinations. Under `pg` there is no per-deployment address to compare — `deploy_web`
+# pushes ONE `DATABASE_URL`, `store.handle()` routes by tenant SLUG, staging's `tenants.json` is
+# byte-identical to production's, and `_schema_for` defaults the slug to `royal-imports`. Every
+# deployment therefore resolves the SAME schema for the same tenant. The only two facts that
+# differ between a legitimate write and a catastrophic one are WHICH TENANT is being written and
+# WHICH DEPLOYMENT is writing it — so those are the two inputs, and there are no others.
+#
+# ⚠ READS ARE NOT REFUSED, exactly as on the HF side and for the reason stated there: a refused
+# read hands back an empty grid that reads as "no data" rather than as "refused". `get`,
+# `get_projection`, `exists`, `download_bytes` and `revision` are deliberately unguarded.
+#
+# ⛔ WHAT THIS DOES NOT COVER, said here rather than discovered later: raw SQL through `_pool()`.
+# `ops/seed_pg_from_hf.py` opens a connection directly to apply the DDL, and any future tool can.
+# The guard is on the STORE INTERFACE — the four functions every product write crosses — not on
+# the database handle. A caller that reaches past the interface reaches past the guard.
+# =============================================================================================
+
+#: The tenant slugs whose `t_<slug>` schema holds REAL customer data.
+#:
+#: ⛔ THIS IS RULE 2, NOT THE WHOLE GUARD — the same standing as `data_binding.PRODUCTION_STORES`,
+#: which it mirrors one-for-one (`verify_store_binding.py::section_constants` pins the mapping, so
+#: a fifth tenant added to one list and not the other goes red). It exists to make a DELIBERATE
+#: mis-grant loud: `AIOS_SANDBOX_TENANTS=royal-imports` typed by hand must not open tenant #0.
+#: Rule 4 below is what covers a tenant provisioned after this line was written.
+PRODUCTION_TENANTS = frozenset({
+    'royal-imports',       # tenant #0 — Royal Imports  (royal-imports/cfo-os-data)
+    'nurilab',             # Nurilab                     (royal-imports/aios-nurilab-data)
+    'gtmlab',              # GTM Lab                     (royal-imports/aios-gtmlab-data)
+    'loopable',            # Loopable                    (royal-imports/aios-loopable-data)
+})
+
+#: The env a NON-production deployment uses to name the tenant schemas it may write.
+#: Comma-separated slugs. The pg twin of `AIOS_SANDBOX_STORES`, and the polarity is the same one
+#: that keeps the HF guard honest: forgetting it makes a deployment write LESS, never more.
+#:
+#: ⛔ `AIOS_TENANT` IS DELIBERATELY NOT A GRANT. It is a DEFAULT — unset, it resolves to tenant #0 —
+#: so treating it as a hand-off would mean "a process that named no tenant is authorised for the
+#: one it did not name". That is `--data-repo`'s exact failure, which is the failure this file's
+#: existence is a response to.
+_SANDBOX_TENANTS_VAR = 'AIOS_SANDBOX_TENANTS'
+
+
+def sandbox_tenants():
+    """The tenant slugs a non-production deployment was explicitly handed."""
+    raw = str(os.environ.get(_SANDBOX_TENANTS_VAR) or '')
+    return frozenset(s.strip().lower() for s in raw.split(',') if s.strip())
+
+
+def write_refusal(tenant_slug=None):
+    """`None` if this deployment may write this tenant's schema, else the sentence explaining why.
+
+    The pg twin of `data_binding.write_refusal`, and the four rules are the same four — only the
+    thing being classified changes, from a dataset repo to a tenant slug:
+
+        1. the PRODUCTION deployment                          -> may write any tenant
+        2. any other deployment writing a PRODUCTION tenant   -> REFUSED (a laptop may opt in)
+        3. any other deployment writing a tenant it was HANDED -> allowed
+        4. anything else                                      -> REFUSED
+
+    ⭐ RULE 2 BEATS RULE 3, deliberately, which is why the order above is the order below: an
+    allowlist must not be able to re-open tenant #0. ⚠ And the Space/laptop asymmetry is carried
+    over unchanged — a Space that is not production gets NO override, because that is the case the
+    owner said "EVER" about.
+    """
+    slug = _effective_slug(tenant_slug)
+    if data_binding.is_production_deployment():
+        return None                                      # rule 1
+    if slug in PRODUCTION_TENANTS:                       # rule 2
+        if data_binding.local_override():
+            return None
+        who = data_binding.deployment_id() or 'this machine (no Space identity)'
+        where = f'{slug!r} ({_schema_for(slug)})'
+        if data_binding.is_space():
+            return (f'{who} is not the production deployment, so it may not write tenant {where}, '
+                    f'which holds real customer data. Point this deployment at its own database, '
+                    f'or name the sandbox tenants it may write in {_SANDBOX_TENANTS_VAR}. There is '
+                    f'no override for a Space: a build that is not live never writes live data.')
+        return (f'{who} may not write tenant {where}, which holds real customer data. Set '
+                f'AIOS_TENANT to a sandbox tenant, or set '
+                f'{data_binding._LOCAL_OPT_IN_VAR}=1 to opt in deliberately.')
+    allow = sandbox_tenants()                            # rule 3
+    if slug in allow:
+        return None
+    who = data_binding.deployment_id() or 'this machine (no Space identity)'
+    listed = ', '.join(sorted(allow)) or '(nothing)'
+    return (f'{who} was not given tenant {slug!r}. A non-production deployment may write only the '
+            f'tenants it was handed: {listed}. Add it to {_SANDBOX_TENANTS_VAR} if that is '
+            f'intended.')
+
+
+def check_write(tenant_slug=None, operation='write'):
+    """Raise `StoreWriteRefused` unless this deployment may write this tenant. The pg door.
+
+    ⭐ IT RAISES `data_binding.StoreWriteRefused` — the SAME type the HF backend raises, not a pg
+    twin — and that is load-bearing rather than tidy. `api/main.py:185` carries one exception
+    handler for that type which answers 503 with the reason, and the type is deliberately NOT a
+    subclass of `StoreUnavailable` so it falls through every route that would otherwise DEGRADE to
+    a session-scoped fallback and tell the user their change was saved. A new type would have had
+    to re-earn both properties, and would have failed the second one silently.
+    """
+    reason = write_refusal(tenant_slug)
+    if reason:
+        raise data_binding.StoreWriteRefused(
+            f'{operation} to tenant {_effective_slug(tenant_slug)!r} refused: {reason}')
 
 
 def _pool():
@@ -181,6 +321,12 @@ def exists(name, tenant_slug=None):
 
 
 def put(name, data, tenant_slug=None):
+    # ⛔ BEFORE `_pool()`, NOT AFTER. A refusal that fires once a connection is open has already
+    # told the database this deployment is here, and on a pooled driver it has already borrowed a
+    # slot. More to the point, ordering is the only thing an offline gate can observe: with the
+    # pool stubbed to raise, "refused" and "reached the database" are two distinguishable answers,
+    # which is what makes the negative control in `verify_store_pg.py` bite without a server.
+    check_write(tenant_slug, f'put {name!r}')
     with _pool().connection() as con:
         con.execute(
             _q('INSERT INTO {tbl} (key, value) VALUES (%s, %s::jsonb) '
@@ -202,6 +348,7 @@ def update(name, fn, flush='sync', tenant_slug=None):
     `flush` is accepted and ignored (see the module docstring): there is no commit budget to
     coalesce against, so 'async' has nothing to defer.
     """
+    check_write(tenant_slug, f'update {name!r}')     # D-353 — see `put`, and before `_pool()`
     with _pool().connection() as con:
         with con.transaction():
             row = con.execute(
@@ -220,6 +367,7 @@ def update(name, fn, flush='sync', tenant_slug=None):
 
 
 def upload_bytes(path_in_repo, data, message=None, tenant_slug=None):
+    check_write(tenant_slug, f'write bytes {path_in_repo!r}')    # D-353 — before `_pool()`
     with _pool().connection() as con:
         con.execute(
             _q('INSERT INTO {tbl} (path, bytes, message) VALUES (%s, %s, %s) '
@@ -239,7 +387,14 @@ def download_bytes(path_in_repo, tenant_slug=None):
 
 
 def delete_path(path_in_repo, tenant_slug=None):
-    """Absent is SUCCESS — deleting what is already gone is the goal (HF backend's contract)."""
+    """Absent is SUCCESS — deleting what is already gone is the goal (HF backend's contract).
+
+    ⚠ ABSENT-IS-SUCCESS DOES NOT EXTEND TO REFUSED. A delete this deployment may not make RAISES;
+    it does not answer True on the grounds that nothing was removed. The lenient return exists so a
+    caller need not care whether a blob was already gone — not so a caller can be told a delete it
+    was forbidden went fine.
+    """
+    check_write(tenant_slug, f'delete {path_in_repo!r}')         # D-353 — before `_pool()`
     with _pool().connection() as con:
         con.execute(_q('DELETE FROM {tbl} WHERE path = %s', 'store_blobs', tenant_slug),
                     (str(path_in_repo),))
@@ -317,6 +472,14 @@ class PgStore:
     behaviour argument (FOR UPDATE in `update`, absent-is-success in `delete_path`, `fresh`
     ignored because a SELECT has no cache to bypass) is stated once, up there, and cannot drift
     between the two entry points.
+
+    ⭐⭐ AND THAT IS WHY THE D-353 GUARD IS NOT REPEATED HERE. `put`, `update`, `upload_bytes` and
+    `delete_path` below pass `tenant_slug=self.tenant_slug` down to the module functions, which
+    call `check_write` before touching the pool — so this class is guarded by delegation rather
+    than by four more copies that could drift out of step with the four above. It matters because
+    THIS is the object the app actually holds: `store.handle()` returns it under `STORE_BACKEND=pg`
+    and `harness.runtime` binds one per tenant, so every product write on the pg path arrives here
+    first and leaves through a guarded module function.
     """
 
     def __init__(self, tenant_slug):

platform/core/table_store.py

@@ -730,14 +730,65 @@ class TableStore:
 
         self._update(username, _drop, shared=lambda shared_fields: shared_fields.pop(key, None))
 
+    def _tenant_wide_keys(self):
+        """The columns of THIS table whose values live in the tenant-wide stratum.
+
+        ⭐ THE CHEAP HALF. A table that shares nothing reads one small per-key file (cache-first
+        per process) and answers the empty set, so `patch_overlay` behaves exactly as it did
+        before W38-T20 for every database that has no shared column. It is deliberately not
+        memoised on the instance: `modules/customer_data.py` and `modules/product_data.py` both
+        hold a MODULE-LEVEL `TABLE_OPS`, so a per-instance cache would serve one request's answer
+        to the next, and this one decides WHERE a value is written.
+        ⚠ LENIENT LIKE EVERY OTHER STRATUM READ, and the failure direction is the safe one: an
+        unreachable shared bucket routes the write to the PER-USER stratum, which is the
+        pre-ticket behaviour, rather than dropping it.
+        """
+        try:
+            import core.shared_overlay as shared_overlay
+            return set(shared_overlay.fields(self.table_key, st=self._st) or ())
+        except Exception:                                    # noqa: BLE001
+            return set()
+
     def patch_overlay(self, username, pid, updates):
-        """Patch only the external editable stratum; never writes to the source system."""
+        """Patch only the external editable stratum; never writes to the source system.
+
+        ⭐⭐ W38-T20 / D-423 — A CELL IN A TENANT-WIDE COLUMN GOES TO THE TENANT-WIDE STRATUM,
+        AND WITHOUT THIS SPLIT THE EDIT SILENTLY DISAPPEARS. The read path layers the shared
+        stratum OVER the per-user one (it has to: that is what makes every reader see the same
+        number). This method wrote PER USER. So the sequence was: type a new value, see it accept,
+        come back, and read the shared value again — the owner's *"I went back and it all got
+        reseted"*, with a successful 200 at every step and nothing in any log.
+
+        ⛔ IT IS DECIDED BY WHERE THE COLUMN LIVES, NOT BY WHO IS WRITING OR THROUGH WHICH ROUTE.
+        `modules/product_data._ProductTableStore` has done exactly this since W30-T36 against its
+        CANONICAL list; the only reason it needed a subclass is that its shared columns are
+        declared in a contract file. Columns created at runtime cannot be, so the general form
+        asks the stratum itself. Both doors (`PATCH /customers/{pid}` and `POST /grid/events`)
+        arrive here through `grid_events._tops(ctx)`, which is why the split belongs at the STORE
+        and not at either route: intercepting at one leaves the other writing into the shadow.
+
+        ⛔ NO PERMISSION IS ANSWERED HERE. `shared_overlay`'s header is explicit that it is not a
+        wall, and neither is this: whether this session may write this key is settled upstream by
+        `EventCtx.hidden_keys`, which `routes_customers._hidden_for` now computes over the MERGED
+        contract precisely so a grant-governed column is refused before it reaches this line.
+        """
         clean = dict(updates or {})
         if not clean:
             return
+        wide = self._tenant_wide_keys()
+        shared = {k: v for k, v in clean.items() if k in wide}
+        personal = {k: v for k, v in clean.items() if k not in wide}
+        if shared:
+            import core.shared_overlay as shared_overlay
+            # ⚠ `st=self._st`, NEVER the module default. The two strata must resolve to the SAME
+            # tenant handle, or a value written by one is invisible to the other and the user's
+            # edit vanishes the moment they save it (`_ProductTableStore` records the same rule).
+            shared_overlay.put_cells(self.table_key, pid, shared, st=self._st)
+        if not personal:
+            return
 
         def _patch(ws):
-            ws['overlays'].setdefault(str(int(pid)), {}).update(clean)
+            ws['overlays'].setdefault(str(int(pid)), {}).update(personal)
 
         self._update(username, _patch)
 

web/src/customer-grid/CustomerGrid.tsx

@@ -188,6 +188,28 @@ import TimeSeriesPanel from "./TimeSeriesPanel";
 import type { WindowSpec } from "./windows";
 import { windowLabel } from "./windows";
 
+/**
+ * ⭐⭐ WAVE 38 · T06 (owner instruction 1) — "OPEN THE CHAT ABOUT THIS DATA", raised by the SHELL.
+ *
+ * Owner: *"When the Navigation is minimized: the icon that opens the AI chatbot overlay with the
+ * grid…"* The launcher lives in the frame's minimised rail; `chatOpen` and the `<GridChat>` mount
+ * live here. So the shell asks and this surface answers, the shape every cross-fence click-through
+ * in this app already has (`VIEW_OPEN_EVENT`, `AUTOMATION_OPEN_EVENT`, `QUERY_OPEN_EVENT`).
+ *
+ * ⛔ THE CANONICAL DECLARATION IS THIS ONE, and its twin in `shell/Shell.tsx` says why the pair
+ * exists rather than one shared constant in `apiContract.ts`: that file was outside the ticket's
+ * `files:` list, `customer-grid/**` may not import `shell/**`, and a static import out of this
+ * module would pull the spreadsheet engine into the shell's entry chunk past the `lazy()` that
+ * keeps it out. `verify_wiring.py`'s W38-T06 row matches the LITERAL on both sides so the two
+ * spellings cannot drift apart in silence.
+ *
+ * ⛔ NO `retryEmit` LADDER, deliberately. `VIEW_OPEN_EVENT` rides one because it races a fresh hash
+ * navigation against a grid that is still mounting. This launcher only exists in a rail that is
+ * already beside a mounted grid, so a bare `signal()` is the honest emit — the same call the fold
+ * signal two fences over makes.
+ */
+export const GRID_CHAT_OPEN_EVENT = "aios:grid-chat-open";
+
 const ROW_PX: Record<RowHeightMode, number> = { short: 28, medium: 34, tall: 48 };
 
 /**
@@ -472,6 +494,39 @@ function queryPreviewView(binding: QueryVirtualBinding, fields: Field[]): SavedV
   };
 }
 
+/**
+ * ⭐⭐ W38-T07 (owner instruction 12) — THE ONE WRITER OF A COLOUR CHOICE, AND IT WRITES BOTH
+ * TARGETS.
+ *
+ * The colour a person picks is READ from two places by two different renderers:
+ *   · `config.colorBy`      -> the grid's row wash (`getRowThemeOverride` -> STATUS_ROW_THEME)
+ *   · `config.display.colorField` -> the map's pin colours (MapView -> SERIES)
+ * They were written by two different controls, which is exactly the duplication the owner
+ * reported. With ONE control, every path that sets a colour has to set both, or the single door
+ * has a back door writing half the state: the pins would recolour while the toolbar still read
+ * "No color".
+ *
+ * ⛔ A PURE FUNCTION ON PURPOSE, not a hook: `onChatApplyView` needs it too (E's chat could
+ * already say "colour by status" and it wrote `colorField` ALONE), and a second half-writer is
+ * how this defect grows back. Both callers go through here.
+ *
+ * ⚠ `?? { mode: "grid" }` is exact rather than a guess, and it is the shape `onChatApplyView`
+ * already used: `cleanDisplay` returns undefined only when the view stores no display spec at
+ * all, and a view with no spec IS in grid mode. Grid WITH refs is a legal stored shape (the W13
+ * carry), so a colour picked on the grid survives a trip through Map and back.
+ *
+ * ⚠ The result is piped back through `cleanDisplay` so that clearing the colour on a view which
+ * had no other display ref normalises to `undefined` rather than storing a bare `{mode:"grid"}` —
+ * the churn `viewEcho`'s whole-object compare would otherwise see forever.
+ */
+function withColorField(config: ViewConfig, key: string): ViewConfig {
+  const spec = cleanDisplay(config.display) ?? { mode: "grid" as const };
+  const display: DisplaySpec = { ...spec };
+  if (key) display.colorField = key;
+  else delete display.colorField;
+  return { ...config, colorBy: key || null, display: cleanDisplay(display) };
+}
+
 function readLocal(storageKey: string): LocalWorkspace | null {
   try {
     const raw = localStorage.getItem(`aios-grid:${storageKey}`);
@@ -2696,6 +2751,28 @@ function CustomerGridSurface({
    * is this repo's most repeated defect (five whole unreachable features in one wave).
    */
   const [chatOpen, setChatOpen] = useState(false);
+  /**
+   * ⭐⭐ WAVE 38 · T06 (owner instruction 1) — THE SHELL'S MINIMISED-RAIL LAUNCHER LANDS HERE.
+   *
+   * ⛔ IT OPENS, IT DOES NOT TOGGLE, and that is a consequence of the fence rather than a taste
+   * call: the shell cannot see `chatOpen`, so a toggle raised from over there would CLOSE a panel
+   * the user was already reading whenever the two states disagreed. "Open" is idempotent and is
+   * the only instruction a caller with no view of the state can honestly give. The views rail's
+   * `cg-chat-toggle` keeps the toggle, because it is inside this fence and can see it.
+   *
+   * ⛔ THE GUARD IS THE MOUNT'S GUARD, RESTATED, NOT A NEW ONE. `<GridChat>` renders under
+   * `!embedded && !queryBinding` (a linked-record grid in a modal and a Query preview each have no
+   * database of their own for a chat to be about). Flipping `chatOpen` where the panel cannot mount
+   * would set a flag nothing reads, so the LISTENER is what is absent there — which is also the
+   * second of the two reasons a click with no grid on screen cannot throw. The first is that
+   * `signal()` on a window with no listener at all is a plain no-op.
+   */
+  useEffect(() => {
+    if (embedded || queryBinding) return;
+    const onOpenChat = () => setChatOpen(true);
+    window.addEventListener(GRID_CHAT_OPEN_EVENT, onOpenChat);
+    return () => window.removeEventListener(GRID_CHAT_OPEN_EVENT, onOpenChat);
+  }, [embedded, queryBinding]);
   /** The config to put back when the chat is asked to undo its own view change (E-4 `onUndoView`).
    *  A snapshot rather than a diff: the chat may change several axes at once, and a per-axis undo
    *  would restore some of them. */
@@ -2751,15 +2828,22 @@ function CustomerGridSurface({
   const onChatApplyView = useCallback(
     (spec: GridChatViewSpec) => {
       chatUndoRef.current = config;
-      const next: ViewConfig = { ...config };
+      let next: ViewConfig = { ...config };
       if (spec.sortBy && fieldByKey.has(spec.sortBy))
         next.sorts = [{ colId: spec.sortBy, dir: "asc" }];
       if (spec.groupBy !== undefined)
         next.groupBy = spec.groupBy && fieldByKey.has(spec.groupBy) ? spec.groupBy : null;
-      if (spec.colorBy !== undefined)
-        next.display = spec.colorBy && fieldByKey.has(spec.colorBy)
-          ? { ...(next.display ?? { mode: "grid" }), colorField: spec.colorBy }
-          : next.display;
+      /* ⭐⭐ W38-T07 — THROUGH THE ONE WRITER. This clause used to set `display.colorField` and
+         nothing else, which was true enough while the map owned a colour picker of its own and
+         the grid's wash had a separate on/off control. With ONE control reading `config.colorBy`,
+         a half-write here would recolour the pins while the control that claims to be the single
+         door still reported "No color" — the back door that makes a merged control a lie.
+         ⚠ The GUARD is unchanged on purpose: an absent or unresolvable `colorBy` is still a
+         NO-OP rather than a clear, because E's `readIntent` omits the key when the question said
+         nothing about colour, and reading that omission as "turn colour off" would have the
+         assistant undoing a pick the person made by hand. */
+      if (spec.colorBy && fieldByKey.has(spec.colorBy))
+        next = withColorField(next, spec.colorBy);
       updateConfig(next);
     },
     [config, fieldByKey, updateConfig]
@@ -6203,8 +6287,10 @@ function CustomerGridSurface({
       dateChoices={dateFieldChoices}
       stackField={kanbanField}
       stackChoices={stackFieldChoices}
-      colorField={mapColorField}
-      colorChoices={colorFieldChoices}
+      /* ⭐ W38-T07 — the map's own colour picker is GONE from the mode bar, so the two props that
+         fed it go with it. `mapColorField` survives: `MapView` still reads the encoding, it just
+         no longer offers a second control for choosing it. `colorFieldChoices` survives too and
+         now feeds the toolbar's one Color control. */
       sizeField={mapSizeField}
       sizeChoices={sizeFieldChoices}
       onPickField={setDisplayField}
@@ -6639,15 +6725,17 @@ function CustomerGridSurface({
           onFieldOrder={(keys) => updateConfig({ ...config, order: keys })}
           deletableKeys={deletableKeys}
           onDeleteField={deleteField}
-          colorOn={config.colorBy !== null}
-          onToggleColor={(on) =>
-            updateConfig({
-              ...config,
-              colorBy: on
-                ? fields.find((field) => field.type === "status")?.key ?? null
-                : null,
-            })
-          }
+          /* ⭐⭐ W38-T07 (owner instruction 12) — THE ONE COLOUR CONTROL. This was `colorOn` plus a
+             boolean toggle whose `true` arm guessed the column: `fields.find(type === "status")`,
+             so on a table with two status columns the person got the first one and had no way to
+             say which. Map view then mounted a picker of its own to answer the same question,
+             which is the duplication reported. The toolbar's control now names the field, and
+             `withColorField` writes BOTH the grid's `colorBy` and the map's `display.colorField`.
+             ⚠ ONE list of eligible columns, shared with the map's own resolution above
+             (`colorFieldChoices`), so "what can carry a colour" has a single definition. */
+          colorField={config.colorBy}
+          colorChoices={colorFieldChoices}
+          onColorField={(key) => updateConfig(withColorField(config, key))}
           rowHeightMode={config.rowHeightMode}
           onRowHeightMode={(rowHeightMode) => updateConfig({ ...config, rowHeightMode })}
           filters={config.filters}

web/src/customer-grid/MapView.tsx

@@ -80,13 +80,15 @@ import {
   planRoute,
   pointInPolygon,
   project,
+  routeFingerprint,
+  routeRanks,
   toScreen,
   unproject,
   WORLD,
   zoomAt,
   zoomLimits,
 } from "./mapProjection";
-import type { GeoStop, Pt, View } from "./mapProjection";
+import type { GeoStop, Pt, RouteStamp, View } from "./mapProjection";
 import "./map.css";
 
 /**
@@ -270,6 +272,28 @@ export function MapView({
   >(null);
   const [roadBusy, setRoadBusy] = useState(false);
   const [roadErr, setRoadErr] = useState<string | null>(null);
+  /**
+   * ⭐⭐ W38-T20 — THE ROUTE-ORDER COLUMNS THIS ACCOUNT MAY SEE, fetched rather than read off the
+   * grid's `fields`.
+   *
+   * ⛔ TWO REASONS, AND THE SECOND IS THE REAL ONE. `MapView` is handed the field it PLOTS, not
+   * the table's field list, so it could not find them anyway; and the useful half is not the
+   * column, it is the INPUT FINGERPRINT each column was solved from, which the grid contract has
+   * no business carrying to every reader of every row. `GET /customers/route-order` serves the
+   * pair behind the same per-field wall the grid uses, so a column this account was not granted
+   * is absent here exactly as it is absent there.
+   * ⚠ `null` means NOT ASKED YET and `[]` means none exist. They are different states: the first
+   * must not render "no saved orders".
+   */
+  const [routeCols, setRouteCols] = useState<
+    { key: string; label: string; inputsHash: string; mine: boolean }[] | null
+  >(null);
+  /** Which saved column a save writes to. `""` = a new one, named by `saveName`. */
+  const [saveTarget, setSaveTarget] = useState("");
+  const [saveName, setSaveName] = useState("");
+  const [saveBusy, setSaveBusy] = useState(false);
+  const [saveMsg, setSaveMsg] = useState<string | null>(null);
+  const [saveErr, setSaveErr] = useState<string | null>(null);
   /**
    * W37-T37 — the address lookup's own progress, and it exists so the WAIT IS VISIBLE.
    *
@@ -574,19 +598,60 @@ export function MapView({
       if (i >= 0) start = i;
     }
     const { order, km } = planRoute(stops, haversineKm, { start, roundTrip });
-    let ordered = order.map((i) => routable[i]);
+    // ⭐⭐ W38-T20 — THE HAND-REORDER STAYS IN **INDEX** SPACE, and that is a deliberate change of
+    // representation rather than a tidy-up. `stops`, `routable` and `order` are one index space
+    // already (`order.map(i => routable[i])` is what zips them back), and the visit NUMBER a
+    // record carries is the inverse of a permutation over exactly that space. Rebuilding the
+    // sequence out of MapPoints and then recovering indices from it would be a second, silent
+    // conversion between the two — and W38-T21 prepends a synthetic depot into this same index
+    // space, which is far harder to reason about across two representations than one.
+    // ⚠ EXACTLY THE OLD BEHAVIOUR: `order` is a permutation of every index and `ordered` was
+    // `order.map(i => routable[i])`, so filtering `order` by index-not-seen selects the same
+    // stops, in the same sequence, as filtering `ordered` by pid-not-seen did.
+    let seq = order;
     // W37-T36 — a hand-picked order wins over the planner's, but only for the stops that are still
     // selected. Anything the user has since deselected drops out; anything newly selected is
     // appended in the planner's own order rather than being silently left off the route.
     if (routeOrder) {
-      const byPid = new Map(routable.map((p) => [p.pid, p]));
-      const picked = routeOrder.map((pid) => byPid.get(pid)).filter(Boolean) as MapPoint[];
-      const seen = new Set(picked.map((p) => p.pid));
-      ordered = [...picked, ...ordered.filter((p) => !seen.has(p.pid))];
+      const idxByPid = new Map(routable.map((p, i) => [p.pid, i]));
+      const picked = routeOrder
+        .map((pid) => idxByPid.get(pid))
+        .filter((i) => i !== undefined) as number[];
+      const seen = new Set(picked);
+      seq = [...picked, ...order.filter((i) => !seen.has(i))];
     }
+    const ordered = seq.map((i) => routable[i]);
+    // ⛔⛔ THE PERMUTATION IS NOT THE RANK (A25 / A44). `seq[i]` is WHICH STOP is visited i-th;
+    // the number a record carries is the other way round, and `routeRanks` is the one inversion.
+    // It is called HERE, in the shipped path, and not only in the gate: a tested function the
+    // product does not use guards nothing (`paintedRadius`'s docstring is this repo's record of
+    // that, and the wave-29 client-px conversion is the scar).
+    const ranks = routeRanks(seq, routable.length);
     return {
       ordered,
       km,
+      /** `{pid: visit number}` — what the route-order COLUMN stores, one integer per record. */
+      ranksByPid: routable.reduce((acc, p, i) => {
+        const n = ranks[i];
+        if (n != null) acc[p.pid] = n;
+        return acc;
+      }, {} as Record<number, number>),
+      /**
+       * The identity of the INPUTS this order was solved from, so staleness can be DERIVED at
+       * read time rather than stored. A saved column carries the fingerprint it was solved with;
+       * when this one differs, what is on screen would solve to different numbers.
+       */
+      fingerprint: routeFingerprint(
+        routable.map((p) => ({ pid: p.pid, lat: p.lat, lon: p.lon } as RouteStamp)),
+        // ⚠ THE RESOLVED ORIGIN, NOT `routeStartPid`. The picker is null while the westernmost
+        // default applies, so keying on it would report STALE the moment somebody explicitly
+        // selects the stop that was ALREADY the origin — the numbers unchanged, the marker on.
+        // What the answer depends on is which stop the planner was actually given.
+        { roundTrip, startPid: routable[start].pid, handOrder: routeOrder }
+      ),
+      /** The origin the planner was given, so the saved column records the same one the
+       *  fingerprint was taken over. */
+      startPid: routable[start].pid,
       link: googleRouteUrl(
         ordered.map((p) => ({ lat: p.lat, lon: p.lon })),
         { roundTrip, coarsePointer }
@@ -665,6 +730,102 @@ export function MapView({
     void fetchRoad();
   }, [plan, fetchRoad]);
 
+  // ─────────────────────────────── W38-T20: the order, as a column every colleague reads ───────
+  /**
+   * The saved route-order columns, refreshed from the server.
+   *
+   * ⚠ A READ, so it may run without a click, unlike `fetchRoad`. R3 is about not spending a
+   * ROUTING request on a render; this asks our own store for a short list of column names and is
+   * the only way the STALE marker can exist at all.
+   */
+  const loadRouteCols = useCallback(async () => {
+    try {
+      const res = await fetch("/api/v1/customers/route-order", { credentials: "same-origin" });
+      const body = res.ok ? await res.json().catch(() => null) : null;
+      setRouteCols(Array.isArray(body?.fields) ? body.fields : []);
+    } catch {
+      // A listing that cannot be fetched is "none known", not an error banner over the map: the
+      // planner still works, and the save below reports its own failure in its own words.
+      setRouteCols([]);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (routeOn && routeCols === null) void loadRouteCols();
+  }, [routeOn, routeCols, loadRouteCols]);
+
+  /**
+   * Write the visit numbers on screen into a tenant-wide column.
+   *
+   * ⛔ THE NUMBER PER RECORD IS `plan.ranksByPid`, WHICH IS THE **INVERSE** OF THE PLANNER'S
+   * ANSWER (A25 / A44). `planRoute` returns which stop is visited i-th; a column answers what
+   * number THIS record carries. Sending the permutation would fill every row with a plausible
+   * integer from somebody else's stop, and nothing downstream could tell.
+   *
+   * ⚠ THE FINGERPRINT GOES WITH IT, ONCE. One solve covers the whole cohort, so the inputs are
+   * identical for every record; the server stores it on the column DEFINITION. Staleness is then
+   * derived by comparing it against `plan.fingerprint` on whatever is on screen later.
+   */
+  const saveRouteOrder = useCallback(async () => {
+    if (!plan) return;
+    const ranks = plan.ranksByPid;
+    if (Object.keys(ranks).length < 2) return;
+    setSaveBusy(true);
+    setSaveErr(null);
+    setSaveMsg(null);
+    try {
+      const res = await fetch("/api/v1/customers/route-order", {
+        method: "POST",
+        credentials: "same-origin",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          field: saveTarget || undefined,
+          label: saveTarget
+            ? (routeCols || []).find((f) => f.key === saveTarget)?.label || saveTarget
+            : saveName.trim(),
+          ranks,
+          inputsHash: plan.fingerprint,
+          roundTrip,
+          startPid: plan.startPid,
+        }),
+      });
+      const body = await res.json().catch(() => null);
+      if (!res.ok) {
+        // ⭐ THE SERVER'S OWN SENTENCE. It knows whether a record was outside this book, whether
+        // the numbers were not a clean sequence, or whether somebody else planned this column,
+        // and those need three different things from the person reading it.
+        setSaveErr(
+          (body && body.error && body.error.message) ||
+            "The visit order could not be saved."
+        );
+        return;
+      }
+      setSaveTarget(String(body?.field || ""));
+      setSaveName("");
+      setSaveMsg(
+        `Saved ${Number(body?.stops || 0).toLocaleString()} visit numbers to ` +
+          `${body?.label || "the column"}` +
+          (body?.cleared ? `, and cleared ${Number(body.cleared).toLocaleString()} that dropped out` : "")
+      );
+      await loadRouteCols();
+    } catch {
+      setSaveErr("The visit order could not be saved.");
+    } finally {
+      setSaveBusy(false);
+    }
+  }, [plan, saveTarget, saveName, roundTrip, routeCols, loadRouteCols]);
+
+  /**
+   * The saved column selected for writing, and whether what is on screen would solve differently.
+   *
+   * ⛔ STALE IS DERIVED HERE AND STORED NOWHERE. What the server keeps is the fingerprint the
+   * numbers were produced FROM, so this comparison is made against the cohort as it is right now
+   * and can never itself be out of date. A stored flag would be a claim about a moment that has
+   * already passed.
+   */
+  const savedCol = (routeCols || []).find((f) => f.key === saveTarget) || null;
+  const orderStale = !!(savedCol && plan && savedCol.inputsHash !== plan.fingerprint);
+
   /** The drawn road, projected once per answer. Straight-line fallback stays in `plan`, so a map
    *  that never got a road answer still shows the sequence it worked out for itself. */
   const roadPath = useMemo(() => {
@@ -922,19 +1083,39 @@ export function MapView({
   );
 
   /**
-   * D-135 (W37-T30) — a pin could be OPENED and never SELECTED.
+   * ⛔⛔ W38-T09 (ruling R10) — A SINGLE CLICK ON A PIN OPENS THE RECORD. This SUPERSEDES the
+   * single-click-SELECTS half of W37-T30 (D-135), which was built deliberately one wave ago. The
+   * paragraph W37-T30 wrote is kept below rather than deleted, because its argument is still the
+   * argument that has to be traded against, and a reader who only sees the winner cannot tell a
+   * decision from an accident.
    *
-   * ⭐ THE MAP WAS THE LAST VIEW STILL ON THE OLD INTERACTION MODEL. Owner item 19 moved the whole
+   * ⭐ WHAT W37-T30 ARGUED, AND IT WAS NOT WRONG AT THE TIME. Owner item 19 moved the whole
    * product off click-to-open: in the grid "the single click that used to open a record now
-   * highlights it" and opening moved to a deliberate affordance (CustomerGrid.tsx, the hover-only
-   * Expand). The map kept firing `onOpen` on a bare click, so the one view built around choosing a
-   * SET of records was the one view where choosing was impossible, and the "N selected" bar,
-   * "Add to cohort" and the route planner all sat behind a gesture the map did not have.
+   * highlights it", and opening moved to a deliberate affordance (CustomerGrid.tsx, the
+   * hover-only Expand). The map went on firing `onOpen` on a bare click, so the one view built
+   * around choosing a SET of records was the one view where choosing was impossible, and the
+   * "N selected" bar, "Add to cohort" and the route planner all sat behind a gesture the map did
+   * not have.
+   *
+   * ⭐ WHAT R10 TRADES IT FOR. A pin is not a row. A row lives in a sheet where the cursor already
+   * means "this cell", so click-to-highlight costs a user nothing; a pin is a target you had to
+   * AIM at, and the thing you wanted after aiming is the record. Every set-building gesture the
+   * map grew for item 19 SURVIVES, and not one of them is the plain click: shift-drag and the
+   * lasso build a cohort, shift-alt-drag extends one, a modifier click toggles a single pin in or
+   * out, and the keyboard keeps Space for select and Enter for open.
+   *
+   * ⚠ SO `pinSelect`'s NON-ADDITIVE BRANCH IS NOW KEYBOARD-ONLY, not dead. A plain Space still
+   * replaces the selection with the focused pin; a pointer no longer has that gesture at all.
+   * Deleting the branch as unreachable would take the keyboard's only "just this one" with it.
+   *
+   * ⛔ AND `movedRef` IS NOW LOAD-BEARING FOR A WORSE REASON THAN THE ONE IT WAS WRITTEN FOR.
+   * Before R10, a pan or a box-drag that happened to finish on top of a pin mis-SELECTED it.
+   * After R10 the same stray gesture would OPEN a drawer over the map. Whoever next reads that
+   * early return as noise should read this sentence instead: its failure mode got louder.
    *
-   * So: a plain click selects, a modifier click TOGGLES that pin in or out of the set, and opening
-   * escalates to a double click. Toggle rather than plain accumulate is done here rather than
-   * asked for from the host, because `onSelectPids` offers "replace" and "add" only, and a second
-   * shift-click that cannot undo the first is a trap on a map where pins overlap.
+   * Toggle rather than plain accumulate is done here rather than asked for from the host, because
+   * `onSelectPids` offers "replace" and "add" only, and a second shift-click that cannot undo the
+   * first is a trap on a map where pins overlap.
    */
   const pinSelect = useCallback(
     (pid: number, additive: boolean) => {
@@ -1274,6 +1455,80 @@ export function MapView({
                       Re-optimise
                     </button>
                   )}
+                  {/* ⭐⭐ W38-T20 — THE ORDER BECOMES A COLUMN EVERY PERMITTED COLLEAGUE READS.
+                      Until now a planned day lived in one browser tab: close it and the sequence
+                      is gone, and nobody else ever saw it. The number written per record is the
+                      INVERSE of the planner's permutation (see `saveRouteOrder`), the column is
+                      tenant-wide and grant-governed, and the fingerprint it was solved from rides
+                      the column so a later reader can be told it is out of date instead of being
+                      shown yesterday's numbers as though they were today's. */}
+                  <label className="cg-map-route-opt">
+                    Visit order column
+                    <select
+                      className="cg-map-route-start"
+                      value={saveTarget}
+                      aria-label="Which visit order column to write"
+                      onChange={(e) => {
+                        setSaveTarget(e.target.value);
+                        setSaveMsg(null);
+                        setSaveErr(null);
+                      }}
+                    >
+                      <option value="">New column</option>
+                      {(routeCols || [])
+                        .filter((f) => f.mine)
+                        .map((f) => (
+                          <option key={f.key} value={f.key}>
+                            {f.label}
+                          </option>
+                        ))}
+                    </select>
+                  </label>
+                  {!saveTarget && (
+                    <input
+                      type="text"
+                      /* ⚠ The SELECT's class, deliberately: `index.css` is outside this
+                         change's fence, and `.cg-map-route-start` is already the bar's
+                         input styling (border, radius, 22 px, inherited font). A new class
+                         would render unstyled until somebody remembered the stylesheet. */
+                      className="cg-map-route-start"
+                      value={saveName}
+                      placeholder="Name this order"
+                      aria-label="Name this visit order column"
+                      maxLength={60}
+                      onChange={(e) => setSaveName(e.target.value)}
+                    />
+                  )}
+                  <button
+                    type="button"
+                    className="cg-map-route-go"
+                    disabled={saveBusy || (!saveTarget && !saveName.trim())}
+                    onClick={() => void saveRouteOrder()}
+                    title={
+                      saveTarget
+                        ? "Write these visit numbers into the saved column, for everyone it is shared with"
+                        : "Save these visit numbers as a column your colleagues can be given"
+                    }
+                  >
+                    {saveBusy ? "Saving" : saveTarget ? "Update visit order" : "Save visit order"}
+                  </button>
+                  {/* ⛔ DERIVED, NEVER STORED. The saved column carries the fingerprint of the
+                      inputs it was solved from; this compares it against the cohort ON SCREEN
+                      NOW. So the marker cannot itself go out of date, and nothing recomputes
+                      under somebody mid-day. */}
+                  {orderStale && (
+                    <span className="cg-map-route-note">
+                      Stale. The saved numbers were solved from different stops, so re-solving
+                      would change them.
+                    </span>
+                  )}
+                  {(routeCols || []).some((f) => !f.mine) && (
+                    <span className="cg-map-route-note">
+                      Shared orders you can read but not re-solve are not listed above.
+                    </span>
+                  )}
+                  {saveMsg && <span className="cg-map-route-note">{saveMsg}</span>}
+                  {saveErr && <span className="cg-cal-nodate">{saveErr}</span>}
                   <button
                     type="button"
                     className="cg-map-route-go"
@@ -1322,8 +1577,8 @@ export function MapView({
             knew about. It needs shift too — alt alone still pans. */}
         <span className="cg-map-hint">
           Scroll to zoom · drag to pan · {lassoTool ? "shift-drag to lasso" : "shift-drag to select"}{" "}
-          · shift-alt-drag to extend the selection · click a pin to select it · shift-click to add
-          or remove one · double-click to open the record
+          · shift-alt-drag to extend the selection · click a pin to open the record · shift-click a
+          pin to add or remove it from the selection
         </span>
       </div>
       <div
@@ -1464,27 +1719,48 @@ export function MapView({
                   role="button"
                   tabIndex={0}
                   aria-pressed={on}
-                  aria-label={`${p.title || "Untitled record"}. Click to select, double click to open.`}
+                  // ⛔ THE ACCESSIBLE NAME IS THE ONLY CHANNEL A NON-SIGHTED USER HAS FOR A PIN'S
+                  // gesture: a `<circle>` carries no tooltip, no hover card and no glyph, and the
+                  // hint bar above is the SIGHTED half of this same disclosure. It said "Click to
+                  // select, double click to open." until R10 made that false.
+                  // Policed by `verify_ui.py::pin_label_states_the_gesture`.
+                  aria-label={`${p.title || "Untitled record"}. Click to open, shift-click to select.`}
                   onMouseEnter={() => setHoverPid(p.pid)}
                   onMouseLeave={() => setHoverPid((h) => (h === p.pid ? null : h))}
                   onFocus={() => setHoverPid(p.pid)}
                   onBlur={() => setHoverPid((h) => (h === p.pid ? null : h))}
                   onClick={(e) => {
-                    if (movedRef.current) return; // a finished pan/box is not a click
-                    pinSelect(p.pid, e.shiftKey || e.ctrlKey || e.metaKey);
+                    // ⛔ NO LONGER MERELY "a finished pan is not a click" (R10): a drag that ends
+                    // on a pin would now OPEN a drawer, not just move the selection. See the
+                    // `pinSelect` doc comment above before touching this line.
+                    if (movedRef.current) return;
+                    // ⭐ THE SPLIT R10 ASKS FOR, and `verify_map.py::structural_scan` reads it
+                    // STRUCTURALLY: the select lives inside this block and the open lives outside
+                    // it, which is the one claim a substring search cannot make.
+                    const additive = e.shiftKey || e.ctrlKey || e.metaKey;
+                    if (additive) {
+                      pinSelect(p.pid, true);
+                      return;
+                    }
+                    onOpen(p.pid);
                   }}
-                  // Opening escalates to a double click now that a single one selects. The two
-                  // clicks React reports before this one are both `pinSelect` on the SAME pid, so
-                  // the selection lands where the user pointed either way.
+                  // ⚠ KEPT AFTER R10, AND IT IS NO LONGER AN ESCALATION. A plain click already
+                  // opened the record, so this fires `onOpen` a second time on the SAME pid --
+                  // idempotent, because the host's handler is a `setDetailPid` identity. It stays
+                  // because removing it would make a double click on a pin do nothing at all,
+                  // and because a user who learned the old gesture keeps getting the record.
                   onDoubleClick={(e) => {
                     if (movedRef.current) return;
                     e.preventDefault();
                     onOpen(p.pid);
                   }}
                   onKeyDown={(e) => {
-                    // ⚠ The keyboard keeps a DIRECT open on Enter rather than mirroring the double
-                    // click: focus already says which pin, and there is no keyboard gesture that
-                    // means "twice, quickly". Space is the selection half.
+                    // ⚠ AFTER R10 THIS IS THE MIRROR, not the exception it used to be: Enter opens
+                    // exactly as a plain click now does, and Space is the selection half exactly
+                    // as a modifier click is. Space with a modifier toggles; Space alone still
+                    // REPLACES the selection, which is the only surface left that can.
+                    // ⛔ No `movedRef` check here, deliberately: a keypress has no drag to
+                    // disambiguate, so the guard the pointer needs would only be superstition.
                     if (e.key === "Enter") {
                       e.preventDefault();
                       onOpen(p.pid);

web/src/customer-grid/Toolbar.tsx

@@ -4,8 +4,9 @@
 // buttons with popovers, a hairline underline, tabular-nums count.
 //
 // PURELY PRESENTATIONAL. Every piece of state and every setter is a prop; this
-// file owns no view-state and knows nothing about glide. The color on/off ->
-// status-key mapping lives in CustomerGrid (Toolbar just gets colorOn + toggle).
+// file owns no view-state and knows nothing about glide. W38-T07: the Color
+// control is a FIELD PICKER, so the prop is the chosen key plus the eligible
+// columns, and CustomerGrid owns what a chosen key is written into.
 //
 // Controls left -> right: Fields (hide/show), Filter+Sort (disabled, next
 // batch), Color (by status), Rows (height) | spacer | Search | "N records".
@@ -67,8 +68,21 @@ export interface ToolbarProps {
   deletableKeys?: ReadonlySet<string>;
   onDeleteField?: (key: string) => void;
 
-  colorOn: boolean;
-  onToggleColor: (on: boolean) => void;
+  /**
+   * ⭐⭐ W38-T07 (owner instruction 12) — THE ONE COLOUR CONTROL, and it names a FIELD rather than
+   * answering yes/no. It used to be two radios ("No color" / "Color by status") whose `true` arm
+   * made CustomerGrid guess at `fields.find(type === "status")`, so the person never chose; Map
+   * view then mounted a SECOND colour picker of its own, which is the duplication this closes.
+   *
+   * ⛔ THE KEY, NOT A PALETTE. Two renderers consume the choice and their palettes are
+   * structurally different engines — see the control's own note further down. This prop carries
+   * a column key and nothing about how either of them paints it.
+   */
+  colorField: string | null;
+  /** The columns eligible to carry a colour. Resolved by the caller, shared with the map. */
+  colorChoices: Field[];
+  /** `""` is the real "no colour" choice, matching every other optional field ref in this app. */
+  onColorField: (key: string) => void;
 
   rowHeightMode: RowHeightMode;
   onRowHeightMode: (m: RowHeightMode) => void;
@@ -556,8 +570,9 @@ export default function Toolbar({
   onFieldOrder,
   deletableKeys,
   onDeleteField,
-  colorOn,
-  onToggleColor,
+  colorField,
+  colorChoices,
+  onColorField,
   rowHeightMode,
   onRowHeightMode,
   filters,
@@ -699,6 +714,12 @@ export default function Toolbar({
   const groupLabel = groupBy
     ? `Group: ${fieldByKey.get(groupBy)?.label ?? "?"}`
     : "Group";
+  // W38-T07 — the trigger NAMES the chosen column, exactly as Group's does one line up. A
+  // control that only lights up makes the reader open it to learn which column it picked, and
+  // this one now has a column to report.
+  const colorLabel = colorField
+    ? `Color: ${colorChoices.find((f) => f.key === colorField)?.label ?? "?"}`
+    : "Color";
 
   return (
     <div className="cg-toolbar">
@@ -727,7 +748,12 @@ export default function Toolbar({
         )}
       </Popover>
 
-      {/* Filter — condition builder */}
+      {/* Filter — condition builder.
+          W38-T02 (owner instruction 8): `Popover` has always manufactured a closer and handed it
+          to this render-prop, and this call site has always spelled the prop zero-arg and thrown
+          it away. Taking the argument and passing it down is the whole of the header X wiring —
+          no new plumbing, no new state, and Escape / click-outside keep working because they were
+          never this closer's doing in the first place. */}
       <Popover
         label={filterLabel}
         icon={<IconFilter />}
@@ -738,7 +764,7 @@ export default function Toolbar({
         pairWide={hasComparand}
         forceOpenSignal={filterSeed?.n}
       >
-        {() => (
+        {(close) => (
           <FilterBuilderPanel
             // The COMPLETE list: the kit narrows the picker to the filterable ones itself and
             // keeps the full map for resolving a condition saved against a column that has
@@ -751,6 +777,7 @@ export default function Toolbar({
             onChange={onFilterTree}
             statusValues={statusValues}
             cohortLock={cohortLock}
+            onClose={close}
             footerExtra={
               canCopyConfig ? (
                 <CopyFromViewDoor
@@ -824,29 +851,71 @@ export default function Toolbar({
 
       <span className="cg-tb-divider" aria-hidden />
 
-      {/* Color — by status */}
-      <Popover label="Color" icon={<IconColor />} active={colorOn}>
-        {() => (
+      {/* ⭐⭐ W38-T07 (owner instruction 12) — THE ONE COLOUR CONTROL, PROMOTED TO A FIELD PICKER.
+          Owner: *"Under Map view, the 'Colour' dropdown duplicates the existing Color dropdown.
+          Use the existing one."* Map view mounted a second colour picker beside the mode switcher,
+          so one question had two controls on one screen and neither could see the other's answer.
+          This is the survivor; `viewModes.tsx`'s map-only picker is deleted in the same change.
+
+          ⛔⛔ ONE PICKER, TWO UNCHANGED CONSUMERS — the merge is of the CONTROL, never of the
+          PALETTES, and that distinction is the whole safety of this ticket. The two renderers are
+          structurally different engines:
+            · the GRID is identity-keyed — `theme.ts::STATUS_ROW_THEME` maps a lowercased status
+              value to a hand-tuned rgba wash (`reactivated` deliberately reuses `growing`'s hue
+              louder, `dormant` is deliberately near-invisible, and the alpha blend is
+              load-bearing because it TINTS the row rather than replacing it);
+            · the MAP is order-keyed — `MapView.tsx::SERIES` hands out 8 opaque fill/line pairs by
+              FIRST-SEEN ORDER in the current filtered row set, with an overflow colour after that.
+          Driving the grid off `SERIES` would make a status's colour depend on sort and filter
+          order and would hard-replace the wash instead of tinting it. So each renderer keeps its
+          own palette and this control only says WHICH COLUMN. `theme.ts` needing no edit is the
+          proof the merge stayed safe.
+
+          ⚠ RADIO ROWS, not a nested `FieldSelectButton`: "Group by" three blocks up asks this same
+          "which column?" question over a WIDER field set with exactly this markup, so the strip
+          already has an idiom for it, and a picker nested inside this popover would cost a second
+          open on a list this short. A stale key cannot reach here either — `cleanConfig` drops an
+          unknown `colorBy` on read and the field-delete paths null it — so the `is-missing` slot
+          that would have been the picker's one advantage has nothing to show. */}
+      <Popover label={colorLabel} icon={<IconColor />} active={!!colorField}>
+        {(close) => (
           <div className="cg-pop-body">
-            <div className="cg-pop-title">Color</div>
+            <div className="cg-pop-title">Color by</div>
             <label className="cg-radio-row">
               <input
                 type="radio"
                 name="cg-color"
-                checked={!colorOn}
-                onChange={() => onToggleColor(false)}
+                checked={!colorField}
+                onChange={() => {
+                  onColorField("");
+                  close();
+                }}
               />
               <span>No color</span>
             </label>
-            <label className="cg-radio-row">
-              <input
-                type="radio"
-                name="cg-color"
-                checked={colorOn}
-                onChange={() => onToggleColor(true)}
-              />
-              <span>Color by status</span>
-            </label>
+            {colorChoices.map((f) => (
+              <label key={f.key} className="cg-radio-row">
+                <input
+                  type="radio"
+                  name="cg-color"
+                  checked={colorField === f.key}
+                  onChange={() => {
+                    onColorField(f.key);
+                    close();
+                  }}
+                />
+                {/* The same type mark every other field list in this strip wears. */}
+                <FieldTypeIcon type={f.type} title={TYPE_LABELS[f.type]} />
+                <span>{f.label}</span>
+              </label>
+            ))}
+            {colorChoices.length === 0 && (
+              // Say why the list is short rather than showing a lone "No color" row that reads
+              // as a broken control.
+              <div className="cg-pop-note">
+                This table has no status or single select column to color by.
+              </div>
+            )}
           </div>
         )}
       </Popover>

web/src/customer-grid/mapProjection.ts

@@ -226,6 +226,35 @@ export function paintedStroke(basePx: number, k: number): number {
   return hairline(basePx, k) * k;
 }
 
+/**
+ * The bump `MapView.tsx`'s pin `<circle>` applies to the hovered pin's radius attribute. Exported rather than
+ * re-typed in the gate, because the number the sweep bounds must be the number the renderer is
+ * actually asked for: a mirrored `1.28` that drifts turns the ceiling leg into a leg about a
+ * constant that no longer exists.
+ */
+export const PIN_HOVER_SCALE = 1.28;
+
+/**
+ * What the renderer actually paints, in screen units, for a PIN RADIUS at zoom k. The radius twin
+ * of `paintedStroke`, and it exists because the map has exactly two size channels and only one of
+ * them was ever gated.
+ *
+ * `MapView.tsx`'s pin `<circle>` writes `r={radius(p) / view.k}`, bumps it by `PIN_HOVER_SCALE` while hovered
+ * (`:1460`), and paints it inside `<g transform="… scale(view.k)">`. This models that whole
+ * pipeline: pre-divide, hover bump, then the group's scale. It must return `baseR` (times the bump)
+ * at EVERY k, and `zoomLimits` gives the gate the real range to sweep.
+ *
+ * ⛔ NOT CIRCULAR, and W38-T08 is why the distinction earns its paragraph. `reference/ERROR 7.png`
+ * shows a 411 CSS px disc on the map and the ticket reasonably assumed a pin had grown into it. A
+ * pin cannot: this expression is size-invariant BY CONSTRUCTION. The sweep in `map.test.ts` is what
+ * turns that sentence from an assertion into a measurement, and it bites the way the wave-9 stroke
+ * bug bit: delete the `/ k` and the invariant holds at exactly one zoom, which is exactly how many
+ * zooms a screenshot shows.
+ */
+export function paintedRadius(baseR: number, k: number, hovered = false): number {
+  return hairline(baseR, k) * (hovered ? PIN_HOVER_SCALE : 1) * k;
+}
+
 /**
  * The CSS half of the same invariant: any `.cg-map*` rule that declares
  * `vector-effect: non-scaling-stroke` is double-compensating against
@@ -458,6 +487,118 @@ export function planRoute(
   return { order, km: tourLength(order, stops, dist, roundTrip) };
 }
 
+// ------------------------------------------- the order as a value, per record
+//
+// ⛔⛔ W38-T20 / AMENDMENTS A25 + A44 — THE PERMUTATION IS NOT THE RANK, AND THE
+// DIFFERENCE IS INVISIBLE IN THE OUTPUT.
+//
+// `planRoute` answers `order`, where `order[i]` is WHICH STOP is visited i-th.
+// A COLUMN on the record answers the other question: for THIS record, what
+// number does the rep see on their sheet. That is the INVERSE permutation, and
+// writing one where the other belongs produces a fully populated, entirely
+// plausible, completely wrong column — every row carries a number, the numbers
+// are 1..N with no repeats, and every one of them is somebody else's.
+//
+// ⛔ AND MOST FIXTURES CANNOT TELL THEM APART. `planRoute` pins `order[0] ===
+// start`, so a permutation and its inverse AGREE on the first element by
+// construction. Enumerated over every start-pinned permutation: at n = 3 the
+// two are IDENTICAL for 100% of them — a three-stop fixture can never catch
+// this — at n = 4 for 66%, at n = 5 for 41%. `ROUTE_WAYPOINTS_MOBILE` is 3, so
+// a test written at the mobile cap sits in the blind case by construction. The
+// gate's fixture is `[0, 2, 3, 1]`: ranks `[1, 4, 2, 3]`, the bug `[1, 3, 4, 2]`.
+
+/**
+ * `ranks[stopIndex]` = the 1-based position of that stop on the route, or
+ * `null` for a stop the tour never reached.
+ *
+ * ⛔ `null` AND NEVER `0`. `nearestNeighbourOrder` breaks out when no unvisited
+ * stop is reachable, so `order` may be SHORTER than the stop list, and a `0` in
+ * an integer column reads as a real visit number that sorts to the front. An
+ * unvisited stop has no number; the honest spelling of that is an empty cell.
+ *
+ * ⚠ Defensive on the way in for one reason only: this feeds a column that other
+ * people plan a day from. A repeated or out-of-range index in `order` would
+ * otherwise silently overwrite one record's rank with another's, so the FIRST
+ * occurrence wins and anything off the end is ignored.
+ */
+export function routeRanks(order: number[], stopCount: number): (number | null)[] {
+  const n = Math.max(0, Math.floor(stopCount) || 0);
+  const ranks = new Array<number | null>(n).fill(null);
+  let seat = 0;
+  for (const raw of order || []) {
+    const i = Math.floor(raw);
+    if (!Number.isInteger(i) || i < 0 || i >= n) continue;
+    if (ranks[i] != null) continue;
+    seat += 1;
+    ranks[i] = seat;
+  }
+  return ranks;
+}
+
+/** A stop as the ORDER COLUMN sees it: a record id and where that record is. */
+export interface RouteStamp {
+  pid: number;
+  lat: number;
+  lon: number;
+}
+
+/**
+ * The identity of the INPUTS an order was solved from.
+ *
+ * ⭐⭐ STALENESS IS DERIVED, NEVER STORED, and this is the half that gets stored
+ * so the derivation is possible. `core/user_tables.py` states the law for the AI
+ * columns in the same words: what is written down is the input fingerprint the
+ * value was produced FROM, so "is this stale" is a question asked at READ time
+ * and can never itself be out of date. A stored `stale: true` is a fact about a
+ * moment that has already passed.
+ *
+ * It answers exactly one question: would solving again, over what is on screen
+ * NOW, give different numbers? So it covers everything that decides them —
+ * which records are in the cohort, where each one is, whether the day returns to
+ * its origin, which stop it starts from, and any hand-picked order laid over the
+ * planner's. It deliberately does NOT cover the zoom, the selection colour or
+ * anything else a render can change.
+ *
+ * ⚠ CANONICALISED, or it reads STALE on every render for no reason: the stops
+ * are sorted by `pid` (the on-screen list is sorted by pid, but a caller's is not
+ * promised to be) and coordinates go through `toFixed(6)` — the same precision
+ * `googleMapsUrl` and `googleRouteUrl` already hand to Google, so this borrows a
+ * house constant rather than inventing a tolerance.
+ */
+export function routeFingerprint(
+  stops: RouteStamp[],
+  opts: { roundTrip?: boolean; startPid?: number | null; handOrder?: number[] | null } = {}
+): string {
+  const rows = (stops || [])
+    .map((s) => `${Math.trunc(s.pid)}@${s.lat.toFixed(6)},${s.lon.toFixed(6)}`)
+    .sort();
+  const canon = [
+    rows.join(";"),
+    opts.roundTrip ? "rt" : "open",
+    `s:${opts.startPid == null ? "auto" : Math.trunc(opts.startPid)}`,
+    `h:${(opts.handOrder || []).map((p) => Math.trunc(p)).join(",")}`,
+  ].join("|");
+  return `${_fnv1a(canon, 0x811c9dc5)}${_fnv1a(canon, 0x01000193)}`;
+}
+
+/**
+ * FNV-1a, 32 bits, as unpadded hex. Called TWICE with different offset bases and
+ * the two halves concatenated, which is the whole reason it takes one: a single
+ * 32-bit digest collides at roughly one pair in 65,536 by the birthday bound,
+ * and this decides whether a rep is told their route is out of date. Two
+ * independent bases put that past 2^-50, which is not a security claim and does
+ * not need to be — a collision here shows a stale column as current, and the
+ * user can still re-solve.
+ */
+function _fnv1a(text: string, base: number): string {
+  let h = base >>> 0;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
 // --------------------------------------------------- handing the route over
 //
 // MEASURED 2026-07-29, do not re-derive: Google Maps URLs need NO API key and

web/src/customer-grid/viewModes.tsx

@@ -96,8 +96,6 @@ export function ModeSwitch({
   coordField,
   coordChoices = [],
   onPickCoordField,
-  colorField,
-  colorChoices,
   sizeField,
   sizeChoices,
   onPickField,
@@ -124,11 +122,13 @@ export function ModeSwitch({
   /** The kanban's effective stack field (resolved by the caller). */
   stackField?: Field;
   stackChoices: Field[];
-  /** Wave-8 I3/I5 — the map's encodings, resolved by the caller from the VIEW
+  /** Wave-8 I3/I5 — the map's SIZE encoding, resolved by the caller from the VIEW
    *  DEF exactly like the two above (never from component state that dies on
-   *  unmount). Both are optional encodings, so both offer a "no encoding" row —
-   *  which is why their `<select>`s carry an explicit empty option instead of
-   *  relying on a first option, the wave-7 trap. */
+   *  unmount). It is an optional encoding, so it offers a "no encoding" row —
+   *  which is why its picker carries an explicit empty option instead of
+   *  relying on a first option, the wave-7 trap.
+   *  ⚠ This said "the map's encodingS", plural, while colour was its twin. W38-T07 moved colour
+   *  to the toolbar's one Color control, so size is the only encoding this component still owns. */
   /**
    * W37-T34 — WHICH COLUMN CARRIES THE LOCATION, resolved by the caller from the view def like
    * every field above it. Its cell holds `"lat,lon"` (contract C7).
@@ -150,11 +150,18 @@ export function ModeSwitch({
    * nothing. The mounted-but-inert defect is unreachable here rather than merely unlikely.
    */
   onPickCoordField?: (key: string) => void;
-  colorField?: Field;
-  colorChoices: Field[];
+  /** ⭐ W38-T07 — `colorField`/`colorChoices` are GONE from this component, not merely unused: the
+   *  toolbar's Color popover is the one colour control now, so a prop here would be a second door
+   *  standing open for the next lane to mount a twin through. The map still reads its colour from
+   *  `display.colorField`; that key is written by the toolbar's picker. */
   sizeField?: Field;
   sizeChoices: Field[];
-  onPickField: (k: "dateField" | "stackField" | "colorField" | "sizeField", key: string) => void;
+  /** ⭐ W38-T07 — `"colorField"` LEFT THIS UNION, and dropping it is the point rather than tidying
+   *  up after the deleted picker: the mode bar must not be able to write a colour at all, so a
+   *  later lane that mounts a colour control here fails to COMPILE instead of shipping the twin
+   *  the owner just asked us to remove. The host's `setDisplayField` still accepts the wider set
+   *  (it is the general display-field writer) and stays assignable to this narrower prop. */
+  onPickField: (k: "dateField" | "stackField" | "sizeField", key: string) => void;
   /** Item 3 (C-DISP) — cards are clamped unless the view stored the literal `false`. */
   clamped?: boolean;
   /** `false` = opt out of the clamp; `undefined` = back to the default (the key comes OFF). */
@@ -428,12 +435,13 @@ export function ModeSwitch({
           )}
         </Popover>
       )}
-      {/* The map's two encodings are OPTIONAL, so "none" is a real choice and not merely the
+      {/* The map's SIZE encoding is OPTIONAL, so "none" is a real choice and not merely the
           absence of one: it is a row in the list AND the placeholder the button falls back to,
           which is the same state said twice on purpose — you can see what you would return to
-          before you pick it. The "Colour: " prefix lived on every option because a native
+          before you pick it. The "Size: " prefix lived on every option because a native
           select had nowhere else to say which encoding it was; the aria-label and the row
-          carry that now, so the labels are just the field names. */}
+          carry that now, so the labels are just the field names.
+          ⚠ This read "the map's two encodings" while colour was the other; W38-T07 left one. */}
       {/* W37-T34 — the LOCATION picker, and it is deliberately the FIRST of the map's three.
           Colour and size are encodings you can live without; this one decides whether there are
           any pins at all, so it reads left to right in the order the questions actually arrive.
@@ -455,23 +463,14 @@ export function ModeSwitch({
           ]}
         />
       )}
-      {mode === "map" && colorChoices.length > 0 && (
-        <FieldSelectButton
-          className="cg-mode-field"
-          ariaLabel="Colour pins by"
-          placeholder="Colour: none"
-          // `?? ""` on purpose: "" is the key of the explicit "No colour" row, so the none
-          // state MARKS itself in the list instead of leaving every row unmarked.
-          value={colorField?.key ?? ""}
-          onChange={(key) => onPickField("colorField", key)}
-          fields={[
-            { key: "", label: "No colour", type: undefined },
-            ...colorChoices.map((f) => ({
-              key: f.key, label: `Colour: ${f.label}`, type: f.type,
-            })),
-          ]}
-        />
-      )}
+      {/* ⭐⭐ W38-T07 (owner instruction 12) — THE MAP'S OWN COLOUR PICKER USED TO SIT HERE, and it
+          is deleted rather than moved. Owner: *"Under Map view, the 'Colour' dropdown duplicates
+          the existing Color dropdown. Use the existing one."* The toolbar's Color popover is "the
+          existing one"; it was two radios and is now a field picker, and it writes BOTH
+          `config.colorBy` (the grid's row wash) AND `display.colorField` (this map's pins), so the
+          map still gets its encoding from a control that no longer has a twin.
+          ⛔ THE SIZE PICKER BELOW IS NOT PART OF THIS. It has no duplicate anywhere in the strip
+          and the ticket's non-goal names it explicitly: "No size" stays, and it still sizes pins. */}
       {mode === "map" && sizeChoices.length > 0 && (
         <FieldSelectButton
           className="cg-mode-field"

web/src/filter-kit/FilterBuilderPanel.tsx

@@ -928,6 +928,18 @@ export interface FilterBuilderPanelProps {
    * serves an admin editor should know about.
    */
   footerExtra?: ReactNode;
+  /**
+   * W38-T02 (owner instruction 8) — close the panel from its own header.
+   *
+   * ⛔ OPTIONAL BY DESIGN, and the reason is the two call sites, not tidiness. The grid toolbar
+   * mounts this inside `filter-kit/Popover`, which already manufactures a closer and hands it to
+   * its children render-prop; that closer is what arrives here. The admin permission editor
+   * (`settings/ModulePermsList`) mounts the very same panel in a BARE `div` with no overlay
+   * ancestor at all, and already owns a different way out — its own "Hide detail" disclosure.
+   * Requiring this prop would force that surface to invent a second, competing closer. So the
+   * control paints only where a closer genuinely exists, and its absence is a statement.
+   */
+  onClose?: () => void;
 }
 
 export function FilterBuilderPanel({
@@ -941,6 +953,7 @@ export function FilterBuilderPanel({
   statusValues,
   cohortLock,
   footerExtra,
+  onClose,
 }: FilterBuilderPanelProps) {
   const nodes = filterTreeNodes(filters);
   const conj = filterTreeConj(filters);
@@ -977,7 +990,26 @@ export function FilterBuilderPanel({
 
   return (
     <div className="cg-pop-body cg-builder">
-      <div className="cg-pop-title">Filter</div>
+      {/* W38-T02 (owner instruction 8) — the panel's own header row: the label on the left, the
+          way out on the right. ⭐ This control is a PANEL control: it dismisses the popover and
+          leaves every condition standing exactly as it was. It is NOT one of the small remove
+          buttons the rows below carry, which paint the same glyph and mean the opposite thing —
+          the class and the label are the discriminator, never the character.
+          The row deliberately does not wear the column menu's head rule; see `.cg-pop-head` in
+          index.css for what borrowing that one would have done to this header. */}
+      <div className="cg-pop-head">
+        <div className="cg-pop-title">Filter</div>
+        {onClose && (
+          <button
+            type="button"
+            className="cg-icon-btn"
+            onClick={onClose}
+            aria-label="Close filter panel"
+          >
+            ×
+          </button>
+        )}
+      </div>
       {/* C-LOCK (item 12) — the lock is NOT a condition row: it cannot be written here and
           cannot be removed here (the view menu owns it). So it has to be SAID here, above
           the conditions it bounds — otherwise the count and the conditions disagree and the

web/src/index.css

@@ -278,7 +278,13 @@
    rail toggle cannot re-open the rail. That is the same trade `.shell-root:has(.cg-agent-panel)`
    already makes and its comment already argues — *a preference may decline a COURTESY fold; it may
    not decline a layout constraint*. Navigation survives because the strip keeps its icons; what is
-   lost is the labels, on a window where the alternative was a 312px canvas. */
+   lost is the labels, on a window where the alternative was a 312px canvas.
+   ⚠ W38-T05 — THE QUOTED MAXIM IS UNCHANGED; THE EVIDENCE UNDER IT IS NOT, so follow the pointer
+   before quoting it a third time. That comment used to ground the sentence in a decline that really
+   existed (`railHeldOpen`); W38-T04 deleted the ref, so it is grounded STRUCTURALLY now — the event
+   is a courtesy channel by construction, not a channel that happens to have a guard on it today.
+   This back-reference is why that comment had to be rewritten rather than merely corrected: a quote
+   outlives the sentence it was taken from, and the two must not drift. */
 @media (max-width: 1023px) {
   :root { --lp-rail-w: var(--lp-rail-min); }
   .shell-side .lp-wordmark,
@@ -762,6 +768,32 @@ body {
      without it a narrow viewport would re-create the same wrap inside the ceiling. */
   min-width: 186px;
   max-width: 260px;
+  /* ⭐ W38-T01 / owner item 16 (2026-08-20), "ERROR 8.png" — THE PANEL HAS TO BE A SCROLL BOX,
+     not merely a capped one. `OverlaySurface.tsx::AnchoredOverlay::updatePosition` stamps an
+     inline `maxHeight` on EVERY anchored panel (unconditionally, from
+     `overlayPlacement.ts::computeOverlayPosition`, where it is the space actually left above
+     or below the anchor in the VISUAL viewport). `max-height` with `overflow: visible` clamps
+     the BOX and nothing else: the white background, the border and the shadow all stop at the
+     cap while the remaining `role="menuitem"` buttons keep laying out below it, transparent,
+     over the view rail. That is exactly what the owner photographed at 150% zoom — the shadow
+     cuts clean across the Star / "Alert me about new records" seam, with five rows rendering
+     underneath it and no background at all. Zoom is what makes it bite: it shrinks
+     `visualViewport.height`, so the cap lands mid-menu instead of past its last item.
+     ⭐ ONE RULE, FOUR PANELS: `ViewSidebar.tsx` stamps this class on the create flyout (:1049),
+     the folder menu (:1720), the saved-view menu (:1943) and the export pane (:2286).
+     ⚠ `overscroll-behavior` is NOT precedent here — it appears nowhere else in this file. It is
+     the other half of the repair and not decoration: without it, a wheel that reaches the end
+     of a now-scrollable menu chains straight into the view rail underneath and scrolls the
+     list the menu is anchored to, out from under its own anchor.
+     Siblings that already carry the `overflow-y` half: `.cg-column-menu` (which belts it with a
+     CSS ceiling too) and `.cg-pop` (which, like this one, leans on the inline `maxHeight`).
+     No CSS `max-height` is added here on purpose — all four of these are AnchoredOverlays, so
+     the inline cap is always present, and a `100vh` ceiling would be a second, disagreeing
+     number. `overflow-x` is left implicit, matching both siblings: `placed.maxWidth` is the
+     whole viewport minus margins rather than a per-panel clamp, and every row is closed
+     vocabulary under `nowrap` with `.cg-mi-text`'s ellipsis as the backstop. */
+  overflow-y: auto;
+  overscroll-behavior: contain;
   padding: 4px;
   border: 1px solid var(--lp-line);
   border-radius: var(--lp-r-lg);
@@ -1386,6 +1418,34 @@ body > .cg-overlay {
   color: #8a8a96;
   padding: 4px 8px 6px;
 }
+/* W38-T02 (owner instruction 8) — the header ROW a popover panel wears when it carries a close
+   control beside its label. It lays the two children out and does NOTHING else.
+
+   ⛔ WHY THIS EXISTS INSTEAD OF REUSING `.cg-column-head`, which is the obvious candidate and is
+   where the button markup was copied from: that rule carries `min-height: 42px`, a
+   `border-bottom`, and `align-items: flex-start`. Borrowing it would have near-doubled the Filter
+   header's height and ruled a line under it — an unrequested restyle of the very header the owner
+   has already had an opinion about (see the item-11 note on `.cg-pop-title` above), smuggled in
+   under a ticket that asked only for a close button. No gate in this repo measures painted layout,
+   so that change would have shipped silently.
+
+   `.cg-pop-title` itself is untouched on purpose: it is shared with the view-note popover and the
+   view menu, both of which use it WITHOUT this row. The title keeps its own padding; the row adds
+   only the right-hand breathing space the button needs, so a panel with no close control paints
+   byte-identically to before. */
+.cg-pop-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 6px;
+  padding-right: 4px;
+}
+.cg-pop-head .cg-pop-title {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
 .cg-pop-list {
   max-height: 320px;
   overflow-y: auto;
@@ -3150,6 +3210,33 @@ body > .cg-overlay {
   align-items: center;
   min-width: 0;
 }
+/* ⭐⭐ WAVE 38 · T06 (owner instruction 1) — THE LOGO SITS LOWER WHILE THE RAIL IS MINIMIZED, and
+   it does so WITHOUT MOVING A SINGLE NODE. Owner: *"When the Navigation is minimized: … move the
+   logo downward."*
+   ⛔ WHY `:has()` AND NOT A JSX MOVE. `.shell-topbar` is a PRECEDING SIBLING of `.shell-frame`,
+   and `.shell-side` lives inside `.shell-frame` — so the brand's box is structurally invariant to
+   the fold and no descendant selector can reach it from the rail. CSS has no previous-sibling
+   combinator either. Physically relocating `.shell-topbar-brand` into `.shell-side` would have
+   worked, at the cost of emptying the one persistent strip that W35-T01's ruling R1 exists to
+   protect (and of reddening `verify_ui.py`'s `W35-T01 (C1)` leg, which asserts the strip carries
+   BOTH its toggle and its brand). `:has()` is already this stylesheet's vocabulary for exactly
+   this shape of reach — see `.shell-root:has(.cg-agent-panel) .shell-side` below — so the strip
+   keeps its contract and the brand still answers to the fold.
+   ⛔ `align-self`, NOT `transform: translateY()`. This band has no `overflow: hidden`, so a
+   transform large enough to be legible would paint the mark across the border and onto the grid
+   below. Bottom-alignment cannot overflow the band whatever the lockup's height turns out to be:
+   the mark is a 26px `<img>` in a 44px band today (9px of slack, so ~7px of travel), and if the
+   lockup ever grows the drop shrinks to nothing rather than spilling. The 2px keeps it off the
+   strip's own border.
+   ⚠ KEYED TO `.is-collapsed` ONLY, and the asymmetry is deliberate. Every fold rule further down
+   is doubled across `.is-collapsed` and `:has(.cg-agent-panel)` because both genuinely narrow the
+   rail. This one is not a fold rule: the owner asked for a logo that moves when THE USER minimises
+   the navigation, and it is gated on the same `navCollapsed` state its sibling launcher in
+   `Shell.tsx` is. A chat panel opening should not walk the brand down the strip. */
+.shell-root:has(.shell-side.is-collapsed) .shell-topbar-brand {
+  align-self: flex-end;
+  padding-bottom: 2px;
+}
 
 /* WHITE, like the host's `[theme.sidebar]` (owner 2026-07-23: "slick, visible
    light-grey borders") — the wash belongs to page bodies, not the rail.
@@ -3171,20 +3258,40 @@ body > .cg-overlay {
     flex-basis var(--lp-fold-t) var(--lp-fold-e);
 }
 
-/* ⭐ WAVE 35 · T02 — WHAT THIS BAND IS NOW. It held the brand and the minimize control; both live
-   in `.shell-topbar` (C1). It survives, empty, ONLY as an alignment band: the content pane's first
-   band is one `--lp-rail-head-h` tall, so removing it would raise the rail's first nav row a header
-   above the grid beside it on every database page. Same height, same hairline, no contents —
-   `justify-content` and the fold `transition` went with the children they positioned.
-   ⚠ W36-T51 (owner item 7) — THE BAND IT ALIGNS WITH IS NOW `.cg-views-top` ALONE. This sentence
-   used to read "`DbHead` and `.cg-views-top` are each one ... tall", and `DbHead` is deleted from
-   the database surface. The alignment is unchanged because the views rail still opens on a head of
-   the same height; what WOULD orphan this element is that head going, not the title. */
-.shell-side-head {
-  flex: 0 0 var(--lp-rail-head-h);
-  height: var(--lp-rail-head-h);
-  border-bottom: 1px solid var(--lp-line);
-}
+/* ⛔⛔ WAVE 38 · T05 (owner instruction 2) — `.shell-side-head` IS DELETED, RULE AND ELEMENT BOTH.
+   Owner: *"Move the 'Home' button into the empty space above it, and every other module button
+   upward, so there is no awkward gap."* The gap WAS this rule — an empty band reserving
+   `--lp-rail-head-h` at the top of the rail, so `<nav>` and Home with it opened a full header below
+   the top strip. The rule is gone, so `<nav>` is now `.shell-side`'s first child.
+
+   ⛔ WHAT THE OLD COMMENT ARGUED, AND WHY IT NO LONGER WINS — this was a decision, not a tidy-up.
+   It said the band aligned the rail's first nav row with the content pane's own first band, so that
+   `.shell-side-head`, `.cg-views-top` and `.cg-toolbar` were three segments of ONE horizontal line
+   (item 5 of wave 35). That was true. Two things settle it against the band anyway: the owner asked
+   for exactly the row this element prevented, and — measured, not assumed — `.cg-views-top` mounts
+   ONLY in `customer-grid/ViewSidebar.tsx` and `.auto-rail-top` ONLY in
+   `automation/AutomationSurface.tsx`. On Home, Starred, Inbox and Connectors there is no second
+   band anywhere on the page, so this one was an empty box closed by a hairline that stopped at the
+   rail's own right edge, aligned with nothing. It was an artifact on the landing page the owner
+   opens on, and a stub on most of the rest.
+
+   ⚠ THE COST, NAMED RATHER THAN ARGUED AWAY: on a grid surface and on Agents, that SECOND
+   horizontal line no longer crosses the left rail — it now begins at the views rail. The FIRST line
+   is untouched, which is why the loss is bounded: `.shell-topbar` is a full-width sibling of
+   `.shell-frame` and its own `border-bottom` still runs edge to edge above all three rails.
+
+   ⛔ COLLAPSING IT TO THE HAIRLINE (`height: 0`, border kept) WAS THE OTHER CANDIDATE, AND IT IS
+   STRICTLY WORSE RATHER THAN A MILDER VERSION OF THIS — work the geometry before reaching for it.
+   A zero-height band paints its `border-bottom` at the rail's TOP, 1px under `.shell-topbar`'s own
+   border: two adjacent hairlines, a doubled line across the rail's width while the rest of the app
+   draws 1px. And it does NOT buy back the line one head lower, because there is no longer a band
+   reaching down to that y. So it breaks the continuity in exactly the place removal does and adds a
+   visible defect on top. It is removal plus a bug, not a compromise.
+
+   ⚠ `.cg-views-top` IS DELIBERATELY UNTOUCHED, above at its own rule. It still opens flush under
+   the top strip on `--lp-rail-head-h`, which is the no-change condition this instruction carried.
+   Realigning the two rails was never on the table: they share the identical token, so any edit that
+   raised Home to the views rail's CONTENT would have had to move `.cg-views-top` too. */
 /* ⛔⛔ DELETED WITH T02, AND THIS NOTE IS THE POINT OF THE DELETION: `.shell-rail-toggle` (its base,
    hover and focus rules) and `.shell-side.is-collapsed .shell-rail-toggle { display: none }`.
    That last rule is what made wave-20 R9 necessary — the toggle vanished when collapsed, so the
@@ -3205,9 +3312,18 @@ body > .cg-overlay {
    the folded LOOK, because every rule below simply takes a second selector. `:has()` is already in
    this file's supported set (`.shell-nav-item:has(.shell-nav-badge)`).
    ⛔ AND IT DELIBERATELY DOES NOT RIDE `NAV_MINIMIZE_EVENT`, WHICH IS THE OBVIOUS AND WRONG CHANNEL.
-   `Shell.tsx`'s listener declines that signal whenever `railHeldOpen` is up (W34-T12/R1 — "an expand
-   has to survive the next click"), so a user who had once clicked the logo open would get the 187px
-   grid anyway. A preference may decline a COURTESY fold; it may not decline a layout constraint.
+   A preference may decline a COURTESY fold; it may not decline a layout constraint.
+   ⚠ W38-T05 — THE EVIDENCE FOR THAT SENTENCE CHANGED; THE SENTENCE DID NOT. It used to continue
+   that `Shell.tsx`'s listener declines the signal whenever `railHeldOpen` is up (W34-T12/R1, "an
+   expand has to survive the next click"), so a user who had once clicked the logo open would get the
+   187px grid anyway. W38-T04 revoked R1 and deleted `railHeldOpen` outright: that listener now folds
+   unconditionally and there is nothing left to decline anything, so the old clause was simply false.
+   ⛔ THE RULE BELOW IS UNAFFECTED AND STAYS — read why before "simplifying" it onto the event. The
+   argument was never that a decline exists today; it is that `NAV_MINIMIZE_EVENT` is a COURTESY
+   channel by construction. Every wave that has touched that handler has reached for a guard in front
+   of it, and `verify_ui.py`'s `W38-T04 unconditional` leg exists precisely because the next one will
+   too. A layout constraint routed through it would be one edit away from being declinable again.
+   `:has()` cannot be declined by anything, which is the whole reason it is the channel here.
    ⚠ WHICH IS ALSO WHY `.shell-side.is-collapsed { cursor: pointer }` FURTHER DOWN IS THE ONE FOLD
    RULE NOT EXTENDED HERE: a rail folded by the panel must not offer a click that would re-open it
    into the space the panel is standing in. The user's own fold keeps its way back; this one has no
@@ -3296,6 +3412,38 @@ body > .cg-overlay {
   gap: 0;
 }
 
+/* ⭐⭐ WAVE 38 · T06 (owner instruction 1) — THE MINIMISED RAIL'S CHAT LAUNCHER. Owner: *"When the
+   Navigation is minimized: the icon that opens the AI chatbot overlay with the grid…"*
+   ⛔ IT IS DELIBERATELY NOT A `.shell-nav-item`, and that is a gate fact rather than a taste one.
+   TWO gates derive their subject from the rail instead of listing it: `verify_ui.py`'s
+   `nav_row_classes` treats every class worn in the same `className` literal as `shell-nav-item`
+   as a ROW and forbids it its own type declaration, and `verify_wiring.py`'s `_ROW_LITERAL` scan
+   reads the same literals to work out each row's loading state. This control is neither a
+   destination nor a row: it exists in one state only, it never carries a label, and enrolling it
+   in a rail-row roster would make both gates answer questions about it that have no meaning.
+   ⚠ NO MARGIN AND NO WIDTH, and that is measured rather than styled. This control is a CHILD of
+   `.shell-nav`, so the collapsed rail's 6px gutter is already `.shell-nav`'s own `padding: 8px 6px
+   0`; `padding: 7px 10px` then lands the 16px glyph at x = 6 + 10 = 16 = (48-16)/2, the strip's
+   centre and the exact x every `.shell-nav-item` icon takes (the geometry note on the fold rules
+   above states that sum). The first draft copied `.shell-nav-templates`' `margin: 0 6px` and would
+   have sat 6px right of every other icon: that row is a SIBLING of `.shell-nav` and has to supply
+   its own gutter, which is precisely the difference. Height, radius and hover are the rail row's,
+   so the column reads as one column whatever tag each control happens to be. */
+.shell-rail-chat {
+  display: flex;
+  align-items: center;
+  margin: 0 0 2px;
+  padding: 7px 10px;
+  min-height: 34px;
+  border: 0;
+  border-radius: var(--lp-r-sm);
+  background: transparent;
+  color: var(--lp-ink);
+  cursor: pointer;
+}
+.shell-rail-chat:hover { background: var(--lp-surface-2); }
+.shell-rail-chat:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
+
 /* ⭐ WAVE 35 · T02 — `.shell-brand-btn` IS DELETED, and it is the wave-20 R9 decision being
    retired rather than a style being tidied. The brand was a `<button>` at all only so it could be
    the way back from a collapsed rail; it is a plain `<div class="shell-topbar-brand">` in the top

web/src/settings/ModulePermsList.tsx

@@ -42,6 +42,18 @@ export interface ModulePermsListProps {
   onFilter: (key: string, next: FilterTree | null) => void;
   onToggleHidden: (key: string, fieldKey: string) => void;
   onSetHidden: (key: string, keys: string[]) => void;
+  /**
+   * ⭐⭐ W38-T19 — the per-database METRICS capability. Absent means the caller does not govern
+   * it and no box is drawn, which is the account editor's and the agent editor's genuine
+   * difference rather than a stub: an agent's reads run through `agent_rows` / `agent_may_read`
+   * and never open a grid door, so a Metrics toggle in that room would be a stored rule nothing
+   * applies, the exact class W36's contract C2 deleted.
+   *
+   * ⛔ OPTIONAL, AND FORCED RATHER THAN CHOSEN. `manage-agent/ManageAgentPane.tsx` mounts this
+   * same component and is outside W38-T19's fence; a required prop stops it compiling, which
+   * reds `web_ui` on a build break in a file that ticket may not repair.
+   */
+  onMetrics?: (key: string, on: boolean) => 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…"
@@ -58,6 +70,7 @@ export function ModulePermsList({
   onFilter,
   onToggleHidden,
   onSetHidden,
+  onMetrics,
   userOptions,
   headExtra,
   emptyNote,
@@ -129,6 +142,29 @@ export function ModulePermsList({
               </span>
             </div>
 
+            {/* ⭐⭐ W38-T19 — THE METRICS CAPABILITY, one box per database.
+                ⛔ GATED ON `on && !schemaless` FOR TWO DIFFERENT REASONS, not one.
+                `on`: a capability inside a database nobody may open is a control
+                that decides nothing, and the row already says "No access".
+                `!schemaless`: an app SURFACE has no grid and therefore no measure
+                door, so a box there would store a rule nothing reads — R9's rule
+                that this editor never writes a restriction it could not honestly
+                show, applied to a capability instead of to a filter.
+                ⚠ It sits OUTSIDE `.set-perm-headend` deliberately. That rule is
+                `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 ? (
+              <label className="set-check">
+                <input
+                  type="checkbox"
+                  checked={entry?.metrics !== false}
+                  onChange={(e) => onMetrics(m.key, e.target.checked)}
+                />
+                <span>Metric fields (lookback measures over this database)</span>
+              </label>
+            ) : null}
+
             {/* R9's fail-closed rendering: no readable schema means the access
                 toggle and nothing else. The record it saves says the same thing —
                 no filter, no hidden fields — so the editor and the payload cannot

web/src/settings/permsModel.ts

@@ -167,6 +167,28 @@ export interface PermsEntry {
   filter: FilterTree | null;
   /** Field keys this account never receives. Server-stripped from every wire. */
   hiddenFields: string[];
+  /**
+   * ⭐⭐ W38-T19 — MAY THIS ACCOUNT BUILD AND RECEIVE **METRIC** COLUMNS on this database?
+   * `false` empties the measure offer at every grid door, which takes the Metric kind off the
+   * field picker AND fail-closes a create with `measure_not_offered`.
+   *
+   * ⛔ OPTIONAL, AND THE CHOICE WAS **FORCED** RATHER THAN PREFERRED. Required is the loud
+   * option and it is the one this file would otherwise take: `tsc` would then name every
+   * `PermsEntry`-shaped literal that forgot the key. But `web/verify_login.py` compiles
+   * `src/shell/_test/shell.test.ts` in the same `npx tsc` call as this file's own suite, and
+   * that file passes a bare `{access, filter, hiddenFields}` literal straight into
+   * `moduleSummary(entry: PermsEntry | undefined)`. A required key reds `web_login` at COMPILE
+   * time ("tsc emitted nothing") in a file W38-T19's fence does not contain, with no legal
+   * repair. Optional is what the fence permits.
+   *
+   * ⚠ SO THE DEFAULT IS CENTRALISED INSTEAD, IN EXACTLY TWO PLACES, and both spell it the same
+   * way: `parseEntry` reads the wire (`metrics: r.metrics !== false`) and `toPutBody` writes it
+   * (`metrics: e.metrics !== false`). Absence GRANTS at both ends, matching
+   * `perm_scope.may_metrics` and `_clean_perms` on the server, so a record written before this
+   * key existed reads as unrestricted rather than as a silent mass revocation. Every literal
+   * that omits the key therefore means the one thing it could safely mean.
+   */
+  metrics?: boolean;
 }
 
 export type PermsRecord = Record<string, PermsEntry>;
@@ -355,6 +377,14 @@ export function parseEntry(raw: unknown): PermsEntry {
     access: r.access === true,
     filter: parseFilter(r.filter),
     hiddenFields: normalizeHidden(asStringArray(r.hiddenFields)),
+    // ⭐⭐ W38-T19 — `!== false`, NOT `=== true`, AND THE TWO ARE OPPOSITE HERE. `access` reads
+    // absence as DENY because a migrated record declares every governed database, so a missing
+    // `access` is a decision. No `metrics` key was STORABLE before this ticket, so EVERY record
+    // in every tenant is missing one: reading absence as deny would paint the box unticked for
+    // every account on the day this shipped, and the next save of any unrelated change would
+    // write that revocation for real. The server's `may_metrics` and `_clean_perms` default the
+    // same direction, so the editor shows what the wall will actually do.
+    metrics: r.metrics !== false,
   };
 }
 
@@ -468,6 +498,12 @@ export function setFilter(rec: PermsRecord, key: string, filter: FilterTree | nu
   return withEntry(rec, key, { filter: empty ? null : filter });
 }
 
+/** ⭐⭐ W38-T19 — the Metrics capability toggle. A plain `withEntry` patch like every other
+ *  setter, so the draft stays immutable and `isDirty` sees the change through `toPutBody`. */
+export function setMetrics(rec: PermsRecord, key: string, metrics: boolean): PermsRecord {
+  return withEntry(rec, key, { metrics });
+}
+
 export function setHidden(rec: PermsRecord, key: string, hidden: readonly string[]): PermsRecord {
   return withEntry(rec, key, { hiddenFields: normalizeHidden(hidden) });
 }
@@ -526,7 +562,23 @@ export function toPutBody(payload: PermsPayload, rec: PermsRecord): { perms: Per
           access: e.access,
           filter: e.filter,
           hiddenFields: normalizeHidden(e.hiddenFields.filter((k) => k !== locked)),
+          // ⭐⭐ W38-T19 — ALWAYS EMITTED, never left to the server's default. A PUT is a
+          // whole-record replace and this editor is the last thing the record passes through,
+          // so a key it withholds is a key whose meaning is decided somewhere else. Emitting it
+          // is also what keeps `isDirty` honest: that function compares the SENT SHAPE, and a
+          // capability the payload never carries could be toggled all day without lighting Save.
+          metrics: e.metrics !== false,
         }
+      // ⭐⭐ W38-T19 — THE SCHEMA-LESS ARM EMITS **NO** `metrics` KEY, and the omission is the
+      // rule rather than an oversight. R9: access is the WHOLE rule for a module with no
+      // readable schema. An Assistant or Agents row has no grid and therefore no measure door,
+      // this editor renders no Metrics box for it, and a whole-record COPY is the one path that
+      // could otherwise carry a revocation onto it — a restriction the admin was never shown.
+      // ⚠ ABSENT IS NOT UNDECIDED HERE, IT IS GRANTED, and it resolves in exactly one place:
+      // `_clean_perms` stores `bool(raw.get("metrics", True))`, so an omitted key persists as
+      // `true`. Sending `true` explicitly would be the same value by a longer road, and it
+      // would break `shell/_test/shell.test.ts`'s "a schema-less module saves access only" —
+      // a leg whose CLAIM is right and which this file must not make false.
       : { access: e.access, filter: null, hiddenFields: [] };
   }
   return { perms };
@@ -643,10 +695,16 @@ export function moduleSummary(entry: PermsEntry | undefined, schemaless = false)
   if (schemaless) return "Full access";
   const conds = countLeaves(entry.filter);
   const hidden = entry.hiddenFields.length;
-  if (!conds && !hidden) return "Full access";
+  // ⭐⭐ W38-T19 — A REVOKED CAPABILITY IS A RESTRICTION AND THE COLLAPSED ROW HAS TO SAY SO.
+  // The whole point of this sentence is that an admin can read a database's rule without
+  // opening it; a row reading "Full access" over an account that cannot build a Metric column
+  // is the summary lying, which is the failure mode this function's own header is about.
+  const noMetrics = entry.metrics === false;
+  if (!conds && !hidden && !noMetrics) return "Full access";
   const parts: string[] = [];
   if (conds) parts.push(`${conds} condition${conds === 1 ? "" : "s"}`);
   if (hidden) parts.push(`${hidden} field${hidden === 1 ? "" : "s"} hidden`);
+  if (noMetrics) parts.push("Metrics off");
   return parts.join(", ");
 }
 

web/src/shell/Shell.tsx

@@ -235,6 +235,29 @@ const NAV_DRAG_TYPE = "application/x-loopable-nav";
 /** A stable identity for "no nav yet" — see its use below. */
 const NO_ENTRIES: NavEntry[] = [];
 
+/**
+ * ⭐⭐ WAVE 38 · T06 (owner instruction 1) — THE SHELL→GRID CHANNEL FOR "open the chat".
+ *
+ * The frame owns the minimised rail; `CustomerGrid` owns `chatOpen` and mounts `<GridChat>`. So
+ * the launcher does what every other cross-fence click-through in this frame does: it raises a
+ * window event and the surface answers if it can, exactly as `VIEW_OPEN_EVENT` and
+ * `AUTOMATION_OPEN_EVENT` already do. Nothing here learns the grid's state, which is the point:
+ * the shell cannot know whether a chat is already open, so this signal OPENS and never toggles.
+ *
+ * ⛔⛔ THE STRING IS TYPED TWICE, AND THAT IS A CONSTRAINT, NOT A PREFERENCE. Its natural home is
+ * `apiContract.ts` beside the other four signals — the host-neutral leaf both trees already
+ * import — and that file is outside this ticket's `files:` list. The two legal alternatives are
+ * both worse: `customer-grid/**` may not import `shell/**` (it is host-neutral by its own rule,
+ * which is what lets the grid run inside another host), and a STATIC import of a constant out of
+ * `CustomerGrid.tsx` would drag the whole spreadsheet engine into the shell's entry chunk, undoing
+ * the `lazy()` at :60 that keeps it out. So the canonical declaration is
+ * `CustomerGrid.tsx::GRID_CHAT_OPEN_EVENT`, this is its twin, and the divergence they invite is
+ * closed by a control rather than by a comment: `verify_wiring.py`'s W38-T06 row matches the
+ * LITERAL `aios:grid-chat-open` on both sides, so a typo in either spelling reds `web_wiring`.
+ * ⚠ Move both to `apiContract.ts` the next time a ticket owns that file. See PENDING.
+ */
+const GRID_CHAT_OPEN_EVENT = "aios:grid-chat-open";
+
 /**
  * WAVE 23 C10 — the Database flyout's anchor, CLAMPED to the viewport.
  *
@@ -1102,37 +1125,33 @@ function ShellFrame() {
       // storage can be blocked; the toggle still works for the session
     }
   }, [navCollapsed]);
-  // ── ⭐⭐ W34-T12 (ruling R1): AN EXPAND HAS TO SURVIVE THE NEXT CLICK ──────────────────────
-  //
-  // R1: *"Fix the navigation error where minimizing gets stuck and cannot be reopened."*
+  // ── ⭐⭐ W38-T04 (ruling R9): A CELL CLICK ALWAYS FOLDS THE RAIL ───────────────────────────
   //
-  // ⛔ THE CAUSE IS NOT A MISSING CONTROL, AND THAT WAS WORTH PROVING BEFORE CHANGING ANYTHING
-  // (`proto/nav-stuck/README.md` records the trace). Every one of the six `setNavCollapsed` call
-  // sites was read; the brand button below is rendered unconditionally, is enabled exactly when
-  // the rail is collapsed, and no `.is-collapsed` rule hides it. There is no state with no way
-  // back. What there is: `NAV_MINIMIZE_EVENT` fires from `CustomerGrid` on EVERY cell click and
-  // EVERY view switch, unconditionally and undebounced (owner item 10, 2026-07-31 — "I am working
-  // now"), and the listener always SETS. So the user clicks the logo, the rail opens, they touch
-  // one cell, and it shuts again. The control works; its EFFECT never survives. From the seat that
-  // is "cannot be reopened", and no gate can see it because the code does exactly what it was
-  // asked to do in July.
+  // ⛔ WAVE 34's R1 IS REVOKED. That ruling read owner item 10's fold as a COURTESY a deliberate
+  // expand was allowed to decline, and this block used to hold a `railHeldOpen` ref that every
+  // expand raised, the explicit fold lowered, and the automatic fold consulted before it set.
+  // Wave 38 item 3 overrules it, verbatim: *"Clicking any cell must minimize the main navigation.
+  // This was the previous behavior; make sure it is fixed forever."* R9 reads "fixed forever"
+  // LITERALLY — no held-open state, no preference, no ref may decline the fold, because anything
+  // able to decline it is a way for the behaviour to stop being fixed.
   //
-  // ⚠ SO KEEP THE FOLD AND MAKE THE EXPAND STICK, rather than revoking owner item 10. This ref is
-  // raised by every DELIBERATE expand and lowered by the explicit Minimize button; the automatic
-  // fold declines while it is up.
+  // ⛔ THE REF WAS DELETED, NOT LEFT INERT, and that is the deliberate half of this edit. A
+  // `railHeldOpen` that every expand still raised while nothing read it would compile clean — it
+  // is WRITTEN, so no unused-local diagnostic ever sees it — and would read to the next person as
+  // a live rule with a missing consumer, which is an invitation to "repair" the decline back in.
+  // A revoked ruling leaves no residue. (`proto/nav-stuck/README.md` keeps R1's original trace;
+  // its finding — that no expand CONTROL was ever missing — is still true and still worth having.)
   //
-  // ⛔ NOT PERSISTED, DELIBERATELY. `navCollapsed` rides localStorage; this does not. Persisting it
-  // would retire owner item 10 permanently the first time anybody clicked the logo — a ruling
-  // revoked by a preference. A reload starts it down, so the first fold still happens per visit.
-  const railHeldOpen = useRef(false);
-  /** Every deliberate expand goes through here, so a fifth expand door cannot forget the flag. */
+  // ⚠ WHAT SURVIVES R1 IS THE ONE-DOOR SHAPE, and `verify_ui.py` still enforces it: every expand
+  // goes through `expandRail`, every deliberate collapse through `collapseRail`, so a fifth
+  // control cannot set `navCollapsed` behind the two named doors. R1's decline is gone; the
+  // plumbing that kept its call sites countable is not.
+  /** Every deliberate expand goes through here, so a fifth expand door cannot be added quietly. */
   const expandRail = useCallback(() => {
-    railHeldOpen.current = true;
     setNavCollapsed(false);
   }, []);
-  /** Asking for the fold is also asking for the AUTOMATIC fold back. */
+  /** …and every deliberate fold through here. The AUTOMATIC fold has its own handler, below. */
   const collapseRail = useCallback(() => {
-    railHeldOpen.current = false;
     setNavCollapsed(true);
   }, []);
   // Owner item 3 (2026-07-31) — the collapsed strip names its icons on hover. A real DOM
@@ -1253,13 +1272,14 @@ function ShellFrame() {
     const onDataError = (e: Event) =>
       setDataError(String((e as CustomEvent).detail ?? "") || "The data could not be loaded.");
     const onToast = (e: Event) => setToast(String((e as CustomEvent).detail ?? ""));
-    // ⭐ W34-T12 (R1) — THE AUTOMATIC FOLD DECLINES ONCE THE USER HAS PUT THE RAIL BACK.
-    // Owner item 10's fold is intact for the first grid click of a visit; after a deliberate
-    // expand it stops firing, so the logo's effect survives the next cell click instead of being
-    // undone by it. Reading a ref here is what keeps this listener's `[]` deps honest — a state
-    // value would have to be in the dependency array, re-registering the listener on every fold.
+    // ⭐⭐ W38-T04 (R9) — THE AUTOMATIC FOLD IS UNCONDITIONAL, AND THAT IS THE WHOLE RULE.
+    // `NAV_MINIMIZE_EVENT` fires from `CustomerGrid` on EVERY cell click and EVERY view switch;
+    // this is its only listener, and it sets, every time, with nothing in front of it. W34-T12's
+    // `railHeldOpen` guard stood here and is deleted (see the block by `expandRail` for why the
+    // ref went with it). ⛔ ANY early return, condition or stored preference added between this
+    // line and the setter re-creates the behaviour owner item 3 asked to be fixed FOREVER — and
+    // `verify_ui.py`'s `W38-T04 unconditional` leg exists to go red the moment one appears.
     const onNavMinimize = () => {
-      if (railHeldOpen.current) return;
       setNavCollapsed(true);
     };
     // C-SHARE: the rail asks, the frame opens. A malformed detail opens NOTHING —
@@ -2130,22 +2150,24 @@ function ShellFrame() {
         // brand button below ("Expand navigation"), which is what a keyboard reaches.
         onClick={navCollapsed ? expandOnBlank : undefined}
       >
-        {/* ⭐ WAVE 35 · T02 — THE HEAD IS AN ALIGNMENT BAND NOW AND NOTHING ELSE. The brand and
-            the toggle both moved into `.shell-topbar` above (C1), and contract C1 keeps this
-            element on its `--lp-rail-head-h` token deliberately: the content pane's own first
-            band is one `--lp-rail-head-h` tall, so deleting this would start the rail's first nav
-            row a header higher than the grid beside it and every database page would read as
-            misaligned. It is a spacer with the shared hairline, not a leftover.
-            ⚠ W36-T51 — THAT BAND USED TO BE NAMED AS `DbHead` OR `.cg-views-top`, AND `DbHead` IS
-            NOW DELETED FROM THIS SURFACE (owner item 7). The alignment survives because
-            `.cg-views-top` is still there and still one band tall; it is the VIEWS rail's head
-            that this spacer now lines up with. ⛔ So the thing that would orphan this element is
-            the views rail losing its head, NOT the database losing its title — a different edit
-            from the one a reader of the old sentence would have gone looking for.
-            ⚠ It is `aria-hidden` because it now has no content and no purpose a screen reader can
-            use; announcing an empty banner is noise. */}
-        <div className="shell-side-head" aria-hidden="true" />
-
+        {/* ⛔⛔ WAVE 38 · T05 (owner instruction 2) — `<div className="shell-side-head" aria-hidden />`
+            STOOD HERE AND IS DELETED, WITH ITS RULE IN `index.css`. Owner: *"Move the 'Home' button
+            into the empty space above it, and every other module button upward, so there is no
+            awkward gap."* That empty space was this element: an `aria-hidden` spacer holding
+            `--lp-rail-head-h`, so `<nav>` — and Home as its first row — opened a full header below
+            the top strip. `<nav>` is now `.shell-side`'s first child, Home is the rail's topmost
+            row, and every row below rises by the same one head, because they are literal
+            source-order siblings and nothing else about them moved.
+            ⚠ IT WAS NOT A LEFTOVER, AND THE COMMENT THAT STOOD HERE WAS RIGHT: it aligned this
+            rail's first row with the content pane's first band. The tombstone on `.shell-side-head`
+            in `index.css` carries the cost that was accepted and the alternative that was rejected.
+            The short version is that the band it aligned with (`.cg-views-top`, `.auto-rail-top`)
+            exists only on grid and Agents surfaces, so on Home — where the owner is looking — it
+            aligned with nothing at all.
+            ⚠ NOTHING ELSE IN THE RAIL KEYED ON IT, checked rather than assumed: neither `index.css`
+            nor `shell/navExtras.css` carries a `.shell-side >`, `:first-child` or `:nth-child` rule
+            into `.shell-side`, so `<nav>` becoming the first child changes no other selector's
+            match. `verify_ui.py`'s `W38-T05 no-rail-head` leg keeps the element from coming back. */}
         <nav className={"shell-nav" + (railLoading ? " is-rail-loading" : "")}>
           {/* ⭐⭐ W33-T75 — THE ONE IN-FLIGHT STATE. `is-rail-loading` hides every sibling below
               (`navExtras.css`), so a row cannot paint ahead of its neighbours. Rendering the rows
@@ -2153,6 +2175,55 @@ function ShellFrame() {
               the tooltips and the account menu all hang off this subtree, and unmounting them for
               the length of a fetch would tear down state that has nothing to do with the nav. */}
           {railLoading ? <RailSkeleton /> : null}
+          {/* ⭐⭐ WAVE 38 · T06 (owner instruction 1) — THE MINIMISED RAIL'S CHAT LAUNCHER. Owner:
+              *"When the Navigation is minimized: the icon that opens the AI chatbot overlay with
+              the grid, and move the logo downward."*
+              ⛔ IT OPENS THE GRID'S OWN OVERLAY, NOT `#/assistant`. Those are two different doors:
+              the assistant is a route with no table under it, while `<GridChat>` is docked beside
+              the grid it is about and reads the rows already on screen. This raises the same signal
+              the views rail's `cg-chat-toggle` flips locally, so both launchers land on one panel
+              rather than the app growing a second chat.
+              ⛔ COLLAPSED ONLY, because expanded the rail already has room for the views rail's own
+              launcher and a second control for one panel in one window is a coin toss for the
+              reader. `navCollapsed` is the same state the brand's downward nudge keys on
+              (`index.css`, `.shell-root:has(.shell-side.is-collapsed) .shell-topbar-brand`), so the
+              two halves of the owner's sentence appear and disappear together.
+              ⚠ A `<button>`, which is what keeps `expandOnBlank` off it: the rail's background click
+              returns early on `closest('a,button,…')`, so this opens the chat WITHOUT also expanding
+              the rail it was minimised into. Verified against that handler, not assumed from its
+              name — `.shell-side-bottom` next door had to become a sibling for the mirror-image
+              reason, and its comment records the cost.
+              ⚠ THE TIP IS NOT DECORATION. Collapsed, `.shell-nav-label` folds to zero width, so
+              every rail row buys its name back through `tipEnter`; a glyph without one is the
+              unlabelled-icon trap the Templates row's comment names. Unconditional here rather than
+              ternary, because this control exists only in the state that needs it.
+              ⚠ Clicking it with no grid mounted is a NO-OP BY CONSTRUCTION, twice over: `signal()`
+              dispatches into a window with no listener, and the grid's listener is itself absent on
+              an embedded or Query surface, matching the `!embedded && !queryBinding` guard that
+              decides whether `<GridChat>` can mount at all (`CustomerGrid.tsx`, the chat dock). */}
+          {navCollapsed ? (
+            <button
+              type="button"
+              className="shell-rail-chat"
+              aria-label="Ask about this data"
+              title="Ask about this data"
+              onClick={() => signal(GRID_CHAT_OPEN_EVENT)}
+              onMouseEnter={tipEnter("Ask about this data")}
+              onMouseLeave={tipLeave}
+            >
+              {/* The views rail's own chat glyph, redrawn identically. One mark, one meaning
+                  (DESIGN.md §4) — two doors onto one panel must not wear two different icons. */}
+              <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+                <path
+                  d="M13.4 9.2c0 1.5-1.3 2.7-2.9 2.7H6.9l-3 2.1v-2.3a2.8 2.8 0 0 1-1.3-2.3V5.1c0-1.5 1.3-2.7 2.9-2.7h5c1.6 0 2.9 1.2 2.9 2.7z"
+                  stroke="currentColor"
+                  strokeWidth="1.3"
+                  strokeLinejoin="round"
+                />
+                <path d="M5.9 7.2h4.2" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" />
+              </svg>
+            </button>
+          ) : null}
           {/* ⭐ WAVE 23 item 9 (R7, contract C10) — HOME, the new landing, at the top of the rail.
               An `<a>` to a CHROME route: it needs no grant because it renders nothing the server
               did not already send (nav.ts' `CHROME_ROUTES` note carries the full argument, and
@@ -2975,10 +3046,14 @@ function ShellFrame() {
               comments up. `.shell-db-frame` is the rail-and-content GEOMETRY; dropping it collapses
               the box. Only the 44px title band is reclaimed, and the grid takes it: `.shell-grid-
               host` is `height: 100%` inside a column that now has one fewer fixed row.
-              ⚠ `.shell-side-head` (index.css) IS NOT ORPHANED BY THIS, checked rather than assumed:
-              its comment says it exists to align the rail's first nav row with a 44px band, and the
-              band it now aligns with is `.cg-views-top`, which is still there and still
-              `--lp-rail-head-h` tall. It would only become dead if the VIEWS rail lost its head.
+              ⚠ `.shell-side-head` WAS CHECKED HERE AND FOUND LIVE. W38-T05 HAS SINCE DELETED IT,
+              and this line is corrected rather than left standing, because a comment asserting the
+              liveness of an element that no longer exists is the precise failure the "checked
+              rather than assumed" habit was adopted to prevent. ⛔ THE REASONING WAS SOUND AND ITS
+              CONCLUSION STILL HOLDS FOR T51: the band aligned with the VIEWS rail's head, not with
+              the database title, so nothing T51 did orphaned it. What retired it was owner
+              instruction 2 of wave 38 — the rail's empty top band IS the "awkward gap" — which is a
+              later and unrelated ruling. Its tombstone in `index.css` carries the full argument.
               ⛔ `DbHead` ITSELF SURVIVES UNTIL W36-T67 LANDS. `query/QueryPage.tsx:138` still mounts
               it and that file is session D's fence — a component cannot be deleted while another
               fence imports it, which is why T51 is blocked-by T67 rather than the reverse. */