runloopable / platform /aios_grid.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
8729c1d verified
Raw History Blame Contribute Delete
233 kB
"""aios_grid β€” embed the AIOS React/glide Airtable-style grid inside Streamlit. This is REUSABLE MODULE INFRASTRUCTURE: the same self-contained grid that runs as the standalone aios-web app is inlined into a single HTML file and hosted inside a Streamlit component. The React bundle reads its data from `window.__AIOS_GRID__` (an object `{fields, rows}`) that we inject into the page <head> before the app's module script runs β€” so there is NO backend and NO /api call in the Streamlit container; the browser only ever sees the derived JSON we hand it. Usage (from any page): import aios_grid aios_grid.render(aios_grid.rows_from_pool(pool_rows), aios_grid.FIELDS) Design notes: * ZERO app-internal imports (no `modules.*` / `core.*`). FIELDS is a literal and `rows_from_pool` takes already-built rows β€” so this helper is tenant/module-agnostic and sidesteps deploy_hf.py's import guard entirely. * The built HTML ships as `aios_grid_embed.html` in THIS directory (added to deploy_hf.py INCLUDE). Build it with `npm run build:embed` in aios-web/web, then copy dist-embed/index.html -> platform/aios_grid_embed.html (see build_embed.py). For LOCAL dev before that copy, we fall back to reading dist-embed/index.html directly. * The preferred host is a Streamlit Components v1 bridge. It sends data/view/schema args into the React app and returns guarded events for persistence in the tenant store. The old injected-HTML path remains a read/local-write fallback when component assets are absent. """ import datetime as _dt import copy import json import math import re from decimal import Decimal, ROUND_HALF_EVEN, localcontext from pathlib import Path _HERE = Path(__file__).resolve().parent # Where the inlined single-file build lives. FIRST match wins: # 1. the shipped copy in this dir (what deploy_hf.py uploads to the Space) # 2. the raw build output in the sibling aios-web tree (local dev, pre-copy) _EMBED_CANDIDATES = [ _HERE / "aios_grid_embed.html", _HERE.parent / "aios-web" / "web" / "dist-embed" / "index.html", ] _COMPONENT_CANDIDATES = [ _HERE / "aios_grid_component", _HERE.parent / "aios-web" / "web" / "dist-embed", ] _DECLARED_COMPONENTS = {} # --- the FIELD CONTRACT β€” loaded from the CANONICAL source `aios_grid_fields.json` in THIS # directory (the SINGLE source of truth, shared with aios-web/api/main.py). source='odoo' is # READ-ONLY; source='overlay' is the editable stratum (notes/tags) that lives OUTSIDE Odoo. # # Why a sibling JSON and NOT an import: aios_grid.py's contract is ZERO app-internal imports so # it stays tenant/module-agnostic and sidesteps deploy_hf.py's import guard. A JSON next to the # module preserves that exactly β€” no import, no guard interaction β€” while still single-sourcing # the values (a build-time copy from another tree would reintroduce the drift we're removing). # The file ships to the Space via deploy_hf.py INCLUDE. Edit the JSON, then run # aios-web/verify_fields_contract.py. --- _FIELDS_PATH = _HERE / "aios_grid_fields.json" def _load_fields(): if not _FIELDS_PATH.is_file(): raise FileNotFoundError( f"aios_grid: canonical field contract missing at {_FIELDS_PATH}. It is the single " "source of truth for the grid schema and MUST ship (deploy_hf.py INCLUDE lists it)." ) doc = json.loads(_FIELDS_PATH.read_text(encoding="utf-8")) fields = doc.get("fields") if isinstance(doc, dict) else doc if not isinstance(fields, list) or not fields: raise ValueError(f"aios_grid: {_FIELDS_PATH} has no 'fields' list.") return fields FIELDS = _load_fields() def product_fields(): """The PRODUCT table's canonical contract (wave 15 C-TOPIC, `product_data` key in the same JSON). A separate accessor rather than a second module constant so the one file-read and the one failure mode stay shared with `FIELDS`.""" doc = json.loads(_FIELDS_PATH.read_text(encoding="utf-8")) fields = (doc.get("product_data") or {}).get("fields") if not isinstance(fields, list) or not fields: raise ValueError(f"aios_grid: {_FIELDS_PATH} has no product_data.fields list.") return fields # text/date fields pass through untouched; every OTHER odoo (numeric) field is rounded β€” # mirrors aios-web/api/main.py _payload() exactly so embed == standalone byte-for-byte. def _round(v): return round(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else v def _round2(v): """D-153 (W37, asked by lane B) β€” MONEY AND PERCENT KEEP THEIR DECIMALS. `_round`'s whole-number convention is right for counts and wrong for currency: `first_cost` 3.47 shipped as `3`, so every money cell on every Odoo grid was a whole dollar. ⚠ `pct` IS AFFECTED TOO, and that is the half most likely to be dropped. `cells.ts` renders a percent as `num(v).toFixed(1) + "%"`, so a `yoy_pct` of 12.34 was `round()`ed to 12 and painted "12.0%" β€” one decimal of a number that HAS one, which reads as precision rather than as loss. β›” NOT written as a `_round(v, nd=0)` default argument, deliberately: `round(v, 0)` returns a FLOAT where `round(v)` returns an INT, so every integer column's wire shape would change under an edit that looks purely cosmetic. """ if not isinstance(v, (int, float)) or isinstance(v, bool): return v if not math.isfinite(v): return v # `round(12.345, 2)` is 12.35 because its binary float is just above the decimal tie, while # DuckDB's `round_even(..., 2)` (the filter and sort expression) correctly yields 12.34. # Quantizing the user-visible decimal spelling preserves banker's rounding at cents in both # engines. Keep an int an int: a currency value can be integral without changing its wire type. decimal = Decimal(str(v)) # Decimal's default precision is 28 digits; keep the prior `round` behavior for an unusual # but valid large finite float instead of making it an InvalidOperation at the payload edge. with localcontext() as context: context.prec = max(context.prec, decimal.adjusted() + 3) rounded = decimal.quantize(Decimal("0.01"), rounding=ROUND_HALF_EVEN) return int(rounded) if isinstance(v, int) else float(rounded) # Types a USER may create from the column menu (owner item 7, 2026-07-26). Mirrors # customer-grid/types.ts CREATABLE_TYPES; verify_fields_contract.py holds the two in step. # select β€” a single-select with its own `options` (the "Status" a user wants to add; distinct # from the Odoo-sourced `status` lifecycle, which is not user-defined) # user β€” an assignee, whose choices come from the HOST's real user list, never from here #: `multiselect` (wave-2 item 5, 2026-07-27): the Airtable-style MULTI select β€” declared #: options like `select`, but the cell holds a comma-joined SET and the row belongs to every #: member of it (the `multi` grouping/cell contract the Cohorts column established). #: Wave-5 item 11 (2026-07-27): `checkbox` (cell = bool; the overlay stores '1' or '') Β· #: `phone` / `email` / `url` (text-family with per-type rendering) Β· `rating` (top-level #: `max`, SVG stars client-side β€” never emoji) Β· `created_time` (READ-ONLY, renders the row's #: `_created`) Β· `formula` (READ-ONLY, client-computed from the row's other cells). #: ⭐ Wave-19 R7 / contract C5: `image` β€” a PICTURE on a record. The cell holds a string #: REFERENCE, never bytes: a product `code`, an `ed:<slug>` editorial asset, or `rec:<id>` for #: something uploaded through the field (`POST /api/v1/assets/records`). Storing a reference is #: what lets Royal's 1,142 existing SKU masters appear with nothing re-uploaded, and it keeps the #: overlay stratum the size it is β€” base64 bytes in a JSON blob read on every render would be a #: megabyte-per-row tax on the whole store. Editable by NATURE (deliberately NOT in #: `READONLY_CUSTOM_TYPES`): the ref is what the upload endpoint hands back, and the client PATCHes #: it through the ordinary overlay wall rather than the asset route writing cells behind it. #: ⭐ WAVE 23 (C7) β€” `json` joined: a cell holding a whole DOCUMENT (an Instagram comment thread, #: a webhook payload, a scraped blob) that opens in its own viewer instead of being flattened #: into one unreadable line. It is EDITABLE by nature, like `image`: the value is still a plain #: string on the wire, so it rides the ordinary overlay wall β€” what makes it a json field is that #: `grid_events` REFUSES a write that does not parse (a column promising structure must not #: silently hold something that isn't). #: ⭐ 2026-08-07 β€” `link` and `rollup` JOINED (the relational wave). They ride here because #: `UT_FIELD_TYPES` must stay a SUBSET of this set (gated in verify_api's W18-UT section) β€” the #: surfaces that CREATE them are the user-table databases, where a relation between two tables is #: a thing that exists. On the Odoo-backed Customer/Product grids there is no second user table to #: point at, so the column menu there simply never offers one. #: ⭐⭐ WAVE-34 (owner ruling R13) β€” `ai_enrich` JOINS, and it had to join HERE in the same change #: that put it in `UT_FIELD_TYPES`, not a ticket later. The wave planned a SERVER-FIRST landing on #: the reasoning that a kind the client does not offer is invisible while a kind the server refuses #: deletes a column. That reasoning is sound and the conclusion was still wrong, because THREE #: parity gates chain over these sets and none of them permits a partial landing: #: `verify_api` W18-UT `UT_FIELD_TYPES - CUSTOM_FIELD_TYPES == set()` (this line) #: `aw_fields_contract` Β§5 `CREATABLE_TYPES == CUSTOM_FIELD_TYPES`, EXACT set equality #: `types.ts` `CREATABLE_TYPES: readonly FieldType[]`, so the union must carry it too #: Measured live by lane B at 17:09: `api_api` went 969/969 to 968/969 the moment the kind entered #: `core/user_tables.py` alone, printing `got {'ai_enrich'} want set()`. The comments on #: `json`, `link`/`rollup` and `code` below all say the same thing in their own words. CUSTOM_FIELD_TYPES = {"text", "long_text", "select", "multiselect", "user", "int", "currency", "pct", "date", "checkbox", "phone", "email", "url", "rating", "created_time", "formula", "automation", "image", "json", "link", "rollup", "code", "ai_enrich", "if", "autonumber", "created_by", "last_modified_time", "last_modified_by", "chart"} #: ⭐ WAVE-27 item 13 (owner ruling R13) β€” the `code` field's LANGUAGES. #: #: R13 is explicit that this kind is "syntax-highlighted storage + language config, NO execution #: engine". So a language is a RENDERING hint and nothing else: it selects a highlighter, it never #: selects an interpreter, and no value here may ever grow a run path. The list is short on #: purpose β€” every entry costs a highlighter the client actually has to implement, and an #: unimplemented language would paint plain text under a label promising colour. #: #: `plain` is the default and the fallback, so it is never a second way to say nothing: it is the #: honest answer for a snippet whose language the user has not chosen. CODE_LANGUAGES = {"plain", "json", "sql", "python", "javascript", "typescript", "html", "css", "markdown", "yaml", "xml", "shell"} def _clean_code(raw): """The `code` field's config bag -> `{'language': ...}`, or None. Deliberately OPTIONAL rather than required (the `automation` posture, not `link`'s): a code column with no declared language is a legitimate state β€” it stores and highlights as plain text β€” so refusing the FIELD over a missing bag would block the ordinary create path. An unknown language falls back to `plain` rather than refusing, because the value is a rendering hint: dropping the user's column to punish a typo in a highlighter name would be the disproportionate half of the fail-closed rule. ⚠ `plain` RETURNS NONE, and that is what makes the control reversible rather than one-way. Absent already means plain, so storing `{'language': 'plain'}` would be the default wearing a second name (the `kanbanClamp` law). But the patch path resolves an OMITTED key to the previous value β€” so if plain were merely omitted by the client, switching a column back from SQL to Plain text would keep storing SQL and read as a control that does not save. Sending the bag explicitly and having it evaluate to None here means: omit = keep, plain = clear. """ if not isinstance(raw, dict): return None lang = str(raw.get('language') or 'plain').strip().lower() if lang not in CODE_LANGUAGES or lang == 'plain': return None return {'language': lang} #: User-created types whose CELLS are read-only: their values are computed (formula β€” client #: side, any error degrades to BLANK) or system-owned (created_time = the row's `_created`). #: Emitted with the cohort column's read-only mechanism β€” `source: 'odoo'` + `derived` β€” so #: the client never offers an editor and the host never accepts a cell write for them. READONLY_CUSTOM_TYPES = {"created_time", "formula", "if", "autonumber", "created_by", "last_modified_time", "last_modified_by", "chart"} # Mirrored server persistence ceiling. ``core.route_system.MAX_OPTIONS`` owns what is published # to clients; the focused contract gate keeps this import-free helper equal to that value. MAX_FIELD_OPTIONS = 200 MAX_FORMULA_LEN = 500 #: `rating` bounds. Airtable caps at 10; below 2 a rating is a checkbox. RATING_MAX_DEFAULT, RATING_MAX_MIN, RATING_MAX_MAX = 5, 2, 10 #: Key prefix of a FORMULA-MEASURE column (owner item 7, 2026-07-27): a user-created field that #: IS a measure over a window β€” `Sales Β· the last 90 days` as a column. Mirrors the client's #: `measure_` keys in CustomerGrid.createField. Distinct from `custom_` because the two strata #: could not be more different: `custom_` is the EDITABLE overlay (user-typed values), while a #: measure field is READ-ONLY and its values are computed by the host per render. MEASURE_FIELD_PREFIX = "measure_" #: The numeric types a measure can render as (semantic._FORMAT_TYPE's range). MEASURE_FIELD_TYPES = {"currency", "int", "pct"} class OptionLimitExceeded(ValueError): """A choice vocabulary cannot be represented without discarding entered values.""" def __init__(self, entered): self.entered = int(entered) self.limit = MAX_FIELD_OPTIONS self.rejected = max(0, self.entered - self.limit) super().__init__( f"This list has {self.entered} choices; the server limit is {self.limit}, so " f"{self.rejected} would be rejected. Remove {self.rejected} choices, then save." ) def _clean_options(raw): """Choices for a `select`: strings, trimmed, de-duplicated case-insensitively, capped. Mirrors types.ts parseOptions β€” a choice list that means one thing in the picker and another in the filter dropdown is a column with two vocabularies.""" out, seen = [], set() for v in list(raw or []): if not isinstance(v, (str, int, float)) or isinstance(v, bool): continue s = str(v).strip()[:120] if not s or s.lower() in seen: continue seen.add(s.lower()) out.append(s) if len(out) > MAX_FIELD_OPTIONS: raise OptionLimitExceeded(len(out)) return out def merge_choice_options(*sources): """One canonical choice vocabulary from ordered option sources. A source-backed column may learn values through an overlay while retaining contract choices. Keeping the merge beside `_clean_options` makes the case-folding, 120-character label, and `MAX_FIELD_OPTIONS` rules identical on the persistence and payload paths. The first spelling wins: a later ``et`` therefore resolves to an existing ``ET`` rather than producing a second visibly identical choice. """ merged = [] for source in sources: merged.extend(list(source or [])) return _clean_options(merged) def _choice_values_from_cell(field, value): """The individual labels represented by one select-family cell value.""" if not isinstance(field, dict) or field.get("type") not in ("select", "multiselect"): return [] raw_values = (str(value or "").split(",") if field.get("type") == "multiselect" else [value]) return _clean_options(raw_values) def hydrate_choice_options_from_rows(fields, rows, ignored_by_field=None): """Return field copies whose choice vocabularies include their served cell values. A field may already contain real values from an import or a read-time source default before anybody edits it through ``grid_events``. Those values are still choices: omitting them makes the picker claim that a populated select has no options. This is a read projection, deliberately; it cannot write a value a caller is not permitted to read into tenant schema. """ row_maps = [row for row in (rows or ()) if isinstance(row, dict)] ignored = {} for key, raw_values in (ignored_by_field or {}).items(): values = [raw_values] if isinstance(raw_values, (str, int, float)) else raw_values ignored[str(key)] = {str(value).strip().casefold() for value in (values or ()) if str(value).strip()} out = [] for raw in fields or (): field = dict(raw) if isinstance(raw, dict) else raw if not isinstance(field, dict) or field.get("type") not in ("select", "multiselect"): out.append(field) continue key = str(field.get("key") or "") values = [] for row in row_maps: if key not in row: continue values.extend(value for value in _choice_values_from_cell(field, row.get(key)) if value.casefold() not in ignored.get(key, set())) if values: field["options"] = merge_choice_options(field.get("options"), values) out.append(field) return out def apply_choice_overrides(fields, overrides): """Return field copies with durable select-family definition overrides applied. `overrides` is deliberately only a field-key map, so a product route can use the tenant-wide shared schema and a normal table workspace can use its personal source-column annotations. It never changes a non-choice field, and it never replaces canonical choices with a stale annotation: both vocabularies are merged through the one cleaner above. Product's shared spreadsheet columns also carry their Administrator-authored label and note here, so a definition save is visible on the same field projection that supplies the picker. """ saved = overrides if isinstance(overrides, dict) else {} out = [] for raw in fields or []: field = dict(raw) if isinstance(raw, dict) else raw if not isinstance(field, dict) or field.get("type") not in ("select", "multiselect"): out.append(field) continue extra = saved.get(field.get("key")) if not isinstance(extra, dict): out.append(field) continue # A Product spreadsheet choice becomes an ordinary shared definition on its first save. # The product API serves the canonical declaration as the base field, so carry the # definition's custody stamp across this overlay too; without it a fresh field payload # says the field is shared but cannot say who created the editable definition. if isinstance(extra.get("createdBy"), str) and extra["createdBy"].strip(): field["createdBy"] = extra["createdBy"].strip() if isinstance(extra.get("label"), str) and extra["label"].strip(): field["label"] = extra["label"].strip()[:120] if isinstance(extra.get("note"), str): field["note"] = extra["note"][:2000] fmt = _clean_format(extra.get("format"), field.get("type")) if fmt: field["format"] = fmt if "options" in extra: options = merge_choice_options(field.get("options"), extra.get("options")) field["options"] = options field.update(_choice_appearance(extra, options)) out.append(field) return out def _clean_option_colors(raw, options): """Choice-label -> #RRGGBB, limited to the field's canonical option vocabulary.""" if not isinstance(raw, dict): return {} supplied = {} for label, color in raw.items(): if not isinstance(label, str) or not isinstance(color, str): continue clean = color.strip().upper() if re.fullmatch(r"#[0-9A-F]{6}", clean): supplied[label.strip().lower()] = clean out = {} for option in options or []: color = supplied.get(str(option).strip().lower()) if color: out[str(option)] = color return out def _choice_appearance(raw, options): """Validated select-family appearance. Absent colour toggle means legacy-on.""" if not isinstance(raw, dict): return {} out = {} if isinstance(raw.get("colorCodeOptions"), bool): out["colorCodeOptions"] = raw["colorCodeOptions"] colors = _clean_option_colors(raw.get("optionColors"), options) if colors: out["optionColors"] = colors return out def _clean_rating_max(raw): """A rating's star count, bounded. Anything unusable is the default, not a refusal β€” the field still holds its 1..max integers either way.""" try: return max(RATING_MAX_MIN, min(int(raw), RATING_MAX_MAX)) except (TypeError, ValueError): return RATING_MAX_DEFAULT #: The field types a number-style display format may apply to. `formula` is here because its #: RESULT is a number the client renders; `pct` already renders in points and takes decimals. #: `number` is an Odoo float column: its Decimals setting is display only, never the stored value. _NUMBER_FORMAT_TYPES = {"int", "currency", "pct", "formula", "number"} def _clean_format(raw, ftype): """Retain typed display options and the shared numeric write policy for field readback.""" if not isinstance(raw, dict): return None out = {} if ftype in _NUMBER_FORMAT_TYPES: if isinstance(raw.get("currencySymbol"), str) and raw["currencySymbol"] in ("$", "EUR", "GBP", "IDR", ""): out["currencySymbol"] = raw["currencySymbol"] if isinstance(raw.get("allowNegative"), bool): out["allowNegative"] = raw["allowNegative"] if isinstance(raw.get("thousands"), bool): out["thousands"] = raw["thousands"] if raw.get("decimals") is not None: try: d = int(raw["decimals"]) except (TypeError, ValueError): d = None if d is not None and 0 <= d <= 4: out["decimals"] = d if isinstance(raw.get("abbrev"), bool): out["abbrev"] = raw["abbrev"] elif ftype in ("date", "created_time", "last_modified_time"): if isinstance(raw.get("time"), bool): out["time"] = raw["time"] if raw.get("tz") in ("local", "utc"): out["tz"] = raw["tz"] from core.user_tables import _clean_format as clean_module_format display = clean_module_format(raw) or {} for key in ('display', 'pictureKey', 'subKey', 'labelKey', 'emptyLabel'): if key in display: out[key] = display[key] return out or None def _clean_permissions(raw): """Canonical field edit permissions; legacy values remain readable during migration.""" from core.field_permissions import clean_permissions if not isinstance(raw, dict): return None return clean_permissions(raw, fallback="personal") #: β›” THE CHARSET MUST ADMIT EVERY TOKEN THE CLIENT ENGINE PARSES, or a legal formula is #: refused by a wall that is supposed to be structural (2026-08-03). #: #: This regex was written when a formula was arithmetic over refs. On 2026-07-31 the client #: engine (owner item 2) gained STRING literals, `&` concatenation and `^` β€” CONCATENATE, TEXT, #: LEFT/RIGHT/MID, and any `IF(cond, "yes", "no")`. This list was never widened to match, so #: every such formula died here: `field_upsert` refused the create, and `fields_from_workspace` #: dropped the column on read. Nothing went red β€” a refused create looks like a quiet failure #: and a dropped column looks like a column nobody made. #: #: Found by trying to ship the owner's own Buy signal formula, which is `IF(..., "Buy now", #: "OK")` and could not be created through the product UI at all. #: #: ⚠ IT IS STILL STRUCTURAL, and deliberately not a second grammar β€” that is the filter_sql-class #: drift risk this file's docstring names. The charset says which characters may appear; the #: engine says what they mean. `_quotes_balanced` below is the one structural rule the quote #: character brings with it. #: WAVE 42 G7 (2026-08-25) -- THE SAME SCAR, WIDENED IN THE SAME CHANGE THIS TIME. #: #: The client engine gained REGEX_EXTRACT, REGEX_REPLACE, SUBSTITUTE, FIND, SWITCH, DATEADD, #: DATETIME_DIFF and DATETIME_FORMAT. Each added character below is admitted because a token #: the client's tokenizer parses would otherwise die here: #: #: ' a SINGLE-QUOTED literal. Airtable documents units and date formats that way. #: [ ] a regex character class, the commonest construct there is: "[0-9]+". #: | ? \\ : regex alternation, optional/non-capturing groups, and escapes. #: @ SUBSTITUTE/FIND over an email or URL. #: # $ % TEXT number formats already accepted by the client; `$` is also a regex anchor. #: #: `;` stays refused: no legal formula token needs a statement separator. #: #: β›” D-547: A CHARACTER FILTER, NOT A SAFETY BOUNDARY. `__import__("os")` passes it (word #: characters, parens, quotes). Such a source is inert because the ENGINE refuses it: the server #: parser door in `aios-web/api/formula_runtime.py` is an AST interpreter over a function allowlist #: with no Python eval. `api/verify_formula_storage.py` records both halves; never read this as the wall. _FORMULA_CHARS = re.compile(r"^[\w\s{}()+\-*/.,<>=!^&\"'\[\]|?:\\#$%@]*$") _FORMULA_REF = re.compile(r"\{([^{}]*)\}") #: Longest single regex-pattern literal. The client independently caps both pattern and subject. MAX_FORMULA_LITERAL_LEN = 200 #: Catastrophic-backtracking shape, applied to STRING LITERALS only. Applying this to the whole #: source would also match ordinary arithmetic such as `({a} + {b}) * 2`. _NESTED_QUANT = re.compile(r"\((?:[^()\\]|\\.)*[*+](?:[^()\\]|\\.)*\)\??\s*[*+]") def _string_literals(s): """Return literal bodies, or None for an unterminated quote. This mirrors the client tokenizer's structural rule: single and double quoted strings are equivalent, a doubled opening quote escapes itself, and the other quote kind is ordinary text. It assigns no formula meaning; it only locates literal boundaries. """ out = [] i = 0 n = len(s) while i < n: quote = s[i] if quote not in ('"', "'"): i += 1 continue j = i + 1 body = [] while True: if j >= n: return None if s[j] == quote: if j + 1 < n and s[j + 1] == quote: body.append(quote) j += 2 continue break body.append(s[j]) j += 1 out.append("".join(body)) i = j + 1 return out def _quotes_balanced(s): """Whether every single- or double-quoted literal is structurally closed. A parity count is not sound now that both spellings are legal: the double quote inside ``'5" pipe'`` is ordinary text, not an opener. The shared scanner answers exactly the same boundary question as the client tokenizer without assigning meaning to the literal. """ return _string_literals(s) is not None #: Wave-18 C5-AUTOFIELD. `kind` is a whitelist because an unknown kind would be a column that #: silently never runs; `source` names where the run's subject comes from. AUTOMATION_KINDS = {"instagram_profile"} AUTOMATION_SOURCES = {"record_url_field", "self"} MAX_AUTOMATION_SETTINGS = 12 def _clean_automation(raw, valid_keys=None, flow_ids=None): """Validate an `automation` config bag. Returns the clean dict, or None when there is nothing valid to store (the column then renders as unconfigured β€” never invented). β›” WAVE 22 (contract C8, owner item 5) β€” NO FIELD WITHOUT A FLOW. With `flow_ids` given (the WRITE path: grid_events / user_tables pass the tenant's automation-definition ids), the bag MUST carry a `flowId` naming one of them β€” absent or naming a deleted flow is refused, the same fail-closed direction as a formula ref that names no field. With `flow_ids=None` (the READ path, `fields_from_workspace`) the law is NOT applied: a column stored before the law must keep projecting β€” enforcement at read time would vaporise it, which is the `_clean_formula` write/read split exactly. """ if not isinstance(raw, dict): return None kind = str(raw.get('kind') or '').strip() if kind not in AUTOMATION_KINDS: return None source = str(raw.get('source') or 'record_url_field').strip() if source not in AUTOMATION_SOURCES: source = 'record_url_field' out = {'kind': kind, 'source': source} flow = str(raw.get('flowId') or '').strip()[:40] if flow_ids is not None and (not flow or flow not in flow_ids): return None if flow: out['flowId'] = flow url_field = str(raw.get('urlField') or '').strip()[:80] # fail closed on a ref that does not exist, exactly as _clean_formula does at WRITE time if url_field and (valid_keys is None or url_field in valid_keys): out['urlField'] = url_field settings = {} for k, v in list((raw.get('settings') or {}).items())[:MAX_AUTOMATION_SETTINGS]: if isinstance(v, bool) or isinstance(v, (int, float)): settings[str(k)[:40]] = v elif isinstance(v, str): settings[str(k)[:40]] = v[:200] if settings: out['settings'] = settings return out def _clean_formula(raw, valid_keys=None): """STRUCTURAL passthrough for a formula field's expression (wave-5 item 9). Meaning is NOT checked here: the CLIENT engine owns the grammar (arithmetic over `{field}` refs, ABS/ROUND/MIN/MAX/IF), and any evaluation error degrades to a BLANK cell β€” never a wrong number. That is the `_clean_window` split one stratum up, and deliberately NOT a Python mirror of the grammar: a second engine is the filter_sql-class drift risk. Structure IS checked β€” charset, length, balanced parens, BALANCED QUOTES, well-formed non-empty `{refs}` β€” and at WRITE time (`valid_keys` given) every ref must name a field this table has, fail closed. At READ time refs are left alone: a referenced field deleted later must blank the CELLS, not vaporise the column. ⚠ A `{ref}` INSIDE A STRING LITERAL is still checked against `valid_keys` at write time, so `IF(x, "see {notafield}", "")` is refused. That is a false rejection and it is the fail-closed direction: the alternative is teaching this function where strings begin and end, which is the second grammar the paragraph above refuses to write. """ if not isinstance(raw, str): return None s = raw.strip() if not s or len(s) > MAX_FORMULA_LEN or not _FORMULA_CHARS.match(s): return None depth = 0 for ch in s: if ch == "(": depth += 1 elif ch == ")": depth -= 1 if depth < 0: return None if depth: return None if not _quotes_balanced(s): return None # Regex patterns are user input reaching JavaScript's regex engine. The client owns the # load-bearing runtime bounds (pattern AND subject); this structural wall rejects an obvious # unsafe literal before it is stored. Run it on read too: literal shape is intrinsic and # cannot become invalid merely because the table's field set later changes. literals = _string_literals(s) if literals is None: return None regexy = 'REGEX_' in s.upper() for literal in literals: if regexy and len(literal) > MAX_FORMULA_LITERAL_LEN: return None if _NESTED_QUANT.search(literal): return None refs = _FORMULA_REF.findall(s) leftover = _FORMULA_REF.sub("", s) if "{" in leftover or "}" in leftover: # unbalanced / nested braces return None if any(not r.strip() for r in refs): # a `{}` ref names nothing return None if valid_keys is not None and any(r not in valid_keys for r in refs): return None return s def _clean_geocode(raw): """One `geocode` bag β†’ the stored shape, or None (dropped). ⭐⭐ W37-T22 (owner item 15 / ruling R4, contract C7). THE ONE validator for the geocode pseudo-kind, called by BOTH field doors: `_field_extras` here (the Odoo grids) and `core/user_tables._clean_field` via `_ag_geocode` (every `ut_*` user database). β›” IT WAS INLINE IN `_field_extras` UNTIL 2026-08-19 AND THAT IS WHY IT SHIPPED HALF-DONE. `user_tables._clean_field` is a strict allowlist that returns only the bags it NAMES, so a geocode column created on a user database was stored WITHOUT its `{addressField}` β€” the *"created, named, configured, gone"* failure the `image` type shipped as in wave 19. Extracting it rather than copying the rules is [[one-question-two-normalizers]]: a second copy is how the two doors come to disagree about what a valid bag is. β›” WHOLE-KEY DROP (the `swipe` construction): a geocode column with no address column is not a degraded column, it is a column no run can ever fill, and the honest state for that is the unconfigured one the client refuses at `canCreate`. β›” THE FIELD'S `type` IS `text` AND THERE IS NO `geocode` FieldType. The kind is a PSEUDO-KIND in the create picker (the `measure` construction), so `CUSTOM_FIELD_TYPES`, `UT_FIELD_TYPES`, `CREATABLE_TYPES`, the shape/label tables and the cell renderer are all untouched β€” three parity gates chain over those sets and none permits a partial landing. This is also why the bag takes `format`'s posture and NOT `formula`'s: there is no type to pair it with, so an absent bag is an ordinary text column rather than a refusal. ⚠ `addressField` is NOT checked against the table's keys: neither door is given `valid_keys`, and the split this module already draws puts that loss on the surface that RENDERS. The enricher must SAY the address column is gone rather than geocode an empty string. """ if not isinstance(raw, dict): return None addr = raw.get("addressField") if not isinstance(addr, str) or not addr.strip(): return None out = {"addressField": addr.strip()[:80]} # D-3 β€” the optional ISO 3166-1 alpha-2 hint, mapped straight onto the geocoder's # `countrycodes` parameter. NORMALISED to upper case and stored only when it is exactly two # letters: absent means "anywhere", and `""` would be that state's second spelling. A # three-letter or numeric code is REFUSED rather than truncated, because a truncated code is # a valid code for a different country. cc = raw.get("country") if isinstance(cc, str) and re.fullmatch(r"[A-Za-z]{2}", cc.strip() or ""): out["country"] = cc.strip().upper() return out # --- DATE RECURRENCE --------------------------------------------------------- # A date cell remains an ISO scalar. Its optional field recurrence is a separate, explicit # configuration bag: persisting a JavaScript Date, locale label, or a client-computed next value # would make an identical record mean different things to two hosts. The host computes the # next occurrence and preview at projection time from this compact, durable shape. _RECURRENCE_KINDS = frozenset({'daily', 'weekly', 'monthly', 'yearly', 'holiday', 'anchored'}) # ⭐ W47-T25 (owner instruction 13, ruling R1): "the date is N days ON / AFTER / BEFORE another # date field". The other date field is the recurrence-level `anchorField` that # `routes_grid.govern_date_recurrence` already requires and already validates as same-database or # linked-through-a-Link-field, so this kind needs no anchor of its own β€” and because the anchor is # a COLUMN, every record computes its own answer from its own anchor value. That is the # per-record behaviour the instruction asks for, without a per-record rule store. # # ⚠ THE KIND IS `anchored`, NOT `offset`. Holiday and anchored rules now share the human # quantity/unit/before-on-after vocabulary, but their anchors remain different: a holiday names # a calendar occurrence while an anchored rule names a record value. Keeping the kinds distinct # stops a holiday rule from quietly becoming a per-row field rule. _ANCHORED_UNITS = frozenset({'day', 'business_day', 'weekday', 'week', 'month', 'year'}) _ANCHORED_RELATIONS = frozenset({'on', 'after', 'before'}) _HOLIDAY_OFFSET_UNITS = _ANCHORED_UNITS # A calendar appears here only when the server really evaluates it. The Date picker reads this # same registry, so a selector cannot promise a country whose recurrence becomes a no-op later. # # ⭐⭐ W46-T33 (owner instruction 13, ruling R11: fixed-date plus floating "plus religious # holidays too including jewish holidays"). A recurrence may now name ONE holiday instead of a # whole national calendar, and the unified quantity/unit/before-on-after offset applies to it. # The granular codes live in THIS registry rather # than a second one, so `_PUBLIC_HOLIDAY_CALENDARS` admits them at the field door, the Date # picker reads them off the same wire, and `recurrence_preview` resolves every choice from that # one registry. # `group` is what lets the picker head its two option groups without a client-side copy of the # list; it is additive, so an older client that ignores it still renders a flat, correct list. PUBLIC_HOLIDAY_CALENDARS = ( {'code': 'US', 'label': 'United States federal holidays', 'group': 'calendar'}, {'code': 'CA', 'label': 'Canada federal public holidays', 'group': 'calendar'}, {'code': 'NEW_YEARS', 'label': "New Year's Day", 'group': 'holiday'}, {'code': 'VALENTINES', 'label': "Valentine's Day", 'group': 'holiday'}, {'code': 'EASTER', 'label': 'Easter Sunday', 'group': 'holiday'}, {'code': 'MOTHERS_DAY', 'label': "Mother's Day", 'group': 'holiday'}, {'code': 'MEMORIAL_DAY', 'label': 'Memorial Day', 'group': 'holiday'}, {'code': 'FATHERS_DAY', 'label': "Father's Day", 'group': 'holiday'}, {'code': 'INDEPENDENCE_DAY', 'label': 'Independence Day', 'group': 'holiday'}, {'code': 'LABOR_DAY', 'label': 'Labor Day', 'group': 'holiday'}, {'code': 'ROSH_HASHANAH', 'label': 'Rosh Hashanah', 'group': 'holiday'}, {'code': 'YOM_KIPPUR', 'label': 'Yom Kippur', 'group': 'holiday'}, {'code': 'HALLOWEEN', 'label': 'Halloween', 'group': 'holiday'}, {'code': 'THANKSGIVING', 'label': 'Thanksgiving', 'group': 'holiday'}, {'code': 'HANUKKAH', 'label': 'Hanukkah', 'group': 'holiday'}, {'code': 'CHRISTMAS_EVE', 'label': 'Christmas Eve', 'group': 'holiday'}, {'code': 'CHRISTMAS', 'label': 'Christmas Day', 'group': 'holiday'}, {'code': 'NEW_YEARS_EVE', 'label': "New Year's Eve", 'group': 'holiday'}, {'code': 'PASSOVER', 'label': 'Passover', 'group': 'holiday'}, ) _PUBLIC_HOLIDAY_CALENDARS = frozenset(item['code'] for item in PUBLIC_HOLIDAY_CALENDARS) # The three old spellings are READ ONLY migration input. `clean_date_recurrence` always emits # the unified quantity/unit/relation form below, so no new saved rule carries the disconnected # +/-1 shape that Wave 48's audit rejected. _HOLIDAY_LEGACY_RELATIONS = {'day_before': -1, 'day_on': 0, 'day_after': 1} def _iso_day(value): if isinstance(value, _dt.datetime): value = value.date() if isinstance(value, _dt.date): return value if not isinstance(value, str): return None try: return _dt.date.fromisoformat(value.strip()[:10]) except ValueError: return None def _observed(day): """US federal-observed day: Saturday -> Friday, Sunday -> Monday.""" if day.weekday() == 5: return day - _dt.timedelta(days=1) if day.weekday() == 6: return day + _dt.timedelta(days=1) return day def _nth_weekday(year, month, weekday, nth): day = _dt.date(year, month, 1) shift = (weekday - day.weekday()) % 7 return day + _dt.timedelta(days=shift + 7 * (nth - 1)) def _last_weekday(year, month, weekday): if month == 12: day = _dt.date(year + 1, 1, 1) - _dt.timedelta(days=1) else: day = _dt.date(year, month + 1, 1) - _dt.timedelta(days=1) return day - _dt.timedelta(days=(day.weekday() - weekday) % 7) def _easter_sunday(year): """Gregorian computus, kept local so a recurrence preview needs no network.""" a = year % 19 b, c = divmod(year, 100) d, e = divmod(b, 4) f = (b + 8) // 25 g = (b - f + 1) // 3 h = (19 * a + b - d - g + 15) % 30 i, k = divmod(c, 4) l = (32 + 2 * e + 2 * i - h - k) % 7 m = (a + 11 * h + 22 * l) // 451 month = (h + l - 7 * m + 114) // 31 day = (h + l - 7 * m + 114) % 31 + 1 return _dt.date(year, month, day) # ── THE HEBREW CALENDAR, kept local for the same reason the computus is ─────────────────────── # R11 asks for Jewish holidays, and those are lunisolar: a hardcoded month and day would be wrong # every year. So they are COMPUTED, with the arithmetic of Dershowitz & Reingold, and the answer # stays available during an outage exactly like `_easter_sunday`'s. # # β›” `_HEBREW_EPOCH` IS -1373427, NOT -1373429. The off-by-two value returns every anchor exactly # two days early across five Hebrew years and four Hebrew months, which reads as a broken # algorithm rather than a wrong constant. RD 1 == 0001-01-01 proleptic Gregorian, which is # precisely `datetime.date.fromordinal`'s origin, so no epoch shim is needed. _HEBREW_EPOCH = -1373427 # Hebrew months are 1=Nisan .. 7=Tishrei .. 13=Adar II, and the YEAR begins at Tishrei (7). _HEBREW_TISHREI, _HEBREW_NISAN, _HEBREW_KISLEV = 7, 1, 9 _HEBREW_YEAR_CACHE = {} def _hebrew_leap(year): return ((year * 7 + 1) % 19) < 7 def _hebrew_last_month(year): return 13 if _hebrew_leap(year) else 12 def _hebrew_elapsed_days(year): months = (235 * ((year - 1) // 19) + 12 * ((year - 1) % 19) + (7 * ((year - 1) % 19) + 1) // 19) day = months * 29 + (12084 + 13753 * months) // 25920 return day + 1 if (3 * (day + 1)) % 7 < 3 else day def _hebrew_new_year(year): """The fixed day number of 1 Tishrei, including the three postponement rules.""" cached = _HEBREW_YEAR_CACHE.get(year) if cached is not None: return cached before, this, after = (_hebrew_elapsed_days(year - 1), _hebrew_elapsed_days(year), _hebrew_elapsed_days(year + 1)) delay = 2 if after - this == 356 else (1 if this - before == 382 else 0) value = _HEBREW_EPOCH + this + delay if len(_HEBREW_YEAR_CACHE) > 2048: _HEBREW_YEAR_CACHE.clear() _HEBREW_YEAR_CACHE[year] = value return value def _hebrew_year_days(year): return _hebrew_new_year(year + 1) - _hebrew_new_year(year) def _hebrew_month_days(year, month): if month in (2, 4, 6, 10, 13): return 29 if month == 12 and not _hebrew_leap(year): return 29 # Marheshvan (8) is long only in a 355 or 385 day year; Kislev (9) is short only in a 353 or # 383 day one. Those two variable months are what keep the festivals off a fixed offset. if month == 8 and _hebrew_year_days(year) % 10 != 5: return 29 if month == 9 and _hebrew_year_days(year) % 10 == 3: return 29 return 30 def _hebrew_date(year, month, day): """The Gregorian DAYTIME date of a Hebrew year/month/day. ⚠ Hebcal's holiday LISTING pages print the preceding SUNSET, one day earlier than this; its converter prints the daytime date, which is what a calendar cell means. """ if month < _HEBREW_TISHREI: span = (sum(_hebrew_month_days(year, item) for item in range(_HEBREW_TISHREI, _hebrew_last_month(year) + 1)) + sum(_hebrew_month_days(year, item) for item in range(1, month))) else: span = sum(_hebrew_month_days(year, item) for item in range(_HEBREW_TISHREI, month)) return _dt.date.fromordinal(_hebrew_new_year(year) + span + day - 1) def _hebrew_in_gregorian(month, day, year): """Every occurrence of one Hebrew month/day landing inside Gregorian `year`. β›” ONE HEBREW YEAR STRADDLES TWO GREGORIAN YEARS β€” Hebrew 5788 puts Rosh Hashanah in 2027 and Passover in 2028 β€” so this scans a WINDOW of Hebrew years and filters on the result, and never assumes `hebrew_year = gregorian_year + 3760`. """ out = set() for hebrew_year in range(year + 3759, year + 3763): try: got = _hebrew_date(hebrew_year, month, day) except (ValueError, OverflowError): continue if got.year == year: out.add(got) return out # β›” A NAMED holiday is the TRUE date and is NEVER weekend-shifted. `_observed()` belongs to the # federal CALENDARS above, where a Saturday holiday really is taken on the Friday. Christmas 2027 # falls on a Saturday and must stay 2027-12-25: shifting it would land it on Christmas Eve, which # is its own separately selectable holiday here. _GRANULAR_HOLIDAYS = { 'NEW_YEARS': lambda year: {_dt.date(year, 1, 1)}, 'VALENTINES': lambda year: {_dt.date(year, 2, 14)}, 'INDEPENDENCE_DAY': lambda year: {_dt.date(year, 7, 4)}, 'HALLOWEEN': lambda year: {_dt.date(year, 10, 31)}, 'CHRISTMAS_EVE': lambda year: {_dt.date(year, 12, 24)}, 'CHRISTMAS': lambda year: {_dt.date(year, 12, 25)}, 'NEW_YEARS_EVE': lambda year: {_dt.date(year, 12, 31)}, 'MOTHERS_DAY': lambda year: {_nth_weekday(year, 5, 6, 2)}, # second Sunday of May 'FATHERS_DAY': lambda year: {_nth_weekday(year, 6, 6, 3)}, # third Sunday of June 'MEMORIAL_DAY': lambda year: {_last_weekday(year, 5, 0)}, # last Monday of May 'LABOR_DAY': lambda year: {_nth_weekday(year, 9, 0, 1)}, # first Monday of September 'THANKSGIVING': lambda year: {_nth_weekday(year, 11, 3, 4)}, # fourth Thursday of November 'EASTER': lambda year: {_easter_sunday(year)}, 'ROSH_HASHANAH': lambda year: _hebrew_in_gregorian(_HEBREW_TISHREI, 1, year), 'YOM_KIPPUR': lambda year: _hebrew_in_gregorian(_HEBREW_TISHREI, 10, year), 'HANUKKAH': lambda year: _hebrew_in_gregorian(_HEBREW_KISLEV, 25, year), 'PASSOVER': lambda year: _hebrew_in_gregorian(_HEBREW_NISAN, 15, year), } def _canada_public_holidays(year): """Canada's federal public-service holiday schedule, deterministically calculated. This is deliberately not a claim about every provincial observance. Weekend fixed holidays move to the next available weekday, including the Christmas/Boxing-Day collision. """ days = { _easter_sunday(year) - _dt.timedelta(days=2), # Good Friday _last_weekday(year, 5, 0) - _dt.timedelta(days=7), # Monday before May 25 _nth_weekday(year, 9, 0, 1), # Labour Day _nth_weekday(year, 10, 0, 2), # Thanksgiving } fixed = [_dt.date(year, 1, 1), _dt.date(year, 7, 1), _dt.date(year, 11, 11), _dt.date(year, 12, 25), _dt.date(year, 12, 26)] if year >= 2021: fixed.append(_dt.date(year, 9, 30)) # Truth and Reconciliation for holiday in fixed: observed = holiday if observed.weekday() == 5: observed += _dt.timedelta(days=2) elif observed.weekday() == 6: observed += _dt.timedelta(days=1) while observed in days: observed += _dt.timedelta(days=1) days.add(observed) return frozenset(days) # A preview generates its finite set of holiday source years once. An uncached lunisolar # computation would otherwise repeat for every editor preview. The values are immutable # frozensets of a pure function of (code, year), so remembering them cannot change an answer. _HOLIDAY_CACHE = {} def _remember_holidays(key, days): if len(_HOLIDAY_CACHE) > 4096: _HOLIDAY_CACHE.clear() _HOLIDAY_CACHE[key] = days return days def public_holidays(calendar, year): """A supported public holiday calendar, returned as deterministic ISO-day objects. US federal holidays are intentionally calculated locally rather than fetched from a public endpoint during a render: a recurrence must keep its answer during an outage and historical previews must not move when a third party updates a feed. Unsupported calendars are refused at the field door; the empty result here protects old malformed stored data. """ calendar = str(calendar or '').upper() if calendar not in _PUBLIC_HOLIDAY_CALENDARS: return frozenset() key = (calendar, year) cached = _HOLIDAY_CACHE.get(key) if cached is not None: return cached if calendar == 'CA': return _remember_holidays(key, _canada_public_holidays(year)) # β›” THIS GUARD IS LOAD-BEARING. Without it every granular code admitted above falls straight # through to the US federal body below and previews as the whole United States calendar β€” # a wrong answer that no gate would go red on. if calendar != 'US': builder = _GRANULAR_HOLIDAYS.get(calendar) return _remember_holidays(key, frozenset(builder(year) if builder else ())) days = { _observed(_dt.date(year, 1, 1)), _nth_weekday(year, 1, 0, 3), # Martin Luther King Jr. Day _nth_weekday(year, 2, 0, 3), # Washington's Birthday _last_weekday(year, 5, 0), # Memorial Day _observed(_dt.date(year, 7, 4)), _nth_weekday(year, 9, 0, 1), # Labor Day _nth_weekday(year, 10, 0, 2), # Columbus Day _observed(_dt.date(year, 11, 11)), _nth_weekday(year, 11, 3, 4), # Thanksgiving _observed(_dt.date(year, 12, 25)), } # Juneteenth became a federal holiday in 2021; earlier recurrence previews must not # retroactively invent it. if year >= 2021: days.add(_observed(_dt.date(year, 6, 19))) return _remember_holidays(key, frozenset(days)) def clean_ends(raw): """One recurrence's stopping condition, normalised. Never raises. W46-T32 shipped the Ends control on the client and `clean_date_recurrence` builds a fresh allowlist dict, so `ends` round-tripped as ABSENT and a rule asking for three occurrences still previewed ten. This is the server half of that control. Anything malformed degrades to ``never`` rather than refusing the whole recurrence: a stopping condition nobody can read is a reason to keep repeating, not a reason to lose the schedule. """ if not isinstance(raw, dict): return {'kind': 'never'} kind = str(raw.get('kind') or 'never').strip().lower() if kind == 'on': day = _iso_day(raw.get('date')) return {'kind': 'on', 'date': day.isoformat()} if day else {'kind': 'never'} if kind == 'after': count = raw.get('count') if isinstance(count, bool) or not isinstance(count, int) or not 1 <= count <= 999: return {'kind': 'never'} return {'kind': 'after', 'count': count} return {'kind': 'never'} def clean_date_recurrence(raw, condition_fields=None): """One date field's recurrence config, or ``None`` for absent/malformed input. ``rules`` are an intentional union: selecting weekday + public holiday means either makes a valid next date. The stored config carries neither a process clock nor generated preview; those derived values belong to ``recurrence_payload`` and are evaluated by the server. """ if not isinstance(raw, dict): return None start = _iso_day(raw.get('startDate', raw.get('anchor'))) anchor_raw = raw.get('anchorField') anchor = None if isinstance(anchor_raw, dict): table = str(anchor_raw.get('table') or 'same').strip()[:80] field = str(anchor_raw.get('field') or '').strip()[:80] via = str(anchor_raw.get('linkedVia') or '').strip()[:80] if field and (table == 'same' or via): anchor = {'table': table, 'field': field} if via: anchor['linkedVia'] = via if start is None and anchor is None: return None # W48-T11 / R6: tenant holidays are declarative dates stored with this recurrence, # never fetched from an external calendar. Bound and normalised before a rule can refer # to them, so the preview and persisted filter share one tenant-owned set. tenant_holidays = sorted({day.isoformat() for day in (_iso_day(value) for value in list(raw.get('tenantHolidays') or [])[:366]) if day is not None}) out_rules = [] for raw_rule in list(raw.get('rules') or [])[:12]: if not isinstance(raw_rule, dict): continue kind = str(raw_rule.get('kind') or '').lower() if kind not in _RECURRENCE_KINDS: continue interval = raw_rule.get('interval', 1) if not isinstance(interval, int) or isinstance(interval, bool) or not 1 <= interval <= 366: continue rule = {'kind': kind, 'interval': interval} if kind == 'weekly': weekdays = sorted({day for day in (raw_rule.get('weekdays') or []) if isinstance(day, int) and not isinstance(day, bool) and 0 <= day <= 6}) rule['weekdays'] = weekdays or ([start.weekday()] if start else []) if not rule['weekdays']: continue elif kind == 'monthly': # ``day: 1`` means the first of every N months. ``ordinal`` + ``weekday`` adds # Google-Calendar-style first Monday / last Friday without a competing model. if 'ordinal' in raw_rule or 'weekday' in raw_rule: ordinal, weekday = raw_rule.get('ordinal'), raw_rule.get('weekday') if (not isinstance(ordinal, int) or isinstance(ordinal, bool) or ordinal not in (-1, 1, 2, 3, 4, 5) or not isinstance(weekday, int) or isinstance(weekday, bool) or not 0 <= weekday <= 6): continue rule.update({'ordinal': ordinal, 'weekday': weekday}) else: day = raw_rule.get('day', start.day if start else None) if not isinstance(day, int) or isinstance(day, bool) or not 1 <= day <= 31: continue rule['day'] = day elif kind == 'yearly': month = raw_rule.get('month', start.month if start else None) day = raw_rule.get('day', start.day if start else None) if (not isinstance(month, int) or isinstance(month, bool) or not 1 <= month <= 12 or not isinstance(day, int) or isinstance(day, bool) or not 1 <= day <= 31): continue # Validate the month/day without reinterpreting 29 February. try: _dt.date(2024, month, day) except ValueError: continue rule.update({'month': month, 'day': day}) elif kind == 'holiday': calendar = str(raw_rule.get('calendar') or 'US').strip().upper() if calendar not in _PUBLIC_HOLIDAY_CALENDARS and calendar != 'TENANT': continue if calendar == 'TENANT' and not tenant_holidays: continue # W48-T11: Holidays must use the SAME quantity/unit/before-on-after sentence as a # date offset. The former +/-1 relation is still accepted only long enough to turn # existing rules into this one canonical shape. It never reaches a response or a # fresh save unchanged. raw_relation = str(raw_rule.get('relation') or '').strip().lower() legacy_offset = _HOLIDAY_LEGACY_RELATIONS.get(raw_relation) if legacy_offset is not None: relation = 'before' if legacy_offset < 0 else ('after' if legacy_offset > 0 else 'on') offset, unit = abs(legacy_offset), 'day' elif raw_relation in _ANCHORED_RELATIONS: relation = raw_relation unit = str(raw_rule.get('unit') or 'day').strip().lower() if unit not in _HOLIDAY_OFFSET_UNITS: continue offset = raw_rule.get('offset', 0 if relation == 'on' else None) if (not isinstance(offset, int) or isinstance(offset, bool) or (relation == 'on' and offset != 0) or (relation != 'on' and not 1 <= offset <= 366)): continue # The hidden unit/count must not survive an "on" choice in storage. A rule is # therefore read back exactly as the editor renders it. if relation == 'on': unit = 'day' else: # Legacy rules written before the relation words carried only a signed day # offset. Convert those deterministically; an unsigned value above one with no # unit/direction is malformed rather than guessed. legacy_offset = raw_rule.get('offset', 0) if (not isinstance(legacy_offset, int) or isinstance(legacy_offset, bool) or legacy_offset not in (-1, 0, 1)): continue relation = ('before' if legacy_offset < 0 else ('after' if legacy_offset > 0 else 'on')) offset, unit = abs(legacy_offset), 'day' rule.update({'calendar': calendar, 'offset': offset, 'unit': unit, 'relation': relation}) elif kind == 'anchored': # ⚠ Anchored and holiday rules share the readable before/on/after words, but their # anchors differ: this branch moves from a record date while holiday moves from a # calendar occurrence. The kinds stay exclusive and each branch writes only its # own keys. # # An unknown unit or relation drops the rule, exactly as an unknown calendar does # above, rather than degrading to a default the person never chose. `interval` was # already bounded to 1..366 by the shared check, so `relation: on` arrives as 1 and a # 0 would have dropped the rule before reaching here. unit = str(raw_rule.get('unit') or 'day').strip().lower() relation = str(raw_rule.get('relation') or 'after').strip().lower() if unit not in _ANCHORED_UNITS or relation not in _ANCHORED_RELATIONS: continue rule.update({'unit': unit, 'relation': relation}) if rule not in out_rules: out_rules.append(rule) if not out_rules: return None preview_count = raw.get('previewCount', raw.get('preview', 10)) if not isinstance(preview_count, int) or isinstance(preview_count, bool): preview_count = 10 out = {'rules': out_rules, 'previewCount': max(1, min(preview_count, 50))} if tenant_holidays: out['tenantHolidays'] = tenant_holidays if start: out['startDate'] = start.isoformat() if anchor: out['anchorField'] = anchor admitted_conditions = (condition_fields if condition_fields is not None else raw.get('conditionFields')) conditions = clean_filter_tree(raw.get('conditions') or [], valid_keys={ str(key) for key in admitted_conditions or () if str(key)}) if conditions: out['conditions'] = conditions ends = clean_ends(raw.get('ends')) # Emitted only when it says something, exactly like `conditions`, so no previously saved # config grows a key it never had. `clean_ends` is idempotent on its own output, which is # what lets `recurrence_payload` re-clean an already-clean dict. if ends['kind'] != 'never': out['ends'] = ends return out def _shift_months(day, amount): """``day`` moved ``amount`` calendar months, CLAMPED to the target month's last valid day. Adding one month to 31 January has no 31 February, so the answer is 28 or 29 February rather than a rolled-over 2 or 3 March. Python's FLOOR division and modulo are what make a negative amount (a ``before`` rule) land in the right year: a total of -1 gives year - 1, month 12, where a C-style remainder would give month 0. """ total = (day.year * 12 + day.month - 1) + amount year, month = divmod(total, 12) month += 1 if not 1 <= year <= 9999: return None # The last day of `month` is the day before the first of the next one, without importing # `calendar` for a single call. December 9999 cannot ask Python for January 10000, so its # known last day stays local instead of turning a valid editor input into a server error. last = 31 if month == 12 else (_dt.date(year, month + 1, 1) - _dt.timedelta(days=1)).day return _dt.date(year, month, min(day.day, last)) def _business_day_shift(start, amount, holidays): """Move by business days, excluding weekends and this tenant's declared holidays.""" if amount == 0: return start direction = 1 if amount > 0 else -1 remaining, day = abs(amount), start try: while remaining: day += _dt.timedelta(days=direction) if day.weekday() < 5 and day not in holidays: remaining -= 1 except OverflowError: return None return day def _weekday_shift(start, amount): """Move by weekdays, excluding weekends but deliberately not tenant holidays.""" if amount == 0: return start direction = 1 if amount > 0 else -1 remaining, day = abs(amount), start try: while remaining: day += _dt.timedelta(days=direction) if day.weekday() < 5: remaining -= 1 except OverflowError: return None return day def _shift_years(day, amount): """Move calendar years while clamping a leap-day to February's last valid day.""" year = day.year + amount if not 1 <= year <= 9999: return None try: return day.replace(year=year) except ValueError: # The only legal source-day failure is 29 February into a non-leap year. return _dt.date(year, 2, 28) def _anchored_occurrence(start, rule, tenant_holidays=frozenset()): """The ONE date an ``anchored`` rule names, computed straight from the anchor date. β›” NEVER route this through `_recurrence_matches`. That function returns False for ``day < start``, and a ``before`` date is by definition EARLIER than the anchor, so the day scan below could never find one however far it walked. """ relation = rule.get('relation', 'after') if relation == 'on': return start amount = rule['interval'] * (1 if relation == 'after' else -1) unit = rule.get('unit', 'day') if unit == 'month': return _shift_months(start, amount) if unit == 'year': return _shift_years(start, amount) if unit == 'business_day': return _business_day_shift(start, amount, tenant_holidays) if unit == 'weekday': return _weekday_shift(start, amount) try: return start + _dt.timedelta(days=amount * (7 if unit == 'week' else 1)) except OverflowError: return None def _holiday_occurrence(holiday, rule, tenant_holidays=frozenset()): """The exact date one unified holiday-offset rule names. `weekday` intentionally ignores tenant holidays while `business_day` skips both weekends and the tenant's declared dates. The distinction is visible in the editor and keeps the server preview authoritative for the rule the person actually chose. """ relation = rule.get('relation', 'on') if relation == 'on': return holiday amount = rule['offset'] * (1 if relation == 'after' else -1) unit = rule.get('unit', 'day') if unit == 'month': return _shift_months(holiday, amount) if unit == 'year': return _shift_years(holiday, amount) if unit == 'business_day': return _business_day_shift(holiday, amount, tenant_holidays) if unit == 'weekday': return _weekday_shift(holiday, amount) try: return holiday + _dt.timedelta(days=amount * (7 if unit == 'week' else 1)) except OverflowError: return None def _recurrence_matches(day, start, rule): kind, interval = rule['kind'], rule['interval'] if day < start: return False if kind == 'daily': return (day - start).days % interval == 0 if kind == 'weekly': return ((day - start).days // 7) % interval == 0 and day.weekday() in rule['weekdays'] if kind == 'monthly': months = (day.year - start.year) * 12 + day.month - start.month if months < 0 or months % interval: return False if 'ordinal' not in rule: return day.day == rule['day'] match = (_last_weekday(day.year, day.month, rule['weekday']) if rule['ordinal'] == -1 else _nth_weekday(day.year, day.month, rule['weekday'], rule['ordinal'])) return match.month == day.month and match == day if kind == 'yearly': return (day.year - start.year) % interval == 0 and day.month == rule['month'] and day.day == rule['day'] return False def recurrence_preview(raw, today=None, count=None, condition_fields=None): """The next distinct ISO dates, anchored to the server's supplied/current day.""" config = clean_date_recurrence(raw, condition_fields=condition_fields) if config is None: return [] now = _iso_day(today) or _dt.date.today() start = _iso_day(config.get('startDate')) if start is None and isinstance(raw, dict): start = _iso_day(raw.get('resolvedAnchorDate')) if start is None: return [] want = config['previewCount'] if count is None else max(1, min(int(count), 50)) ends = config.get('ends') or {'kind': 'never'} # A preview of at most fifty values needs no unbounded search. Ten years also makes an # unavailable public calendar visibly empty instead of spinning a request forever. try: horizon = max(start, now) + _dt.timedelta(days=3660) except OverflowError: horizon = _dt.date.max # β›” "After N occurrences" COUNTS FROM `startDate`, NOT FROM TODAY: occurrences already in the # past have spent the allowance. Counting from today is the obvious implementation and it is # wrong in a way that looks perfectly reasonable β€” a weekly Monday schedule begun 2026-01-01 # with `after 3`, viewed on 2026-01-13, has exactly ONE occurrence left, not three. So the # scan starts at the START for that case, and the visible window is trimmed afterwards. limit = want if ends['kind'] == 'after': lower, limit = start, ends['count'] else: lower = max(start, now) if ends['kind'] == 'on': horizon = min(horizon, _iso_day(ends.get('date')) or horizon) found = set() holiday_rules = [rule for rule in config['rules'] if rule['kind'] == 'holiday'] anchored_rules = [rule for rule in config['rules'] if rule['kind'] == 'anchored'] ordinary_rules = [rule for rule in config['rules'] if rule['kind'] not in ('holiday', 'anchored')] # W47-T25: an anchored rule names ONE date rather than a repeating series, so it is COMPUTED # here instead of being searched for by the scan below. It still passes the trailing # `item >= now` filter, and that is deliberate: the cell holds the NEXT date, so an anchored # date that has already gone by is EMPTY rather than a date in the past. One column, one # meaning, which is what lets the ordinary filter, sort and group paths read it unchanged. # `horizon` is already final at this point, so an `ends: on` boundary binds here too. tenant_holidays = frozenset(_dt.date.fromisoformat(value) for value in config.get('tenantHolidays', [])) for rule in anchored_rules: occurrence = _anchored_occurrence(start, rule, tenant_holidays) if occurrence is not None and start <= occurrence <= horizon: found.add(occurrence) # A holiday's source year can differ from its result year when the chosen unit is years. We # generate each authoritative occurrence once, then let the ordinary-rule scan merge it with # daily/weekly/monthly values. Stopping that scan merely because holidays filled the preview # would drop an earlier ordinary occurrence, so it intentionally walks the finite horizon. for rule in holiday_rules: extra_years = rule['offset'] if rule.get('unit') == 'year' and rule.get('relation') != 'on' else 0 for holiday_year in range(start.year, min(9999, horizon.year + extra_years) + 1): if (holiday_year - start.year) % rule['interval']: continue holidays = ({_dt.date.fromisoformat(value) for value in config.get('tenantHolidays', []) if value.startswith(f"{holiday_year:04d}-")} if rule['calendar'] == 'TENANT' else public_holidays(rule['calendar'], holiday_year)) for holiday in holidays: occurrence = _holiday_occurrence(holiday, rule, tenant_holidays) # Outside an `ends: after` rule the old day scan began at `lower`, so adding # earlier calendar occurrences here would let past holidays consume the preview # limit before today's dates were considered. if occurrence is not None and lower <= occurrence <= horizon: found.add(occurrence) day = lower while ordinary_rules and day <= horizon: if any(_recurrence_matches(day, start, rule) for rule in ordinary_rules): found.add(day) if day == _dt.date.max: break day += _dt.timedelta(days=1) allowed = sorted(found)[:limit] return [item.isoformat() for item in allowed if item >= now][:want] def recurrence_payload(raw, today=None, condition_fields=None): """Durable config plus server-authoritative ``nextDate`` and finite ``preview``.""" config = clean_date_recurrence(raw, condition_fields=condition_fields) if config is None: return None preview = recurrence_preview(config, today=today, condition_fields=condition_fields) return {**config, 'nextDate': preview[0] if preview else None, 'preview': preview} def project_date_recurrences(fields, today=None): """Re-project recurrence metadata against the final visible field contract.""" valid_keys = {str(field.get('key')) for field in fields or () if isinstance(field, dict) and field.get('key')} out = [] for field in fields or (): if not isinstance(field, dict) or field.get('type') != 'date' \ or not isinstance(field.get('recurrence'), dict): out.append(field) continue item = dict(field) recurrence = recurrence_payload( field.get('recurrence'), today=today, condition_fields=valid_keys) if recurrence: item['recurrence'] = recurrence else: item.pop('recurrence', None) out.append(item) return out # ── ⭐⭐ W47-T26 (owner instruction 13 / ruling R2, contract C5): THE NEXT DATE AS A CELL ── # # R2, verbatim: the computed next date is STORED in the cell, "so it filters, sorts and groups # like an ordinary date". Everything below is PURE β€” it reads a recurrence config and a row's # anchor cell and returns an ISO day string. The writer lives on the write path # (`aios-web/api/routes_grid.py`), because a value re-derived on every response is exactly the # thing that cannot be filtered, and that is the defect this pair closes. # # ⚠ `project_date_recurrences` ABOVE IS UNCHANGED AND STAYS UNCHANGED. It projects the field's # METADATA (the config plus a server-authoritative preview) for the editor to draw; these two # functions project a ROW's value. Two different questions, and `verify_fields_contract.py` and # `verify_api.py::section_recurrence_preview` both assert the first one's exact output. def recurrence_row_next_date(recurrence, anchor_value, today=None, condition_fields=None): """The ONE next date a row's recurrence names, computed from THAT ROW's anchor cell. β›” AN EMPTY ANCHOR CELL IS AN EMPTY ANSWER, never the field-level ``startDate``. Falling back to the field's own start would hand every unanchored row the SAME date β€” a column full of confident wrong values instead of an honestly empty one, and W47-T25 already ruled that clause. ``None`` here becomes an empty cell there. The per-row config is the STORED config with ``startDate`` REPLACED, which is deliberately simpler than `recurrence_preview`'s unused ``resolvedAnchorDate`` hook: one substitution, and then every rule kind β€” daily, weekly, monthly, yearly, holiday, anchored β€” is answered by exactly the code that answers the field-level preview. There is no second definition of "next" to keep in step, which is the whole reason the substitution happens here rather than inside the scan. """ if not isinstance(recurrence, dict): return None anchor = _iso_day(anchor_value) if anchor is None: return None payload = recurrence_payload({**recurrence, 'startDate': anchor.isoformat()}, today=today, condition_fields=condition_fields) return (payload or {}).get('nextDate') or None def recurrence_column_values(recurrence, rows, anchor_key, today=None, condition_fields=None, row_ids=None): """``{row_id: <ISO day> or ''}`` for one recurrence date column over ``rows``. ``rows`` is the store's own ``{row_id: {field_key: value}}`` shape. ``row_ids`` narrows the pass to the rows an anchor edit actually touched; ``None`` means the whole column. β›” MEMOISED ON THE ANCHOR DAY, and that is not a micro-optimisation. `recurrence_preview` walks a day at a time until it has ``previewCount`` matches, so ONE yearly rule is ~3,650 iterations β€” per row. Rows overwhelmingly share anchor days (a batch loaded on one date, a renewal month), so the cache collapses a thousand-row column onto a handful of computations. ⚠ The obvious alternative β€” asking `recurrence_preview` for ``count=1`` β€” is NOT equivalent and must not be substituted: an anchored occurrence joins ``found`` BEFORE the scan and may be in the past, and ``sorted(found)[:limit]`` truncates BEFORE the ``>= now`` filter, so a limit of one can answer empty exactly where the full preview answers correctly. An empty answer is ``''`` rather than ``None`` because that is what the grid stores when a person CLEARS a date cell (`core/grid_events.py`'s overlay branch). One representation of empty, so a materialised blank and a typed blank are the same value to every reader. """ if not isinstance(recurrence, dict) or not isinstance(rows, dict) or not anchor_key: return {} anchor_key = str(anchor_key) ids = list(rows) if row_ids is None else [str(rid) for rid in row_ids] memo, out = {}, {} for rid in ids: row = rows.get(str(rid)) if not isinstance(row, dict): continue anchor = _iso_day(row.get(anchor_key)) day = anchor.isoformat() if anchor is not None else '' if day not in memo: memo[day] = (recurrence_row_next_date( recurrence, day, today=today, condition_fields=condition_fields) or '') out[str(rid)] = memo[day] return out def _default_value_extras(saved): """Carry scalar default metadata without treating falsy values as absent.""" value = saved.get('defaultValue') if isinstance(value, (str, int, float, bool)): return {'defaultValue': value} return {} def _field_extras(saved, ftype, condition_fields=None): """createdBy / permissions / format / scope β€” the validated passthrough the created strata share (wave 5). `createdBy` is only ever WRITTEN host-side (the handler stamps it); here it is carried so the client can gate its menus and the handler can enforce against it. `scope` (wave-6 item 9): 'cohort' marks a field created as cohort-specific β€” the handler stamps it at create (cohort page only) and preserves it like createdBy; carried here so the client can label the field, filtered OUT of other pages by fields_from_workspace.""" out = _default_value_extras(saved) if ftype == 'link' and 'link' in saved: from core.user_tables import _clean_link link = _clean_link(saved['link']) if link is None: raise ValueError('The link field definition is invalid.') out['link'] = link if ftype == 'autonumber': from core.user_tables import _clean_autonumber out['autonumber'] = _clean_autonumber(saved.get('autonumber')) out['valueAuthority'] = 'computed' if ftype in ('created_by', 'last_modified_time', 'last_modified_by'): out['valueAuthority'] = 'computed' who = saved.get("createdBy") if isinstance(who, str) and who.strip(): out["createdBy"] = who.strip()[:80] perms = _clean_permissions(saved.get("permissions")) if perms: out["permissions"] = perms fmt = _clean_format(saved.get("format"), ftype) if fmt: out["format"] = fmt if saved.get("scope") == "cohort": out["scope"] = "cohort" # ── ⭐⭐ W37-T22 (owner item 15 / ruling R4, contract C7): THE GEOCODE COLUMN'S CONFIG ── # # `{addressField}` β€” which column this one reads. WHOLE-KEY drop (the `swipe` construction): # a geocode column with no address column is not a degraded one, it is a column no run can # ever fill, and the honest state for that is the unconfigured one the client refuses at # `canCreate`. # # β›” THE FIELD'S `type` IS `text` AND THERE IS NO `geocode` FieldType. The kind is a PSEUDO-KIND # in the create picker (the `measure` construction), so `CUSTOM_FIELD_TYPES`, `UT_FIELD_TYPES`, # `CREATABLE_TYPES`, the shape/label tables and the cell renderer are all untouched β€” three # parity gates chain over those sets and none permits a partial landing. # ⚠ `addressField` is NOT checked against this table's keys: `_field_extras` is not given # `valid_keys`, and the split this module already draws puts that loss on the surface that # RENDERS ("what each mode MEANS ... is the client's business"). The enricher must SAY the # address column is gone rather than geocode an empty string. # ⚠ EXTRACTED to `_clean_geocode` 2026-08-19 (/validate-wave, W37-T22 clause 1). The rules # did not change; what changed is that `core/user_tables.py` now reaches THIS function through # `_ag_geocode` instead of carrying a second copy. See `_clean_geocode`'s own note. geo = _clean_geocode(saved.get("geocode")) if geo: out["geocode"] = geo # W43C C2 Ò€” the ISO date remains scalar in each row; recurrence is field metadata. Serve # the compact persisted config together with a server-derived next date and preview so the # client never substitutes its browser clock or holiday library for the tenant contract. recurrence = (recurrence_payload(saved.get("recurrence"), condition_fields=condition_fields) if ftype == "date" else None) if recurrence: out["recurrence"] = recurrence corrected_from = saved.get("labelCorrectedFrom") correction_id = saved.get("labelCorrectionId") if (isinstance(corrected_from, str) and corrected_from.strip() and isinstance(correction_id, str) and correction_id.strip()): out["labelCorrectedFrom"] = corrected_from.strip()[:120] out["labelCorrectionId"] = correction_id.strip()[:180] return out #: The DERIVED column listing the cohorts a customer is in (owner, 2026-07-27). #: #: NOT in `aios_grid_fields.json`, deliberately. That contract is per-TABLE and shared with the #: standalone API and the dev sample; a cohort is per-USER, so the column exists exactly when the #: caller has cohorts β€” the same condition under which the `__cohort__` FILTER field is offered. #: Putting it in the canonical contract would mean an always-present column that is empty for #: everyone else, plus three consumers to keep in step for a value none of them can produce. COHORT_COLUMN = 'cohorts' def cohort_field(label='Locked views'): """The derived membership column's descriptor. ⚠ WAVE 17 item 14 / C-STR β€” THE LABEL AND THE NOTE SPEAK THE NEW VOCABULARY; THE KEY DOES NOT. `COHORT_COLUMN` is still `'cohorts'` and the function is still `cohort_field`, because every stored view that shows or groups by this column names it by KEY, and every gate in two runtimes names the function. The owner renamed a CONCEPT ("we should stop calling it Cohort, but locked instead"), which is a change to what a reader sees β€” renaming the identifiers would break saved views to change a word nobody reads. `source: 'odoo'` is doing ONE job here and it is not provenance: the client keys editability off `source == 'overlay'`, and `_cl_handle_grid_event` accepts cell writes only for overlay keys. So 'odoo' is what makes this column READ-ONLY at both ends. `derived: True` is what stops the column menu calling it a "source field" on that basis. ⚠ `filterable: False`, and the replacement is the `Where [Cohort] […]` CONDITION, not another column. Text ops over a joined string would ALMOST work and disagree at the edges β€” `contains "VIP"` also matches a cohort called "VIP club" β€” and a filter that is nearly right is worse than one that is absent. """ return { 'key': COHORT_COLUMN, 'label': label, 'type': 'text', 'source': 'odoo', 'default': False, 'filterable': False, 'derived': True, 'multi': True, 'note': 'The locked views this customer is in, newest first. A locked view holds a SET, ' 'so grouping by this column puts a customer under EVERY view they are in; the ' 'group counts therefore add up to more than the record count, which stays the ' 'number of distinct customers. Read-only: membership changes only by adding or ' 'removing customers on the locked view itself.', } def cohort_cells(cohorts, allowed_pids=None): """`{pid: {'cohorts': 'Q3 calls, Lost'}}` from `[{id,name,pids}, ...]`. Built per render from the caller's OWN cohorts and handed to `rows_from_pool` as `derived`, never merged into the cached pool rows β€” those are shared across users, and stamping one user's cohorts onto them would leak the membership to everybody else on the next render. """ cells = {} for c in cohorts or []: # ⚠ The COMMA is the separator the client splits on to group a customer into EVERY # cohort they are in, so it cannot also occur inside a name. Cohort names are free text # ("Q3 calls, west" is a name somebody will type), so a comma is replaced here rather # than left to break the split silently β€” one group called "Q3 calls" and another called # "west" would be two lists that do not exist. The cost is cosmetic and confined to the # cell; the Cohort page still shows the name the user typed. name = str(c.get('name') or c.get('id') or '').replace(',', ' ').strip() for pid in c.get('pids') or (): if allowed_pids is not None and pid not in allowed_pids: continue cells.setdefault(pid, []).append(name) return {pid: {COHORT_COLUMN: ', '.join(names)} for pid, names in cells.items()} def clean_measure_field(raw, offered): """Validate one UNTRUSTED formula-measure field (owner item 7) against the caller's OFFER. `offered` is `{measure key: {label, type}}` from `measure_filter.measure_fields(team_id)` β€” the same admission the condition builder uses, so a field can only name a measure this caller could also filter by. Returns the canonical stored shape, or None (fail closed). `source:'odoo'` + `derived:True` is the cohort column's read-only mechanism, reused: the client keys editability off `source == 'overlay'` and the host accepts cell writes only for overlay keys, so a measure column cannot be typed into at either end. `filterable:False` because the REPLACEMENT is the measure CONDITION with the same measure and window β€” the governed, gate-proved path (CG-8/CG-12) β€” not text ops over a derived cell. """ if not isinstance(raw, dict): return None key = str(raw.get("key") or "") if not key.startswith(MEASURE_FIELD_PREFIX) or len(key) > 80: return None spec = raw.get("measure") if not isinstance(spec, dict): return None m = (offered or {}).get(spec.get("key")) if not m: return None # not admitted for this caller -> fail closed window = _clean_window(spec.get("window")) if window is None: return None # a measure column with no period is not a column mtype = m.get("type") if m.get("type") in MEASURE_FIELD_TYPES else "currency" return { "key": key, "label": str(raw.get("label") or m.get("label") or "Measure")[:120], "type": mtype, "source": "odoo", "default": True, "custom": True, "derived": True, "filterable": False, # W41-T21 (owner instruction 16): every numeric measure column arrives with a column # summary, `pct` included. A pct measure used to fall through to `agg: None`, so a # percentage column could never total at the bottom or per group. # It defaults to AVERAGE rather than sum ON PURPOSE: twenty rows of 20% would "total" # 400%, a number nobody can use. Currency and int keep `sum`. `average` is a member # of FIELD_AGGS, which is the vocabulary the saved-field passthrough at the bottom # of `fields_from_workspace` filters against, so it is not nulled on the way out. # Do not tidy the pct arm back to `sum`. The `else None` arm stays fail closed for # any future member of MEASURE_FIELD_TYPES that is not summable; today the `mtype` # fallback above makes it unreachable. "agg": ("average" if mtype == "pct" else "sum" if mtype in ("currency", "int") else None), "note": str(raw.get("note") or "")[:2000], "measure": {"key": str(spec.get("key"))[:80], "window": window}, } def measure_fields_of(fields): """The formula-measure columns among `fields` β€” the ones whose values the host must compute per render (see `rows_from_pool`'s `derived`).""" return [f for f in fields or [] if isinstance(f.get("measure"), dict)] def fields_from_workspace(workspace=None, cohorts=False, scope_key=None, fields_base=None): """Overlay persisted notes/custom fields onto the immutable source-field contract. `cohorts=True` appends the derived cohort column β€” see `cohort_field`. Appended LAST and `default: False`, so it never displaces a column somebody already reads; the Fields menu is where you turn it on. Three saved strata pass through: notes on base fields, `custom_` overlay fields (editable), and `measure_` formula-measure fields (read-only, host-computed β€” owner item 7). A measure field was validated against the caller's measure OFFER when it was written (`clean_measure_field`); here only its SHAPE is re-checked, because this module has zero app-internal imports and cannot know the offer. A measure that has since become unanswerable (a BU scope on a company-level measure) degrades to a BLANK column at value time, never to an error. `scope_key` (wave-6 item 9) names the PAGE doing the asking ('customer' / 'cohort'). A saved def carrying `scope` is emitted only when it matches β€” so a cohort-specific field never appears on the Customer table. FAIL-CLOSED: a caller that passes no scope_key sees only unscoped (global) fields; base contract fields are never scoped. `fields_base` (wave 16 C-TOPIC) β€” the canonical contract to overlay onto. Absent = the CUSTOMER contract (`FIELDS`), byte-identical to before the parameter existed; the product surface passes `product_fields()`. The workspace dict a caller hands in must already be the matching table object's bucket β€” this function cannot tell a customer overlay from a product one, which is exactly why the buckets are separate stores. """ saved = dict((workspace or {}).get("fields") or {}) out = [] base_fields = fields_base if fields_base is not None else FIELDS base_keys = {field["key"] for field in base_fields} recurrence_keys = base_keys | {str(key) for key in saved} for base in base_fields: meta = saved.get(base["key"]) or {} field = dict(base) field.update(_default_value_extras(meta)) if base.get('type') == 'link' and 'link' in meta: field.update(_field_extras(meta, 'link', condition_fields=recurrence_keys)) if isinstance(meta.get("note"), str): field["note"] = meta["note"][:2000] # Wave-5 item 10: a saved DISPLAY format on any base field (a preset included) β€” how a # number or date READS, per user. Rendering-only, so this is the whole acceptance. fmt = _clean_format(meta.get("format"), base.get("type")) if fmt: field["format"] = fmt # ⭐ W29-T83 β€” the saved COLUMN SUMMARY, the read half of the write door in # `grid_events.field_upsert`. Without this the value round-trips into the store and is # never served back, which looks exactly like a write that never happened # ([[read-path-cannot-witness-write-path]]). Absent = whatever the contract declares. if meta.get("agg") in FIELD_AGGS: field["agg"] = meta["agg"] # PRESET measure fields (wave-2 item 8): a preset+measure base may take a saved # window/label override. Wave 6 deleted every preset member (the owner's # no-buildable-presets rule) so this branch is currently MEMBERLESS β€” kept as the # measure_ path's twin for any future preset-carrying contract, and because deleting # it would silently change what a re-added preset means. if base.get("preset") and isinstance(base.get("measure"), dict): saved_measure = meta.get("measure") if isinstance(meta.get("measure"), dict) else {} window = _clean_window(saved_measure.get("window")) if window is not None: field["measure"] = {"key": base["measure"]["key"], "window": window} if isinstance(meta.get("label"), str) and meta["label"].strip(): field["label"] = meta["label"][:120] # A source-backed choice field can learn vocabulary from accepted values. The annotation # is not a replacement for contract choices: an old workspace cannot make a currently # declared option disappear. This is the read half of TableStore's atomic overlay + # choice write, so an "Add option" survives a fresh payload rather than existing only in # the optimistic cell editor. if base.get("type") in ("select", "multiselect") and "options" in meta: options = merge_choice_options(base.get("options"), meta.get("options")) field["options"] = options field.update(_choice_appearance(meta, options)) # Recurrence belongs to the Date FIELD, not to an individual ISO date cell. Source # fields need this explicit read half because their override is otherwise rebuilt from # the immutable contract on every workspace projection. if base.get("type") == "date" and "recurrence" in meta: recurrence = recurrence_payload( meta.get("recurrence"), condition_fields=recurrence_keys) if recurrence: field["recurrence"] = recurrence out.append(field) for key, field in saved.items(): if key in base_keys or not isinstance(field, dict): continue if field.get("scope") and field.get("scope") != scope_key: continue # a cohort-specific field on another page (wave-6 item 9) if (str(key).startswith(MEASURE_FIELD_PREFIX) and isinstance(field.get("measure"), dict)): window = _clean_window(field["measure"].get("window")) mkey = str(field["measure"].get("key") or "") if window is None or not mkey: continue mtype = field.get("type") if field.get("type") in MEASURE_FIELD_TYPES else "currency" out.append({ "key": str(key)[:80], "label": str(field.get("label") or "Measure")[:120], "type": mtype, "source": "odoo", "default": bool(field.get("default", True)), "custom": True, "derived": True, "filterable": False, # W41-T21: the SAVED half of the same default, and it must stay identical to # `clean_measure_field`. A measure column already sitting in somebody's # workspace is rebuilt HERE, not there, so stamping only the create door would # leave every existing pct column with no summary and ship the feature half # dead. `pct` averages (a summed percentage is meaningless), currency and int # sum. Do not tidy the pct arm back to `sum`. "agg": ("average" if mtype == "pct" else "sum" if mtype in ("currency", "int") else None), "note": str(field.get("note") or "")[:2000], "measure": {"key": mkey[:80], "window": window}, **_field_extras(field, mtype, condition_fields=recurrence_keys), }) continue if not str(key).startswith("custom_"): continue ftype = field.get("type") if ftype not in CUSTOM_FIELD_TYPES: continue if ftype in READONLY_CUSTOM_TYPES: # Wave-5 items 9/11: the read-only user-created pair. Emitted with the cohort # column's mechanism (source 'odoo' + derived) so the client never offers an # editor and the host's overlay-write guard excludes them by construction. # FILTERABLE since wave 6 (owner item 6): their values live client-side # (formula computes over the row, created_time renders `_created`), this # table's counts are client-mode, and the windowed count path never sees # these tables β€” so the client engine answers them soundly. entry = { "key": str(key)[:80], "label": str(field.get("label") or "Untitled")[:120], "type": ftype, "source": "odoo", "derived": True, "filterable": True, "default": bool(field.get("default", True)), "custom": True, "note": str(field.get("note") or "")[:2000], **_field_extras(field, ftype, condition_fields=recurrence_keys), } if ftype == "formula": formula = _clean_formula(field.get("formula")) if formula is None: continue # a formula field without a formula is nothing entry["formula"] = formula if ftype == "if": from core.if_field import clean entry["if"] = clean(field.get("if")) entry["valueAuthority"] = "computed" out.append(entry) continue if field.get("source") != "overlay": continue options = (_clean_options(field.get("options")) if ftype in ("select", "multiselect") else []) out.append({ "key": str(key)[:80], "label": str(field.get("label") or "Untitled")[:120], "type": ftype, "source": "overlay", "default": bool(field.get("default", True)), "custom": True, # WAVE-29 C7: the whole vocabulary, not the `{"sum"}` literal that was here β€” a # picker offering Average against a projection that only passes Sum through is the # silent half of this feature. "agg": field.get("agg") if field.get("agg") in FIELD_AGGS else None, # W50-T05 / R4 β€” the DISPLAY mode rides the projection beside the aggregate it is # independent of: a Sum column may read as a share, and so may a column with no # summary at all. Dropped to None rather than defaulted, so an unknown spelling # cannot become a silent "value" that the picker then disagrees with. "showAs": field.get("showAs") if field.get("showAs") in SHOW_AS_MODES else None, "note": str(field.get("note") or "")[:2000], # A new choice field starts with no vocabulary and learns it from real writes. Its # empty options list must not silently retype it to text: the picker needs to stay a # picker so the first typed/pasted/imported value can create the first option. **({"options": options} if ftype in ("select", "multiselect") else {}), **(_choice_appearance(field, options) if ftype in ("select", "multiselect") else {}), # comma-joined SET semantics (the Cohorts column's contract): the row belongs to # every member, groups count it under each, the toolbar count stays distinct. **({"multi": True} if ftype == "multiselect" else {}), **({"max": _clean_rating_max(field.get("max"))} if ftype == "rating" else {}), **({"automation": _clean_automation(field.get("automation"))} if ftype == "automation" and _clean_automation(field.get("automation")) else {}), # ⭐ WAVE-27 item 13 (R13) β€” the code column's language rides the wire, because the # highlighter is chosen per column and the client cannot infer a language from a # string. Absent = `plain`, which is what an unconfigured code column renders as. **({"code": _clean_code(field.get("code"))} if ftype == "code" and _clean_code(field.get("code")) else {}), **_field_extras(field, ftype, condition_fields=recurrence_keys), }) if cohorts and not any(f.get('key') == COHORT_COLUMN for f in out): # ⚠ The emptiness check is WAVE 19's, and it is about the topics R9 opened this column to. # A user table's field keys are slugged from whatever its creator typed, so a column # literally called "Cohorts" produces the key `cohorts` β€” and appending here unguarded # would put TWO fields with one key on the wire. The client indexes fields by key, so the # duplicate does not error: it silently paints one column's values under the other's # header. The user's own column wins; the derived one steps aside rather than shadowing it. out.append(cohort_field()) return out def rows_from_pool(pool_rows, fields=None, overlays=None, derived=None, limits=None): """Map customer_data.pool() dicts -> the API row shape the grid expects: pid + each Odoo field (numeric fields rounded, text/date passed through) + the persisted external overlay. Mirrors the standalone API payload contract. `derived` is `{pid: {key: value}}` for columns the HOST computes per render rather than reads off the pool row β€” today just the cohort column. A separate argument from `overlays` on purpose: `overlays` is the PERSISTED user stratum, and putting a value there that is never written back would make the dict mean two things. `limits`, when supplied, collects reports for sourceless fields without changing the list return. """ fields = fields or FIELDS odoo_fields = [field for field in fields if field.get("source") == "odoo"] overlay_fields = [field for field in fields if field.get("source") == "overlay"] readable_fields = [field for field in fields if field.get("source")] if limits is not None: limits.extend({ "subject": field["key"], "effect": "unreadable", "cause": "The field definition has no source.", "recommendation": "Set the field definition's source before reading this column.", } for field in fields if not field.get("source")) derived_keys = [field["key"] for field in readable_fields if field.get("derived")] readable_keys = {field["key"] for field in readable_fields} overlays = overlays or {} derived = derived or {} out = [] for r in pool_rows: pid = r.get("pid") saved = overlays.get(str(pid), {}) or {} # `_created` (wave-5 item 11) rides every row like `pid` does β€” the datum the # `created_time` field type renders, regardless of that field's own key. Not a Field: # it has no column of its own until a user creates one. `lat`/`lon` (wave-7 W11) ride # the same way: the Map VIEW's data, nullable, deliberately not a column. row = {"pid": pid, "_created": r.get("_created") or "", "lat": r.get("lat"), "lon": r.get("lon")} notes = {} for source in (r, saved): mapped = source.get('__cell_notes__') if isinstance(mapped, dict): notes.update({key: text for key, text in mapped.items() if key in readable_keys and isinstance(text, str)}) if notes: row['__cell_notes__'] = notes for field in odoo_fields: k = field["key"] if field.get("derived"): continue # not on the pool row β€” filled from `derived` below v = r.get(k) if k == "maps_url" and saved.get(k): v = saved[k] # D-153 β€” three roundings, not two: text/status/date pass through verbatim, currency # and pct keep two decimals (`_round2`), everything else stays a whole number. if field["type"] == "int" and (field.get("format") or {}).get("decimals", 0) > 0: row[k] = v continue row[k] = v if field["type"] in {"text", "long_text", "status", "date"} else ( _round2(v) if field["type"] in {"currency", "pct"} else _round(v)) for field in overlay_fields: k = field["key"] # The pool may carry the mirror's sync stamp. It wins over a stale overlay, # including an explicit blank; never manufacture freshness from _created or now. row[k] = r.get(k, saved.get(k, "")) if ( k == "refreshed" and (field.get("automation") or {}).get("preset") ) else saved.get(k, "") got = derived.get(pid) or {} for k in derived_keys: # '' not None: a customer in no cohort has an EMPTY cohort list, and `is empty` on a # text column is the question somebody will ask of it. row[k] = got.get(k, "") out.append(row) return out # --- the FILTER-TREE contract (mirrors customer-grid/types.ts) --------------- # Ops the Airtable-parity condition builder can emit. isEmpty/isNotEmpty are # VALUE-FREE (they legitimately carry no value and must never be dropped for it). FILTER_OPS = {'contains', 'doesNotContain', 'eq', 'neq', 'isEmpty', 'isNotEmpty', 'gt', 'gte', 'lt', 'lte', 'between', 'within', # Wave 2026-08-02 (C-OPS): RANK operators β€” evaluated as a SET pass over the # sibling-filtered domain by the client engine (useVisibleRows). The validator # accepts them like any op (structural, not semantic); filter_sql REFUSES to # compile them to row SQL (a per-row WHERE cannot express Top-N). aboveAvg / # belowAvg are VALUE-FREE; the rest encode their argument in `value` as a # string int (topN/bottomN 1..10000, inTopPct/inBottomPct 1..100, # inQuartile 1..4, inDecile 1..10). Deliberately NOT in MEASURE_OPS: on a # measure-carrying column they rank the field's own derived values. 'topN', 'bottomN', 'inTopPct', 'inBottomPct', 'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile', # ⭐ W51-T07 (owner instruction 25): the MULTI-VALUE operators. Their operand is # the leaf's `values` LIST, not `value` β€” see MULTI_VALUE_OPS below. 'isAnyOf', 'isNoneOf', 'hasAnyOf', 'hasAllOf', 'hasNoneOf'} #: ⭐ W51-T07 β€” the MULTI-VALUE subset. Mirrors types.ts MULTI_VALUE_OPS and #: filter_sql.MULTI_VALUE_OPS. A leaf carrying one of these persists `values` as a REAL LIST and #: leaves `value` blank; `clean_filter_tree` therefore emits the list beside the usual members #: rather than passing it through the `str(val)[:500]` coercion, which would store the literal #: text of a Python list and make the condition unanswerable in every engine. MULTI_VALUE_OPS = {'isAnyOf', 'isNoneOf', 'hasAnyOf', 'hasAllOf', 'hasNoneOf'} #: How many values one multi-value condition may name. Mirrors types.ts MAX_FILTER_VALUES. MAX_FILTER_VALUES = 100 #: The RESERVED pseudo-column of a cohort-membership leaf (owner item 5, 2026-07-26). It is not #: a Field and never will be β€” a cohort is a hand-curated SET, so making it a column would mean #: a cell per row per cohort. Mirrors customer-grid/types.ts COHORT_FIELD. COHORT_FIELD = '__cohort__' #: Ops a cohort leaf may carry (owner, 2026-07-27): set operators over a SET of cohorts. #: Anything else is dropped. Deliberately DISJOINT from FILTER_OPS β€” see types.ts COHORT_OPS: #: a set op reaching a column leaf would fall through the client engine's switch to "no #: narrowing", so keeping the vocabularies apart makes the existing fail-closed drop do the work. COHORT_OPS = {'anyOf', 'allOf', 'noneOf'} #: ⭐⭐ WAVE-37 T26 (owner item 14, contract C4) β€” THE VIEW-MEMBERSHIP LEAF's reserved #: pseudo-column and its operators. Mirrors `customer-grid/types.ts` VIEW_FIELD / VIEW_OPS. #: #: β›” DISJOINT FROM `FILTER_OPS`, for the reason COHORT_OPS is: `matchFilter` answers an operator #: it does not know by NOT NARROWING, so an op that reached a column leaf would widen the result #: under an authoritative count. Keeping the two vocabularies apart means a column leaf carrying #: `inView` is dropped by the same fail-closed path that drops `dropTable`. #: ⚠ The leaf names exactly ONE view (singular where a cohort leaf names a set), so there is no #: all-or-nothing rule to get wrong here β€” the id either resolves or the leaf goes. VIEW_FIELD = '__view__' VIEW_OPS = {'inView', 'notInView'} MAX_VIEW_ID = 64 #: The single-cohort ops this leaf shipped with, kept as PERMANENT aliases and REWRITTEN here: #: `is part of [one]` is `is any of [that one]`, so a saved view keeps answering and upgrades the #: next time it is written. Mirrors types.ts COHORT_OP_ALIASES. COHORT_OP_ALIASES = {'eq': 'anyOf', 'neq': 'noneOf'} #: How many cohorts one condition may name. Mirrors types.ts MAX_COHORT_IDS. MAX_COHORT_IDS = 20 def parse_cohort_ids(value): """The cohorts a leaf names, parsed out of `value`. Mirrors types.ts `cohortIds()`. Comma-separated in one string because `FilterRule.value` is what all four layers persist and round-trip, and a one-element list is byte-identical to what the single-cohort leaf already stored β€” so every shipped view parses with no migration. Safe because a cohort id is built from `[a-z0-9_]` only (modules/cohort.new_id), so a comma cannot occur inside one. """ out = [] for raw in ('' if value is None else str(value)).split(','): cid = raw.strip()[:120] if not cid or cid in out: continue out.append(cid) if len(out) >= MAX_COHORT_IDS: break return out def parse_filter_values(values): """The values a multi-value leaf names. Mirrors types.ts `filterValues()` and `harness.filter_sql.parse_filter_values`. β›” A REAL LIST, and the contrast with `parse_cohort_ids` above is the decision, not an inconsistency: a cohort id cannot contain a comma, and a SELECT OPTION is tenant prose that perfectly well can ("Bouquets, mixed"). Comma-joining would split one real choice into two that match nothing. β›” AND UNLIKE the cohort leaf, this is NOT all-or-nothing: an unknown option string is KEPT (the ticket's `how` line). The all-or-nothing rule exists for cohorts because a dropped member WIDENS a `noneOf` question against a set the caller cannot even see; here the values are the column's own prose, a member that no longer exists simply matches nothing, and the chip that still shows it is what lets somebody remove it. Order preserved, blanks dropped, duplicates collapsed, members capped at 120 characters, the list capped at MAX_FILTER_VALUES. """ out = [] if not isinstance(values, (list, tuple)): return out for raw in values: val = ('' if raw is None else str(raw)).strip()[:120] if not val or val in out: continue out.append(val) if len(out) >= MAX_FILTER_VALUES: break return out # Airtable allows 3 nesting levels (root conditions -> group -> group), then grays # the button out. MAX_FILTER_DEPTH in types.ts must stay in lock-step with this. MAX_FILTER_DEPTH = 3 MAX_FILTER_NODES = 100 # total nodes across the whole tree MAX_FILTER_SIBLINGS = 50 # per level #: Shape of a measure condition's date window. aios_grid has ZERO app-internal imports by #: design, so it does NOT know the window VOCABULARY β€” `harness/windows.py` owns that, mirrored #: in `customer-grid/windows.ts`, and a third copy here is exactly the drift those two already #: need a gate to prevent. This validates SHAPE only. WINDOW_MAX_N = 3650 def _clean_window(raw): """Structural passthrough for a measure condition's `{kind, n?, from?, to?}` window. Meaning is NOT checked here: an unrecognised `kind` survives this function and is REFUSED by `harness.measure_filter.resolve_rule`, the layer that owns the vocabulary. Splitting it this way keeps the grid module reusable and keeps one definition of what "last quarter" means. """ if not isinstance(raw, dict): return None kind = raw.get('kind') if not isinstance(kind, str) or not kind or len(kind) > 40: return None out = {'kind': kind} if raw.get('n') is not None: try: out['n'] = max(1, min(int(raw['n']), WINDOW_MAX_N)) except (TypeError, ValueError): return None for side in ('from', 'to'): if raw.get(side) not in (None, ''): out[side] = str(raw[side])[:32] return out def _clean_rhs(raw, valid_keys): """CG-9 β€” validate `{kind, colId, window?}`, the "compare against another attribute" side. SHAPE and KEY only: `colId` must be something this table has (the caller widens `valid_keys` with the measure keys, exactly as it does for the left side), and a measure rhs must carry a window. What the window MEANS is `harness/windows.py`'s business, same split as `_clean_window`. """ if not isinstance(raw, dict): return None kind = raw.get('kind') if kind not in ('field', 'measure', 'stat'): return None if kind == 'stat': # A STATISTIC carries no column: the population is the comparand. Shape only β€” which # statistics exist is `harness/measure_filter.STATS`'s business, and an unrecognised one # is REFUSED there rather than guessed at, exactly like an unrecognised window kind. stat = raw.get('stat') if not isinstance(stat, str) or not stat or len(stat) > 24: return None return {'kind': 'stat', 'stat': stat} col = raw.get('colId') if col not in valid_keys: return None out = {'kind': kind, 'colId': col} if kind == 'measure': window = _clean_window(raw.get('window')) if window is None: return None # a measure comparand with no period is not a question out['window'] = window return out #: View DISPLAY MODES beside the grid (wave-6 item 10; 'map' wave-7 W11; 'dashboard' wave-8 #: I19). Mirrors customer-grid/types.ts DISPLAY_MODES; 'grid' is what an absent/unknown #: display means, so it is never stored. #: ⚠ 'dashboard' is RETAINED FOREVER (wave-9 I10, contract C2). The owner renamed the mode to #: "Chart" (a Dashboard MODULE is coming and the two would collide), but this set is the #: gatekeeper for a STORED value: `_clean_display` DROPS an unknown mode, so removing #: 'dashboard' here would silently downgrade every already-saved chart view to grid β€” and live #: views are sitting in mode:'dashboard' right now (wave 8's own close-out records one). The #: rename is therefore a stored-value MIGRATION, not a constant rename: accept 'dashboard' on #: READ forever, only ever WRITE 'chart'. #: ⭐ WAVE-27 item 8 (owner ruling R2, contract C3): 'swipe' β€” a DECK of the records whose bound #: single-select is EMPTY, triaged one at a time by swiping left or right into two of that #: field's options. Landed here FIRST and in the same change as the client registry, which is #: the whole reason the two modes above it needed a staged hold: `_clean_display` DROPS an #: unknown mode, so a client that offers a mode this set does not carry lets a user build a view #: that silently reverts to a grid on the next read. #: ⭐⭐ WAVE-29 R6/R7 (owner item 10, contract C3) β€” 'form', which CLOSES D-90. The client has #: carried `form` in its union, with an icon, a label and a tone, since wave 23; this set never #: did, so `_clean_display` DROPPED both the mode and the `display.form` spec on every write β€” #: while `routes_forms.py` reads exactly that key to serve the public submit door. The public door #: has therefore been live and UNREACHABLE for two waves: not broken, just impossible to point at #: anything. The mirror is one name, and it is the half nobody could see was missing because #: BOTH sides were individually consistent. #: ⚠ Being a legal stored mode is NOT the same as being offered: `form` is deliberately held out #: of the client's `CREATABLE_MODES` until `CustomerGrid` mounts a renderer for it (the hold law #: written into `iconShapes.ts`, and now machine-enforced in BOTH directions by #: `verify_icons.py::mode_parity` β€” offering an unmounted mode is red, and mounting an unoffered #: one is red too, so the hold cannot outlive its reason the way wave 27's did). DISPLAY_MODES = {'grid', 'list', 'calendar', 'kanban', 'map', 'dashboard', 'chart', 'catalog', 'swipe', 'form', 'gallery', 'timeline'} _RETIRED_MODES = {'timeseries'} #: ⭐⭐ WAVE-29 R7 (owner item 10, contracts C3/C4) β€” THE FORM INTERFACE's stored spec, at #: `views[<id>].config.display.form`. The public door (`aios-web/api/routes_forms.py`) has read #: exactly this key since wave 23 and NOTHING HAS EVER BEEN ABLE TO WRITE IT: `form` was not a #: legal mode and this function had no branch for the key, so every spec a client sent was dropped #: on the way in. That is D-90 stated precisely β€” not a broken feature, an unreachable one. #: #: β›” THE TOKEN IS NOT HERE, AND IT NEVER WILL BE. A share token that rides the wire is a token a #: browser can CHOOSE, and `routes_forms._resolve` walks tenants and answers with the FIRST match β€” #: so one tenant setting its token to another tenant's value would silently receive that tenant's #: submissions. The token is minted server-side and lives in a bucket no client write can reach; #: `_clean_form` drops any `token` key that arrives here, rather than validating its shape. #: ⭐⭐ WAVE-37 T21 (owner items 1/12, rulings R5+R6, contract C3) β€” THE PER-VIEW CATALOG SPEC, #: stored at `views[<id>].config.display.catalog`. #: #: β›”β›” IT IS **`catalog`**, SINGULAR, AND IT IS NOT `catalogs`. Both keys live on `display`, they #: are one letter apart, and that is the single most likely mistake anybody touching this file will #: make. They are different things and BOTH are live: #: Β· `catalogs` (wave-18 C6) β€” a LIST of up to 12 print artifacts, each with its own paper, #: brand and pages of kind cover/intro/section/gallery. Authored CONTENT. UNTOUCHED by T21. #: Β· `catalog` (wave-37 C3) β€” THIS view's catalog SETTINGS: which column is the picture, which #: is the title (R5: per view, so two catalog views on one database may differ), plus the page #: order and the free-placed items R6 asks for. #: Neither replaces the other, and neither validator reads the other's key. #: #: β›” THE MIGRATION IS A RULE ABOUT WHAT THIS FUNCTION MUST **NOT** DO (R6, C3). An item authored #: before free placement has no `x`/`y`, and an ABSENT coordinate must read back ABSENT β€” never #: normalised to 0. Defaulting to zero would pile every pre-existing item at the origin, which is #: "a catalog that silently loses its layout is a FAIL, not a migration" stated as code. The #: RENDERER turns an absent coordinate into flow position N; the host's whole job is to not destroy #: the distinction it reads. #: ⚠ `w`/`h` carry the OPPOSITE asymmetry, deliberately: a zero WIDTH is an invisible item, so 0 #: is refused and absent means "the renderer's default size". A zero X is the top-left corner and is #: a real, storable position. Two keys of one shape with two rules β€” the `kanbanClamp` family β€” #: which is why each is written out rather than looped. MAX_CATALOG_SECTIONS = 20 #: A bound on a hostile payload, not an opinion about the renderer's coordinate space: D owns what #: the numbers MEAN. Stored to 2 decimals, finer than any print surface resolves. MAX_CATALOG_COORD = 10000 #: The page `order` bound. ABSENT => that page's ARRAY INDEX, and `order` WINS where present; ties #: break by array index. Decided HERE rather than left to the renderer, because two readers guessing #: differently about page order is exactly the divergence contract C3 exists to close. MAX_CATALOG_ORDER = 9999 def _clean_catalog_coord(raw, allow_zero): """One free-placement number, or None. `allow_zero` False is the w/h leg (see the header). β›” THE ROUNDING IS `floor(v * 100 + 0.5) / 100` AND NOT `round(v, 2)`, AND THAT IS THE WHOLE POINT OF THIS FUNCTION EXISTING SEPARATELY. Python's `round` is BANKER'S rounding and JavaScript's `Math.round` is half-up-toward-+Infinity, so the two engines disagree on every exact half: `round(0.125, 2)` is 0.12 here and 0.13 in the browser. One dragged item landing two hundredths apart on the two engines is a `display` object that never compares equal β€” the silent mirror drift contract C2 exists to prevent, arriving through arithmetic instead of through a missing key. The expression below is `Math.floor(v * 100 + 0.5) / 100` written in Python, evaluated in the same IEEE doubles, so the two agree bit for bit. ⚠ AND AN INTEGRAL RESULT IS EMITTED AS AN `int`: `12.0` serialises as `12.0` in Python and `12` in JSON.stringify, which is one stored value with two spellings. """ if isinstance(raw, bool) or not isinstance(raw, (int, float)): return None if raw != raw or raw in (float("inf"), float("-inf")): # NaN / +-inf return None val = math.floor(float(raw) * 100 + 0.5) / 100 if val > MAX_CATALOG_COORD or val < -MAX_CATALOG_COORD: return None if not allow_zero and val <= 0: return None return int(val) if val == int(val) else val def _clean_catalog_item(raw): """One free-placed item: `{code, x?, y?, w?, h?}`. `code` REQUIRED; every coordinate optional. Key EMISSION ORDER is fixed and mirrored byte-for-byte by `types.ts::cleanCatalogSpec` β€” an accepted save has to read back identically on both engines, and this pair is where that is decided. """ if not isinstance(raw, dict): return None code = raw.get("code") if not isinstance(code, str) or not code.strip(): return None out = {"code": code.strip()[:CATALOG_CODE_MAX]} for key, allow_zero in (("x", True), ("y", True), ("w", False), ("h", False)): val = _clean_catalog_coord(raw.get(key), allow_zero) if val is not None: out[key] = val return out def _clean_catalog_spec(raw, valid_keys): """C3 β€” `display.catalog`, fail-closed. See the header block above for what it is NOT. Field refs follow the `dateField`/`stackField` rule this module already runs: a ref naming a deleted column is dropped INDIVIDUALLY and the renderer falls back to its per-mode default. It never costs the user their pages β€” the `charts` per-entry-drop precedent, applied to the one payload here that is AUTHORED rather than derived from the rows. """ if not isinstance(raw, dict): return None out = {} for ref in ("imageField", "titleField"): if raw.get(ref) in valid_keys: out[ref] = raw[ref] pages_raw = raw.get("pages") pages = [] if isinstance(pages_raw, list): # ONE cumulative item budget across the whole spec, spent in page order then section order # β€” the `_clean_catalogs` construction, so a 40-page catalog cannot smuggle 20,000 items # past a per-page cap. budget = MAX_CATALOG_CODES seen_pages = set() for raw_page in pages_raw: if len(pages) >= MAX_CATALOG_PAGES: break if not isinstance(raw_page, dict): continue pid = str(raw_page.get("id") or "").strip()[:CATALOG_ID_MAX] if not pid or pid in seen_pages: continue seen_pages.add(pid) page = {"id": pid} order = raw_page.get("order") if (isinstance(order, int) and not isinstance(order, bool) and 0 <= order <= MAX_CATALOG_ORDER): page["order"] = order sections_raw = raw_page.get("sections") sections = [] if isinstance(sections_raw, list): seen_sections = set() for raw_section in sections_raw: if len(sections) >= MAX_CATALOG_SECTIONS: break if not isinstance(raw_section, dict): continue sid = str(raw_section.get("id") or "").strip()[:CATALOG_ID_MAX] if not sid or sid in seen_sections: continue seen_sections.add(sid) section = {"id": sid} items_raw = raw_section.get("items") items = [] if isinstance(items_raw, list) and budget > 0: for raw_item in items_raw: item = _clean_catalog_item(raw_item) if item is None: continue items.append(item) budget -= 1 if budget <= 0: break # ⚠ NOT de-duplicated by `code`. The same product legitimately appears twice in # one section at two positions β€” that is what free placement IS β€” and wave-18's # "deduped WITHIN a page" rule was written for a LISTING, where a repeat is a # mistake. Here it is the feature. if items: section["items"] = items sections.append(section) # An EMPTY section is KEPT: a person adds a New Section and then drags into it, and # dropping it would delete the thing they just made, between two autosaves. if sections: page["sections"] = sections pages.append(page) if pages: out["pages"] = pages # A spec that reduces to nothing is DROPPED, never stored as `{}`. "No image field, no title # field, no pages" IS the unconfigured state, and `{}` would be its second spelling β€” the # no-churn law every literal-only key in `_clean_display` follows. return out or None FORM_ACCESS = ('public', 'emails') MAX_FORM_FIELDS = 60 MAX_FORM_EMAILS = 200 MAX_FORM_TITLE, MAX_FORM_DESC, MAX_FORM_SUBMIT = 120, 1000, 60 MAX_FORM_EMAIL = 254 #: The field types a form may COLLECT, as an ALLOW-LIST rather than a list of exclusions β€” the #: fail-closed direction, because the cost of the two mistakes is not symmetric. A type missing #: from here is a question the builder cannot ask yet; a type wrongly present is a public door #: writing values the column cannot mean (an `image` with no upload channel, a `json` document #: typed into a text box, a `link` naming a record id a stranger guessed). #: ⚠ NOT sufficient on its own, and the reason is a shape this codebase has been bitten by before: #: a METRIC bag rides ANY field type (`core/user_tables.py` β€” `metric` is not a field kind), so an #: `int` column can be machine-computed while passing this list. `routes_forms` therefore asks #: `user_tables.is_computed_cell` as well β€” one evaluator for "is this computed", reused rather #: than re-derived ([[one-evaluator-per-question]]). #: Client mirror: `customer-grid/FormInterface.tsx` FORM_FIELD_TYPES; `verify_forms.py` compares #: the two files name-for-name. FORM_FIELD_TYPES = ('text', 'select', 'multiselect', 'int', 'currency', 'pct', 'date', 'checkbox', 'phone', 'email', 'url', 'rating') #: Deliberately looser than a full RFC parse and stricter than `routes_forms._clean_values`' "@ in #: it": this list decides who MAY SUBMIT, so a typo that silently locks a colleague out is the #: expensive failure, not an odd address that gets in. _FORM_EMAIL = re.compile(r'^[^@\s,;]+@[^@\s,;]+\.[^@\s,;]+$') def _clean_form(raw, valid_keys): """One form spec, fail-closed. Returns None when nothing is configured. ⚠ FIELD ORDER IS THE FORM'S OWN and is preserved here, not re-derived from the schema: the builder let somebody arrange these questions, and sorting them by column order would silently rearrange a live form every time a column was added (`_public_form` states the same rule from the serving end). ⚠ PARTIAL-DROP, not whole-key drop, and the asymmetry against `swipe` above is deliberate. A swipe binding is one three-part machine: two of its parts is not a degraded deck, it is a deck that can never write. A form is a LIST of questions β€” losing the column behind question three costs the asker question three, and taking the whole form away because one field was deleted would be a far larger loss than the one that happened. """ if not isinstance(raw, dict): return None fields, seen = [], set() for k in (raw.get('fields') or [])[:MAX_FORM_FIELDS]: if k in valid_keys and k not in seen: seen.add(k) fields.append(k) out = {} if fields: out['fields'] = fields # A required flag on a question the form no longer asks is not a rule, it is a trap: the # submitter can never satisfy it and the sentence names a field they cannot see. req = [k for k in dict.fromkeys(raw.get('required') or []) if k in seen] if req: out['required'] = req for key, cap in (('title', MAX_FORM_TITLE), ('desc', MAX_FORM_DESC), ('submitLabel', MAX_FORM_SUBMIT)): text = str(raw.get(key) or '').strip()[:cap] if text: out[key] = text # `public` is the ABSENT default (the `kanbanClamp` law: one way to say one thing), so only # the restrictive value is ever stored. β‡’ a spec that loses its `access` key fails OPEN, which # is why `emails` is what gets written rather than a `public: false`. if raw.get('access') == 'emails': out['access'] = 'emails' emails = [] for e in (raw.get('emails') or [])[:MAX_FORM_EMAILS]: e = str(e or '').strip().lower()[:MAX_FORM_EMAIL] if _FORM_EMAIL.match(e) and e not in emails: emails.append(e) # Kept even while `access` is public: a person toggling the door open to test it and back # again must not lose the list of people they typed. It is never served publicly. if emails: out['emails'] = emails return out or None #: C3 β€” the swipe binding's option cap. `leftOption`/`rightOption` are stored VALUES of a #: single-select, and `_clean_options` trims every choice to 120 chars, so this is that same #: number rather than a second opinion about it: a longer string cannot name a real option, and #: a SHORTER cap here would silently refuse a binding to a legal one. MAX_SWIPE_OPTION = 120 #: C-DISP (wave 2026-08-02): the time-series view's bucket vocabulary and caps, plus the #: calendar-summary metric cap. types.ts mirrors these as TS_BUCKETS / TS_MAX_LAST_N / #: TS_MAX_FIELDS / MAX_CALENDAR_METRICS, and cleanDisplay applies the same per-entry drops, #: so an accepted save reads back byte-identically on both engines. TS_BUCKETS = {'week', 'month', 'quarter', 'year'} TS_MAX_LAST_N = 120 TS_MAX_FIELDS = 12 MAX_CALENDAR_METRICS = 4 _ISO_DAY = re.compile(r'^\d{4}-\d{2}-\d{2}$') #: C6-CATALOG (wave 18) β€” the catalog view's vocabulary and caps. types.ts mirrors every name #: below, and `cleanDisplay` applies the same drops in the SAME ORDER, so an accepted save reads #: back identically on both engines. The code budget is the order-sensitive one β€” see #: `_clean_catalogs`. MAX_CATALOGS = 12 MAX_CATALOG_PAGES = 40 MAX_CATALOG_CODES = 500 # cumulative across ONE catalog's pages, spent in PAGE ORDER CATALOG_PAPERS = {'letter', 'a4', 'tabloid'} CATALOG_ORIENTATIONS = {'portrait', 'landscape'} CATALOG_QUALITIES = {'web', 'print'} CATALOG_PAGE_KINDS = {'cover', 'intro', 'section', 'gallery'} CATALOG_COLS = (2, 3, 4) CATALOG_ID_MAX, CATALOG_NAME_MAX = 40, 80 CATALOG_TITLE_MAX, CATALOG_BODY_MAX, CATALOG_CODE_MAX = 120, 2000, 60 _HEX6 = re.compile(r'^#[0-9A-Fa-f]{6}$') #: Wave 14 C-ACC ([[loopable-wave14-split]]; rulings R2/R3). Mirrored by types.ts #: TS_DELTA_KINDS / TS_MAX_CUSTOM_ROWS / TS_MAX_STYLES β€” the C-DISP byte-identical law. TS_DELTA_KINDS = ('abs', 'pct', 'yoy', 'ytd') TS_MAX_CUSTOM_ROWS = 12 TS_MAX_STYLES = 200 TS_MAX_EXPR = 500 def _ts_formula_source_ok(expr): """Transport wall for a Time Series formula governed by the shared server parser. This function deliberately does not duplicate the formula grammar. It preserves any bounded source, including quotes and regex punctuation, for the API parser to accept or explain. The sole syntax-shaped refusal is an unquoted square bracket: the shared contract declares that legacy ``[field]`` references cannot enter the braces-only grammar. Brackets inside a quoted regex/text literal remain ordinary source and round-trip byte-for-byte. """ if not isinstance(expr, str) or len(expr) > TS_MAX_EXPR: return False quote, i = None, 0 while i < len(expr): char = expr[i] if quote: if char == quote: if i + 1 < len(expr) and expr[i + 1] == quote: i += 2 continue quote = None i += 1 continue if char in ("'", '"'): quote = char elif char in '[]': return False i += 1 return True #: Old wire value -> the value we store today. Applied AFTER the membership test so an unknown #: mode is still rejected rather than accidentally aliased. _LEGACY_MODES = {'dashboard': 'chart'} #: Chart kinds a chart-mode view may hold (wave-8 I19, contract C2). Mirrors the client's #: union. Deliberately small: the owner asked to "start with simple charts" and expand, and a #: kind the client cannot draw is worse than one that does not exist yet. #: Wave-16 C-CHARTCAP: + 'table' β€” the group-by aggregate table (by-rep / by-BU / #: top-customers, the third Sales block shape). Client renderer: DashboardView's #: GroupTableView over salesParity.tableFromSpec. CHART_KINDS = {'bar', 'line', 'area', 'donut', 'kpi', 'table'} CHART_AGGS = {'sum', 'avg', 'count', 'min', 'max'} #: ⭐ WAVE-29 C7 (item 17) β€” THE COLUMN-SUMMARY vocabulary: what a FIELD's `agg` may be, which is #: what the grid's totals row and its per-group subtotals compute. ORDERED, because the order is #: the picker's order; membership tests read it as a tuple perfectly well. #: #: β›” IT IS NOT `CHART_AGGS` AND THE TWO MUST NOT BE MERGED, however alike they look. `CHART_AGGS` #: gatekeeps a STORED value with live data behind it (`charts[].agg`, `calendarMetrics[].agg`): #: `_clean_chart` falls back to 'sum' on an unknown agg and `_clean_display` DROPS a whole #: calendarMetrics entry, so renaming its 'avg' would silently turn every saved chart into a sum #: and delete calendar cards, with nothing red. A chart's aggregation and a column's summary are #: also different questions β€” one reduces a SERIES, the other a COLUMN β€” and one list serving both #: would have to be the intersection of what each can express. #: #: ⭐ `average`, NOT `avg`, and the tie is broken by the vocabulary we cannot rename: `ROLLUP_FNS` #: (`core/user_tables.py`, 16 names, 47 rollups live in production) already spells it `average`, #: and it is the aggregate vocabulary a user actually reads today. Spelling it `avg` here would #: give the product two words for one operation on two menus a click apart. #: #: ⚠ `median` is net-new: it is in NEITHER `CHART_AGGS` nor `ROLLUP_FNS`, so a Median column #: summary has no rollup equivalent and this list is NOT a subset of either of its neighbours. #: #: ⚠ `count` counts ROWS in the scope (the group, or every matched row) β€” not non-blank cells. #: `ROLLUP_FNS` splits that hair three ways (count / counta / countall); a column summary does not, #: and must not grow a second spelling of it. #: #: Client mirror: `customer-grid/iconShapes.ts` FIELD_AGGS β€” ONE client list, imported by #: `aggregations.ts` and the field editor rather than re-declared, so the only boundary left to #: police is this one. `verify_icons.py::agg_parity` reads BOTH FILES and compares them. FIELD_AGGS = ('sum', 'average', 'median', 'min', 'max', 'count') #: ⭐⭐ WAVE 50 Β· W50-T03 Β· CONTRACT C1 (owner rulings R1 + R2) β€” **THE SUMMARY BAR'S WIRE #: VOCABULARY, AND IT IS DELIBERATELY NOT `FIELD_AGGS` WITH TWO MORE NAMES.** #: #: C1, verbatim: ``agg ∈ sum | average | median | min | max | count | count_distinct | #: percentile`` with ``p`` 0-100 for ``percentile``. This tuple is that clause, in that order, #: and it is what the windowed-aggregate route (``POST /api/v1/odoo-tables/<key>/aggregates``) #: admits an ``agg`` against. #: #: β›” WHY NOT WIDEN `FIELD_AGGS`. That list is what a FIELD's ``agg`` may be, and THREE literals #: gate a WRITE on it β€” this one, ``core/user_tables.FIELD_AGGS`` (``_clean_field``, the door #: that silently discards an ``agg`` it does not recognise) and the client's #: ``customer-grid/iconShapes.FIELD_AGGS`` β€” held name-for-name in order by #: ``verify_icons.py::agg_parity``. R2 moved the summary choice OFF ``field.agg`` and onto the #: VIEW (``ViewConfig.summary``), so adding ``count_distinct`` and ``percentile`` there would #: widen a per-field setting the ruling just retired, in three files, for no consumer. The two #: vocabularies OVERLAP by six names and are not one list β€” the same relationship ``FIELD_AGGS`` #: already has with ``CHART_AGGS`` and ``ROLLUP_FNS``. #: #: Client mirror: ``customer-grid/iconShapes.SUMMARY_AGGS``, held in step by #: ``aios-web/web/verify_grid_ux.py``'s summary-bar section against C1's clause typed in frozen. #: ⚠ ``count_distinct`` is the SQL name, not ``unique``: the word on screen lives in the client's #: label table, and a wire vocabulary that spells itself the way the screen does is one rename #: away from meaning nothing to the compiler. SUMMARY_AGGS = ('sum', 'average', 'median', 'min', 'max', 'count', 'count_distinct', 'percentile') #: ⭐ W50-T05 / R4 β€” how a numeric column READS: its own value, its share of the VIEW's grand total, #: or the value with the share beneath it. Client mirror: ``ui/fmt.ts::SHOW_AS_MODES``; the server #: twin that validates the write is ``core/user_tables.SHOW_AS_MODES``. #: #: β›” THIS IS THE THIRD LIST IN THIS FILE THAT LOOKS MERGEABLE AND IS NOT, and the note above #: already records what merging two of them costs. ``FIELD_AGGS`` and ``SUMMARY_AGGS`` both answer #: WHICH NUMBER to compute over a set of rows; this answers HOW THE NUMBER ALREADY IN THE CELL IS #: DRAWN. They are independent by design β€” a Sum column can read as a share, and so can a column #: carrying no summary at all β€” so a field can hold one value from each list at the same time. SHOW_AS_MODES = ('value', 'share', 'both') MAX_CHARTS = 12 #: per view β€” a dashboard, not an unbounded render loop MAX_CHART_TITLE = 60 #: Wave-9 I11 (contract C2) β€” chart customisation, host-validated. #: #: `palette` names a colour JOB, never a colour. A browser must not be able to post a raw hex: #: the four names below map to the four jobs a palette can do (identity / magnitude / polarity) #: and resolve to brand ramps client-side, so a tenant restyle cannot be defeated by a stored #: literal. STATUS colours (good/warning/serious/critical) are deliberately NOT selectable β€” #: they are reserved signal, and reusing them as "series 4" is how a chart starts lying. CHART_PALETTES = {'brand', 'categorical', 'sequential', 'diverging'} CHART_FORMATS = {'auto', 'number', 'currency', 'percent', 'compact'} MAX_AXIS_LABEL = 40 #: `size` is the I10 drag. Width is in GRID COLUMNS (a 12-column board), height in px. CHART_W_RANGE = (1, 12) CHART_H_RANGE = (120, 800) def _clean_chart(raw, valid_keys): """One dashboard chart, fail-closed. Returns None if the chart cannot be drawn. A chart's `y` is optional (absent = count of rows, which is what "how many customers per state" means). `x` is NOT: a chart with no category axis has nothing to plot against, and silently keeping it would put an empty card on the dashboard with no way to tell why. """ if not isinstance(raw, dict): return None kind = raw.get('kind') if kind not in CHART_KINDS: return None x = raw.get('x') if x not in valid_keys: return None # dead category ref -> the chart goes, not the board cid = raw.get('id') if not isinstance(cid, str) or not cid.strip(): return None # the client owns chart ids; an unidentified card # cannot be edited or removed, so it must not persist out = {'id': cid.strip()[:64], 'kind': kind, 'x': x, 'agg': raw.get('agg') if raw.get('agg') in CHART_AGGS else 'sum'} if raw.get('y') in valid_keys: out['y'] = raw['y'] else: # no measurable column -> the only honest aggregation left is "how many rows" out['agg'] = 'count' title = raw.get('title') if isinstance(title, str) and title.strip(): out['title'] = title.strip()[:MAX_CHART_TITLE] # ── wave-9 I11 (contract C2): customisation ──────────────────────────────────────────── # `splitBy` is the field whose values become the SERIES. It is deliberately not called # `colorBy`: that name already means two other things here (`config.colorBy` = row # colouring, `display.colorField` = map pin colour) and a third sense would be unreadable. if raw.get('splitBy') in valid_keys and raw['splitBy'] != x: out['splitBy'] = raw['splitBy'] # Stacking is only a question once there are series to stack, and only for the two kinds # that can express it. Anywhere else it is dropped rather than stored as a lie the client # would have to re-decide. if out.get('splitBy') and kind in ('bar', 'area') and raw.get('stacked') is True: out['stacked'] = True if raw.get('palette') in CHART_PALETTES: out['palette'] = raw['palette'] axis = raw.get('axis') if isinstance(axis, dict): # β›” ONE y-scale, always. There is no second-axis key here and there must never be: # two y-scales on one frame can manufacture any correlation you like by rescaling, and # the honest alternatives are two charts, small multiples, or indexing to a common base. # Ruled explicitly in contract C2 against the "Tableau versatility" brief. clean_axis = {} for side in ('x', 'y'): spec = axis.get(side) if not isinstance(spec, dict): continue one = {} lab = spec.get('label') if isinstance(lab, str) and lab.strip(): one['label'] = lab.strip()[:MAX_AXIS_LABEL] if spec.get('format') in CHART_FORMATS: one['format'] = spec['format'] if one: clean_axis[side] = one if clean_axis: out['axis'] = clean_axis size = raw.get('size') if isinstance(size, dict): one = {} for key, (lo, hi) in (('w', CHART_W_RANGE), ('h', CHART_H_RANGE)): try: one[key] = max(lo, min(hi, int(size[key]))) except (KeyError, TypeError, ValueError): pass # a partial size is fine: the client defaults the missing axis if one: out['size'] = one # ── Wave 14 R3 ([[loopable-wave14-split]]): a METRIC chart may carry a PERIOD β€” the # trend-over-buckets encoding. Kept only when the chart's value field is measure-backed: # a category column has no time dimension, and a stored period on it would promise a # trend the TS channel must refuse. `span` is meaningful only beside `bucket`. if isinstance(out.get('y'), str) and out['y'].startswith('measure_'): if raw.get('bucket') in TS_BUCKETS: out['bucket'] = raw['bucket'] sp = raw.get('span') if isinstance(sp, dict): n = sp.get('lastN') if (isinstance(n, int) and not isinstance(n, bool) and 1 <= n <= TS_MAX_LAST_N): out['span'] = {'lastN': n} # ── Wave-16 C-CHARTCAP: the YoY companion. Kept ONLY where it can mean something β€” # beside a kept bucket (the compare series) or on a sum-of-metric KPI (the delta # line). Anything else is a stored claim the renderer would have to re-refuse. # Mirrors the client's cleanCharts rule key for key. if raw.get('compare') == 'prior_year' and ( out.get('bucket') or (kind == 'kpi' and out.get('agg') == 'sum')): out['compare'] = 'prior_year' return out def _clean_catalog_page(raw, budget): """C6-CATALOG β€” one page of a catalog. Returns `(page | None, codes_spent)`. `budget` is what is LEFT of the catalog's 500-code allowance. Codes are deduped WITHIN a page and not across the catalog: a product legitimately appears on a gallery page and again in its section listing, and de-duplicating globally would silently delete the second appearance. The budget is spent in page order, so a catalog that runs out loses the TAIL of its last pages β€” never a random scatter, and never a page (a page with no products is a heading the user can still see and fix). """ if not isinstance(raw, dict): return None, 0 page_id = str(raw.get('id') or '')[:CATALOG_ID_MAX] kind = raw.get('kind') if not page_id or kind not in CATALOG_PAGE_KINDS: return None, 0 out = {'id': page_id, 'kind': kind} for key, cap in (('title', CATALOG_TITLE_MAX), ('body', CATALOG_BODY_MAX), ('imageCode', CATALOG_CODE_MAX)): v = raw.get(key) if isinstance(v, str) and v: out[key] = v[:cap] products = raw.get('products') if isinstance(products, list) and budget > 0: clean_p, seen_p = [], set() for c in products: if not isinstance(c, str) or not c: continue c = c[:CATALOG_CODE_MAX] if c in seen_p: continue seen_p.add(c) clean_p.append(c) if len(clean_p) >= budget: break if clean_p: out['products'] = clean_p layout = raw.get('layout') if isinstance(layout, dict): clean_l = {} cols = layout.get('cols') if isinstance(cols, int) and not isinstance(cols, bool) and cols in CATALOG_COLS: clean_l['cols'] = cols # The kanbanClamp/tsSparkline asymmetry, one per direction: pack and colour SHOW by # default (the 2027 catalogue shows both), price does NOT (it shows no prices at all). # So only the opt-OUT is storable for the first two and only the opt-IN for the third β€” # a second spelling of a default is how a round trip starts churning. if layout.get('showPack') is False: clean_l['showPack'] = False if layout.get('showColor') is False: clean_l['showColor'] = False if layout.get('showPrice') is True: clean_l['showPrice'] = True if clean_l: out['layout'] = clean_l return out, len(out.get('products') or ()) def _clean_catalogs(raw, valid_keys): """C6-CATALOG (wave 18) β€” `display.catalogs`, fail-closed. Returns a list or None. A catalog is a PRINT artifact, so the two structural keys that decide how it paginates (`paper`, `orientation`) are NORMALISED WITH A DEFAULT rather than dropped: a page box with no size is not a smaller catalog, it is an unrenderable one. Everything else follows the house rules β€” unknown keys dropped, per-entry drops never cost the neighbours, empty sub-objects omitted entirely (`brand`, `fields`, `layout`, `products`) so an absent key and an empty one are not two spellings of the same nothing. `fields` binds the listing lines to real columns (the 2027 listing prints description / SKU / pack / colour, and `product_data` carries no pack or colour of its own β€” the user binds custom fields). Refs are checked against `valid_keys` HERE and not on the client, the same split `dateField`/`stackField` already run. """ if not isinstance(raw, list): return None out = [] for c in raw: if len(out) >= MAX_CATALOGS: break if not isinstance(c, dict): continue cat_id = str(c.get('id') or '')[:CATALOG_ID_MAX] name = c.get('name') # An EMPTY name is legal (the user cleared the box and will type again) β€” an ABSENT one # is a malformed record. The `tsRows` label rule, same reasoning. if not cat_id or not isinstance(name, str): continue cat = {'id': cat_id, 'name': name[:CATALOG_NAME_MAX]} cat['paper'] = c['paper'] if c.get('paper') in CATALOG_PAPERS else 'letter' cat['orientation'] = (c['orientation'] if c.get('orientation') in CATALOG_ORIENTATIONS else 'portrait') if c.get('quality') in CATALOG_QUALITIES: cat['quality'] = c['quality'] brand = c.get('brand') if isinstance(brand, dict): clean_b = {} for k in ('primary', 'accent'): v = brand.get(k) if isinstance(v, str) and _HEX6.match(v): clean_b[k] = v company = brand.get('company') if isinstance(company, str) and company: clean_b['company'] = company[:CATALOG_NAME_MAX] # An asset CODE (resolved through C2-ASSET), never a URL: an arbitrary host inside # print CSS is exactly the tokens-not-values rule this contract carries. logo = brand.get('logo') if isinstance(logo, str) and logo: clean_b['logo'] = logo[:CATALOG_CODE_MAX] if clean_b: cat['brand'] = clean_b binds = c.get('fields') if isinstance(binds, dict): clean_bind = {k: binds[k] for k in ('name', 'pack', 'color', 'price') if binds.get(k) in valid_keys} if clean_bind: cat['fields'] = clean_bind pages, budget = [], MAX_CATALOG_CODES raw_pages = c.get('pages') if isinstance(raw_pages, list): for p in raw_pages: if len(pages) >= MAX_CATALOG_PAGES: break page, spent = _clean_catalog_page(p, budget) if page is None: continue budget -= spent pages.append(page) # ALWAYS emitted, even empty: a catalog with no pages yet is the state every catalog # starts in, and dropping the key would make "new" and "corrupt" the same wire value. cat['pages'] = pages out.append(cat) return out or None def _clean_display(raw, valid_keys): """Structural passthrough for a view's `config.display` (wave-6 item 10), fail-closed. `{mode, dateField?, stackField?, titleField?, colorField?, sizeField?, coordField?, charts?}` β€” mode must be known. `coordField` is retained only to read older saved Views; new Map source setup is database-owned. Every field ref must name a field this table has (a ref to a deleted field is DROPPED and the client falls back to its per-mode default); unknown keys are dropped. What each mode MEANS β€” calendar wants a date-family field, kanban a select-family stack, map a single-select to colour by and a numeric to size by β€” is the client's business: it is the only layer that renders them, and a wrong-typed ref degrades to that surface's default rather than to an error (the `_clean_window` split). Wave-8 (contract C2) adds the map encodings (`colorField` I3, `sizeField` I5) and dashboard `charts` (I19). A chart whose x/y names a deleted field is dropped INDIVIDUALLY β€” never the whole array, because losing one column should not cost the user a dashboard they spent time building. W33-T45 (contract C1, ruling R5) adds `published` + `publishAccess`. ⚠ THE HALF OF THE ROUND TRIP THIS FUNCTION CANNOT ENFORCE: `customer-grid/types.ts::cleanDisplay` is a SECOND normalizer, in the browser, which rebuilds the config key by key on every autosave and drops anything it does not name. A key accepted here and unknown there dies on the next column resize β€” silently, because the client then POSTs the stripped config and the host REPLACES the stored one. "The host accepts it" is half a round trip; that file is the other half. """ if not isinstance(raw, dict): return None # Boot purges run while requests are live. Preserve retired identity until removal, # so a racing workspace rewrite cannot silently turn a retired view into a grid. if raw.get('mode') in _RETIRED_MODES: return {'mode': raw['mode']} # W48-T07 / R3 β€” view configuration is data interpreted by deployed renderers, never # tenant-supplied executable code. Reject the common script escape hatches rather than # silently dropping them, which would make a caller believe an expression was persisted. if any(key in raw for key in ('expr', 'formula', 'signal', 'fn')): return None mode = raw.get('mode') if mode not in DISPLAY_MODES: return None # Grid is normally represented by an absent display object. Retain a valid legacy Map source # when an older configured Map view returns here, while refusing every unrelated Grid-only # display setting. Without this compatibility exception existing views lose their pins on the # next server round trip. if mode == 'grid': coord_field = raw.get('coordField') if raw.get('groupSummary') is not True: return {'mode': 'grid', 'coordField': coord_field} if coord_field in valid_keys else None # The C1 display member carries the grid's group summary toggle. Store only True. out = {'mode': 'grid', 'groupSummary': True} if coord_field in valid_keys: out['coordField'] = coord_field return out # Wave-9 I10 (C2): normalise the legacy wire value AFTER the membership test, so an unknown # mode is still rejected rather than accidentally aliased into a real one. Every already # saved 'dashboard' view reads back as 'chart' from here on; nothing writes 'dashboard'. mode = _LEGACY_MODES.get(mode, mode) out = {'mode': mode} if raw.get('groupSummary') is True: out['groupSummary'] = True # `coordField` is the older per-View fallback. Keep it in the regular field-ref loop so a # deleted source fails safely; the current source is served separately as database setup. for ref in ('dateField', 'stackField', 'titleField', 'colorField', 'sizeField', 'coordField'): if raw.get(ref) in valid_keys: out[ref] = raw[ref] # ── C-DISP (wave 2026-08-02) ───────────────────────────────────────────────────────── # kanbanClamp: stored ONLY as the literal opt-OUT. Absent means clamped β€” the new # standardized default β€” so storing True would be a second way to say nothing (the same # rule that keeps mode:'grid' out of the store). if raw.get('kanbanClamp') is False: out['kanbanClamp'] = False if raw.get('calendarMode') in ('records', 'summary'): out['calendarMode'] = raw['calendarMode'] metrics = raw.get('calendarMetrics') if isinstance(metrics, list): clean_m, seen_m = [], set() for m in metrics[:MAX_CALENDAR_METRICS]: # Dropped INDIVIDUALLY (the charts precedent): one dead metric must not cost the # user the summary card they configured around it. if not isinstance(m, dict): continue mid = str(m.get('id') or '')[:40] if (not mid or mid in seen_m or m.get('field') not in valid_keys or m.get('agg') not in CHART_AGGS): continue seen_m.add(mid) clean_m.append({'id': mid, 'field': m['field'], 'agg': m['agg']}) if clean_m: out['calendarMetrics'] = clean_m if raw.get('tsBucket') in TS_BUCKETS: out['tsBucket'] = raw['tsBucket'] span = raw.get('tsSpan') if isinstance(span, dict): clean_span = {} n = span.get('lastN') if isinstance(n, int) and not isinstance(n, bool) and 1 <= n <= TS_MAX_LAST_N: clean_span['lastN'] = n else: f, t = span.get('from'), span.get('to') f = f if isinstance(f, str) and _ISO_DAY.match(f) else None t = t if isinstance(t, str) and _ISO_DAY.match(t) else None if f and t and f > t: f, t = t, f if f: clean_span['from'] = f if t: clean_span['to'] = t if clean_span: out['tsSpan'] = clean_span ts_fields = raw.get('tsFields') if isinstance(ts_fields, list): clean_f, seen_f = [], set() for k in ts_fields[:TS_MAX_FIELDS]: if k in valid_keys and k not in seen_f: seen_f.add(k) clean_f.append(k) if clean_f: out['tsFields'] = clean_f # Native series are declarative measure references, never generated tenant fields. ts_metrics = raw.get('tsMetrics') if isinstance(ts_metrics, list): clean_m, seen_m = [], set() for item in ts_metrics[:TS_MAX_FIELDS]: if not isinstance(item, dict): continue key = str(item.get('key') or '').strip()[:80] if not key or key in seen_m: continue seen_m.add(key) metric = {'key': key} label = str(item.get('label') or '').strip()[:120] if label: metric['label'] = label clean_m.append(metric) if clean_m: out['tsMetrics'] = clean_m # ── Wave 14 C-ACC ([[loopable-wave14-split]] R2; items 17/18) ──────────────────────── deltas = raw.get('tsDeltas') if isinstance(deltas, list): clean_d, seen_d = [], set() for d in deltas: if d in TS_DELTA_KINDS and d not in seen_d: seen_d.add(d) clean_d.append(d) if clean_d: out['tsDeltas'] = clean_d # Gridlines: stored ONLY as the literal opt-OUT (absent = shown), sparkline ONLY as the # literal opt-IN (absent = off) β€” the kanbanClamp asymmetry, one per direction. if raw.get('tsGridlines') is False: out['tsGridlines'] = False if raw.get('tsSparkline') is True: out['tsSparkline'] = True rows = raw.get('tsRows') if isinstance(rows, list): clean_r, seen_r = [], set() for r in rows[:TS_MAX_CUSTOM_ROWS]: if not isinstance(r, dict): continue rid = str(r.get('id') or '')[:40] r_kind = r.get('kind') if not rid or rid in seen_r or r_kind not in ('note', 'formula'): continue label = r.get('label') if not isinstance(label, str): continue # ABSENT label = malformed; an EMPTY one is a legal spacer row # (GRID's dated asymmetry amendments, 2026-08-02) one = {'id': rid, 'kind': r_kind, 'label': label.strip()[:120]} if r_kind == 'formula': expr = r.get('expr') if _ts_formula_source_ok(expr): one['expr'] = expr # Else keep the ROW and drop only the source. Legacy square references and # over-bound transport cannot enter the shared formula parser; deleting the row # would also delete the user's label and its saved order. seen_r.add(rid) clean_r.append(one) if clean_r: out['tsRows'] = clean_r styles = raw.get('tsStyles') if isinstance(styles, dict): clean_s = {} for s_key, s_val in styles.items(): if len(clean_s) >= TS_MAX_STYLES: break # capped, not truncated silently: the gate names this if not isinstance(s_key, str) or not s_key or len(s_key) > 96: continue # key = rowId or "rowId:colKey" β€” the client's grammar if not isinstance(s_val, dict): continue one = {} if s_val.get('bold') is True: one['bold'] = True if s_val.get('line') is True: one['line'] = True if one: clean_s[s_key] = one if clean_s: out['tsStyles'] = clean_s charts = raw.get('charts') if isinstance(charts, list): clean = [c for c in (_clean_chart(x, valid_keys) for x in charts[:MAX_CHARTS]) if c] # de-dupe by id: two cards sharing an id are one card as far as the client's keyed # render is concerned, and the second would silently shadow the first seen, uniq = set(), [] for c in clean: if c['id'] in seen: continue seen.add(c['id']) uniq.append(c) if uniq: out['charts'] = uniq # ── C6-CATALOG (wave 18) ───────────────────────────────────────────────────────────── catalogs = _clean_catalogs(raw.get('catalogs'), valid_keys) if catalogs: out['catalogs'] = catalogs # ── ⭐⭐ WAVE-37 C3 (T21) β€” `catalog`, SINGULAR, and it is NOT the line above it. See the # header on `_clean_catalog_spec` for the two-keys-one-letter-apart warning; this call site is # where a reader is most likely to "fix" one into the other. catalog = _clean_catalog_spec(raw.get('catalog'), valid_keys) if catalog: out['catalog'] = catalog # ── ⭐ WAVE-27 C3 (item 8 / R2): the swipe binding ──────────────────────────────────── # `{fieldKey, leftOption, rightOption}` β€” WHOLE-KEY drop, never a partial one, and that # asymmetry against `charts`/`calendarMetrics` above is the point rather than an oversight. # Those are LISTS of independent cards, so losing one entry costs the user one card. This is # a single three-part BINDING: a swipe view holding a fieldKey with one option, or two # options and no field, is not a degraded swipe view β€” it is a deck that can never write # anything, rendered as though it were configured. Dropping the key entirely puts the view # back in its honest unconfigured state, which is the one state the client has a UI for. # # ⚠ What this CANNOT check, deliberately, and why the client must: whether `fieldKey` names # a SELECT, and whether the two options are still in that select's vocabulary. `valid_keys` # is a key set, and the docstring above draws this exact line β€” "what each mode MEANS ... is # the client's business". So SwipeView owns three losses this function is blind to (field # deleted, field retyped away from select, option removed) and must SHOW each one rather # than fall back to the first option, per the `viewModes.tsx` house rule. swipe = raw.get('swipe') if isinstance(swipe, dict): f_key = swipe.get('fieldKey') left, right = swipe.get('leftOption'), swipe.get('rightOption') ok = (f_key in valid_keys and isinstance(left, str) and isinstance(right, str)) if ok: left, right = left.strip()[:MAX_SWIPE_OPTION], right.strip()[:MAX_SWIPE_OPTION] # Both non-empty, and DISTINCT: one option on both sides is a deck whose two # gestures do the same thing, which is two spellings of one state (the # `kanbanClamp` law) wearing a control that promises a choice. if left and right and left.casefold() != right.casefold(): out['swipe'] = {'fieldKey': f_key, 'leftOption': left, 'rightOption': right} # ── ⭐⭐ WAVE-29 R7 (item 10): the FORM spec β€” see `_clean_form` for why the token is not here. form = _clean_form(raw.get('form'), valid_keys) if form: out['form'] = form # ── ⭐⭐ W33-T45 / CONTRACT C1 / RULING R5 (owner item 8b): IS THIS INTERFACE PUBLISHED ──── # # β›” TWO KEYS LIVE HERE AND TWO DELIBERATELY DO NOT. The `published` flag and the sharer's # `public | password` choice are DISPLAY state β€” the view says what it is, the client renders # a badge from it, and it travels with the view like every other key in this dict. The SECRET # TOKEN and the PASSPHRASE HASH do not: they live in the server-only bucket, exactly as # `routes_forms.py`'s `TOKENS_KEY` holds the form token. `config.display` is echoed back to # every user who can open the view, so a token in here is a token published to the audience # the password was meant to exclude. `_clean_form` above carries the same rule and the same # reason; this is the second door, not a new one. # # β›” AND THE COERCION IS FAIL-CLOSED, WHICH IS WHY THIS IS NOT A BARE ALLOWLIST. A plain # allowlist drops an unrecognised `publishAccess` and KEEPS `published: True` β€” leaving a # published view with no stated access, i.e. a third state neither the ruling nor the client # has a meaning for, on the one key where guessing wrong publishes a tenant's data to the # open internet. So: a published view ALWAYS carries an access, and anything that is not the # literal `'public'` reads as `'password'`. The unpublished case stores nothing at all β€” # absent means unpublished, and a `published: False` would be the second way to say nothing # that `kanbanClamp` and `mode: 'grid'` are both here to forbid. if raw.get('published') is True: out['published'] = True out['publishAccess'] = 'public' if raw.get('publishAccess') == 'public' else 'password' return out #: FOLDERS over the saved views / cohorts sidebars (wave-8 I11, contract C4). #: #: ⚠ Folder membership is stored as a SIDE MAP (`itemFolders`), not as a `folderId` ON each #: view or cohort β€” a deliberate amendment to C4's first wording, recorded in the split doc. #: Two reasons. (1) A cohort lives in a DIFFERENT store (`customer_cohorts`, keyed by cohort #: id) and adding a `folders` key beside those ids would collide with a cohort whose generated #: id happened to be 'folders'. (2) Folder placement is a per-user ORGANISING act, not part of #: what a view IS: keeping it out of the view config means duplicating or exporting a view does #: not drag a folder reference along with it. One map, one home, both surfaces. FOLDER_SURFACES = {"views", "cohorts"} MAX_FOLDERS = 60 MAX_FOLDER_NAME = 80 #: Wave-9 I15 (contract C5) β€” a user-chosen folder icon, as {shape, tone}. #: #: Both halves are WHITELISTS, never free values: `shape` names geometry the client already #: draws (one source, `iconShapes.ts`, read by both painters) and `tone` names a palette token, #: not a colour β€” so a browser cannot post a hex and defeat a tenant restyle, and a shape the #: client cannot render can never reach the store. #: ⚠ MIRRORS CLIENT'S `iconShapes.ts` ENUMERATION EXACTLY (C5: CLIENT enumerates, HOST mirrors β€” #: posted in the split doc 2026-07-29, HOST adopted it the same day, replacing a provisional #: 12-shape guess of mine that contained shapes the client cannot draw). Do not extend this set #: without the matching client geometry: an unknown shape falls back to the default folder mark, #: which is also I14's "existing folders get the folder icon" for every pre-wave-9 folder. FOLDER_ICON_SHAPES = { "folder", "star", "flag", "tag", "bookmark", "grid", "chart", "map", "users", "clock", "heart", "bolt", } #: Tones are the C1 pastels β€” FILLS ONLY, never text. This mirrors the current client vocabulary; #: the old host spelling `grey` is accepted as a read/write migration alias for `neutral` below. FOLDER_ICON_TONES = {"neutral", "blue", "green", "yellow", "red"} FOLDER_ICON_DEFAULT_TONE = "neutral" def clean_folder_icon(raw): """{shape, tone} or None. Fail-closed on both halves, independently. A folder with a valid shape but a junk tone keeps the shape and defaults the tone rather than losing the icon entirely β€” losing a user's pick because one half was wrong is the kind of silent data loss the folder events already avoid elsewhere. """ if not isinstance(raw, dict): return None shape = raw.get("shape") if shape not in FOLDER_ICON_SHAPES: return None tone = raw.get("tone") # The first host implementation called the neutral tone `grey`. Accept that legacy value so # an existing folder cannot crash a newer client, but canonicalise it on the next workspace # write/read to the current shared vocabulary. if tone == "grey": tone = FOLDER_ICON_DEFAULT_TONE return {"shape": shape, "tone": tone if tone in FOLDER_ICON_TONES else FOLDER_ICON_DEFAULT_TONE} def clean_folders(raw): """Validate the per-surface folder lists, fail-closed. {surface: [{id, name, order}]}.""" out = {} for surface in FOLDER_SURFACES: items, seen = [], set() for f in list((raw or {}).get(surface) or [])[:MAX_FOLDERS]: if not isinstance(f, dict): continue fid = str(f.get("id") or "").strip()[:80] name = str(f.get("name") or "").strip()[:MAX_FOLDER_NAME] if not fid or not name or fid in seen: continue # an unidentified or unnamed folder cannot be shown or edited seen.add(fid) try: order = int(f.get("order", len(items))) except (TypeError, ValueError): order = len(items) row = {"id": fid, "name": name, "order": order} icon = clean_folder_icon(f.get("icon")) # wave-9 I15 (C5); absent = default mark if icon: row["icon"] = icon # W41-T12 / T33 / OWNER INSTRUCTION 12 -- `parent` SURVIVES THIS FUNCTION NOW. # THIS ONE LINE IS WHY NESTING WAS DEAD. Every other half shipped and worked: # `ViewSidebar.tsx:316` takes a `parent`, `CustomerGrid.tsx:7432` puts it on the wire, # `table_store.validate_folder_tree` refuses cycles and chains over `MAX_FOLDER_DEPTH` # with a worded receipt, and `grid_events` already catches `FolderTreeError` into # `_folder_refuse`. This row build STRIPPED the key on the way in, so the validator # could never fire and a folder made inside a folder was gone on refresh -- a feature # dead behind four correct halves and every gate green. `grid_events.py` stated the # forward contract itself: "the day `clean_folders` learns `parent`, the refusal is # already wired and worded". This is that day. # # ABSENT, NEVER `None`, and never invented. An absent `parent` IS the root, which is # what every stored row has meant until now -- and `validate_folder_tree` promises that # a payload carrying no `parent` anywhere comes back byte-identical with zero repairs, # so writing a null key would break that promise for no gain. # SELF-PARENTING IS DROPPED HERE as well as refused downstream: the validator raises # `cycle` on it, and a row that cannot be legal should not reach the validator wearing # a repair. A parent naming a folder that is GONE is deliberately NOT dropped here -- # deleting a folder creates exactly that, and `validate_folder_tree` repairs it to the # root WITH a receipt the user can read. Dropping it silently here would destroy the # receipt, and the user would never learn their folder had moved. parent = str(f.get("parent") or "").strip()[:80] if parent and parent != fid: row["parent"] = parent items.append(row) items.sort(key=lambda x: x["order"]) for i, f in enumerate(items): f["order"] = i # re-index so `order` is always dense and total if items: out[surface] = items return out #: ⭐⭐ WAVE 32 Β· OWNER ITEM 20 (`W32-T27`, raised by SESSION C as ASK C-16) β€” "FILED AT ROOT". #: #: β›” THE DEFECT IS THAT ROOT WAS REPRESENTED BY *ABSENCE*, AND ABSENCE CANNOT HOLD TWO FACTS. #: "this arrived by grant and was never filed" and "the receiver deliberately dragged this OUT of #: the Shared group" were the same stored state β€” nothing β€” so the client had to GUESS, and #: `folders.ts::groupByFolder` guessed "Shared". That is why only folderβ†’folder moves appeared to #: work: **the root bucket was unreachable for a shared view by construction.** #: #: ⚠ A RESERVED FOLDER ID, NOT A NEW FIELD, deliberately. The placement map is `{itemId: folderId}` #: and every reader on both sides already understands it; a parallel "filedAtRoot" set would be a #: second source of truth for one question, and the two would disagree the first time one of them #: was written without the other. This id names no folder BY DESIGN and is therefore exempt from #: the folder-exists test below β€” it is the one value that means "no folder, on purpose". #: ⚠ Spelled `ROOT_FOLDER_ID` on the client (`customer-grid/folders.ts`, C's file). Two spellings #: of one constant is [[a-constant-two-features-share]]; `verify_folders`/`verify_api` assert they #: agree rather than a comment asking nicely. ROOT_PLACEMENT = "__root__" def clean_item_folders(raw, folders, valid_ids): """{surface: {itemId: folderId}} β€” dropping any placement whose ITEM or FOLDER is gone. This is what makes a deleted folder's contents fall back to the root rather than vanish: nothing stores "this item is in no folder", so an unresolvable placement simply disappears and the item renders at the top level. Same for an item that was deleted elsewhere β€” its stale placement can never resurrect it, because the sidebars render ITEMS and consult this map, never the other way round. ⭐⭐ WAVE 32 β€” THE PARAGRAPH ABOVE STATES THE FEATURE AND THE BUG IN ONE SENTENCE, and it took owner item 20 to notice they were the same mechanism. *"Nothing stores 'this item is in no folder', so an unresolvable placement simply disappears"* is exactly right for a DELETED FOLDER (its contents should fall to the root) and exactly wrong for a SHARED VIEW (falling back means falling back INTO the Shared group, which is where it started). `ROOT_PLACEMENT` is the value that survives this function so the second case can be said out loud. """ out = {} for surface in FOLDER_SURFACES: fids = {f["id"] for f in (folders or {}).get(surface, [])} ok = {} for item_id, fid in ((raw or {}).get(surface) or {}).items(): if not isinstance(item_id, str) or not isinstance(fid, str): continue # β›” `fid == ROOT_PLACEMENT` FIRST, and it is NOT in `fids` β€” it names no folder, which # is the whole point. Without this clause the value is written by `item_move` and # scrubbed here on the way back out, so the mark would be stored and instantly lost: # the two halves are ONE change and shipping either alone is worse than shipping # neither ([[lost-write-looks-like-failed-read]]). if item_id in (valid_ids or {}).get(surface, ()) and (fid == ROOT_PLACEMENT or fid in fids): ok[item_id[:120]] = fid if ok: out[surface] = ok return out def view_refs_of(nodes): """C4 β€” every view id a tree REFERS to, deduped, in order. Mirrors `types.ts::viewRefsOf`. ⚠ An INACTIVE leaf (no view chosen yet) is not a reference, on both engines: counting one would refuse a save the moment somebody opened the condition and had not picked anything. """ out = [] for node in nodes or []: if not isinstance(node, dict): continue if 'children' in node: for vid in view_refs_of(node.get('children')): if vid not in out: out.append(vid) continue if node.get('colId') != VIEW_FIELD: continue vid = str(node.get('value') or '').strip()[:MAX_VIEW_ID] if vid and vid not in out: out.append(vid) return out def view_filter_cycle(view_id, nodes, filters_of): """⭐⭐ W37-T26 / C4 β€” THE CYCLE REFUSAL's host half. Mirrors `types.ts::viewFilterCycle`. View X filtered on "is in View Y" where Y is filtered on X cannot be resolved by anything: X needs Y needs X. Returns the CYCLE PATH (ids, starting and ending at `view_id`) or None. β›” THE CLIENT REFUSES THE SAME SHAPE AND THAT IS NOT DUPLICATION. The browser's guard is what a PERSON sees and is the only one that can explain itself; this one is what makes the rule true for a caller that POSTs a view directly, which is every guard-in-the-browser's blind spot. ⚠ A view referring to ITSELF is a cycle of length one and is caught by the same walk β€” also the case a person reaches most easily, by duplicating a view. """ def walk(current, path, seen): refs = view_refs_of(nodes if current == view_id else filters_of(current)) for nxt in refs: if nxt == view_id: return path + [nxt] if nxt in seen: continue seen.add(nxt) found = walk(nxt, path + [nxt], seen) if found: return found return None return walk(view_id, [view_id], {view_id}) def clean_filter_cell_ref(raw): """Validate a saved external cell address without choosing its reader or changing its shape.""" if (not isinstance(raw, dict) or set(raw) - {'workbook_id', 'tab', 'ref', 'locked'} or any(not isinstance(raw.get(key), str) or not raw[key].strip() or raw[key] != raw[key].strip() or len(raw[key]) > 120 for key in ('workbook_id', 'tab', 'ref')) or not re.fullmatch(r'\$?[A-Za-z]{1,3}\$?[1-9][0-9]{0,6}', raw['ref']) or 'locked' in raw and not isinstance(raw['locked'], bool)): return None return copy.deepcopy(raw) def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None, visible_view_ids=None, report=None): """Recursively validate an UNTRUSTED filter tree (conditions + nested groups). Returns a clean tree of leaf conditions ({colId, op, value, value2}) and groups ({conj, children}). Module-agnostic on purpose: any module embedding the grid validates its own view state through this one function. Fail-closed PER NODE: anything unrecognised is DROPPED rather than raised β€” the same contract the rest of the view sanitiser follows, so one bad rule can never cost a user their whole saved view. Depth, per-level width and total node count are all capped: the tree is re-evaluated for every row on every render, so an unbounded structure would be a persistent client-side DoS. Empty groups are dropped (they carry no meaning once persisted). `report`, when supplied, accumulates missing-column and invalid-RHS drops across nested groups. Entries name `id`, `colId` and `reason`, plus `rhsColId` for an invalid right operand. The returned tree and callers that omit the accumulator keep their existing shape. `cohort_ids` is the set of cohorts the CALLER may see. A cohort leaf naming anything else is DROPPED here rather than left for the engine β€” a deleted cohort would otherwise leave a condition that can only match nothing, so `List is not [deleted]` would show an empty table forever with no way to tell why. `None` means this host has no cohorts, and then every cohort leaf is dropped: fail-closed, like every other unknown key. ⭐⭐ W37-T26 (C4) β€” `visible_view_ids` is the same parameter one leaf over: the views this caller may name in a `__view__` membership leaf. A leaf naming anything else is DROPPED here for the identical reason, and `None` (this host has no views to offer) drops every one. ⚠ DEFAULTS TO `None` SO EVERY EXISTING CALLER IS BYTE-IDENTICAL. Three callers pass nothing (`routes_admin`, `routes_query` twice) and each of them is a surface with no saved-view vocabulary of its own; under the fail-closed rule they drop the leaf, which is correct rather than merely safe. """ if budget is None: budget = [MAX_FILTER_NODES] out = [] for node in list(raw or [])[:MAX_FILTER_SIBLINGS]: if budget[0] <= 0: break if not isinstance(node, dict): continue if isinstance(node.get('children'), list): # a condition GROUP if depth >= MAX_FILTER_DEPTH: continue # too deep -> drop budget[0] -= 1 children = clean_filter_tree(node['children'], valid_keys, depth + 1, budget, cohort_ids, visible_view_ids, report=report) if children: out.append({'conj': 'or' if node.get('conj') == 'or' else 'and', 'children': children}) continue if node.get('colId') == COHORT_FIELD: # a cohort-membership leaf op = COHORT_OP_ALIASES.get(node.get('op'), node.get('op')) named = parse_cohort_ids(node.get('value')) # ALL of them, or the leaf goes. A set that quietly lost a member asks a DIFFERENT # question, and for `noneOf` a strictly wider one: `is none of [A, B]` degrading to # `is none of [A]` would show every row in B under a count nobody would doubt. This # is the same all-or-nothing the single-cohort leaf already had, extended to a set. if op in COHORT_OPS and named and all(c in (cohort_ids or ()) for c in named): budget[0] -= 1 leaf = {'colId': COHORT_FIELD, 'op': op, 'value': ','.join(named), 'value2': ''} if node.get('locked') is True: leaf['locked'] = True out.append(leaf) continue if node.get('colId') == VIEW_FIELD: # C4: a view-membership leaf # β›” THE SAME ALL-OR-NOTHING THE COHORT ARM ABOVE APPLIES, AND FOR THE SAME REASON. # A leaf naming a view this caller cannot see is DROPPED rather than kept, because a # kept one can only ever match nothing: `View is not [a view you cannot see]` would # show an empty table forever with no way to tell why. Dropping it puts the view back # in its honest unfiltered state, which is what `clean_filter_tree`'s own docstring # already promises for cohorts. # ⚠ `visible_views` is what the caller passes; `None` means this host does not know, # and then EVERY view leaf is dropped β€” fail-closed, like every other unknown key. v_op = node.get('op') v_id = str(node.get('value') or '').strip()[:MAX_VIEW_ID] if v_op in VIEW_OPS and v_id and v_id in (visible_view_ids or ()): budget[0] -= 1 leaf = {'colId': VIEW_FIELD, 'op': v_op, 'value': v_id, 'value2': ''} if node.get('locked') is True: leaf['locked'] = True out.append(leaf) continue # Wave 45 C1: ``zone`` was the pre-canonical projection key. A saved View is migrated # at its ordinary validated save door, rather than kept as a second readable field or # dropped as an unknown condition. The migration is admissible only when this database # actually exposes ``__zone__``; on every other database an unknown ``zone`` leaf keeps # the longstanding fail-closed behaviour. column = ('__zone__' if node.get('colId') == 'zone' and '__zone__' in valid_keys else node.get('colId')) if column not in valid_keys: if report is not None: report.append({'id': str(node.get('id', ''))[:64], 'colId': column, 'reason': 'missing_column'}) continue if node.get('op') in FILTER_OPS: budget[0] -= 1 # `or ''` would be wrong here: it maps every FALSY value to '', and '' is the # signal for "inactive". A numeric 0 (or 0.0, or False) is a real value the client # treats as active β€” `0 === ""` is false in TS β€” so `revenue = 0` would silently # stop filtering and show every row instead of the zero-revenue ones. val, val2 = node.get('value'), node.get('value2') leaf = {'colId': column, 'op': node['op'], 'value': ('' if val is None else str(val))[:500], 'value2': ('' if val2 is None else str(val2))[:500]} # CG-8. A MEASURE condition ("Sales, in the last 90 days, > 5,000") carries two # extra members: a stable client-generated `id`, which is how the server's answer # finds its way back to the condition that asked (positional matching silently # re-associates every answer the moment a user deletes a condition), and the # `window`. Emitted ONLY when the input has them β€” a column condition's cleaned # shape is unchanged, so every persisted view deserialises byte-identically and # `clean_filter_tree` stays idempotent (verify_filter_engine.py asserts that by # exact structural comparison). # ⭐ W51-T07 β€” the MULTI-VALUE operand, emitted as a REAL LIST and never through the # `str(val)[:500]` coercion three lines up, which would store the literal text # "['A', 'B']" and leave the condition unanswerable in all three engines. # # Emitted for these ops ALWAYS and for every other op NEVER, which is what keeps # `clean_filter_tree` idempotent (verify_filter_engine.py compares the cleaned shape # structurally): an ordinary column leaf is byte-identical to what it always was, and # a multi-value leaf whose list is EMPTY keeps an empty list rather than losing the # member β€” so the leaf survives as INCOMPLETE (is_rule_active answers False, the # builder renders it unfinished) instead of being silently dropped. if node['op'] in MULTI_VALUE_OPS: leaf['values'] = parse_filter_values(node.get('values')) rid = node.get('id') if rid not in (None, ''): leaf['id'] = str(rid)[:64] window = _clean_window(node.get('window')) if window is not None: leaf['window'] = window # Owner items 3 + 4, carried under the SAME rule as CG-8's `id`/`window`: emitted # only when the input has them, so a plain column condition's cleaned shape is # byte-identical to what it always was and `clean_filter_tree` stays idempotent # (verify_filter_engine.py asserts that by exact structural comparison). Drop the # carry-through and the next autosave silently strips a date condition back to a # bare comparison against an empty value β€” i.e. back to INACTIVE. date_window = _clean_window(node.get('dateWindow')) if date_window is not None: leaf['dateWindow'] = date_window mode = node.get('dateMode') # SHAPE only. An unrecognised mode survives here and is refused by # `windows.resolve_anchor`, which returns None and makes the condition match # NOTHING β€” the same split as `_clean_window`, and the reason this module can stay # free of the date vocabulary it would otherwise have to keep in step. if isinstance(mode, str) and 0 < len(mode) <= 40: leaf['dateMode'] = mode # W43C C1/R1 Ò€” rank is a set-wide question. A saved leaf says whether it ranks # the residual domain globally or once per the view's group. The concise ``group`` # form deliberately relies on the view's ``groupBy`` at evaluation time; the object # form pins a particular field and therefore survives a later view regroup. Unknown # shapes are dropped, never coerced to global, because that would change a narrowing # question while preserving its friendly-looking label. if node.get('op') in {'topN', 'bottomN', 'inTopPct', 'inBottomPct', 'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile'}: rank_scope = _clean_rank_scope(node.get('rankScope'), valid_keys) if rank_scope is not None: leaf['rankScope'] = rank_scope rhs = _clean_rhs(node.get('rhs'), valid_keys) if isinstance(node.get('rhs'), dict) and rhs is None: # An invalid comparison must not become an inactive empty literal. if report is not None: report.append({'id': leaf.get('id', ''), 'colId': column, 'rhsColId': node['rhs'].get('colId'), 'reason': 'invalid_rhs'}) continue if rhs is not None: leaf['rhs'] = rhs # The save host authorizes these addresses before this structural cleaner runs. refs = {key: clean_filter_cell_ref(node[key]) for key in ('valueRef', 'value2Ref') if key in node} if any(ref is None for ref in refs.values()): continue leaf.update(refs) # C3: a record lock is explicit on the leaf, not a view-wide presentation flag. # Once stored, grid_events preserves the containing filter config unless it is copied # to a new View; a later caller cannot turn this `True` into an editable-looking false. if node.get('locked') is True: leaf['locked'] = True out.append(leaf) return out def migrate_zone_projection_config(raw): """Copy one saved View config while renaming every legacy ``zone`` field reference. Filter leaves are validated later by ``clean_filter_tree``. The other members are field-key projections and can be migrated structurally here, before their normal allow-list checks. This retains old View intent without re-publishing ``zone`` as a writable or readable field. """ config = copy.deepcopy(raw if isinstance(raw, dict) else {}) def key(value): return '__zone__' if value == 'zone' else value def filters(nodes): for node in nodes or (): if not isinstance(node, dict): continue if isinstance(node.get('children'), list): filters(node['children']) else: if node.get('colId') == 'zone': node['colId'] = '__zone__' rank_scope = node.get('rankScope') if isinstance(rank_scope, dict): for member in ('field', 'groupBy'): if member in rank_scope: rank_scope[member] = key(rank_scope.get(member)) raw_filters = config.get('filters') filters((raw_filters.get('nodes') or raw_filters.get('children') or ()) if isinstance(raw_filters, dict) else raw_filters) for member in ('sorts',): for item in config.get(member) or (): if isinstance(item, dict) and item.get('colId') == 'zone': item['colId'] = '__zone__' for member in ('order', 'visible'): if isinstance(config.get(member), list): config[member] = list(dict.fromkeys(key(value) for value in config[member])) if isinstance(config.get('widths'), dict) and 'zone' in config['widths']: config['widths']['__zone__'] = config['widths'].pop('zone') for member in ('groupBy', 'colorBy', 'stackField'): if config.get(member) == 'zone': config[member] = '__zone__' return config def preserve_locked_view_records(prior_config, filters, sorts): """Return authoritative filter/sort records when an in-place lock was touched. A lock protects its semantic position as well as its leaf text: moving a locked condition between AND/OR groups changes the question even when the leaf itself is byte-identical. We therefore retain the full corresponding list on any attempted change. A new View has no prior config, so copying is the explicit alteration path. """ prior = prior_config if isinstance(prior_config, dict) else {} old_filters = prior.get('filters') if isinstance(prior.get('filters'), list) else [] old_sorts = prior.get('sorts') if isinstance(prior.get('sorts'), list) else [] def _has_locked_filter(nodes): for node in nodes or (): if not isinstance(node, dict): continue if node.get('locked') is True: return True if _has_locked_filter(node.get('children') if isinstance(node.get('children'), list) else []): return True return False def _same(left, right): return json.dumps(left, sort_keys=True, separators=(',', ':')) == json.dumps( right, sort_keys=True, separators=(',', ':')) if _has_locked_filter(old_filters) and not _same(old_filters, filters): filters = json.loads(json.dumps(old_filters)) if any(isinstance(rule, dict) and rule.get('locked') is True for rule in old_sorts) \ and not _same(old_sorts, sorts): sorts = json.loads(json.dumps(old_sorts)) return filters, sorts def _clean_rank_scope(raw, valid_keys): """The persisted rank scope, or ``None`` when absent/malformed. ``None`` retains legacy global semantics. ``'group'`` is intentionally valid without a column here: it means *the view's selected group*, and the server resolver refuses it when a caller later supplies no real group field. An explicit field is accepted only when this table exposes it, so a stale saved scope cannot silently collect every row in one bucket. """ if raw in (None, ''): return None if raw == 'global': return 'global' if raw in ('group', 'perGroup'): return 'group' if not isinstance(raw, dict): return None mode = raw.get('mode', raw.get('scope')) field = str(raw.get('field', raw.get('groupBy')) or '').strip()[:80] if mode == 'global' and not field: return 'global' if mode == 'group' and field and field in valid_keys: return {'mode': 'group', 'field': field} return None def _is_default_visible(field): """Does this column open SHOWN in a view that has never recorded its own `visible`? ⭐⭐ OWNER, 2026-08-23: *"when any new View is created only shareable pre-set data should show. Shared to me or Shared to everyone should be auto hidden."* β›” THE CLIENT TWIN IS `useGridColumns.isDefaultVisible` AND IT MUST SAY THE SAME THING. The note inside `_default_view_config` below is the record of what happens when it does not: `CustomerGrid` compares the stored system view against its own `defaultViewConfig` by JSON equality, so a disagreement here is a view that looks permanently dirty and autosaves for ever. The reasoning for the predicate itself lives in the client file, once. ⚠ `custom or shared` is the same membership test `FieldsHidePanel` uses to draw BOTH of its shared headings, so hiding on it covers both without a second list of section names. """ if field.get("default") is False: return False if field.get("custom") is True or field.get("shared") is True: return False return True def _default_view_config(fields): # ⭐⭐ W30-T41's SERVER HALF (F's ask F-1, answered by D β€” this file is D's fence). # # β›” THE SECOND ARM USED TO BE `or field["source"] == "overlay"`, AND IT SWALLOWED THE FIRST # ONE FOR EVERY CONNECTED COLUMN. `user_tables._clean_field` stamps `source: "overlay"` on # every `ut_` field, so on an Odoo grid the arm was true for ALL of them and `default: False` # meant nothing: `odoo_id`, `state`, `customer_link` and `partner_id` opened SHOWN however # they were declared. The exception had become the rule ([[fallback-that-became-the-rule]]), # and it is the same predicate `useGridColumns.isDefaultVisible` carried on the client. # # ⚠ AND THE TWO HALVES MUST MOVE TOGETHER, which is why this is not cosmetic. `CustomerGrid` # compares the stored view against its own `defaultViewConfig` by JSON equality; with the # client fixed (T41) and this left alone, the system view would differ from the client's # default on every render β€” a view that looks permanently dirty and autosaves forever, which # is the failure `verify_filter_engine`'s key-ORDER check exists to prevent, one level down. # # ⚠ A USER-CREATED COLUMN IS UNAFFECTED, and that is why the fix is a DELETION rather than a # carve-out for the four Odoo keys: it carries no `default` key at all, so `is not False` # keeps it visible. On the main Customer grid exactly one field moves β€” `notes`, which asks # to be hidden in its own declaration and was being shown against it. # ⭐⭐ OWNER, 2026-08-23 β€” ONLY PRE-SET DATA OPENS SHOWN. The client twin is # `useGridColumns.isDefaultVisible` and it carries this comment's argument in full; the two # MUST move together, which is the whole subject of the note above. shown = [field["key"] for field in fields if _is_default_visible(field)] hidden = [field["key"] for field in fields if field["key"] not in shown] archive_filter = [{"colId": "archived", "op": "neq", "value": "true"}] if any( field.get("key") == "archived" and field.get("type") == "checkbox" and field.get("source") == "odoo" for field in fields) else [] return { # `filters` is the ROOT of the filter tree: leaf conditions and/or nested # condition groups ({conj, children}); `filterConj` joins the root level. "filters": archive_filter, "filterConj": "and", "sorts": [], "groupBy": None, "colorBy": None, "rowHeightMode": "short", "order": shown + hidden, "visible": shown, "widths": {}, "memberPids": [], } #: Wave 17 R1 / C-LOCKV β€” the `kind` a PROJECTED locked view wears. A cohort is not a separate #: kind of object any more: it is a saved view whose rows are a hand-curated set. LOCKED_VIEW_KIND = 'locked' def locked_view_projection(entry, base_config): """One cohort -> the saved-view row that IS it (wave 17 R1, contract C-LOCKV). β›” THE LOCK IS THE VIEW'S IDENTITY, NOT ITS CONFIGURATION. `config.cohortLock` names the view's OWN id, which is what makes the shipped engine law (`useVisibleRows`: intersect the named set FIRST, unconditionally, and match NOTHING when the membership is unresolvable) do all the work with no second mechanism. Membership itself is NEVER copied in here β€” it stays in `customer_cohorts` and travels as `workspace.lists`, because a per-reader-scoped collection inside a client-writable `config` is deleted by the next autosave (see the contract's reason 2). ⚠ `locked: True` is the LEGACY "undeletable/mode-frozen" flag and is deliberately NOT set: these views are ordinary in every respect the owner asked for β€” reorder, folder, sort, filter, change display mode. The lock mark in the rail is driven by `kind`. """ return { 'id': entry['id'], 'name': entry.get('name') or entry['id'], 'kind': LOCKED_VIEW_KIND, 'config': {**base_config, 'cohortLock': entry['id']}, } #: ⭐ WAVE-27 item 27 (owner ruling R8) β€” the IG "Overview" view's CURATED COLUMNS, in the #: owner's own order: handle, followers, engagement, location, last enriched. #: #: Written as candidates rather than as a requirement. The template registry REFUSES a template #: whose columns the target lacks (`view_templates.missing_columns`) because applying one writes #: the user's own views and a filter on a missing column silently WIDENS. This view is INJECTED, #: not applied, and it filters nothing β€” so the proportionate rule is the opposite one: take the #: columns the table has, in this order, and skip the rest. An IG database that predates a #: column simply shows the other four. #: #: ⚠ `location_guess` is SESSION B's item-16 column and may not exist yet. That is exactly why #: this list is intersected rather than asserted: a hard requirement here would make the whole #: view vanish (or the assembly refuse) on every tenant until B lands, and then appear by #: surprise. `profile_url` closes the list as the click-through, which is what makes the view #: usable rather than merely informative. IG_OVERVIEW_COLUMNS = ('handle', 'full_name', 'followers', 'avg_engagement', 'location_guess', 'enriched_at', 'profile_url') #: The id is PINNED, the `view_templates` discipline: re-assembling must update the same view #: rather than mint "Overview 2". It also lets a user's own edits overlay it through the saved #: -config loop below, exactly as a cohort projection does. IG_OVERVIEW_ID = 'tpl_overview' #: How this function recognises an IG preset database WITHOUT importing the engine: two of the #: profile preset columns is a stronger signal than any single one (a hand-made table could #: plausibly own a column called `followers`; owning `followers` AND `avg_engagement` AND #: `handle` is the preset set). `core/` must stay importable without the API layer, so this #: mirrors `user_tables.PROFILE_PRESET_KEYS` the way that module mirrors the engine's. _IG_SIGNATURE = ('handle', 'followers', 'avg_engagement') def _ig_overview_view(fields, base): """R8's curated Overview, or None when this table is not an Instagram one.""" keys = {f['key'] for f in fields} if not all(k in keys for k in _IG_SIGNATURE): return None visible = [k for k in IG_OVERVIEW_COLUMNS if k in keys] return { 'id': IG_OVERVIEW_ID, 'name': 'Overview', 'kind': 'system', # NOT `locked`. The system view is locked because it is the identity of the table ("show # me everything"); this one is a STARTING LAYOUT, and R8 calls it curated rather than # fixed. A user who wants a sixth column should get one. 'note': 'The five things worth seeing first on a creator. Sorted by reach.', 'config': { **dict(base), 'visible': visible, 'order': visible + [k for k in (f['key'] for f in fields) if k not in visible], 'sorts': ([{'colId': 'followers', 'dir': 'desc'}] if 'followers' in keys else []), }, } def views_from_defs(defs, saved_views, fields, system_name="All customers", locked_lists=None, view_order=None): """Convert legacy list formulas into the shared serializable SavedView contract. `system_name` (wave 16 C-TOPIC) labels the system view per TOPIC ("All products" on the product surface). The ID stays "all-customers" on every topic β€” the client pins it (UNDELETABLE_VIEW_IDS, the landing default), and an id that varies by surface would fork that contract for a label's sake. `locked_lists` (wave 17 R1) are the caller's cohorts, each PROJECTED as a saved view whose id IS the cohort id β€” so every stored reference to that id (a `cohortLock` on another view, an `is part of` condition, a folder placement) keeps pointing at the same thing and no rewrite map is needed. Saved config OVERLAYS the projection through the same mechanism the `list:` views have always used, which is what gives a locked view its own sort, filter, columns and display mode with no new storage.""" base = _default_view_config(fields) views = [{ "id": "all-customers", "name": system_name, "kind": "system", "locked": True, "config": dict(base), }] # ⭐ WAVE-27 item 27 (R8) β€” the IG Overview, ABOVE All records. # # ⚠ INJECTED, not seeded into the store, and that is what makes "existing IG databases gain # it too" true with no migration and no write on a read path. It is the same mechanism the # system view above has always used; the pinned id means a user's own edits overlay it # through the saved-config loop below rather than forking a second view. _overview = _ig_overview_view(fields, base) if _overview: views.insert(0, _overview) op_map = {">=": "gte", ">": "gt", "<=": "lte", "<": "lt", "=": "eq", "contains": "contains"} for name, definition in (defs or {}).items(): filters = [dict(rule) for rule in base["filters"]] for rule in definition.get("rules") or []: if rule.get("field") not in {field["key"] for field in fields}: continue filters.append({ "colId": rule["field"], "op": op_map.get(rule.get("op"), "eq"), "value": str(rule.get("value") if rule.get("value") is not None else ""), }) sort = str(definition.get("sort") or "") sorts = ([{"colId": sort.lstrip("-"), "dir": "desc" if sort.startswith("-") else "asc"}] if sort.lstrip("-") in {field["key"] for field in fields} else []) views.append({ "id": "list:" + str(name), "name": str(name), "kind": "list", "note": str(definition.get("note") or ""), "config": { **base, "filters": filters, "sorts": sorts, "memberPids": [int(pid) for pid in definition.get("members") or [] if isinstance(pid, int) or str(pid).isdigit()], }, }) # Wave 17 R1 β€” the cohorts, as ordinary views. Appended BEFORE the saved-config overlay # below so a user's own edits to a locked view (its sort, its columns, its display mode) # land on the projection instead of creating a second row with the same id. for _entry in (locked_lists or []): if isinstance(_entry, dict) and _entry.get('id'): views.append(locked_view_projection(_entry, base)) index = {view["id"]: i for i, view in enumerate(views)} for view_id, saved in (saved_views or {}).items(): if not isinstance(saved, dict) or not isinstance(saved.get("config"), dict): continue clean = dict(saved) clean["id"] = str(view_id) if view_id in index: views[index[view_id]] = clean else: views.append(clean) # β›” WAVE 17 R1 β€” RE-STAMP THE LOCK AFTER THE OVERLAY. The loop above REPLACES a projected # view with its saved record, and a saved record that omits `cohortLock` would hand back a # view that shows the WHOLE BOOK under a locked view's name. That is not hypothetical: the # client rebuilds `config` on every autosave (a column resize is enough), and the lock is # identity here, not something the browser is the source of truth for. Read-side rather than # write-side-only on purpose β€” this also repairs any record already written by another path. _locked_ids = {e['id']: e for e in (locked_lists or []) if isinstance(e, dict) and e.get('id')} if _locked_ids: for _v in views: _entry = _locked_ids.get(_v.get('id')) if not _entry: continue _v['kind'] = LOCKED_VIEW_KIND _v['config'] = {**(_v.get('config') or {}), 'cohortLock': _v['id']} # One thing, one name: the cohort store owns it (the rename event routes there), so # a stale `name` on the saved record can never fork into a second title. _v['name'] = _entry.get('name') or _v['id'] # ── ⭐ WAVE-27 item 5, contract C7: the PER-USER VIEW ORDER ─────────────────────────────── # # `view_order` is a list of view ids this user dragged into place. Applied LAST, over the # finished list, so it reorders whatever the assembly produced without having to know how any # of it got there (system, list:, cohort projection, saved, injected Overview). # # β›” THE SYSTEM VIEW STAYS AT INDEX 0 (C7), and it is re-pinned here rather than trusted to # sort correctly: `all-customers` is the client's landing default and one of its # UNDELETABLE_VIEW_IDS, so a stored order that happened to omit it β€” or list it third β€” # would move the rail's home row. ⚠ R8's Overview is the ONE thing allowed above it, because # the owner put it there; it is re-pinned with the system view so a drag cannot bury it # either. Both are facts about the table rather than the user's arrangement of it. # # ⚠ UNKNOWN IDS APPEND IN SERVER ORDER (C7). A view created since this order was stored, or # one shared to this user yesterday, must APPEAR β€” dropping it would make sharing look # broken, and the failure would be invisible to whoever shared it. Ids in the stored order # that no longer resolve are simply skipped. if view_order: _rank = {vid: i for i, vid in enumerate(view_order) if isinstance(vid, str)} _pinned = [v for v in views if v.get('id') in (IG_OVERVIEW_ID, 'all-customers')] _rest = [v for v in views if v.get('id') not in (IG_OVERVIEW_ID, 'all-customers')] # A stable sort over a rank that DEFAULTS TO THE END keeps unranked views in their # server order behind the ranked ones, rather than interleaving them by accident. _rest.sort(key=lambda v: _rank.get(v.get('id'), len(_rank) + 1)) views = _pinned + _rest return views def narrow_view_keys(views, hidden): """D-464: a WIRE COPY of `views` whose column-bearing config names no key in `hidden`. `views_from_defs` merges saved configs verbatim and runs before the field wall exists, so a hidden field's KEY rode `/workspace` in `order`/`visible`/`widths`/`sorts`/`groupBy`/`colorBy` (and `stackField`, `summary`, `display.*Field`) to the very reader the wall targets. Each assembly calls this beside its overlay narrowing, on `workspace["views"]` only: `g["views"]` stays whole for server-side work (exports, measure sets), and a walled reader's own autosave is already cleaned against their walled keys. ⚠ FILTER LEAVES (and `secondaryView`) ARE LEFT ALONE: dropping a leaf would change which rows a view shows, so a hidden key named only in a filter still rides this wire.""" hidden = set(hidden or ()) if not hidden: return views out = [] for view in views or []: cfg = view.get("config") if isinstance(view, dict) else None if not isinstance(cfg, dict): out.append(view) continue cfg = dict(cfg) for name in ("order", "visible"): if isinstance(cfg.get(name), list): cfg[name] = [key for key in cfg[name] if key not in hidden] if isinstance(cfg.get("widths"), dict): cfg["widths"] = {key: w for key, w in cfg["widths"].items() if key not in hidden} if isinstance(cfg.get("sorts"), list): cfg["sorts"] = [s for s in cfg["sorts"] if not (isinstance(s, dict) and s.get("colId") in hidden)] for name in ("groupBy", "colorBy", "stackField"): if isinstance(cfg.get(name), str) and cfg[name] in hidden: cfg[name] = None if isinstance(cfg.get("summary"), dict): cfg["summary"] = {key: s for key, s in cfg["summary"].items() if key not in hidden} if isinstance(cfg.get("display"), dict): # `DisplaySpec`'s `dateField`/`stackField`/`titleField`/`colorField`/... members. cfg["display"] = {name: value for name, value in cfg["display"].items() if not (name.endswith("Field") and isinstance(value, str) and value in hidden)} out.append(dict(view, config=cfg)) return out def workspace_wire(ws, uname, pool_pids, defs=None, scope_key='customer', storage_key=None, fields_base=None, with_cohorts=True, st=None): """The client's `GridWorkspace` WIRE SHAPE from the stored table workspace β€” the ONE projection, shared by both servers (app.py's `_table_grid` and the API's `/workspace`). β›” WHY THIS EXISTS (2026-07-30). The API route used to return the STORE shape with no `storageKey` β€” and the client validator (`fetchWorkspace`) requires one, so the standalone shell silently discarded the whole workspace: saved views never rendered and `cohortMode` never arrived (the Cohort route drew the Customer surface). Duplicating the host's inline projection into the route would have re-created the same drift one wave later; extracting it means the wire can only be one thing. Returns `(workspace, fields, views, cohort_lists)` β€” the extra three because the host interleaves further work (docs, derived cells, measure sets) that consumes them. HOST-ONLY extras stay with the host: `docs`/`docPayload`, `pool`, `hideViews`, `cohortMode`/`scopeChoice` (the API stamps its own from `?scope=`). Wave 16 C-TOPIC: `fields_base` selects the canonical contract (absent = customer, byte-identical). ⭐ WAVE 19 / R9 β€” `with_cohorts` NO LONGER MEANS "customer only". Wave 16 set it False on the product surface because cohorts were a single customer-keyed bucket, so resolving them against product pids would have intersected two unrelated id spaces and printed a plausible, meaningless member count. `modules.cohort` is scope-parameterized now: the lists come from THIS topic's bucket (`cohort_mod.scoped(scope_key)`), so their ids are this topic's ids and the intersection with `pool_pids` is the ordinary one. The flag survives as an honest OFF switch for a surface that wants no membership channel at all β€” it is not a topic wall. """ import modules.cohort as cohort_mod cohort_lists = [] if with_cohorts: for cid, c in sorted(cohort_mod.scoped(scope_key, st=st).visible(uname, pool_pids).items(), key=lambda kv: (kv[1].get('name') or '').lower()): members = [p for p in (c.get('members') or []) if p in pool_pids] entry = {'id': cid, 'name': c.get('name') or cid, 'pids': members} # Rule 8b: a member can drop out of the 24-month pool without the cohort being # wrong, and a silently smaller cohort is exactly what the unverifiable-count rule # forbids. missing = len(c.get('members') or []) - len(members) if missing: entry['missing'] = missing cohort_lists.append(entry) fields = fields_from_workspace(ws, cohorts=bool(cohort_lists), scope_key=scope_key, fields_base=fields_base) views = views_from_defs(defs or {}, ws.get('views'), fields, # Wave 21 (item 3, R6): the system view's name is TOPIC-DERIVED. A # user database's default view used to read "All customers" β€” a # compiled customer literal minted on every topic, one half of the # owner's "my new database looks like RI's Customer table". The ID # stays 'all-customers' everywhere (pinned client+server β€” the # client's UNDELETABLE set and the view pin both name it). system_name=("All products" if scope_key == 'product' else "All records" if str(scope_key or '').startswith('ut_') else "All customers"), locked_lists=cohort_lists, # ⭐ WAVE-27 item 5 (C7) β€” this user's own rail arrangement, from # their own stratum. Read here rather than sorted by the client so # the ORDER a request answers with is the order that was stored: # sorting client-side would make the rail settle after a paint on # every load, and shared views would land in server order first. view_order=ws.get('viewOrder')) workspace = {'storageKey': storage_key, 'views': views, 'lists': cohort_lists} # Owner item 3 (2026-07-31): where this user left off. The client's own localStorage copy # wins when present; this is the server's answer for a FRESH browser, which used to fall # all the way to the system default view (and whatever display mode was stored on it). if ws.get('activeViewId'): workspace['activeViewId'] = str(ws['activeViewId']) # FOLDERS (owner item 11, contract C4), re-validated at SERVE time: a view or cohort can be # deleted by a path that knows nothing about folders, and the placement map must not outlive # the thing it points at. _folders = clean_folders(ws.get('folders')) _view_ids = {v['id'] for v in (views or []) if isinstance(v, dict) and v.get('id')} # ── WAVE 17 R1 (C-LOCKV amendment 2026-08-03): the two folder surfaces become ONE, AT # SERVE TIME rather than by a store migration. A locked view is an ordinary view now, so # its folder has to be an ordinary view folder β€” but rewriting the stored map would be a # one-shot write that has to be got right once, while this is a projection that is right # every time it runs. New drags write to `views` anyway (the client only knows that # surface), so `cohorts` drains on its own and never needs a second pass. # ⚠ A cohorts-surface folder whose id ALREADY names a views folder is DROPPED, not merged: # re-parenting somebody's list into a folder that merely shares an id is a worse outcome # than the list appearing at the root, where it is visible and one drag from home. _cf = list(_folders.get('cohorts') or []) if _cf: _vf = list(_folders.get('views') or []) _taken = {f['id'] for f in _vf} _order = len(_vf) for _f in _cf: if _f['id'] in _taken: continue _vf.append({**_f, 'order': _order}) _order += 1 _folders['views'] = _vf _raw_item_folders = dict(ws.get('itemFolders') or {}) if _raw_item_folders.get('cohorts'): # Cohort placements now describe VIEWS (same ids β€” that is the point of preserving them). # A placement already stored on the views surface WINS: it is the more recent act. _raw_item_folders['views'] = {**dict(_raw_item_folders.get('cohorts') or {}), **dict(_raw_item_folders.get('views') or {})} _placed = clean_item_folders( _raw_item_folders, _folders, {'views': _view_ids, 'cohorts': {c['id'] for c in cohort_lists}}) if _folders.get('views'): workspace['folders'] = _folders['views'] # β›” `cohortFolders` IS NO LONGER EMITTED. The rail has no cohorts section to fold, and a # wire that still described one would invite a second rendering of rows that are now views. _vplaced = _placed.get('views') or {} for _v in (views or []): if isinstance(_v, dict) and _v.get('id') in _vplaced: _v['folderId'] = _vplaced[_v['id']] _cplaced = _placed.get('cohorts') or {} for _c in cohort_lists: if _c['id'] in _cplaced: _c['folderId'] = _cplaced[_c['id']] # RECORD LAYOUT (wave 2026-08-02, C-LAYOUT): the per-user record-detail field order, # re-validated at SERVE time exactly like folders β€” a field can be deleted by a path # that knows nothing about this stratum, and a stale key must not outlive its field. _rl = ws.get('recordLayout') if isinstance(_rl, dict) and isinstance(_rl.get('order'), list): _fkeys = {f['key'] for f in fields if isinstance(f, dict) and f.get('key')} _order, _seen = [], set() for _k in _rl['order'][:200]: _k = str(_k or '') if _k and _k in _fkeys and _k not in _seen: _seen.add(_k) _order.append(_k) if _order: workspace['recordLayout'] = {'order': _order} return workspace, fields, views, cohort_lists def embed_html_path(): """The first existing candidate path for the inlined single-file build, or None.""" for p in _EMBED_CANDIDATES: if p.is_file(): return p return None def scope_counts(shown, matched, total): """The honest 'N of M' a SERVER-WINDOWED table must carry (CG-2). `matched` and `total` MUST come from their own queries over the whole scope. Never pass `len(rows)` as `matched` β€” that is the silent [:N] this exists to prevent: the page would report the window size as though it were the result size. Refuses the shapes that could only be a mistake, because a wrong count here is invisible on screen (it looks like a smaller dataset, not like an error). """ shown, matched, total = int(shown), int(matched), int(total) if matched > total: raise ValueError(f"matched ({matched}) exceeds total ({total}); a filter cannot match " f"more rows than the scope holds") if shown > matched: raise ValueError(f"shown ({shown}) exceeds matched ({matched}); the window cannot hold " f"more rows than the filter matched") return {"shown": shown, "matched": matched, "total": total, "windowed": True} # β›” EXIT-6 (2026-08-04): `build_html`, `component_dir`, `render` and `_DECLARED_COMPONENTS` WERE # HERE, and they are gone with Streamlit. They were the EMBED HOST β€” the path that declared the # prebuilt bundle as a `streamlit.components.v1` custom component (or injected the single-file # HTML build as a fallback) so the React grid could be drawn inside a Streamlit page. # # THIS MODULE ITSELF SURVIVES, and that distinction is the whole point: `aios_grid.py` is imported # at 11 sites across `aios-web/api/` plus `harness/semantic.py` β€” it owns the canonical field # contract, the workspace wire and the count envelope. Only the ~95 lines that knew about a HOST # went; the rest never did. Its one and only `import streamlit` lived inside `render`, lazily, and # left with it. `api/verify_no_streamlit.py` now gates that nothing here re-imports it. # # Deleted with them: `aios_grid_embed.html` + `aios_grid_component/index.html` (a 2.1 MB prebuilt # bundle), `build_embed.py` that produced them, and `deploy_hf.py`'s embed-staleness guard. The # React app is now served directly by the FastAPI container β€” there is no twin to keep fresh, so # the entire class of "the code shipped but the bundle did not" is retired rather than guarded. # -- W46-T33's SELF-CHECK --------------------------------------------------------------------- # The done-when asks that "each computed date is checked against a known correct year in a test". # There is no `test_*.py` anywhere in this repository and the `verify_*.py` gates are outside this # ticket's fence, so the check lives HERE, beside the arithmetic it checks, and runs with # `python aios_grid.py` (no store, no network, no fixture). # # β›” EVERY EXPECTED VALUE BELOW IS AN INDEPENDENT FACT, never a value produced by running the code # above it: a test whose expectations came from its own implementation is a tautology. The # Jewish anchors each carry the hebcal CONVERTER url they were fetched from, one fetch per row. # ⚠ Hebcal's holiday LISTING pages print the preceding SUNSET, one day earlier than the # converter; an expectation taken from a listing page is off by one for every Jewish holiday. _SELFCHECK_HOLIDAYS = ( # code, gregorian year, expected ISO dates ('NEW_YEARS', 2027, ['2027-01-01']), ('VALENTINES', 2027, ['2027-02-14']), ('INDEPENDENCE_DAY', 2027, ['2027-07-04']), ('HALLOWEEN', 2027, ['2027-10-31']), ('CHRISTMAS_EVE', 2027, ['2027-12-24']), # Christmas 2027 is a SATURDAY. A named holiday is the true date and must NOT shift to the # Friday, which is already Christmas Eve above. The US federal CALENDAR does shift it, and # that difference is checked as a negative control further down. ('CHRISTMAS', 2027, ['2027-12-25']), ('NEW_YEARS_EVE', 2027, ['2027-12-31']), ('MOTHERS_DAY', 2026, ['2026-05-10']), # second Sunday of May 2026 ('FATHERS_DAY', 2026, ['2026-06-21']), # third Sunday of June 2026 ('MEMORIAL_DAY', 2026, ['2026-05-25']), # last Monday of May 2026 ('LABOR_DAY', 2026, ['2026-09-07']), # first Monday of September 2026 ('THANKSGIVING', 2026, ['2026-11-26']), # fourth Thursday of November 2026 ('EASTER', 2026, ['2026-04-05']), ('EASTER', 2027, ['2027-03-28']), # hebcal.com/converter?gy=2026&gm=9&gd=12&g2h=1 -> 1 Tishrei 5787 ('ROSH_HASHANAH', 2026, ['2026-09-12']), # hebcal.com/converter?gy=2027&gm=10&gd=2&g2h=1 -> 1 Tishrei 5788 ('ROSH_HASHANAH', 2027, ['2027-10-02']), # hebcal.com/converter?gy=2030&gm=9&gd=28&g2h=1 -> 1 Tishrei 5791 ('ROSH_HASHANAH', 2030, ['2030-09-28']), # hebcal.com/converter?gy=2027&gm=10&gd=11&g2h=1 -> 10 Tishrei 5788 ('YOM_KIPPUR', 2027, ['2027-10-11']), # hebcal.com/converter?gy=2027&gm=12&gd=25&g2h=1 -> 25 Kislev 5788 ('HANUKKAH', 2027, ['2027-12-25']), # hebcal.com/converter?gy=2026&gm=4&gd=2&g2h=1 -> 15 Nisan 5786 ('PASSOVER', 2026, ['2026-04-02']), # hebcal.com/converter?gy=2028&gm=4&gd=11&g2h=1 -> 15 Nisan 5788. Together with Rosh # Hashanah 2027 above this is the STRADDLE control: both come from Hebrew year 5788, which # sits in two different Gregorian years. ('PASSOVER', 2028, ['2028-04-11']), ) _SELFCHECK_ENDS = ( # name, ends config, viewing day, expected preview of a weekly-Monday rule from 2026-01-01 ('never', {'kind': 'never'}, '2026-01-01', ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']), ('on cuts the tail', {'kind': 'on', 'date': '2026-01-26'}, '2026-01-01', ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26']), ('after 3 from the start', {'kind': 'after', 'count': 3}, '2026-01-01', ['2026-01-05', '2026-01-12', '2026-01-19']), # A count already spent by past occurrences is the case that catches the wrong reading. ('after 3 seen later', {'kind': 'after', 'count': 3}, '2026-01-13', ['2026-01-19']), ('after 3 seen past the end', {'kind': 'after', 'count': 3}, '2026-02-01', []), ('a malformed count degrades to never', {'kind': 'after', 'count': 0}, '2026-01-01', ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']), ('a garbage ends object degrades to never', 'not-an-object', '2026-01-01', ['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']), ) _SELFCHECK_WEEKLY = {'startDate': '2026-01-01', 'anchorField': {'table': 'same', 'field': 'due'}, 'rules': [{'kind': 'weekly', 'interval': 1, 'weekdays': [0]}], 'previewCount': 10} def selfcheck_recurrence(): """Return (failures, lines) for the granular holidays and the `ends` stopping condition.""" state = {'bad': 0} lines = [] def check(ok, text): state['bad'] += 0 if ok else 1 lines.append(('ok ' if ok else 'FAIL ') + text) for code, year, want in _SELFCHECK_HOLIDAYS: got = sorted(day.isoformat() for day in public_holidays(code, year)) check(got == sorted(want), '%-17s %d want %s got %s' % (code, year, want, got)) # Every selectable code must produce a date in every year of a decade, or the selector # promises a recurrence that is silently a no-op. empty = [(item['code'], year) for item in PUBLIC_HOLIDAY_CALENDARS for year in range(2026, 2036) if not public_holidays(item['code'], year)] check(not empty, 'every code yields a date for 2026..2035 (%d empty)' % len(empty)) # The registry and the computation table must not drift apart. declared = set(item['code'] for item in PUBLIC_HOLIDAY_CALENDARS if item['group'] == 'holiday') check(declared == set(_GRANULAR_HOLIDAYS), 'registry and computation table agree on %d granular codes' % len(declared)) check(all(item.get('group') in ('calendar', 'holiday') for item in PUBLIC_HOLIDAY_CALENDARS), 'every registry entry carries a group') check(not [item for item in PUBLIC_HOLIDAY_CALENDARS if 'β€”' in item['label'] or '–' in item['label']], 'no label carries an em dash or an en dash') # NEGATIVE CONTROLS. check(public_holidays('NOT_A_HOLIDAY', 2026) == frozenset(), 'NC an unknown code still returns an empty set') check(public_holidays('CHRISTMAS', 2027) != public_holidays('US', 2027), 'NC a granular code does not fall through to the US federal set') check(_dt.date(2027, 12, 25) in public_holidays('CHRISTMAS', 2027) and _dt.date(2027, 12, 25) not in public_holidays('US', 2027), 'NC Christmas 2027 is a Saturday: the named day stays, the federal calendar shifts') check(_hebrew_date(5788, _HEBREW_TISHREI, 1).year == 2027 and _hebrew_date(5788, _HEBREW_NISAN, 15).year == 2028, 'NC Hebrew 5788 straddles Gregorian 2027 and 2028') jewish = ('ROSH_HASHANAH', 'YOM_KIPPUR', 'HANUKKAH', 'PASSOVER') saved_cache = dict(_HOLIDAY_CACHE) globals()['_HOLIDAY_CACHE'] = {} globals()['_HEBREW_YEAR_CACHE'] = {} globals()['_HEBREW_EPOCH'] = _HEBREW_EPOCH + 1 broken = sum(1 for code, year, want in _SELFCHECK_HOLIDAYS if code in jewish and sorted(day.isoformat() for day in public_holidays(code, year)) != sorted(want)) globals()['_HEBREW_EPOCH'] = _HEBREW_EPOCH - 1 globals()['_HEBREW_YEAR_CACHE'] = {} globals()['_HOLIDAY_CACHE'] = saved_cache expected_jewish = len([1 for code, _, _ in _SELFCHECK_HOLIDAYS if code in jewish]) check(broken == expected_jewish, 'NC a one day epoch shift breaks all %d Jewish anchors (broke %d)' % (expected_jewish, broken)) for name, ends, today, want in _SELFCHECK_ENDS: got = recurrence_preview(dict(_SELFCHECK_WEEKLY, ends=ends), today=today) got = got[:len(want)] if want else got check(got == want, '%-42s want %s got %s' % (name, want, got)) once = clean_date_recurrence(dict(_SELFCHECK_WEEKLY, ends={'kind': 'after', 'count': 3})) check(once.get('ends') == {'kind': 'after', 'count': 3}, 'ends survives the field cleaner') check(clean_date_recurrence(once) == once, 'clean_date_recurrence is idempotent over ends') check('ends' not in (clean_date_recurrence(_SELFCHECK_WEEKLY) or {}), 'a recurrence with no ends grows no ends key') return state['bad'], lines if __name__ == '__main__': failures, report = selfcheck_recurrence() print('\n'.join(report)) print('\nRESULT: %d/%d checks passed' % (len(report) - failures, len(report))) raise SystemExit(1 if failures else 0)
"""aios_grid β€” embed the AIOS React/glide Airtable-style grid inside Streamlit.
This is REUSABLE MODULE INFRASTRUCTURE: the same self-contained grid that runs as the
standalone aios-web app is inlined into a single HTML file and hosted inside a Streamlit
component. The React bundle reads its data from `window.__AIOS_GRID__` (an object
`{fields, rows}`) that we inject into the page <head> before the app's module script runs
β€” so there is NO backend and NO /api call in the Streamlit container; the browser only ever
sees the derived JSON we hand it.
Usage (from any page):
import aios_grid
aios_grid.render(aios_grid.rows_from_pool(pool_rows), aios_grid.FIELDS)
Design notes:
* ZERO app-internal imports (no `modules.*` / `core.*`). FIELDS is a literal and
`rows_from_pool` takes already-built rows β€” so this helper is tenant/module-agnostic and
sidesteps deploy_hf.py's import guard entirely.
* The built HTML ships as `aios_grid_embed.html` in THIS directory (added to
deploy_hf.py INCLUDE). Build it with `npm run build:embed` in aios-web/web, then copy
dist-embed/index.html -> platform/aios_grid_embed.html (see build_embed.py).
For LOCAL dev before that copy, we fall back to reading dist-embed/index.html directly.
* The preferred host is a Streamlit Components v1 bridge. It sends data/view/schema args
into the React app and returns guarded events for persistence in the tenant store. The old
injected-HTML path remains a read/local-write fallback when component assets are absent.
"""
import datetime as _dt
import copy
import json
import math
import re
from decimal import Decimal, ROUND_HALF_EVEN, localcontext
from pathlib import Path
_HERE = Path(__file__).resolve().parent
# Where the inlined single-file build lives. FIRST match wins:
# 1. the shipped copy in this dir (what deploy_hf.py uploads to the Space)
# 2. the raw build output in the sibling aios-web tree (local dev, pre-copy)
_EMBED_CANDIDATES = [
_HERE / "aios_grid_embed.html",
_HERE.parent / "aios-web" / "web" / "dist-embed" / "index.html",
]
_COMPONENT_CANDIDATES = [
_HERE / "aios_grid_component",
_HERE.parent / "aios-web" / "web" / "dist-embed",
]
_DECLARED_COMPONENTS = {}
# --- the FIELD CONTRACT β€” loaded from the CANONICAL source `aios_grid_fields.json` in THIS
# directory (the SINGLE source of truth, shared with aios-web/api/main.py). source='odoo' is
# READ-ONLY; source='overlay' is the editable stratum (notes/tags) that lives OUTSIDE Odoo.
#
# Why a sibling JSON and NOT an import: aios_grid.py's contract is ZERO app-internal imports so
# it stays tenant/module-agnostic and sidesteps deploy_hf.py's import guard. A JSON next to the
# module preserves that exactly β€” no import, no guard interaction β€” while still single-sourcing
# the values (a build-time copy from another tree would reintroduce the drift we're removing).
# The file ships to the Space via deploy_hf.py INCLUDE. Edit the JSON, then run
# aios-web/verify_fields_contract.py. ---
_FIELDS_PATH = _HERE / "aios_grid_fields.json"
def _load_fields():
if not _FIELDS_PATH.is_file():
raise FileNotFoundError(
f"aios_grid: canonical field contract missing at {_FIELDS_PATH}. It is the single "
"source of truth for the grid schema and MUST ship (deploy_hf.py INCLUDE lists it)."
)
doc = json.loads(_FIELDS_PATH.read_text(encoding="utf-8"))
fields = doc.get("fields") if isinstance(doc, dict) else doc
if not isinstance(fields, list) or not fields:
raise ValueError(f"aios_grid: {_FIELDS_PATH} has no 'fields' list.")
return fields
FIELDS = _load_fields()
def product_fields():
"""The PRODUCT table's canonical contract (wave 15 C-TOPIC, `product_data` key in the same
JSON). A separate accessor rather than a second module constant so the one file-read and the
one failure mode stay shared with `FIELDS`."""
doc = json.loads(_FIELDS_PATH.read_text(encoding="utf-8"))
fields = (doc.get("product_data") or {}).get("fields")
if not isinstance(fields, list) or not fields:
raise ValueError(f"aios_grid: {_FIELDS_PATH} has no product_data.fields list.")
return fields
# text/date fields pass through untouched; every OTHER odoo (numeric) field is rounded β€”
# mirrors aios-web/api/main.py _payload() exactly so embed == standalone byte-for-byte.
def _round(v):
return round(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else v
def _round2(v):
"""D-153 (W37, asked by lane B) β€” MONEY AND PERCENT KEEP THEIR DECIMALS.
`_round`'s whole-number convention is right for counts and wrong for currency: `first_cost`
3.47 shipped as `3`, so every money cell on every Odoo grid was a whole dollar.