Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,5 +1,5 @@
 {
- "current": "0b2ab48",
+ "current": "240caca",
  "releases": [
   {
    "version": "v52",

VERSION

@@ -1 +1 @@
-0b2ab48
+240caca

api/aios_session.py

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

api/deps.py

@@ -296,7 +296,20 @@ def assistant_read_scope(session: Session, database, fields=None, filters=None):
         perm_scope.validate_assistant_filter((grant or {}).get("filter"), canonical_fields)
     except ValueError as exc:
         _assistant_refuse(400, "assistant_bad_filter", str(exc))
-    permitted_rows = (perm_scope.assistant_apply_row_scope(rows, session.user, key, canonical_fields)
+    # ⭐ OWNER I16 — the tenant handle rides into the row wall here too, so one stored rule means
+    # the same thing in the Analyst's answer as it does on the grid (see
+    # `perm_scope._enrich_for_wall`).
+    #
+    # ⚠ AND IT CHANGES NOTHING ON THIS PATH TODAY, WHICH IS STATED RATHER THAN LEFT TO BE
+    # REDISCOVERED. `validate_assistant_filter` three lines up refuses any leaf naming a column
+    # outside `canonical_fields`, so a wall on a user-generated column is rejected before it can
+    # reach this call at all. The handle is passed anyway because the alternative is a door that
+    # walls these modules WITHOUT it — and "all six or none" is the property that keeps one wall
+    # from having two meanings. Widening the Assistant's own validator to admit such a column is
+    # a separate decision about what E may read, not a side effect of a grid fix.
+    permitted_rows = (perm_scope.assistant_apply_row_scope(rows, session.user, key,
+                                                           canonical_fields,
+                                                           st=getattr(session, "runtime", None))
                       if grant is not None else list(rows or ()))
     visible = (perm_scope.assistant_visible_fields(canonical_fields, session.user, key)
                if grant is not None else list(canonical_fields))

api/routes_customers.py

@@ -274,7 +274,21 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
     # 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)
+    #
+    # ⭐⭐ OWNER I16 — `st=rt` IS WHAT MAKES A WALL ON A USER-GENERATED COLUMN MEAN ANYTHING
+    # HERE. *"Permission Filters must be able to filter on user-generated Fields too."* The
+    # sentence above is exactly why it was needed: the canonical list has no `custom_` column in
+    # it and these rows are PRE-OVERLAY, so such a leaf denied every row while the editor
+    # reported the rule saved. With the handle, `perm_scope._enrich_for_wall` merges the
+    # tenant-wide value for the named column onto a COPY of each row and declares it for the
+    # evaluator. Nothing else about this call changes, and a caller with no handle still gets
+    # the wall exactly as it was.
+    #
+    # ⛔ THE SAME HANDLE GOES TO `allowed_pids` BELOW, AND THE PAIR IS NOT OPTIONAL. That is the
+    # WRITE wall to this one's READ wall; lending it here alone would make a user-generated rule
+    # narrow what an account SEES while leaving what it may PATCH untouched.
+    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, aios_grid.FIELDS,
+                                          st=rt)
     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
@@ -488,12 +502,17 @@ def allowed_pids(session: Session):
     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.
+
+    ⛔ AND `st` IS PART OF "SAME FUNCTION, SAME ORDER" (owner I16). `grid_assembly` lends the
+    tenant handle so a wall naming a user-generated column can be answered at all; without the
+    identical argument here that rule would narrow the READ and not the WRITE — the drift this
+    docstring already refuses, wearing a new argument's clothes.
     """
     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)
+                                      aios_grid.FIELDS, st=session.runtime)
     return frozenset(r["pid"] for r in rows if r.get("pid") is not None)
 
 

api/routes_products.py

@@ -115,7 +115,14 @@ def scoped_pool(session: Session):
     # The SAME wall the customer assembly applies, in the same order: rows first (before pids
     # are taken, so an out-of-filter row never enters allowed_pids), then the field closure,
     # then the values stripped from the rows as well as the field list.
-    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, fields_base)
+    # ⭐⭐ OWNER I16 — AND THE SAME TENANT HANDLE, for the same reason and with the same
+    # consequence if it is left off. `fields_base` is this topic's contract plus its declared
+    # tenant-wide columns; a column a USER made is in neither, and these rows are pre-overlay,
+    # so such a leaf denied every product row while the admin was told the rule saved. See
+    # `perm_scope._enrich_for_wall`. This route is BOTH walls at once (it returns the pids the
+    # write door uses), so there is no second call here to keep in step.
+    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, fields_base,
+                                          st=session.runtime)
     pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
     return pids, team_id, rows_src, fields_base
 

api/routes_slack.py

@@ -182,13 +182,30 @@ def agent_visible_fields(agent, fields, module):
     return perm_scope.visible_fields(fields, agent_principal(agent), module)
 
 
-def agent_rows(agent, rows, module, fields, ctx=None):
+def agent_rows(agent, rows, module, fields, ctx=None, st=None):
     """The rows this channel may receive — `permits()`, so an unanswerable permanent filter DENIES
-    rather than being ignored."""
+    rather than being ignored.
+
+    ⭐⭐ `st` IS THE TENANT HANDLE AND IT IS HERE BECAUSE OF THE SENTENCE IN `agent_principal`:
+    a channel agent IS a principal of the same wall, so a permanent filter naming a
+    user-generated column has to mean the SAME thing here as it does on the grid (owner I16).
+    A door that lends the handle and a door that does not are one stored rule with two meanings.
+
+    ⚠ PASS THE TENANT'S OWN RUNTIME — every other store read in this file takes
+    `session.runtime`, and a channel is not a second tenancy. It is a keyword with a `None`
+    default for the same reason `perm_scope.apply_row_scope`'s is: without one this is
+    byte-identical to the wall that shipped before the argument existed.
+
+    ⚠ `hidden_keys` DELIBERATELY DOES NOT TAKE IT IN THIS CHANGE. Its field-grant leg
+    under-hides without a handle (see `perm_scope.visible_overlays`), which is a real and
+    separate gap on this surface — but it is the FIELD wall, it moves what a channel receives
+    rather than what I16 asked for, and widening two walls in one ticket is how a permission
+    change stops being reviewable.
+    """
     import core.perm_scope as perm_scope
     p = agent_principal(agent)
     hide = perm_scope.hidden_keys(p, module, fields)
-    kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx)
+    kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx, st=st)
     # Both wires, never one: the field list and the row payload are separate, and stripping only
     # the first leaves the value sitting in the second where anyone can read it.
     return [perm_scope.strip_row(r, hide) for r in kept]

platform/core/shared_overlay.py

@@ -1,302 +1,327 @@
-"""The TENANT-WIDE overlay stratum — one value per (row, column) for the whole workspace.
-
-Wave 29, item 20 / owner ruling R11, contract C5. The sibling of `core/table_store.py`, which
-holds the PER-USER strata (`store.get(key)[username]`) and always has.
-
-⛔ THE DEFECT THIS EXISTS FOR IS NOT "SHARING WOULD BE NICE" — IT IS THAT A SHARED VIEW SILENTLY
-WIDENS. `modules/product_data.py` already states it, in the comment above the supplier master:
-
-    "A user-created field and its values live in the PER-USER strata; only VIEWS are shared. So a
-     shared 'Buy list' view that filtered on a user-created column would, for every OTHER account,
-     name a column that does not exist — and an unknown column is an INACTIVE condition in the
-     tri-state engine, which IGNORES it and therefore WIDENS. The buy list would silently show the
-     whole catalogue to everyone but its author."
-
-That is why the four supplier columns were frozen as read-only CONTRACT columns rather than made
-editable, and why the owner's ask ("turn this Excel sheet into a User created Field that we can
-edit") has been parked for two waves. A column whose value is the same for every reader makes the
-shared view mean ONE thing, which is the precondition for editing it at all.
-
-────────────────────────────────────────────────────────────────────────────────────────────────
-⛔⛔ THIS MODULE IS NOT A PERMISSION WALL, AND MUST NEVER BECOME ONE BY ACCIDENT.
-
-It refuses no reader and no writer. The caller has already answered "may this session open this
-surface" (`user_tables.may_open`, `Session.require`, the BU pool) and this module answers only
-"what is stored". Two different questions; one of them belongs upstream, where the session is.
-
-What it DOES enforce is the one thing a caller can get wrong silently:
-
-    ⭐ `cells(table_key, pids)` — `pids` IS REQUIRED, POSITIONALLY, AND THERE IS NO "EVERYTHING"
-      CALL. A default of "all rows" is the widening hazard above wearing a friendly face: the
-      caller passes the row set it has ALREADY scoped, so a cell for a row this reader may not see
-      cannot come back to be merged. There is deliberately no `all_cells()` to reach for; a caller
-      that genuinely needs the lot passes the lot, in writing, where a reviewer can see it.
-
-The row wall then holds twice over, because `aios_grid.rows_from_pool` iterates the POOL and looks
-each pid UP in the overlay — never the reverse. A cell for a row outside the pool has nothing to
-attach to. This module is built to keep that true rather than to re-implement it.
-────────────────────────────────────────────────────────────────────────────────────────────────
-
-RESIDENCY. Its own bucket, `<table_key>__shared`, beside the per-user one — never a `__shared__`
-member inside it. Two reasons, and the first is `product_data.py`'s own argument for separate
-topic keys ("separate store keys make that structurally impossible, which is the whole reason the
-table-page factory exists"): a per-user reader iterating usernames cannot encounter shared data
-when there is no shared data in that bucket to encounter. The second is cost — the per-user bucket
-carries every user's views, and a cell edit should not read-modify-write all of it.
-
-SHAPE, chosen to be drop-in:
-
-    {"fields": {field_key: Field},              # the tenant-wide column DEFINITIONS
-     "cells":  {"<pid>": {field_key: value}}}   # exactly `rows_from_pool(overlays=...)`'s shape
-
-`cells()` returns STRING pid keys for that reason — `rows_from_pool` does `overlays.get(str(pid))`,
-so a caller merges the shared stratum over the per-user one with one `dict.update` and cannot get
-the key type wrong. (`table_store` stores `{str(pid): {...}}` too; one shape, three readers.)
-"""
-import core.store as store
-
-#: The suffix that turns a topic's per-user workspace key into its shared one. Callers pass the
-#: key they ALREADY hold (`product_data.TABLE_KEY`, `f'{ut_key}_table_workspace'`) — one
-#: identifier for both strata, so there is no second naming convention to get wrong.
-BUCKET_SUFFIX = '__shared'
-
-#: One cell value's ceiling, matching the `json` field kind's. A shared cell is read by every user
-#: in the tenant, so an unbounded one is an unbounded cost for all of them.
-MAX_VALUE_CHARS = 32_768
-
-
-def bucket(table_key):
-    """The store key this topic's shared stratum lives under."""
-    key = str(table_key or '').strip()
-    if not key:
-        raise ValueError('shared_overlay: a table_key is required — it names the bucket')
-    return f'{key}{BUCKET_SUFFIX}'
-
-
-def _st(st):
-    return st if st is not None else store
-
-
-def _read(table_key, st=None):
-    """The whole stratum, always in its full two-key shape. Lenient like every other display
-    read: an unreachable store degrades to "nothing shared yet", never to an exception on a page
-    that would otherwise render."""
-    try:
-        data = _st(st).get(bucket(table_key)) or {}
-    except Exception:
-        data = {}
-    return {'fields': dict(data.get('fields') or {}),
-            'cells': dict(data.get('cells') or {})}
-
-
-def _write(table_key, change, st=None, flush='async'):
-    """Read-modify-write one shared stratum.
-
-    `flush='async'` by default for the same reason `table_store._update` uses it: a typed cell
-    lands here inside the request round-trip, and the historical synchronous hub commit cost
-    seconds per keystroke. Structural writes (a field definition) pass `flush='sync'` — they are
-    rare, and a lost column definition is a worse failure than a lost keystroke.
-    """
-    def _up(data):
-        data = data if isinstance(data, dict) else {}
-        data.setdefault('fields', {})
-        data.setdefault('cells', {})
-        change(data)
-        return data
-    return _st(st).update(bucket(table_key), _up, flush=flush)
-
-
-def _pid(pid):
-    """Pids are ints everywhere in the grid and strings in JSON. ONE coercion, here, so a caller
-    passing either cannot write a row that a reader keyed the other way never finds."""
-    return str(int(pid))
-
-
-def _value(value):
-    """A cell holds a SCALAR. The Row contract is scalar on every surface — the grid, the filter
-    engine, formulas, export — and the `json` kind is a validated STRING rather than an object.
-
-    ⛔ A dict or a list RAISES rather than being dropped. This is called by our own code, so a
-    non-scalar is a programming error, and silently storing nothing would surface later as "the
-    shared column is blank for everyone" with no failure anywhere near the cause.
-    """
-    if isinstance(value, (dict, list, tuple, set)):
-        raise ValueError(f'shared_overlay: a cell holds a scalar, not {type(value).__name__}')
-    if value is None or isinstance(value, bool) or isinstance(value, (int, float)):
-        return value
-    text = str(value)
-    return text[:MAX_VALUE_CHARS]
-
-
-# ----------------------------------------------------------------- the column DEFINITIONS
-def fields(table_key, st=None):
-    """`{field_key: Field}` — the columns this topic shares tenant-wide.
-
-    Unscoped on purpose, and it is the one thing here that is: a shared column's EXISTENCE is
-    tenant-wide by definition — that is the whole feature, and it is what stops a shared view
-    naming a column half the workspace lacks. Its VALUES are scoped by `cells()`.
-    """
-    return _read(table_key, st)['fields']
-
-
-def is_shared(table_key, field_key, st=None):
-    """Is this column's value tenant-wide? The predicate a caller uses to decide WHICH stratum to
-    read and write — one evaluator, so the read path and the write path cannot disagree about
-    where a given column lives ([[one-evaluator-per-question]])."""
-    return str(field_key or '') in _read(table_key, st)['fields']
-
-
-def put_field(table_key, field_key, defn, st=None):
-    """Declare (or redefine) a shared column. Returns what was stored."""
-    key = str(field_key or '').strip()
-    if not key:
-        raise ValueError('shared_overlay: a field needs a key')
-    entry = dict(defn or {})
-    entry['key'] = key
-
-    def _add(data):
-        data['fields'][key] = entry
-
-    _write(table_key, _add, st, flush='sync')
-    return entry
-
-
-def drop_field(table_key, field_key, st=None):
-    """Remove a shared column AND every stored value for it.
-
-    ⛔ The cells go with the definition, exactly as `table_store.delete_field` scrubs its own:
-    orphaned values would silently resurface if the key were ever reused — and a resurrected
-    value in a TENANT-WIDE stratum reappears for everybody at once.
-    """
-    key = str(field_key or '').strip()
-    if not key:
-        return False
-    hit = [False]
-
-    def _drop(data):
-        hit[0] = data['fields'].pop(key, None) is not None
-        for row in data['cells'].values():
-            if isinstance(row, dict):
-                row.pop(key, None)
-        # ⚠ AND DROP THE ROWS THAT ARE NOW EMPTY. `cells()` already skips a blank row, so this
-        # changes nothing a reader sees — but this bucket is read by every user in the tenant,
-        # and a `{}` per pid that once held a since-deleted column is dead weight that only ever
-        # grows. Caught by `prune()` reporting rows nobody could see as dropped.
-        for pid in [p for p, row in data['cells'].items() if not row]:
-            data['cells'].pop(pid, None)
-
-    _write(table_key, _drop, st, flush='sync')
-    return hit[0]
-
-
-# ----------------------------------------------------------------------------- the VALUES
-def cells(table_key, pids, st=None):
-    """`{"<pid>": {field_key: value}}` for the rows named by `pids` — and ONLY those.
-
-    ⛔ `pids` IS REQUIRED. See the module header: this is the row wall expressed as a signature,
-    so a caller cannot get "every shared cell in the tenant" by forgetting an argument. Pass the
-    pool you have already scoped for this session.
-
-    An empty `pids` legitimately returns `{}` — a reader with no rows sees no cells, which is the
-    correct answer rather than a special case.
-    """
-    if pids is None:
-        raise TypeError('shared_overlay.cells: pids is required — pass the row set you have '
-                        'already scoped for this reader (there is deliberately no "all" call)')
-    wanted = {_pid(p) for p in pids}
-    if not wanted:
-        return {}
-    stored = _read(table_key, st)['cells']
-    return {pid: dict(row) for pid, row in stored.items()
-            if pid in wanted and isinstance(row, dict) and row}
-
-
-def put_cell(table_key, pid, field_key, value, st=None):
-    """Write ONE shared cell. Returns the value as stored (which may be truncated)."""
-    return put_cells(table_key, pid, {field_key: value}, st=st).get(str(field_key or ''))
-
-
-def put_cells(table_key, pid, values, st=None):
-    """Write several shared cells on one row, in one store update. Returns what was stored."""
-    row_id = _pid(pid)
-    clean = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
-    if not clean:
-        return {}
-
-    def _patch(data):
-        data['cells'].setdefault(row_id, {}).update(clean)
-
-    _write(table_key, _patch, st)
-    return clean
-
-
-def put_rows(table_key, rows, st=None):
-    """Write shared cells on MANY rows in ONE store update. Returns `{row_id: {key: value}}`.
-
-    ⭐⭐ THE WHOLE POINT IS THE *ONE*, AND IT IS NOT AN OPTIMISATION. `put_cells` is one row per
-    store write, so a 1,397-row catalog import is 1,397 download-modify-upload cycles against one
-    JSON document. This repo has a MEASURED scar for that shape: **18 writes against one document
-    under the store's coalescing single-flight landed ZERO while answering 200 eighteen times.**
-    Batching is what makes a bulk import land at all, not what makes it fast.
-
-    ⚠ It deliberately takes the WHOLE SET rather than accepting a stream: a caller that loops over
-    this function has simply rebuilt `put_cells` with extra steps, and the failure it reintroduces
-    is silent. If the set does not fit in memory it does not fit in this store either — that is a
-    signal to change substrate, not to chunk.
-
-    ⛔ NO CAP HERE, ON PURPOSE. The bound belongs at the DOOR, where a caller identity and a
-    reportable refusal exist (`routes_grid.bulk_cells`). A silent ceiling in a store primitive is
-    exactly the shape the standing no-cap rule forbids.
-    """
-    clean = {}
-    for pid, values in dict(rows or {}).items():
-        row_id = _pid(pid)
-        cells_for_row = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
-        if cells_for_row:
-            clean.setdefault(row_id, {}).update(cells_for_row)
-    if not clean:
-        return {}
-
-    def _patch(data):
-        for row_id, values in clean.items():
-            data['cells'].setdefault(row_id, {}).update(values)
-
-    # `flush='sync'` because a bulk import must be durable when the call returns: the caller is a
-    # script that will report "1,397 rows written" and exit, and an async flush would make that
-    # sentence a prediction rather than a fact.
-    _write(table_key, _patch, st, flush='sync')
-    return clean
-
-
-def clear_row(table_key, pid, st=None):
-    """Forget every shared cell on one row. True when there was something to forget."""
-    row_id = _pid(pid)
-    hit = [False]
-
-    def _clear(data):
-        hit[0] = data['cells'].pop(row_id, None) is not None
-
-    _write(table_key, _clear, st)
-    return hit[0]
-
-
-def prune(table_key, live_pids, st=None):
-    """Drop shared cells for rows that no longer exist. Returns how many rows were dropped.
-
-    ⛔ NOT a scoped read wearing another name, and the difference is the whole reason `cells()`
-    refuses to serve everything: `live_pids` here means *every row this TABLE has*, which is a
-    fact about the data, whereas `pids` in `cells()` means *every row this READER may see*, which
-    is a fact about the session. Calling this with one session's pool would delete the shared
-    values of every row that session cannot see. The name says which is which; so does this note.
-    """
-    keep = {_pid(p) for p in live_pids}
-    dropped = [0]
-
-    def _prune(data):
-        gone = [pid for pid in data['cells'] if pid not in keep]
-        for pid in gone:
-            data['cells'].pop(pid, None)
-        dropped[0] = len(gone)
-
-    _write(table_key, _prune, st, flush='sync')
-    return dropped[0]
+"""The TENANT-WIDE overlay stratum — one value per (row, column) for the whole workspace.
+
+Wave 29, item 20 / owner ruling R11, contract C5. The sibling of `core/table_store.py`, which
+holds the PER-USER strata (`store.get(key)[username]`) and always has.
+
+⛔ THE DEFECT THIS EXISTS FOR IS NOT "SHARING WOULD BE NICE" — IT IS THAT A SHARED VIEW SILENTLY
+WIDENS. `modules/product_data.py` already states it, in the comment above the supplier master:
+
+    "A user-created field and its values live in the PER-USER strata; only VIEWS are shared. So a
+     shared 'Buy list' view that filtered on a user-created column would, for every OTHER account,
+     name a column that does not exist — and an unknown column is an INACTIVE condition in the
+     tri-state engine, which IGNORES it and therefore WIDENS. The buy list would silently show the
+     whole catalogue to everyone but its author."
+
+That is why the four supplier columns were frozen as read-only CONTRACT columns rather than made
+editable, and why the owner's ask ("turn this Excel sheet into a User created Field that we can
+edit") has been parked for two waves. A column whose value is the same for every reader makes the
+shared view mean ONE thing, which is the precondition for editing it at all.
+
+────────────────────────────────────────────────────────────────────────────────────────────────
+⛔⛔ THIS MODULE IS NOT A PERMISSION WALL, AND MUST NEVER BECOME ONE BY ACCIDENT.
+
+It refuses no reader and no writer. The caller has already answered "may this session open this
+surface" (`user_tables.may_open`, `Session.require`, the BU pool) and this module answers only
+"what is stored". Two different questions; one of them belongs upstream, where the session is.
+
+What it DOES enforce is the one thing a caller can get wrong silently:
+
+    ⭐ `cells(table_key, pids)` — `pids` IS REQUIRED, POSITIONALLY, AND THERE IS NO "EVERYTHING"
+      CALL. A default of "all rows" is the widening hazard above wearing a friendly face: the
+      caller passes the row set it has ALREADY scoped, so a cell for a row this reader may not see
+      cannot come back to be merged. There is deliberately no `all_cells()` to reach for; a caller
+      that genuinely needs the lot passes the lot, in writing, where a reviewer can see it.
+
+The row wall then holds twice over, because `aios_grid.rows_from_pool` iterates the POOL and looks
+each pid UP in the overlay — never the reverse. A cell for a row outside the pool has nothing to
+attach to. This module is built to keep that true rather than to re-implement it.
+────────────────────────────────────────────────────────────────────────────────────────────────
+
+RESIDENCY. Its own bucket, `<table_key>__shared`, beside the per-user one — never a `__shared__`
+member inside it. Two reasons, and the first is `product_data.py`'s own argument for separate
+topic keys ("separate store keys make that structurally impossible, which is the whole reason the
+table-page factory exists"): a per-user reader iterating usernames cannot encounter shared data
+when there is no shared data in that bucket to encounter. The second is cost — the per-user bucket
+carries every user's views, and a cell edit should not read-modify-write all of it.
+
+SHAPE, chosen to be drop-in:
+
+    {"fields": {field_key: Field},              # the tenant-wide column DEFINITIONS
+     "cells":  {"<pid>": {field_key: value}}}   # exactly `rows_from_pool(overlays=...)`'s shape
+
+`cells()` returns STRING pid keys for that reason — `rows_from_pool` does `overlays.get(str(pid))`,
+so a caller merges the shared stratum over the per-user one with one `dict.update` and cannot get
+the key type wrong. (`table_store` stores `{str(pid): {...}}` too; one shape, three readers.)
+"""
+import core.store as store
+
+#: The suffix that turns a topic's per-user workspace key into its shared one. Callers pass the
+#: key they ALREADY hold (`product_data.TABLE_KEY`, `f'{ut_key}_table_workspace'`) — one
+#: identifier for both strata, so there is no second naming convention to get wrong.
+BUCKET_SUFFIX = '__shared'
+
+#: One cell value's ceiling, matching the `json` field kind's. A shared cell is read by every user
+#: in the tenant, so an unbounded one is an unbounded cost for all of them.
+MAX_VALUE_CHARS = 32_768
+
+
+def bucket(table_key):
+    """The store key this topic's shared stratum lives under."""
+    key = str(table_key or '').strip()
+    if not key:
+        raise ValueError('shared_overlay: a table_key is required — it names the bucket')
+    return f'{key}{BUCKET_SUFFIX}'
+
+
+def _st(st):
+    return st if st is not None else store
+
+
+def _read(table_key, st=None):
+    """The whole stratum, always in its full two-key shape. Lenient like every other display
+    read: an unreachable store degrades to "nothing shared yet", never to an exception on a page
+    that would otherwise render."""
+    try:
+        data = _st(st).get(bucket(table_key)) or {}
+    except Exception:
+        data = {}
+    return {'fields': dict(data.get('fields') or {}),
+            'cells': dict(data.get('cells') or {})}
+
+
+def _write(table_key, change, st=None, flush='async'):
+    """Read-modify-write one shared stratum.
+
+    `flush='async'` by default for the same reason `table_store._update` uses it: a typed cell
+    lands here inside the request round-trip, and the historical synchronous hub commit cost
+    seconds per keystroke. Structural writes (a field definition) pass `flush='sync'` — they are
+    rare, and a lost column definition is a worse failure than a lost keystroke.
+    """
+    def _up(data):
+        data = data if isinstance(data, dict) else {}
+        data.setdefault('fields', {})
+        data.setdefault('cells', {})
+        change(data)
+        return data
+    return _st(st).update(bucket(table_key), _up, flush=flush)
+
+
+def _pid(pid):
+    """Pids are ints everywhere in the grid and strings in JSON. ONE coercion, here, so a caller
+    passing either cannot write a row that a reader keyed the other way never finds."""
+    return str(int(pid))
+
+
+def _value(value):
+    """A cell holds a SCALAR. The Row contract is scalar on every surface — the grid, the filter
+    engine, formulas, export — and the `json` kind is a validated STRING rather than an object.
+
+    ⛔ A dict or a list RAISES rather than being dropped. This is called by our own code, so a
+    non-scalar is a programming error, and silently storing nothing would surface later as "the
+    shared column is blank for everyone" with no failure anywhere near the cause.
+    """
+    if isinstance(value, (dict, list, tuple, set)):
+        raise ValueError(f'shared_overlay: a cell holds a scalar, not {type(value).__name__}')
+    if value is None or isinstance(value, bool) or isinstance(value, (int, float)):
+        return value
+    text = str(value)
+    return text[:MAX_VALUE_CHARS]
+
+
+# ----------------------------------------------------------------- the column DEFINITIONS
+def fields(table_key, st=None):
+    """`{field_key: Field}` — the columns this topic shares tenant-wide.
+
+    Unscoped on purpose, and it is the one thing here that is: a shared column's EXISTENCE is
+    tenant-wide by definition — that is the whole feature, and it is what stops a shared view
+    naming a column half the workspace lacks. Its VALUES are scoped by `cells()`.
+    """
+    return _read(table_key, st)['fields']
+
+
+def is_shared(table_key, field_key, st=None):
+    """Is this column's value tenant-wide? The predicate a caller uses to decide WHICH stratum to
+    read and write — one evaluator, so the read path and the write path cannot disagree about
+    where a given column lives ([[one-evaluator-per-question]])."""
+    return str(field_key or '') in _read(table_key, st)['fields']
+
+
+def put_field(table_key, field_key, defn, st=None):
+    """Declare (or redefine) a shared column. Returns what was stored."""
+    key = str(field_key or '').strip()
+    if not key:
+        raise ValueError('shared_overlay: a field needs a key')
+    entry = dict(defn or {})
+    entry['key'] = key
+
+    def _add(data):
+        data['fields'][key] = entry
+
+    _write(table_key, _add, st, flush='sync')
+    return entry
+
+
+def drop_field(table_key, field_key, st=None):
+    """Remove a shared column AND every stored value for it.
+
+    ⛔ The cells go with the definition, exactly as `table_store.delete_field` scrubs its own:
+    orphaned values would silently resurface if the key were ever reused — and a resurrected
+    value in a TENANT-WIDE stratum reappears for everybody at once.
+    """
+    key = str(field_key or '').strip()
+    if not key:
+        return False
+    hit = [False]
+
+    def _drop(data):
+        hit[0] = data['fields'].pop(key, None) is not None
+        for row in data['cells'].values():
+            if isinstance(row, dict):
+                row.pop(key, None)
+        # ⚠ AND DROP THE ROWS THAT ARE NOW EMPTY. `cells()` already skips a blank row, so this
+        # changes nothing a reader sees — but this bucket is read by every user in the tenant,
+        # and a `{}` per pid that once held a since-deleted column is dead weight that only ever
+        # grows. Caught by `prune()` reporting rows nobody could see as dropped.
+        for pid in [p for p, row in data['cells'].items() if not row]:
+            data['cells'].pop(pid, None)
+
+    _write(table_key, _drop, st, flush='sync')
+    return hit[0]
+
+
+# ----------------------------------------------------------------------------- the VALUES
+def cells(table_key, pids, st=None):
+    """`{"<pid>": {field_key: value}}` for the rows named by `pids` — and ONLY those.
+
+    ⛔ `pids` IS REQUIRED. See the module header: this is the row wall expressed as a signature,
+    so a caller cannot get "every shared cell in the tenant" by forgetting an argument. Pass the
+    pool you have already scoped for this session.
+
+    An empty `pids` legitimately returns `{}` — a reader with no rows sees no cells, which is the
+    correct answer rather than a special case.
+    """
+    if pids is None:
+        raise TypeError('shared_overlay.cells: pids is required — pass the row set you have '
+                        'already scoped for this reader (there is deliberately no "all" call)')
+    wanted = {_pid(p) for p in pids}
+    if not wanted:
+        return {}
+    stored = _read(table_key, st)['cells']
+    return {pid: dict(row) for pid, row in stored.items()
+            if pid in wanted and isinstance(row, dict) and row}
+
+
+def snapshot(table_key, pids, st=None):
+    """`(fields, cells)` for `pids` — the shared stratum's SCHEMA and VALUES, from ONE read.
+
+    ⛔⛔ THIS EXISTS BECAUSE TWO READS OF THIS BUCKET CAN DISAGREE, AND THE DISAGREEMENT OPENS A
+    WALL. `perm_scope._enrich_for_wall` needs both halves: the schema decides WHICH user columns
+    the row wall may answer, and the cells are the values it answers with. Taking them as two
+    `st.get()` calls leaves a gap in which a concurrent write can land, and a wave-40 adversarial
+    probe drove exactly that: with the second read returning an emptied `cells`, a blank is merged
+    for a key the store cannot really serve and `custom_x is not West` flips from denying every row
+    to ADMITTING a row whose true value IS West. `is empty` does the same. The set and the values
+    must come from one snapshot or they are not talking about the same tenant state.
+
+    ⚠ `pids` IS REQUIRED, exactly as in `cells()` — the row wall expressed as a signature, so no
+    caller can get "every shared cell in the tenant" by forgetting an argument.
+    """
+    if pids is None:
+        raise TypeError('shared_overlay.snapshot: pids is required — pass the row set you have '
+                        'already scoped for this reader (there is deliberately no "all" call)')
+    stored = _read(table_key, st)
+    wanted = {_pid(p) for p in pids}
+    served = {pid: dict(row) for pid, row in stored['cells'].items()
+              if pid in wanted and isinstance(row, dict) and row} if wanted else {}
+    return dict(stored['fields']), served
+
+
+def put_cell(table_key, pid, field_key, value, st=None):
+    """Write ONE shared cell. Returns the value as stored (which may be truncated)."""
+    return put_cells(table_key, pid, {field_key: value}, st=st).get(str(field_key or ''))
+
+
+def put_cells(table_key, pid, values, st=None):
+    """Write several shared cells on one row, in one store update. Returns what was stored."""
+    row_id = _pid(pid)
+    clean = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
+    if not clean:
+        return {}
+
+    def _patch(data):
+        data['cells'].setdefault(row_id, {}).update(clean)
+
+    _write(table_key, _patch, st)
+    return clean
+
+
+def put_rows(table_key, rows, st=None):
+    """Write shared cells on MANY rows in ONE store update. Returns `{row_id: {key: value}}`.
+
+    ⭐⭐ THE WHOLE POINT IS THE *ONE*, AND IT IS NOT AN OPTIMISATION. `put_cells` is one row per
+    store write, so a 1,397-row catalog import is 1,397 download-modify-upload cycles against one
+    JSON document. This repo has a MEASURED scar for that shape: **18 writes against one document
+    under the store's coalescing single-flight landed ZERO while answering 200 eighteen times.**
+    Batching is what makes a bulk import land at all, not what makes it fast.
+
+    ⚠ It deliberately takes the WHOLE SET rather than accepting a stream: a caller that loops over
+    this function has simply rebuilt `put_cells` with extra steps, and the failure it reintroduces
+    is silent. If the set does not fit in memory it does not fit in this store either — that is a
+    signal to change substrate, not to chunk.
+
+    ⛔ NO CAP HERE, ON PURPOSE. The bound belongs at the DOOR, where a caller identity and a
+    reportable refusal exist (`routes_grid.bulk_cells`). A silent ceiling in a store primitive is
+    exactly the shape the standing no-cap rule forbids.
+    """
+    clean = {}
+    for pid, values in dict(rows or {}).items():
+        row_id = _pid(pid)
+        cells_for_row = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
+        if cells_for_row:
+            clean.setdefault(row_id, {}).update(cells_for_row)
+    if not clean:
+        return {}
+
+    def _patch(data):
+        for row_id, values in clean.items():
+            data['cells'].setdefault(row_id, {}).update(values)
+
+    # `flush='sync'` because a bulk import must be durable when the call returns: the caller is a
+    # script that will report "1,397 rows written" and exit, and an async flush would make that
+    # sentence a prediction rather than a fact.
+    _write(table_key, _patch, st, flush='sync')
+    return clean
+
+
+def clear_row(table_key, pid, st=None):
+    """Forget every shared cell on one row. True when there was something to forget."""
+    row_id = _pid(pid)
+    hit = [False]
+
+    def _clear(data):
+        hit[0] = data['cells'].pop(row_id, None) is not None
+
+    _write(table_key, _clear, st)
+    return hit[0]
+
+
+def prune(table_key, live_pids, st=None):
+    """Drop shared cells for rows that no longer exist. Returns how many rows were dropped.
+
+    ⛔ NOT a scoped read wearing another name, and the difference is the whole reason `cells()`
+    refuses to serve everything: `live_pids` here means *every row this TABLE has*, which is a
+    fact about the data, whereas `pids` in `cells()` means *every row this READER may see*, which
+    is a fact about the session. Calling this with one session's pool would delete the shared
+    values of every row that session cannot see. The name says which is which; so does this note.
+    """
+    keep = {_pid(p) for p in live_pids}
+    dropped = [0]
+
+    def _prune(data):
+        gone = [pid for pid in data['cells'] if pid not in keep]
+        for pid in gone:
+            data['cells'].pop(pid, None)
+        dropped[0] = len(gone)
+
+    _write(table_key, _prune, st, flush='sync')
+    return dropped[0]