"""Canonical permissions and migration for user-created field definitions. Field definitions used to carry ``everyone|creator|admins`` while their definitions and values remained in one user's workspace. That combination made "Everyone" a visual promise that could never be true. This module is the single normalization point for the new model: personal, collaborative, or specific users. """ import copy import time import core.shared_overlay as shared_overlay import core.shares as shares from functools import wraps import inspect def _workspace_rows(st, key): from core.store_pg import _view_settings_backend return _view_settings_backend(st, key) def _settings_transaction(fn): """Enlist field definitions, values and grants in the same tenant transaction.""" signature = inspect.signature(fn) @wraps(fn) def call(*args, **kwargs): bound = signature.bind(*args, **kwargs) st = bound.arguments.get('st') key = bound.arguments.get('workspace_key', bound.arguments.get('table_key')) if st is None or (fn.__name__ == 'migrate_legacy_fields' and not bound.arguments.get('allow_write', False)): return fn(*args, **kwargs) rows = _workspace_rows(st, key) if rows is None: return fn(*args, **kwargs) from core import store_pg with store_pg._pool().connection() as con: with con.transaction(): with store_pg._caller_transaction(con, rows.tenant_slug): rows._head(con, lock=True) return fn(*args, **kwargs) return call def _workspace_read(st, key, *, owners=None, drop=()): rows = _workspace_rows(st, key) if rows is None: reader = getattr(st, 'get_projection', None) return reader(key, drop=drop) if drop and callable(reader) else st.get(key) from core.store_pg import _view_projection return _view_projection(rows, owners=owners, drop=drop) def _workspace_update(st, key, fn, *, owners=None): rows = _workspace_rows(st, key) if rows is None: return st.update(key, fn, flush='sync') from core import store_pg, view_settings_rows with store_pg._pool().connection() as con: with con.transaction(): with store_pg._caller_transaction(con, rows.tenant_slug): rows._head(con, lock=True) if owners is None: owners = [row[0] for row in con.execute(view_settings_rows._sql( "SELECT row_key FROM {rows} WHERE workspace_key=%s AND kind='settings'", rows.tenant_slug), (rows.name,)).fetchall()] owners = list(set(owners) | {WORKSPACE_SHARED_MEMBER}) return rows.update(fn, owners=owners) FIELD_EDIT_MODES = ("personal", "collaborative", "users") MAX_FIELD_USERS = 50 _ALIASES = {"everyone": "collaborative", "creator": "personal", "admins": "personal"} #: ⭐⭐ W41-T01 / RULING R5 / CONTRACT C1 — THE THREE BADGES' VOCABULARIES, DECLARED ONCE. #: R5: *"A field is classified by THREE badges, and every right derives from them: Origin #: (`Pre-set` = the platform made it / blank = a person made it) x Audience (`Private` / #: `Shared by ` / `Everyone`) x Values (`Shared values` = one value everyone sees / blank = #: yours alone)."* A consumer greps ONE place for the spellings; nothing derives a badge #: independently. FIELD_ORIGINS = ("preset", "user") FIELD_AUDIENCES = ("private", "users", "everyone") FIELD_VALUE_STRATA = ("shared", "personal") #: SDLC63 C8 — the View-to-field edges live beside the View grants, in the SAME tenant-scoped #: document, but outside ``shares.KINDS``. A boundary names fields once; it never copies the #: View's current people into N field grant records. Consequently a later audience edit takes #: effect on the next permission read and removing one View cannot erase a direct or second-View #: path. ``core.shares`` deliberately remains the direct-grant registry; callers that need to #: explain provenance can therefore distinguish its record from this derived edge. VIEW_FIELD_BOUNDARIES_KEY = "view_field_boundaries" VIEW_FIELD_AUDIT_CAP = 200 VIEW_SHARE_DIAGNOSTICS_KEY = "view_share_diagnostics" VIEW_SHARE_DIAGNOSTIC_CAP = 30 VIEW_SHARE_DIAGNOSTIC_FIELDS_CAP = 500 #: ⭐⭐ W42-T47 / RULING R15 / CONTRACT C10 — WHICH STRATUM A DEFINITION WAS READ FROM. #: #: C10: *"`field_classes` reports, beside `{origin, audience, sharedBy, values, owner}`, WHICH #: STRATUM the definition was read from, so the client sections on ownership without re-deriving #: it."* The three are the three places a field definition can physically live in this codebase: #: #: * ``contract`` — the canonical contract file (`aios_grid_fields.json`) or a module's declared #: columns. Nobody made it here; it is the same document for every account. #: * ``shared`` — `shared_overlay`'s tenant-wide bucket (`_table_workspace__shared`), #: which is where `mint_field` and `promote_field` put a definition. ONE document, read by #: every account. #: * ``personal`` — the reader's OWN member of the `_table_workspace` document. A #: per-user definition: no other account ever receives it. #: #: ⛔ IT IS NOT `FIELD_VALUE_STRATA` WEARING A SECOND HAT, AND THE TWO MUST NOT BE COMPARED. That #: tuple says where a column's VALUES live; this one says where its DEFINITION was read from. A #: column can be `stratum='personal'` with `values='shared'` — that pair is R15's report, not R15's #: bug (see `field_stratum`). FIELD_DEFINITION_STRATA = ("contract", "shared", "personal") #: `permissions_from_grants`' edit vocabulary -> C1's audience vocabulary. The two answer the SAME #: question in different words (who can reach this column), so this map is the whole of the #: translation and there is no second derivation to drift from it #: ([[one-evaluator-per-question]]). ⛔ It is a MAP rather than a branch on purpose: a mode this #: dict does not name falls to `private`, which is the fail-closed direction. _AUDIENCE_FROM_EDIT = {"collaborative": "everyone", "users": "users", "personal": "private"} def _uname(value): """One spelling of a username, everywhere in this module.""" return str(value or "").strip().lower() def clean_permissions(raw, fallback="personal", known_users=None): """Return a small, canonical field permission bag or ``None`` for malformed input.""" if fallback not in FIELD_EDIT_MODES: fallback = "personal" if not isinstance(raw, dict): return {"edit": fallback} edit = _ALIASES.get(str(raw.get("edit") or "").strip().lower(), str(raw.get("edit") or "").strip().lower()) if edit not in FIELD_EDIT_MODES: edit = fallback if edit != "users": return {"edit": edit} allowed = None if known_users is None else {str(u).strip().lower() for u in known_users if str(u).strip()} result = [] seen = set() for value in (raw.get("users") if isinstance(raw.get("users"), list) else [])[:MAX_FIELD_USERS]: user = str(value or "").strip().lower() if not user or user in seen or (allowed is not None and user not in allowed): continue seen.add(user) result.append(user) return {"edit": "users", "users": result} if result else {"edit": "personal"} def stored_permissions(field, fallback="collaborative", known_users=None): """Read a stored field without retroactively making old fields private.""" if not isinstance(field, dict): return {"edit": fallback} return clean_permissions(field.get("permissions"), fallback=fallback, known_users=known_users) def grant_entries(permissions): """Translate the field model into the registry's explicit edit grants.""" mode = (permissions or {}).get("edit") if mode == "collaborative": return [{"user": shares.EVERYONE, "role": "edit"}] if mode == "users": return [{"user": user, "role": "edit"} for user in (permissions.get("users") or [])] return [] # ---------------------------------------------------------- SDLC63 / C8: View audience inheritance def view_field_keys(view): """Fields deliberately used by one View, in stable encounter order. ``config.order`` is intentionally absent. Both the browser reconciler and the server save door append every database field to that list, including columns the author never selected; treating it as an inclusion list is the old over-share. Visible columns and fields used by a View rule/display are deliberate. Hiding a plain column therefore removes that inherited path, while a hidden filter/group/sort input stays readable because the View still depends on it. """ if not isinstance(view, dict): return [] cfg = view.get("config") if isinstance(view.get("config"), dict) else view keys, seen = [], set() def add(raw): key = str(raw or "").strip() if key and key not in seen: seen.add(key) keys.append(key) def walk_filter(node): if isinstance(node, list): for child in node: walk_filter(child) return if not isinstance(node, dict): return walk_filter(node.get("children")) add(node.get("colId")) rhs = node.get("rhs") if isinstance(rhs, dict) and rhs.get("kind") != "stat": add(rhs.get("colId")) for key in cfg.get("visible") or (): add(key) walk_filter(cfg.get("filters")) add(cfg.get("groupBy")) colour = cfg.get("colorBy") add(colour.get("colId") if isinstance(colour, dict) else colour) sorts = cfg.get("sorts") if isinstance(sorts, dict): sorts = [sorts] for spec in sorts or (): if isinstance(spec, dict): add(spec.get("colId")) for key in (cfg.get("summary") or {}) if isinstance(cfg.get("summary"), dict) else (): add(key) display = cfg.get("display") if isinstance(display, dict): for name, value in display.items(): if str(name).endswith("Field"): add(value) for chart in display.get("charts") or (): if isinstance(chart, dict): add(chart.get("x")) add(chart.get("y")) for metric in display.get("calendarMetrics") or (): if isinstance(metric, dict): add(metric.get("field")) for key in display.get("fields") or (): add(key) return keys def _st_for_boundaries(st=None): """Use the same tenant handle ``core.shares`` uses without reaching into a second store.""" return st if st is not None else shares._st(None) def sync_view_field_boundary(view, grant_topic, actor, st=None, *, audit_additions=True, force=False): """Persist one View's current field edge and return its delta. The audience snapshot used by an addition audit is read inside the same ``object_shares`` update as the boundary change. It is evidence only; permission resolution always reads the live View grant, so the snapshot can never become an access list. """ view_id = str((view or {}).get("id") or "").strip() topic = str(grant_topic or "").strip() who = _uname(actor) if not view_id or not topic: return {"added": [], "removed": [], "audience": [], "owner": None} wanted = view_field_keys(view) result = {"added": [], "removed": [], "audience": [], "owner": None} handle = _st_for_boundaries(st) # A private View needs no second write on every filter/resize autosave. Its first share calls # this helper with ``force=True`` after the View grant lands; from then on the existing edge # makes field additions/removals write-bearing. This keeps C8 off the ordinary private-view # hot path without opening a share-before-boundary race. try: current = handle.get(shares.SHARES_KEY) or {} except Exception: # noqa: BLE001 current = {} current_boundaries = current.get(VIEW_FIELD_BOUNDARIES_KEY) or {} current_grant = (current.get("view") or {}).get(view_id) current_grant = current_grant if isinstance(current_grant, dict) else {} current_audience = shares._clean_entries(current_grant.get("entries")) current_owner = _uname(current_grant.get("owner")) or None prior = (current_boundaries.get(view_id) if isinstance(current_boundaries, dict) else None) if not force and not isinstance(prior, dict) and not current_audience: return {"added": [], "removed": [], "audience": [], "owner": current_owner} if isinstance(prior, dict): before = [str(key) for key in (prior.get("fields") or ()) if str(key)] if prior.get("topic") == topic and before == wanted: return {"added": [], "removed": [], "audience": current_audience, "owner": current_owner} def _apply(data): data = data if isinstance(data, dict) else {} boundaries = dict(data.get(VIEW_FIELD_BOUNDARIES_KEY) or {}) prior = boundaries.get(view_id) if isinstance(boundaries.get(view_id), dict) else {} before = [str(key) for key in (prior.get("fields") or ()) if str(key)] before_set, wanted_set = set(before), set(wanted) added = [key for key in wanted if key not in before_set] removed = [key for key in before if key not in wanted_set] grant = (data.get("view") or {}).get(view_id) grant = grant if isinstance(grant, dict) else {} audience = shares._clean_entries(grant.get("entries")) owner = _uname(grant.get("owner")) or None audit = [row for row in (prior.get("audit") or ()) if isinstance(row, dict)] if audit_additions and audience: stamp = time.time() snapshot = [{"user": row["user"], "role": row["role"]} for row in audience] for key in added: audit.append({"ts": stamp, "actor": who or None, "field": key, "view": view_id, "audience": snapshot}) boundaries[view_id] = { "topic": topic, "fields": wanted, "updatedBy": who or None, "audit": audit[-VIEW_FIELD_AUDIT_CAP:], } data[VIEW_FIELD_BOUNDARIES_KEY] = boundaries result.update({"added": added, "removed": removed, "audience": audience, "owner": owner}) return data handle.update(shares.SHARES_KEY, _apply, flush="async") return result def set_view_grants_with_boundary(view, grant_topic, entries, *, owner, granter, expect, st=None, _fail_after_prepare=False): """Replace one View audience and its field edge in one store transaction. The mutation is built on a detached copy. If comparison, normalization, a test-injected mid-operation fault, or persistence fails, neither the audience nor its derived boundary is visible. The callback writes one bounded View record plus one bounded list of field keys; its store-call count is therefore constant for a View with one field or five hundred. ``_fail_after_prepare`` is an internal verifier seam. It raises after both changes have been prepared but before the detached document is returned, proving rollback at the only point a half-applied mutation could otherwise escape. """ view_id = str((view or {}).get("id") or "").strip() topic = str(grant_topic or "").strip() if not view_id or not topic: raise ValueError("a View share must name its View and database") clean = shares._clean_entries(entries) wanted = view_field_keys(view) owner_l = _uname(owner) or None granter_l = _uname(granter) or None expected = ([(row["user"], row["role"]) for row in shares._clean_entries(expect)] if expect is not None else None) answer = {} def _apply(raw): data = copy.deepcopy(raw) if isinstance(raw, dict) else {} views = dict(data.get("view") or {}) prior = views.get(view_id) if isinstance(views.get(view_id), dict) else {} prior_entries = shares._clean_entries(prior.get("entries")) if expected is not None: current = [(row["user"], row["role"]) for row in prior_entries] if current != expected: raise shares.GrantsChanged( "this item was shared with somebody else while you were editing, so nothing " "was saved. Reopen the sharing panel to see who has access now, then make " "your change again.") prior_by = {row["user"]: row.get("by") for row in prior_entries} stamped = [] for row in clean: saved = {"user": row["user"], "role": row["role"]} by = prior_by[row["user"]] if row["user"] in prior_by else granter_l if by: saved["by"] = by stamped.append(saved) keep_owner = owner_l or _uname(prior.get("owner")) or None if not stamped and not keep_owner: views.pop(view_id, None) else: views[view_id] = {"owner": keep_owner, "entries": stamped} boundaries = dict(data.get(VIEW_FIELD_BOUNDARIES_KEY) or {}) old_boundary = (boundaries.get(view_id) if isinstance(boundaries.get(view_id), dict) else {}) boundaries[view_id] = { "topic": topic, "fields": list(wanted), "updatedBy": granter_l, "audit": [dict(row) for row in (old_boundary.get("audit") or ()) if isinstance(row, dict)][-VIEW_FIELD_AUDIT_CAP:], } data["view"] = views data[VIEW_FIELD_BOUNDARIES_KEY] = boundaries if _fail_after_prepare: raise RuntimeError("forced View-share transaction failure") answer.update({"owner": keep_owner, "entries": stamped, "fieldCount": len(wanted)}) return data _st_for_boundaries(st).update(shares.SHARES_KEY, _apply, flush="sync") return dict(answer) def record_view_share_diagnostic(reference, view_id, actor, stage, fields, cause, st=None): """Retain bounded server-only failure detail under a short support reference.""" ref = str(reference or "").strip().upper()[:40] if not ref: return False clean_fields = [] seen = set() for raw in fields or (): key = str(raw or "").strip()[:160] if key and key not in seen: seen.add(key) clean_fields.append(key) if len(clean_fields) >= VIEW_SHARE_DIAGNOSTIC_FIELDS_CAP: break def _apply(raw): data = copy.deepcopy(raw) if isinstance(raw, dict) else {} rows = [dict(row) for row in (data.get(VIEW_SHARE_DIAGNOSTICS_KEY) or ()) if isinstance(row, dict)] rows.append({ "reference": ref, "ts": time.time(), "view": str(view_id or "").strip()[:160], "actor": _uname(actor) or None, "stage": str(stage or "transaction").strip()[:80], "fields": clean_fields, "cause": (f"{cause.__class__.__name__}: {cause}".strip()[:500] if isinstance(cause, BaseException) else str(cause or "view share failed").strip()[:500]), }) data[VIEW_SHARE_DIAGNOSTICS_KEY] = rows[-VIEW_SHARE_DIAGNOSTIC_CAP:] return data _st_for_boundaries(st).update(shares.SHARES_KEY, _apply, flush="sync") return True def view_share_diagnostic(reference, st=None): """Return a detached diagnostic from the caller's tenant store, or ``None``. The API owns administrator admission. This helper never consults a default or foreign tenant when handed a runtime, and it exposes only the row identified by the support ref. """ ref = str(reference or "").strip().upper() if not ref.startswith("VS-") or len(ref) > 40: return None data = _st_for_boundaries(st).get(shares.SHARES_KEY) or {} rows = data.get(VIEW_SHARE_DIAGNOSTICS_KEY) or () for row in reversed(rows): if isinstance(row, dict) and row.get("reference") == ref: return copy.deepcopy(row) return None def drop_view_field_boundary(view_id, st=None): """Remove exactly one inherited source; direct and other-View grants remain untouched.""" view_id = str(view_id or "").strip() if not view_id: return False removed = {"value": False} def _apply(data): boundaries = data.get(VIEW_FIELD_BOUNDARIES_KEY) if isinstance(boundaries, dict) and view_id in boundaries: boundaries.pop(view_id, None) removed["value"] = True return data _st_for_boundaries(st).update(shares.SHARES_KEY, _apply, flush="async") return removed["value"] def _field_role_sources_from_data(topic, key, me, is_admin, data): """Resolve one field from one already-read share document.""" oid = shares.field_oid(topic, key) raw_direct = (data.get("field") or {}).get(oid) raw_direct = raw_direct if isinstance(raw_direct, dict) else {} direct_rec = {"owner": _uname(raw_direct.get("owner")) or None, "entries": shares._clean_entries(raw_direct.get("entries"))} direct = shares.role_from(direct_rec, me, is_admin=is_admin) if direct == "owner" or is_admin: return {"role": "owner", "direct": direct, "views": []} view_ids = [] boundaries = data.get(VIEW_FIELD_BOUNDARIES_KEY) or {} view_grants = data.get("view") or {} if isinstance(boundaries, dict) and isinstance(view_grants, dict): for view_id, boundary in boundaries.items(): if not isinstance(boundary, dict) or boundary.get("topic") != topic: continue if key not in {str(value) for value in (boundary.get("fields") or ())}: continue raw = view_grants.get(str(view_id)) if not isinstance(raw, dict): continue rec = {"owner": _uname(raw.get("owner")) or None, "entries": shares._clean_entries(raw.get("entries"))} if shares.role_from(rec, me, is_admin=False) is not None: view_ids.append(str(view_id)) role = direct if direct in ("edit", "view") else ("view" if view_ids else None) return {"role": role, "direct": direct, "views": sorted(view_ids)} def field_roles_for_keys(grant_topic, field_keys, viewer, *, is_admin=False, st=None): """Resolve many field roles from one share-document read.""" topic = str(grant_topic or "").strip() me = _uname(viewer) keys = [] seen = set() for raw in field_keys or (): key = str(raw or "").strip() if key and key not in seen: seen.add(key) keys.append(key) if not topic or not me: return {key: {"role": None, "direct": None, "views": []} for key in keys} try: data = _st_for_boundaries(st).get(shares.SHARES_KEY) or {} except Exception: # noqa: BLE001 data = {} return {key: _field_role_sources_from_data(topic, key, me, is_admin, data) for key in keys} def field_role_sources(grant_topic, field_key, viewer, *, is_admin=False, st=None): """Resolve one field role and its direct/View provenance. A View role inherits READ access only. ``Can edit`` on a View means editing the View's configuration, not taking ownership of or editing a colleague's field definition/value. Direct field roles remain stronger and are returned unchanged. """ key = str(field_key or "").strip() if not key: return {"role": None, "direct": None, "views": []} return field_roles_for_keys( grant_topic, [key], viewer, is_admin=is_admin, st=st).get( key, {"role": None, "direct": None, "views": []}) # Save the unwrapped direct resolver once, including across module reloads in verifier processes. _DIRECT_FIELD_ROLE_FOR = getattr(shares.role_for, "_direct_field_role_for", shares.role_for) def install_view_field_resolver(): """Install C8 at the existing ``shares.role_for`` wall, once per process. Lane V does not own ``core.shares`` or ``core.perm_scope``. The application imports its share router at startup, and that router explicitly installs this owned resolver. Every existing caller therefore keeps asking the same wall; only ``kind='field'`` gains the View-boundary leg. The original callable remains attached for direct/provenance reads. """ if getattr(shares.role_for, "_view_field_resolver", False): return shares.role_for def _role_for(kind, oid, user, is_admin=False, st=None): if kind != "field": return _DIRECT_FIELD_ROLE_FOR(kind, oid, user, is_admin=is_admin, st=st) topic, key = shares.split_field_oid(oid) if not topic or not key: return None return field_role_sources(topic, key, user, is_admin=is_admin, st=st)["role"] _role_for._view_field_resolver = True _role_for._direct_field_role_for = _DIRECT_FIELD_ROLE_FOR shares.role_for = _role_for return _role_for def permissions_from_grants(entries): """⭐⭐ W40-T03 / CONTRACT C4 — THE CLASSIFICATION IS DERIVED FROM THE REGISTRY, NEVER STAMPED. Owner instruction 21 (2026-08-23): *"A Field shared with only Karen Ganley shows under Hide Fields as 'Shared with everyone' — it should be 'Shared with me'. Fix the logic. By default every Field created is private until it is shared."* The registry (`core/shares.py`) already knows exactly who a column is shared with; the `permissions` bag on the definition is only the WORD the client sections on (`FieldsHidePanel` buckets by `types.fieldEditMode`). Until now those two could disagree, because `promote_field` stamped the bag from a hardcoded fallback BEFORE the request's own grant entries were written. This function is the single place the bag is derived from the grants, so the word on screen and the wall in the registry answer the same question. ⛔ CLASSIFICATION IS ABOUT **WHO**, NOT ABOUT **ROLE**, and that is C4's wording rather than an approximation: *"'Shared with me' means grants naming me"*. A `view`-role grantee is a person the column is shared with exactly as an `edit`-role one is, so both count. The role itself is NOT recoverable from this bag and is not meant to be — `shares.role_for` is what answers "may this account change it", on every path that asks (see the four short-circuits named on `reconcile_shared_permissions`). ⛔ THE WILDCARD WINS, AND THE NAMED USERS ARE DISCARDED. `*` plus named users is still "shared with everyone" on screen, because everyone can already reach it; carrying the named few alongside would produce a bag that says `users` while the registry admits the room. Discarding them is safe precisely because this bag is not a wall for a shared field: `role_for` keeps the stronger of an everyone-grant and a personal one, so a named user's raised role survives in the registry where it is actually read. ⛔ `known_users` IS DELIBERATELY NOT PASSED, HERE OR BY ANY CALLER ON THIS PATH. `clean_permissions` collapses to `{'edit': 'personal'}` when the filtered users list ends up empty, so ONE grantee missing from the user registry would silently reflip a shared column to Private — the owner's defect in the other direction, and just as invisible. `put_share` has already validated every grantee through `_entries_or_400` before the grant is stored, so the filter would only ever fire on a name that door already accepted. ⚠ THE USERS LIST IS SORTED, AND THAT IS WHAT MAKES THE RECONCILE IDEMPOTENT rather than merely convergent. `shares._clean_entries` preserves stored insertion order, so two grant sets holding the same people in a different order would otherwise derive two different-but-equal bags and rewrite each other forever on alternating reads (the D-358 egress class). """ users = [] seen = set() for entry in entries or (): if not isinstance(entry, dict): continue user = str(entry.get("user") or "").strip().lower() if not user or user in seen: continue seen.add(user) if user == shares.EVERYONE: return clean_permissions({"edit": "collaborative"}) users.append(user) if not users: return clean_permissions({"edit": "personal"}) return clean_permissions({"edit": "users", "users": sorted(users)}) # --------------------------------------------------------------- W41-T01 / R5 / C1: the badges def _governed(field): """Does the per-field grant WALL apply to this column? ⛔ ONE EVALUATOR, AND IT IS `perm_scope`'s. `granted_field_keys` is the cheap half of `field_grant_hidden`; asking it here is what makes the BADGE and the WALL incapable of disagreeing, which is this ticket's own acceptance. Re-spelling `f.get('granted') is True` locally would be a second reader of the mark, and a second reader is how the two come apart. ⛔ THE IMPORT IS LAZY, MATCHING `field_grant_hidden`'s OWN `import core.shares` AT ITS CALL SITE. `perm_scope` pulls `core.perms` -> `context`/`registry`/`users`; this module is imported lazily from `grid_events` precisely to stay cheap, and a top-level import here would widen its graph for every importer to buy nothing. """ try: import core.perm_scope as perm_scope except Exception: # noqa: BLE001 # Unresolvable means "not governed": the badge then reports the column's OTHER, true # properties instead of asserting a permission state it cannot verify. The wall itself # does not degrade with it — it lives in `perm_scope` and is unreachable from here. return False return bool(perm_scope.granted_field_keys([field] if isinstance(field, dict) else [])) #: ⭐⭐ W50-T23 / OWNER RULING R7 — THE `origin` WORDS THAT MEAN **THE CONNECTOR WROTE THIS #: COLUMN**, on a `ut_*` database. It is `core.user_tables.FIELD_ORIGINS` minus `'user'`, and it #: is SPELLED HERE rather than imported because `core.user_tables` imports back into `core` and a #: module-level import from this file would close a cycle (`_shared_value_keys`' note makes the #: same trade one function down). ⛔ THE TWO MUST NOT DRIFT: `verify_field_permissions.py` asserts #: `CONNECTOR_ORIGINS == user_tables.FIELD_ORIGINS - {'user'}` so a new origin word added there #: reddens a gate rather than silently reclassifying a whole database. CONNECTOR_ORIGINS = frozenset({"odoo", "loopable", "system", "automation"}) def is_connector_column(field): """Did a CONNECTED SOURCE write this column, rather than a person? ⭐⭐ OWNER RULING R7 (2026-09-03), verbatim: *"There is no such thing as an editable SYSTEM field. If it comes directly from a Connector like Odoo, obviously you can't change it. The Supplier field isn't a connector column."* So this is the ONE predicate for "system field", and it is positive evidence only. It covers all three places a definition is stored: * `automation.preset is True` — `automation_engine.ut_ensure` (L1233/L1293/L5280) and `_locked_ig_field`, the seeded/locked columns on a `ut_*` database; * `source == "odoo"` — the canonical contract (`aios_grid_fields.json`: 51 of product's 69 fields, 36 of customer's 37). `source` only ever takes `"odoo"` or `"overlay"` in production code, so this is exact rather than heuristic; * `origin` in `CONNECTOR_ORIGINS` — the `ut_*` vocabulary `user_tables._clean_field` keeps (it strips `custom` and `createdBy` but preserves `origin`), plus `core.monid`'s `origin: 'loopable'`. ⛔ `valueAuthority` AND `derived` ARE NOT MARKS HERE, and that is measured rather than cautious: both are caller-suppliable and a plain user formula column sets `derived`. Reading them would call somebody's own column a connector column, which is the direction that takes a delete away from its owner. """ if not isinstance(field, dict): return False automation = field.get("automation") if isinstance(automation, dict) and automation.get("preset") is True: return True if str(field.get("source") or "").strip().lower() == "odoo": return True return str(field.get("origin") or "").strip().lower() in CONNECTOR_ORIGINS def field_origin(field): """R5's FIRST badge: `"preset"` (a connected source made this column) or `"user"` (a person did) — RE-DERIVED under OWNER RULING R7, W50-T23. ⭐⭐ R7 IS THE LAW HERE AND IT IS NOT A REFINEMENT, IT IS A REVERSAL OF THE DEFAULT. *"Supplier on Odoo products is a USER-CREATED field, as if an admin created and entered it themselves … There is no such thing as an editable SYSTEM field."* Classification, in order: 1. `custom is True` or a non-blank `createdBy` -> `"user"` (positive author evidence) 2. otherwise a CONNECTOR mark (`is_connector_column`) -> `"preset"` 3. otherwise -> `"user"` ⛔⛔ THE ORDER MOVED, AND THE PARAGRAPH IT REPLACES SAID THE OPPOSITE. This docstring used to assert *"`automation.preset` IS CHECKED FIRST AND IT WINS"* and *"Supplier and every canonical Odoo column answer `preset`"*. The second claim was MEASURABLY FALSE the day it was written: `aios_grid_fields.json` carries `custom: true` on `supplier`, so leg 2 of the old body already answered `"user"` for it. The first claim is now retired by R7 — a column carrying an AUTHOR is that person's column whatever else it carries. ⚠ NO LIVE SHAPE CHANGES ON THAT REORDER: it was measured across all three storage places that no door emits both marks at once (`ut_ensure` and `_locked_ig_field` set `automation.preset` and stamp NEITHER `custom` NOR `createdBy`, because `user_tables._clean_field` strips both). The reorder is pinned by an NC fixture in `verify_field_permissions.py` that carries BOTH marks, so it is the gate and not this prose that holds the ordering. ⚠ ABSENCE NOW FALLS TO `"user"`, AND THE POLARITY FLIP IS DELIBERATE AND AUTHORISED. Under R7 every editable field has an owner (its creator, else the tenant Administrator), so an unmarked shared column is somebody's, not the platform's. ⛔ IT CHANGES A RIGHT: an unmarked legacy shared column is now DELETABLE by its owner or an administrator, where it was `"preset"` and therefore undeletable by anyone. `routes_tables.py` (its `delete_shared_field` note) books exactly that as a defect — *"such a column becomes undeletable rather than admin-only … booked as a defect rather than left to be discovered"* — and this closes it. ⚠ AND IT CLOSES THE `ut_*` GAP THE OLD DOCSTRING BOOKED. `user_tables._clean_field` keeps neither `custom` nor `createdBy` but DOES keep `origin`, so a user-created `ut_*` column now answers `"user"` off `origin: 'user'` (leg 3) instead of `"preset"`, and a connector-seeded one still answers `"preset"` off `origin: 'odoo'|'automation'|...` (leg 2). ⛔⛔ A DECISION, NOT A CONSEQUENCE: ON A `ut_*` DATABASE `origin` IS CALLER DISCIPLINE. `_clean_field` HARDCODES `source: 'overlay'`, DEFAULTS `origin` to `'user'`, and enforces nothing about who may set it. So the shape `{source: 'overlay', origin: 'user', valueAuthority: 'user-entered', scope: 'tenant'}` — no `custom`, no `createdBy`, no `automation` — is what that validator produces BOTH for a genuine user column AND for any connector column minted by a path that is not `automation_engine.ut_ensure` / `_locked_ig_field`, or that predates the `origin` stamp entirely. Under the old law it answered `"preset"` and was undeletable by anyone; under R7 it answers `"user"` and `routes_shares._field_owner` hands it to the tenant Administrator as an owned, deletable column. ⛔ THAT IS THE FAIL-OPEN DIRECTION the old docstring's conservatism was buying, it is taken KNOWINGLY, and R7 authorises it: *"every editable field has an owner (its creator, else the tenant Administrator)"*, and a column with no owner at all was the worse failure — nobody could delete it, nobody could be asked for it, and the dialog printed a blank. Connector detection on `ut_*` therefore rests on `automation.preset` plus a caller-supplied `origin`, and an unmarked column there is now read as SOMEBODY'S rather than as the platform's. `verify_field_permissions.py` pins that exact fixture. ⛔ AND THE `type != 'rollup'` LEG OF THE CLIENT'S `isSchemaLocked` IS STILL DELIBERATELY NOT REPEATED HERE: that leg answers *"may this be edited"* (`user_tables.preset_editable` returns True for exactly `rollup`), which is a RIGHT derived from the badge, not the badge. """ if not isinstance(field, dict): # Not a definition at all. `"preset"` is the only honest answer: there is nothing here # that could carry an author, so nothing to hand a right to. return "preset" if field.get("custom") is True or _uname(field.get("createdBy")): return "user" if is_connector_column(field): return "preset" return "user" def _grant_mark(): """The name of the wall's own mark, read from `perm_scope` and never re-spelled locally. ⛔ `_governed`'s note forbids a second reader by name: *"Re-spelling `f.get('granted') is True` locally would be a second reader of the mark, and a second reader is how the two come apart."* The stratum fallback below needs the same mark, so it takes the CONSTANT rather than the literal, and the two cannot drift apart on a rename. ⚠ THE FAILURE DIRECTION IS DELIBERATE AND IS THE OPPOSITE OF `_governed`'S. `_governed` degrades to `False` (not governed), which is right for a WALL question. Here an unresolvable import must not tip a definition toward `personal`, because `personal` zeroes the grant record in `field_class`; falling back to the mark's own spelling keeps the conservative answer (`shared`, i.e. trust the registry) when `core.perm_scope` cannot be loaded at all. """ try: import core.perm_scope as perm_scope return str(perm_scope.FIELD_GRANT_MARK) except Exception: # noqa: BLE001 return "granted" #: S79-T68 / R64 (D-487): a contract column that the wall governs only where a grant names it. #: It is not the wall's mark: `granted` with no record hides the column from every account. FIELD_WALL_MARK = "walled" def walled_field_keys(fields): """The keys of `fields` that carry `FIELD_WALL_MARK: true`.""" return {str(f["key"]) for f in (fields or ()) if isinstance(f, dict) and f.get("key") and f.get(FIELD_WALL_MARK) is True} def _names_somebody(record): """True if a grant record has an owner or at least one entry (the arming rule).""" record = record if isinstance(record, dict) else {} return bool(record.get("owner") or record.get("entries")) def arm_walls(fields, grant_topic, st=None): """A new field list where each walled field whose grant record names somebody carries the wall's mark. Every other field comes back unchanged and the input list is never mutated. """ fields = list(fields or ()) walled = walled_field_keys(fields) if not walled: return fields mark = _grant_mark() out = [] for f in fields: key = str(f.get("key") or "") if isinstance(f, dict) else "" # A lenient read that answers empty in a cold-cache window leaves the column visible (R64). if key in walled and f.get(mark) is not True and _names_somebody( _grant_record(key, grant_topic=grant_topic, st=st)): f = dict(f, **{mark: True}) out.append(f) return out def field_stratum(field): """⭐⭐ W42-T47 / R15 / C10 — THE **FALLBACK** DERIVATION OF WHICH STRATUM A DEFINITION CAME FROM, for a caller that cannot lend the fact. See `FIELD_DEFINITION_STRATA`. ⛔⛔ IT IS A FALLBACK AND NOT THE ANSWER, AND THE REASON IS THE WHOLE OF THIS TICKET: **NOTHING ON A FIELD DEFINITION RECORDS WHICH DOCUMENT IT WAS READ FROM.** Every mark that looks like evidence survives being COPIED OUT of that document: * `routes_customers._merge_shared_fields` projects a shared definition as `dict(f, source="overlay", shared=True)`; * that merged list reaches `grid_events.field_upsert`, whose fork-minting branch is `base = field_by_key[key]` then `field = {**base, 'note': ...}` — `{**base}` copies EVERY key, `shared` and `granted` and `source` included; * `TableStore.save_field` then writes that copy into THIS user's own workspace member. So a personal fork of a tenant-wide route carries `shared: True` verbatim, and a mark-based test calls it `shared`. That is R15's own reproduction (gabriel mints `route_x`; another account forks it through Format or Summary), which is exactly the case this member exists to report, so the mark test cannot be the producer of the answer. ⛔ ADDING MORE MARKS DOES NOT RESCUE IT. `source == "overlay"` is copied by the same `{**base}` and fails identically. A key-keyed store (the grant registry, `shared_overlay.fields()` membership, the lent `values_shared`) fails the other way: it answers about whichever definition of that key lives in ITS document, which on a fork is a DIFFERENT definition from the dict in hand, so it can never report the conflict either. ⚠ THE BLIND SPOT, STATED RATHER THAN HIDDEN: **this fallback cannot see a fork, and names one `shared`.** A documented blind spot beats a silent one; the honest answer is lent by the assembly that DID the reading, through `field_class(stratum=...)` / `field_classes(strata=...)`. The marks are still the best available evidence for everything else, and the polarity matches `field_origin`'s: unmarked plus a demonstrable author is `personal`, everything else `contract`. """ if not isinstance(field, dict): return "contract" if field.get("shared") is True or field.get(_grant_mark()) is True: return "shared" if field_origin(field) == "user": return "personal" return "contract" def _clean_stratum(value, field=None): """One lent stratum, canonicalised, falling back to `field_stratum` on anything unrecognised. ⛔ AN UNKNOWN TOKEN FALLS BACK RATHER THAN FAILING CLOSED TO `personal`. `personal` is not the safe direction here: it ZEROES the grant record in `field_class`, so a typo in a lent map would silently strip the owner and the audience off every column it named. """ token = str(value or "").strip().lower() if token in FIELD_DEFINITION_STRATA: return token return field_stratum(field) def _shared_value_keys(table_key, st=None): """The columns of `table_key` whose VALUES are one tenant-wide stratum.""" key = str(table_key or "").strip() if not key: return set() try: return {str(k) for k in shared_overlay.fields(key, st=st)} except Exception: # noqa: BLE001 return set() def _empty_record(): return {"owner": None, "entries": []} def _grant_record(field_key, table_key=None, grant_topic=None, st=None): """ONE column's grant record, read straight from the registry.""" topic = str(grant_topic or table_key or "").strip() key = str(field_key or "").strip() if not topic or not key: return _empty_record() try: return shares.grants("field", shares.field_oid(topic, key), st=st) except Exception: # noqa: BLE001 return _empty_record() def grant_records(grant_topic, st=None): """`{field_key: {'owner', 'entries'}}` for one topic, on **ONE** read of `object_shares`. ⭐⭐ THE BATCH EXISTS FOR A MEASURED REASON, NOT FOR TIDINESS. `shares.grants` opens the registry per call and `store.get` hands back `json.loads(json.dumps(...))` — a fresh deep copy every time. Badging a customer grid is 40-60 columns, so the per-field door is 40-60 serialise/deserialise round trips added to the hot read path. That is the exact shape `grid_assembly`'s own W38-T20 note spent a ticket removing (*"three consumers want this dict on one request, and letting each take its own copy is the shape D-214 spent a whole ticket removing one document over"*). ⛔ THE ENTRIES GO THROUGH `shares._clean_entries`, WHICH IS NOT OPTIONAL AND IS NOT TIDYING. That normaliser DROPS an entry whose role is not in `shares.ROLES`, and `permissions_from_grants` checks only the user. Reading the bucket raw would let a junk-role entry make this badge say `users` while `shares.role_for` — which reads through `grants()`, i.e. through the normaliser — walls that same person out. A badge that disagrees with the wall is precisely what R5's *"every right derives from them"* forbids. Same normaliser, therefore same answer. ⚠ THE TOPIC IS THE GRANT TOPIC, NOT THE BUCKET. `migrate_legacy_fields` already carries this warning in full: `shared_key` names the store bucket (`customer_table_workspace__shared`) and `grant_topic` names the registry namespace (`customer_data`). Handing this one the bucket finds no record for any column and every badge silently reads as never-shared. """ topic = str(grant_topic or "").strip() if not topic: return {} try: bucket = (shares._st(st).get(shares.SHARES_KEY) or {}).get("field") or {} except Exception: # noqa: BLE001 return {} if not isinstance(bucket, dict): return {} out = {} for oid, rec in bucket.items(): table, key = shares.split_field_oid(oid) # `split_field_oid` FAILS CLOSED on junk (`(None, None)`), so an unparseable id is skipped # rather than being attributed to whichever database is being read. if table != topic or not key or not isinstance(rec, dict): continue out[key] = {"owner": (_uname(rec.get("owner")) or None), "entries": shares._clean_entries(rec.get("entries"))} return out def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None, values_shared=None, stratum=None, st=None): """⭐⭐ W41-T01 / R5 / CONTRACT C1 — **THE ONE PRODUCER OF A FIELD'S THREE BADGES.** Returns `{origin, audience, sharedBy, values, owner, stratum}` and nothing else derives a badge independently. The member spellings are C1's and C10's, and they are the wire's: the payload key is `class`, its members are `origin`, `audience`, `sharedBy`, `values`, `owner`, `stratum`. **stratum** — ⭐⭐ W42-T47 / R15 / C10, and it is the member the other five are now ANCHORED to. `contract` | `shared` | `personal`: WHICH DOCUMENT this definition was read from. The client sections on ownership (My fields / From my colleagues / Built in) from `stratum` plus `owner` WITHOUT re-deriving either. ⚠ IT IS **LENT BY THE CALLER**, for `values_shared`'s reason turned up one notch: not merely that `core` never imports up, but that the fact is not present in ANY of this function's inputs. Nothing on a definition records the document it came from, because every mark on it survives being copied out of that document (`field_stratum` carries the proof and the copying doors). Only the assembly that DID the reading knows, so it lends `field_classes(strata={key: stratum})`, and absent that the derivation falls back to `field_stratum`, whose blind spot is stated there rather than hidden here. `viewer` is a USERNAME STRING (`session.uname`), never a user dict — a dict compares unequal to every stored name, which would make `sharedBy` silently never match and `owner` never equal the reader. **origin** — `field_origin`, above. **audience** — `private` | `users` | `everyone`, and it MIRRORS THE WALL rather than paraphrasing it, because a badge that says something the wall does not enforce is worse than no badge: * a column carrying `perm_scope.FIELD_GRANT_MARK` is GOVERNED, so the registry answers, through the existing `permissions_from_grants` (extended, never duplicated): a `*` grant is `everyone`, named grants are `users`, no grant at all is `private`; * an UNGOVERNED column is not walled by `field_grant_hidden` at all, so whoever holds the database holds the column. It is therefore `everyone` when the column is tenant-wide — a contract-declared one (Supplier, and every canonical Odoo column) or one living in the shared stratum — and `private` when it is not, because a per-user definition exists only in its creator's own stratum and no other account ever receives it. ⭐ SUPPLIER IS THE CASE THE THIRD BADGE EXISTS FOR, AND IT IS WHY THE CONTRACT LEG IS NOT OPTIONAL. It answers `everyone` while having NO `object_shares` row at all — its audience comes from the contract that declared it, not from the registry, which is exactly why `ShareDialog` prints "Not shared with anyone yet." about a column the whole workspace can already read. ⛔ THE TRAP, AND IT IS THIS TICKET'S OWN: `shared_overlay`'s `"shared": True` IS WRITTEN AND NEVER READ (D-414). It is not consulted anywhere here. `FIELD_GRANT_MARK` is the only flag the wall reads, so it is the only flag this function reads, and tenant-wide-ness is answered by MEMBERSHIP (`values_shared`) rather than by that stale boolean. ⚠ A ROUTE COLUMN MINTED BEFORE THE MARK EXISTED THEREFORE READS `everyone`, AND THAT IS THE TRUTH RATHER THAN A MISS. Such a column carries `shared: True` alone, is not `granted`, and genuinely leaks to the whole tenant; the badge reports the leak instead of papering over it. Closing it is W41-T05's work, and this badge is how it becomes visible. **sharedBy** — who shared it TO this viewer, or `None`. `shares.grants` carries `by` per entry (D-474) and the owner is the fallback when a pre-D-474 record has none. `None` when the viewer IS the owner, when nobody shared it, or when the viewer shared it to themselves. ⚠ IT IS EMITTED UNDER AN `everyone` AUDIENCE TOO, not only under `users`. R5 renders the three as alternative states of one badge, so a consumer that only wants a name for `Shared by ` reads it under `users` and ignores it otherwise — but the fact ("alice let you in") is true in both, and withholding it would make the producer decide a rendering question that belongs to the consumer. **values** — `shared` when this column's VALUES are one stratum everyone sees (membership of `shared_overlay.fields()` for an overlay topic, or a module's `SHARED_KEYS()` for a contract-declared one), else `personal`. This is R5's new information and it is INDEPENDENT of audience: a route column is `private` with `shared` values, Supplier is `everyone` with `shared` values, and a column you made is `private` with `personal` ones. ⛔⛔ W42-T47 / R15 — `values` AND `audience` KEEP READING GENUINELY DIFFERENT STORES, AND THEY ARE STILL INCAPABLE OF DESCRIBING DIFFERENT DEFINITIONS. The independence is required (one is membership of the shared-overlay stratum, the other is `shares.grants`), so it is not removed; what is removed is the second opinion about WHICH DEFINITION is being described. `stratum` is computed once, from the definition in hand, and both legs are anchored to it: the registry is not consulted at all on a `personal` definition, and `values` no longer decides an audience for one. R15's *"`Private` + `Shared values` is NOT a state to preserve, it IS the bug"* is therefore answered by making the pair UNAMBIGUOUS rather than by suppressing either member: a column whose cells come from the shared pool but whose definition is the reader's own now reads `{stratum: 'personal', values: 'shared', audience: 'private', owner: }`, which is one coherent sentence and the exact fact the owner reported, instead of two badges that contradict each other about who has this column. ⚠ `values_shared` IS LENT BY THE CALLER because the key set is a MODULE-level fact (`product_data.SHARED_KEYS()`), and `core` never imports up. Absent, it is derived from `shared_overlay.fields(table_key)`, which is right for an overlay topic and blind to a contract-declared one. **owner** — the registry's owner, falling back to the definition's `createdBy` when the registry has no record. ⚠ THE FALLBACK IS NOT BELT-AND-BRACES: the create door writes the definition FIRST and claims the grant SECOND, on purpose, so the window where a column exists unclaimed is real. `field_grant_hidden` already relies on exactly this fallback to stop a creator being walled out of the column they just made. """ field = field if isinstance(field, dict) else {} key = str(field.get("key") or "").strip() me = _uname(viewer) origin = field_origin(field) # ⛔⛔ W42-T47 — AN **ASSERTED** STRATUM ANCHORS THE BAG; A GUESSED ONE REPORTS AND NOTHING MORE. # `user_tables._field_badges` calls `field_class` on a RIGHTS path: `delete_field_refusal` reads # `bag['owner']` and returns `NOT_FIELD_OWNER` on a mismatch, so anything that moves `owner` # moves a delete. That caller lends no stratum, and the fallback derivation is a guess by its # own docstring, so letting a guess re-source `owner` could hand somebody a delete they did not # have. This ticket makes a REPORT honest; it moves no wall, and this line is where that # promise is kept rather than asserted. A caller that KNOWS which document it read (C10's lent # map) gets the anchored answer; every existing caller keeps today's behaviour byte for byte. asserted = str(stratum or "").strip().lower() in FIELD_DEFINITION_STRATA stratum = _clean_stratum(stratum, field) anchored_personal = asserted and stratum == "personal" record = grants if isinstance(grants, dict) else _grant_record( key, table_key=table_key, grant_topic=grant_topic, st=st) # ⛔⛔ W42-T47 / R15 / C10 — THE REGISTRY RECORD IS KEYED BY FIELD **KEY**, SO ON A PERSONAL # DEFINITION IT DESCRIBES A DIFFERENT DEFINITION AND IS DROPPED ENTIRELY. # # `shares.field_oid(topic, key)` names a KEY, not a document. A grant record for `route_x` was # written about the definition in the tenant-wide bucket; when the dict in hand came from the # reader's own workspace member instead, those are two different definitions of one key, and # `routes_customers._merge_shared_fields` makes that routine rather than exotic — its rule is # `if k in have: continue`, so a reader holding ANY same-key entry silently keeps their own and # never sees the shared one (that merge is W42-T46's, not this ticket's). # # Reading `owner`, `sharedBy` and `audience` off that record while reading `origin`, `values` # and the marks off the personal dict is how ONE bag came to describe TWO definitions, which is # R15's *"Gabriel created the Route and it ends up being MY field"* — the owner fact and the # audience were answering about different documents. Zeroing the record here is what makes the # anchoring STRUCTURAL: after this line there is no path by which a registry-derived member can # describe a definition the `stratum` member does not name. # # ⚠ NO PERMISSION MOVES, AND IT IS CHECKED RATHER THAN REASONED — BUT NOT FOR THE REASON IT # FIRST LOOKS LIKE. A fork carries `granted: True` copied verbatim, so a `personal` definition # CAN be one the wall does consult the registry about; this arm is exactly where R15's fork # lands. What makes it safe is that the wall reads the registry ITSELF # (`perm_scope.field_grant_hidden` -> `shares.role_for`) and never reads this bag, so zeroing # here changes the REPORT and nothing else. The report is the thing that was wrong: a personal # definition's grant record describes a document the reader is not reading. if anchored_personal: record = _empty_record() owner = _uname(record.get("owner")) or None entries = [e for e in (record.get("entries") or ()) if isinstance(e, dict)] if values_shared is None: values_shared = _shared_value_keys(table_key, st=st) values = "shared" if key and key in {str(k) for k in values_shared} else "personal" # R64: an armed wall is governed, so the badge agrees with `arm_walls` on the same record. if _governed(field) or (key in walled_field_keys([field]) and _names_somebody(record)): audience = _AUDIENCE_FROM_EDIT.get( permissions_from_grants(entries).get("edit"), "private") elif not anchored_personal and (values == "shared" or origin == "preset"): # Ungoverned AND tenant-wide: the database's holders all hold this column. `origin` covers # a contract-declared column whose VALUES are per-user (a canonical Odoo column); the # `values` leg covers a shared-stratum column the contract never named. # # ⛔ W42-T47 — THE `stratum != "personal"` GUARD IS THIS TICKET'S BEHAVIOUR CHANGE, AND IT # FIRES ON EXACTLY ONE SHAPE: a definition read from the reader's OWN workspace member # whose key ALSO has a definition (and therefore shared cells) in the tenant-wide bucket. # Without it, `values` — a fact about the SHARED document — promoted a definition nobody # else can even receive to `everyone`. The reader would be told the whole tenant can see a # column that exists only in their own stratum, which is a promise the merge cannot keep. # ⚠ It cannot touch a shared or contract definition: both answer a `stratum` this test # admits, so Supplier and every minted route badge exactly as they did before. audience = "everyone" else: audience = "private" shared_by = None if me and me != owner: mine = next((e for e in entries if _uname(e.get("user")) == me), None) room = next((e for e in entries if _uname(e.get("user")) == shares.EVERYONE), None) entry = mine if mine is not None else room if entry is not None: shared_by = _uname(entry.get("by")) or owner if shared_by == me: shared_by = None # ⚠ THE `createdBy` FALLBACK IS NOW THE WHOLE ANSWER ON A PERSONAL DEFINITION, not merely the # create-window stopgap it was written as, because `record` was zeroed above. That is the # intended reading of C10's *"whose it is"*: the author mark rides on the definition that was # read, so `owner` and `stratum` cannot name different documents. return {"origin": origin, "audience": audience, "sharedBy": shared_by, "values": values, "owner": owner or _uname(field.get("createdBy")) or None, "stratum": stratum} def field_classes(fields, viewer, *, table_key=None, grant_topic=None, values_shared=None, strata=None, st=None): """`{field_key: }` for a whole field list, on ONE registry read. See `grant_records`. ⭐⭐ W42-T47 / C10 — every bag carries `stratum` (`contract` | `shared` | `personal`), so a caller sections on ownership without re-deriving it. ⛔ `strata` IS THE LENT MAP AND IT IS THE ONLY HONEST SOURCE: `{field_key: }`, supplied by the assembly that READ each definition and therefore knows which document each entry of `fields` came out of. Partial maps are fine — a key the map does not name falls back to `field_stratum`, per key, so a caller can lend only the keys it is sure about. ⚠ THE PER-FIELD ANSWER IS NOT DERIVABLE FROM ANYTHING THIS FUNCTION HOLDS: `records` and `values_shared` are both keyed by field key, so they describe whichever definition of that key lives in THEIR store, which on a forked column is a different definition from the one in `fields`. That is why the fact is lent rather than computed here. ⚠ EVERY COLUMN GETS A BAG, INCLUDING ONE THE REGISTRY HAS NEVER HEARD OF: the missing record is substituted explicitly rather than left to `field_class` to re-read, which is what keeps the single read single. """ topic = str(grant_topic or table_key or "").strip() records = grant_records(topic, st=st) if values_shared is None: values_shared = _shared_value_keys(table_key, st=st) shared_keys = {str(k) for k in (values_shared or ())} lent = {str(k).strip(): v for k, v in strata.items()} if isinstance(strata, dict) else {} out = {} for field in (fields or ()): if not isinstance(field, dict): continue key = str(field.get("key") or "").strip() if not key: continue out[key] = field_class(field, viewer, grants=records.get(key) or _empty_record(), table_key=table_key, grant_topic=topic, values_shared=shared_keys, stratum=lent.get(key), st=st) return out def _same_classification(left, right): """Do two canonical bags say the same thing about WHO? ⚠ THE USERS LIST IS COMPARED AS A SET, not as a sequence, and that is a write-count decision rather than a nicety. A stored bag minted before the sort above carries the registry's insertion order; comparing sequences would rewrite every such column once for a change no reader can see. `shared_overlay.put_field` is a `flush='sync'` store commit per field, so a difference nobody can observe must not cost one. """ if left.get("edit") != right.get("edit"): return False return set(left.get("users") or ()) == set(right.get("users") or ()) def reconcile_shared_permissions(shared_key, grant_topic, st=None, shared_document=None): """Re-derive every SHARED definition's `permissions` bag from the grant registry. Returns the number of definitions actually rewritten. ⭐⭐ THIS IS A **WRITE ON A READ PATH**, ON A TENANT-WIDE STRATUM, AND IT IS DELIBERATE. `routes_customers.py`'s `ROUTE_KIND` comment argues the opposite case for route columns (*"Backfilling every stored route definition on a read is a write nobody asked for, on a tenant-wide stratum, triggered by opening a page"*) and settles it with "re-solving is one click and it is the click the owner is already making". A SHARED FIELD HAS NO SUCH CLICK: the owner's "Fisch Main Catalog" was shared once, months ago, and nothing will ever rewrite its definition again. Leaving it to a future re-share is leaving it wrong forever. C4 also makes the registry AUTHORITATIVE, which a stamp that is never re-derived cannot be. This function is called from `migrate_legacy_fields`, which is already exactly such a pass — it runs `flush='sync'` promotions on the same three read paths — so this adds a kind of write to a door that already makes them, not a new door. ⛔ ONLY A REAL SHARE RECORD MAY TURN SHARED STORAGE INTO A SHARE-GOVERNED FIELD. The pass inspects older `shared` definitions so it can find pre-marker grant records, but it writes `granted: true` only after the registry proves one exists. From then on `grid_events._may_edit_field_definition`, `::_may_edit_field_value`, the two client predicates, and `perm_scope.field_grant_hidden` all key off that explicit marker. A tenant-wide contract field such as Product Supplier can therefore retain its ordinary collaborative permission bag without being mistaken for a separately shared field. ⛔ NO GRANT RECORD AT ALL MEANS **LEAVE IT ALONE**, and the distinction is why `shares.grants` returning an owner with zero entries is a different answer from returning neither. A record with an owner and no entries is a column somebody has managed and shared with nobody: that is `personal`, positively. A column the registry has never heard of is a column this function knows nothing about, and inventing a classification for it would be guessing in the direction of a visible change. ⚠ ONE `put_field` PER CHANGED DEFINITION, and the bound is what makes that acceptable. Only a definition whose stored bag DISAGREES with its grants is rewritten, which in practice is the handful first shared before this derivation existed; steady state is zero writes, proven by the idempotence leg of the harness. `shared_overlay.put_rows`' docstring carries this repo's measured scar for the opposite shape (*"18 writes against one document under the store's coalescing single-flight landed ZERO while answering 200 eighteen times"*), so if a corpus ever makes this pass write in bulk it must become ONE batched write rather than a loop. """ bucket = str(shared_key or "").strip() grant_key = str(grant_topic or bucket).strip() if not bucket or st is None: return 0 rewritten = 0 grant_mark = _grant_mark() for field_key, defn in list(shared_overlay.fields( bucket, st=st, document=shared_document).items()): # ⚠ EACH DEFINITION IS GUARDED ON ITS OWN. `shares.field_oid` RAISES on an empty key, and # the caller wraps this whole function in one swallowing except — so a single malformed # entry would otherwise skip every REMAINING column, including the one the owner reported, # and report as "nothing to reclassify" with no failure anywhere near the cause. try: if not isinstance(defn, dict): continue if not (defn.get("shared") or defn.get("granted")): continue key = str(field_key or "").strip() if not key: continue record = shares.grants("field", shares.field_oid(grant_key, key), st=st) if not record.get("owner") and not record.get("entries"): continue derived = permissions_from_grants(record.get("entries")) stored = defn.get("permissions") # ⛔ A MISSING BAG IS ALWAYS A DIFFERENCE, EVEN WHEN THE DERIVATION SAYS `personal`. # This is the leg that decides whether the fix is visible at all. The client's own # fallback is `"collaborative"` (`types.cleanFieldPermissions(field.permissions, # "collaborative")`), so a definition carrying NO bag renders as "Shared with # everyone" no matter what the registry says. Comparing canonicalised values would # find `personal == personal` and write nothing, and the column would keep reading # "Shared with everyone" forever. The server must emit an EXPLICIT bag on every # shared definition; absence is not a value the wire can carry. if (defn.get(grant_mark) is True and isinstance(stored, dict) and _same_classification(clean_permissions(stored), derived)): continue updated = dict(defn) # ``shared`` alone is storage residency. A legacy tenant-wide field with a real # registry record is promoted to the explicit grant marker so all permission walls # agree without turning ungoverned contract fields into read-only fields. updated[grant_mark] = True updated["permissions"] = derived if not getattr(st, "schema_only", False): shared_overlay.put_field(bucket, key, updated, st=st) if isinstance(shared_document, dict): shared_document.setdefault("fields", {})[key] = updated rewritten += 1 except Exception: continue return rewritten # ═════════ W41-T07 / OWNER INSTRUCTION 21 — A DELETED FIELD STAYS DELETED ═══════════════════ # # Owner, verbatim: *"Deleting a field from Hide fields does not stick; 'August Campaign' on Odoo # customer has reappeared three times."* # # ⛔⛔ MEASURED IN-PROCESS BEFORE ANY OF THIS WAS WRITTEN, because the scout listed the cause as a # HYPOTHESIS and building on an unverified one is how a wave ships a correct fix for the wrong # defect. `promote_field` (and the promotion arm of `migrate_legacy_fields` below) POPS the # definition out of its creator's stratum, so on a PROMOTED column `table_store.delete_field` is a # **total no-op**: the creator's `fields` map no longer holds the key, the shared bucket is a # different document its `shared=` callback cannot reach, and every other account's fork is # untouched. Observed: `anna['fields'] changed? False`, `shared_overlay STILL holds it? True`. # The column the owner deleted three times was never deleted once. # # ⛔ AND `shared_overlay.drop_field` ALONE DOES NOT FIX IT, also measured: drop the shared # definition, run ONE read, and `migrate_legacy_fields` promotes it straight back out of a fork # sitting in another account's workspace. That is the fifth leg, and it is why the delete has to # be a SWEEP of every stratum rather than a call to any one door. # # ⚠ WHICH FORKS RE-PROMOTE, measured, because the guard is untestable without it: a fork carrying # NO permissions bag re-promotes (`stored_permissions` falls back to `collaborative`), one saying # `collaborative` re-promotes, and one saying `personal` does not. A negative control built on a # `personal` fork proves nothing at all: it would stay deleted with every guard disabled. #: The tenant-wide member of a `_table_workspace` document — `core.table_store.SHARED_KEY`. #: ⚠ SPELLED, NOT IMPORTED, and deliberately: `table_store` imports nothing from this module and #: an import the other way would close a cycle in `core`. `migrate_legacy_fields` has skipped this #: member by the same literal since it was written, so the constant names what was already here. WORKSPACE_SHARED_MEMBER = "__shared__" #: Where a delete records itself: `__shared__.deletedFields = {field_key: }`. #: #: ⭐⭐ THE RESIDENCY IS THE WHOLE COST ARGUMENT. `migrate_legacy_fields` ALREADY reads the #: workspace document (`document = st.get(key)`) and a delete ALREADY writes it (the fork sweep), #: so the tombstone is read for free on every read path and written in the SAME transaction as the #: sweep it belongs to. One update, one flush, one failure mode — `table_store._update`'s own #: argument for taking a `shared=` callback instead of making a second write. #: #: ⛔ IT IS A SIBLING OF `__shared__.fields`, NOT AN ENTRY IN IT, and that is what keeps it out of #: everyone's way. `table_store._shared_fields` reads `__shared__['fields']`; `assert_annotation_only` #: judges only the entries of `__shared__['fields']` #: — so nothing that reads this member can see this book, and the C3 annotation law has nothing to #: bite on. ⛔ AND IT IS NOT IN THE SHARED-OVERLAY BUCKET, which was the other candidate: that #: document carries every shared CELL in the tenant and `store.get_projection` drops keys from #: top-level VALUES rather than top-level keys, so reading it for a tombstone would buy a whole #: deep copy of the cells on every read — the D-214 shape, paid on the hot path, for a dozen bytes. DELETED_FIELDS_MEMBER = "deletedFields" #: How long a tombstone suppresses the IMPLICIT legacy promotion. See `delete_field_everywhere` #: for why a finite window is the anti-leak, not a weakness. TOMBSTONE_TTL_S = 900 #: The book is compacted on every write, so this is a ceiling on a document nobody prunes. MAX_TOMBSTONES = 200 def _live_tombstones(document, now=None): """`{field_key: deleted_at}` for the deletes still inside their window, from a document the caller ALREADY HOLDS. Costs no read, and never writes. ⚠ EXPIRY IS READ-SIDE FILTERING, NOT A SWEEP. Retiring an expired entry would be a write on a read path, on a tenant-wide document, triggered by opening a page — the exact shape `reconcile_shared_permissions` had to argue its way past. An expired entry is INERT here and is compacted by `_stamp_tombstone` on the next delete, which is a write somebody asked for. """ member = (document or {}).get(WORKSPACE_SHARED_MEMBER) book = member.get(DELETED_FIELDS_MEMBER) if isinstance(member, dict) else None if not isinstance(book, dict): return {} now = int(time.time()) if now is None else int(now) out = {} for field_key, at in book.items(): # `bool` IS an `int` in Python, so it is excluded by name: `{'k': True}` would otherwise # read as "deleted at epoch 1" and be permanently expired, i.e. a silently absent guard. if isinstance(at, bool) or not isinstance(at, (int, float)): continue if now - int(at) < TOMBSTONE_TTL_S: out[str(field_key)] = int(at) return out def _stamp_tombstone(shared_member, field_key, now): """Record one delete in the `__shared__` member being written. Compacts as it goes. ⚠ A SEPARATE MODULE-LEVEL FUNCTION RATHER THAN A CLOSURE, so the fifth-leg guard can be DISABLED for a negative control without editing the delete. A guard nothing can turn off is a guard nobody can prove is doing the work. """ book = shared_member.get(DELETED_FIELDS_MEMBER) book = book if isinstance(book, dict) else {} fresh = {str(k): int(v) for k, v in book.items() if not isinstance(v, bool) and isinstance(v, (int, float)) and now - int(v) < TOMBSTONE_TTL_S} fresh[str(field_key)] = int(now) if len(fresh) > MAX_TOMBSTONES: for stale in sorted(fresh, key=lambda k: fresh[k])[:len(fresh) - MAX_TOMBSTONES]: fresh.pop(stale, None) shared_member[DELETED_FIELDS_MEMBER] = fresh return fresh def _retire_tombstone(document, field_key): """Forget one delete, because somebody has explicitly said the column should exist again.""" member = (document or {}).get(WORKSPACE_SHARED_MEMBER) book = member.get(DELETED_FIELDS_MEMBER) if isinstance(member, dict) else None if isinstance(book, dict): book.pop(str(field_key), None) return document @_settings_transaction def retire_deleted_field(workspace_key, field_key, st=None): """Forget a live delete of `field_key` before a door declares that column again. False when none.""" if st is None: return False document = _workspace_read(st, workspace_key, owners=(WORKSPACE_SHARED_MEMBER,), drop=('overlays',)) if str(field_key) not in _live_tombstones(document or {}): return False _workspace_update(st, workspace_key, lambda data: _retire_tombstone( data if isinstance(data, dict) else {}, field_key), owners=(WORKSPACE_SHARED_MEMBER,)) return True def _purge_forks(document, field_key): """Drop one column's DEFINITION and VALUES from EVERY account's stratum. Returns the owners hit. ⛔⛔ EVERY ACCOUNT, WHICH IS THE ONE THING A PER-USER DELETE CANNOT DO AND THE REASON THIS EXISTS. `table_store.delete_field(username, key)` reaches exactly one member of this document. A fork left in any other member is re-promoted into the shared stratum by `migrate_legacy_fields` on the very next read, and the column is back — measured, not reasoned. ⚠ Deleting a COLUMN is already a tenant-wide act (`table_store.delete_field`'s own note makes that argument about the tenant-wide summary), so reaching across accounts here is the same act, not a wider one. The RIGHT to do it was answered before this function was reached. ⚠ MODULE-LEVEL AND NOT A CLOSURE, for `_stamp_tombstone`'s reason: the negative control has to be able to switch this off and watch the column come back. """ key = str(field_key or "") owners = [] for owner, workspace in list((document or {}).items()): if owner == WORKSPACE_SHARED_MEMBER or not isinstance(workspace, dict): continue touched = False fields = workspace.get("fields") if isinstance(fields, dict) and fields.pop(key, None) is not None: touched = True overlays = workspace.get("overlays") if isinstance(overlays, dict): for values in overlays.values(): if isinstance(values, dict) and values.pop(key, None) is not None: touched = True if touched: owners.append(str(owner)) return owners def _field_is_migratable(field): return (isinstance(field, dict) and field.get("custom") is True and field.get("source") == "overlay") #: ⭐ W50-T23 — the one suffix that separates a topic's WORKSPACE spelling from its BARE one. _WORKSPACE_SUFFIX = "_table_workspace" def legacy_shared_key(shared_key): """The OTHER spelling of this topic's shared bucket, or `""` when there is only one. A topic's shared stratum has exactly two spellings that have ever been written: `__shared` and `_table_workspace__shared`. Which one is canonical is decided by the door that resolves it — `grid_events._field_share_keys` and its mirror `routes_shares._field_storage_keys` — and the answer differs by family: the two built-in topics use the WORKSPACE spelling (`product_table_workspace__shared`) and a `ut_*` database uses the BARE one (`ut_leads__shared`; `perm_scope` says so in as many words). So this function does not pick a winner. It names the spelling that is NOT canonical for whatever key the caller was already handed, and the fold always runs toward the caller's key. """ key = str(shared_key or "").strip() if not key: return "" if key.endswith(_WORKSPACE_SUFFIX): return key[:-len(_WORKSPACE_SUFFIX)] return f"{key}{_WORKSPACE_SUFFIX}" def fold_legacy_shared_bucket(shared_key, st=None): """⭐⭐ W50-T23 — merge this topic's OTHER shared-bucket spelling into the canonical one. Idempotent, copy-forward, canonical-wins-a-collision, and it never deletes the legacy row. The decisions and their reasons live in `shared_overlay.fold_legacy_bucket`; this function owns only the SPELLING, so there is one reader of "which bucket is the stale one". """ canon = str(shared_key or "").strip() legacy = legacy_shared_key(canon) if not canon or not legacy: return {"fields": 0, "cells": 0} return shared_overlay.fold_legacy_bucket(legacy, canon, st=st) @_settings_transaction def migrate_legacy_fields(table_key, st=None, known_users=None, grant_topic=None, shared_key=None, workspace_document=None, shared_document=None, allow_write=False): """Promote legacy shared-looking custom fields into the shared field stratum. The operation is intentionally idempotent and copy-before-remove. A failed request can therefore leave a private shadow behind, but it cannot lose the creator's values. The next read retries the promotion and the shared definition wins. A caller that already captured the workspace document may lend that read-only snapshot to avoid reopening the same key. ⭐⭐ W50-T23 — AND IT NOW FOLDS THE LEGACY SHARED BUCKET FIRST. This function is the ONE mount point available for that: all three shared-field readers already call it with the right keys (`routes_customers.shared_fields`, `routes_tables._ut_shared_fields`, `modules.product_data.shared_fields`) and read the definitions immediately afterwards, so a fold that writes into the canonical bucket is picked up by that same read. Mounting it at each of those three call sites instead would be three readers of one rule. """ key = str(table_key or "").strip() grant_key = str(grant_topic or key).strip() shared_key = str(shared_key or key).strip() if not key or st is None: return {"promoted": 0, "normalized": 0, "reclassified": 0, "suppressed": 0, "purged": 0, "folded": 0} row_backend = _workspace_rows(st, key) if row_backend is not None: dropped = ('views', 'trash', 'folders', 'itemFolders') + (() if allow_write else ('overlays',)) workspace_document = _workspace_read(st, key, drop=dropped) if not allow_write: tombstones = _live_tombstones(workspace_document) for owner, workspace in workspace_document.items(): if owner in ('__shared__', '__assigned__'): continue for field_key, field in (workspace.get('fields') or {}).items(): if (field_key not in tombstones and _field_is_migratable(field) and stored_permissions(field, fallback='collaborative', known_users=known_users)['edit'] != 'personal'): from core.view_settings_rows import MigrationRequired raise MigrationRequired('legacy fields require explicit owner-row maintenance') return {"promoted": 0, "normalized": 0, "reclassified": 0, "suppressed": 0, "purged": 0, "folded": 0} if getattr(st, "schema_only", False): # The same migration decisions and grant classifier, over detached definitions only. # A pending copy-before-remove operation belongs to the full read door. fold_legacy_shared_bucket(shared_key, st=st) document = (workspace_document if isinstance(workspace_document, dict) else st.get_projection(key, drop=("overlays",))) shared = (shared_document if isinstance(shared_document, dict) else shared_overlay.document(shared_key, st=st)) tombstoned = _live_tombstones(document) for owner, workspace in (document or {}).items(): if owner == WORKSPACE_SHARED_MEMBER or not isinstance(workspace, dict): continue for field_key, original in (workspace.get("fields") or {}).items(): if (str(field_key) not in tombstoned and _field_is_migratable(original) and stored_permissions(original, fallback="collaborative", known_users=known_users)["edit"] != "personal"): raise shared_overlay.SchemaUnavailable( 'field definitions need a full workspace refresh to finish migration') reclassified = reconcile_shared_permissions( shared_key, grant_key, st=st, shared_document=shared) for dead in tombstoned: (shared.get("fields") or {}).pop(dead, None) return {"promoted": 0, "normalized": 0, "reclassified": reclassified, "suppressed": 0, "purged": 0, "folded": 0} # ⭐⭐ W50-T23 — THE FOLD RUNS BEFORE THE RECONCILE, AND THE ORDER IS THE POINT. A definition # that arrives from the legacy bucket must be classified by the same pass that classifies # every other one; folding after the reconcile would leave the newcomer unreconciled until # the NEXT read, which is a whole request serving a column with no permission word. # # ⛔ ITS OWN SWALLOWING GUARD, for the blast-radius reason the reconcile block states below: # `routes_customers.shared_fields` degrades a raise in here to `{}`, i.e. EVERY shared column # on the customer grid disappears and reads as "nothing is shared yet". try: folded = fold_legacy_shared_bucket(shared_key, st=st) folded_count = int(folded.get("fields") or 0) + int(folded.get("cells") or 0) if folded_count and isinstance(shared_document, dict): # ⚠ THE LENT SNAPSHOT IS NOW STALE AND MUST BE REFRESHED IN PLACE. Every reader below # (and the caller that lent it) resolves definitions off this dict, so a fold the # snapshot cannot see is a column that stays invisible for exactly the request that # migrated it — the failure this whole ticket is about, reintroduced by a cache. fresh = shared_overlay.document(shared_key, st=st) shared_document["fields"] = fresh.get("fields") or {} shared_document["cells"] = fresh.get("cells") or {} except Exception: # noqa: BLE001 folded_count = 0 # ⭐⭐ W40-T03 — RECONCILE THE SHARED STRATUM'S CLASSIFICATION FIRST, IN ITS OWN SWALLOWING # GUARD. This is the ONE seam that reaches every shared-field surface: all three readers # (`routes_customers.shared_fields`, `routes_tables._ut_shared_fields`, # `product_data`) already call this function with the right keys and read the definitions # immediately afterwards, so a reconcile that writes into the shared overlay is picked up by # that same read. # # ⛔ THE GUARD IS NOT DEFENSIVENESS, IT IS A BLAST RADIUS. `routes_customers.shared_fields` # wraps its whole call in a `try/except` that degrades to `{}` — i.e. a raise in here would # blank EVERY shared column on the customer grid and read as "nothing is shared yet". A # classification that fails must leave the previous word on screen, never the page empty. # # ⚠ THE TWO KEYS ARE DIFFERENT STRINGS AND THE ORDER MATTERS. `shared_key` names the BUCKET # (`product_table_workspace__shared`); `grant_key` names the registry TOPIC # (`product_data:`). For the product topic they are not the same value. Swapping them # finds no grant record, the "no record" arm fires for every column, and the reconcile # silently does nothing at all. try: reclassified = reconcile_shared_permissions( shared_key, grant_key, st=st, shared_document=shared_document) except Exception: reclassified = 0 # W44 predecessor replay: a table assembly has already read this exact document through # `TableStore.workspace(..., include_document=True)`. Reopening it here paid a third whole # `_table_workspace` copy for the same rows request. Accept that captured snapshot when # supplied; every historical/cold caller still takes the original `st.get(key)` path. # # A non-dict is NOT treated as an empty captured document. It falls back to the store so a # malformed optional argument cannot suppress an existing migration by manufacturing `{}`. if isinstance(workspace_document, dict): document = workspace_document else: try: document = st.get(key) or {} except Exception: return {"promoted": 0, "normalized": 0, "reclassified": reclassified, "suppressed": 0, "purged": 0, "folded": folded_count} if not isinstance(document, dict): return {"promoted": 0, "normalized": 0, "reclassified": reclassified, "suppressed": 0, "purged": 0, "folded": folded_count} promoted = 0 normalized = 0 suppressed = 0 remove = {} # ⭐⭐ W41-T07 — THE FIFTH LEG, READ FOR FREE OFF THE DOCUMENT ALREADY IN HAND. A key deleted # inside the window is not promotable, no matter which account still holds a fork of it. tombstoned = _live_tombstones(document) for owner, workspace in document.items(): if owner == WORKSPACE_SHARED_MEMBER or not isinstance(workspace, dict): continue fields = workspace.get("fields") or {} if not isinstance(fields, dict): continue for field_key, original in list(fields.items()): if not _field_is_migratable(original): continue if str(field_key) in tombstoned: # ⛔ SKIP, NEVER SWEEP. The delete already took every fork it could see; anything # here now either arrived after it or survived a partial failure, and destroying # somebody's column to tidy up is the one mistake with no undo — this store keeps # no history ([[a-cleanup-deletes-what-it-did-not-create]]). Suppressing the # PROMOTION is enough: the fork stays private and visible to its holder, and the # tenant-wide resurrection the owner reported three times does not happen. suppressed += 1 continue permissions = stored_permissions(original, fallback="collaborative", known_users=known_users) if permissions["edit"] == "personal": if original.get("permissions") != permissions: def _stamp(data, owner=owner, field_key=field_key, permissions=permissions): ws = data.get(owner) or {} field = (ws.get("fields") or {}).get(field_key) if isinstance(field, dict): field["permissions"] = permissions return data _workspace_update(st, key, _stamp, owners=(owner,)) normalized += 1 continue existing = shared_overlay.fields( shared_key, st=st, document=shared_document).get(field_key) if isinstance(existing, dict): # A completed promotion is authoritative. Remove a duplicate personal copy # only when it has the same creator; a collision from another owner fails closed. if str(existing.get("createdBy") or "").lower() != str(original.get("createdBy") or owner).lower(): continue shared = existing else: shared = dict(original) shared.update({"shared": True, "granted": True, "permissions": permissions, "createdBy": original.get("createdBy") or owner, "source": "overlay", "custom": True}) shared_overlay.put_field(shared_key, field_key, shared, st=st) if isinstance(shared_document, dict): shared_document.setdefault("fields", {})[field_key] = dict(shared) promoted += 1 rows = {} overlays = workspace.get("overlays") or {} if isinstance(overlays, dict): for pid, values in overlays.items(): if isinstance(values, dict) and field_key in values: rows[str(pid)] = {field_key: values[field_key]} if rows: shared_overlay.put_rows(shared_key, rows, st=st) shares.set_grants("field", shares.field_oid(grant_key, field_key), grant_entries(permissions), owner=str(shared.get("createdBy") or owner), st=st) remove.setdefault(owner, set()).add(field_key) if remove: def _remove(data): for owner, keys in remove.items(): ws = data.get(owner) or {} field_defs = ws.get("fields") or {} overlays = ws.get("overlays") or {} for field_key in keys: field_defs.pop(field_key, None) if isinstance(overlays, dict): for values in overlays.values(): if isinstance(values, dict): values.pop(field_key, None) return data _workspace_update(st, key, _remove, owners=tuple(remove)) # ⭐⭐ W41-T07 — AND A SHARED DEFINITION THAT CAME BACK INSIDE THE WINDOW IS DROPPED AGAIN. # # ⛔ THIS IS THE LEG THAT MAKES A PARTIAL DELETE HEAL FORWARD, and it is why # `delete_field_everywhere` sweeps the forks BEFORE it drops the shared definition. If the # sweep and the tombstone land and the `shared_overlay.drop_field` after them does not, the # definition would otherwise survive and be re-merged onto every grid forever. With this leg # the next read finishes the delete instead. It also closes the concurrency window: a read # that snapshotted the forks before the sweep can still write the promotion after it, and # nothing else would ever take that resurrection away. # # ⚠ IT COSTS A READ OF THE SHARED BUCKET, AND ONLY WHEN A TOMBSTONE IS LIVE. Steady state is # an empty book and this whole block is skipped, so the hot read path is unchanged; the cost # is bounded to the `TOMBSTONE_TTL_S` window after somebody deletes a column. purged = 0 if tombstoned: try: live = shared_overlay.fields(shared_key, st=st, document=shared_document) except Exception: # noqa: BLE001 live = {} for dead in tombstoned: if dead not in live: continue try: if shared_overlay.drop_field(shared_key, dead, st=st): purged += 1 except Exception: # noqa: BLE001 continue # ⛔ `promoted` AND `normalized` KEEP THEIR NAMES AND THEIR MEANINGS. # `aios-web/api/verify_field_permissions.py` asserts `result["promoted"] == 1`; renaming or # folding either into the new count would turn a green gate red for a change it never made. # ⚠ `suppressed` and `purged` are ADDED beside them for the same reason: a caller that reads # the old two keeps reading exactly what it read before. return {"promoted": promoted, "normalized": normalized, "reclassified": reclassified, "suppressed": suppressed, "purged": purged, "folded": folded_count} @_settings_transaction def promote_field(workspace_key, shared_key, grant_topic, owner, field, st=None): """Move one personal field and its values into the shared stratum.""" owner = str(owner or "").strip().lower() key = str(field.get("key") or "").strip() if not owner or not key or st is None: return dict(field) shared = dict(field) shared.update({"shared": True, "granted": True, "source": "overlay", "custom": True}) # ⭐⭐ W40-T03 / OWNER INSTRUCTION 21 — THE FALLBACK IS `personal`, AND IT IS THE ROOT CAUSE. # # Owner: *"By default every Field created is private until it is shared."* # # ⛔ THE BUG WAS AN ORDERING ONE, WHICH IS WHY IT LOOKED LIKE THE OPPOSITE OF ITSELF. # `routes_shares.put_share` promotes FIRST and writes the request's own grant entries one line # LATER, so on a first share this function cannot see who the field is being shared with. With # `fallback="collaborative"` it therefore stamped `{'edit': 'collaborative'}` on EVERY first # share — Karen-only included — and the bag was never re-derived afterwards. `set_grants` # immediately replaced the transient `*` grant with Karen's, so the WALL was right the whole # time; the permanent lie was the WORD, and the word is what the owner reads under Hide fields. # # ⛔ AN EXPLICIT BAG STILL WINS, AND THAT IS WHAT KEEPS THE OTHER CALLER BYTE-IDENTICAL. # `grid_events.field_upsert` (the field editor's permission picker) sets # `field['permissions']` in BOTH arms of its `may_change_permissions` branch before calling # this, and only reaches it when that bag already says `collaborative` or `users`. The # fallback is never consulted there, so this line moves nothing on that path. # # ⚠ THE CALL SITE CHANGES, NOT `stored_permissions`' OWN DEFAULT. That default answers a # different question — *"what did an old field, written before this vocabulary existed, # mean?"* — and `migrate_legacy_fields` still needs the old answer for its LEGACY promotion # leg, which `verify_field_permissions.py` asserts to the letter. # # ⚠ `set_grants` BELOW IS LEFT IN PLACE. With `personal` it writes `[]` plus an owner, which is # the shape `routes_customers.py`'s route claim states in full: *"the empty entry list is the # point. `set_grants` keeps a record with an owner and no entries, so 'shared with nobody' is # STORED and is a different fact from 'never shared'."* `reconcile_shared_permissions` reads # exactly that difference, so dropping the call would make a freshly promoted column # unclassifiable rather than private. permissions = stored_permissions(shared, fallback="personal") shared["permissions"] = permissions shared["createdBy"] = str(shared.get("createdBy") or owner).strip().lower() shared_overlay.put_field(shared_key, key, shared, st=st) document = _workspace_read(st, workspace_key, owners=(owner,)) or {} workspace = document.get(owner) if isinstance(document, dict) else {} rows = {} for pid, values in ((workspace or {}).get("overlays") or {}).items(): if isinstance(values, dict) and key in values: rows[str(pid)] = {key: values[key]} if rows: shared_overlay.put_rows(shared_key, rows, st=st) shares.set_grants("field", shares.field_oid(grant_topic, key), grant_entries(permissions), owner=shared["createdBy"], st=st) def _remove(data): ws = data.get(owner) or {} (ws.get("fields") or {}).pop(key, None) for values in (ws.get("overlays") or {}).values(): if isinstance(values, dict): values.pop(key, None) # ⭐⭐ W41-T07 — AN EXPLICIT SHARE RETIRES THE TOMBSTONE, AND THIS LINE IS THE WHOLE # ANTI-LEAK ARGUMENT FOR HAVING ONE. `delete_field_everywhere` suppresses the IMPLICIT # legacy promotion of a deleted key; this function is the EXPLICIT one, reached from # `routes_shares.put_share`, i.e. a person saying in as many words that this column is # meant to exist and be shared. There is nothing left to be careful about after that, so # the suppression ends immediately rather than waiting out `TOMBSTONE_TTL_S`. _retire_tombstone(data, key) return data _workspace_update(st, workspace_key, _remove, owners=(owner, WORKSPACE_SHARED_MEMBER)) return shared @_settings_transaction def demote_field(workspace_key, shared_key, grant_topic, field, st=None): """Move one shared field back to its creator's personal workspace.""" if not isinstance(field, dict) or st is None: return dict(field or {}) key = str(field.get("key") or "").strip() owner = str(field.get("createdBy") or "").strip().lower() if not key or not owner: return dict(field) personal = dict(field) personal.pop("shared", None) personal.pop("granted", None) personal["permissions"] = {"edit": "personal"} personal["createdBy"] = owner shared_values = shared_overlay._read(shared_key, st=st).get("cells") or {} def _add(data): ws = data.setdefault(owner, {}) ws.setdefault("fields", {})[key] = personal overlays = ws.setdefault("overlays", {}) for pid, values in shared_values.items(): if isinstance(values, dict) and key in values: overlays.setdefault(str(pid), {})[key] = values[key] return data _workspace_update(st, workspace_key, _add, owners=(owner,)) shared_overlay.drop_field(shared_key, key, st=st) shares.drop_objects([("field", shares.field_oid(grant_topic, key))], st=st) return personal @_settings_transaction def delete_field_everywhere(workspace_key, shared_key, grant_topic, field_key, st=None): """⭐⭐ W41-T07 / OWNER INSTRUCTION 21 — **DELETE ONE COLUMN FROM EVERY STRATUM THAT HOLDS IT.** Owner: *"Deleting a field from Hide fields does not stick; 'August Campaign' on Odoo customer has reappeared three times."* It reappeared because no door had ever deleted it. Returns a per-leg report; it decides no rights and refuses nobody. ⛔⛔ THE RIGHT IS ANSWERED BEFORE THIS IS REACHED, AND IT IS NOT ANSWERED AGAIN HERE. `user_tables.may_delete_field` / `delete_field_refusal` are C2's one pair, and C2's last sentence is *"No surface re-implements either test"* — a module that both decided and executed would be the second implementation. This is the EXECUTION half, on purpose. **THE FIVE LEGS, and which line closes each:** 1. the deleter's own per-user stratum -> `_purge_forks` (their member of the document) 2. `shared_overlay`'s bucket -> `shared_overlay.drop_field`, the RIGHT document 3. the re-merge onto the next fetch -> leg 2; `_merge_shared_fields` and `_ut_shared_fields` project what is in the bucket, so a definition that is gone cannot be re-injected 4. the grant record -> `shares.drop_objects` 5. every OTHER account's fork -> `_purge_forks` (all members) + `_stamp_tombstone` ⛔ LEG 5 IS THE ONE THAT BITES, AND `drop_field` ALONE IS NOT ENOUGH — measured in-process before this was written. `migrate_legacy_fields` runs on EVERY read and walks EVERY member of the workspace document, so one fork left in one colleague's stratum re-promotes the column into the shared bucket on the next page load. Deleting the shared definition without sweeping the forks buys exactly one render. ⛔ THE ORDER IS SWEEP-THEN-DROP AND IT IS LOAD-BEARING, not stylistic. The sweep and the tombstone land in ONE transaction on the workspace document; only then is the shared definition dropped. So a failure of the second half leaves a live tombstone, and the next read's `migrate_legacy_fields` finishes the delete instead of re-merging the survivor forever. The other order (drop first, sweep second) fails the opposite way: the definition is gone, the forks are not, and the very next read puts it back with nothing recording that anyone objected. ⚠ THE `__shared__.fields` COLUMN SUMMARY GOES TOO, for `table_store.delete_field`'s own stated reason: *"an orphan `agg` under a deleted key is state nobody can see and nobody can clear, and it would attach itself to the next column that happens to take the key back."* """ key = str(field_key or "").strip() ws_key = str(workspace_key or "").strip() bucket = str(shared_key or "").strip() topic = str(grant_topic or bucket or "").strip() report = {"key": key, "personal": 0, "owners": [], "shared": False, "grants": False, "tombstoned": False} if not key or st is None: return report now = int(time.time()) if ws_key: hit = {"owners": []} def _purge(data): data = data if isinstance(data, dict) else {} hit["owners"] = _purge_forks(data, key) member = data.setdefault(WORKSPACE_SHARED_MEMBER, {}) if isinstance(member, dict): annotations = member.get("fields") if isinstance(annotations, dict): annotations.pop(key, None) _stamp_tombstone(member, key, now) return data # ⛔ `flush='sync'`, matching every other STRUCTURAL write in this module. A delete the # user has confirmed must not be the thing that is still coalescing when the process dies; # `shared_overlay._write`'s own note draws the same line ("a lost column definition is a # worse failure than a lost keystroke") and a lost DELETION is worse again, because the # column comes back and the person deletes it a fourth time. _workspace_update(st, ws_key, _purge) report["owners"] = list(hit["owners"]) report["personal"] = len(hit["owners"]) report["tombstoned"] = True if bucket: report["shared"] = bool(shared_overlay.drop_field(bucket, key, st=st)) if topic: # ⚠ GUARDED, AND THE TOLERANCE IS `routes_tables.delete_shared_field`'s ALREADY: the column # and its values are gone by now, so a registry hiccup must not turn a completed delete # into a 500 that invites the client to repeat it. A surviving grant record is inert # (`shares.role_for` resolves against an object that no longer exists) and is overwritten # by the next `set_grants` on the same id. try: shares.drop_objects([("field", shares.field_oid(topic, key))], st=st) report["grants"] = True except Exception: # noqa: BLE001 report["grants"] = False return report