Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
Download platform/core/grid_events.py from fsanyoto/runloopable: direct link, hf CLI and curl.
- Browser
- Download file 260 kB
-
https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/platform/core/grid_events.py
- Command line
-
hf download hf://spaces/fsanyoto/runloopable/platform/core/grid_events.py
-
curl -L -o grid_events.py https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/platform/core/grid_events.py
260 kB
"""core/grid_events.py β THE WRITE SEAM, lifted out of Streamlit (EXIT-1a, X1, 2026-07-30).
This is the grid's event handler: the code that takes an UNTRUSTED event object from the
browser component and decides what may be persisted. It was `app.py:_cl_handle_grid_event` /
`_cl_handle_one` and moved here as a PURE MOVE β no behavior change inside a move (MA principle
5). Every body below is the app.py body verbatim; the ONLY mechanical rewrites are the
Streamlit couplings the contract names:
st.session_state['_cl_grid_seen_ids'] -> ctx.seen_ids (adapter-owned dedup state)
st.session_state['_cl_doc_payload'] -> ctx.out.doc (EventResult.doc)
st.session_state['_cohort_toast'] -> ctx.out.toast (EventResult.toast)
st.session_state['cl_table_workspace'] -> ctx.fallback_ws (store-unavailable fallback)
is_admin() (the bare call inside doc_delete, and _cl_table_workspace's admin=None default)
-> ctx.admin
There is NO `import streamlit` in this file and there must never be one β `verify_no_streamlit.py`
enforces that with a `sys.meta_path` block, which is the only proof that survives refactoring.
(That gate was `verify_seam.py` until EXIT-6 retired it with `app.py`; the block, its negative
control and the AST walk moved over intact.)
ONE ADAPTER, ONE HANDLER β it was TWO until 2026-08-04:
* β the Streamlit adapter is GONE. `app.py::_cl_handle_grid_event` built an EventCtx whose
`seen_ids` and `fallback_ws` were session-state-backed dicts and applied the Result to session
state. EXIT-6 deleted it. The host-neutrality this file was written for is what let that
happen without touching a line of the handler β which is the argument for the design, recorded
at the moment it paid out.
* the HTTP adapter β `aios-web/api` builds an EventCtx with `fallback_ws=None`. A None
fallback with the store unavailable is a **503**, never a silent in-memory workspace: an
API request has no durable session dict to fall back to, so pretending to persist would
lose the write with a 200 on it.
β LAYERING, stated honestly. `core/` is not supposed to import `modules/` (ARCHITECTURE Β§1's
one-directional rule). This handler genuinely straddles: it is the WRITE half of the customer
table and its persistence verbs live in `modules.customer_data` / `modules.cohort`. The
contracted path for the strangler is `core/grid_events.py` (both adapters import it from here),
so the import stays and the violation is RECORDED rather than hidden. It is the one file in
`core/` that points up; when EXIT-5 ports the surfaces, the persistence verbs are what move
down, and this note is the marker for that work.
"""
import datetime as dt
import json as _json_ev # wave 23 (C7): the json field's parse wall
import re
from dataclasses import dataclass, field
from contextlib import contextmanager, nullcontext
from functools import wraps
# β ALIASED ON PURPOSE. `field` is imported above for the dataclasses that need it, and this file
# uses `field` as a LOCAL VARIABLE in a dozen handlers (`field = {'key': key, β¦}`). A
# `field(default_factory=list)` written inside one of those functions would resolve to the local
# dict and raise. The alias is unshadowable, so D-291's channel cannot be broken by a rename.
from dataclasses import field as dataclass_field
from typing import Callable, List, MutableMapping, Optional
import core.store as store
import core.table_store as _tstore # wave-9 I17: the shared-view authorisation predicates
#: β WAVE-27 item 5 (C7) β how many view ids one rail arrangement may name. Generous on purpose:
#: it bounds a hostile payload, not the user (the rail holds saved views + cohort projections +
#: shared views, and a busy Customer grid already carries dozens). An order longer than this is
#: not a person dragging rows.
MAX_VIEW_ORDER = 500
import core.user_tables as _ut_limits # wave 23 (C7): MAX_JSON_CELL β one ceiling, one definer
import harness.telemetry as _tel # _tel.error() = THE error sink (all caught errors log)
import modules.cohort as cohort_mod
#: C5 (owner item 12): customer documents. The cap is enforced HOST-side on the DECODED byte
#: count β the client checks the same number first, but a client check only spares the user a
#: pointless upload; this is what bounds what the tenant's dataset can be made to hold.
#: MOVED from app.py:1410β1412 with the handler (app.py re-imports these during the strangler).
_DOCS_KEY = 'customer_docs'
_DOC_MAX_BYTES = 5 * 1024 * 1024
_DOC_MAX_PER_ROW = 50
#: The props of a field def the CLIENT actually draws β the wave-6 no-blip comparison set.
#: Host-only stamps (createdBy, permissions) are deliberately absent: the client renders
#: nothing from its own copy of those, and a permissions refusal is answered explicitly.
_FIELD_ECHO_PROPS = ('label', 'type', 'note', 'options', 'colorCodeOptions',
'optionColors', 'max', 'formula', 'agg', 'scope', 'format', 'measure',
# W50-T05 / R4: how a numeric column READS (value / share / both). A key
# absent from this tuple is not refused, it is silently dropped from the
# echo while the route still answers 200 - so the reader sees the change
# land and then lose it. `showAs` is a DISPLAY mode, never an aggregate.
'showAs',
'recurrence', 'if',
# S76-T28: '' , 0 and false are real defaults, so this key compares by type.
'defaultValue')
#: What a source column's stored override may hold; its read-back takes these from the store only.
_SOURCE_OVERRIDE_KEYS = ('note', 'format', 'agg', 'measure', 'options', 'recurrence')
def _source_echo(accepted, durable):
"""A source column's durable definition: the contract's keys from `accepted`, overrides from the store.
A summary or a format may sit in the tenant-wide stratum alone, with no per-user row.
"""
if not isinstance(durable, dict):
return durable
return {**{k: v for k, v in accepted.items() if k not in _SOURCE_OVERRIDE_KEYS}, **durable}
class StoreUnavailable(RuntimeError):
"""The store is down AND the caller offered no durable fallback (HTTP adapter β 503).
The Streamlit adapter never sees this: it passes a session-state-backed `fallback_ws`, so
its store-down path degrades to the same captioned in-memory workspace it always had. An
API caller has no such dict, and the honest answer to "persist this" with nowhere to
persist it is an error β not a 200 over a write that evaporates.
"""
@dataclass
class EventResult:
"""What the HANDLER needs to tell its adapter β the three things it cannot do itself.
`rerender` is the old return value with its old meaning: "this page must re-render from
server state", NOT "handled" (see `handle_one`'s docstring β the distinction is the
difference between a snappy grid and a sluggish one).
"""
rerender: bool = False
doc: Optional[dict] = None # doc_fetch's answer β the bridge has no response channel
toast: Optional[str] = None # add_to_list's confirmation
#: ββ D-291 β WHY A WRITE WAS DECLINED. Until 2026-08-17 this door had NO disclosure channel
#: at all: `field_upsert` carries EIGHT distinct `return False` refusals and every one of them
#: answered `{"results":[{"id":"β¦","rerender":false}]}` β byte-identical to a success.
#: β THE COST WAS NOT THE MISSING MESSAGE, IT WAS THAT EVERY THEORY BECAME UNFALSIFIABLE.
#: D-275 (a custom field on the product grid answers 200 and is absent from a fresh read) sat
#: open across TWO waves because no amount of reading the source can say WHICH of the eight
#: fired on a given request β and the register's own advice is that reporting the cause IS the
#: diagnostic ([[report-the-cause-before-you-fix-it]]). D-276 is the precedent: shipping the
#: report first produced, in one deploy, a measurement that REFUTED a clean by-elimination
#: argument about the cause.
#: β SAFE BY CONSTRUCTION, and this is the check to re-run if a new refusal is added: every
#: entry describes the caller's OWN submitted event. It never names another user, another
#: tenant, or a row the caller cannot see β the failure mode D-276's `visible` flag exists to
#: avoid one layer up.
refusals: List[dict] = dataclass_field(default_factory=list)
writes: dict = dataclass_field(default_factory=dict)
write_id: str = ''
class AdmissionSnapshot:
"""Lend one request's workspace and grants to admission, never to a mutation callback."""
def __init__(self, runtime, uname, table_key, *, schema_only=False):
self._runtime, self.uname, self.table_key = runtime, uname, table_key
self.schema_only = bool(schema_only)
self._documents = {}
@property
def _grid_admission(self):
# A stored self-reference made every snapshot a reference cycle, so the row batches
# lent through it lived until the cycle collector ran (verify_overlay S80-T12 cap).
return self
def __getattr__(self, name):
return getattr(self._runtime, name)
def _holds(self, name):
return name in (self.table_key, 'object_shares')
def invalidate(self, *names):
"""Discard admission documents after canonical writes or fresh reads."""
for name in names or tuple(self._documents):
self._documents.pop(name, None)
def _document(self, name):
from copy import deepcopy
if name not in self._documents:
if self.schema_only and name == self.table_key:
value = self._runtime.get_projection(name, drop=('overlays',))
else:
read = getattr(self._runtime, '_read_strict', self._runtime.get)
value = read(name)
self._documents[name] = value or {}
return deepcopy(self._documents[name])
def get(self, name, fresh=False):
if fresh:
self.invalidate(name)
if self._holds(name) and not fresh:
return self._document(name)
return self._runtime.get(name, fresh=True) if fresh else self._runtime.get(name)
def _read_strict(self, name):
if self._holds(name):
return self._document(name)
return getattr(self._runtime, '_read_strict', self._runtime.get)(name)
def get_entry(self, name, entry):
if self._holds(name):
return self._document(name).get(str(entry))
return self._runtime.get_entry(name, entry)
def get_projection(self, name, drop=()):
if self._holds(name):
from core.store import _project
return _project(self._document(name), frozenset(drop))
return self._runtime.get_projection(name, drop=drop)
def update(self, name, *args, **kwargs):
try:
return self._runtime.update(name, *args, **kwargs)
finally:
self.invalidate(name)
def put(self, name, *args, **kwargs):
try:
return self._runtime.put(name, *args, **kwargs)
finally:
self.invalidate(name)
def request_admission(session, table_key, *, schema_only=False):
"""Bind a detached host session to a fresh tenant, user and table admission snapshot."""
from copy import copy
actor = copy(session)
runtime = session.runtime
if not (isinstance(runtime, AdmissionSnapshot) and runtime.uname == session.uname
and runtime.table_key == table_key and runtime.schema_only == bool(schema_only)):
while isinstance(runtime, AdmissionSnapshot):
runtime = runtime._runtime
runtime = AdmissionSnapshot(runtime, session.uname, table_key, schema_only=schema_only)
actor.runtime = runtime
return actor
@dataclass
class EventCtx:
"""Everything the handler is allowed to know, and nothing about how it is being served.
β `allowed_pids` is a SECURITY parameter: it is the pool this caller may touch at all, and
every row-scoped event (overlay_patch, doc_*, cohort membership, add_to_list, memberPids)
is intersected with it. `admin` and `uname` are likewise the HOST's statement of identity β
never anything the browser said about itself.
`seen_ids` deduplicates trusted/internal and fallback events within their context.
HTTP outbox delivery opts into `durable_receipts`; an active client PATCH captures its event too.
`fallback_ws` is the store-unavailable workspace home, the OUTER dict keyed by username
(exactly what `st.session_state.setdefault('cl_table_workspace', {})` is). HTTP passes
None, and None + store down raises StoreUnavailable (β 503).
`out` is the sink for the two parked answers, so `handle_one` can keep returning a bare
bool exactly as it did in app.py while doc/toast still escape. (Additive amendment to X1's
field list, 2026-07-30 β defaulted; recorded in the S1 mailbox.)
"""
uname: str
allowed_pids: frozenset
fields: list
measure_keys: frozenset = frozenset()
resolved_ids: frozenset = frozenset()
cohort_ids: frozenset = frozenset()
measure_offer: tuple = ()
visible_views: tuple = ()
admin: bool = False
#: β WAVE 15 C-PERM β the fields this caller's PERMANENT PERMISSIONS hide, transitive
#: closure included (`core.perm_scope.hidden_keys`). A SECURITY parameter in the same class
#: as `allowed_pids`, and here for the same reason: the read paths strip a hidden field from
#: both wires, so a caller cannot SEE it β but without this they could still WRITE it by
#: naming the key, because `overlay_keys` only asks whether the column exists. Empty means
#: "nothing hidden", which is every legacy record and therefore every caller today.
hidden_keys: frozenset = frozenset()
# Wave 45 R15: the transport adapter supplies the authority-aware recurrence validator.
# Core can normalise a recurrence's finite shape, but it cannot decide whether a named
# same/linked field is visible to this caller without reaching upward into the API layer.
recurrence_validator: Optional[Callable[[object], Optional[dict]]] = None
record_admitter: Optional[Callable[[int], bool]] = None
# Value-history restore reuses the ordinary cell wall. This stamp changes only the audit
# event kind and admits ``None`` as "remove the prior cell" after every normal field/row
# permission check has passed; browser-authored edits never set it.
history_kind: str = 'edit'
scope_key: str = 'customer'
#: Wave 16 C-TOPIC β the TABLE OPS this ctx reads and writes (a `core.table_store.make`
#: object). None = the CUSTOMER table (`modules.customer_data.TABLE_OPS`), which keeps
#: every existing caller byte-identical. The PRODUCT surface passes
#: `modules.product_data.TABLE_OPS` so its views/fields/overlays land in the product
#: bucket β never the customer one, whose pids are a different id space entirely.
table: Optional[object] = None
#: β WAVE 25 (R6b, closes DEBT D-16) β THE TENANT STORE HANDLE, and it is a RESIDENCY
#: parameter in the same class as `allowed_pids` is a security one. Everything this handler
#: could not reach through `ctx.table` used to go through the MODULE-LEVEL `core.store`,
#: i.e. tenant #0's dataset repo: the documents family, `_store_of(ctx).available()`, and β through
#: `_tops`' fallback β the whole customer and product table workspace. Owner, R6b:
#: *"Tenant 0 should not intertwine anywhere."*
#:
#: None keeps the module default, which is byte-identical for tenant #0 (empty prefix,
#: shared repo) and is what every non-HTTP caller still gets. The HTTP adapters pass
#: `session.runtime`, so a Nurilab write resolves against Nurilab.
st: Optional[object] = None
seen_ids: Optional[MutableMapping] = None
fallback_ws: Optional[MutableMapping] = None
out: EventResult = field(default_factory=EventResult)
# Trusted adapters supply activity attribution. Browser event payloads cannot override it.
by: Optional[str] = None
via: Optional[str] = None
durable_receipts: bool = False
#: The route's assembly workspace, lent to the first event only (`handle_one`).
workspace_lend: Optional[dict] = None
admission: Optional[AdmissionSnapshot] = None
def __post_init__(self):
# A caller that forgets `seen_ids` gets per-call dedup rather than a crash β the SET is
# what makes re-delivery idempotent, and its absence must not be the thing that decides
# whether an event is processed at all.
if self.seen_ids is None:
self.seen_ids = {}
def _store_of(ctx):
"""THE store handle this ctx reads and writes through (wave 25, R6b / D-16). ONE resolver,
so "whose repo does this land in" has exactly one answer per event.
Order, and each step is deliberate: the ctx's own tenant handle Β· else the handle the TABLE
OPS object was built with (`table_store.make(..., st=β¦)` keeps it on `.st`, which is how the
`ut_` path has been tenant-correct since wave 18) Β· else the module default.
β THE MODULE DEFAULT IS TENANT #0, AND THAT IS THE BUG D-16 NAMES β not a safe base case.
It is kept because it is byte-identical for tenant #0 (empty prefix, shared repo) and every
non-HTTP caller still relies on it; what changed is that the HTTP adapters now pass a real
handle, so the fallback is no longer what serves a Nurilab request. `verify_scopes` proves
that with a negative control: force this to fall through and the residency legs go RED.
"""
st = getattr(ctx, 'st', None)
if st is not None:
return st
tbl = getattr(ctx, 'table', None)
inner = getattr(tbl, 'st', None) if tbl is not None else None
return inner if inner is not None else store
def _admission_ctx(ctx):
"""Copy only admission readers while keeping the mutation context on its canonical store."""
snapshot = getattr(ctx, 'admission', None)
if snapshot is None:
return ctx
from copy import copy
from dataclasses import replace
st = _store_of(ctx)
from core.edit_receipts import CheckedStore
if isinstance(st, CheckedStore):
st = st.st
while hasattr(st, '_runtime'):
st = st._runtime
source = snapshot._runtime
while hasattr(source, '_runtime'):
source = source._runtime
if (st is not source or snapshot.uname != ctx.uname
or snapshot.table_key != _tops(ctx).table_key):
raise ValueError('admission snapshot does not match this tenant, user and table')
table = copy(_tops(ctx))
table._st = snapshot
return replace(ctx, st=snapshot, table=table, admission=None)
def _blobs(ctx):
"""The BYTE store for this ctx β `_store_of`'s sibling, split out because it is NOT yet
equivalent and pretending otherwise would hide a live residency hole.
β `TenantRuntime` exposes `get/put/update/exists/available` and **no byte methods**
(`harness/runtime.py`), so a tenant with its OWN repo has nowhere tenant-scoped to put a
document's BYTES. The metadata half of D-16 is fixed here; the byte half needs
`upload_bytes`/`download_bytes`/`delete_path` on the runtime, which is SESSION A's file β
asked for in the mailbox and booked as debt rather than papered over with a fallback that
reads as intentional. The moment those methods exist this resolver picks them up with no
other change, which is why it is written as a capability test and not as a version check.
"""
st = _store_of(ctx)
return st if hasattr(st, 'upload_bytes') else store
def _ag_overview_id():
"""`aios_grid.IG_OVERVIEW_ID`, resolved defensively.
Function-local import, this module's convention for the layer above it. Falls back to the
literal rather than raising: a store blip must not turn "refuse to delete" into "allow", and
an unguarded delete here is the one that reads as success and undoes itself.
"""
try:
import aios_grid as _ago
return _ago.IG_OVERVIEW_ID
except Exception:
return 'tpl_overview'
#: ββ W50-T25 (ruling R9 / contract C3) β THE `from` HALF OF AN AUDIT ROW, AND IT IS HONEST.
#: C3 asks every row for `from: {client, ip}`. `EventCtx` carries identity and residency and
#: deliberately nothing about transport (its own docstring: *"everything the handler is allowed
#: to know, and nothing about how it is being served"*), so this channel has NO request object
#: and therefore no client IP. It reports the channel and a NULL ip rather than inventing an
#: address, because a made-up `from` in the one record that exists to say where a change came
#: from is worse than an absent one. The REST doors in `routes_tables.py` DO have
#: `request.client.host` and report it.
EVENT_ORIGIN = {'client': 'grid-events', 'ip': None}
def _tops(ctx):
"""The table-ops object this ctx operates on β the customer table unless the caller chose
another topic. ONE resolution point so 'which bucket does this write land in' has exactly
one answer per event.
β WAVE 25 (R6b) β THIS FALLBACK IS STILL TENANT #0's, DELIBERATELY, AND IT IS THE ONE PIECE
OF THE RESIDENCY FIX THAT DID NOT LAND. `cl_mod.TABLE_OPS` is a module-level singleton built
with no store handle, so the customer and product table workspaces (views, fields, overlays,
folders) resolve to tenant #0 for every caller. Scoping it here was written, measured and
then REVERTED, because it would have been worse than the bug:
the WRITE door (`routes_grid._ctx`) is this session's file and now carries a handle;
the READ door is `routes_customers._ctx_for` / `routes_products` β files in NO session's
fence this wave β and they carry none.
Moving only the write side means a prefix tenant saves a view into `t/<slug>/β¦` and reads
back from the unprefixed bucket forever: their own view vanishes the moment they save it.
A latent split is worse than a stated residency error, and read and write must move in ONE
change. Booked as an ask + debt with that exact shape. Tenant #0 is unaffected either way
(empty namespace, default repo), which is why nothing today would have shown it.
β Untouched by this wave regardless: the EMIT GUARD is D-40, deferred by ruling A-15.
"""
if ctx.table is not None:
return ctx.table
import modules.customer_data as cl_mod
return cl_mod.TABLE_OPS
def _field_share_keys(ctx):
"""Return (shared storage key, grant topic) for this grid's field registry."""
raw = str(getattr(getattr(ctx, 'table', None), 'table_key', '') or '')
scope = str(getattr(ctx, 'scope_key', '') or '')
if raw == 'product_table_workspace' or scope == 'product':
return 'product_table_workspace', 'product_data'
if raw == 'customer_table_workspace' or scope in ('customer', 'cohort'):
return 'customer_table_workspace', 'customer_data'
if raw.startswith('ut_'):
bare = raw[:-len('_table_workspace')] if raw.endswith('_table_workspace') else raw
return bare, bare
if raw.endswith('_table_workspace'):
return raw, raw[:-len('_table_workspace')]
return raw, raw
def _sync_view_field_inheritance(ctx, view):
"""Apply C8 after a validated View save and notify the field owner/tenant admins.
``ctx.fields`` is already the caller's permission-projected schema. A key the editor cannot
read therefore never reaches the saved config or this boundary. New personal overlay fields
are promoted without changing ``createdBy`` so the inherited READ role points at a definition
the audience can actually receive; database-owned ``ut_*`` fields already live tenant-wide.
"""
from core import field_permissions as _fp
tops = _tops(ctx)
st = getattr(tops, 'st', None) or ctx.st
shared_key, grant_topic = _field_share_keys(ctx)
delta = _fp.sync_view_field_boundary(
view, grant_topic, ctx.uname, st=st, audit_additions=True)
added = list(delta.get('added') or ())
audience = list(delta.get('audience') or ())
if not audience:
return delta
by_key = {str(field.get('key')): field for field in (ctx.fields or ())
if isinstance(field, dict) and field.get('key')}
table_key = str(getattr(tops, 'table_key', '') or '')
# Check every included key, not only this save's delta. If a transient overlay failure left
# an edge pointing at a still-personal definition, the audience remains fail-closed and the
# next View save retries residency instead of treating the boundary as finished forever.
# Successful promotions are idempotent because the projected schema then reports shared=True.
included = _fp.view_field_keys(view)
if not table_key.startswith('ut_'):
for key in included:
field = by_key.get(key)
if not isinstance(field, dict) or field.get('shared') is True:
continue
owner = str(field.get('createdBy') or '').strip().lower()
if not owner or owner != str(ctx.uname or '').strip().lower():
continue
try:
promoted = _fp.promote_field(
table_key, shared_key, grant_topic, owner, field, st=st)
by_key[key] = promoted
except Exception as exc: # noqa: BLE001
# Fail closed: the boundary alone cannot surface a definition that stayed
# personal. Report the infrastructure failure without putting field values in
# logs; every later live-audience save retries the idempotent promotion.
_tel.error('grid_events:view-field-promotion', exc)
if not added:
return delta
# Addition notifications are working-inbox facts, not permission authority. Send one small
# row per field/recipient and never let an inbox outage roll back an already accepted View.
try:
import core.alerts as _alerts
import core.perms as _perms
import core.shares as _shares
import core.users as _users
registry = _users.registry() or {}
tenant = str(getattr(st, 'key', '') or '').strip().lower()
admins = {
str(username).strip().lower()
for username, record in registry.items()
if isinstance(record, dict) and _perms.is_admin(record)
and (not tenant or str(record.get('tenant') or 'royal-imports').strip().lower() == tenant)
}
view_id = str((view or {}).get('id') or '')
view_name = str((view or {}).get('name') or 'this View')[:160]
actor = str(ctx.uname or '').strip().lower()
for key in added:
field = by_key.get(key) or {}
direct = _shares.grants(
'field', _shares.field_oid(grant_topic, key), st=st)
owner = str(direct.get('owner') or field.get('createdBy') or '').strip().lower()
recipients = set(admins)
if owner:
recipients.add(owner)
label = str(field.get('label') or key)[:160]
for recipient in sorted(recipients - {actor, ''}):
_alerts.notify(
recipient, 'Field added to a shared View', topic='share',
key=f'view-field:{view_id}:{key}', row_id=view_id,
detail=f'{label} was added to {view_name}. Its audience can now read it.',
target={"module": "database", "id": grant_topic, "tab": view_id},
actor=actor, st=st)
except Exception as exc: # noqa: BLE001
_tel.error('grid_events:view-field-notification', exc)
return delta
def _field_share_role(ctx, key, definition):
"""Return the specific Share field role, if this definition is governed by it.
``shared`` names tenant-wide storage residency. Only the explicit ``granted`` marker says
that a field's registry role replaces its ordinary collaborative permission bag.
"""
if not isinstance(definition, dict) or definition.get('granted') is not True:
return None
try:
import core.shares as _shares
_storage_key, topic = _field_share_keys(ctx)
return _shares.role_for(
'field', _shares.field_oid(topic, key), ctx.uname,
is_admin=ctx.admin, st=_store_of(_admission_ctx(ctx)))
except Exception:
return None
def _may_edit_field_definition(ctx, key, definition):
"""The server wall for rename/type/settings edits on a field."""
if not isinstance(definition, dict):
return bool(ctx.admin)
if ctx.admin:
return True
owner = str(definition.get('createdBy') or '').strip().lower()
if owner and owner == str(ctx.uname or '').strip().lower():
return True
if definition.get('granted') is True:
return _field_share_role(ctx, key, definition) in ('owner', 'edit')
if not owner:
return False
from core import field_permissions as _fp
perms = _fp.stored_permissions(definition, fallback='collaborative')
edit = perms.get('edit')
return edit == 'collaborative' or (
edit == 'users' and str(ctx.uname).lower() in {
str(user).lower() for user in (perms.get('users') or [])})
def may_edit_field_definition(ctx, key, definition):
"""The definition wall, for doors outside the event bus (`routes_grid.grid_choice_remove`).
ONE evaluator for "may this caller change this field's definition": the REST door asks the
same function `field_upsert` and `choice_rename` ask, so removing an option cannot be
admitted for a caller who could not have renamed one.
"""
return _may_edit_field_definition(ctx, key, definition)
def _may_edit_field_value(ctx, key, definition):
"""The value-write wall; ordinary source-overlay fields remain collaborative by default."""
if not isinstance(definition, dict):
return bool(ctx.admin)
if ctx.admin:
return True
owner = str(definition.get('createdBy') or '').strip().lower()
if owner and owner == str(ctx.uname or '').strip().lower():
return True
if definition.get('granted') is True:
return _field_share_role(ctx, key, definition) in ('owner', 'edit')
from core import field_permissions as _fp
perms = _fp.stored_permissions(definition, fallback='collaborative')
edit = perms.get('edit')
return edit == 'collaborative' or (
edit == 'users' and str(ctx.uname).lower() in {
str(user).lower() for user in (perms.get('users') or [])})
def _may_override_source_value(definition):
"""One source-backed value may write through the ordinary overlay door.
The canonical field contract must carry the capability and the field identity must still be
Maps. Requiring both prevents a copied or caller-forged flag from widening every Odoo field.
"""
return (isinstance(definition, dict)
and definition.get('key') == 'maps_url'
and definition.get('source') == 'odoo'
and definition.get('valueOverride') == 'overlay')
def _cohorts(ctx):
"""The COHORT store this ctx operates on β `_tops`'s sibling, and here for the same reason.
β WAVE 19 / R9: a cohort belongs to its database. Every cohort verb below used to name
`cohort_mod` directly, so a list built on the Product surface landed in `customer_cohorts`
beside somebody's real customer lists β with PRODUCT pids in it (CRC32 hashes of SKU codes),
which the customer page would then try to resolve against partner ids. Wave 16 answered that
by REFUSING cohorts on other topics (`with_cohorts=False`); R9 says scope-parameterize
instead. `modules.cohort.scoped` returns the module itself for the customer topic, so the
customer path is byte-unchanged.
"""
return cohort_mod.scoped(ctx.scope_key, st=_store_of(ctx))
#: The keys a stored document entry may put on the wire. β `path` IS NOT ONE OF THEM β it is the
#: byte address inside the tenant's repo, of no use to a browser and a needless disclosure of the
#: store's layout. `canDelete` is not stored either: it is a fact about the READER, computed per
#: request below, so one person's answer can never be cached into another's.
_DOC_WIRE_KEYS = ('id', 'name', 'mime', 'size', 'by', 'ts')
def docs_for(pids, scope_key='customer', uname='', admin=False, st=None):
"""`{"<pid>": [CustomerDoc, ...]}` for a SCOPED row set β the producer `payload.docs` lost.
ββ WAVE 30 / CONTRACT C4 (D-138). The write door has been live and UNREACHABLE since EXIT-6:
`doc_add`/`doc_fetch`/`doc_delete` all still work, and the comment inside that handler says
exactly why nobody noticed β *"the React shell cannot reach it yet (`payload.docs` is set only
by app.py)"*. `app.py` was deleted, and the producer went with it. Every client half survived:
`RecordDetail`, `SwipeView` and `Documents` are complete, and all six `onDoc*` handlers in
`CustomerGrid.tsx` are written as `payload?.docs ? β¦ : undefined`, so an ABSENT `docs` key is
what has been switching the whole feature off. An empty dict is truthy and turns it on with an
honest empty state.
β THIS IS THE SIXTH INSTANCE OF THE REACHABILITY CLASS and the one `verify_reachability.py`
cannot see β a payload key assembled through helpers and dict merges is not a text-matchable
literal ([[reachable-is-not-the-same-as-built]], [[artifact-with-no-importer]]).
β ONE READER, NOT A MATCHING PAIR. `routes_tables` (ut_*) and `routes_customers` (the customer
scope) both call THIS β they do not each serialise. Two surfaces answering one question
separately is how the same defect got reintroduced in the opposite direction inside a single
commit ([[one-question-two-normalizers]]).
β `pids` IS REQUIRED and is the row set the CALLER has already scoped β `shared_overlay.cells`'
argument, for the same reason: there is no "every document in the tenant" call to reach for.
A record with no documents gets `[]`, never a missing key, so a client can tell "none" from
"not served".
"""
wanted = {str(int(p)) for p in (pids or [])}
if not wanted:
return {}
scope = str(scope_key or 'customer').strip().lower()
key = _DOCS_KEY if scope in cohort_mod.LEGACY_SCOPES else f'{scope}_docs'
try:
stored = (st if st is not None else store).get(key) or {}
except Exception: # noqa: BLE001
stored = {} # a display read degrades; it never breaks the grid
out = {}
for pid in wanted:
row = stored.get(pid)
docs = []
for d in (row if isinstance(row, list) else []):
if not isinstance(d, dict) or not d.get('id'):
continue
wire = {k: d.get(k) for k in _DOC_WIRE_KEYS}
# The delete wall, mirrored onto the wire so the button is absent rather than
# offered-and-refused. `doc_delete` enforces the same test server-side; this is the
# DISPLAY of that rule, never a substitute for it.
wire['canDelete'] = bool(admin or (d.get('by') and d.get('by') == uname))
docs.append(wire)
out[pid] = docs
return out
def _docs_key(ctx):
"""The DOCUMENTS bucket this ctx operates on β `_cohorts`'s sibling (wave 19, item 12's
silent third case).
β `_DOCS_KEY` STAYS the module constant with its shipped value: app.py re-imports it for the
Streamlit docs payload and `verify_seam.py` asserts the two resolve to the same string. This
resolves the CUSTOMER topic to exactly that constant and gives every other database its own
bucket, so the pid keys inside one bucket all come from one id space.
"""
scope = str(getattr(ctx, 'scope_key', '') or 'customer').strip().lower()
if scope in cohort_mod.LEGACY_SCOPES:
return _DOCS_KEY
return f'{scope}_docs'
# ------------------------------------------------------------------ the workspace family (X1 amd.)
def _grant_marker(ctx, ws, uname=None):
"""`has_grants(view_id) -> bool` for this tenant, or None when nothing here is granted at all.
The grant registry is the only View-audience model. Direct grants and grants inherited from
a folder both count. The closure reads the tenant grant bucket once, then marks personal
source views without persisting display-only metadata back into the workspace document.
"""
import core.shares as shares
# The SAME store handle `_granted_views` resolves, and asked for the same reason: the grants
# bucket is tenant-scoped and must be read out of the tenant whose workspace this is. Written
# as `_tops(ctx).st` rather than `_store_of(ctx)` so the two legs cannot drift on tenancy.
st = getattr(_tops(ctx), 'st', None)
view_oids = shares.granted_oids('view', st=st, viewer=uname)
folder_oids = shares.granted_oids('folder', st=st)
if not view_oids and not folder_oids:
return None # nothing in this tenant is granted: no marks, no closure
# β `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, β¦}`) β reading item
# ids off the top level finds the surface NAMES and matches nothing, which is the same trap
# `table_store.find_folder` carries a note about. It is already in the payload above, so the
# folder leg costs no extra store read.
placed = (ws.get('itemFolders') or {}).get('views') or {}
def _has_grants(view_id):
key = str(view_id)
if key in view_oids:
return True
fid = str(placed.get(key) or '')
# `fid` truthiness FIRST: '' must never match a grant stored under the empty-string oid,
# which would mark every unfiled view at once.
return bool(fid and fid in folder_oids)
return _has_grants
#: S67-T39 / R36: the Application registry's store key. READ here, never imported:
#: `application_registry` lives in the api layer and core never imports up (ARCHITECTURE).
_APPLICATIONS_KEY = 'applications_v1'
_APPLICATION_RECORD_PREFIX = 'applications_v1_app/'
def _live_application_ids(ctx):
"""The set of App ids the tenant registry holds, or None when that is not KNOWN.
None means a read failed or a document is malformed, so no binding can be stripped.
"""
try:
st = _store_of(ctx)
doc = st.get(_APPLICATIONS_KEY)
apps = {} if doc is None else doc.get('applications', {}) if isinstance(doc, dict) else None
if not isinstance(apps, dict):
return None
live = {str(key) for key in apps}
listing = getattr(st, 'list_keys', None)
if not callable(listing):
return live
keys = listing(_APPLICATION_RECORD_PREFIX)
reader = getattr(st, 'get_many', None)
records = reader(keys) if keys and callable(reader) else None
if records is None:
records = {key: st.get(key) for key in keys}
tenant = getattr(st, 'key', None) or getattr(st, 'tenant_slug', None)
for key in keys:
record = records.get(key)
if record is None:
continue
applications = record.get('applications', {}) if isinstance(record, dict) else None
if not isinstance(applications, dict) or len(applications) > 1:
return None
for identity, app in applications.items():
if (not isinstance(app, dict) or app.get('id') != identity
or (tenant is not None and app.get('tenant') != tenant)):
return None
live.update(str(identity) for identity in applications)
return live
except Exception as exc:
_tel.error('applications:live', exc)
return None
def _application_ref_id(view):
config = view.get('config') if isinstance(view, dict) else None
ref = config.get('application') if isinstance(config, dict) else None
return str(ref.get('id') or '') if isinstance(ref, dict) else None
def _drop_dead_application_refs(ctx, views):
"""S67-T39 / R36 / D-2233: a View bound to a DELETED App is served as a plain view of its
database (the `application` member dropped, everything else kept), so it opens with no
error. Projection only, and it never raises: any failure serves the views unchanged.
The registry is read only when some View actually carries a reference.
"""
try:
if not any(_application_ref_id(v) is not None for v in (views or {}).values()):
return views
live = _live_application_ids(ctx)
if live is None:
return views
out = {}
for vid, view in views.items():
ref_id = _application_ref_id(view)
if ref_id is not None and ref_id not in live:
config = {k: v for k, v in view['config'].items() if k != 'application'}
view = {**view, 'config': config}
out[vid] = view
return out
except Exception as exc:
_tel.error('applications:dead_refs', exc)
return views
def workspace_corrections(st, table_key, uname, assembly):
"""Only the workspace render wire spends pending acknowledgements, after the memo read."""
# Only the memoised path sets the flag. An absent flag is unknown, so read the workspace.
if assembly.get('_pending_corrections') is False:
return assembly
from core.table_store import TableStore
fields = TableStore(table_key, st=st).workspace(uname, consume_corrections=True)['fields']
acknowledgements = {key: value for key, value in fields.items()
if isinstance(value, dict) and value.get('labelCorrectionId')}
for target in (assembly.get('fields') or [], assembly.get('workspace', {}).get('fields') or []):
for field in target:
ack = acknowledgements.get(field.get('key'))
if ack and ack.get('label') == field.get('label'):
field.update({key: ack[key] for key in ('labelCorrectedFrom', 'labelCorrectionId')})
for key, ack in acknowledgements.items():
field = (assembly.get('ws', {}).get('fields') or {}).get(key)
if isinstance(field, dict) and ack.get('label') == field.get('label'):
field.update({name: ack[name] for name in ('labelCorrectedFrom', 'labelCorrectionId')})
return assembly
def table_workspace(ctx, allowed_pids=None, consume_corrections=True, capture_document=False,
*, include_views=True, admission=True):
"""Durable Airtable-style view/schema/overlay state, with an honest session fallback.
Wave-9 I17: the returned `views` are this user's OWN views MERGED with every view SHARED
with them. Own views win a same-id collision β a personal view is the user's own object and
must never be shadowed by somebody else's share.
β W40-T01 (owner instruction 2, contract C1): every view that HAS grants carries
`hasShares: True` whoever is asking, and the copy belonging to the account doing the sharing
additionally carries `sharedOut: True`. Stamped on ALL THREE merge legs from ONE predicate
(`_grant_marker`), on the PROJECTION only, and never written back.
β `allowed_pids` is a SECURITY parameter, not a convenience. A shared view carries
`memberPids`, which the writer's scope validated on the way IN β but the READER may have a
narrower scope. Handing a Fisch-scoped user a view whose member list was built by a
full-access user would leak the other BU's customers straight through the strict-isolation
rule. So membership is re-filtered against the READER on the way OUT. Pass it wherever the
result reaches a renderer or an event handler; omitting it drops memberPids entirely rather
than trusting the stored list (fail-closed: a smaller view, never a wider one).
MOVED from app.py:5323 (`_cl_table_workspace`). `admin` was a parameter defaulting to a live
`is_admin()` call; it now always comes from `ctx.admin`, which is identical at the one call
site because app.py computes `admin = bool(is_admin())` once per render. `allowed_pids`
stays an EXPLICIT argument because the folder leg deliberately omits it.
"""
original_ctx = ctx
ctx = _admission_ctx(ctx) if admission else ctx
uname = ctx.uname
if _store_of(ctx).available():
# Wave 48 C3: this is the only runtime transition door. It either promotes every
# validated legacy source into the modern model or raises before legacy data is deleted;
# there is deliberately no read-through to ``__shared__.views`` below.
read = _tops(ctx).workspace(
uname, consume_corrections=bool(consume_corrections),
include_document=bool(capture_document))
if capture_document:
ws, ctx.workspace_document = read
original_ctx.workspace_document = ctx.workspace_document
else:
ws = read
if not include_views:
# Field admission still receives the full authored field and shared-field documents.
return {**ws, 'views': {}}
document = ctx.workspace_document if capture_document else None
# β WAVE 21 (item 9, C1): the R10 registry's named-user grants, PROJECTED at last.
# Wave 20 wrote view grants and no reader ever consulted them β "Share viewβ¦" recorded
# a row and changed nothing on the receiver's screen.
try:
granted = _granted_views(ctx, uname)
except Exception as _ge:
_tel.error('sharedviews:granted', _ge)
granted = {}
# C4/R9: assignments are not generic shares with a different label.
# They arrive from their own immutable-filter registry and are merged
# only into the recipient's projection.
try:
assigned = _tops(ctx).assigned_views(
uname, allowed_pids, document=document)
except Exception as _ae:
_tel.error('assignedviews:read', _ae)
assigned = {}
# `granted` is already stamped. Mark owner sources separately so their display metadata
# stays symmetric with recipient projections without creating a second copy or audience.
try:
_has_grants = _grant_marker(ctx, ws, uname) if ws.get('views') else None
except Exception as _me:
# A share mark is DECORATION. It must never be the thing that takes down a workspace
# read, so it fails the way its two siblings above do: log and carry on unmarked.
_tel.error('sharedviews:marks', _me)
_has_grants = None
if _has_grants:
ws['views'] = {
vid: ({**v, 'hasShares': True, 'sharedOut': True}
if isinstance(v, dict) and _has_grants(vid) else v)
for vid, v in (ws.get('views') or {}).items()}
if granted or assigned:
merged = dict(granted)
merged.update(assigned) # dedicated recipient projection
merged.update(ws.get('views') or {}) # own views win the id collision
ws['views'] = {vid: scope_view(v, uname, allowed_pids)
for vid, v in merged.items()}
if ws.get('views'):
ws['views'] = _drop_dead_application_refs(ctx, ws['views'])
return ws
# Store down. Streamlit degrades to its captioned session workspace exactly as before; an
# API caller has no durable dict and must be told, not quietly served memory.
if ctx.fallback_ws is None:
raise StoreUnavailable('table workspace unavailable: no store and no session fallback')
return ctx.fallback_ws.setdefault(
uname, {'views': {}, 'fields': {}, 'overlays': {}})
#: ββ W41-T14 Β· OWNER INSTRUCTION 11 Β· CONTRACT C9 β THE GRANTED FOLDER'S OWN RECORD.
#:
#: β THE ICON WAS NEVER LOST IN TRANSIT; IT WAS NEVER SENT. `_granted_views` stamped
#: `v['sharedFolder'] = <name>` and nothing else, so `folders.ts::groupByFolder` RECONSTRUCTS
#: `{id: sharedFolderGroupId(owner, name), name}` for the receiver's rail β a folder assembled out
#: of two strings, with no icon on it β and `icons.tsx::FolderMark` then falls back to its default
#: shape and tone. That fallback is exactly what the owner is reporting. The record was always in
#: hand: `table_store.find_folder` returns `dict(hit)`, the whole stored row, icon included.
#:
#: β ADDITIVE, AND THAT IS THE CONTRACT DECISION. `sharedFolder` KEEPS its string type and its
#: meaning: `aios-web/web/verify_folders.py` asserts `typeof v.sharedFolder === "string"` and
#: `api/verify_api.py` reads the same key, so retyping it to a record would turn two gates red and
#: blank the receiver's grouping until the client half (W41-T35) lands. C8's rule one bullet above
#: C9 β *absent keys mean "not built yet", never "false"* β is what lets the two halves land in
#: either order, and [[two-lanes-one-contract-dead-feature]] is the scar it exists to prevent.
#:
#: β THE CLIENT MUST NOT USE THIS `id` AS THE GROUP KEY. `folders.ts::SHARED_FOLDER_PREFIX` says
#: it in its own words β *"NOTHING MAY EVER WRITE ONEβ¦ no `order`, no icon, no row in `folders`"* β
#: and every rail affordance gates on `isSyntheticFolderId`. Swapping the synthetic group id for
#: this real one would let the receiver emit `item_move` / `folder_rename` against a folder that
#: lives in somebody ELSE's store. `id` is here to identify the share, never to key the group.
#:
#: β `parent` IS DELIBERATELY NOT FORWARDED, which is why C9 spells it `parent?`. A parent id
#: names a folder in the OWNER's stratum that was NOT granted: the receiver cannot resolve it,
#: must not store it, and would gain only a pointer into a tree they cannot see. One folder is
#: shared, so one folder is delivered, flat.
#:
#: β BUILT MEMBER BY MEMBER, never `dict(folder)`. This row comes out of another account's
#: workspace; forwarding it whole would carry whatever else happens to be sitting on it across a
#: user boundary. The icon goes back out through `aios_grid.clean_folder_icon` β the ONE server
#: whitelist (12 shapes, 5 tones, and the legacy `grey` tone canonicalised) β so a receiver can
#: never be handed a shape no client knows how to draw.
#: ββ W41-T20's DONE-WHEN CLAUSE 5, LANDED BY THE INTEGRATOR. Lane B proved BOTH ways that a
#: saved pivot round-trips to `None` without this, and correctly refused to write it: this file
#: is lane A's fence. The clause named a file its own ticket did not own, so it was
#: undischargeable by construction. [[two-lanes-one-contract-dead-feature]]
#:
#: β THE KEY IS WRITTEN UNCONDITIONALLY, like `important` above and unlike `cohortLock`. The
#: client CLEARS a pivot by omitting the key (`CustomerGrid.tsx:7195`
#: `const { secondaryView: _cleared, ...rest } = config`), so both spellings happen to clear
#: correctly today -- but this dict is REBUILT FROM THE ALLOWLIST on every autosave, and a
#: conditional key is one client change away from a pivot you can set and never clear. Lane A's
#: own note at :1331-1334 argues this for `important`; every word of it applies here.
#:
#: β FAIL-CLOSED ON `database` AND `viaField`, matching `types.ts::cleanSecondaryView` exactly:
#: a pivot missing either cannot be served by anything, so it stores as ABSENT (the ordinary view
#: of this table) rather than as a pivot that renders an empty grid reading as
#: "no related records" -- the distinction C10's `refusal` key exists to preserve.
#:
#: β THE NESTED `config` IS BOUNDED, NOT KEY-VALIDATED, AND THAT IS DELIBERATE. Its filters name
#: columns of the TARGET database, whose field list is not resolvable from this door -- `cfg`'s
#: `valid_keys` belong to the SOURCE. `routes_grid.py::pivot` already takes `filters` from the
#: request body as a raw list (`:1201`) and owns their semantics, so validating here would either
#: duplicate that or reject a legal tree. What this does own is SHAPE and SIZE, so nothing
#: unbounded reaches the store.
_SECONDARY_WINDOWS = ('all', 'last12m', 'ytd') # routes_grid.PIVOT_WINDOWS' key set
def _clean_secondary_view(raw):
"""C6 -- the stored shape of a Relational pivot, or None. Mirrors `types.ts::cleanSecondaryView`."""
if not isinstance(raw, dict):
return None
database = str(raw.get('database') or '').strip()[:80]
via_field = str(raw.get('viaField') or '').strip()[:120]
if not database or not via_field:
return None # fail-closed: see the note above
window = raw.get('window')
cfg = raw.get('config') if isinstance(raw.get('config'), dict) else {}
height = cfg.get('rowHeightMode')
def _keys(value, cap):
return [str(k)[:120] for k in list(value or [])[:cap] if isinstance(k, str)] \
if isinstance(value, list) else []
widths = {}
if isinstance(cfg.get('widths'), dict):
for k, v in list(cfg['widths'].items())[:400]:
try:
widths[str(k)[:120]] = int(v)
except (TypeError, ValueError):
continue
return {
'database': database,
'viaField': via_field,
'window': window if window in _SECONDARY_WINDOWS else 'all',
'config': {
'filters': list(cfg.get('filters') or [])[:200] if isinstance(cfg.get('filters'), list) else [],
'filterConj': 'or' if cfg.get('filterConj') == 'or' else 'and',
'sorts': list(cfg.get('sorts') or [])[:20] if isinstance(cfg.get('sorts'), list) else [],
'groupBy': str(cfg['groupBy'])[:120] if isinstance(cfg.get('groupBy'), str) and cfg['groupBy'] else None,
'colorBy': str(cfg['colorBy'])[:120] if isinstance(cfg.get('colorBy'), str) and cfg['colorBy'] else None,
'rowHeightMode': height if height in ('compact', 'medium', 'tall') else 'short',
'order': _keys(cfg.get('order'), 400),
'visible': _keys(cfg.get('visible'), 400),
'widths': widths,
},
}
_SERVER_VIEW_MEMBERS = frozenset({
'cohortLock', 'createdBy', 'updatedAt', 'filterRemovals', 'kind',
})
_VIEW_POSITION = re.compile(r'[0-9A-Za-z]{1,64}\Z')
@dataclass
class _ViewMemberCtx:
"""Lend create-time filter accounting without changing the request context."""
source: EventCtx
filter_removals: list = field(default_factory=list)
filter_budget: Optional[list] = None
def __getattr__(self, name):
return getattr(self.source, name)
def _view_member_refusal(member, code, message):
return None, {'member': member, 'code': code, 'message': message}
def _view_field_key(key, valid_keys):
return '__zone__' if key == 'zone' and '__zone__' in valid_keys else key
def _clean_view_sort(value):
if not isinstance(value, dict) or value.get('dir') not in ('asc', 'desc'):
return None
result = {'dir': value['dir']}
# Legacy sort arrays have no position. Explicit positions follow the C1 alphabet.
if 'pos' in value:
if not isinstance(value['pos'], str) or not _VIEW_POSITION.fullmatch(value['pos']):
return None
result['pos'] = value['pos']
if value.get('locked') is True:
result['locked'] = True
return result
def _clean_view_summary(value):
import aios_grid as _ag
if not isinstance(value, dict):
return None
agg = value.get('agg')
# Share is a stored picker choice. It is not a query aggregate.
if agg not in (*_ag.SUMMARY_AGGS, 'none', 'share'):
return None
result = {'agg': agg}
if agg == 'percentile':
try:
result['p'] = max(0, min(100, round(float(value.get('p')))))
except (TypeError, ValueError, OverflowError):
return None
return result
def _clean_view_filter(value, ctx, valid_keys):
import aios_grid as _ag
node = value['node']
# C1 creates an empty group before separate operations attach its children.
if node.get('children') == []:
cleaned = {'conj': 'or' if node.get('conj') == 'or' else 'and', 'children': []}
if isinstance(node.get('id'), str):
cleaned['id'] = node['id'][:64]
return {'node': cleaned, 'parent': value.get('parent')}
migrated = _ag.migrate_zone_projection_config({'filters': [node]})['filters']
filter_removals = getattr(ctx, 'filter_removals', None)
if filter_removals is None:
filter_removals = []
# Measures belong to filters only. Every other member uses table fields.
nodes = _ag.clean_filter_tree(
migrated, valid_keys | set(ctx.measure_keys),
budget=getattr(ctx, 'filter_budget', None), cohort_ids=set(ctx.cohort_ids),
visible_view_ids={str(view['id']) for view in ctx.visible_views
if isinstance(view, dict) and view.get('id')},
report=filter_removals)
if not nodes:
return None
cleaned = nodes[0]
if isinstance(node.get('children'), list) and isinstance(node.get('id'), str):
cleaned['id'] = node['id'][:64]
return {'node': cleaned, 'parent': value.get('parent')}
def clean_view_member(member, value, ctx, prior):
"""Return one cleaned C1 member or a refusal before either write door applies it."""
def refuse(code, message):
return _view_member_refusal(member, code, message)
if not isinstance(member, str):
return refuse('unknown_member', 'Choose a supported View setting.')
family, separator, key = member.partition(':')
if family in _SERVER_VIEW_MEMBERS:
return refuse('server_member', 'The server sets this View setting.')
field_families = ('hidden', 'sort', 'width', 'position', 'summary')
scalar_families = ('group', 'display', 'name', 'note', 'locked', 'colorBy',
'rowHeightMode', 'frozenCount', 'important', 'secondaryView',
'application', 'fullscreen', 'filterConj')
if (family not in (*field_families, *scalar_families, 'filter', 'memberPid')
or (family in (*field_families, 'filter', 'memberPid') and not separator)
or (family in scalar_families and separator and family != 'filterConj')):
return refuse('unknown_member', 'Choose a supported View setting.')
valid_keys = {item['key'] for item in ctx.fields}
if family in field_families:
key = _view_field_key(key, valid_keys)
if key not in valid_keys:
return refuse('unknown_field', 'Choose a field in this table.')
if family == 'hidden' or family in ('locked', 'important', 'fullscreen'):
if not isinstance(value, bool):
return refuse('invalid_boolean', 'Choose true or false for this View setting.')
return value, None
if family == 'sort':
cleaned = _clean_view_sort(value)
return ((cleaned, None) if cleaned is not None else
refuse('invalid_sort', 'Choose a sort direction and a valid position.'))
if family == 'width':
try:
return max(60, min(600, round(float(value)))), None
except (TypeError, ValueError, OverflowError):
return refuse('invalid_width', 'Choose a numeric column width.')
if family == 'position':
if isinstance(value, str) and _VIEW_POSITION.fullmatch(value):
return value, None
return refuse('invalid_position', 'Use 1 to 64 letters or digits for the column position.')
if family == 'summary':
cleaned = _clean_view_summary(value)
return ((cleaned, None) if cleaned is not None else
refuse('invalid_summary', 'Choose a supported column summary.'))
if family == 'memberPid':
try:
pid = int(key)
except (TypeError, ValueError):
pid = None
admit_record = getattr(ctx, 'record_admitter', None)
if pid not in (ctx.allowed_pids or ()) and not (
isinstance(pid, int) and 0 < pid < 2**63 and callable(admit_record)
and admit_record(pid)):
return refuse('unknown_record', 'Choose a record available in this table.')
if not isinstance(value, bool):
return refuse('invalid_boolean', 'Choose true or false for record membership.')
return value, None
if family == 'filter':
if (not key or len(key) > 64 or not isinstance(value, dict)
or not isinstance(value.get('node'), dict)
or (value.get('parent') is not None and
(not isinstance(value['parent'], str) or not value['parent']
or len(value['parent']) > 64))):
return refuse('invalid_filter', 'Choose a valid filter condition and parent group.')
try:
cleaned = _clean_view_filter(value, ctx, valid_keys)
except (TypeError, ValueError, OverflowError):
cleaned = None
return ((cleaned, None) if cleaned is not None else
refuse('invalid_filter', 'Choose a filter available in this table.'))
if family == 'filterConj':
if (separator and (not key or len(key) > 64)) or value not in ('and', 'or'):
return refuse('invalid_conjunction', 'Choose "and" or "or" for the filter group.')
return value, None
if family in ('group', 'colorBy'):
value = _view_field_key(value, valid_keys)
if value is None or (isinstance(value, str) and value in valid_keys):
return value, None
return refuse('unknown_field', 'Choose a field in this table.')
if family == 'name':
name = str(value or '').strip()[:120]
return ((name, None) if name else
refuse('invalid_name', 'Give this View a name.'))
if family == 'note':
return str(value or '')[:2000], None
if family == 'rowHeightMode':
if value in ('compact', 'short', 'medium', 'tall'):
return value, None
return refuse('invalid_row_height', 'Choose a supported row height.')
if family == 'frozenCount':
try:
return max(1, min(8, int(value))), None
except (TypeError, ValueError, OverflowError):
return refuse('invalid_frozen_count', 'Choose a numeric frozen column count.')
if family == 'secondaryView':
try:
cleaned = _clean_secondary_view(value)
except (TypeError, ValueError, OverflowError):
cleaned = None
return ((cleaned, None) if value is None or cleaned is not None else
refuse('invalid_secondary_view', 'Choose a related database and linking field.'))
if family == 'application':
if value is None:
return None, None
from core import view_templates
try:
cleaned = view_templates.application_ref({'config': {'application': value}})
except (TypeError, ValueError, OverflowError):
cleaned = None
if cleaned is None:
return refuse('invalid_application_ref',
'That Application reference is not a valid typed identity.')
live = _live_application_ids(ctx)
return (None if live is not None and cleaned['id'] not in live else cleaned), None
if family == 'display':
import aios_grid as _ag
if isinstance(value, dict) and value.get('mode') == 'timeseries':
return refuse('view_mode_retired',
'Time-series Views are retired. Choose an available View display mode.')
try:
cleaned = _ag._clean_display(value, valid_keys)
except (TypeError, ValueError, OverflowError):
cleaned = None
return ((cleaned, None) if value is None or cleaned is not None
or value in ({'mode': 'grid'}, {'mode': 'grid', 'groupSummary': False}) else
refuse('invalid_display', 'Choose an available View display mode.'))
def _clean_view_config(cfg, ctx, prior, display):
"""Project legacy create arrays through the C1 member cleaner."""
import aios_grid as _ag
cleaner_ctx = _ViewMemberCtx(ctx, filter_budget=[_ag.MAX_FILTER_NODES])
def clean(member, value, default=None):
cleaned, refusal = clean_view_member(member, value, cleaner_ctx, prior)
return default if refusal else cleaned
valid_keys = {item['key'] for item in ctx.fields}
config = {
'filters': [], 'filterConj': clean('filterConj', cfg.get('filterConj', 'and'), 'and'),
'important': clean('important', cfg.get('important', False), False),
'sorts': [], 'groupBy': clean('group', cfg.get('groupBy')),
'colorBy': clean('colorBy', cfg.get('colorBy')),
'rowHeightMode': clean('rowHeightMode', cfg.get('rowHeightMode', 'short'), 'short'),
'visible': [], 'widths': {}, 'summary': {}, 'memberPids': [],
'secondaryView': clean('secondaryView', cfg.get('secondaryView')),
}
raw_filters = cfg.get('filters') if isinstance(cfg.get('filters'), list) else []
for index, node in enumerate(raw_filters[:_ag.MAX_FILTER_SIBLINGS]):
node_id = str(node.get('id') or f'legacy-{index}') if isinstance(node, dict) else f'legacy-{index}'
cleaned = clean('filter:' + node_id, {'node': node, 'parent': None})
if cleaned is not None:
config['filters'].append(cleaned['node'])
raw_sorts = cfg.get('sorts') if isinstance(cfg.get('sorts'), list) else []
for rule in raw_sorts[:20]:
if not isinstance(rule, dict) or not isinstance(rule.get('colId'), str):
continue
key = _view_field_key(rule['colId'], valid_keys)
cleaned = clean('sort:' + key, rule)
if cleaned is not None:
config['sorts'].append({'colId': key, **cleaned})
# Order remains an array. S85-T02 owns position seeding and order derivation.
order = cfg.get('order') if isinstance(cfg.get('order'), list) else []
config['order'] = list(dict.fromkeys(
_view_field_key(key, valid_keys) for key in order
if isinstance(key, str) and _view_field_key(key, valid_keys) in valid_keys))
config['order'] += [item['key'] for item in ctx.fields if item['key'] not in config['order']]
visible = cfg.get('visible') if isinstance(cfg.get('visible'), list) else []
for key in dict.fromkeys(_view_field_key(key, valid_keys) for key in visible if isinstance(key, str)):
hidden = clean('hidden:' + key, False)
if hidden is False:
config['visible'].append(key)
for source, family in (('widths', 'width'), ('summary', 'summary')):
values = cfg.get(source) if isinstance(cfg.get(source), dict) else {}
entries = list(values.items())[:400] if family == 'summary' else values.items()
for key, value in entries:
if not isinstance(key, str):
continue
key = _view_field_key(key, valid_keys)
cleaned = clean(family + ':' + key, value)
if cleaned is not None:
config[source][key] = cleaned
pids = cfg.get('memberPids') if isinstance(cfg.get('memberPids'), list) else []
for pid in pids:
if type(pid) is int and clean('memberPid:' + str(pid), True) is True:
config['memberPids'].append(pid)
application, refusal = clean_view_member('application', cfg.get('application'), cleaner_ctx, prior)
if refusal:
return None, cleaner_ctx.filter_removals, refusal
if cfg.get('groupSummary') is True:
# A legacy root toggle lands in the display member, where viewOps.ts reads it.
display = {**(display or {'mode': 'grid'}), 'groupSummary': True}
if application is not None:
config['application'] = application
elif display is not None:
config['display'] = display
if cfg.get('frozenCount') is not None:
frozen = clean('frozenCount', cfg['frozenCount'])
if frozen is not None:
config['frozenCount'] = frozen
if 'fullscreen' in cfg:
config['fullscreen'] = clean('fullscreen', cfg['fullscreen'], False)
return config, cleaner_ctx.filter_removals, None
def _shared_folder_record(fid, folder):
"""C9's wire record for a folder granted to somebody else: `{id, name, order?, icon?}`.
Absent `icon` means the owner chose none and the client draws its default mark, which is the
same thing absence has always meant on a stored folder row (`aios_grid.clean_folders`).
"""
import aios_grid as _agf
src = folder if isinstance(folder, dict) else {}
rec = {'id': str(fid or '')[:80], 'name': str(src.get('name') or '')[:80]}
try:
rec['order'] = int(src.get('order'))
except (TypeError, ValueError):
pass # the owner's rail position rides when it is one, never invented
icon = _agf.clean_folder_icon(src.get('icon'))
if icon:
rec['icon'] = icon
return rec
def _shared_view_role(tops, view_id, owner, uname, st=None):
"""`'edit'` | `'view'` | `None`: the role `uname` holds on `owner`'s View, resolved exactly
the way `_granted_views` projects it.
ββ D-3520 (hotfix 2026-09-29). A DIRECT View grant decides, in both directions; only a View
with no direct grant for `uname` takes the role of the folder its owner filed it in. The save
door used to ask the direct grant alone, so a folder shared Can edit projected every View in
it as `sharedRole: 'edit'` and then refused each save as read-only (Naomi's four folders,
twenty Views, no direct grants).
"""
import core.shares as shares
direct = shares.role_for('view', view_id, uname, st=st)
if direct:
return direct
finder = getattr(tops, 'folder_of_view', None)
fid = finder(owner, view_id) if callable(finder) else None
if not fid:
return None
role = shares.role_for('folder', fid, uname, st=st)
return role if role in ('view', 'edit') else None
_VIEW_READ_ONLY_MESSAGE = "Ask the view's owner for edit access."
def _may_edit_view(tops, view_id, owner, view, uname, admin):
"""Admit the stored creator, an administrator or an edit grantee on this tenant's View."""
creator = str(view.get('createdBy') or owner).strip().lower()
return (admin or creator == str(uname).strip().lower()
or _shared_view_role(tops, view_id, owner, uname,
st=getattr(tops, 'st', None)) == 'edit')
def _granted_views(ctx, uname):
"""{view_id: STAMPED view} for every view GRANTED to `uname` by name (wave 21, item 9, C1).
The R10 registry stores bare ids, tenant-scoped through the SAME store handle this topic's
bucket uses; the record itself is fetched out of the OWNER's personal stratum of THIS
bucket. An id granted on another topic simply finds nothing here and contributes nothing
(fail-closed). Each projected view is stamped `shared` / `sharedRole` / `owner` / `hasShares`
so the client can synthesise the "Shared with me" group and disable edit affordances for
role=view β the stamps live on the PROJECTION only, never written back to the store.
`hasShares` (W40-T01, contract C1) is viewer-independent: `shared` means "granted to me",
while `hasShares` means this source has grants. The owner source receives the same marker
from `_grant_marker`; a saved View has no legacy competing copy.
`role_for` is asked with is_admin=False deliberately: the stamp reports the GRANT (the
registry listed only explicit entries), not the caller's rank.
"""
import core.shares as shares
tops = _tops(ctx)
st = getattr(tops, 'st', None)
snapshot = getattr(st, '_grid_admission', None)
lookup = {}
if (isinstance(snapshot, AdmissionSnapshot) and isinstance(tops, _tstore.TableStore)
and tops._settings_rows is None):
tops.migrate_legacy_shared_views()
lookup['document'] = snapshot.get(tops.table_key)
ids = (shares.shared_with(uname, kind='view', st=st) or {}).get('view') or []
views = dict(lookup, settings=None) if lookup else {}
if ids and not lookup and isinstance(tops, _tstore.TableStore):
# S85-T169: resolve the settings backend and the workspace document once for all ids.
views['settings'] = rows = tops._settings_rows
if rows is None:
tops.migrate_legacy_shared_views()
try:
views['document'] = st.get(tops.table_key) or {}
except Exception:
views = {'settings': None} # each find_view keeps its own fail-closed read
out = {}
for vid in ids:
found = tops.find_view(vid, **views) if hasattr(tops, 'find_view') else None
if not found:
continue
owner, view = found
if owner == uname:
continue
role = shares.role_for('view', vid, uname, st=st)
if role not in ('view', 'edit'):
continue
v = dict(view)
v['shared'] = True
v['sharedRole'] = role
v['owner'] = owner
# β W40-T01 (C1): the RECEIVER's half of the one marker both sides now carry. `shared`
# keeps its old meaning here β "granted to ME" β because the client still reads it that
# way; `hasShares` is the viewer-independent fact underneath it, and stamping it on this
# leg too is what lets the client draw ONE mark from ONE key instead of branching on who
# is looking. No `sharedOut`: this account is not the one sharing it.
v['hasShares'] = True
out[str(vid)] = v
# β D-37 (2026-08-05) β THE FOLDER LEG. W20's R10 said "a folder share = its views ride
# along"; W21 wired the view kind only, so a granted folder was accepted, stored and listed
# under "Shared with me" while changing NOTHING on the receiver's screen. Two waves of a
# control that reported success and did nothing β the same defect class the view leg above
# was written to close, surviving in its sibling.
#
# β A DIRECT VIEW GRANT WINS over the folder it happens to sit in, and the ordering above is
# what implements that: the direct pass has already filled `out`, so the folder pass skips
# ids it finds there. The specific grant is the more deliberate statement of intent, and it
# may carry a DIFFERENT role β a folder shared read-only must not downgrade a view somebody
# was explicitly given edit on, nor upgrade one they were not.
try:
folder_ids = (shares.shared_with(uname, kind='folder', st=st) or {}).get('folder') or []
except Exception:
folder_ids = []
for fid in folder_ids:
found = tops.find_folder(fid, **lookup) if hasattr(tops, 'find_folder') else None
if not found:
continue # a folder on another topic contributes nothing here
owner, folder, inside = found
if owner == uname:
continue
role = shares.role_for('folder', fid, uname, st=st)
if role not in ('view', 'edit'):
continue
for vid, view in inside.items():
if str(vid) in out:
continue
v = dict(view)
v['shared'] = True
v['sharedRole'] = role
v['owner'] = owner
v['hasShares'] = True # W40-T01 (C1) β the folder pass carries it too, or a
# folder share would still be marked on one side only
# The folder's NAME rides so the client can group these together later; today it
# renders in the same "Shared with me" group the view leg feeds. Stamps live on the
# PROJECTION only and are never written back, exactly as above.
v['sharedFolder'] = str(folder.get('name') or '')[:80]
# ββ W41-T14 (C9) β AND NOW THE WHOLE RECORD BESIDE IT, which is the line that
# carries the icon. See `_shared_folder_record`: `sharedFolder` is untouched so the
# existing readers and their two gates keep working, and `sharedFolderRecord` is the
# key W41-T35 reads the shape and tone off. Same projection-only rule as every stamp
# above β `views_from_defs` copies a saved view with `dict(saved)` and `scope_view`
# with `dict(view)`, so an unknown key rides all the way to the wire untouched, and
# the `view_upsert` save path builds from a fixed whitelist so it can never be stored.
v['sharedFolderRecord'] = _shared_folder_record(fid, folder)
out[str(vid)] = v
return out
def scope_view(view, uname, allowed_pids):
"""Re-scope a view to the READER. A no-op for a view the reader created.
Two things travel inside a shared view that are SCOPE, not presentation:
1. `memberPids` β a customer list. Re-filtered against the reader's permitted pool.
2. cohort conditions β a cohort id is a permission handle owned by ONE user. For a reader
who does not own it the leaf is UNANSWERABLE, and partial evaluation of an unanswerable
leaf WIDENS `is none of` ([[cg-cohort-set-conditions]]) β i.e. it would show MORE rows,
not fewer. So the whole filter tree is dropped for a foreign reader rather than
evaluated with a hole in it. A visibly unfiltered shared view is recoverable; a
silently widened one is a leak.
"""
if not isinstance(view, dict) or view.get('createdBy') == uname:
return view
out = dict(view)
cfg = dict(out.get('config') or {})
mp = cfg.get('memberPids')
if isinstance(mp, list):
cfg['memberPids'] = ([p for p in mp if p in (allowed_pids or ())]
if allowed_pids is not None else [])
if tree_has_cohort(cfg.get('filters')):
cfg['filters'] = []
cfg['_scopedOut'] = 'cohort' # the client says so rather than pretending
out['config'] = cfg
return out
def tree_has_cohort(node):
"""True when a filter tree references the Cohorts column anywhere (any depth)."""
import aios_grid as _agc
col = _agc.COHORT_COLUMN
if isinstance(node, list):
return any(tree_has_cohort(n) for n in node)
if not isinstance(node, dict):
return False
if node.get('colId') == col or node.get('field') == col:
return True
return tree_has_cohort(node.get('conditions') or node.get('children'))
def measure_leaves(nodes):
"""Every leaf of a filter tree that carries a date WINDOW β i.e. every measure condition.
Keyed off the window rather than the column name on purpose: a window is the one thing no
column condition has, so this cannot mistake `revenue_ytd > 5000` for a measure.
"""
out = []
for node in nodes or []:
if not isinstance(node, dict):
continue
if isinstance(node.get('children'), list):
out.extend(measure_leaves(node['children']))
elif node.get('window') is not None:
out.append(node)
return out
# ------------------------------------------------------------------ private handler helpers
def _field_echo_equal(accepted, raw):
"""Does the ACCEPTED def match what the client already renders? (wave-6 item 3)
The no-blip law: a field_upsert whose acceptance changed NOTHING the client draws needs no
re-render β the client is the ORIGIN of the change, its optimistic copy is already right,
and the rerun it would buy costs a full payload re-serialisation plus an iframe remount
(the "blip" the owner named). STRICT per-prop equality after collapsing the empty forms
('' / [] / {} / absent all render identically): any normalisation a validator applied is a
real difference the client must be SHOWN. Fail-closed β unsure means not equal means rerun.
"""
empty = ('', [], {})
for k in _FIELD_ECHO_PROPS:
a, b = accepted.get(k), raw.get(k) if isinstance(raw, dict) else None
if k == 'defaultValue':
# Absence, '', False and 0 render differently, so no empty-collapse and no 0 == False.
have = (a is not None, type(a), a) # an explicit null is a clear, stored as absent
sent = (b is not None, type(b), b)
if have != sent:
return False
continue
if k == 'scope':
# 'global' and absent are the SAME rendering (an unscoped field) β the event may
# say 'global' explicitly while the stored def says it by omission.
a = None if a == 'global' else a
b = None if b == 'global' else b
if (None if a in empty else a) != (None if b in empty else b):
return False
return True
def _unique_name(wanted, existing, *, fallback='Untitled', max_len=120):
"""Return a durable, case-insensitively unique field/view display name."""
limit = max(1, int(max_len))
def _clean(value):
return ' '.join(str(value or '').split())
base = (_clean(wanted) or _clean(fallback) or 'Untitled')[:limit].rstrip()
taken = {_clean(value).casefold() for value in existing if _clean(value)}
if base.casefold() not in taken:
return base
index = 2
while True:
suffix = f' {index}'
stem = base[:max(0, limit - len(suffix))].rstrip()
candidate = f'{stem}{suffix}' if stem else str(index)[-limit:]
if candidate.casefold() not in taken:
return candidate
index += 1
# ------------------------------------------------------------------ THE SEAM
#: ββ D-291's WRITER. Every refusal in `field_upsert` goes through here so the caller learns WHY
#: instead of receiving a success-shaped answer.
#:
#: β IT RETURNS **True**, NOT False, AND THAT HALF IS A SECOND DEFECT THIS CLOSES. `handle_one`'s
#: return value means *"this page must re-render from server state"* β so a refusal that returned
#: False left the browser's OPTIMISTIC column on screen indefinitely. The user typed a column, saw
#: it appear, and it was never stored; only a reload revealed it had never existed. The file already
#: states the rule for the one refusal that got it right (`refused_perms`): *"the client's optimistic
#: copy is a lie that must be repainted"*. Now every refusal obeys it.
#:
#: `code` is a stable machine token (the client may branch on it); `message` is the sentence a
#: person reads. β The message must name what the CALLER can change β a refusal a user cannot act
#: on is only marginally better than silence.
#:
#: ββ W41-T13 β `event` USED TO BE THE HARDCODED LITERAL `'field_upsert'`, and that was fine only
#: while this seam had exactly one caller. It now has two, so a folder refusal filed through the
#: old body would have recorded `{'event': 'field_upsert'}` on an `item_move` β a disclosure
#: channel built to end unfalsifiable theories, telling the next reader the wrong thing about
#: which door refused. KEYWORD-ONLY WITH THE OLD LITERAL AS THE DEFAULT, deliberately: every
#: existing `field_upsert` call site is byte-unchanged, and W41-T02's own refusals keep reporting
#: exactly what they reported before. The default is load-bearing, not decorative β it is what
#: makes this a widening rather than a rewrite.
def _refuse(ctx, code, message, key='', *, event='field_upsert'):
"""Record a NAMED refusal on the result and demand a repaint. Always returns True."""
try:
out = getattr(ctx, 'out', None)
if out is not None and hasattr(out, 'refusals'):
if sum(item.get('event') != 'view_op' for item in out.refusals) < 24:
out.refusals.append({
'event': str(event or 'field_upsert')[:40],
'key': str(key or '')[:80],
'code': str(code)[:40],
'message': str(message)[:300],
})
except Exception: # noqa: BLE001
# β REPORTING MUST NEVER BE THE THING THAT BREAKS THE WRITE PATH. A refusal that raises
# while explaining itself would turn a declined field into a 500 β strictly worse than the
# silence this replaces.
pass
if event in ('field_upsert', 'overlay_patch') and ctx.out.write_id:
ctx.out.writes[ctx.out.write_id] = {
'ok': False, 'value': None, 'refused': True, 'reason': str(code)}
return True
#: ββ W41-T13 β THE CHANNEL THAT ACTUALLY REACHES A SCREEN, and the two are not the same one.
#: `EventResult.refusals` is assembled by `api/routes_grid.py` into `results[].refused` and a
#: top-level `refusals` array β and MEASURED 2026-08-24, **nothing under `aios-web/web/src` reads
#: either key**. `apiBridge.ts` (~1461) unpacks exactly `{results, doc, toast, rerender, derived}`
#: from a 200, so `toast` is the only member of that envelope a person ever sees.
#:
#: So a refusal that is only recorded is still a silent 200 to the user, which is the defect this
#: ticket names. Both are written: `refusals` is the machine record a caller branches on and the
#: next investigation reads, `toast` is the sentence.
#:
#: β `toast` IS ONE SLOT, read once by `routes_grid` after its whole per-event loop, and it is
#: SHARED with `add_to_list`'s confirmation. THE PRECEDENCE IMPLEMENTED HERE: a refusal always
#: claims the slot, so within one window the last refusal is what is shown. THE LIMIT, stated
#: rather than left to be discovered: an `add_to_list` that lands AFTER a refused folder event in
#: the same 24-event window still overwrites it, because that branch assigns the slot directly.
#: Widening `EventResult` to a message LIST is the real fix and it is not this ticket's file.
def _folder_refuse(ctx, kind, code, message, key=''):
"""Refuse one event out loud: the machine record AND the rendered sentence."""
try:
out = getattr(ctx, 'out', None)
if out is not None:
out.toast = str(message)[:300]
except Exception: # noqa: BLE001
pass
# β RETURNS True, LIKE EVERY OTHER REFUSAL. `handle_one`'s return value means "repaint from
# server state"; a folder refusal that answered False would leave the browser's OPTIMISTIC
# placement on screen with nothing stored behind it β which is the springback the owner is
# reporting, kept for another two minutes instead of corrected at once.
return _refuse(ctx, code, message, key=key, event=kind)
#: β W41-T13 β WHICH `save_folders` REPAIRS ARE WORTH A SENTENCE. W41-T12's receipt lists every
#: correction it made; most mean *"something you sent was wrong and we fixed it"*, which a person
#: wants to know about because their folder tree now differs from what they dragged.
#:
#: β `parent_is_root_sentinel` IS DELIBERATELY ABSENT AND MUST STAY ABSENT. It means "you said
#: root the other legal way" β both spellings are correct, nothing was lost, and rendering it as a
#: warning would fire on ordinary use. A notice that cries wolf on the normal path trains the user
#: to ignore the ones that matter.
#:
#: β THE WHOLE NOTICE MUST FIT IN 300 CHARACTERS, which is where `EventResult.toast` is sliced.
#: All three phrases plus both joiners and the frame is the worst case, and the first draft came
#: to 328 β a sentence cut off mid-word, in the one channel a person actually reads. The phrases
#: below are short for that reason and not for style; the proof pins the bound so the next person
#: to add one finds out here rather than on a screen.
_FOLDER_REPAIR_COPY = {
'parent_missing': 'named a folder that is gone, so it moved to the top level',
'placement_missing_folder': 'named a folder that is gone, so it moved to the top level',
'item_in_two_folders': 'was in two folders at once, so the first one was kept',
}
#: Everything else actionable collapses to one sentence: the row could not be read at all.
_FOLDER_REPAIR_UNREADABLE = frozenset({
'duplicate_folder_id', 'parent_not_an_id', 'row_not_a_folder', 'folder_without_id',
'surface_not_a_list', 'placements_not_a_map', 'placement_without_item',
'placement_not_an_id',
})
def _folder_repair_notice(repairs):
"""The sentence for a `save_folders` receipt, or None when there is nothing worth saying."""
seen = []
for row in (repairs or ()):
reason = str((row or {}).get('reason') or '')
if reason == 'parent_is_root_sentinel':
continue # see the constant above: the normal path, not a repair
phrase = _FOLDER_REPAIR_COPY.get(reason)
if phrase is None and reason in _FOLDER_REPAIR_UNREADABLE:
phrase = 'could not be read, so it was left out'
if phrase and phrase not in seen:
seen.append(phrase)
if not seen:
return None
return ('Your folders were saved with a correction. Something in them '
+ '; something else '.join(seen)
+ '. Reload the page to see the result.')
def _commit_folder_write(tops):
"""ββ W41-T13 / OWNER INSTRUCTION 10 β MAKE THE FOLDER WRITE THAT JUST HAPPENED DURABLE, NOW.
β THE DEFECT, MEASURED WITH TWO REAL PROCESSES AGAINST A THROWAWAY STORE (2026-08-24):
`table_store.save_folders` commits through `TableStore._update`, which is hardcoded to
`flush='async'`. That applies the change to `Store._cache` and returns; the hub commit is
handed to a coalescing worker that sleeps `_FLUSH_DELAY` (2s) and then, if this key committed
inside the last `_FLUSH_MIN_GAP` (20s), sleeps the remainder of that too. **SIX accepted
folder writes in a row left the hub on its original commit** and a second process read an
empty `itemFolders` every single time. Read-your-writes held inside the process, which is
exactly why no gate in this repo could see it ([[a-guard-closed-on-one-backend-is-not-closed]]).
The user-visible half is the owner's report: `viewEcho.ts::ECHO_RECENT_MS` holds the
optimistic placement for 120s and then yields to the host copy, so a write that never reached
the hub before the container was replaced springs back at about two minutes.
β `st.flush(key)` IS THE WRONG PRIMITIVE HERE, THREE TIMES OVER: it waits out
`_FLUSH_MIN_GAP`, so it can block a drag for ~22 seconds; `harness.runtime.TenantRuntime` (the
handle the HTTP door actually passes) does not proxy it at all; and the gates' store doubles
do not all carry it. `update(key, identity, flush='sync')` is on EVERY handle β the module,
`Store`, `TenantRuntime`, `store_pg`, and both fakes β and `_update_locked`'s D-305 branch
makes it exactly the right one: with the key dirty and owned it takes the CACHE (never
re-downloading over the pending change), commits it through `_commit` with the parent
precondition and the replay journal intact, and clears the dirty mark so the worker does not
then spend a second commit on identical bytes.
β BYPASSING `_FLUSH_MIN_GAP` IS THE POINT, NOT AN OVERSIGHT β do not "fix" this back to
protect the 256-commits/hr budget. That floor exists to coalesce autosave chatter (a column
resize, a filter tweak, a typed cell). A folder event is not chatter: `CustomerGrid.tsx`
emits `item_move` and `folder_reorder` ON DROP, one per completed gesture, so the ceiling
this adds is a handful of commits per session against a budget of 256 per hour.
β IT IS THE HANDLE `save_folders` ITSELF USED, resolved through `_tops` and never `_store_of`.
Those two can be different objects (`_tops` can fall through to `cl_mod.TABLE_OPS`, built with
NO store handle, while `_store_of` returns the request's `TenantRuntime`), and committing the
wrong one would land nothing while looking exactly like success. `TableStore.st` and
`.table_key` are the public pair, so this addresses byte-for-byte what `_update` addressed.
β A FAILED COMMIT IS NOT A REFUSED WRITE. The change is already accepted into the cache and
the key is still marked dirty, so the coalescing worker keeps retrying with backoff. Logging
and carrying on is therefore right; raising here would turn a saved change into a 500.
β ON POSTGRES this is a redundant transaction: `store_pg.update` accepts `flush=` and ignores
it because every write is already committed when it returns. One extra RMW per user gesture,
correctness-neutral. Named for the record rather than special-cased, because a backend test
here would be a second definition of "which backend am I on".
"""
try:
st = getattr(tops, 'st', None)
key = getattr(tops, 'table_key', None)
if st is None or not key or not hasattr(st, 'update'):
return False
st.update(key, lambda doc: doc, flush='sync')
return True
except Exception as exc: # noqa: BLE001
_tel.error('grid_events:folder_commit', exc)
return False
def handle_events(events, ctx):
"""The event LOG entry point β one EventResult. The `[-24:]` window lives here.
β THE VALUE IS AN EVENT LOG `{'events': [...]}`, NOT ONE EVENT (2026-07-27). A component
has exactly one value slot, and two quick emits share it: creating a field emits
`field_upsert` and the insertColumn autosave emits `view_upsert` 420ms later β with the
server still inside the first rerun, the second write clobbered the slot before any run
read it, and the field creation VANISHED with no error anywhere (measured live; the same
race sat latent under overlay-field creation, masked by localStorage). The client now
sends its recent window of events; each is processed exactly once, keyed by its id. The
single-event shape is still accepted β it is what an older client in a stale tab sends.
Accepts everything the component value can be: the log dict, a bare list of events (what
the HTTP body's `events` array unwraps to), or one legacy single-event object.
`EventResult.rerender` is True when ANY processed event demands a re-render from server
state β the same OR-fold `_cl_handle_grid_event` did.
"""
if isinstance(events, dict) and isinstance(events.get('events'), list):
seq = events['events'][-24:]
elif isinstance(events, list):
seq = events[-24:]
else:
seq = [events]
rerun = False
for one in seq:
rerun = handle_one(one, ctx) or rerun
ctx.out.rerender = rerun
return ctx.out
def _activity_action(fn):
@wraps(fn)
def wrapped(event, ctx):
from core.user_tables import activity_batch
with activity_batch():
return fn(event, ctx)
return wrapped
def _view_op_reply(ctx, result, *, rerender=False):
"""Expose one C1 result without receipt history or a shared toast."""
row = {key: result[key] for key in ('opId', 'member', 'applied') if key in result}
row['rerender'] = bool(rerender)
if result.get('refused'):
row['refused'] = {key: result['refused'][key] for key in ('reason', 'member', 'message')}
ctx.out.refusals.append({'event': 'view_op', **row['refused']})
if isinstance(row.get('opId'), str):
ctx.out.writes[row['opId']] = row
return row
def _admit_view_op(view, candidate, member, *, owner, actor, admin):
"""Check the resolved operation against the current locked View inside its update."""
import aios_grid as _ag
family = member.partition(':')[0]
if family == 'locked' and not (admin or str(view.get('createdBy') or owner).lower()
== str(actor).lower()):
return {'reason': 'lock_owner_only',
'message': 'Only the View creator or an administrator can change its lock.'}
cfg, next_cfg = view.get('config') or {}, candidate.get('config') or {}
if (family in ('display', 'application') and view.get('locked')
and view.get('kind') != 'system' and view.get('id') != 'all-customers'
and _tstore._view_member_value(view, member) != _tstore._view_member_value(candidate, member)):
return {'reason': 'view_mode_locked', 'message': 'Unlock this View before changing its display.'}
filters, sorts = next_cfg.get('filters') or [], next_cfg.get('sorts') or []
if (_ag.preserve_locked_view_records(cfg, filters, sorts) != (filters, sorts)
or (family == 'filterConj' and filters
and cfg.get('filterConj', 'and') != next_cfg.get('filterConj', 'and')
and _ag.preserve_locked_view_records(cfg, [], sorts)[0])):
return {'reason': 'locked_view_record',
'message': 'Copy this View to change its locked filter or sort records.'}
return None
@contextmanager
def _cohort_name_transaction(st):
"""Keep a cohort View write and its synchronization on one bounded PostgreSQL connection."""
from core import edit_receipts, store_pg
backend = edit_receipts._backend(st)
if isinstance(backend, edit_receipts.PgReceipts):
with backend._connection() as con, con.transaction():
with store_pg.PgStore(backend.slug).transaction(con):
yield con, backend.slug
else:
yield None, None
def _sync_cohort_view_name(ctx, tops, owner, view_id):
"""Copy the canonical View name while its source remains locked through the cohort write."""
from core import store_pg
sets = _cohorts(ctx)
cohort_name = (sets.all_for(owner).get(view_id) or {}).get('name')
def synchronize(data):
view = ((data.get(owner) or {}).get('views') or {}).get(view_id) or {}
name = view.get('name')
if name and cohort_name != name:
sets.rename(owner, view_id, name)
return True
return False
with _cohort_name_transaction(tops.st) as (con, slug):
if con is not None:
rows = tops._settings_rows
if rows is not None:
with rows._reading():
synchronize(rows._settings(con, (owner,)))
else:
row = con.execute(store_pg._q(
'SELECT value FROM {tbl} WHERE key = %s FOR UPDATE',
'store_kv', slug), (tops.table_key,)).fetchone()
synchronize(row[0] if row else {})
else:
# Detached stores provide source exclusion through their update contract.
class Unchanged(Exception):
pass
def change(data, _audit):
if not synchronize(data):
raise Unchanged
return data
try:
tops._audited_update(change, flush='sync', owners=(owner,))
except Unchanged:
pass
def handle_view_ops(events, ctx):
"""Authorize one View batch and apply its cleaned members through the owner-row writer."""
from copy import deepcopy
from core import edit_receipts, view_settings_rows
import aios_grid as _ag
from harness import measure_filter as _mfc
events = [dict(event, client_op_id=event.get(
'client_op_id', event.get('opId', event.get('id')))) for event in events]
if not events:
return []
ctx.workspace_lend = None
view_id = str(events[0].get('view_id') or '').strip()
def refusal(event, reason, message):
return {'opId': event.get('client_op_id'), 'member': event.get('member'),
'applied': False, 'refused': {
'reason': reason, 'member': event.get('member'), 'message': message}}
def refuse_all(reason, message):
return [_view_op_reply(ctx, refusal(event, reason, message)) for event in events]
if not _store_of(ctx).available():
raise StoreUnavailable('The View store is unavailable.')
tops = _tops(ctx)
admission_tops = _tops(_admission_ctx(ctx))
owner = ctx.uname
workspace = admission_tops._read_owners(owner).get(owner) or {}
prior = (workspace.get('views') or {}).get(view_id)
projected = next((view for view in ctx.visible_views
if isinstance(view, dict) and view.get('id') == view_id), {})
_pinned_per_user = ((prior or projected).get('kind') == 'system'
or view_id in ('all-customers', _ag_overview_id()))
assigned = admission_tops.assigned_views(ctx.uname, ctx.allowed_pids)
is_assigned = view_id in assigned
if is_assigned:
prior = assigned[view_id]
workspace = admission_tops._read_owners(_tstore.ASSIGNED_KEY).get(_tstore.ASSIGNED_KEY) or {}
elif view_id.startswith('assigned:') or projected.get('assigned'):
return refuse_all('view_gone', 'That assigned View is no longer available to you.')
elif not _pinned_per_user:
found = admission_tops.find_view(view_id)
if found and found[0] != ctx.uname:
owner, prior = found
workspace = admission_tops._read_owners(owner).get(owner) or {}
prior = (workspace.get('views') or {}).get(view_id)
seed_view = not prior and _pinned_per_user and bool(projected)
if seed_view:
# A pinned projection gets its own source, never another user's same-id source.
prior = {key: deepcopy(value) for key, value in projected.items()
if key in ('id', 'name', 'kind', 'locked', 'note', 'config')}
prior['createdBy'] = ctx.uname
prior['kind'] = 'system'
if not isinstance(prior, dict):
return refuse_all('view_gone', 'That View is no longer available.')
if not is_assigned and not _pinned_per_user and not _may_edit_view(
admission_tops, view_id, owner, prior, ctx.uname, ctx.admin):
return refuse_all('view_read_only', _VIEW_READ_ONLY_MESSAGE)
def admit(view, candidate, member):
if not is_assigned and not _pinned_per_user and not _may_edit_view(
tops, view_id, owner, view, ctx.uname, ctx.admin):
return {'reason': 'view_read_only', 'message': _VIEW_READ_ONLY_MESSAGE}
return _admit_view_op(view, candidate, member, owner=owner,
actor=ctx.uname, admin=ctx.admin)
receipts = view_settings_rows.ViewOpReceipts(workspace, getattr(tops.st, 'key', tops.table_key))
action = edit_receipts.operation(tops.table_key, 'view_op', view_id)
preview = deepcopy(prior)
prepared, slots, answers, known = [], [], [None] * len(events), {}
for index, event in enumerate(events):
member, operation = _tstore._view_member_identity(event.get('member')), event.get('op')
identity = event.get('client_op_id')
def refuse(reason, message):
answers[index] = refusal(event, reason, message)
try:
edit_receipts.op_id(identity)
except ValueError:
refuse('invalid_op_id', 'Give this View operation a client operation id.')
continue
if str(event.get('view_id') or '').strip() != view_id:
refuse('view_gone', 'That View is no longer available.')
continue
replay = receipts.result(ctx.uname, action, identity)
if replay:
answers[index] = replay
continue
if identity in known:
prepared.append(next(item for item in prepared if item['client_op_id'] == identity))
slots.append(index)
continue
family, _, key = member.partition(':') if isinstance(member, str) else ('', '', '')
if is_assigned and family in ('filter', 'filterConj', 'memberPid'):
refuse('assigned_filter_fixed', 'The assigned View fixes its filters and record membership.')
continue
if operation not in ('set', 'remove', 'undo'):
refuse('invalid_op', 'Choose set, remove or undo for this View setting.')
continue
present, value = operation != 'remove', event.get('value')
if operation == 'undo':
original = known.get(value) if isinstance(value, str) else None
original = original or receipts.result(ctx.uname, action, value)
if (not original or not original.get('applied')
or _tstore._view_member_identity(original.get('member')) != member):
refuse('changed_since', 'That change is not available to undo.')
continue
present, value = original['beforePresent'], original['before']
if not present:
if family not in ('sort', 'width', 'filter', 'summary', 'memberPid') and operation != 'undo':
refuse('invalid_op', 'Set a value for this View setting.')
continue
sample = {'sort': {'dir': 'asc', 'pos': 'V'}, 'width': 100,
'filter': {'node': {'children': []}, 'parent': None},
'summary': {'agg': 'none'}, 'memberPid': False}.get(family)
# Undo can remove an optional scalar that was absent before the user's edit.
if operation == 'undo' and family not in ('sort', 'width', 'filter', 'summary', 'memberPid'):
sample = _tstore._view_member_value(preview, member)[1]
cleaned, denied = clean_view_member(member, sample, ctx, preview)
else:
cleaned, denied = clean_view_member(member, value, ctx, preview)
if denied:
code = 'target_gone' if denied['code'] == 'unknown_field' else denied['code']
refuse(code, denied['message'])
continue
if operation == 'set' and family == 'sort' and 'pos' not in cleaned:
refuse('invalid_position', 'Use 1 to 64 letters or digits for the position.')
continue
if family in ('hidden', 'sort', 'width', 'position', 'summary'):
member = family + ':' + _view_field_key(key, {field['key'] for field in ctx.fields})
cfg = preview.get('config') or {}
candidate = deepcopy(preview)
if family == 'position' and 'positions' not in candidate.setdefault('config', {}):
candidate['config']['positions'] = _tstore._view_position_seed(cfg.get('order') or [])
before_present, before = _tstore._view_member_value(candidate, member)
try:
_tstore._set_view_member(candidate, member, cleaned, present=present)
except _tstore._ViewOpRefused as exc:
refuse(exc.reason, str(exc))
continue
next_cfg = candidate.get('config') or {}
filters, sorts = next_cfg.get('filters') or [], next_cfg.get('sorts') or []
if family == 'filter' and present:
cycle = _ag.view_filter_cycle(view_id, filters, lambda vid: (
next(((view.get('config') or {}).get('filters') or [] for view in ctx.visible_views
if isinstance(view, dict) and view.get('id') == vid), [])))
if cycle:
refuse('view_cycle', 'Choose a View that does not refer back to this View.')
continue
if is_assigned and family in ('name', 'note', 'locked'):
refuse('unknown_member', 'Choose a presentation setting for this assigned View.')
continue
preview = candidate
after_present, after = _tstore._view_member_value(preview, member)
known[identity] = {'opId': identity, 'member': member, 'applied': True,
'before': before, 'beforePresent': before_present,
'after': after, 'afterPresent': after_present}
prepared.append({**event, 'member': member,
'value': cleaned if operation == 'set' else event.get('value')})
slots.append(index)
cohort_name = view_id in ctx.cohort_ids and any(event.get('member') == 'name' for event in events)
with _cohort_name_transaction(tops.st) if cohort_name else nullcontext():
if prepared:
try:
landed = tops.apply_view_ops(
owner, view_id, prepared, actor=ctx.uname, origin=EVENT_ORIGIN,
assigned_recipient=ctx.uname if is_assigned else None,
seed_view=prior if seed_view else None,
admit=admit)
except edit_receipts.ReceiptUnavailable as exc:
raise StoreUnavailable(str(exc)) from exc
finally:
if ctx.admission is not None:
ctx.admission.invalidate(tops.table_key)
for index, result in zip(slots, landed):
answers[index] = result
preview = (tops.assigned_views(ctx.uname, ctx.allowed_pids).get(view_id, {}) if is_assigned else
((tops._read_owners(owner).get(owner) or {}).get('views') or {}).get(view_id, {}))
if view_id in ctx.cohort_ids and any(
result.get('applied') and result.get('member') == 'name' for result in answers):
_sync_cohort_view_name(ctx, tops, owner, view_id)
unresolved = {str(rule.get('id') or '') for rule in measure_leaves(
preview.get('config', {}).get('filters') or []) if _mfc.rule_complete(rule)}
rerender = bool(unresolved - set(ctx.resolved_ids) - {''})
return [_view_op_reply(ctx, answer, rerender=rerender and answer.get('applied', False))
for answer in answers]
class _UnwrittenViewUpsert(Exception):
"""Abort the receipt transaction for an existing View's whole-save refusal."""
def _edit_receipt(fn):
@wraps(fn)
def wrapped(event, ctx):
from copy import copy, deepcopy
from dataclasses import replace
from core import edit_receipts
def apply_event(event, write_ctx):
try:
return fn(event, write_ctx)
finally:
# Canonical writers bypass the admission handle, including row-backed settings.
if write_ctx.admission is not None:
write_ctx.admission.invalidate()
if not isinstance(event, dict):
return False
# C1 stores receipts with its owner-row update, rather than the event wrapper.
if event.get('type') == 'view_op':
identity = event.get('client_op_id', event.get('opId', event.get('id')))
return fn(dict(event, id=identity, client_op_id=identity), ctx)
identity = event.get('opId', event.get('id'))
active_id = edit_receipts.current_op_id()
# Trusted staged previews own their confirmation ledger and must not gain transport metadata.
if ctx.fallback_ws is not None or not (ctx.durable_receipts or (
active_id is not None and active_id == identity)):
identity = str(identity or '')[:180]
if not identity or identity in ctx.seen_ids:
return False
ctx.seen_ids[identity] = True
if len(ctx.seen_ids) > 400:
for stale in list(ctx.seen_ids)[:200]:
ctx.seen_ids.pop(stale, None)
return apply_event(dict(event, id=identity), ctx)
if not identity:
return False
try:
identity = edit_receipts.op_id(identity)
except ValueError as exc:
ctx.out.write_id = ''
return _refuse(ctx, 'bad_op_id', str(exc), event=event.get('type'))
event = dict(event, id=identity)
# The write runs on a copy, so the lend leaves the outer ctx here, replays included.
lend, ctx.workspace_lend = ctx.workspace_lend, None
def apply():
before = len(ctx.out.refusals)
checked = edit_receipts.CheckedStore(_store_of(ctx))
table = copy(ctx.table) if ctx.table is not None else None
if table is not None:
table._st = checked
write_ctx = replace(ctx, st=checked, table=table, workspace_lend=lend)
rerender = apply_event(event, write_ctx)
write = dict(ctx.out.writes.get(identity) or {})
write['opId'] = identity
result = deepcopy({'rerender': bool(rerender), 'write': write,
'refusals': ctx.out.refusals[before:],
'doc': ctx.out.doc, 'toast': ctx.out.toast})
if event.get('type') == 'view_upsert' and any(
row.get('code') in ('view_ops_required', 'view_read_only')
for row in result['refusals']):
raise _UnwrittenViewUpsert(result)
edit_receipts.observe_event(result)
return result
before = len(ctx.out.refusals)
try:
receipt = edit_receipts.run_once(
_store_of(ctx), ctx.uname,
edit_receipts.operation(ctx.scope_key, event.get('type'), event.get('pid')),
identity, apply)
except _UnwrittenViewUpsert as exc:
receipt = exc.args[0]
except edit_receipts.ReceiptUnavailable as exc:
raise StoreUnavailable(str(exc)) from exc
receipt = receipt.get('event') or receipt
# Replace this event's observations so first delivery and replay have the same shape.
ctx.out.refusals[before:] = receipt['refusals']
ctx.out.writes[identity] = receipt['write']
ctx.out.write_id = identity
ctx.out.doc, ctx.out.toast = receipt['doc'], receipt['toast']
return receipt['rerender']
return wrapped
@_edit_receipt
@_activity_action
def handle_one(event, ctx):
"""Validate ONE untrusted component event.
Odoo-source fields are never accepted as cell updates. View and schema objects are
user-scoped; row patches additionally require the pid to be in the currently permitted
Customer List pool.
RETURN VALUE = "this page must re-render from server state", NOT "handled".
The distinction is the difference between a snappy grid and a sluggish one.
Persisting is not by itself a reason to rerun: Streamlit has ALREADY re-run the
script once simply to deliver the component value, and the client is the ORIGIN
of the change, so its own state is correct before the server hears about it. An
extra st.rerun() therefore buys nothing and costs a second full page run.
Measured on the 1,550-row book (2026-07-25): one filter tweak produced TWO
page_customer_data runs ~2.8s apart, each re-serialising the whole ~576 KB row
payload β and the handler on the second run is a guaranteed no-op, because the
event-id dedupe two lines below has already consumed that id.
THE WAVE-6 NO-BLIP LAW (item 3, 2026-07-27) β True ONLY when the next render
genuinely differs from what the client already draws:
field_upsert β False when the accepted def ECHOES the client's copy
(_field_echo_equal); True on any validator mutation, any
permissions refusal, and ALWAYS when a measure window changed
(values must be re-resolved server-side).
overlay_patch β False when every requested update was accepted verbatim;
True the moment anything was refused or truncated.
field_delete β False: the client removed the column optimistically and the
store scrub is invisible to the next render.
field_duplicate β True when a copied-value snapshot or host-computed value must flow
back; a definition-only formula/created_time clone computes client-side.
view_delete β False (the deleted view simply stops being served).
view_upsert β unchanged: False, except an unresolved measure condition.
cohort_* / add_to_list β True: the lists payload is server truth, and these are
not the hot path.
Transport receipts retain the first result; trusted/internal callers use their context's seen ids.
"""
# The ctx fields the moved body reads as plain locals β bound once here so every branch
# below is textually the app.py body (which is what makes this move reviewable).
uname = ctx.uname
allowed_pids = ctx.allowed_pids
fields = ctx.fields
measure_keys = ctx.measure_keys
resolved_ids = ctx.resolved_ids
cohort_ids = ctx.cohort_ids
measure_offer = ctx.measure_offer
visible_views = ctx.visible_views
admin = ctx.admin
scope_key = ctx.scope_key
# A lent workspace is a pre-write snapshot: one event takes it, never a later one.
lend, ctx.workspace_lend = ctx.workspace_lend, None
if not isinstance(event, dict):
return False
event_id = event['id']
ctx.out.write_id = event_id
kind = event.get('type')
if kind == 'view_op':
return any(row['rerender'] for row in handle_view_ops([event], ctx))
if kind == 'overlay_patch' and str(scope_key) == 'ut_activity':
return _refuse(ctx, 'activity_read_only', 'Activity records cannot be edited.',
event=kind)
from core import user_tables as _zone_contract
_zone_key = _zone_contract.ZONE_FIELD_KEY
_offered_keys = set((event.get('updates') or {}).keys()) if isinstance(
event.get('updates'), dict) else set()
_raw_field = event.get('field') if isinstance(event.get('field'), dict) else {}
if _offered_keys.intersection({_zone_key, 'zone'}) \
or str(_raw_field.get('key') or '') in {_zone_key, 'zone'}:
return _refuse(ctx, 'zone_membership_read_only',
"Zone membership is worked out from the record's current location",
key=_zone_key, event=str(kind or 'grid_event'))
field_by_key = {f['key']: f for f in fields}
if str(scope_key).startswith('ut_') and not admin and (
kind == 'overlay_patch' or
(kind == 'field_upsert' and _raw_field.get('key') not in field_by_key)):
if not _zone_contract.may_edit_database(scope_key, uname, st=_store_of(ctx)):
return _refuse(ctx, 'database_read_only',
'Can edit access is required to change this database.', event=kind)
# A Product shared-select option can have been admitted by an earlier event while this
# EventCtx remains alive. The renderer gets the persisted choice projection on refresh,
# but this write wall also has to learn it *before* it canonicalises a later paste/API
# patch; otherwise ``ET`` followed by ``et`` sees an empty contract again and overwrites
# the first spelling. This is intentionally a narrow vocabulary merge, never a second
# field-definition reader: visibility, type and permissions remain the caller's served
# schema.
try:
from core import shared_overlay as _shared_choices
import aios_grid as _ag_choices
_choice_table_key = getattr(getattr(ctx, 'table', None), 'table_key', None)
if _choice_table_key:
_stored_choices = _shared_choices.fields(_choice_table_key, st=_store_of(ctx)) or {}
for _choice_key, _stored_def in _stored_choices.items():
_served_def = field_by_key.get(_choice_key)
if (_served_def and _served_def.get('type') in ('select', 'multiselect')
and isinstance(_stored_def, dict)):
_served_def['options'] = _ag_choices.merge_choice_options(
_served_def.get('options'), _stored_def.get('options'))
except Exception:
# Field writes must not become unavailable merely because an optional shared-overlay
# vocabulary is absent (ordinary customer and legacy in-memory contexts have none).
pass
valid_keys = set(field_by_key)
overlay_keys = {f['key'] for f in fields
if f.get('source') == 'overlay' or _may_override_source_value(f)}
# Event validation is not a render payload. It must not consume a one-shot label
# correction before the browser has had a chance to receive it.
# Only the view kinds take the lend: they read `ws['views']`, which the assembly never merges.
if (kind in ('view_upsert', 'view_delete') and isinstance(lend, dict)
and _store_of(ctx).available()):
ws = lend
else:
ws = table_workspace(
ctx, allowed_pids=allowed_pids, consume_corrections=False)
def _session_ready():
ws.setdefault('views', {})
ws.setdefault('fields', {})
ws.setdefault('overlays', {})
if kind == 'view_select':
# Owner item 3 (2026-07-31): remember WHERE THE USER IS so a fresh browser resumes
# there instead of the system default view. Presentation state only β the read side
# re-validates the id against what the caller may see, so nothing here needs an
# authorisation wall beyond the length cap. Never a re-render: the client is already
# on that view.
vid = str(event.get('viewId') or '').strip()[:120]
if vid and _store_of(ctx).available():
try:
_tops(ctx).save_active_view(uname, vid)
except Exception as _ae:
_tel.error('grid:view-select', _ae)
return False
if kind == 'record_layout':
# Wave 2026-08-02 (C-LAYOUT): the per-user record-detail field order. Presentation
# state for one surface; grid column order is untouched. Unknown keys are pruned
# against the LIVE field set, dupes collapse, and the wire re-validates at serve
# time β so a client racing a field delete degrades to default order, never an error.
raw_order = event.get('order')
if not isinstance(raw_order, list):
return False
order, seen = [], set()
for k in raw_order[:200]:
k = str(k or '').strip()[:80]
if k and k in valid_keys and k not in seen:
seen.add(k)
order.append(k)
if _store_of(ctx).available():
_tops(ctx).save_record_layout(uname, order)
else:
_session_ready()
if order:
ws['recordLayout'] = {'order': order}
else:
ws.pop('recordLayout', None)
# Autosave hot path, like view_select: the client already renders the order it asked
# for, and the wire echoes it back on the next workspace read.
return False
if kind == 'view_upsert':
raw = event.get('view')
if not isinstance(raw, dict):
return False
view_id = str(raw.get('id') or '').strip()[:120]
prior = (ws.get('views') or {}).get(view_id) or {}
tops = _tops(ctx)
assigned = tops.assigned_views(uname, allowed_pids) if _store_of(ctx).available() else {}
is_assigned = raw.get('assigned') or prior.get('assigned') or view_id in assigned
# Stored system Views and pinned ids keep personal presentation in the caller's stratum.
_pinned_per_user = (prior.get('kind') == 'system'
or view_id in ('all-customers', _ag_overview_id()))
_save_as = uname
if _store_of(ctx).available() and not _pinned_per_user and view_id not in assigned:
found = tops.find_view(view_id, prefer_owner=uname)
if found:
_save_as, prior = found
if prior.get('kind') == 'system':
_save_as, prior = uname, (ws.get('views') or {}).get(view_id) or {}
elif not _may_edit_view(tops, view_id, _save_as, prior, uname, admin):
return _refuse(ctx, 'view_read_only', _VIEW_READ_ONLY_MESSAGE,
view_id, event=kind)
if ctx.durable_receipts and (prior or view_id in assigned):
return _refuse(ctx, 'view_ops_required',
'This page is out of date. Reload to keep editing this view.',
view_id, event=kind)
if not isinstance(raw.get('config'), dict):
return False
name, name_refusal = clean_view_member('name', raw.get('name'), ctx, prior)
requested_name = name
if not view_id or name_refusal:
return False
display, display_refusal = clean_view_member('display', raw['config'].get('display'), ctx, prior)
if display_refusal and display_refusal['code'] == 'view_mode_retired':
return _folder_refuse(ctx, kind, display_refusal['code'], display_refusal['message'], key=view_id)
if 'permissions' in raw:
return _refuse(
ctx, 'view_permissions_retired',
'Saved View sharing uses modern grants. Remove the retired view permissions field.',
view_id, event='view_upsert')
# The filter TREE (leaf conditions and/or nested condition groups) is
# validated by the module-agnostic grid contract helper β imported lazily
# here for the same reason the page does it: a missing embed build must
# never break page import.
import aios_grid as _ag
cfg = raw['config']
# A MEASURE key is valid in a FILTER and nowhere else (CG-8): it may not be ordered,
# shown, grouped or coloured by, because it is not a column of this table. Hence the
# widened key set here and the plain `valid_keys` everywhere below.
# `cohort_ids` is a PERMISSION list, not a convenience: a cohort rule naming anything
# else is dropped here. Leaving it in would persist a condition the engine can only
# answer with "nothing", so `Cohort is not [a list I deleted]` would show an empty table
# forever with nothing on screen explaining why.
# ββ W37-T26 / CONTRACT C4 β `visible_view_ids` is the same PERMISSION list one leaf over:
# a `__view__` membership leaf naming a view this caller cannot see is dropped here, for
# the identical reason the cohort line above gives. Without it the arm is fail-closed and
# every view leaf is dropped on save, so the condition would vanish on the next read β
# D-90's shape exactly.
# β `ctx.visible_views` is already populated (`routes_grid.py` passes it, `:714` reads it),
# so this needs no new plumbing; it is the value nobody had handed to the validator.
# β Edited by lane C, not this file's owner: `platform/core/grid_events.py` is in NO fence
# and lane C was the last session open. See `mailbox/C.md` NOTE C-24.
# ββ THE CYCLE REFUSAL'S HOST HALF (C4), and it is the ticket's `done-when` rather than a
# guard bolted on afterwards. View X filtered on "is in View Y" where Y is filtered on X
# cannot be resolved by anything: X needs Y needs X. The browser refuses it too, with a
# sentence a person reads; this one is what makes the rule true for a caller that POSTs a
# view directly, which is every guard-in-the-browser's blind spot.
# β REFUSED, NOT REPAIRED. Dropping the offending leaf would save a view the person did not
# write and leave the panel showing a condition the config does not carry.
_cycle = _ag.view_filter_cycle(
view_id, cfg.get('filters'),
lambda vid: next((v.get('config', {}).get('filters')
for v in (visible_views or ())
if isinstance(v, dict) and str(v.get('id')) == vid), None))
if _cycle:
_refuse(ctx, 'view_cycle',
'that would make a loop: ' + ' refers to '.join(_cycle) +
'. A view cannot filter on a view that filters on it, because neither can '
'be worked out without the other.', view_id)
return False
config, filter_removals, config_refusal = _clean_view_config(cfg, ctx, prior, display)
if config_refusal:
_refuse(ctx, config_refusal['code'], config_refusal['message'], view_id, event=kind)
return False
filters, sorts = config['filters'], config['sorts']
# C-LOCK (wave 2026-08-02, item 12's mechanism): a view may be LOCKED to one cohort.
# `cohort_ids` is the same permission list the cohort filter leaf uses β a lock naming
# a cohort this session cannot see is DROPPED at write, exactly like a cohort rule.
# (Readers of a SHARED locked view resolve the id against their OWN visible sets; an
# unresolvable lock matches NOTHING client-side β the cohort-leaf law, never a widen.)
cohort_lock = str(cfg.get('cohortLock') or '').strip()[:120]
# β WAVE 17 R1 (C-LOCKV guard a) β A PROJECTED LOCKED VIEW RE-STAMPS ITS OWN LOCK.
# A locked view IS its set: its id and its lock are the same fact. The client rebuilds
# `config` from scratch on every autosave (a column resize is enough), so taking the
# lock from the browser would mean one omitted key turns "the 40 accounts we agreed to
# call" into the whole book, under the same name, with nothing going red. The read side
# re-stamps too (aios_grid.views_from_defs) β this keeps the STORE from accumulating the
# wrong record in the first place.
_is_locked_view = view_id in set(cohort_ids)
if _is_locked_view:
cohort_lock = view_id
if cohort_lock and cohort_lock in set(cohort_ids):
config['cohortLock'] = cohort_lock
# The prior stored View supplies lock state and its immutable filter records. Sharing
# itself is exclusively the modern grant registry checked at the foreign-view wall below.
# A visible foreign view is a grant projection. The modern foreign-view wall below
# resolves the owner's personal source and checks the grant registry before deciding
# whether this is a create; there is no legacy bucket to consult as a second authority.
is_new = not prior
if not is_new:
# W44 C3: filters/sorts locked in an existing View are immutable records. This
# runs after the visibility/edit wall has established `prior`, so a guessed foreign
# view cannot be used as a source of lock state. A copied View has no prior and is
# consequently the only alteration path.
filters, sorts = _ag.preserve_locked_view_records(
prior.get('config') or {}, filters, sorts)
config['filters'], config['sorts'] = filters, sorts
# The creator is HOST-STAMPED and never read from the browser β the same rule as the
# field-level createdBy. An existing view keeps whoever made it.
creator = prior.get('createdBy') or uname
# A non-owner cannot change the mode lock. There is deliberately no view-level
# permissions bag to preserve: modern grants are the only access authority.
owns_prior = (str(prior.get('createdBy') or uname).strip().lower()
== str(uname or '').strip().lower())
if not is_new and not (admin or owns_prior):
raw = dict(raw)
raw['locked'] = prior.get('locked')
# ββ I12/C3 BELT (2026-07-31): a LOCKED view's DISPLAY MODE is frozen HOST-SIDE too.
# The client's switcher already refuses (setDisplayMode), and its comment has claimed
# "the host refuses too" since wave 9 β this makes that claim true for direct API
# callers. β MIRRORS types.ts `isModeFrozen` EXACTLY: SYSTEM views and the undeletable
# list:/cohort: projections are EXEMPT β their `locked` is legacy "undeletable", not
# mode-frozen, and freezing them would trap the default view in whatever mode it last
# saved (the owner's stuck-in-Map report is that trap, client-made). An upsert that
# UNLOCKS in the same write (authorised above) may change display freely.
_mode_frozen = (prior.get('locked') and raw.get('locked') is not False
and prior.get('kind') != 'system'
and view_id != 'all-customers')
if _mode_frozen:
if prior.get('config', {}).get('application'):
config['application'] = dict(prior['config']['application'])
else:
config.pop('application', None)
if prior.get('config', {}).get('display'):
config['display'] = dict(prior['config']['display'])
else:
config.pop('display', None)
# C3: only the creator or an admin may SET or CLEAR the lock; anyone else keeps whatever
# is already stored. Enforced here rather than hidden in the client. This composes with
# C4 and does not override it: C4 governs who may edit the CONTENTS, C3 who may freeze
# the display MODE.
# β Inert in practice TODAY β a user can only ever write their own per-user workspace,
# so `uname == creator` always holds. Correct plumbing for shared views, not a live gate.
may_lock = admin or uname == creator
locked, lock_refusal = clean_view_member(
'locked', raw.get('locked', False) if may_lock else prior.get('locked', False), ctx, prior)
if lock_refusal:
locked = bool(prior.get('locked')) if not is_new else False
# C3: the LOCK's actual job β a locked view's display mode is frozen, so a locked Kanban
# stays Kanban. This half IS live per-user and is the part the owner asked for. Filters,
# sorts and columns stay editable by design.
if _mode_frozen:
was = (prior.get('config') or {}).get('display')
now = config.get('display')
if (was or {}).get('mode') != (now or {}).get('mode'):
if was:
config['display'] = was
else:
config.pop('display', None)
# WAVE 17 R1 (C-LOCKV guard b) β ONE THING, ONE NAME. Renaming a locked view renames
# the SET it is, in the store that owns it; the view record must not grow a second title
# that the read side would then have to arbitrate. Routed rather than duplicated.
if _is_locked_view and _store_of(ctx).available():
_sets = _cohorts(ctx) # R9: the SET lives in this topic's bucket
_cur = (_sets.all_for(uname).get(view_id) or {}).get('name')
if name and name != _cur:
try:
_sets.rename(uname, view_id, name)
except ValueError as _e:
_tel.error('cohort:rename-via-view', _e)
view = {'id': view_id, 'name': name,
# β DERIVED FROM THE ID, never taken from the browser: `kind` is what paints the
# lock mark, so a client claiming it for an ordinary view would be claiming a
# guarantee the engine is not making about that view's rows.
'kind': _ag.LOCKED_VIEW_KIND if _is_locked_view
else raw.get('kind') if raw.get('kind') in ('system', 'list', 'custom')
else 'custom',
'locked': locked,
'createdBy': creator,
'note': clean_view_member('note', raw.get('note'), ctx, prior)[0],
'config': config,
'filterRemovals': filter_removals}
# System/list projections are not all persisted in this table store, but custom views
# may not impersonate their visible names. Persisted view names are allocated
# tenant-globally by TableStore inside the write transaction.
_reserved_view_names = [
value.get('name') for value in visible_views
if (isinstance(value, dict) and value.get('id') != view_id
and value.get('kind') in ('system', 'list'))
]
# Wave 21 (item 3, R6): the reserved SYSTEM name is PER-TOPIC β a ut_ database's system
# view is "All records", and reserving the customer literal there uniquified a user's
# honest "All customers" view name against a string that never appears on that topic.
_scope = str(getattr(ctx, 'scope_key', '') or 'customer').strip().lower()
_sys_name = ('All products' if _scope == 'product'
else 'All records' if _scope.startswith('ut_') else 'All customers')
if view_id != 'all-customers':
_reserved_view_names.append(_sys_name)
# β WAVE 21 (item 9, C1) β THE FOREIGN-VIEW WALL. A granted view is projected into the
# receiver's rail, so their autosave can now emit an upsert carrying an id they do not
# own. Silently saving that into the RECEIVER's stratum would FORK the view (own views
# win the merge, so the receiver sees their private copy forever and calls sharing
# broken). Role `edit` (or admin) writes THROUGH to the owner's record β config only;
# `createdBy` stays pinned from the stored source and grants remain the access wall.
# A reader receives a result-row refusal before any View mutation.
#
# ββ WAVE 33 Β· T13 (owner item 3) β A PINNED PER-USER ID IS NOT A FOREIGN VIEW, AND
# TREATING IT AS ONE IS A CROSS-USER WRITE THAT REPORTS SUCCESS.
#
# `find_view` scans EVERY personal stratum and returns the FIRST match. `all-customers`
# and `tpl_overview` are PINNED ids that every user of a table has their own copy of β
# so the moment ANY colleague autosaves one (a column resize is enough), the wall reads
# "somebody else owns this id" for everybody else. MEASURED, on this exact path, after
# one colleague resized a column on the Overview:
# Β· a NON-ADMIN marking it is REFUSED, with a toast blaming sharing β a view nobody
# ever shared, on their own database;
# Β· an ADMIN marking it answers 200 and writes the mark into the OTHER USER'S
# stratum. The admin's own workspace still serves the un-marked view, so the mark
# "does not work"; the colleague silently gains a mark they never made.
# That is item 3's second mechanism, and it is a residency bug wearing a sharing bug's
# error message.
#
# β THIS FUNCTION ALREADY STATES THE RULE THE WALL BREAKS, seventy lines up: "A SYSTEM
# VIEW IS PER-USER STATE AND MUST NEVER BE SHARED", enforced there by pinning
# `perms = {'edit': 'personal'}`. A per-user view can therefore never BE a grant, which
# is the only thing this wall exists to protect β so exempting it narrows nothing.
# W48-T20 / C4 β an assignment is neither the owner's view nor a generic foreign
# share. Its filter lives in TableStore's ``__assigned__`` projection and this write
# door accepts only the recipient's presentation. In particular, a forged ``edit``
# grant or a client flip of ``assigned`` cannot route this through the generic
# share-through-to-owner branch below.
if is_assigned:
if view_id not in assigned:
ctx.out.toast = 'That assigned view is no longer available to you.'
return False
try:
_tops(ctx).save_assigned_presentation(uname, view_id, config)
except ValueError:
ctx.out.toast = 'That assigned view is no longer available to you.'
return False
# The API adapter re-reads workspace after a durable event. Returning True is
# load-bearing: it replaces any optimistic browser filter with the locked server
# projection before another action can use it.
return True
if _store_of(ctx).available():
# β W50-T25 / D8 β `_save_as` IS THE BUCKET THE WRITE LANDED IN and is therefore
# the audit `owner`; `uname` is who DID it. On the foreign-owner branch above they
# differ, and a row that conflated them would name the wrong person in the one
# record whose entire job is naming the right one.
view = (_tops(ctx).save_view(
_save_as, view, reserved_names=_reserved_view_names,
actor=uname, origin=EVENT_ORIGIN) or view)
else:
_session_ready()
_view_names = list(_reserved_view_names)
_view_names.extend(
value.get('name')
for candidate_id, value in ws['views'].items()
if candidate_id != view_id and isinstance(value, dict)
)
view['name'] = _unique_name(view.get('name'), _view_names)
ws['views'][view_id] = view
_sync_view_field_inheritance(ctx, view)
name_changed = view.get('name') != requested_name
# PERSISTED, but deliberately NO rerun β see the return-value contract in
# this function's docstring. This is the hot path: every filter, sort,
# group, colour, column-resize and column-toggle autosaves through here.
#
# CG-8 is the ONE exception, and it is self-limiting. A measure condition is answered
# server-side, so if this view carries one whose answer was NOT in the payload we just
# shipped, the client is showing a pending marker with nothing coming. Ask for exactly
# one more run β and only then, so the common case (a column filter) still costs zero.
# If the top-of-run read of the component's own value already covered it, this is False
# and nothing extra happens; if that read is ever stale, this is what stops the
# condition hanging unresolved.
#
# β COMPLETE rules only (wave-6 item 3, found by the live roundtrip on this rev):
# picking a measure FIELD mints a valueless rule whose autosave used to land here as
# "unresolved" and trigger a rerun that could resolve NOTHING β `rule_complete` refuses
# half-asked questions β so the only effect was a remount that closed the builder
# popover mid-build (the wave-5 "gate flake" runs, now explained). A rule still being
# typed stays client-side PENDING by design; the run that matters fires when its VALUE
# arrives and the question becomes answerable.
from harness import measure_filter as _mfc
unresolved = {str(r.get('id') or '') for r in measure_leaves(filters)
if _mfc.rule_complete(r)} - set(resolved_ids)
return name_changed or bool(unresolved - {''})
if kind == 'view_delete':
view_id = str(event.get('viewId') or '')[:120]
# β WAVE-27 item 27 (R8) β `IG_OVERVIEW_ID` joins the system view here, and the comment
# eight lines down already explains why in the LOCKED-view case: dropping the saved
# config leaves the PROJECTION, which rebuilds the row on the very next render. Overview
# is injected on every read of an Instagram database, so a delete would look like it
# worked and the view would be back after a reload β which is precisely the
# reads-as-success failure the client's own `UNDELETABLE_VIEW_IDS` note describes.
if not view_id or view_id in ('all-customers', _ag_overview_id()):
return False
# WAVE 17 R1 (C-LOCKV guard c) β deleting a LOCKED view deletes the set it is. Without
# this the store would drop the saved config and the projection would rebuild the view
# on the very next render: the row would come back, minus the user's sort and columns,
# which reads as a corruption rather than as a refusal. Own sets only (`all_for`), the
# same wall `cohort_delete` rides.
if _store_of(ctx).available() and view_id in _cohorts(ctx).all_for(uname):
_cohorts(ctx).delete(uname, view_id)
_tops(ctx).delete_view(uname, view_id, actor=uname, origin=EVENT_ORIGIN)
# True, unlike an ordinary view_delete: the lists payload IS server truth and the
# client cannot know the membership channel changed.
return True
if _store_of(ctx).available():
# R14: a recipient dismisses only their own assignment. The source View and every
# other recipient's projection remain intact; this is intentionally not a grant
# revoke and not a source deletion.
if _tops(ctx).dismiss_assigned_view(uname, view_id):
return True
_foreign = _tops(ctx).find_view(view_id)
if _foreign and _foreign[0] != uname:
if not admin:
ctx.out.toast = 'Only the owner can delete this Saved View.'
return False
# β W50-T25 / D8 β AN ADMIN DELETING A COLLEAGUE'S VIEW. `_foreign[0]` owns
# the record and `uname` is doing the deleting; the trail must say both.
_tops(ctx).delete_view(_foreign[0], view_id,
actor=uname, origin=EVENT_ORIGIN)
try:
import core.shares as _shares
_shares.drop_objects([('view', view_id)], st=getattr(_tops(ctx), 'st', None))
from core import field_permissions as _fp
_fp.drop_view_field_boundary(view_id, st=getattr(_tops(ctx), 'st', None))
except Exception:
pass
return True
if not _foreign:
return False
_tops(ctx).delete_view(uname, view_id, actor=uname, origin=EVENT_ORIGIN)
try:
import core.shares as _shares
_shares.drop_objects([('view', view_id)], st=getattr(_tops(ctx), 'st', None))
from core import field_permissions as _fp
_fp.drop_view_field_boundary(view_id, st=getattr(_tops(ctx), 'st', None))
except Exception:
pass
else:
_session_ready()
ws['views'].pop(view_id, None)
try:
from core import field_permissions as _fp
_fp.drop_view_field_boundary(view_id, st=ctx.st)
except Exception:
pass
# Wave-6 item 3: the client removed the view optimistically; a deleted view simply
# stops being served, so the next render differs in nothing the client still shows.
return False
if kind == 'field_upsert':
raw = event.get('field')
if not isinstance(raw, dict):
return _refuse(ctx, 'malformed',
'the event carried no field object')
key = str(raw.get('key') or '')[:80]
import aios_grid as _ag2
from core import field_permissions as _fp
# Runtime-created tenant-wide fields have a definition outside the
# per-user workspace. Product Image is the first such editable field;
# keep the opt-in marker so existing shared schema fields retain their
# own definition doors.
shared_prior = None
shared_field = False
source_backed = False
shared_storage_key = None
grant_topic = None
spreadsheet_choice_created = False
if ctx.table is not None:
try:
import core.shared_overlay as _shared_overlay
table_key = str(ctx.table.table_key)
shared_storage_key, grant_topic = _field_share_keys(ctx)
shared_prior = (_shared_overlay.fields(
shared_storage_key, st=ctx.table.st) or {}).get(key)
shared_field = bool(isinstance(shared_prior, dict)
and shared_prior.get('custom'))
except Exception:
shared_prior = None
# Product's spreadsheet-backed choice columns are ordinary tenant-shared
# definitions, created by the person who saves them (normally the
# Administrator account), rather than source API presets.
# A prior W43 value edit may already have created a bare ``{key,
# options}`` shared entry, so merge that vocabulary over the canonical
# definition before opening the definition door.
base_field = field_by_key.get(key)
spreadsheet_choice = (
scope_key == 'product'
and isinstance(base_field, dict)
and base_field.get('source') == 'overlay'
and base_field.get('shared') is True
and base_field.get('custom') is True
and base_field.get('type') in ('select', 'multiselect')
)
if spreadsheet_choice:
stored_choice = shared_prior if isinstance(shared_prior, dict) else {}
spreadsheet_choice_created = not bool(stored_choice.get('custom'))
shared_prior = {**base_field, **stored_choice,
'key': key, 'source': 'overlay', 'shared': True,
'custom': True, 'type': base_field['type']}
# Registry admission comes from the server context, even when the native
# definition stores granted=False. The stored marker is persistence only.
if base_field.get('granted') is True:
shared_prior['granted'] = True
shared_field = True
if shared_field:
if not _may_edit_field_definition(ctx, key, shared_prior):
return _refuse(
ctx, 'field_read_only',
'you can only change this field if you created it or have Can edit access',
key)
# Pin the type/source/key to the stored definition. Only the
# user-authored settings below are allowed to change, so a browser
# cannot turn an image field into another schema type while saving
# its permissions.
field = dict(shared_prior)
# The Product choice projection may derive granted=True from the registry.
# Keep it for admission above, but persist only the native marker state.
if spreadsheet_choice:
if 'granted' in stored_choice:
field['granted'] = stored_choice['granted']
else:
field.pop('granted', None)
field['label'] = str(raw.get('label') or field.get('label') or 'Untitled')[:120]
field['note'] = str(raw.get('note') or '')[:2000]
fmt = _ag2._clean_format(raw.get('format'), field.get('type'))
if fmt:
field['format'] = fmt
else:
field.pop('format', None)
# The existing Image shared field has no vocabulary. Spreadsheet
# choices do, and the definition writer has to validate and retain
# its list and visual treatment rather than silently preserving a
# read-only source projection.
if field.get('type') in ('select', 'multiselect') and 'options' in raw:
try:
options = _ag2._clean_options(raw.get('options'))
except _ag2.OptionLimitExceeded as exc:
return _refuse(ctx, 'option_limit', str(exc), key)
if not options:
return _refuse(
ctx, 'no_options', 'a select column needs at least one choice', key)
field['options'] = options
field.update(_ag2._choice_appearance({**field, **raw}, options))
# The canonical spreadsheet declaration predates the normal field
# definition record. Its first normal save is a creation, so stamp
# the actual creator exactly as any other shared field does.
if spreadsheet_choice and not str(field.get('createdBy') or '').strip():
field['createdBy'] = uname
elif key.startswith(_ag2.MEASURE_FIELD_PREFIX):
# A FORMULA-MEASURE column (owner item 7). Validated against THIS caller's measure
# offer β the same admission the condition builder uses β so a field can only name a
# measure this user could also filter by. Fail closed on anything else.
field = _ag2.clean_measure_field(raw, {m['key']: m for m in measure_offer})
if field is None:
return _refuse(
ctx, 'measure_not_offered',
'this measure is not one you can filter by on this page, so a column '
'cannot be built from it', key)
fmt = _ag2._clean_format(raw.get('format'), field.get('type'))
if fmt:
field['format'] = fmt
elif key in field_by_key and not key.startswith('custom_'):
base = field_by_key[key]
source_backed = True
field = {**base, 'note': str(raw.get('note') or '')[:2000]}
# β W29-T83 β THE COLUMN SUMMARY ON A SOURCE-BACKED COLUMN. This branch rebuilds the
# accepted def from the CONTRACT and adds only what a user may override, and `agg` was
# not in that list β so Average on Customer's `Overdue days` was accepted with a 200
# and dropped here, before it ever reached the store. Validated against the shared
# vocabulary rather than a literal (see the custom branch below for what a literal
# costs). An ABSENT or unknown `agg` clears it: the client sends the whole field on
# every edit, so a missing key is a user who unset the summary, and `{**base}` has
# already re-applied whatever the contract itself declares.
_agg = raw.get('agg')
if _agg in _ag2.FIELD_AGGS:
field['agg'] = _agg
else:
field.pop('agg', None)
# Wave-5 item 10: a DISPLAY format on any base field (presets included) β how a
# number/date reads, per user. Rendering-only; validated fail-closed per type.
fmt = _ag2._clean_format(raw.get('format'), base.get('type'))
if fmt:
field['format'] = fmt
else:
field.pop('format', None) # cleared -> back to the type's default render
# PRESET measure fields (wave-2 item 8): the browser may change the PERIOD (and the
# auto-renamed label) of revenue_ytd / revenue_ly / orders_24m β nothing else. The
# whitelist IS the base contract: only a field that shipped with preset+measure can
# take a window here, and the measure KEY is pinned to the base's (fail closed).
if (base.get('preset') and isinstance(base.get('measure'), dict)
and isinstance(raw.get('measure'), dict)):
window = _ag2._clean_window(raw['measure'].get('window'))
if window is not None:
field['measure'] = {'key': base['measure']['key'], 'window': window}
if isinstance(raw.get('label'), str) and raw['label'].strip():
field['label'] = str(raw['label'])[:120]
elif key.startswith('custom_') and raw.get('type') in _ag2.CUSTOM_FIELD_TYPES:
ftype = raw['type']
# ββ 2026-08-09 β THE RELATIONAL PAIR HAS NO HOME IN A PER-USER OVERLAY, and this
# door used to accept one silently. It builds the stored field from a fixed key list
# and adds only the bags it knows (`options`, `max`, `formula`, `automation`, `code`)
# β so a `link`/`rollup` arriving here was stored WITHOUT its bag, in one user's
# stratum, where `compute_relation_cells` (which walks `user_tables` definitions)
# never sees it. Measured on nurilab as `custom_video_views_90j26`: a Rollup column
# that rendered, could not be filled by anything, and reported no error.
# β REFUSED RATHER THAN REPAIRED. These two belong to the table's SHARED schema
# (`POST /tables/{key}/fields`), which is where the client now sends them; storing a
# second, private, non-computing copy here would be a second definition of the same
# column. A refusal repaints, so a stale client says something rather than nothing.
if ftype in ('link', 'rollup') or (ftype == 'if' and scope_key.startswith('ut_')):
return _refuse(
ctx, 'wrong_door',
'Create this schema field from the Fields panel through '
'POST /api/v1/tables/{key}/fields. On a connected registry database, '
'only an administrator can create a Link field here.', key)
readonly = ftype in _ag2.READONLY_CUSTOM_TYPES
# The editable family must SAY it is overlay (the client's own contract); the
# read-only pair (formula / created_time) is stored under the cohort column's
# mechanism instead, so no cell write can ever be accepted for it.
if not readonly and raw.get('source') != 'overlay':
return _refuse(
ctx, 'source_not_overlay',
"an editable column must declare source 'overlay'; this one declared "
'%r' % (raw.get('source'),), key)
field = {'key': key, 'label': str(raw.get('label') or 'Untitled')[:120],
'type': ftype, 'source': 'odoo' if readonly else 'overlay',
'default': True, 'custom': True,
'note': str(raw.get('note') or '')[:2000]}
if readonly:
field['derived'] = True
# FILTERABLE since wave 6 (owner item 6): formula/created_time values live
# client-side, and this table's counts are client-mode β the client engine
# answers conditions on them soundly. Mirrors fields_from_workspace.
field['filterable'] = True
# β W29-T83 β THE VOCABULARY, NOT THE LITERAL `'sum'`. This is the write gatekeeper
# for an overlay column's summary and it accepted exactly one name, while the READ
# projection (`aios_grid.py:679`) passes all six β so a user who chose Median got a
# 200, a menu that said Median, and no summary after the next reload. The same shape
# as the `agg:"sum"` defect this repo already shipped, where one door kept it and the
# other dropped it ([[read-path-cannot-witness-write-path]]).
_agg = raw.get('agg')
if _agg in _ag2.FIELD_AGGS and not readonly:
field['agg'] = _agg
# A `select`/`multiselect` carries its own vocabulary; a `user` does NOT β its
# choices are the tenant's accounts, resolved fresh on every render, so persisting
# a snapshot here would go stale the moment somebody joins or leaves.
if ftype in ('select', 'multiselect'):
try:
field['options'] = _ag2._clean_options(raw.get('options'))
except _ag2.OptionLimitExceeded as exc:
return _refuse(ctx, 'option_limit', str(exc), key)
if not field['options']:
# a select with no choices can never hold a value
return _refuse(
ctx, 'no_options',
'a select column needs at least one choice', key)
field.update(_ag2._choice_appearance(raw, field['options']))
if ftype == 'rating':
field['max'] = _ag2._clean_rating_max(raw.get('max'))
if ftype == 'formula':
# WRITE-time is where refs must exist (fail closed); read-time leaves them
# alone so a later-deleted ref blanks the CELLS, not the column.
formula = _ag2._clean_formula(raw.get('formula'), valid_keys)
if formula is None:
# β THE ONE D-275 IS MOST LIKELY TO BE. `valid_keys` is THIS page's column
# set, so a formula naming a column that exists on another grid is refused
# here and was, until now, indistinguishable from a save.
return _refuse(
ctx, 'formula_refs',
'the formula is empty or names a column this table does not have',
key)
field['formula'] = formula
if ftype == 'automation':
# C5-AUTOFIELD (wave 18): persist the validated config bag. No `return False`
# when absent β an unconfigured automation column is a legitimate intermediate
# state (create the column, then configure it in the gear).
# β C8 (wave 22): a CONFIGURED bag must name an existing flow β the write door
# reads the tenant's definition ids and `_clean_automation` refuses a bag
# without one (or naming a deleted one). Refused = the whole field write is
# refused, loudly (repaint), because storing the field while dropping its bag
# would be a column that silently never runs.
if isinstance(raw.get('automation'), dict):
try:
_flow_ids = frozenset((ctx.table.st if ctx.table is not None
else _tops(ctx).st).get('automations') or {})
except Exception:
_flow_ids = frozenset()
auto = _ag2._clean_automation(raw.get('automation'), valid_keys,
flow_ids=_flow_ids)
if auto is None:
return _refuse(
ctx, 'automation_flow',
'the automation this column names does not exist', key)
field['automation'] = auto
# β WAVE-27 item 13 (R13): the code column's language. OPTIONAL, like the
# `automation` bag above and unlike `formula` β an unconfigured code column is a
# legitimate intermediate state (create it, pick the language in the gear), and it
# stores and renders as plain text meanwhile. `_clean_code` never refuses over an
# unknown language; it falls back to `plain`, because the value chooses a
# HIGHLIGHTER, and dropping a user's column to punish a typo in one would be the
# disproportionate half of fail-closed.
if ftype == 'code' and isinstance(raw.get('code'), dict):
code_bag = _ag2._clean_code(raw.get('code'))
if code_bag:
field['code'] = code_bag
fmt = _ag2._clean_format(raw.get('format'), ftype)
if fmt:
field['format'] = fmt
# S76-T28: explicit null clears a default; omission keeps it only from a same-type definition.
if 'defaultValue' in raw:
_default = raw.get('defaultValue')
else:
_prior_def = shared_prior if shared_field else (ws.get('fields') or {}).get(key)
_default = (_prior_def.get('defaultValue') if isinstance(_prior_def, dict)
and _prior_def.get('type') == ftype else None)
if _default is not None:
from core import user_tables as _ut_default
if readonly or not _ut_default._default_value_valid(field, _default):
return _refuse(ctx, 'bad_default_value',
'The default value does not fit this field type.', key)
field['defaultValue'] = _default
else:
# β THE FALL-THROUGH, AND IT IS THE WIDEST OF THE EIGHT: the key is neither a base
# contract field (a note/format override) nor a `custom_`/`measure_` key, so there is
# no stratum it could be written to. A client sending an unprefixed new key lands
# here β and until D-291 that answered exactly like a save.
return _refuse(
ctx, 'unknown_key',
"a new column's key must start with 'custom_'; a base column can only take a "
'note or a format override', key)
# Wave-5 item 1 β createdBy + permissions on the CREATED strata (custom_/measure_).
# `createdBy` is stamped HOST-SIDE at create and preserved on every later write: the
# client never supplies it, so a browser cannot claim someone else's field. A
# permissions CHANGE is accepted only from the creator or an admin; a legacy field
# with no createdBy is admin-only (fail closed, both directions). The table workspace
# is per-user today, so this wall becomes load-bearing when sharing arrives β but the
# admin path and the legacy path are enforceable (and NC'd) right now.
# W43: recurrence is configuration on a scalar Date field. The DatePicker sends the
# complete server-shaped bag; an older field editor that omits it preserves the existing
# setting rather than deleting a schedule merely by changing the note.
if field.get('type') == 'date':
recurrence_raw = raw.get('recurrence') if 'recurrence' in raw else field.get('recurrence')
# An omitted recurrence is an older editor changing another Date property, so it
# preserves the stored schedule. An explicit JSON null is the DatePicker's clear
# command and must not fall through to that preservation branch.
if 'recurrence' not in raw and recurrence_raw is None and not shared_field:
previous = (ws.get('fields') or {}).get(key)
recurrence_raw = previous.get('recurrence') if isinstance(previous, dict) else None
if 'recurrence' in raw:
if recurrence_raw is not None and ctx.recurrence_validator is None:
return _refuse(
ctx, 'bad_recurrence',
'recurrence needs the server field-authority validator', key)
try:
recurrence = (ctx.recurrence_validator(recurrence_raw)
if ctx.recurrence_validator is not None else None)
except (TypeError, ValueError) as exc:
return _refuse(ctx, 'bad_recurrence', str(exc)[:240], key)
else:
recurrence = _ag2.clean_date_recurrence(recurrence_raw)
if recurrence:
field['recurrence'] = recurrence
else:
field.pop('recurrence', None)
if field.get('type') == 'if':
from core.if_field import admit_sources, DefinitionError
previous = shared_prior if shared_field else (ws.get('fields') or {}).get(key)
definition = raw.get('if') if 'if' in raw else (previous or {}).get('if')
# A restricted reader can rename a field without receiving its source definition.
try:
field['if'] = admit_sources(definition, ctx.hidden_keys or (),
(previous or {}).get('if'))
except DefinitionError as exc:
return _refuse(ctx, exc.code, str(exc), key)
field.update(source='odoo', derived=True, filterable=True, valueAuthority='computed')
needs_values = False
refused_perms = False
permission_sync = False
promoted_this_save = False
if shared_field or key.startswith('custom_') or key.startswith(_ag2.MEASURE_FIELD_PREFIX):
prior = shared_prior if shared_field else ws.get('fields', {}).get(key)
prior = prior if isinstance(prior, dict) else None
if prior is not None and not shared_field \
and not _may_edit_field_definition(ctx, key, prior):
return _refuse(
ctx, 'field_read_only',
'you can only change this field if you created it or have Can edit access',
key)
if prior is None and not shared_field:
field['createdBy'] = uname
# Wave-6 item 9: scope is chosen at CREATE, on the cohort page only β
# 'cohort' marks the field cohort-specific; 'global' or absent stays
# unscoped, so an old bundle that sends no scope keeps today's behavior.
if scope_key == 'cohort' and raw.get('scope') == 'cohort':
field['scope'] = 'cohort'
else:
if isinstance(prior.get('createdBy'), str) and prior['createdBy'].strip():
field['createdBy'] = prior['createdBy']
# Scope is PRESERVED like createdBy: the client copy never moves an
# existing field between scopes.
if prior.get('scope') == 'cohort':
field['scope'] = 'cohort'
has_permission_request = isinstance(raw.get('permissions'), dict)
have = (_fp.stored_permissions(prior, fallback='collaborative')
if prior is not None else {'edit': 'personal'})
want = (_fp.clean_permissions(raw.get('permissions'), fallback=have['edit'])
if has_permission_request else have)
owner = field.get('createdBy')
may_change_permissions = bool(admin or (owner and owner.lower() == uname.lower()))
if may_change_permissions:
field['permissions'] = want
permission_sync = has_permission_request
else:
field['permissions'] = have
# Asked for a permissions change and did not get it: the client's
# optimistic copy is a lie that must be repainted (wave-6 item 3).
refused_perms = has_permission_request and want != have
# A NEW measure column, or an existing one whose window moved: the VALUES
# are host-computed, so the next render genuinely differs.
if key.startswith(_ag2.MEASURE_FIELD_PREFIX):
needs_values = prior is None or prior.get('measure') != field.get('measure')
if field.get('type') == 'if':
needs_values = prior is None or prior.get('if') != field.get('if')
# Canonical names are reserved outside the durable workspace. Persisted field names are
# allocated by TableStore from the transaction's current state, not this stale snapshot.
_workspace_field_keys = set((ws.get('fields') or {}))
_reserved_field_names = [
value.get('label') for candidate_key, value in field_by_key.items()
if (candidate_key != key and candidate_key not in _workspace_field_keys
and isinstance(value, dict))
]
desired_shared = field.get('permissions', {}).get('edit') in ('collaborative', 'users')
if field.get('type') == 'if' and (shared_field or desired_shared):
from core import shared_overlay as _if_shared
if 'if' not in _if_shared.ALLOWED_FIELD_KEYS:
return _refuse(ctx, 'if_definition_storage_unavailable',
'The shared field store cannot preserve an If statement definition.', key)
if not shared_field and desired_shared and shared_storage_key and ctx.table is not None:
# Promotion makes the permission choice true for the whole tenant, rather than merely
# storing a collaborative label in Anna's private workspace.
field = _fp.promote_field(ctx.table.table_key, shared_storage_key, grant_topic,
field.get('createdBy') or uname, field, st=ctx.table.st)
shared_field = True
promoted_this_save = True
if shared_field:
# A shared definition is the source of truth for every tenant
# member. Persisting this through TableStore.save_field would put
# the permission back into the creator's private stratum and make
# the successful UI save invisible to everybody else.
import core.shared_overlay as _shared_overlay
field = _shared_overlay.put_field(shared_storage_key, key, field,
st=ctx.table.st)
if permission_sync or promoted_this_save:
import core.shares as _shares
_shares.set_grants('field', _shares.field_oid(grant_topic, key),
_fp.grant_entries(field.get('permissions')),
owner=field.get('createdBy') or uname, st=ctx.table.st)
elif spreadsheet_choice_created:
# The first ordinary save turns the spreadsheet declaration
# into a normal field created by this user and shared to the
# same collaborative audience as its cells.
import core.shares as _shares
_shares.set_grants('field', _shares.field_oid(grant_topic, key),
_fp.grant_entries(field.get('permissions')),
owner=field.get('createdBy') or uname, st=ctx.table.st)
elif _store_of(ctx).available():
saved_field = _tops(ctx).save_field(
uname, field, reserved_names=_reserved_field_names,
correction_id=event_id)
if not saved_field:
raise StoreUnavailable('The field definition was not saved.')
field = saved_field
else:
_session_ready()
_field_names = list(_reserved_field_names)
_field_names.extend(
value.get('label')
for candidate_key, value in ws['fields'].items()
if candidate_key != key and isinstance(value, dict)
)
requested_label = ' '.join(
str(field.get('label') or 'Untitled').split())[:120].rstrip()
field.pop('labelCorrectedFrom', None)
field.pop('labelCorrectionId', None)
field['label'] = _unique_name(requested_label, _field_names)
if field['label'] != requested_label and event_id:
field['labelCorrectedFrom'] = requested_label
field['labelCorrectionId'] = str(event_id)[:180]
# β W29-T83 β THE SAME PREDICATE the store uses, called rather than restated. This
# fallback carried its own shorter copy (note only), so a format or measure override
# survived one path and not the other, and `agg` survived neither.
if _tstore.source_override_is_empty(field):
ws['fields'].pop(key, None)
else:
ws['fields'][key] = field
if ctx.fallback_ws is None and not _tstore.source_override_is_empty(field):
if shared_field:
fresh_fields = _shared_overlay.fields(shared_storage_key, st=ctx.table.st) or {}
else:
fresh_fields = (table_workspace(
ctx, allowed_pids=allowed_pids, consume_corrections=False,
admission=False).get('fields') or {})
durable_field = fresh_fields.get(key)
if source_backed:
durable_field = _source_echo(field, durable_field)
if not isinstance(durable_field, dict) or not _field_echo_equal(durable_field, field):
raise StoreUnavailable('The saved field definition could not be read back.')
from core.if_field import project_fields
ctx.out.writes[event_id] = {
'ok': not refused_perms,
'value': project_fields([field], ctx.hidden_keys or ())[0], 'refused': refused_perms,
'reason': 'field_permissions_refused' if refused_perms else ''}
if needs_values or refused_perms:
return True
# THE NO-BLIP RETURN (wave-6 item 3): an accepted def that echoes what the client
# already renders needs no rerun β see _field_echo_equal and the docstring's law.
return not _field_echo_equal(field, raw)
if kind in ('cohort_add', 'cohort_remove', 'cohort_rename', 'cohort_delete'):
# Cohort membership/lifecycle edits from the grid's cohort panel (wave-2 item 2 β
# replaces the retired Manage popover, so rename/delete keep a surface). Fail-closed:
# only the caller's OWN cohorts (all_for), and member pids are intersected with the
# caller's permitted pool β the same guard add_to_list rides.
if not _store_of(ctx).available():
return False
sets = _cohorts(ctx) # R9: this DATABASE's lists, never another's
cohort_id = str(event.get('cohortId') or '').strip()[:120]
if not cohort_id or cohort_id not in sets.all_for(uname):
return False
try:
if kind == 'cohort_rename':
name = str(event.get('name') or '').strip()[:120]
if not name:
return False
sets.rename(uname, cohort_id, name)
elif kind == 'cohort_delete':
sets.delete(uname, cohort_id)
else:
raw_pids = event.get('pids')
if not isinstance(raw_pids, list):
return False
pids = [p for p in raw_pids if isinstance(p, int) and p in allowed_pids]
if not pids:
return False
if kind == 'cohort_add':
sets.add_members(uname, cohort_id, pids)
else:
sets.remove_members(uname, cohort_id, pids)
except ValueError as e:
_tel.error('cohort:panel-edit', e)
return False
# True: the lists payload (names, membership, counts) must reflect this on the next
# render β the panel is showing server truth, not local optimism.
return True
if kind in ('doc_add', 'doc_delete', 'doc_fetch'):
# DOCUMENTS on a row (owner item 12, contract C5). Metadata in the store key
# `customer_docs`; the BYTES live at their own path in the tenant dataset, never in a
# JSON blob β see core.store.upload_bytes for why that distinction is load-bearing.
#
# β WAVE 19 / R9 β item 1's SILENT THIRD CASE, and the one nobody reported because the
# React shell cannot reach it yet (`payload.docs` is set only by app.py). Both homes are
# keyed by pid and both were topic-blind: the metadata bucket AND the byte path
# `docs/<pid>/β¦`. Two topics' pid spaces overlap by construction (a CRC32 hash lands
# anywhere an Odoo partner id can), so a product's file could occupy the path of a
# customer's β one upload silently shadowing another tenant-visible document. Per-topic
# bucket AND per-topic prefix; the customer topic keeps both of its shipped names.
import base64 as _b64c
import re as _re_mod
if not _store_of(ctx).available():
return False
docs_key = _docs_key(ctx)
docs_dir = 'docs' if docs_key == _DOCS_KEY else f'docs/{docs_key[:-5]}'
pid = event.get('pid')
doc_id = str(event.get('docId') or '').strip()[:80]
# The pid wall is the SAME one every other row-scoped event rides: a caller may only
# touch rows inside their own permitted pool. Without it, documents would be the
# one surface where a scoped agent could read another book's rows.
if not isinstance(pid, int) or pid not in allowed_pids or not doc_id:
return False
# β WAVE 25 (R6b / D-16) β THE DOCUMENTS FAMILY WAS THE LAST MODULE-GLOBAL READER HERE.
# Every line below said `store.β¦`, so an R2 tenant's document metadata (and its bytes)
# landed in tenant #0's repo. Wave 19 made this family per-TOPIC; per-TENANT is the axis
# it was still missing, and the two failures look identical from the app.
_st_docs = _store_of(ctx)
meta_all = _st_docs.get(docs_key) or {}
row = list((meta_all.get(str(pid)) or []))
if kind == 'doc_add':
raw_b64 = event.get('data_b64')
name = str(event.get('name') or 'document')[:200]
if not isinstance(raw_b64, str) or not raw_b64:
return False
try:
blob = _b64c.b64decode(raw_b64, validate=True)
except Exception:
return False # not base64 -> not a file we will store
# Re-check the DECODED size host-side. The client checks it too, but a client check
# is a courtesy: this is the number that bounds what the tenant's repo can be made
# to hold by anyone who can reach the endpoint.
if not blob or len(blob) > _DOC_MAX_BYTES:
return False
if len(row) >= _DOC_MAX_PER_ROW or any(d.get('id') == doc_id for d in row):
return False
safe = _re_mod.sub(r'[^A-Za-z0-9._-]', '_', name)[:80] or 'file'
path = f'{docs_dir}/{pid}/{doc_id}_{safe}'
try:
_blobs(ctx).upload_bytes(
path, blob, message=f'doc {doc_id} for {scope_key} {pid}')
except Exception as _ue:
_tel.error('docs:upload', _ue)
return False
row.append({'id': doc_id, 'name': name,
'mime': str(event.get('mime') or 'application/octet-stream')[:120],
'size': len(blob), 'by': uname,
'ts': dt.datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
'path': path})
elif kind == 'doc_delete':
hit = next((d for d in row if d.get('id') == doc_id), None)
if not hit:
return False
# THE WALL: the uploader or an admin. Enforced here regardless of what the client
# chose to render β `canDelete` in the payload only hides a button.
if hit.get('by') != uname and not admin:
return False
_blobs(ctx).delete_path(hit.get('path') or '')
row = [d for d in row if d.get('id') != doc_id]
else: # doc_fetch
hit = next((d for d in row if d.get('id') == doc_id), None)
if not hit:
return False
blob = _blobs(ctx).download_bytes(hit.get('path') or '')
if blob is None:
return False
# The bridge is a fire-and-forget event LOG with no response channel, so the answer
# is PARKED on the Result and rides the next render's payload (C5).
ctx.out.doc = {
'pid': pid, 'docId': doc_id, 'name': hit.get('name') or 'document',
'mime': hit.get('mime') or 'application/octet-stream',
'data_b64': _b64c.b64encode(blob).decode('ascii')}
return True # re-render to deliver it
def _write(cur):
cur[str(pid)] = row
return cur
# β `docs_key`, NOT `_DOCS_KEY`. The read above and the byte path were both made
# per-topic and this line was not β so a product document's BYTES landed correctly under
# `docs/product/β¦` while its METADATA went into `customer_docs` beside the customer rows,
# keyed by a CRC32 hash. Found by `verify_scopes.py`'s own leg on its first run, which is
# the argument for asserting the ABSENCE from the legacy bucket and not just the presence
# in the new one: every "it saved" check here was green.
_st_docs.update(docs_key, _write, flush='async')
return True
if kind in ('folder_create', 'folder_rename', 'folder_delete', 'folder_duplicate',
'item_move', 'folder_reorder'):
# FOLDERS over the Views / Cohorts sidebars (owner item 11, contract C4). All five
# events touch ONE home β the table workspace's `folders` + `itemFolders` β so a cohort
# can be filed without the cohort STORE learning about folders at all.
import aios_grid as _agf
# ββ W41-T13 β NOT ONE BARE `False` LEAVES THIS BRANCH ANY MORE. Every exit below was a
# `return False`, which `routes_grid` renders as `{"results":[{"rerender":false}]}` β byte
# for byte a success. The user dragged a view, the rail sprang back, and the app said
# nothing at all. `refused` carries the cause a caller branches on; `_folder_refuse` also
# claims the one slot the client renders (see its note).
if not _store_of(ctx).available():
return _folder_refuse(
ctx, kind, 'store_unavailable',
'Your folders could not be saved because the workspace store is not reachable '
'right now, so nothing was changed. Try again in a moment.')
surface = str(event.get('surface') or '')
if surface not in _agf.FOLDER_SURFACES:
return _folder_refuse(
ctx, kind, 'surface_unknown',
'That folder change did not name a sidebar this page has, so nothing was saved. '
'Reload the page and try again.', key=surface)
# The ids this user may actually file: their own views, their own cohorts. Fail-closed β
# an item_move naming somebody else's cohort is dropped by clean_item_folders anyway,
# but refusing here means we never write it in the first place.
def _own_ids(sfc, cur_ws):
if sfc == 'views':
return set((cur_ws.get('views') or {}))
return set(_cohorts(ctx).all_for(uname))
# β A CELL THE CLOSURE FILLS, because `_mutate` has ONE way to say no β `return None` β
# and eleven distinct reasons for saying it. Threading the cause out through the existing
# sentinel keeps every refusal at the line that decided it, rather than re-deriving the
# reason at the caller from state that has already moved on.
why = {}
def _no(code, message, key=''):
"""Refuse from inside `_mutate`, naming the cause. Returns None, the sentinel."""
why.clear()
why.update({'code': code, 'message': message, 'key': str(key or '')})
return None
def _mutate(cur_ws):
folders = _agf.clean_folders(cur_ws.get('folders'))
placed = dict(cur_ws.get('itemFolders') or {})
lst = list(folders.get(surface) or [])
# β the wire field is `folderId` on EVERY folder event (CLIENT's types.ts is the
# built contract; the split doc's first draft said `id`). Converged here rather
# than asking the client to re-emit β see the C4 reconciliation note in the doc.
fid = str(event.get('folderId') or '').strip()[:80]
if kind == 'folder_create':
name = str(event.get('name') or '').strip()[:_agf.MAX_FOLDER_NAME]
if len(lst) >= _agf.MAX_FOLDERS:
# β THE CAP IS SPLIT OUT FROM THE MALFORMED CASE, because it is the one a
# person can actually do something about and the only one they will ever hit.
return _no('folders_at_cap',
f'This sidebar already holds {_agf.MAX_FOLDERS} folders, which is '
f'all it can show, so the new one was not created. Delete a folder '
f'you no longer need, then try again.', key=fid)
if not fid or not name:
return _no('folder_needs_a_name',
'A folder needs a name before it can be created, so nothing was '
'saved. Type a name and try again.', key=fid)
if any(f['id'] == fid for f in lst):
return _no('folder_already_exists',
'A folder with that id is already on this sidebar, so nothing was '
'created. Reload the page to see the folders you have.', key=fid)
row = {'id': fid, 'name': name, 'order': len(lst)}
icon = _agf.clean_folder_icon(event.get('icon')) # wave-9 I15 (C5)
if icon:
row['icon'] = icon
# OWNER INSTRUCTION 12 -- the client's `parent` reaches the store. Paired with
# `aios_grid.clean_folders`, which carries it through the sanitiser; NEITHER EDIT
# DOES ANYTHING ALONE. `clean_folders` runs over the whole list on every folder
# event, so a rename or a reorder cannot un-nest a folder as a side effect either.
# Bounded to 80 like every other id on this door, absent rather than null for the
# root, and self-parenting dropped. A parent naming a folder that has since been
# deleted is passed THROUGH on purpose: `validate_folder_tree` repairs it to the
# root and returns a receipt, which `_folder_repair_notice` already turns into the
# sentence the user reads.
parent = str(event.get('parent') or '').strip()[:80]
if parent and parent != fid:
row['parent'] = parent
lst.append(row)
elif kind == 'folder_rename':
name = str(event.get('name') or '').strip()[:_agf.MAX_FOLDER_NAME]
hit = next((f for f in lst if f['id'] == fid), None)
if not hit:
return _no('folder_gone',
'That folder is not on this sidebar any more, so it could not be '
'renamed. Reload the page to see the folders you have.', key=fid)
# ββ W41-T14 Β· OWNER INSTRUCTION 11 β AN ICON-ONLY EVENT IS LEGAL ON THIS DOOR.
#
# β THE SECOND HALF OF THE INSTRUCTION IS *"allow changing the icon from the
# '...' menu"* β a Change icon item, NOT the rename pane wave-9 built this branch
# for. A dialog that changes only the icon has no name to send, and until this
# line `{folderId, icon}` fell straight into the refusal below: the receiver of a
# gesture that never mentioned a name was told *"A folder needs a name"*, the icon
# was not stored, and both lanes were individually correct
# ([[two-lanes-one-contract-dead-feature]], with a wrong sentence on top).
#
# β THE DISCRIMINATION IS THE `name` KEY, NOT ITS EMPTINESS, and that is what
# keeps W41-T13's refusal intact: an event that CARRIES `name` and means blank is
# still a rename to nothing and is still refused, in T13's exact words. Today's
# client always sends one (`CustomerGrid.tsx::onFolderRename`), so every event
# that has ever been emitted takes the byte-identical path. An event with neither
# a usable name nor an `icon` key is malformed and is refused as it always was.
if not name and ('name' in event or 'icon' not in event):
return _no('folder_needs_a_name',
'A folder needs a name, so the new one was not saved and the old '
'name was kept. Type a name and try again.', key=fid)
if name:
hit['name'] = name
# wave-9 I15 (C5): the rename pane is also where the icon is changed. An event
# that carries NO icon key leaves the existing one alone (a rename must not
# silently strip a chosen icon); an explicit null clears it back to default.
# β W41-T14 MEASURED THE LIMIT RATHER THAN WIDENING IT: `clean_folder_icon`
# answers None for an explicit null AND for a junk shape, so this branch cannot
# tell *"clear my icon"* from *"that shape does not exist"* and drops the stored
# icon either way. Nothing junk is ever STORED, which is what this ticket owes;
# the conflation is booked rather than fixed here, because a new refusal would
# claim the single `toast` slot on the path W41-T35 is about to exercise.
if 'icon' in event:
icon = _agf.clean_folder_icon(event.get('icon'))
if icon:
hit['icon'] = icon
else:
hit.pop('icon', None)
elif kind == 'folder_delete':
if not any(f['id'] == fid for f in lst):
return _no('folder_gone',
'That folder is not on this sidebar any more, so there was nothing '
'to delete. Reload the page to see the folders you have.', key=fid)
lst = [f for f in lst if f['id'] != fid]
# CONTENTS MOVE TO ROOT, never delete. Dropping the placements is exactly that:
# an item with no placement renders at the top level.
placed[surface] = {k: v for k, v in (placed.get(surface) or {}).items()
if v != fid}
elif kind == 'folder_reorder':
# β WAVE 20 (owner item 19, contract C-FOLDER-REORDER) β the user's own folder
# ORDER in the rail. Views could already be dragged between folders; the folders
# themselves could not be dragged past each other.
#
# THE WIRE CARRIES THE FULL ORDER, NEVER A DELTA, and that is the contract's
# doing: a partial list cannot say where an UNNAMED folder went, so a "moved B
# after C" message would leave every other folder's position to be re-derived by
# two sides that can disagree. The client sends the list it is looking at.
#
# β IDS THIS USER DOES NOT OWN ARE IGNORED, NOT REJECTED. A stale tab can emit an
# order containing a folder that has since been deleted; dropping the whole event
# would make the rail un-reorderable until reload, while dropping the unknown id
# reorders exactly what still exists. Anything the payload omits keeps its
# relative position AFTER the named ones β an order that silently deleted a
# folder it merely failed to mention would be a data loss dressed as a sort.
order = [str(i).strip()[:80] for i in (event.get('order') or [])]
if not order:
return _no('order_named_no_folders',
'That rail arrangement named no folders, so the order you had was '
'kept. Drag the folder again.')
known = {f['id']: f for f in lst}
seen, ranked = set(), []
for fid_ in order:
if fid_ in known and fid_ not in seen:
seen.add(fid_)
ranked.append(known[fid_])
ranked.extend(f for f in lst if f['id'] not in seen)
if len(ranked) != len(lst): # cannot happen; refuse rather than truncate
return _no('order_incomplete',
'That rail arrangement could not be applied without losing a '
'folder, so the order you had was kept. Reload the page and try '
'again.')
for i, f in enumerate(ranked):
f['order'] = i
lst = ranked
elif kind == 'folder_duplicate':
new_id = str(event.get('newId') or '').strip()[:80]
src = next((f for f in lst if f['id'] == fid), None)
if len(lst) >= _agf.MAX_FOLDERS:
return _no('folders_at_cap',
f'This sidebar already holds {_agf.MAX_FOLDERS} folders, which is '
f'all it can show, so the copy was not made. Delete a folder you '
f'no longer need, then try again.', key=fid)
if not src:
return _no('folder_gone',
'That folder is not on this sidebar any more, so there was nothing '
'to copy. Reload the page to see the folders you have.', key=fid)
if not new_id:
return _no('duplicate_without_id',
'The copy was not given an id, so nothing was created. Try '
'duplicating the folder again.', key=fid)
if any(f['id'] == new_id for f in lst):
return _no('folder_already_exists',
'A folder with that id is already on this sidebar, so the copy was '
'not made. Reload the page to see the folders you have.',
key=new_id)
lst.append({'id': new_id, 'name': f"{src['name']} copy"[:_agf.MAX_FOLDER_NAME],
'order': len(lst)})
# β The folder's CONTENTS are duplicated by the client emitting the ordinary
# per-item duplicate events it already owns (view_upsert with a fresh id, the
# cohort copy path) and then item_move-ing them here. Copying views/cohorts
# inside this handler would be a SECOND implementation of "duplicate an item",
# and the two would drift the first time either one changed.
else: # item_move
item_id = str(event.get('itemId') or '').strip()[:120]
target = event.get('folderId')
# ββ W41-T13 / OWNER INSTRUCTION 10 β THE TWO CAUSES ARE SPLIT, and the split is
# the ticket's own argument: `not item_id` is a malformed event, `not in _own_ids`
# is a permission answer, and one `return None` for both told the user neither.
if not item_id:
return _no('move_without_item',
'That move did not say which item to file, so nothing was saved. '
'Drag the item again.')
# ββ W47-T12 Β· OWNER INSTRUCTION 3 β AN `itemId` NAMING A **FOLDER** IS A
# RE-PARENT, NOT A PLACEMENT.
#
# Owner: *"make sure we can drag and drop folder into another folder"*. Until this
# branch the product had no re-parent gesture at all: `folder_create` was the only
# event that carried `parent`, so a folder could be BORN inside another one and
# could never be MOVED into one afterwards.
#
# β NO NEW EVENT KIND, AND THAT IS A CONSTRAINT RATHER THAN A PREFERENCE. The
# client's `HostEvent` union and the emitters that build it live in files this
# ticket does not own, so a `folder_move` would have been a kind nothing could
# ever send. `item_move` already carries exactly the two fields a re-parent needs
# (what moved, where it went) and already lands on this door.
#
# β THE ORDER OF THE TWO TESTS IS THE WHOLE SAFETY OF IT. An id this user OWNS as
# an item is still an item move, checked first, so every event that has ever been
# emitted takes the byte-identical path it always did. Only an id that is NOT an
# item β which until today was refused outright as `item_not_yours` β is looked up
# among the folders. A view and a folder cannot both answer to one id here, and if
# they somehow did the item would win and nothing new would happen.
#
# β THE TREE WALL IS `validate_folder_tree`, NOT THIS BRANCH, and deliberately so:
# `save_folders` below already refuses a multi-folder cycle and any chain past
# `MAX_FOLDER_DEPTH`, naming the shallowest folder at fault in a sentence
# `_folder_refuse` turns into a toast. Re-deriving either rule here would be a
# second evaluator for a question that already has one, and the two would drift
# the first time the cap moved. What this branch owes is the part the validator
# cannot answer: the parent has to be a folder that IS HERE.
#
# β THE ONE CASE THE VALIDATOR NEVER SEES IS A **SELF**-PARENT, and this comment
# said the opposite in its first draft. `aios_grid.clean_folders` runs first and
# drops `parent` when it equals the folder's own id (`aios_grid.py`, the
# `if parent and parent != fid` line), so a self-nest arriving on the wire is a
# silent no-op here rather than a refusal β the folder simply stays where it is.
# The RAIL refuses it out loud (`folders.ts::mayNestFolder`, *"A folder cannot go
# inside itself."*), which is the path a person can actually take, and the create
# branch above drops the same case the same way. Written down rather than
# "fixed": a second refusal would claim the single toast slot on the path that
# already speaks, and a comment asserting a guard that does not fire is what
# W41-T12's own correction three screens down exists to warn about.
own_here = _own_ids(surface, cur_ws)
nested = (None if item_id in own_here
else next((f for f in lst if f['id'] == item_id), None))
if nested is not None:
if target is None or str(target) == _agf.ROOT_PLACEMENT:
# β BOTH SPELLINGS OF "THE TOP LEVEL" CLEAR THE PARENT. For an ITEM the
# two are different facts (W32-T27: absence means never filed, the
# sentinel means filed at root on purpose) because a shared view reads
# them apart. A FOLDER has no such split β `folderNesting` renders every
# unresolvable parent at the top level β so one behaviour for both is the
# honest answer rather than a distinction nothing downstream can see.
nested.pop('parent', None)
else:
pid_ = str(target).strip()[:80]
if not any(f['id'] == pid_ for f in lst):
return _no('folder_gone',
'That folder is not on this sidebar any more, so the '
'folder you dragged stayed where it was. Reload the page '
'to see the folders you have, then try again.', key=pid_)
nested['parent'] = pid_
# β NO `placed` WRITE, AND NO RETURN EITHER. A folder is not an item and has no
# placement: writing `itemFolders` here would file a folder as though it were a
# view, and `clean_item_folders` would prune it on the very next read for naming
# an id that is not in `_own_ids`. The parent IS the whole record β and `lst`
# holds the row by reference, so the shared tail below (`folders[surface] = lst`,
# then one `clean_folders`) carries it out through the ONE sanitise-and-return
# this function has. A second copy of that tail here would be a second success
# path to keep in step.
elif item_id not in own_here:
# β Worded for the person, not the wall: a view shared WITH someone is in
# their rail and is not theirs to file, which is the case they will meet.
return _no('item_not_yours',
'You can file only the items you own, and this one belongs to '
'somebody else, so it stayed where it was.', key=item_id)
else:
cur = dict(placed.get(surface) or {})
if target is None:
# β "UNFILE" β the client says nothing about where it went. Popping is
# right here and always was: no placement = render at the top level, and
# that is the state a brand-new item is already in.
cur.pop(item_id, None) # back to the root
elif str(target) == _agf.ROOT_PLACEMENT:
# ββ WAVE 32 Β· OWNER ITEM 20 (`W32-T27`, ASK C-16) β "FILED AT ROOT",
# STORED.
#
# β THE THIRD CASE, AND ITS ABSENCE IS THE WHOLE DEFECT. Popping (above)
# and this branch produce the SAME rendering for an ordinary view, which
# is why nobody missed it for nine waves β but they are different FACTS,
# and for a SHARED view the difference is the entire feature: "never
# filed" sends it to the Shared group, "the receiver dragged it out" must
# not. Absence cannot hold two facts, so the second one gets a value.
#
# β AND IT IS DELIBERATELY EXEMPT FROM THE FOLDER-EXISTS TEST BELOW. This
# id names no folder by design; running it through `any(f['id'] == tid
# ...)` would refuse every root filing, which is the same silent no-op
# that ticket exists to remove. `aios_grid.clean_item_folders` carries the
# matching exemption on the READ side β the two are one change (see its
# note).
cur[item_id] = _agf.ROOT_PLACEMENT
else:
tid = str(target)[:80]
if not any(f['id'] == tid for f in lst):
return _no('folder_gone',
'That folder is not on this sidebar any more, so the item '
'stayed where it was. Reload the page to see the folders '
'you have, then try again.', key=tid)
cur[item_id] = tid
placed[surface] = cur
folders[surface] = lst
clean = _agf.clean_folders(folders)
return clean, _agf.clean_item_folders(
placed, clean,
{sfc: _own_ids(sfc, cur_ws) for sfc in _agf.FOLDER_SURFACES})
# Folder gestures mutate the latest owner row inside the write, without a whole-tree stamp.
try:
_receipt = _tops(ctx).save_folders(uname, mutate=_mutate,
actor=uname, origin=EVENT_ORIGIN)
except _tstore.FolderTreeError as _fte:
return _folder_refuse(ctx, kind,
str(getattr(_fte, 'reason', '') or 'folder_tree_illegal'),
str(_fte), key=str(getattr(_fte, 'folder_id', '') or ''))
if _receipt is None:
return _folder_refuse(
ctx, kind,
why.get('code') or 'folder_change_refused',
why.get('message') or ('That folder change could not be saved, so nothing was '
'altered. Reload the page and try again.'),
key=why.get('key') or '')
# ββ THE DURABILITY HALF β the owner's actual complaint. See `_commit_folder_write`: the
# write above lands in `Store._cache` and the hub commit is deferred by up to ~22s, so
# a second process (or the same one after a restart) cannot read it back. Forced here,
# for EVERY folder kind rather than `item_move` alone: they all write one key through one
# `save_folders`, they are all one discrete gesture, and a `folder_create` that evaporated
# would take the move filed into it with it.
_commit_folder_write(_tops(ctx))
# W41-T12's receipt, partitioned. A repair means the stored tree differs from what was
# dragged, which the user has to be told or their sidebar silently disagrees with them.
_notice = _folder_repair_notice((_receipt or {}).get('repairs'))
if _notice:
try:
ctx.out.toast = _notice[:300]
except Exception: # noqa: BLE001
pass
# True: the sidebars render from server state (which folder holds what), not from local
# optimism β the same contract the cohort panel's membership edits ride.
return True
if kind == 'view_reorder':
# β WAVE-27 item 5 (contract C7) β the user drags views up and down the rail.
#
# THE WIRE CARRIES THE FULL ORDER, NEVER A DELTA β the `folder_reorder` contract above,
# verbatim, and for its reason: a partial list cannot say where an unnamed view went.
#
# β NO OWNERSHIP FILTER, and that is the difference from `item_move`. Filing a view into
# a folder writes a placement keyed by a view this user must own; ARRANGING the rail is
# about the reader's own screen, and the rail legitimately contains views this user does
# not own β the system view, cohort projections, R8's injected Overview, and anything
# SHARED with them. Refusing ids they do not own would make exactly those un-draggable,
# which is the half of sharing people notice.
#
# β Unresolvable ids are harmless by construction rather than by filtering here: the READ
# side (`aios_grid.views_from_defs`) ranks by this list and appends anything unranked, so
# an id naming a deleted view simply never matches. Validating against today's view set
# at WRITE time would also drop an id whose view is merely not visible in this request.
raw_order = event.get('order')
if not isinstance(raw_order, list):
return False # a non-list order is malformed, not an empty arrangement
order, seen_v = [], set()
for vid in raw_order[:MAX_VIEW_ORDER]:
vid = str(vid or '').strip()[:120]
if vid and vid not in seen_v:
seen_v.add(vid)
order.append(vid)
# β THE SESSION FALLBACK IS `record_layout`'s, COPIED DELIBERATELY, and it is not just a
# testability convenience. Both keys are per-user PRESENTATION state for one surface, and
# both should keep working while the store is briefly unavailable β a rail that refuses
# to reorder because a write failed is a frozen control with no explanation. It also
# makes the round trip reachable from `verify_grid_events`, which is headless and where
# `store.available()` is False: the store-backed branch of every OTHER stratum writer is
# covered only by the live pass, and this one did not have to be.
if _store_of(ctx).available():
_tops(ctx).save_view_order(uname, order)
else:
_session_ready()
if order:
ws['viewOrder'] = order
else:
ws.pop('viewOrder', None) # absent = server order, never a stored []
# True: the rail renders from server state, like the folder sidebars it sits beside.
return True
if kind == 'field_delete':
# Delete a USER-CREATED column outright (owner gap closed 2026-07-27). The prefix IS
# the permission: only the created strata (`custom_` overlay fields, `measure_` formula
# columns) are deletable β a base field's key fails the prefix test no matter what the
# browser claims, so the table's contract cannot be deleted from the client. The store
# scrubs the field's stored cell values with it (delete_table_field); views naming the
# key self-heal on their next autosave, the rule every stale colId already rides.
key = str(event.get('key') or '')[:80]
import aios_grid as _ag3
# ββ OWNER 2026-08-31 β THE LEGACY ROUTE-ORDER STRATUM JOINS THE DELETABLE ONES.
# Owner: *"Can you also delete all the stale routes and their field ... We don't need
# those. It's legacy I believe."* They are right about what these are: a field with
# `kind == 'route_order'` is the ONLY thing `route_system.legacy_route_plan` projects a
# read-only `compatibility: 'legacy-route-order'` Route from, so the column IS the route
# and deleting one deletes both. There was no door for it at all β the prefix test above
# is on a KEY, and these are named `route_<name>`, so the column could be neither
# deleted nor edited by anybody, on any surface.
#
# β IT IS A KIND TEST, NOT A `route_` PREFIX TEST, and that distinction is the wall. A
# prefix would let a browser delete any base contract column it could name `route_`;
# `kind` is read from the STORED definition below, which the client does not author.
# β The RIGHTS wall underneath is untouched: `may_delete_field` still decides, so this
# widens which stratum is structurally deletable and gives nobody a new right.
_legacy_route = False
if not (key.startswith('custom_') or key.startswith(_ag3.MEASURE_FIELD_PREFIX)):
_probe = field_by_key.get(key)
if not isinstance(_probe, dict):
_probe = (ws.get('fields') or {}).get(key)
_legacy_route = isinstance(_probe, dict) and _probe.get('kind') == 'route_order'
if not _legacy_route:
return False
# ββ W41-T02 / RULING R6a+R6b / CONTRACT C2 β THE RIGHT, ASKED OF THE ONE PAIR THAT OWNS
# IT. Until now this door had NO rights test at all: the prefix above was the whole of
# the wall, so any holder of a grid could delete a column somebody else made and shared
# with them, and an administrator could delete a pre-set the rename door had always
# refused them. C2's last sentence is *"No surface re-implements either test"*, so the
# answer comes from `user_tables.may_delete_field`, which derives it from C1's badges.
#
# β THE PREFIX TEST STAYS, AND IT IS NOT THE SAME WALL. It is STRUCTURAL β it says which
# STRATUM a key could even be deleted from, which is what stops the browser claiming a
# base contract column is deletable. The predicate is the RIGHTS wall over the columns
# that survive it. Replacing one with the other would drop a check in either direction.
#
# β NO `_refuse` HERE, ON PURPOSE. That helper stamps `'event': 'field_upsert'` on every
# record it writes, so reporting from this branch would file a refusal that lies about
# which event it was. The refusal is real and silent for exactly one more ticket: W41-T07
# owns turning this door's `return False` into a truthy result with a message, and this
# line is what gives it a genuine refusal to carry. Until then the wall is proved from
# STORE STATE β the definition is still there after a refused delete β never from a
# refusal record this door cannot yet emit honestly.
# β THE DEFINITION IS RESOLVED IN TWO PLACES, AND THE SECOND IS NOT BELT-AND-BRACES.
# `field_by_key` is `ctx.fields`, bound ONCE per request, and it must be asked FIRST
# because it is the only one carrying the tenant-wide SHARED stratum (merged into the
# served contract by the assembly, never into this user's own bucket). But it is also
# STALE inside a batch: `handle_events` walks a window of events with one ctx, so a
# create and a delete arriving in the same burst would leave the delete looking at a
# field list assembled before the create landed β and the pair fails CLOSED, so the
# column would survive its own delete. `ws` is re-read per event a few lines up, so the
# per-user stratum it holds is current. Neither lookup DECIDES anything; both just hand
# the same one predicate the definition it is owed.
_defn = field_by_key.get(key)
if not isinstance(_defn, dict):
_defn = (ws.get('fields') or {}).get(key)
_share_key, _share_topic = _field_share_keys(ctx)
import core.user_tables as _ut2
if not _ut2.may_delete_field(
_share_key, key, uname, bool(admin),
ctx.st or getattr(ctx.table, 'st', None),
field=_defn, grant_topic=_share_topic):
return False
# W41-T07 / OWNER INSTRUCTION 21 -- DELETE FROM EVERY STRATUM, NOT JUST THIS USER'S.
# Owner: *"Deleting a field from Hide fields does not stick; 'August Campaign' on Odoo
# customer has reappeared three times."* It reappeared because THIS door never deleted
# it: `table_store.delete_field` reaches exactly one member of the workspace document --
# the deleter's own -- while the definition survives in `shared_overlay`'s bucket and in
# every other account's fork, and `migrate_legacy_fields` (which runs on EVERY read)
# promotes one straight back. Measured in-process by the ticket that built the executor:
# drop, one read, the column is back.
#
# W41-T07 BUILT `delete_field_everywhere` and wired it to `routes_tables.py::
# delete_shared_field`, the generic `ut_*` door. THIS door -- the one serving
# `customer_data` and `product_data`, which is the grid the owner named -- was left on the
# single-stratum call, so the fix existed and the defect shipped anyway. A correct
# mechanism on the wrong door is why every gate stayed green. [[two-lanes-one-contract-dead-feature]]
#
# THE RIGHT WAS ALREADY DECIDED ABOVE and is not decided again here: C2's last sentence is
# *"No surface re-implements either test"*, and `may_delete_field` is that test. This is
# the EXECUTION half only, which is exactly what the executor's own docstring says it is.
# The keys are the pair `_field_share_keys` already resolved: `customer_data`'s per-user
# and tenant-wide strata are named from ONE key (`routes_customers::_shared_key` --
# *"the store key this topic's per-user AND tenant-wide strata are both named from"*), so
# workspace and shared are the same argument here, and the grant topic is the second.
if _store_of(ctx).available():
import core.field_permissions as _fp2
_removed = _fp2.delete_field_everywhere(
_share_key, _share_key, _share_topic, key,
st=ctx.st or getattr(ctx.table, 'st', None))
# The per-leg report is kept rather than reduced to a boolean: a delete that reached
# the tenant-wide field stratum but no fork, or the reverse, is a different fact from a clean one.
try:
ctx.out.derived = dict(getattr(ctx.out, 'derived', None) or {},
fieldDeleteRemoved=_removed)
except Exception: # noqa: BLE001
pass
else:
_session_ready()
ws['fields'].pop(key, None)
for _row in ws['overlays'].values():
if isinstance(_row, dict):
_row.pop(key, None)
# Wave-6 item 3: the client dropped the column optimistically; the store scrub is
# invisible to the next render (the values leave WITH the column).
return False
if kind == 'choice_rename':
# β WAVE 20 (owner item 15, contract C-RENAME) β RENAMING AN OPTION CARRIES ITS VALUES.
#
# Owner: *"if I change the option from 'Aaron' to 'Aron' the existing field that has the
# Selected 'Aaron' doesn't change to 'Aron'."* Correct, and it is a data-model fact rather
# than an oversight: a select cell stores the option's LABEL, so renaming the option in
# the field definition orphans every cell holding the old string. They do not render as
# the new name; they render as a value that is no longer an option.
#
# β THE WIRE CARRIES AN EXPLICIT {from, to} MAPPING, NEVER A DIFF OF THE CHOICE LISTS.
# Diffing is what makes this unsafe: rename AβB while also DELETING C and adding D, and a
# differ sees two removals and two additions with no way to know which pairs up. It would
# cheerfully rewrite every C cell to D. The client knows which row of its editor the user
# typed in; that intent travels, and nothing here has to guess it.
#
# THREE PLACES HOLD THE OLD STRING, and missing any one is its own visible bug:
# 1. the CELLS (`overlays`) β the owner's complaint;
# 2. the FIELD's own `choices` list β else the picker still offers the old name;
# 3. every VIEW that FILTERS or COLOURS BY that value β a saved view filtering
# `Agent is "Aaron"` silently matches NOTHING the moment the value moves, which is
# the failure that looks like data loss ([[aios-shared-views]]).
key = str(event.get('key') or '')[:80]
pairs = []
for r in (event.get('renames') or ()):
if not isinstance(r, dict):
continue
a, b = str(r.get('from') or '')[:200], str(r.get('to') or '')[:200]
if a and b and a != b:
pairs.append((a, b))
field = field_by_key.get(key)
if not key or not pairs or not isinstance(field, dict):
return False
if str(field.get('type') or '') not in ('select', 'multiselect', 'status'):
return False
# Only a field this caller may edit. A rename is a write to the field CONTRACT, so it
# rides the same wall `field_upsert` does rather than a looser one of its own.
if key in (ctx.hidden_keys or frozenset()):
return False
mapping = dict(pairs)
def _rename_in(ws_):
fields_ = ws_.setdefault('fields', {})
fld = fields_.get(key)
if isinstance(fld, dict) and isinstance(fld.get('choices'), list):
seen, out = set(), []
for c in fld['choices']:
if isinstance(c, dict):
nm = mapping.get(str(c.get('name') or ''), None)
if nm is not None:
c = {**c, 'name': nm}
ident = str(c.get('name') or '')
else:
c = mapping.get(str(c), str(c))
ident = str(c)
# A rename ONTO an existing option MERGES rather than duplicating it: the
# user typed a name that already exists, and two identical options is a
# picker bug. Their cells merge too, which is what the value rewrite below
# does anyway.
if ident in seen:
continue
seen.add(ident)
out.append(c)
fld['choices'] = out
fields_[key] = fld
for row in (ws_.get('overlays') or {}).values():
if not isinstance(row, dict) or key not in row:
continue
val = row[key]
if isinstance(val, list): # multiselect
merged, out2 = set(), []
for v in val:
nv = mapping.get(str(v), str(v))
if nv not in merged:
merged.add(nv)
out2.append(nv)
row[key] = out2
elif isinstance(val, str) and val in mapping:
row[key] = mapping[val]
# Views: filter rule values + colour-by keys naming the old option.
for view in (ws_.get('views') or {}).values():
if not isinstance(view, dict):
continue
cfg = view.get('config') if isinstance(view.get('config'), dict) else view
def _walk(nodes):
for n in nodes or ():
if not isinstance(n, dict):
continue
if isinstance(n.get('children'), list):
_walk(n['children'])
continue
if str(n.get('colId') or '') != key:
continue
v = n.get('value')
if isinstance(v, str) and v in mapping:
n['value'] = mapping[v]
elif isinstance(v, list):
n['value'] = [mapping.get(str(x), x) for x in v]
_walk(cfg.get('filters') or [])
# β `colorBy` NEEDS NO REWRITE, and the reason is worth stating because the
# opposite looks obvious: it stores a COLUMN KEY (a string, validated against
# `valid_keys` at `view_upsert`), not a {value: colour} map. Per-value colours
# ride the CHOICE OBJECTS themselves, which this function renames in place β
# `{**c, 'name': nm}` keeps every other key on the choice, colour included β so
# a renamed option keeps its swatch for free. An earlier version of this handler
# tried to rewrite `colorBy['rules']` and crashed the whole event pipeline with
# `TypeError: unhashable type: 'dict'` on the FIRST view it touched.
return ws_
if _store_of(ctx).available():
_tops(ctx).rename_choice_values(uname, _rename_in)
else:
_session_ready()
_rename_in(ws)
# True = the host must re-read: the client dropped its optimistic copy of the CHOICES,
# but the rewritten cells and view filters only exist server-side until the next payload.
return True
if kind == 'field_duplicate':
# Wave-5 item 1. The DESTINATION key is client-generated (the established pattern β
# the client must know it synchronously to place the clone right of the source), and
# W48-T17 / R8: a duplicate is ALWAYS a tenant-owned `custom_` definition. Source
# columns may be copied as values, but never as source/identity semantics.
# The duplicator becomes the clone's creator β it is a NEW field they made.
src_key = str(event.get('sourceKey') or '')[:80]
new_key = str(event.get('key') or '')[:80]
import aios_grid as _ag5
if (not new_key.startswith('custom_') or new_key == src_key
or new_key in field_by_key or new_key in (ws.get('fields') or {})):
return False
src = ws.get('fields', {}).get(src_key) or field_by_key.get(src_key)
if not isinstance(src, dict):
return False
# The first served field is the table identity. A field can also declare identity
# explicitly in a stored fixture; either spelling is unavailable by contract. This
# runs before a clone is built or a store transaction starts, so a forged browser event
# cannot mutate the database through the absent client affordance.
identity_key = next((str(f.get('key') or '') for f in fields
if isinstance(f, dict) and f.get('pinned')), '')
if not identity_key and fields and isinstance(fields[0], dict):
identity_key = str(fields[0].get('key') or '')
if src_key == identity_key or bool(src.get('identity')):
return _refuse(ctx, 'identity_field_not_duplicable',
'The unique identity field cannot be duplicated.', src_key,
event='field_duplicate')
clone = dict(src)
clone['key'] = new_key
# A source definition may describe an immutable connector field. The clone is an
# ordinary custom field, so it deliberately sheds those authority claims.
for prop in ('origin', 'valueAuthority', 'valueOverride', 'readOnly', 'shared', 'granted',
'sharedRole', 'superseded', 'identity', 'pinned', 'preset', 'derived'):
clone.pop(prop, None)
clone['source'] = 'overlay'
clone['origin'] = 'user'
clone['valueAuthority'] = 'user-entered'
clone['custom'] = True
clone['default'] = True
label = str(event.get('label') or '').strip()[:120]
requested_label = label or (str(src.get('label') or 'Untitled')[:110] + ' copy')
_workspace_field_keys = set((ws.get('fields') or {}))
_reserved_field_names = [
value.get('label') for candidate_key, value in field_by_key.items()
if (candidate_key != new_key and candidate_key not in _workspace_field_keys
and isinstance(value, dict))
]
clone['label'] = requested_label
clone['createdBy'] = uname
# Wave-6 item 9: the clone inherits the source's scope via dict(src); on the cohort
# page the duplicate surface may explicitly place it instead (same create-time rule
# as field_upsert β a page that is not the cohort page cannot mint a cohort field).
if scope_key == 'cohort' and event.get('scope') in ('cohort', 'global'):
if event['scope'] == 'cohort':
clone['scope'] = 'cohort'
else:
clone.pop('scope', None)
copied_values = {}
if event.get('copyValues') is True and isinstance(event.get('values'), dict):
# The browser can only see its supplied payload, but it remains untrusted. PIDs
# are re-intersected with the host's current scope; only ordinary scalar cells are
# accepted, keeping a field duplication from becoming an arbitrary JSON write door.
for raw_pid, value in event['values'].items():
try:
pid = int(raw_pid)
except (TypeError, ValueError):
continue
if (pid in allowed_pids and not isinstance(value, bool)
and isinstance(value, (str, int, float))):
copied_values[pid] = str(value)[:10000]
if _store_of(ctx).available():
clone = (_tops(ctx).duplicate_field(
uname, src_key, new_key, clone,
reserved_names=_reserved_field_names,
correction_id=event_id,
copied_values=copied_values) or clone)
else:
_session_ready()
_field_names = list(_reserved_field_names)
_field_names.extend(
value.get('label')
for candidate_key, value in ws['fields'].items()
if candidate_key != new_key and isinstance(value, dict)
)
clone.pop('labelCorrectedFrom', None)
clone.pop('labelCorrectionId', None)
clone['label'] = _unique_name(requested_label, _field_names)
if clone['label'] != requested_label and event_id:
clone['labelCorrectedFrom'] = requested_label
clone['labelCorrectionId'] = str(event_id)[:180]
ws['fields'][new_key] = clone
for _pid, _value in copied_values.items():
ws['overlays'].setdefault(str(_pid), {})[new_key] = _value
# A copied snapshot lives host-side. Definition-only formula/created_time clones are
# already complete in the browser; every other source needs its server projection.
label_changed = clone['label'] != requested_label
return bool(copied_values) or label_changed or src.get('type') not in ('formula', 'created_time')
if kind == 'add_to_list':
# "Add to list" (owner item 6): a view's current matches become fixed cohort members.
#
# β `pids` arrives from the BROWSER. It is intersected with `allowed_pids` β the pool this
# user may actually see β before anything is stored. The client computing the set is a
# correctness decision (it is the only engine that already knows the answer, and asking a
# second engine the same question is the drift verify_filter_engine.py exists to prevent);
# it is NOT a trust decision.
raw_pids = event.get('pids')
if not isinstance(raw_pids, list):
return False
pids = [p for p in raw_pids if isinstance(p, int) and p in allowed_pids]
if not pids:
return False
cohort_id = str(event.get('cohortId') or '').strip()[:120]
name = str(event.get('name') or '').strip()[:120]
if not _store_of(ctx).available():
return False
# β WAVE 19 / R9 β THE BUG THIS RULING NAMES. This branch is where a list is BORN, and it
# named `cohort_mod` directly: a list created from the Product surface was written into
# `customer_cohorts` with CRC32 product pids in it, then rendered on the Customer page as
# a list of customers nobody recognised. The set now belongs to the database it was
# created on, and `ctx.scope_key` is the only thing that decides which.
sets = _cohorts(ctx)
try:
if not cohort_id:
if not name:
return False
cohort_id = sets.create(uname, name, pids)
else:
if cohort_id not in sets.all_for(uname):
return False # not this user's cohort β fail closed, do not create
sets.add_members(uname, cohort_id, pids)
except ValueError as e:
_tel.error('cohort:add_to_list', e)
return False
# True: the Cohort page's list and counts must reflect this, and the toast below only
# renders on a fresh run.
#
# β The NOUN is the TOPIC's, not the literal "customer" this line carried since wave 2.
# "Added 12 customers" over a set of SKUs is the surface stating, in words, that the list
# went somewhere it did not β the user-visible half of the same leak.
_noun = sets.noun
ctx.out.toast = (
f"Added {len(pids):,} {_noun}{'' if len(pids) == 1 else 's'} to "
f"{name or 'the list'}.")
return True
if kind == 'overlay_patch':
pid = event.get('pid')
if not isinstance(pid, int) or isinstance(pid, bool):
# Connector write acknowledgements name invalid IDs. Legacy malformed events stay silent.
if str(scope_key or '').startswith('ut_') and ctx.table is not None:
from core import user_tables as _invalid_row_table
if _invalid_row_table.is_connected(scope_key, st=ctx.table.st):
return _refuse(ctx, 'bad_row_id', 'A numeric record ID is required.', event=kind)
return False
if pid not in allowed_pids:
return _folder_refuse(
ctx, kind, 'row_outside_audience',
'This edit was not applied because the record is outside your permitted audience.')
_history_table = str(ctx.scope_key or 'customer')
_connector_cells = False
if _history_table.startswith('ut_') and ctx.table is not None:
import core.user_tables as _ut_history
_history_before = dict((((_ut_history.get(
_history_table, st=ctx.table.st) or {}).get('rows') or {}).get(str(pid)) or {}))
_connector_cells = _ut_history.is_connected(_history_table, st=ctx.table.st)
if _connector_cells:
from core import shared_overlay as _connector_overlay
_history_before.update(_connector_overlay.cells(
_history_table, [pid], st=ctx.table.st).get(str(pid)) or {})
else:
_history_before = dict(((ws.get('overlays') or {}).get(str(pid)) or {}))
updates = {}
refused = False
stage_moved = False
row_events = [] # C3 (wave 22): admitted writes, emitted AFTER they apply
# W43: labels learned from a normal cell edit are persisted with that cell. The actual
# residency transaction belongs to TableStore / shared_overlay below; this map carries
# only NEW canonical labels, after this wall has applied the same permission, case and cap
# rules as every other choice write.
choice_additions = {}
raw_updates = event.get('updates') if isinstance(event.get('updates'), dict) else {}
for key, value in raw_updates.items():
restoring_absence = value is None and ctx.history_kind == 'restore'
if key not in overlay_keys or (
not restoring_absence and not isinstance(value, (str, int, float))):
refused = True
continue
# C-PERM: a field this caller's permissions HIDE cannot be written, only refused.
# `overlay_keys` asks whether the column exists, not whether this person may touch
# it β so without this line a restricted user who knows a hidden key could PATCH a
# value they are not allowed to read back. Refused LOUDLY (repaint) so the client
# reverts rather than showing a value the store never took.
if key in (ctx.hidden_keys or frozenset()):
refused = True
continue
# Wave-5 item 1 plus Share field precedence: the client hiding its editor is
# courtesy, this is the wall. A shared field's registry role overrides the legacy
# permissions bag, so Can view remains read-only inside an editable view.
definition = field_by_key.get(key) or {}
permitted = _may_edit_field_value(ctx, key, definition)
if not permitted:
refused = True
continue
# C5-AUTOFIELD (wave 18): an automation cell is MACHINE-WRITTEN. The client marks
# the type read-only (READONLY_CELL_TYPES) but that is courtesy β this is the wall.
# Without it the UI hides the editor while the API still takes a PATCH, which is
# exactly the shape a "read-only" type must not have.
if (field_by_key.get(key) or {}).get('type') == 'automation':
refused = True
continue
# C2 (wave 22): a STAGE FIELD is engine-written EXCEPT at a review gate, where a
# human may advance a card to a member of the review stage's `next` and nothing
# else. The law rides the field definition (`automation.humanMoves` / `arrive`,
# stamped by the engine that derives the stages) because this module must not
# import the engine β the engine states the law, this door enforces it
# mechanically. An ADMITTED move writes THROUGH to the definition row, the shared
# truth the engine and every viewer read: parked in this user's overlay stratum it
# would be a board position only its author could see. Everything else about the
# field is refused β the same wall the automation-cell type gets, extended, not
# replaced.
if str(ctx.scope_key or '').startswith('ut_'):
import core.user_tables as _ut_mod
_tdef = _ut_mod.get(ctx.scope_key, st=ctx.table.st) if ctx.table is not None \
else None
_fdef = next((f for f in ((_tdef or {}).get('fields') or [])
if f.get('key') == key), None)
# C7 (wave 22): a METRIC cell is engine-computed from the master series β a
# human write would be an invented measurement, refused the way an automation
# cell is (the wall, not the courtesy).
# β 2026-08-07 β EXTENDED TO THE RELATIONAL PAIR, and read through the field
# layer's own predicate rather than re-tested here. A `rollup` cell is an
# aggregate the server computes; a DERIVED `link` cell is a join the server
# resolves. Both would be overwritten by the next refresh anyway, so accepting
# the write would not merely be wrong β it would look like it worked and then
# silently revert, which is worse than a refusal.
# β An ORDINARY (user-picked) link is deliberately NOT refused: `is_computed_cell`
# answers per FIELD, not per type, because one kind is read-only in one mode and
# editable in the other.
if _ut_mod.is_computed_cell(_fdef):
refused = True
continue
_auto = (_fdef or {}).get('automation')
# An ordinary Link is a shared database relationship. Validate its selected
# target ids and write it through to the definition row; a personal overlay
# would be invisible to reciprocal links and Rollups.
if (_fdef or {}).get('type') == 'link':
_linked = _ut_mod.patch_link_cell(
ctx.scope_key, pid, key, value, st=ctx.table.st,
by=ctx.by if ctx.by is not None else uname, via=ctx.via)
if _linked is None:
refused = True
continue
if _linked != str(value):
refused = True
row_events.append((key, _linked))
continue
# β WAVE 25 (C3 + amendment C3-A1, owner rulings R7/R6) β THE PROFILE CELL.
# Two things happen here and neither can live anywhere else:
#
# 1. IT WRITES THROUGH TO THE DEFINITION ROW, the stage field's mechanism two
# branches up, for the identical reason. MEASURED before it was written: an
# ordinary `ut_*` cell edit lands in the TYPIST'S OWN overlay stratum, and
# the automation engine reads `t['rows']` β so a handle somebody typed
# would be invisible to the enrich action and to every other viewer of the
# same database. The flag would be decorative.
# 2. BLANKING IT CLEARS THAT ROW'S PRESET CELLS IN THE SAME WRITE (R6) β
# `patch_profile_cell` does both inside ONE store update, because a blank
# that commits without its clear leaves a row with no handle and a live
# follower count, i.e. stale numbers attributed to nobody.
#
# β NOT VIA THE EMIT GUARD (HARD RULE 5 / D-40). Nothing here emits; this is
# `user_tables`' own write door, reached from the branch that already knows the
# scope is `ut_`. β `editRole` is deliberately NOT consulted: it governs the
# SCHEMA, and C3 is explicit that a profile field's VALUES stay fully editable β
# that is the whole point of item 5a.
if isinstance((_fdef or {}).get('profile'), dict):
_pw = _ut_mod.patch_profile_cell(
ctx.scope_key, pid, key, value, st=ctx.table.st,
by=ctx.by if ctx.by is not None else uname, via=ctx.via)
if _pw is None:
# Not a handle we can enrich. Refused LOUDLY so the client repaints to
# the stored truth instead of showing a value the store never took.
refused = True
continue
# A normalisation (`@Name` -> `name`, a pasted URL -> its handle) is a real
# difference from what the client is drawing, so it must repaint. An
# untouched value echoes and stays on the no-blip path.
if _pw['handle'] != str(value):
refused = True
if _pw['cleared']:
stage_moved = True # cells the client never typed changed: re-read
row_events.append((key, _pw['handle']))
continue
# β OWNER ITEM 4 (2026-08-06) β A COLUMN AN AUTOMATION FILLS IS NOT A COLUMN A
# PERSON TYPES IN. Owner, verbatim: *"I should not be able to edit any of the
# Pre-set fields on instagram automation, we talked about this extensively."*
#
# β IT HAD NEVER BEEN ENFORCED ANYWHERE. `editRole: 'admins'` rides on every
# preset column and reads exactly like this wall, which is why it was believed to
# be one β but it governs the SCHEMA (`user_tables.py:535`): who may rename or
# retype the column. The VALUES stayed open to anyone with grid access, and the
# owner typed into one to prove it. The metric branch above is the same rule for
# the same reason, written for a different column kind; this is its sibling.
#
# β REACHED ONLY AFTER stage AND profile have `continue`d, and the order is the
# rule rather than an accident: both of those columns carry the identical tag and
# both are cells a human is SUPPOSED to drive β the stage because moving a card
# IS the decision, the profile because it is where enrichment gets its subject.
# Refusing on the tag alone would freeze every kanban.
#
# `flowId` and not merely `automation`: a user-configured `automation` COLUMN
# carries its own gear bag (kind/source/urlField/settings) and no flowId, and it
# is not this ruling's subject.
if isinstance(_auto, dict) and (_auto.get('flowId') or _auto.get('preset')):
refused = True
continue
# A restore of an event whose before-value was absent removes the cell. It reaches
# this branch only after the same hidden, edit-role, automation and computed-field
# checks as an ordinary edit. A browser-authored null remains refused above.
if restoring_absence:
updates[key] = None
continue
# β WAVE 23 (C7) β the json wall, BEFORE the generic 10 000-char truncation, which
# would otherwise cut a document in half and store the halves as valid text. A json
# column promises its readers a parseable document; a write that is not one is
# REFUSED with the cell unchanged rather than silently kept as a string nothing can
# open. Blank stays legal β an empty cell is "no document", not a malformed one.
if (field_by_key.get(key) or {}).get('type') == 'json':
raw_j = value if isinstance(value, str) else _json_ev.dumps(value)
if not str(raw_j).strip():
updates[key] = ''
continue
if len(str(raw_j)) > _ut_limits.MAX_JSON_CELL:
refused = True
continue
try:
_json_ev.loads(raw_j)
except (ValueError, TypeError):
refused = True
continue
updates[key] = str(raw_j)
continue
clean = str(value)[:10000]
if isinstance(value, str) and clean != value:
# Truncated: the stored truth is shorter than the client's copy. (An
# int/float arriving as its string form renders identically β not a refusal.)
refused = True
definition = field_by_key.get(key) or {}
if definition.get('type') in ('select', 'multiselect') and clean:
# A choice value is DATA, not a precondition the field editor must have visited.
# Pasted/imported/API values therefore mint an option through this same write
# door. It is deliberately still bounded and case-canonical: "ET" then "et"
# is one option, and the 201st distinct label is refused rather than creating a
# picker the contract cannot represent.
import aios_grid as _ag_choices
options = _ag_choices.merge_choice_options(definition.get('options'))
canonical = {v.strip().casefold(): v for v in options}
raw_parts = ([clean] if definition.get('type') == 'select'
else clean.split(','))
normalized_parts = []
additions = []
seen = set()
invalid = False
for part in raw_parts:
candidate = _ag_choices._clean_options([part])
if len(candidate) != 1:
invalid = True
break
label = candidate[0]
folded = label.casefold()
match = canonical.get(folded)
if match is None:
if len(options) >= _ag_choices.MAX_FIELD_OPTIONS:
invalid = True
break
match = label
options.append(match)
canonical[folded] = match
additions.append(match)
if folded not in seen:
seen.add(folded)
normalized_parts.append(match)
if invalid:
refused = True
continue
normalized = (normalized_parts[0] if definition.get('type') == 'select'
else ','.join(normalized_parts))
if normalized != clean:
refused = True
clean = normalized
if additions:
choice_additions[key] = additions
updates[key] = clean
if updates:
if _connector_cells:
# Source refreshes own source rows. Authored cells use the same overlay as REST.
try:
if choice_additions:
updates = _connector_overlay.put_cells_and_choice_options(
_history_table, pid, updates, choice_additions, st=ctx.table.st)
else:
updates = _connector_overlay.put_cells(
_history_table, pid, updates, st=ctx.table.st)
except ValueError as exc:
# S76-T33: a registry Link condition refusal keeps its code and reason.
return _folder_refuse(ctx, kind, getattr(exc, 'code', None) or 'bad_value',
str(exc) or 'The edit was refused.', key=','.join(updates))
elif str(ctx.scope_key or '').startswith('ut_') and ctx.table is not None:
# User-table cells are collaborative record data. Views/layout remain personal,
# but record values live in the definition rows so Links, Rollups, automations,
# and every viewer observe one truth.
import core.user_tables as _ut_values
try:
_cells_taken = _ut_values.patch_cells(
ctx.scope_key, pid, updates, st=ctx.table.st,
by=ctx.by if ctx.by is not None else uname, via=ctx.via)
except ValueError as exc:
# S76-T29/T33: a core value rule (number policy, Link condition) names its reason.
return _folder_refuse(ctx, kind, getattr(exc, 'code', None) or 'number_value_refused',
str(exc) or 'The edit was refused.', key=','.join(updates))
if not _cells_taken:
updates = {}
refused = True
elif _store_of(ctx).available():
_tops(ctx).patch_overlay_with_choice_options(
uname, pid, updates, choice_additions)
else:
_session_ready()
ws['overlays'].setdefault(str(pid), {}).update(updates)
if choice_additions:
import aios_grid as _ag_choices
for _key, _values in choice_additions.items():
_prior = ws['fields'].get(_key)
_entry = dict(_prior) if isinstance(_prior, dict) else {}
_entry['options'] = _ag_choices.merge_choice_options(
_entry.get('options'), _values)
ws['fields'][_key] = _entry
# Keep this long-lived event context in sync too. The following event may be a
# paste/API retry before the next field projection is fetched, and it must retain
# the original option's casing rather than treating it as another new choice.
if choice_additions:
import aios_grid as _ag_choices
for _key, _values in choice_additions.items():
_definition = field_by_key.get(_key)
if _definition is not None:
_definition['options'] = _ag_choices.merge_choice_options(
_definition.get('options'), _values)
if updates or row_events:
import core.user_tables as _ut_history
if _history_table.startswith('ut_') and ctx.table is not None:
_history_after = dict((((_ut_history.get(
_history_table, st=ctx.table.st) or {}).get('rows') or {}).get(str(pid)) or {}))
_history_st = ctx.table.st
if _connector_cells:
_history_after.update(_connector_overlay.cells(
_history_table, [pid], st=ctx.table.st).get(str(pid)) or {})
actor = ctx.by if ctx.by is not None else uname
append = _ut_history._activity_writer(_history_st, actor)
changes = {key: {'before': _history_before.get(key),
'after': _history_after.get(key)}
for key in updates
if _history_before.get(key) != _history_after.get(key)}
if append is not None and changes:
_ut_history._emit_activity(
append, _history_st, kind='record',
object={'database': _history_table, 'id': str(pid)},
by=actor, via=ctx.via, changes=changes)
else:
_history_after = dict(_history_before)
_history_after.update(updates)
_history_after.update(dict(row_events))
_history_st = ctx.st
if ctx.table is not None and (_history_table.startswith('ut_')
or _history_table in ('customer', 'product')):
# One receipt carries every committed field delta, even when legacy hooks fan out.
changes = {key: {'before': _history_before.get(key),
'after': _history_after.get(key)}
for key in set(updates) | {key for key, _value in row_events}
if _history_before.get(key) != _history_after.get(key)}
for _k, _v in list(updates.items()) + row_events:
_ut_history.emit_row_event({
'type': 'event_field', 'table': _history_table, 'rowId': str(pid),
'field': _k, 'after': _v, 'st': ctx.table.st, 'user': uname,
'receiptId': event_id, 'changes': changes})
if _history_table in ('customer', 'product') and getattr(_history_st, 'key', None):
from core import received_changes
changes = {key: {'before': _history_before.get(key), 'after': _history_after.get(key)}
for key in set(updates) | {key for key, _value in row_events}
if _history_before.get(key) != _history_after.get(key)}
received_changes.publish(
_history_st, source='typed', database=_history_table + '_data',
row_id=str(pid), changes=changes, receipt_id=event_id, actor=uname)
_ut_history.append_value_history(
_history_table, pid, _history_before, _history_after,
ctx.by if ctx.by is not None else uname, st=_history_st,
kind=ctx.history_kind)
# Wave-6 item 3: the client's cell already shows the typed value β rerun ONLY when
# some of what it shows was refused or clamped and must be repainted to the truth.
# A stage move reruns too: its `arrive` side-effects (the tracked flag) changed cells
# the client never typed.
if refused:
_refuse(ctx, 'cell_write_refused',
'One or more cell values were invalid or read-only. The saved values are returned.',
event=kind)
accepted = dict(updates)
accepted.update(dict(row_events))
canonical = {key: accepted.get(key, _history_before.get(key, ''))
for key in raw_updates if key in field_by_key
and key not in (ctx.hidden_keys or frozenset())}
ctx.out.writes[event_id] = {
'ok': not refused, 'value': canonical, 'refused': refused,
'reason': 'cell_write_refused' if refused else ''}
return refused or stage_moved
return False
"""core/grid_events.py β THE WRITE SEAM, lifted out of Streamlit (EXIT-1a, X1, 2026-07-30).
This is the grid's event handler: the code that takes an UNTRUSTED event object from the
browser component and decides what may be persisted. It was `app.py:_cl_handle_grid_event` /
`_cl_handle_one` and moved here as a PURE MOVE β no behavior change inside a move (MA principle
5). Every body below is the app.py body verbatim; the ONLY mechanical rewrites are the
Streamlit couplings the contract names:
st.session_state['_cl_grid_seen_ids'] -> ctx.seen_ids (adapter-owned dedup state)
st.session_state['_cl_doc_payload'] -> ctx.out.doc (EventResult.doc)
st.session_state['_cohort_toast'] -> ctx.out.toast (EventResult.toast)
st.session_state['cl_table_workspace'] -> ctx.fallback_ws (store-unavailable fallback)
is_admin() (the bare call inside doc_delete, and _cl_table_workspace's admin=None default)
-> ctx.admin
There is NO `import streamlit` in this file and there must never be one β `verify_no_streamlit.py`
enforces that with a `sys.meta_path` block, which is the only proof that survives refactoring.
(That gate was `verify_seam.py` until EXIT-6 retired it with `app.py`; the block, its negative
control and the AST walk moved over intact.)
ONE ADAPTER, ONE HANDLER β it was TWO until 2026-08-04:
* β the Streamlit adapter is GONE. `app.py::_cl_handle_grid_event` built an EventCtx whose
`seen_ids` and `fallback_ws` were session-state-backed dicts and applied the Result to session
state. EXIT-6 deleted it. The host-neutrality this file was written for is what let that
happen without touching a line of the handler β which is the argument for the design, recorded
at the moment it paid out.
* the HTTP adapter β `aios-web/api` builds an EventCtx with `fallback_ws=None`. A None
fallback with the store unavailable is a **503**, never a silent in-memory workspace: an
API request has no durable session dict to fall back to, so pretending to persist would
lose the write with a 200 on it.
β LAYERING, stated honestly. `core/` is not supposed to import `modules/` (ARCHITECTURE Β§1's
one-directional rule). This handler genuinely straddles: it is the WRITE half of the customer
table and its persistence verbs live in `modules.customer_data` / `modules.cohort`. The
contracted path for the strangler is `core/grid_events.py` (both adapters import it from here),
so the import stays and the violation is RECORDED rather than hidden. It is the one file in
`core/` that points up; when EXIT-5 ports the surfaces, the persistence verbs are what move
down, and this note is the marker for that work.
"""
import datetime as dt
import json as _json_ev # wave 23 (C7): the json field's parse wall
import re
from dataclasses import dataclass, field
from contextlib import contextmanager, nullcontext
from functools import wraps
# β ALIASED ON PURPOSE. `field` is imported above for the dataclasses that need it, and this file
# uses `field` as a LOCAL VARIABLE in a dozen handlers (`field = {'key': key, β¦}`). A
# `field(default_factory=list)` written inside one of those functions would resolve to the local
# dict and raise. The alias is unshadowable, so D-291's channel cannot be broken by a rename.
from dataclasses import field as dataclass_field
from typing import Callable, List, MutableMapping, Optional
import core.store as store
import core.table_store as _tstore # wave-9 I17: the shared-view authorisation predicates
#: β WAVE-27 item 5 (C7) β how many view ids one rail arrangement may name. Generous on purpose:
#: it bounds a hostile payload, not the user (the rail holds saved views + cohort projections +
#: shared views, and a busy Customer grid already carries dozens). An order longer than this is
#: not a person dragging rows.
MAX_VIEW_ORDER = 500
import core.user_tables as _ut_limits # wave 23 (C7): MAX_JSON_CELL β one ceiling, one definer
import harness.telemetry as _tel # _tel.error() = THE error sink (all caught errors log)
import modules.cohort as cohort_mod
#: C5 (owner item 12): customer documents. The cap is enforced HOST-side on the DECODED byte
#: count β the client checks the same number first, but a client check only spares the user a
#: pointless upload; this is what bounds what the tenant's dataset can be made to hold.
#: MOVED from app.py:1410β1412 with the handler (app.py re-imports these during the strangler).
_DOCS_KEY = 'customer_docs'
_DOC_MAX_BYTES = 5 * 1024 * 1024
_DOC_MAX_PER_ROW = 50
#: The props of a field def the CLIENT actually draws β the wave-6 no-blip comparison set.
#: Host-only stamps (createdBy, permissions) are deliberately absent: the client renders
#: nothing from its own copy of those, and a permissions refusal is answered explicitly.
_FIELD_ECHO_PROPS = ('label', 'type', 'note', 'options', 'colorCodeOptions',
'optionColors', 'max', 'formula', 'agg', 'scope', 'format', 'measure',
# W50-T05 / R4: how a numeric column READS (value / share / both). A key
# absent from this tuple is not refused, it is silently dropped from the
# echo while the route still answers 200 - so the reader sees the change
# land and then lose it. `showAs` is a DISPLAY mode, never an aggregate.
'showAs',
'recurrence', 'if',
# S76-T28: '' , 0 and false are real defaults, so this key compares by type.
'defaultValue')
#: What a source column's stored override may hold; its read-back takes these from the store only.
_SOURCE_OVERRIDE_KEYS = ('note', 'format', 'agg', 'measure', 'options', 'recurrence')
def _source_echo(accepted, durable):
"""A source column's durable definition: the contract's keys from `accepted`, overrides from the store.
A summary or a format may sit in the tenant-wide stratum alone, with no per-user row.
"""
if not isinstance(durable, dict):
return durable
return {**{k: v for k, v in accepted.items() if k not in _SOURCE_OVERRIDE_KEYS}, **durable}