diff --git a/RELEASES.json b/RELEASES.json index 835d9a54cd5b57f9058f0e6facaeb623baae8dff..e61bf56959757f559aff90a1436dd194de9744de 100644 --- a/RELEASES.json +++ b/RELEASES.json @@ -1,6 +1,12 @@ { - "current": "eedfb6a", + "current": "3c72c5b", "releases": [ + { + "version": "v70", + "sha": "eedfb6a", + "date": "2026-09-03", + "subject": "release v70 - wave 50 (grid analytics, the Sheet as a spreadsheet, view trash and audit)" + }, { "version": "v69", "sha": "8598f56", diff --git a/VERSION b/VERSION index 523970ede495a3ba89455fa8d4cc15100afa057c..780f52fd255aea7c69ece67b1ccb8cef5a8047dc 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -eedfb6a +3c72c5b diff --git a/api/formula_runtime.py b/api/formula_runtime.py index dcedb7836c032c59dae3074116d76629df4e7b03..6443b91ccf02ac25c63383b46c9f1dca055d135c 100644 --- a/api/formula_runtime.py +++ b/api/formula_runtime.py @@ -880,8 +880,18 @@ def _is_range_position(fn, index): return False -def _a1_at(source, i): - """`(replacement_text, next_index)` if an A1 token starts at `i`, else None.""" +def _a1_at(source, i, default_sheet=""): + """`(replacement_text, next_index)` if an A1 token starts at `i`, else None. + + ⭐ `default_sheet` IS WHAT MAKES A WORKBOOK PASS POSSIBLE (W51-T23). An UNQUALIFIED reference + means "this tab", and the only moment anything knows which tab that is, is when the formula is + read out of a cell that lives on one. So the owning tab is supplied HERE, at rewrite time, and + `=G4+1` on `Tab05` becomes `A1REF('G4', 'Tab05')` before `_normal` ever builds a key. A + reference that names its own sheet keeps that name; nothing else in the pipeline changes. + ⛔ THE ALTERNATIVE WAS MEASURED AND IS WORSE: qualifying the SPEC KEYS alone and leaving the + formulas untouched makes cross-tab keys resolvable and breaks every local reference, which the + wave-51 prototype recorded as 3,770 blanks against a true 785. + """ m = _A1_RE.match(source, i) if not m: return None @@ -893,7 +903,7 @@ def _a1_at(source, i): return None # a function call, not an address. See the note above. if nxt < len(source) and (source[nxt].isalnum() or source[nxt] in "_$!"): return None # the token does not end here, so it is not an address - sheet = m.group(1) or m.group(2) or "" + sheet = m.group(1) or m.group(2) or default_sheet first = (m.group(3) or "") + (m.group(4) or "") if m.group(5): last = m.group(5) + (m.group(6) or "") @@ -901,8 +911,12 @@ def _a1_at(source, i): return f"A1REF({first!r}, {sheet!r})", end -def _rewrite(source): - """Translate Excel punctuation to Python AST punctuation without touching strings.""" +def _rewrite(source, sheet=""): + """Translate Excel punctuation to Python AST punctuation without touching strings. + + `sheet` is the tab this formula LIVES ON, and every reference that does not name a tab of its + own is read as pointing at that one. See `_a1_at` for why it enters the pipeline here. + """ out, i, quote = [], 0, None while i < len(source): c = source[i] @@ -913,16 +927,6 @@ def _rewrite(source): out.append(source[i + 1]); i += 2; continue quote = None i += 1; continue - if c in ("'", '"'): - quote = c; out.append(c); i += 1; continue - if c == "{": - end = source.find("}", i + 1) - if end < 0: - raise FormulaError("a field reference is missing its closing }") - key = source[i + 1:end].strip() - if not re.fullmatch(r"[A-Za-z0-9_]+", key) or len(key) > MAX_FIELD_KEY: - raise FormulaError("a field reference may contain only letters, digits and _") - out.append(f"REF({key!r})"); i = end + 1; continue # ⭐ AN A1 TOKEN IS ONLY TRIED AT AN IDENTIFIER BOUNDARY. Without this guard the scanner # would happily match the tail of a longer name, so `myB4` would end up holding a reference # to cell B4. The previous SOURCE character decides, not the previous emitted one, because @@ -931,6 +935,17 @@ def _rewrite(source): # True, because "" is a substring of every string. That silently disabled A1 addressing for # any formula STARTING with a reference, which is most of them, while leaving `SUM(B4:B8)` # working because its `B` follows a `(`. Compare against a tuple, which has no such edge. + # + # ⛔⛔ THIS BLOCK SITS ABOVE THE QUOTE BRANCH, AND THAT ORDER IS THE WHOLE OF D-638 + # (W51-T23). It used to sit below, so a leading `'` ALWAYS entered string mode first: + # `'Data'!B12` was emitted as the Python string `'Data'` followed by a separately rewritten + # `!B12` with an EMPTY sheet name, which cannot parse, and Excel's own quoted spelling came + # back as "the formula could not be parsed". The guard below already reads `c in ("$", "'")` + # because the author meant this branch to see a quote; it simply never got the chance. + # ⭐ MOVING IT IS SAFE BECAUSE `_a1_at` IS ALL OR NOTHING: it answers None unless the whole + # `'name'!ADDR` shape matches, so a `'...'` used as TEXT falls straight through to the + # quote branch below and keeps working. `"` never reaches here at all, since the guard + # admits only letters, `$` and `'`. prev = source[i - 1] if i else "" if (c.isalpha() or c in ("$", "'")) and not (prev.isalnum() or prev in ("_", "$")): # ⭐ A DOTTED EXCEL NAME IS FOLDED BEFORE THE A1 ATTEMPT (W50-T16). `STDEV.P(` must @@ -942,11 +957,21 @@ def _rewrite(source): out.append(dotted.group(1).upper() + "_P") i = dotted.end() continue - got = _a1_at(source, i) + got = _a1_at(source, i, sheet) if got: text, i = got out.append(text) continue + if c in ("'", '"'): + quote = c; out.append(c); i += 1; continue + if c == "{": + end = source.find("}", i + 1) + if end < 0: + raise FormulaError("a field reference is missing its closing }") + key = source[i + 1:end].strip() + if not re.fullmatch(r"[A-Za-z0-9_]+", key) or len(key) > MAX_FIELD_KEY: + raise FormulaError("a field reference may contain only letters, digits and _") + out.append(f"REF({key!r})"); i = end + 1; continue two = source[i:i + 2] if two in ("<=", ">=", "!=", "=="): out.append(two); i += 2; continue @@ -1027,8 +1052,16 @@ def _normal(node, depth=0): raise FormulaError("formula contains unsupported syntax") -def parse_formula(source): +def parse_formula(source, *, sheet=""): + """One formula's stored definition. `sheet` is the tab it lives on, or "" for a grid field. + + ⭐ KEYWORD ONLY, AND DEFAULTED TO "", so every caller that has no notion of a tab keeps the + definition it always had: with no sheet, an unqualified reference still keys as the bare `B4` + that `evaluate_fields` and `routes_query.py::parse_formula` already read. Only a Sheet supplies + a tab, and only then do this formula's own references key as `TAB!B4`. + """ source = str(source or "") + sheet = str(sheet or "") if not source.strip(): raise FormulaError("the formula is empty") if len(source) > MAX_SOURCE: @@ -1038,7 +1071,7 @@ def parse_formula(source): # Python 3.12 warns while parsing them even though the string is valid for this grammar. with warnings.catch_warnings(): warnings.simplefilter("ignore", SyntaxWarning) - parsed = ast.parse(_rewrite(source), mode="eval") + parsed = ast.parse(_rewrite(source, sheet), mode="eval") except (SyntaxError, ValueError) as exc: raise FormulaError("the formula could not be parsed") from exc if sum(1 for _ in ast.walk(parsed)) > MAX_NODES: @@ -2160,12 +2193,52 @@ def evaluate_fields(definitions, row, *, today=None): return {"values": {key: values.get(key) for key in definitions}, "errors": errors} -def evaluate_sheet(cells, *, today=None): - """Evaluate a whole SHEET of A1 cells in dependency order (wave 49, W49-T03). +def _sheet_half(key): + """The tab a lookup key names, upper cased, or "" when the key is a bare address.""" + text = str(key) + return text.rsplit("!", 1)[0].upper() if "!" in text else "" + + +def _unknown_sheets(definition, known): + """Every tab this formula points at that the workbook does not have, in the order found. + + ⛔ IT WALKS `definition["cells"]`, NOT THE EVALUATOR'S NODE LOOKUP, AND THAT IS THE POINT. + `_range_arg` treats a key missing from `row` as a BLANK CELL on purpose, because a rectangle + almost always contains empty cells; so a check living in the lookup would catch + `='Ghost'!A1` and let `=SUM('Ghost'!A1:B9)` answer a confident 0. `cells` carries every + address a formula names, scalar and range alike, so one walk covers both. + """ + out = [] + for key in definition.get("cells") or (): + name = _sheet_half(key) + if name and name not in known and name not in out: + out.append(name) + return out + + +def evaluate_sheet(cells, *, today=None, sheets=None): + """Evaluate a whole WORKBOOK of A1 cells in dependency order (wave 49 W49-T03, W51-T23). `cells` is `{addr_key: {"formula": "=..."} or {"value": v}}` where `addr_key` is what - `a1_key` produces: `B4` on this tab, `SHEET2!C3` on another. Returns - `{"values": {addr: value}, "errors": {addr: code}}`. + `a1_key` produces: `B4` on a single unnamed tab, `SHEET2!C3` when the caller keys a workbook. + Returns `{"values": {addr: value}, "errors": {addr: code}}`. + + ⭐⭐ A SPEC ENTRY MAY CARRY `"sheet"`, AND THAT IS HOW A WORKBOOK GETS ONE MEMOIZED PASS + (W51-T23). It names the tab that cell lives on, and it is handed to `parse_formula` so this + formula's own unqualified references key as `TAB!B4` rather than `B4`. Every tab in the book + therefore goes into ONE `cells` dict with one `resolve` memo over it, so a cross-tab reference + is an ordinary lookup and a chain that crosses tabs twice is still computed once. + ⛔ QUALIFYING THE KEYS WITHOUT `"sheet"` IS THE PROTOTYPE'S FAILURE MODE 3, MEASURED: cross-tab + references resolve and every LOCAL one breaks, 3,770 blanks against a true 785. + + `sheets` is the list of tab names the workbook actually has. When it is supplied, a formula + naming a tab outside it is refused `unknown_sheet` rather than quietly reading as blank; when + it is None nothing is checked, so every wave-49 caller keeps its behaviour exactly. + + ⚠ `SHEET_ADDR_KEY` IS STILL HANDED THE FULL KEY, and `ROW()` / `COLUMN()` still answer, + because `_call` splits an address at its last `!` before `_split_addr` reads it. That split + lands the same way for `G4` and for `TAB05!G4`, so the bare and the argument spelling both + survive a workbook pass. It has its own gate leg because it does not look like it would. ⛔⛔ **THE REFUSAL IS `circular_reference`, AND IT IS DELIBERATELY NOT THE `"cycle"` THAT `evaluate_fields` ALREADY USES.** Renaming that one was considered and rejected on evidence: @@ -2184,6 +2257,7 @@ def evaluate_sheet(cells, *, today=None): """ values, errors, active, resolved = {}, {}, [], set() parsed = {} + known = None if sheets is None else {str(n).upper() for n in sheets if str(n or "")} for addr, spec in (cells or {}).items(): if not isinstance(spec, dict): @@ -2202,10 +2276,19 @@ def evaluate_sheet(cells, *, today=None): raw = spec.get("formula") if isinstance(raw, str) and raw.strip().startswith("="): try: - parsed[addr] = parse_formula(raw.strip()[1:]) + definition = parse_formula(raw.strip()[1:], sheet=str(spec.get("sheet") or "")) except FormulaError: errors[addr] = "bad_formula" values[addr] = None + continue + # ⛔ A MISSING TAB IS ITS OWN REFUSAL, NOT A BLANK. Left to the lookup it would read as + # `unknown_ref` at best and as a confident 0 through a range at worst, and both send + # the reader to inspect a formula that is correct except for a tab that is not there. + if known is not None and _unknown_sheets(definition, known): + errors[addr] = "unknown_sheet" + values[addr] = None + continue + parsed[addr] = definition else: values[addr] = spec.get("value") diff --git a/api/routes_grid.py b/api/routes_grid.py index cbe4ff5c5ed25c23bd160158e92ee389493bdb05..759f60c64366b42b96bfa831ea970035197a19d9 100644 --- a/api/routes_grid.py +++ b/api/routes_grid.py @@ -108,7 +108,7 @@ def _scope_or_400(raw): return scope if scope not in _SCOPES: raise err(400, "bad_scope", - f"scope must be one of {', '.join(_SCOPES)} — refusing to guess") + f"scope must be one of {', '.join(_SCOPES)}. Refusing to guess") return scope @@ -814,7 +814,7 @@ def grid_timeseries(body: dict = Body(default=None), scope: str = "customer", _sc = _scope_or_400(scope) if _sc == "product" or _sc.startswith("ut_"): raise err(400, "bad_timeseries", - "this surface has no time-series channel — measures are customer-grain") + "this surface has no time-series channel, because measures are customer-grain") body = body or {} bucket = body.get("bucket") @@ -1084,7 +1084,7 @@ def grid_calendar_metrics(body: dict = Body(default=None), scope: str = "custome _sc_cal = _scope_or_400(scope) if _sc_cal == "product" or _sc_cal.startswith("ut_"): raise err(400, "bad_calendar_metrics", - "the product surface has no measure channel yet — measures are customer-grain") + "the product surface has no measure channel yet, because measures are customer-grain") body = body or {} raw_groups = body.get("groups") @@ -1984,7 +1984,7 @@ def grid_events_route(body: dict = Body(default=None), raise err(409, "pid_scope_unresolved", f"this database is served through the connector mirror and its rows " f"cannot be listed in one window, so a change addressed to particular " - f"records ({len(named)} of {len(events)} here) cannot be admitted — " + f"records ({len(named)} of {len(events)} here) cannot be admitted. " f"{lim.get('cause') or 'the row set is unresolved'}. " f"{lim.get('recommendation') or ''}".strip()) else: @@ -2026,7 +2026,7 @@ def grid_events_route(body: dict = Body(default=None), results.append(row) except grid_events.StoreUnavailable: raise err(503, "store_unavailable", - "the tenant store is unavailable — none of your changes were saved") + "the tenant store is unavailable, so none of your changes were saved") out = {"results": results, "rerender": any(r["rerender"] for r in results)} if ctx.out.refusals: @@ -2615,3 +2615,136 @@ def grid_hop_topics(session: Session = Depends(require_session)): if not odoo_relational.is_royal(session.tenant): return {"topics": [], "windows": [], "omissions": []} return _hop_topic_offer() + + +# ═══════════════════════════════════════════════════════════════════════════════════════════════ +# ⭐⭐ W51-T05 / RULING R2 / CONTRACT C6 — RELATED DATABASES, SERVED. +# +# R2: *"A 'Linked database' tab exists for FORWARD link fields, REVERSE links (another table's link +# field pointing at this table) and the ODOO BRIDGES … one tab per related table, resolved +# server-side; two links between the same pair give two tabs subtitled by the field."* +# +# ⛔ RESOLVED SERVER-SIDE IS THE RULING, NOT AN IMPLEMENTATION NOTE. `types.ts::relationalTargets` +# is the client's forward-only derivation and it STAYS, because it answers a different question +# (which of MY columns is a link) on data the client already holds. It cannot see a reverse link — +# that needs every other definition in the tenant — and it cannot see a bridge, which is not a +# field at all. So this route is additive to it rather than a replacement for it. +# +# ⛔ `grid_pivot` CANNOT SUBSTITUTE AND D-484 IS WHY. `_PIVOT_ROUTES` declares exactly ONE pair, +# `("customer_data", "product_data")`, while every link field on `customer_data` targets a +# `ut_odoo_*` grid and NO link field anywhere targets `product_data`. The two halves of the +# relational feature offer exactly disjoint sets, so the one pivot that is declared is the one that +# is never offered. This route is the other half of that repair: it OFFERS the edges that exist. +# ═══════════════════════════════════════════════════════════════════════════════════════════════ + +#: The two registry modules whose link fields are PRE-SET rather than tenant-authored. Their bags +#: come from `odoo_relational.module_link_fields`, which `automation_engine` reaches by STRING +#: (`getattr(_rel, "module_link_fields", None)`) — so it is read here and never moved, renamed or +#: shadowed. `core/relations.py` declares the BRIDGES; that function keeps declaring the FIELDS. +_PRESET_LINK_MODULES = ("customer_data", "product_data") + + +def _may_open(session: Session, key: str): + """May this session open `key` at all? The SAME two gates `_pivot_side` applies, minus the rows. + + ⛔ THE ROWS ARE THE POINT OF THE DIFFERENCE. `_pivot_side` calls `perm_scope.scoped_table`, + which materialises every row of the side it is checking; a listing that asked that question of + a dozen candidate targets would read a dozen whole databases to draw a tab strip. The WALL is + `session.require` plus `perm_scope.scoped_fields`, and both of those answer without a row. + + ⚠ FAIL CLOSED. Any refusal, any unknown table, any error is False. A target this account may + not open must not appear in the strip, because the tab would 403 on the first click and read as + a broken product rather than as a permission. + """ + import core.perm_scope as perm_scope + + try: + session.require(key) + except HTTPException: + return False + except Exception: # noqa: BLE001 + return False + try: + perm_scope.scoped_fields(session.user, key, st=session.runtime) + except Exception: # noqa: BLE001 + return False + return True + + +def _source_fields(session: Session, table: str): + """The link-bearing field list for `table`, under this session's field wall. + + ⛔⛔ THE PRE-SET COLUMNS ARE NOT IN `scoped_fields` AND THAT IS THE TRAP THIS FUNCTION EXISTS + FOR. `odoo_relational.module_link_fields`' own docstring says so: *"`routes_customers` / + `routes_products` still build their field lists from `aios_grid` alone, so today these columns + live only inside the relational pass."* A `/related` answer built from `scoped_fields` alone + would therefore report ZERO forward links on `customer_data` — the one grid that has three — + and look entirely correct doing it. + ⚠ APPENDED, NOT MERGED BY KEY: a tenant cannot author a field on a registry module, so the two + lists cannot collide, and a union keyed on `key` would hide that if they ever did. + """ + import core.perm_scope as perm_scope + + try: + fields = list(perm_scope.scoped_fields(session.user, table, st=session.runtime) or ()) + except Exception: # noqa: BLE001 + fields = [] + if table in _PRESET_LINK_MODULES: + try: + import odoo_relational + fields = fields + list(odoo_relational.module_link_fields(table) or ()) + except Exception: # noqa: BLE001 + pass + return fields + + +def related_entries(session: Session, table: str): + """C6's `/related` list for `table`, ALREADY NARROWED to targets this session may open. + + `[{key, label, via: {direction, key, field?, on?, from?}, target, served, where?}]`. + + ⛔ THE NARROWING HAPPENS HERE AND NOWHERE ELSE, so the listing door and the pinned read agree + by construction: `routes_odoo_tables._compiled_read` resolves a `related` pin by calling THIS + function, which means an edge a reader cannot be offered is also an edge they cannot pin. A + second, laxer resolution on the read side would be a permission wall with a hole in it. + """ + import core.relations as relations + import core.user_tables as user_tables + + table = str(table or "") + defs = {} + try: + defs = dict(user_tables.all_defs(st=session.runtime) or {}) + except Exception: # noqa: BLE001 + defs = {} + entries = relations.related(table, fields=_source_fields(session, table), defs=defs) + return [e for e in entries if _may_open(session, e["target"])] + + +@router.get("/grid/{table}/related") +def grid_related(table: str, session: Session = Depends(require_session)): + """C6 — every database related to `table`, one entry per edge, under the caller's scope. + + `{ok, table, related: [{key, label, via, target, served, where?}]}`. + + ⭐ ONE ENTRY PER EDGE, NOT PER TARGET. R2: *"two links between the same pair give two tabs + subtitled by the field"* — so `key` is the EDGE's identity and `via.key` repeats it, because + `via` is the whole of what the pinned read is handed back and it has to identify an edge on its + own. Two bridges off `customer_data` really do share `{direction: "bridge", on: "partner_id"}`. + + ⭐ `served` IS PART OF THE ANSWER, AND R6'S SECOND SENTENCE IS WHY. A declared edge whose + target is served from its stored copy cannot be pinned yet (that door takes no predicate), and + the caller is told which ones those are rather than discovering it as an empty tab. Open + invoices is the one such edge today. + + ⛔ THE CALLER'S OWN ACCESS IS CHECKED FIRST. Listing what `table` is related to tells you what + `table` is, so the listing is behind the same gate the grid is. + """ + table = str(table or "").strip() + if not table: + raise err(400, "bad_table", "name the database to list relations for") + if not _may_open(session, table): + raise err(403, "not_permitted", + f"your account may not open '{table}', so it cannot be told what that database " + f"is related to. Ask an administrator for access to it") + return {"ok": True, "table": table, "related": related_entries(session, table)} diff --git a/api/routes_odoo_tables.py b/api/routes_odoo_tables.py index 9b12d5db4f66d0eac5b050f921d75c87ad55da12..4321da7e102159354ce35bcfd3153b44bd77b9aa 100644 --- a/api/routes_odoo_tables.py +++ b/api/routes_odoo_tables.py @@ -245,7 +245,7 @@ def odoo_tables_status(brief: bool = Query(False), # why this grid still keeps its rows in the tenant document, when it does not have to "materialisedBecause": (why_not.get(key, "") if materialised else ""), "refreshed": (max([s for s in stamps if s], default="") if materialised - else "live — read through the mirror"), + else "live, read through the mirror"), "locked": table.get("recordMode") == user_tables.AUTOMATION_RECORD_MODE, # W30/R7: whether this database is served THROUGH the mirror rather than from the copy # above. Reported per table, because they convert one at a time and an operator @@ -1222,8 +1222,209 @@ def apply_filtered_bulk(table_key: str, body: dict = Body(default=None), _TREE_UNSET = object() +# ═══════════════════════════════════════════════════════════════════════════════════════════════ +# ⭐⭐ W51-T05 / C6 — THE PINNED READ. `related: {table, record, via}` narrows this grid to the rows +# linked to ONE record of another database, AHEAD of anything the client asked for. +# ═══════════════════════════════════════════════════════════════════════════════════════════════ + +#: Past this many pinned ids the `IN (...)` list is worth a sentence. ⛔ IT IS NOT A CAP — standing +#: rule 1 forbids one on connected-source data, and its SECOND sentence is the half that gets +#: dropped: a cost that cannot be removed is REPORTED with a cause and a recommendation. A customer +#: with 40,000 order lines gets all 40,000; they are also told why the page took a moment. +_PIN_REPORT_AT = 20_000 + + +def _related_source_value(session, entry, record): + """The value of the SOURCE record that this edge is keyed on. + + ⭐ USUALLY THE RECORD ID ITSELF, and that is the cheap path: `customer_data.pid` IS the Odoo + `res.partner` id and `ut_odoo_orders.pid` IS the `sale_order` id, so three of the five bridges + need no lookup at all. + + ⛔⛔ `product_data` IS THE EXCEPTION AND IT IS NOT AN EDGE CASE — it is one of the two grids R2 + names. `product_data.pid` is `crc32(default_code)` (`modules/product_data.sku_pid`), NOT an + Odoo id, so matching it against `sale_order_line.product_id` resolves ZERO rows for every + product, silently, and paints as "this product has never been ordered". The row's `product_id` + column carries Odoo's own id (W33-T43 / A2) and that is what the bridge is declared on, so the + cell has to be read off the source record. + + ⚠⚠ THE READ IS THE SAME SCOPED ONE `_pivot_side` USES, AND IT IS **NOT** THE SAME COST, WHICH + AN EARLIER DRAFT OF THIS DOCSTRING CLAIMED. It reads a whole module pool (5,873 products / + 3,643 customers on tenant #0, from the prewarmed cache rather than from Odoo) and scans it + linearly for one `pid`. `grid_pivot` pays that ONCE PER PIVOT; this path pays it ONCE PER PAGE, + so a reader scrolling a pinned grid pays it again on every window. The frequency is the + difference and asserting parity would have hidden it. Reported to the reader as a `limits` + sentence by the caller, and booked as a PENDING row with a testable exit condition rather than + left as a comment nobody costs. + + ⛔ A RECORD THAT IS NOT IN THE SCOPED SET ANSWERS None, WHICH THE CALLER TURNS INTO A REFUSAL. + Falling back to the raw `record` would pin the target grid on a value from a row this reader + may not see, which is the permission wall leaking through the join. + """ + import core.perm_scope as perm_scope + import core.relations as relations + + frm = str((entry.get("via") or {}).get("from") or relations.IDENTITY_COL) + if frm == relations.IDENTITY_COL: + return record + # ⚠ STAMPED BY THE CALLER (`__source__`), not carried on the wire: an entry describes an edge + # FROM a table, and which table that was is the caller's own question, never the client's. + source = str(entry.get("__source__") or "") + if not source: + return None + try: + rows = perm_scope.scoped_table(session.user, source, st=session.runtime) or [] + except Exception: # noqa: BLE001 + return None + want = str(record) + for row in rows: + if str(row.get("pid")) == want: + got = row.get(frm) + return got if got not in (None, "") else None + return None + + +def _related_pin(table_key, session, spec, base_where, wall_params, cur, related): + """`(sql, params, notes)` for C6's pinned read, or `(None, [], [])` when nothing is pinned. + + ⛔⛔ WHY THIS DOES NOT CALL `compile_filter_tree(member_ids=)`, WHICH IS WHAT C6'S SENTENCE + SAYS. Measured against `platform/harness/filter_sql.py` on 2026-09-03, that call cannot express + a pinned read and the failure is silent in the widening direction, twice over: + + 1. `:583` returns None the moment the tree is INACTIVE, and the `member_ids` branch is BELOW + that return. A pin with no client filter is exactly the inactive case, so the ids would be + dropped and the whole table served. + 2. `:588` emits `(tree OR id_sql IN (...))`. Its own docstring: *"`member_ids` reproduces + `members.has(r.pid) || matchFilterTree(...)`"*. That is a UNION. ORing a pin onto a + filter WIDENS; a pinned read needs an INTERSECTION. + + So the tail is compiled by `core.relations.pin_sql`, in `filter_sql`'s OWN spelling (proven + byte for byte by `verify_pivot.py`, not by this comment), and ANDed in. `filter_sql.py` is lane + B's file this wave; a narrowing member mode there is an AMENDMENT and is booked in the handoff, + not edited in from here. + + ⭐ `id_sql` IS PASSED EXPLICITLY, AS `spec["id"]`, AND IS NEVER DEFAULTED. `harness/semantic.py` + defaults it to `f"{alias}.id"` inside its OWN compile calls; a call from the route layer never + reaches that line, and `filter_sql:586` RAISES without it. It matters that it is per table + rather than a literal `id`: `ut_odoo_order_lines` is join-shaped and its identity is `sol.id`, + so a bare `id` would be ambiguous across `sale_order_line` and `sale_order`. It is the same + expression this route already trusts as `tiebreak_sql` and as the fallback ORDER BY. + """ + import core.relations as relations + + if isinstance(related, str): + related = _json_arg(related, "related") + if related in (None, "", {}): + return None, [], [] + if not isinstance(related, dict): + raise err(400, "bad_relation", + "`related` must be an object naming the record to pin these rows to: " + "{table, record, via}") + + source = str(related.get("table") or "") + record = related.get("record") + via = related.get("via") + if not source or record in (None, "") or not isinstance(via, dict): + raise err(400, "bad_relation", + "a pinned read needs the record's database, the record id and the relation to " + "follow, as {table, record, via}. Ask GET /api/v1/grid/" + (source or "{table}") + + "/related for the relations this account may follow") + + from routes_grid import _may_open, related_entries + + if not _may_open(session, source): + # ⚠ THE CAUSE IS NAMED AS A PAIR, ON PURPOSE. `_may_open` is fail-closed and answers False + # both for a genuine permission refusal and for a database it could not read at all, so a + # sentence claiming only the first would tell a reader their access was revoked when the + # store had merely hiccupped. Naming both is honest and still refuses. + raise err(403, "not_permitted", + f"'{source}' could not be opened for your account, either because it is not " + f"granted to you or because it could not be read just now, so rows here cannot " + f"be pinned to one of its records. Ask an administrator for access to that " + f"database, or try again") + + # ⛔ RESOLVED AGAINST THE **SCOPED** LISTING, which is what makes "an edge you cannot be + # offered is an edge you cannot pin" structural rather than remembered. `related_entries` is + # the same function `GET /grid/{table}/related` answers with; there is no second resolution. + entries = related_entries(session, source) + entry = relations.pick(entries, via) + if entry is None: + raise err(400, "unknown_relation", relations.unknown_via_refusal(source, via)) + entry = dict(entry, __source__=source) + + if str(entry.get("target") or "") != str(table_key): + raise err(400, "unknown_relation", + f"the relation '{entry.get('key')}' on '{source}' points at " + f"'{entry.get('target')}', not at '{table_key}', so it cannot narrow this " + f"database. Read the database the relation names, or ask for the relation that " + f"reaches this one") + if not entry.get("served", True): + raise err(409, "relation_not_served", relations.unserved_target_refusal(entry)) + + on = str((entry.get("via") or {}).get("on") or "") + # ⚠ `spec["cols"]`, NOT the caller's narrowed `cols`. The join column is a JOIN, not a value + # this response returns: a relation must keep working when an administrator has hidden the id + # column it runs over, and no cell of it is ever projected. The hidden-field closure still + # governs everything that reaches the wire, one layer up. + binding = (spec.get("cols") or {}).get(on) + if not binding: + raise err(409, "relation_not_served", + f"'{table_key}' has no live expression for '{on}', which is the column this " + f"relation joins on, so the rows cannot be narrowed to one record here. Open " + f"this database directly, or ask for '{on}' to be added to its live connection") + on_expr, on_cast = binding[0], binding[1] + + value = _related_source_value(session, entry, record) + if value in (None, ""): + raise err(400, "unknown_relation", + relations.unresolvable_source_refusal(source, entry)) + try: + value = on_cast(value) + except Exception: # noqa: BLE001 + value = str(value) + + # ── the member ids, in ONE SQL over the bridge column (the ticket's `how:`) ──────────────── + # ⛔ NOT THROUGH `datastore.window`: that clamps at `WINDOW_MAX` (5,000) rows, so a customer + # with more order lines than that would be pinned to the first 5,000 of them and the tab would + # show a smaller, entirely plausible number with nothing red anywhere. Standing rule 1: no cap + # on data from a connected source. + # ⚠ THE WALL RIDES ALONG. Resolving ids under `base_where` means the id SET a scoped reader can + # produce is already narrowed to rows they may see, so the pin cannot be used to learn how many + # rows exist beyond their boundary. + frm_body = spec["from_sql"] if spec.get("from_sql") else spec["table"] + parts = [p for p in (base_where, entry.get("where")) if p] + parts.append(f"{on_expr} = ?") + pred = " AND ".join(f"({p})" for p in parts) + ids = [int(r[0]) for r in cur.execute( + f'SELECT DISTINCT {spec["id"]} FROM {frm_body} WHERE {pred}', + list(wall_params) + [value]).fetchall() if r and r[0] is not None] + + notes = [] + # ⭐ STANDING RULE 1'S SECOND SENTENCE, ON A COST RATHER THAN ON A CAP. Nothing is limited + # here; the reader is told that this particular relation is answered by reading the source + # database once per page, because it is keyed on a column rather than on the record id. + if str((entry.get("via") or {}).get("from") or "") != relations.IDENTITY_COL: + notes.append({ + "subject": "related", "effect": "slow", + "cause": f"this relation is keyed on the '{entry['via']['from']}' column of " + f"'{source}' rather than on its record id, so every page of these rows is " + f"resolved by reading that database first", + "recommendation": "read this database on its own and filter it on " + f"'{on}' if you are paging through a large set"}) + if len(ids) >= _PIN_REPORT_AT: + notes.append({ + "subject": "related", "effect": "slow", + "cause": f"this record is linked to {len(ids):,} rows, and each page names every one " + f"of them in the query that narrows this database to them", + "recommendation": "add a filter beside the relation to ask a smaller question, or " + "read this database on its own"}) + + sql, params = relations.pin_sql(spec["id"], ids) + return sql, params, notes + + def _compiled_read(table_key, session, *, filters=None, filterConj="and", sorts=None, - search=None, tree=_TREE_UNSET): + search=None, tree=_TREE_UNSET, related=None): """EVERYTHING THAT DECIDES **WHICH ROWS** A CONNECTED GRID MAY ANSWER OVER, compiled once. Returns `{defn, fields, cur, spec, cols, base_where, wall_params, where, params, limits, @@ -1246,6 +1447,14 @@ def _compiled_read(table_key, session, *, filters=None, filterConj="and", sorts= wall refuse is unchanged. A caller that already holds a decoded tree (the aggregates door, whose body `_selection_query` has validated) passes `tree=` instead. Exactly one of the two, in the shape `datastore.window` uses for `table`/`from_sql`. + + ⭐⭐ `related` (W51-T05 / C6) IS `{table, record, via}` AND IT LANDS HERE FOR THE SAME REASON + EVERYTHING ELSE DOES. ⛔ THE TWO DOORS SPELL IT DIFFERENTLY ON THE WIRE and that is not a + choice: `/rows` is a GET whose predicate arrives as JSON in a query STRING (the `filters` + precedent), `/aggregates` is a POST whose predicate arrives as a BODY KEY. This argument + accepts either, exactly as `filters`/`tree` already does, so the pin cannot end up applied on + one door and not the other - which would be C1's promise broken in the direction nobody + notices, an aggregate over a whole database sitting under a tab about one record. """ from routes_tables import _defn_or_refuse @@ -1392,6 +1601,25 @@ def _compiled_read(table_key, session, *, filters=None, filterConj="and", sorts= else: sort_spec = list(sorts or []) + # ── W51-T05 / C6 — THE PIN, FOLDED INTO THE BASELINE ────────────────────────────────────── + # ⛔⛔ INTO `base_where`, NOT INTO `where`, AND THE DIFFERENCE IS THREE NUMBERS ON SCREEN. + # `base_where` is what `totalUnfiltered` counts and what the wall is made of; `where` is that + # plus the reader's own conditions. A relation is NOT one of the reader's conditions - it is + # the SCOPE of the tab they opened, exactly as an administrator's row wall is - so "N of M" + # under a Linked-database tab must mean "N of M rows related to THIS record". Folding it in + # here also means `total`, `totalUnfiltered`, the deep-page walk and C1's aggregates all + # inherit it from the ONE compiler, which is the promise this function exists to keep: a + # summary that ignored the pin while the window respected it would be a plausible number + # describing a different population. + # ⭐ AND IT IS AHEAD OF ANY CLIENT FILTER, which is C6's word for it: the predicate below is + # ANDed on top of this, never merged into it. + _pin_sql, _pin_params, _pin_notes = _related_pin( + table_key, session, spec, base_where, wall_params, cur, related) + if _pin_sql: + base_where = f"({base_where}) AND {_pin_sql}" if base_where else _pin_sql + wall_params = list(wall_params) + list(_pin_params) + limits.extend(_pin_notes) + # R6's SECOND SENTENCE, ON THE WALL ITSELF. The precision note further down covers the # conditions a USER sends; the same arithmetic governs the one an ADMINISTRATOR stored, and # a scoped reader has no other way to learn that the boundary they are held to is evaluated @@ -1496,6 +1724,7 @@ def odoo_table_rows(table_key: str, filterConj: str = Query(default="and"), sorts: str = Query(default=None), search: str = Query(default=None), + related: str = Query(default=None), session: Session = Depends(require_session)): """ONE WINDOW over a connected grid, read straight from the mirror (contract C2). @@ -1509,6 +1738,16 @@ def odoo_table_rows(table_key: str, that CANNOT (a column with no mirror expression, an op the compiler refuses) is reported in `limits` with its cause and a recommendation — R6's second sentence — and never silently dropped, because an ignored condition widens. + + ⭐⭐ `related` (W51-T05 / C6) IS A **JSON QUERY STRING**, copying the `filters` precedent one + argument over: `?related={"table":"customer_data","record":1234,"via":{...}}`. It narrows this + window to the rows linked to that ONE record, ahead of `filters`, and `total` / + `totalUnfiltered` count inside the pin rather than around it. + ⛔ `routes_connected_tables.connected_table_rows` - the source-neutral ALIAS onto this + function - forwards its arguments BY NAME and does not forward this one, so a pinned read must + name THIS route. That file is in no lane's fence this wave; the one-line forward is booked in + W51-T05's handoff. Degrading to an UNPINNED read is the behaviour that shipped rather than a + new wrong answer, which is the one direction this gap is allowed to be wrong in. """ import aios_grid import core.perm_scope as perm_scope @@ -1521,7 +1760,7 @@ def odoo_table_rows(table_key: str, # a WINDOW alone needs: the total order, the projection, the overlay merge and the two # sentences a page earns (`window_clamped`, the deep-page walk). read = _compiled_read(table_key, session, filters=filters, filterConj=filterConj, - sorts=sorts, search=search) + sorts=sorts, search=search, related=related) defn, fields, cur, spec = read["defn"], read["fields"], read["cur"], read["spec"] cols, limits, frm = read["cols"], read["limits"], read["frm"] base_where, wall_params = read["base_where"], read["wall_params"] @@ -1868,9 +2107,13 @@ def odoo_table_aggregates(table_key: str, body: dict = Body(default=None), session: Session = Depends(require_session)): """SERVER-SIDE SUMMARIES over the WHOLE predicate a server-windowed grid is showing (C1). - Body `{filters, filterConj, search, groupBy?, aggs: [{colId, agg, p?}]}`; response + Body `{filters, filterConj, search, related?, groupBy?, aggs: [{colId, agg, p?}]}`; response `{ok, total_rows, aggregates, groups?, limits}`. + ⚠ `related` IS A BODY KEY HERE AND A JSON QUERY STRING ON `/rows`. Same object either way + (`{table, record, via}`), same compiler, two transports - because this door is a POST and that + one is a GET, and the wire cannot be identical when the method is not. + ⛔⛔ THE POINT IS THAT IT IS **NOT** THE WINDOW. `/rows` answers 200 rows at a time, so a summary computed from what arrived would change as the reader scrolled and nothing would say so (D-159). This computes over every row the same predicate matches: the SAME predicate, from @@ -1899,8 +2142,14 @@ def odoo_table_aggregates(table_key: str, body: dict = Body(default=None), if group_by is not None and not isinstance(group_by, str): raise err(400, "bad_selection", "groupBy must be a column id") + # ⛔⛔ THE PIN RIDES THE **SAME** COMPILER, AND THIS ONE LINE IS THE WHOLE OF CORRECTION (3). + # `/rows` takes `related` as a JSON query STRING and this door takes it as a BODY KEY; a worker + # who assumed both were bodies would have wired the rows and left the summaries answering over + # the entire database under a tab that names one record. `_compiled_read` accepts either shape, + # so the two doors cannot pin differently without this argument being deleted. read = _compiled_read(table_key, session, tree=query["filters"], - filterConj=query["filterConj"], search=query["search"]) + filterConj=query["filterConj"], search=query["search"], + related=payload.get("related")) out = _aggregate_over(read["cur"], read["spec"], read["cols"], read["where"], read["params"], read["frm"], aggs, group_by=group_by, limits=read["limits"]) diff --git a/api/routes_sheet.py b/api/routes_sheet.py index 7d8c2f12bff3f329b3affde2cea0ec738ddde054..1c0ccf8a6a1dc98c1fa3564a2a5597d3e8eaedfb 100644 --- a/api/routes_sheet.py +++ b/api/routes_sheet.py @@ -5,6 +5,14 @@ WHAT GOES HERE: Contract C1's routes over `platform/core/sheets.py`: list, create, read, replace, plus the three doors that RESOLVE something and are therefore built by later tickets in this lane. +⭐⭐ **WAVE 51 ADDS C3's THREE DOORS, AND THEY EXIST BECAUSE THE CAPS MOVED (A1).** With the byte +cap at 16 MiB a whole-document PUT can now legitimately be a 16 MB upload PER COMMIT, so C3 splits +reading and writing by TAB: `GET /sheets/{id}?tabs=meta` is the workbook without any cells, +`GET /sheets/{id}/tabs/{tab}` is the one tab a person has open, and +`PATCH /sheets/{id}/tabs/{tab}/cells` saves the range that changed. PUT stays exactly as it was and +is what a STRUCTURE change still uses, so a client that finds the PATCH door missing falls back to +it and says so. + ⭐ **THE WALL HERE IS THE ORDINARY SESSION, AND THAT IS THE WHOLE POINT OF THE SPLIT.** Any signed in user may own a workbook, so a workbook needs no per-database permission. A CELL is different: it names a database, and W49-T04 puts the per-database wall on the doors that read one, per contract @@ -27,7 +35,12 @@ while its surface is a 404. (standing rule 2), and each names both the cause and the subject. """ -from fastapi import APIRouter, Body, Depends, HTTPException +import os +import tempfile +import threading +import uuid + +from fastapi import APIRouter, Body, Depends, File, HTTPException, UploadFile from deps import Session, err, require_session @@ -121,7 +134,16 @@ def _view_filter(session: Session, database: str, view_id: str, view_name: str = # ⚠ `TableStore(table_key, st=...)`, in that order. `st` is the STORE HANDLE, and passing the # session's runtime is what makes the lookup read THIS tenant's bucket rather than tenant #0's. store = table_store.TableStore(database, st=session.runtime) - found = store.find_view(view_id, prefer_owner=session.uname) + # ⭐⭐ `include_trashed=True` IS R11, AND IT IS ONE KEYWORD BECAUSE THE DEFAULT MUST NOT MOVE + # (wave 51, W51-T26). A deleted view is MOVED into `.trash`, so the bare scan answered + # None and this door refused a cell whose view somebody deleted an hour ago and can still + # restore with one click. R11: the cell keeps working for the whole 30 days, and the view's + # filter is copied into the cell's own scope only at PURGE. "Missing" and "trashed" stay + # different answers - an EXPIRED entry is not offered, so this still refuses by name. + # ⛔ THE FLAG IS OPT IN RATHER THAN THE DEFAULT because eight other callers of `find_view` are + # permission-adjacent (shares, starred, publish, forms); widening there would open doors no + # ticket asked about, with every gate green. + found = store.find_view(view_id, prefer_owner=session.uname, include_trashed=True) if not found: raise err(409, "view_missing", f"View {view_name or view_id} no longer exists.") _owner, view = found @@ -129,9 +151,57 @@ def _view_filter(session: Session, database: str, view_id: str, view_name: str = return rot._fe().tree_parts((view or {}).get("filters")) +#: ⛔ THE TWO CAP CODES ANSWER 413, NOT 400 (contract C3). A 400 says the request was malformed and +#: sends a client looking for a typo; these two say the request was perfectly well formed and the +#: DOCUMENT it would produce cannot be stored, which is what 413 means and is the only status a +#: client can branch on to show the server's own sentence inline instead of a generic error. +_CAP_CODES = ("sheet_too_many_cells", "workbook_too_large") + +#: The refusals that mean "that thing is not here", answered 404 so a client can tell a missing +#: workbook from a malformed one without reading the sentence. +_MISSING_CODES = ("workbook_missing", "tab_missing") + +#: ⛔⛔ C5's TWO SHARING REFUSALS ANSWER 403, AND THE TUPLE EXISTS BECAUSE THE FALL-THROUGH BELOW +#: IS 400 (wave 51, W51-T25). Without this branch `workbook_read_only` would arrive as a NAMED 400 +#: carrying a perfectly correct sentence, so nothing on a screen would look wrong and every client +#: branching on the status would read a permission refusal as a malformed request. A 400 says +#: "fix your request"; these two say the request was exactly right and this account may not make +#: it, which is what 403 means and is the only status a client can act on. +#: +#: `workbook_read_only` is a VIEWER at a write door; `workbook_owner_only` is a non-owner at a +#: door C5 reserves for the owner (the two share doors, and DELETE). Two codes rather than one +#: because they send the reader to two different places: one asks for edit access, the other +#: cannot be granted at all. +_FORBIDDEN_CODES = ("workbook_read_only", "workbook_owner_only") + + def _refuse(exc): - """Turn a `SheetRefusal` into the HTTP answer that names it.""" - status = 404 if exc.code == "workbook_missing" else 409 if exc.code.endswith("_stale") else 400 + """Turn a `SheetRefusal` into the HTTP answer that names it. + + ⭐⭐ THE 409's SHAPE IS COPIED, NOT INVENTED. `{"error": {"code", "message", "rev_current"}}` + is byte for byte what `main.py::_view_revision_stale` and `routes_tables.py::delete_table_view` + already ship for `view_revision_stale`, so one class of refusal does not arrive in two shapes + depending on which module the user happened to be in. `deps.err` shapes `{code, message}` and + nothing else, so the 409 and the 413 are raised here directly rather than by bending `err`, + which would change the error shape of every route in the app. + + ⚠ `workbook_revision_stale` (the PUT door's code) ALSO ENDS `_stale` and still lands here. It + carries no `rev_current`, so its body is unchanged and the client's existing PUT branch keeps + working. ⭐ D-639's `index_revision_stale` lands here too and DOES carry one, so the rail's + new guard needed no branch of its own: matching the family's spelling was the whole cost. + """ + if exc.code in _CAP_CODES: + return HTTPException(status_code=413, + detail={"error": {"code": exc.code, "message": exc.message}}) + if exc.code.endswith("_stale"): + body = {"code": exc.code, "message": exc.message} + current = getattr(exc, "rev_current", None) + if current is not None: + body["rev_current"] = int(current) + return HTTPException(status_code=409, detail={"error": body}) + if exc.code in _FORBIDDEN_CODES: + return err(403, exc.code, exc.message) + status = 404 if exc.code in _MISSING_CODES else 400 return err(status, exc.code, exc.message) @@ -139,11 +209,229 @@ def _store(session: Session): return session.runtime +# ── C5: WORKBOOK SHARING (wave 51, W51-T25, rulings R13 + R16) ─────────────────────────────── +# +# ⭐⭐ THE GRANTS LIVE IN `core.shares`, THE ONE REGISTRY FOR EVERY SHAREABLE OBJECT (wave 20, +# owner R10). `kind='workbook'` is a member of its `KINDS` tuple and that is the WHOLE cost of the +# new kind: every predicate in that module treats `kind` as an opaque bucket key, so this file +# gets `grants / set_grants / role_for / may_administer / shared_with / drop_objects` without a +# fourth permission decision in a fourth file. +# +# ⛔⛔ AND IT IS NOT STORED ON THE INDEX ROW, WHICH IS THE OBVIOUS SPELLING AND IS A DEFECT. +# `core.sheets._index_upsert` rebuilds the row from the DOCUMENT on every save, so a `shares` key +# living there would be deleted by the next PATCH of any cell with nothing going red. The join +# happens at READ time (`core.sheets.project_shares`), which makes that failure impossible rather +# than guarded. The full argument is at the join. +# +# ⛔ `workbook` IS DELIBERATELY ABSENT FROM `core.shares.RESHARE_KINDS`. C5 says the share doors +# are the OWNER's, and leaving the kind out of that tuple is what enforces it: `may_administer` +# answers True for an `edit` grantee ONLY on a kind listed there, so an editor of a workbook can +# change cells and cannot change who else reaches it. Adding the kind to that tuple would widen +# this in one line, from another file, with nothing here to notice. + +#: C5's wire words, and the registry's. ⛔ TWO SPELLINGS OF ONE FACT IS HOW ONE OF THEM ENDS UP +#: IGNORED, so the translation is exactly two functions in exactly this file: the registry's +#: `('view', 'edit')` is what is STORED and what `role_for` returns, and C5's `viewer` / `editor` +#: is what crosses the wire. Nothing else in the app may spell either mapping. +_WIRE_ROLE = {"view": "viewer", "edit": "editor"} +_STORE_ROLE = {"viewer": "view", "editor": "edit"} + + +def wire_role(role): + """A stored registry role as C5's wire word, or `""` for anything that is not a role.""" + return _WIRE_ROLE.get(str(role or "").strip().lower(), "") + + +def store_role(role): + """C5's wire word as the registry role to store, or `""` when the client named neither. + + ⚠ `""` RATHER THAN A DEFAULT. A body that says `role: "admin"` has asked for something this + door does not offer, and quietly storing `view` would hand back a 200 for a request that was + refused in substance. The caller turns the empty string into a named refusal. + """ + return _STORE_ROLE.get(str(role or "").strip().lower(), "") + + +def _sheet_refusal(code, subject=""): + """The HTTP answer for one C5 refusal, worded ONCE in `modules/sheet.py::REFUSALS`. + + ⚠ It returns the exception rather than raising it, exactly as `_refuse` does, so a caller + reads `raise _sheet_refusal(...)` and the status still comes from the ONE table that maps a + Sheet code to a status. + """ + from modules import sheet as sheet_mod + return _refuse(sheet_mod.SheetRefusal(code, subject)) + + +def _workbook_owner(book): + """Who OWNS a workbook: the document's `created_by`, folded to the identity a session has. + + ⭐ `created_by` IS `session.uname` AND THE TWO ARE THE SAME STRING. `create_sheet` passes + `created_by=session.uname` and `Session.uname` is `user["username"]`, so "did this account + make this workbook" is decidable from the document alone and needs no second record. That + matters because the grant registry has no owner for a workbook until its first share is + written, and the creator must be able to write that first share. + """ + return str((book or {}).get("created_by") or "").strip().lower() + + +def _role_on_workbook(session: Session, book): + """`'owner' | 'edit' | 'view' | None` for this session on this workbook, fail-closed. + + ⛔ THE DOCUMENT DECIDES OWNERSHIP AND THE REGISTRY DECIDES GRANTS, and the order is that way + round because a workbook that has never been shared has no registry record at all. Asking + `shares.role_for` alone would answer `None` for the person who created it. + """ + from core import shares + if session.admin: + return "owner" + me = str(session.uname or "").strip().lower() + if me and _workbook_owner(book) == me: + return "owner" + return shares.role_for("workbook", book.get("id"), me, st=_store(session)) + + +def _require_editor(session: Session, book): + """Refuse 403 `workbook_read_only` unless this session may CHANGE the workbook. + + ⛔⛔ EVERY WRITE DOOR CALLS THIS BEFORE ITS REVISION COMPARISON, AND THE ORDER IS THE POINT. + A viewer holding a stale `rev` who is checked the other way round is told the document changed + somewhere else, which is true and is not why they were refused: they would refetch, retry, and + be refused again with the same wrong sentence forever. The refusal has to name the reason the + write can never succeed. + """ + if _role_on_workbook(session, book) in ("owner", "edit"): + return + raise _sheet_refusal("workbook_read_only", _workbook_owner(book) or "its owner") + + +def _require_owner(session: Session, book): + """Refuse 403 `workbook_owner_only` unless this session OWNS the workbook (C5).""" + if _role_on_workbook(session, book) == "owner": + return + raise _sheet_refusal("workbook_owner_only", _workbook_owner(book) or "its owner") + + +def _wire_shares(rows): + """Translate each index row's `shares` into C5's role words, in place on a fresh list. + + `core.sheets.project_shares` joins the REGISTRY's words onto the row; this is the boundary + where they become C5's, and it is the only one. + """ + out = [] + for row in rows or (): + row = dict(row) + row["shares"] = [{"who": s.get("who"), "role": wire_role(s.get("role"))} + for s in (row.get("shares") or []) + if wire_role(s.get("role"))] + out.append(row) + return out + + +def _wire_index(index): + """One rail document with C5's role words on every row.""" + out = dict(index or {}) + out["workbooks"] = _wire_shares(out.get("workbooks")) + return out + + +def _reresolved_for_reader(session: Session, book): + """A COPY of `book` whose every bound cell was recomputed under THIS reader's scope (C5). + + ⛔⛔ IN MEMORY, AND IT MUST NEVER PERSIST. `refresh_sheet` runs the same loop and ends with + `put_workbook`, and a read path that copied that body would write the READER's numbers into + the OWNER's document: the same leak as serving stale owner values, in the opposite direction, + caused by a GET, and therefore reachable by anybody the workbook was shared with. So this + works on a `copy.deepcopy` and returns it, and nothing here touches the store. + + ⭐ THE WALL RUNS ONCE PER DISTINCT DATABASE, exactly as `refresh_sheet` does (R16): a reader + who has lost access to a bound database is refused on every cell of it rather than shown the + owner's cached number. + + ⚠ `refreshedFor` IS STAMPED ONLY WHEN A BOUND CELL WAS ACTUALLY RECOMPUTED. A workbook of + literals has nothing to re-resolve, and a stamp there would be a claim with nothing behind it. + """ + import copy as _copy + fresh = _copy.deepcopy(book) + stamp = _now_iso() + seen_db = {} + touched = 0 + for tab in fresh.get("sheets") or (): + for _addr, cell in (tab.get("cells") or {}).items(): + if not isinstance(cell, dict) or cell.get("kind") != "bound": + continue + touched += 1 + binding = cell.get("binding") or {} + db = str(binding.get("database") or "") + if db not in seen_db: + try: + _require_database(session, db) + seen_db[db] = None + except Exception as exc: # noqa: BLE001 + seen_db[db] = exc + failure = seen_db.get(db) + if failure is not None: + cell["state"] = "refused" + cell["value"] = None + cell["refusal"] = {"code": "database_unreadable", + "message": f"You cannot read {db}."} + cell.pop("limits", None) + continue + try: + out = _resolve_binding(session, binding) + except HTTPException as exc: + detail = getattr(exc, "detail", None) or {} + info = detail.get("error") if isinstance(detail, dict) else None + cell["state"] = "refused" + cell["value"] = None + cell["refusal"] = { + "code": (info or {}).get("code", "sheet_unresolved"), + "message": (info or {}).get("message", "This cell could not be refreshed."), + } + continue + cell["state"] = "fresh" + cell["value"] = out["value"] + cell["display"] = "" if out["value"] is None else str(out["value"]) + cell["refreshed_at"] = stamp + cell.pop("refusal", None) + if out["limits"]: + cell["limits"] = out["limits"] + else: + cell.pop("limits", None) + if not touched: + return fresh + # ⭐ EVERY FORMULA IS RE-EVALUATED TOO, over the numbers this reader is entitled to. Leaving + # them alone would serve the owner's totals sitting on top of the reader's inputs, which is + # the leak this whole function exists to close, one layer up. + from modules import sheet as sheet_mod + import formula_runtime as fr + _recompute_formulas(fresh, fr, sheet_mod) + fresh["refreshedFor"] = str(session.uname or "") + return fresh + + +def _read_for(session: Session, book): + """The workbook this session is entitled to see: stored for the owner, re-resolved otherwise. + + ⚠ A STRANGER IS A NON-OWNER AND TAKES THE SAME PATH, deliberately. Nothing in this file + refuses a stranger's READ today (see the module note the measurement is booked under), so the + fail-closed answer to "what should they be shown" is: whatever THEIR OWN scope computes, + never the owner's cached numbers. + """ + if _role_on_workbook(session, book) == "owner": + return book + return _reresolved_for_reader(session, book) + + @router.get("/sheets") def list_sheets(session: Session = Depends(require_session)): - """The workbook list, identity only. Cells never ride this door.""" + """The workbook list, identity only. Cells never ride this door. + + ⚠ C5's `shares` rides here as well as on `/sheets/index`, because the client reads both. + """ from core import sheets - return {"workbooks": sheets.list_workbooks(_store(session))} + rows = sheets.project_shares(_store(session), sheets.list_workbooks(_store(session))) + return {"workbooks": _wire_shares(rows)} @router.post("/sheets", status_code=201) @@ -171,13 +459,34 @@ def create_sheet(body: dict = Body(default=None), session: Session = Depends(req # # ⚠ `Depends(require_session)` ONLY, like every other door in this file, and that is correct: the # Sheet is granted to everyone, and the rail's folders name no database. +# +# ⛔⛔ MEASURED IN W51-T25 AND BOOKED, NOT FIXED: THAT SENTENCE MEANS EVERY SIGNED IN ACCOUNT CAN +# ALREADY READ EVERY WORKBOOK. Nothing in `core.sheets.list_workbooks` or `::read_index` filters by +# owner, and `GET /sheets/{id}` walls on the session alone, so an account holding NO share reads a +# stranger's workbook with **200**. Driven in `verify_sheet.py` section 5c with a third identity. +# ⇒ `sharedWithMe` is therefore a PARTITION of a list everyone can already see, and C5's +# viewer/editor wall guards the WRITE doors rather than closing a read that was never shut. +# Refusing a stranger's read is not in W51-T25's `done-when` and widening it here would change the +# behaviour of a door six other tickets are built on, so it is an amendment finding for the root. +# ⚠ WHAT THIS TICKET DOES GUARANTEE MEANWHILE is the half that leaks data rather than existence: +# a non-owner never receives the owner's stored numbers, because every cell-bearing read +# re-resolves under the caller's own scope first. @router.get("/sheets/index") def read_sheet_index(session: Session = Depends(require_session)): - """`{workbooks, folders, itemFolders, starred}` for the Sheet rail in ONE read.""" + """`{workbooks, folders, itemFolders, starred, rev, sharedWithMe}` for the rail in ONE read. + + ⭐ C5 — EVERY ROW CARRIES `shares` AND THE DOCUMENT CARRIES `sharedWithMe`. Both are computed + from `core.shares` at read time and neither is stored on the index; the join is in + `core.sheets` and the role words are translated here, at the wire boundary. + + ⭐⭐ D-639 — `rev` RIDES OUT AND THE PUT BELOW CHECKS IT. Half of that pair is a guard nothing + can reach: a client cannot send a revision it was never given, and a server that never checks + one is a client stamping a number nobody reads. + """ from core import sheets - return {"index": sheets.read_index(_store(session))} + return {"index": _wire_index(sheets.read_index(_store(session), viewer=session.uname))} @router.put("/sheets/index") @@ -188,24 +497,332 @@ def write_sheet_index(body: dict = Body(default=None), ⭐ `repairs` RIDES BACK OUT. `core.sheets.save_folders` records every change it made to the payload, and the rail says so in a sentence rather than letting a workbook reappear at the top level with no explanation (R16). Dropping this key is what makes a silent repair. + + ⭐⭐ D-639 — `rev` IN THE BODY MAKES THIS WRITE CONDITIONAL, and it is the half of the guard + that lives on the server. Send the `rev` the GET handed you and a concurrent reorganisation + answers 409 `index_revision_stale` carrying `rev_current`, which `_refuse`'s existing + `_stale` branch shapes for free. ⚠ Omitting it is still legal and still means last writer + wins, exactly as it does on the workbook PUT: a client that has never read the rail cannot + send one. """ from core import sheets raw = dict(body or {}) try: out = sheets.save_folders(_store(session), raw.get("folders"), - raw.get("itemFolders"), starred=raw.get("starred")) + raw.get("itemFolders"), starred=raw.get("starred"), + expect_rev=raw.get("rev")) except sheets.SheetRefusal as exc: raise _refuse(exc) - return {"index": out} + return {"index": _wire_index(out)} + + +# ── C4: the .xlsx IMPORT, which is a JOB and not a request (wave 51, W51-T24) ──────────────── +# +# ⭐⭐ THE JOB EXISTS BECAUSE THE WORK OUTLIVES THE REQUEST. Two openpyxl passes over the owner's +# treasury model MEASURED 31 s of parsing and 25 s of recalculation on this box, and the Space is +# slower; a synchronous door would be a browser timeout, a proxy 504, or a person who closed the +# tab and lost an import that had already finished. So the upload starts a thread, answers with a +# job id, and `GET /sheets/import/{job}` reports where it got to. ⛔ NOTHING IN THE JOB READS THE +# CLIENT: it does not stop when the polling stops, which is the whole point. +# +# ⛔ THE TEMP FILE IS DELETED IN A `finally`, INCLUDING ON REFUSAL. An import that refuses is the +# case that leaves a 25 MB file behind, because it is the path nobody walks while testing. +# +# ⚠ DECLARED ABOVE `/sheets/{workbook_id}`, and it is free insurance rather than a fix: FastAPI +# matches in declaration order, and `/sheets/index` further up is a literal that a `{param}` route +# on the SAME depth would eat. These two cannot collide (POST at depth 3 against a GET-only param +# route, and GET at depth 4 against a depth-3 param route), but the file's discipline is that a +# literal is declared first and this one is not going to be the exception nobody re-checks. + +#: Every import this process has run, newest last. ⚠ IT IS PROCESS MEMORY, NOT THE STORE, and +#: that is correct for a progress reading: it is worthless after a restart and a restart has +#: already killed the thread it describes. The WORKBOOK is in the store; only the progress is here. +_IMPORT_JOBS = {} +_IMPORT_LOCK = threading.Lock() + +#: How many finished jobs are kept before the oldest is dropped. A job holds its report, which +#: holds up to `MAX_MISMATCHED` addresses, so an unbounded registry is an unbounded leak in a +#: process that never restarts. +_MAX_IMPORT_JOBS = 24 + + +def _job_set(job_id, **fields): + """Update one job under the registry lock. Called from the worker thread.""" + with _IMPORT_LOCK: + job = _IMPORT_JOBS.get(job_id) + if job is not None: + job.update(fields) + + +def _job_view(job): + """C4's wire shape for one job. Only the keys C4 names, and only when they hold something.""" + out = {"state": job.get("state") or "reading", + "progress": round(float(job.get("progress") or 0.0), 3)} + for key in ("workbook_id", "report", "sentence"): + if job.get(key) is not None: + out[key] = job[key] + return out + + +def _reap_jobs(): + """Drop the oldest FINISHED jobs past the cap. A running job is never reaped.""" + with _IMPORT_LOCK: + done = [k for k, v in _IMPORT_JOBS.items() if v.get("state") in ("done", "refused")] + while len(_IMPORT_JOBS) > _MAX_IMPORT_JOBS and done: + _IMPORT_JOBS.pop(done.pop(0), None) + + +def _import_refused(job_id, code, message): + _job_set(job_id, state="refused", progress=1.0, code=code, sentence=message) + + +def _run_import(job_id, path, filename, runtime, uname): + """The whole import, on its own thread: read, map, recalculate, compare, save. + + ⛔⛔ THE REPORT SURVIVES A REFUSAL, and that is the difference between a refusal a person can + act on and one they cannot. If the document does not fit `MAX_WORKBOOK_BYTES` the save raises, + and answering with a bare sentence would leave the reader knowing only that something was too + big; the report already knows how many cells and formulas were in their file and what did not + survive, so it is written into the job BEFORE the save is attempted. + """ + from core import sheet_import, sheets + from modules import sheet as sheet_mod + import formula_runtime as fr + + made = None + try: + out = sheet_import.import_workbook( + path, source=filename, + progress=lambda state, fraction: _job_set(job_id, state=state, progress=fraction)) + book, report = out["workbook"], out["report"] + + #: ⛔ PULLED OFF BEFORE THE RECALC OVERWRITES `value`. `_recompute_formulas` replaces every + #: formula cell's value with OUR answer, so a differential run after it with the cached + #: readings still on the cells would be comparing our answer against itself. + cached = sheet_import.take_imported_values(book) + _job_set(job_id, state="recalc", progress=0.96, report=report) + _recompute_formulas(book, fr, sheet_mod) + diff = sheet_import.differential(book, cached) + report["matched"] = diff["matched"] + report["mismatched"] = diff["mismatched"] + report["compared"] = diff["compared"] + _job_set(job_id, report=report) + + stamp = _now_iso() + made = sheets.create_workbook(runtime, name=book.get("name") or "", created_by=uname) + saved = sheets.put_workbook(runtime, made["id"], + {"name": book.get("name"), "sheets": book.get("sheets"), + "refreshed_at": stamp, "rev": made["rev"]}) + _job_set(job_id, state="done", progress=1.0, workbook_id=saved["id"], + sentence=_import_sentence(report)) + except sheet_import.ImportRefusal as exc: + _import_refused(job_id, exc.code, exc.message) + except sheets.SheetRefusal as exc: + # ⛔ THE HALF MADE WORKBOOK GOES WITH THE REFUSAL. `create_workbook` has already written an + # empty document and an index row; leaving them would file an untitled empty workbook into + # the rail for every import that was too large to store. + if made is not None: + try: + sheets.delete_workbook(runtime, made["id"]) + except Exception: # noqa: BLE001 + pass + _import_refused(job_id, exc.code, exc.message) + except Exception as exc: # noqa: BLE001 + _import_refused(job_id, "import_failed", + "That workbook could not be imported: " + str(exc)[:200]) + finally: + try: + os.remove(path) + except OSError: + pass + _reap_jobs() + + +def _import_sentence(report): + """What a finished import SAYS, in digits (R16). No em dash and no en dash.""" + compared = int(report.get("compared") or 0) + matched = int(report.get("matched") or 0) + line = ("Imported " + str(int(report.get("cells") or 0)) + " cells and " + + str(int(report.get("formulas") or 0)) + " formulas.") + if compared: + line += (" " + str(matched) + " of " + str(compared) + + " recalculated cells match the answers the file had stored.") + if report.get("unsupported"): + line += (" " + str(len(report["unsupported"])) + + " kinds of thing in that file could not be carried over.") + return line + + +@router.post("/sheets/import", status_code=202) +async def start_sheet_import(file: UploadFile = File(...), + session: Session = Depends(require_session)): + """Take an .xlsx upload and START a job (contract C4). Answers `{job, state, progress}`. + + ⚠ THE TWO REFUSALS HERE ARE SYNCHRONOUS ON PURPOSE. A wrong file type and a file over the cap + are both knowable before any work starts, so answering them as a job the caller has to poll + would make the client wait to be told something the server already knew. + """ + from core import sheet_import + + name = str(file.filename or "").strip() + if not name.lower().endswith(".xlsx"): + raise err(400, "import_not_xlsx", + "Only an .xlsx workbook can be imported. Save your file as .xlsx and try again.") + data = await file.read() + if len(data) > sheet_import.MAX_IMPORT_BYTES: + raise HTTPException(status_code=413, detail={"error": { + "code": "import_too_large", + "message": ("That file is " + _mb(len(data)) + " and an import takes at most " + + _mb(sheet_import.MAX_IMPORT_BYTES) + + ", so it cannot be read. Split it into two workbooks and try again.")}}) + if not data: + raise err(400, "import_empty", "That file holds nothing to import.") + + handle, path = tempfile.mkstemp(prefix="sheet-import-", suffix=".xlsx") + with os.fdopen(handle, "wb") as fh: + fh.write(data) + + job_id = uuid.uuid4().hex[:16] + with _IMPORT_LOCK: + _IMPORT_JOBS[job_id] = {"state": "reading", "progress": 0.0, "owner": session.uname, + "started": _now_iso()} + thread = threading.Thread(target=_run_import, name="sheet-import-" + job_id, + args=(job_id, path, name, _store(session), session.uname), + daemon=True) + thread.start() + return {"job": job_id, "state": "reading", "progress": 0.0} + + +@router.get("/sheets/import/{job}") +def read_sheet_import(job: str, session: Session = Depends(require_session)): + """Where one import got to (contract C4). + + ⚠ A JOB THAT IS NOT THIS CALLER'S ANSWERS 404, not 403. A 403 would confirm that somebody + else's import exists, which is a fact this door has no business handing out; a job id is a + random hex string and "not here" is the honest answer for one the caller does not own. + """ + with _IMPORT_LOCK: + found = _IMPORT_JOBS.get(str(job or "").strip()) + snapshot = dict(found) if found else None + if not snapshot or snapshot.get("owner") != session.uname: + raise err(404, "import_job_missing", "That import is no longer being tracked.") + return _job_view(snapshot) + + +def _mb(byte_count): + """A byte count as MB with one decimal, the way `core.sheets._mb` says it (R16).""" + return "%.1f MB" % (float(byte_count) / (1024.0 * 1024.0)) @router.get("/sheets/{workbook_id}") -def read_sheet(workbook_id: str, session: Session = Depends(require_session)): +def read_sheet(workbook_id: str, tabs: str = "", + session: Session = Depends(require_session)): + """The whole workbook, or `?tabs=meta` for the workbook WITHOUT any cells (contract C3). + + ⭐ `?tabs=meta` IS HOW A CLIENT OPENS ONE TAB AT A TIME (R4). A1 raised the byte cap to 16 MiB, + so the plain read below can now legitimately hand back 16 MB on a workbook with ten tabs the + reader is not looking at. The meta read carries every tab's identity, geometry and strata and + none of its cells, and `GET /sheets/{id}/tabs/{tab}` fetches the one tab that is open. + + ⚠ ANY OTHER VALUE OF `tabs` READS AS THE FULL WORKBOOK, on purpose. A client that sends an + unknown value has asked for something this door does not know how to trim, and answering with + everything is the honest superset; refusing would 400 a READ over a query string. + + ⭐⭐ C5 — A NON-OWNER'S READ IS RE-RESOLVED UNDER THEIR OWN SCOPE, and `?tabs=meta` is the one + shape that skips it because it carries no cells at all. A shared workbook's stored numbers are + the OWNER's: they were computed under the owner's row scope, so handing them to a reader whom + an administrator has restricted on that database shows them exactly the rows they were walled + off from, with a 200 and nothing red. + """ + from core import sheets + try: + book = sheets.get_workbook(_store(session), workbook_id) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + if str(tabs or "").strip().lower() == "meta": + return {"workbook": sheets.workbook_meta(book)} + return {"workbook": _read_for(session, book)} + + +# ⛔ THE ORDER WAS CHECKED, BECAUSE FASTAPI MATCHES IN DECLARATION ORDER. `/sheets/index`'s hazard +# (a literal eaten by a `{param}` route on the same prefix) cannot reach these two: both carry a +# LITERAL `tabs` segment at depth four, and no route in this file declares a parameter at that +# depth. A mount census cannot prove that either way, so `verify_sheet.py` section 2 DRIVES both +# doors and reads the answer, which is the only check that can tell a declared route from a +# reachable one. + + +@router.get("/sheets/{workbook_id}/tabs/{tab}") +def read_sheet_tab(workbook_id: str, tab: str, + session: Session = Depends(require_session)): + """ONE tab and its cells (contract C3). `{tab}` is the tab's `id`, or its name. + + ⚠ THE ANSWER CARRIES `rev`, and it has to: the PATCH door below is rev guarded, so a client + that fetched a tab without the revision it belongs to would have to guess one or re-read the + whole workbook to save a single cell. + + ⛔⛔ C5's RE-RESOLVE IS WIRED HERE TOO, AND THIS IS THE DOOR IT WOULD HAVE BEEN MISSED ON. + There are THREE read shapes, not one: the full workbook, `?tabs=meta` (no cells, nothing to + re-resolve) and this one. Wiring the reader's scope into the full read alone would still hand + a reader the owner's cached numbers through `GET /sheets/{id}/tabs/{tab}` — the door the + client actually uses once a workbook is open, so the leak would be the NORMAL path rather + than the rare one. ⚠ `refreshedFor` is stamped on the ENVELOPE here rather than on the tab, + because the tab is `found` verbatim and a key added inside it would be a cell-shaped thing + that is not a cell. + """ from core import sheets try: - return {"workbook": sheets.get_workbook(_store(session), workbook_id)} + book = sheets.get_workbook(_store(session), workbook_id) + served = _read_for(session, book) + found = sheets.find_tab(served, tab) except sheets.SheetRefusal as exc: raise _refuse(exc) + out = {"id": book.get("id"), "rev": book.get("rev"), "tab": found} + if served.get("refreshedFor"): + out["refreshedFor"] = served["refreshedFor"] + return out + + +@router.patch("/sheets/{workbook_id}/tabs/{tab}/cells") +def patch_sheet_cells(workbook_id: str, tab: str, body: dict = Body(default=None), + session: Session = Depends(require_session)): + """Merge a RANGE of cells into one tab: body `{cells: {A1: Cell | null}, rev}` (contract C3). + + ⭐ `{"A1": null}` DELETES A1 and leaves its neighbours alone. After C2 an empty cell can carry + a style (`kind: "empty"`), so a client needs a way to say "nothing at all lives here" that is + distinguishable from "this is painted yellow and holds nothing". + + ⭐ ONE BAD CELL DOES NOT THROW THE COMMIT AWAY. The answer is `{rev, tab, cells, refused}`, + where `refused` is a per address list of `{addr, code, sentence}` and every other cell in the + same patch has landed. A CAP breach is the opposite: it is a whole request 413, because the + document as a whole cannot be stored and there is no partial version of that. + + ⚠ `rev` IN THE BODY MAKES THE WRITE CONDITIONAL, exactly as it does on the PUT door. Omit it + and the last writer wins; send the `rev` the tab read and a concurrent change answers 409 + `sheet_revision_stale` carrying `rev_current`, which is the revision to refetch. + + ⛔⛔ C5's READ-ONLY CHECK RUNS BEFORE THAT COMPARISON AND THE ORDER IS THE CONTRACT. A viewer + is refused 403 `workbook_read_only`; a viewer holding a stale rev is ALSO refused + `workbook_read_only`, not 409, because 409 names a problem they could fix by refetching and + this one they cannot fix at all. An editor's write falls straight through to the rev guard, + which is exactly what C5 asks for. + """ + from core import sheets + raw = dict(body or {}) + try: + _require_editor(session, sheets.get_workbook(_store(session), workbook_id)) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + #: ⚠ `rev` ABSENT and `rev: null` are the same request and both opt out. A client that has + #: never read the document cannot send one, and refusing would make the first save of an + #: imported workbook impossible. + expect = raw.get("rev") + try: + out = sheets.patch_cells(_store(session), workbook_id, tab, raw.get("cells"), + expect_rev=expect) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + return out @router.put("/sheets/{workbook_id}") @@ -216,9 +833,15 @@ def write_sheet(workbook_id: str, body: dict = Body(default=None), ⚠ `rev` in the body makes the write CONDITIONAL. Omit it and the last writer wins; send the `rev` you read and a concurrent change answers `workbook_revision_stale` instead of being silently overwritten. + + ⛔ C5: THE READ-ONLY CHECK RUNS FIRST, for the reason spelled out on the PATCH door. """ from core import sheets raw = dict(body or {}) + try: + _require_editor(session, sheets.get_workbook(_store(session), workbook_id)) + except sheets.SheetRefusal as exc: + raise _refuse(exc) try: # `rev` inside the body IS the expectation; `core.sheets.put_workbook` reads it. This door # does not translate it into a second argument, because two ways to say the same thing is @@ -231,14 +854,113 @@ def write_sheet(workbook_id: str, body: dict = Body(default=None), @router.delete("/sheets/{workbook_id}") def drop_sheet(workbook_id: str, session: Session = Depends(require_session)): + """Delete a workbook. THE OWNER's door, and an editor is refused by name (C5). + + ⛔ AN `edit` GRANT IS PERMISSION TO CHANGE THE CONTENT, NOT TO DESTROY THE OBJECT, and the + fail-closed reading is the one that ships: an editor who deletes the owner's workbook has + taken it from everybody it was shared with, and nothing in this system can put it back. The + refusal is `workbook_owner_only` rather than `workbook_read_only` because the sentences send + the reader to two different places, and telling an editor their workbook is read only would be + flatly false. + """ from core import sheets try: + _require_owner(session, sheets.get_workbook(_store(session), workbook_id)) removed = sheets.delete_workbook(_store(session), workbook_id) except sheets.SheetRefusal as exc: raise _refuse(exc) return {"deleted": bool(removed)} +# ── C5's two share doors, and they are the OWNER's ─────────────────────────────────────────── +# +# ⚠ DECLARED BELOW `/sheets/{workbook_id}` AND THAT IS SAFE: both carry a LITERAL `shares` +# segment at depth four or five, and this file declares no parameter at either depth on that +# prefix, so no `{param}` route can eat them. The two doors that DID need declaration order +# (`/sheets/index`, `/sheets/import`) are literals at depth THREE and are still first. + + +@router.post("/sheets/{workbook_id}/shares") +def share_sheet(workbook_id: str, body: dict = Body(default=None), + session: Session = Depends(require_session)): + """Grant one person `viewer` or `editor` on this workbook (C5, R16). Owner only. + + ⭐ THE GRANT GOES INTO `core.shares`, THE ONE REGISTRY, and the answer hands back the WHOLE + list rather than the row just written: the registry replaces a grant set wholesale, so the + honest answer to "what did that do" is what the list is now. + + ⚠ `expect` IS THE COMPARE-AND-SET `core.shares.set_grants` already offers, and it is passed + the list this request decided against. Two people with the sharing panel open would otherwise + silently overwrite each other, which that module measured in wave 40 and answers `409`. + """ + from core import sheets, shares + raw = dict(body or {}) + try: + book = sheets.get_workbook(_store(session), workbook_id) + _require_owner(session, book) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + + who = str(raw.get("who") or "").strip().lower() + role = store_role(raw.get("role")) + if not who: + raise err(400, "share_who_required", "Name the person to share this workbook with.") + if who == _workbook_owner(book): + raise err(400, "share_owner_redundant", + "That person already owns this workbook, so there is nothing to share.") + if not role: + raise err(400, "share_role_unknown", + "A workbook is shared as viewer or as editor, and %r is neither." + % (str(raw.get("role") or ""),)) + + held = shares.grants("workbook", book["id"], st=_store(session)) + prior = list(held.get("entries") or []) + entries = [dict(e) for e in prior if e.get("user") != who] + [{"user": who, "role": role}] + try: + rec = shares.set_grants("workbook", book["id"], entries, + owner=(None if held.get("owner") else _workbook_owner(book)), + granter=session.uname, st=_store(session), expect=prior) + except shares.GrantsChanged as exc: + # ⚠ `grants_changed`, THE SAME CODE `routes_shares.py` ALREADY ANSWERS, and a plain 409 + # rather than the `_stale` shape: there is no revision to hand back here, and a + # `rev_current: 0` would be a number the client could only misuse. + raise err(409, "grants_changed", str(exc)) + return {"shares": [{"who": e["user"], "role": wire_role(e["role"])} + for e in (rec.get("entries") or [])]} + + +@router.delete("/sheets/{workbook_id}/shares/{who}") +def unshare_sheet(workbook_id: str, who: str, session: Session = Depends(require_session)): + """Revoke one person's access to this workbook (C5). Owner only. + + ⚠ REVOKING SOMEBODY WHO WAS NEVER THERE IS A 200 WITH THE LIST UNCHANGED. The caller's + intention ("this person must not have access") is satisfied either way, and a 404 here would + make a double click on Remove look like a failure. + """ + from core import sheets, shares + try: + book = sheets.get_workbook(_store(session), workbook_id) + _require_owner(session, book) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + + target = str(who or "").strip().lower() + held = shares.grants("workbook", book["id"], st=_store(session)) + prior = list(held.get("entries") or []) + entries = [dict(e) for e in prior if e.get("user") != target] + try: + rec = shares.set_grants("workbook", book["id"], entries, + owner=(None if held.get("owner") else _workbook_owner(book)), + granter=session.uname, st=_store(session), expect=prior) + except shares.GrantsChanged as exc: + # ⚠ `grants_changed`, THE SAME CODE `routes_shares.py` ALREADY ANSWERS, and a plain 409 + # rather than the `_stale` shape: there is no revision to hand back here, and a + # `rev_current: 0` would be a number the client could only misuse. + raise err(409, "grants_changed", str(exc)) + return {"shares": [{"who": e["user"], "role": wire_role(e["role"])} + for e in (rec.get("entries") or [])]} + + # ── the doors that RESOLVE, and are therefore later tickets ────────────────────────────────── # # ⭐ Each is declared here so the surface exists and `main.py` needs no second edit, and each @@ -256,6 +978,14 @@ def refresh_sheet(workbook_id: str, session: Session = Depends(require_session)) ⚠ Each distinct `view_id` is resolved ONCE. `table_store.find_view` runs a legacy migration on every call, so resolving per cell would make a forty-cell refresh do forty migrations. + + ⛔⛔ C5 — THIS IS A WRITE DOOR, BECAUSE IT ENDS IN `put_workbook`, AND A VIEWER IS REFUSED + HERE FOR A REASON THAT IS NOT ABOUT PERMISSION TO SEE. A viewer whose refresh were allowed + would compute every bound cell under THEIR scope and then SAVE those numbers into the owner's + document, so a narrowly walled reader pressing Refresh would silently shrink the owner's + workbook. The reader's own re-resolve happens on the READ path, in memory, and never lands. + ⚠ An EDITOR still writes their own numbers here, which is what an edit grant means and is + booked as a residual rather than widened away. """ from core import sheets from modules import sheet as sheet_mod @@ -263,6 +993,7 @@ def refresh_sheet(workbook_id: str, session: Session = Depends(require_session)) try: book = sheets.get_workbook(_store(session), workbook_id) + _require_editor(session, book) except sheets.SheetRefusal as exc: raise _refuse(exc) @@ -309,14 +1040,26 @@ def refresh_sheet(workbook_id: str, session: Session = Depends(require_session)) else: cell.pop("limits", None) + # ⭐⭐ R4 / A1: THE RECALC IS TIMED AND THE TIME IS SHOWN. The prototype measured 2.9 s as the + # FLOOR for the owner's 11,300 formulas (2.9 to 6.2 s observed), so a refresh is a wait a + # person notices, and a wait nobody explains reads as a hang. `recalc_ms` is what the client + # renders as "Recalculated in N.N s". + # + # ⚠ IT TIMES THE RECALC, NOT THE ROUTE. The bound-cell loop above is database work whose + # duration says nothing about the formula engine, and the save below is store work; folding + # either into this number would make the figure on the screen unable to answer the question it + # exists for, which is whether the ENGINE is inside A1's 5 s target. + from time import perf_counter + started = perf_counter() _recompute_formulas(book, fr, sheet_mod) + recalc_ms = round((perf_counter() - started) * 1000.0, 1) try: saved = sheets.put_workbook(_store(session), workbook_id, {"name": book.get("name"), "sheets": book.get("sheets"), "refreshed_at": stamp, "rev": book.get("rev")}) except sheets.SheetRefusal as exc: raise _refuse(exc) - return {"workbook": saved} + return {"workbook": saved, "recalc_ms": recalc_ms} def _now_iso(): @@ -324,44 +1067,85 @@ def _now_iso(): return datetime.now(timezone.utc).replace(microsecond=0).isoformat() +#: ⛔ THE NAME A TAB GETS WHEN IT CANNOT KEEP ITS OWN, and it is built to be UNTYPEABLE on two +#: independent counts: it carries a NUL, and it is longer than the 64 characters `_A1_RE` allows a +#: sheet name on either spelling. See `_tab_scope_names` for when one is handed out. +_UNADDRESSABLE_TAB = "\x00 a tab that cannot be named inside a formula, which is the point \x00" + + +def _tab_scope_names(tabs): + """The name each tab is ADDRESSED BY during one workbook pass, one per tab, all distinct. + + ⛔⛔ TWO TABS SHARING A NAME WOULD MERGE THEIR CELLS INTO ONE KEY SPACE, and that hazard is + created BY the workbook pass: keying per tab, as this function's caller used to, made a + collision impossible. `core.sheets._clean_sheet` names a blank tab `Sheet` but never checks + that two tabs differ, so a workbook holding two tabs called `Data` is an ordinary saved + document. The second one keeps its cells, keeps its own local references and simply cannot be + reached by name from another tab, which is the honest reading of an ambiguous name: `Data!B12` + means the first `Data`, and nothing silently overwrites anything. + """ + names, seen = [], set() + for index, tab in enumerate(tabs): + name = str(tab.get("name") or "") + folded = name.upper() + if not folded or folded in seen: + name = _UNADDRESSABLE_TAB + str(index) + folded = name.upper() + seen.add(folded) + names.append(name) + return names + + def _recompute_formulas(book, fr, sheet_mod): - """Re-evaluate every formula cell across the workbook, per tab, in dependency order. + """Re-evaluate every formula cell across the WORKBOOK, in one memoized dependency pass. + + ⭐⭐ ONE PASS OVER EVERY TAB, NOT ONE PASS PER TAB (W51-T23). Per tab, `DATA!B12` was never in + the inputs, so all 785 cross-sheet cells in the wave-51 prototype resolved BLANK with no error. + Here every cell in the book is keyed `TAB!ADDR` in a single spec, and each formula carries the + tab it lives on so its own unqualified references default to that tab rather than to the first + one. Both halves are needed: keys alone break local references, and defaults alone leave + cross-tab keys unreachable. ⛔ A REFUSED INPUT PROPAGATES; IT DOES NOT BECOME ZERO (C2, and W49-T09 hardens it further). A cell whose value is None because the database refused is handed to the engine as absent, so arithmetic over it stays None rather than silently counting it as nothing. """ - for tab in book.get("sheets") or (): - cells = tab.get("cells") or {} - spec = {} - for addr, cell in cells.items(): + tabs = [t for t in (book.get("sheets") or ()) if isinstance(t, dict)] + names = _tab_scope_names(tabs) + spec = {} + for tab, name in zip(tabs, names): + for addr, cell in (tab.get("cells") or {}).items(): if not isinstance(cell, dict): continue + key = fr.a1_key(addr, name) if cell.get("kind") == "formula" and cell.get("formula"): - spec[addr] = {"formula": cell["formula"]} + spec[key] = {"formula": cell["formula"], "sheet": name} elif cell.get("state") == "refused": # ⛔⛔ CARRIED AS A REFUSAL, NOT DROPPED (W49-T09, C2). Leaving a refused cell OUT # of the inputs is the defect, not the safe option: MEASURED, `=SUM(B4:B8)` with B4 # merely absent answers **3.0 with no error**, while the same range with B4 REFUSED # answers None and names the cause. Dropping it turns a refusal into a smaller # total that looks entirely reasonable. - spec[addr] = {"refused": (cell.get("refusal") or {}).get("code") or "refused"} + spec[key] = {"refused": (cell.get("refusal") or {}).get("code") or "refused"} else: - spec[addr] = {"value": cell.get("value")} - if not any("formula" in v for v in spec.values()): - continue - out = fr.evaluate_sheet(spec) - for addr, cell in cells.items(): + spec[key] = {"value": cell.get("value")} + if not any("formula" in v for v in spec.values()): + return + out = fr.evaluate_sheet(spec, sheets=names) + errors = out.get("errors") or {} + computed = out.get("values") or {} + for tab, name in zip(tabs, names): + for addr, cell in (tab.get("cells") or {}).items(): if not isinstance(cell, dict) or cell.get("kind") != "formula": continue - code = (out.get("errors") or {}).get(addr) + code = errors.get(fr.a1_key(addr, name)) if code: cell["state"] = "refused" cell["value"] = None cell["refusal"] = {"code": code, "message": _formula_message(code)} else: cell["state"] = "fresh" - cell["value"] = (out.get("values") or {}).get(addr) + cell["value"] = computed.get(fr.a1_key(addr, name)) cell["display"] = "" if cell["value"] is None else str(cell["value"]) cell.pop("refusal", None) @@ -382,6 +1166,10 @@ def _formula_message(code, subject=""): "circular_reference": "This formula refers back to itself, so it has no value.", "bad_formula": "This formula could not be read.", "unknown_ref": "This formula points at a cell that is not filled in.", + # ⭐ W51-T23. A MISSING TAB IS NOT A MISSING CELL, and the two sentences send the reader to + # two different places: `unknown_ref` says fill the cell in, this one says the tab it names + # is not in this workbook, which is usually a renamed or deleted tab rather than a typo. + "unknown_sheet": "This formula points at a tab that is not in this workbook.", "div_zero": "This formula divides by zero.", # ── W50-T16's two diagnostic codes (lane B), worded by lane B, added by W50-T20 ──────── # @@ -456,6 +1244,23 @@ def _resolve_binding(session: Session, raw_binding, *, today=None): wall_nodes=wall_nodes, wall_conj=wall_conj, today=today) except sheet_mod.SheetRefusal as exc: raise err(400, exc.code, exc.message) + except ValueError: + # ⛔⛔ A CONDITION THIS COMPILER REFUSES IS A NAMED 409, NOT A 500 (W51-T26). `filter_sql` + # RAISES rather than dropping a leaf it cannot push down - deliberately, because a dropped + # condition widens the answer while the number beside it still looks authoritative. It was + # arriving here as an unhandled exception, so the honest refusal became a blank error. + # ⚠ THE LIVE CASE IS A COHORT LEAF, and W51-T26 is what makes one reachable: a purged + # LOCKED view adopts its member set as `{colId: "__cohort__"}`, and this resolver passes + # neither `cohort_sets` nor `id_sql`, so `_compile_cohort` refuses. Reported as a finding + # with its own exit rather than papered over; the same branch also names a rank op and a + # relative date with no anchor, both of which reached this door as a 500 before. + # ⚠ THE EXCEPTION TEXT IS NOT ECHOED. `filter_sql`'s own message carries an em dash, and + # standing rule 2 governs any string returned to the client, so the sentence is written + # here rather than forwarded. + raise err(409, "scope_not_applicable", + "this cell's scope uses a condition that cannot be applied to this database's " + "live connection, so the number is not being shown rather than shown wider " + "than you asked for. Edit the cell's scope and try again.") row = cur.execute(sql, params).fetchone() value = row[0] if row else None diff --git a/api/routes_tables.py b/api/routes_tables.py index cfcd786c8d6043436acc8256063dc80b48ce828a..64f462cb2d4e744bc680605e566c0436d4327d09 100644 --- a/api/routes_tables.py +++ b/api/routes_tables.py @@ -3394,6 +3394,101 @@ def restore_table_view(table_key: str, view_id: str, request: Request, return {"restored": vid, "owner": owner, "name": landed.get("name")} +# ── RULING R11 (W51-T26): "DELETE FOREVER", AND THE COUNT THE CONFIRM SENTENCE NEEDS ─────────── +# ⭐⭐ R11, verbatim: *"A view-scoped cell keeps pointing at a TRASHED view for the 30 days (it +# still resolves); its filter is copied into the cell's own scope AT PURGE (30-day purge or +# 'Delete forever')."* The 30-day half already had a door (`trash` above, which purges on read). +# The deliberate half had NONE - there was no way to destroy one trashed view - so R11's second +# purge path is unbuildable without these two. +# +# ⛔⛔ THE PREVIEW IS A SEPARATE, READ-ONLY FUNCTION AND THAT IS NOT DECORATOR TASTE. One handler +# serving GET and DELETE would have to branch on `request.method` to decide whether to run +# `_managed_or_refuse(..., mutation=True)` - a permission decision keyed off a method string, +# inside the one door that destroys something. Two thin functions, two walls, one shared scan. +# +# ⛔ AND THE COUNT COMES FROM THE SERVER. "N Sheet cells will keep this view's filter" is the only +# fact the person deciding has, and a client cannot see a colleague's workbooks: a client-side or +# hardcoded N passes every visual check and lies. It is the SAME `iter_workbooks` scan the +# adoption itself walks (`core/sheets.py::count_view_bindings`), so the sentence and the act +# cannot disagree. +def _trash_owner_or_refuse(session, table_key, view_id, *, mutation): + """`(ops, vid, owner, entry)` for a trashed view this caller may act on, or a refusal.""" + from core import table_store as ts + + _managed_or_refuse(session, table_key, mutation=mutation) + vid = str(view_id or "").strip() + if not vid: + raise err(400, "view_required", "choose a view") + ops = _ops(session, table_key) + # ⛔ AN UNREADABLE DOCUMENT IS A 503, NOT A 404 - the same rule the restore door states above. + try: + found = ops.find_trashed(vid, prefer_owner=session.uname) + except Exception as exc: # noqa: BLE001 + raise err(503, "view_trash_unreadable", + "the deleted views could not be read just now. Try again in a moment.") from exc + if not found: + raise err(404, "view_not_in_trash", + "that view is not in the trash. Deleted views are kept for " + f"{ts.TRASH_RETENTION_DAYS} days.") + owner, entry = found + if owner != session.uname and not session.admin: + raise err(403, "view_not_yours", "only the owner can delete this saved view for good") + return ops, vid, owner, entry + + +@router.get("/tables/{table_key}/views/{view_id}/purge") +def preview_view_purge(table_key: str, view_id: str, + session: Session = Depends(require_session)): + """How many Sheet cells would keep this view's filter if it were destroyed now. A pure read.""" + from core import sheets + + _ops_unused, vid, _owner, entry = _trash_owner_or_refuse( + session, table_key, view_id, mutation=False) + view = entry.get("view") if isinstance(entry.get("view"), dict) else {} + try: + cells = sheets.count_view_bindings(session.runtime, vid) + except Exception: # noqa: BLE001 + # ⚠ A COUNT THAT COULD NOT BE TAKEN IS `null`, NEVER 0. Zero is a claim ("nothing depends + # on this"), and making it on an unreadable index would talk somebody into a delete. + cells = None + return {"viewId": vid, "name": str(view.get("name") or vid), "cells": cells} + + +@router.delete("/tables/{table_key}/views/{view_id}/purge") +def purge_table_view(table_key: str, view_id: str, + rev: int = Query(default=None), + session: Session = Depends(require_session)): + """Destroy one trashed view now, after every cell scoped to it has taken its filter.""" + from core import view_audit + + ops, vid, owner, _entry = _trash_owner_or_refuse( + session, table_key, view_id, mutation=True) + try: + sent = None if rev is None else int(rev) + except (TypeError, ValueError): + raise err(400, "bad_revision", "the view revision must be a whole number") + from core import table_store as ts + try: + name, adopted = ops.purge_view(owner, vid, rev=sent) + except ts.ViewNotInTrash as missing: + raise err(404, "view_not_in_trash", str(missing)) + except view_audit.ViewRevisionStale as stale: + raise HTTPException(status_code=409, detail={"error": { + "code": "view_revision_stale", + "message": "someone else changed this view list while you had it open. " + "Reload and try again.", + "rev_current": stale.rev_current}}) + except view_audit.RevisionUnverifiable as unknown: + raise err(503, "view_revision_unverifiable", str(unknown)) + except Exception as exc: # noqa: BLE001 + # ⛔ THE ADOPTION FAILED, SO NOTHING WAS DESTROYED. `purge_view` copies the filter before + # it touches the bucket, so this refusal leaves the view exactly where it was. + raise err(503, "view_purge_failed", + "that view could not be deleted just now, so nothing was changed. " + "Try again in a moment.") from exc + return {"purged": vid, "owner": owner, "name": name, "adopted": adopted} + + # ── CONTRACT C1 (W36-T20): THE MIRROR READER ────────────────────────────────────────────────── # ⭐⭐ R6. `core.perm_scope.scoped_table` is the ONE door to any database's rows and it answers for # a MATERIALISED `ut_*` table entirely on its own — deliberately, so a cold process (E's sandbox diff --git a/platform/aios_grid.py b/platform/aios_grid.py index 2e5c6a79f37b6586d64145f1a54feb59d2de1fe2..3bcfbc449bd9d93b18e97fc6d2051613a8f62fc4 100644 --- a/platform/aios_grid.py +++ b/platform/aios_grid.py @@ -1940,7 +1940,18 @@ FILTER_OPS = {'contains', 'doesNotContain', 'eq', 'neq', 'isEmpty', 'isNotEmpty' # 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'} + '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. @@ -1988,6 +1999,37 @@ def parse_cohort_ids(value): 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 @@ -3322,6 +3364,18 @@ def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None, # 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] diff --git a/platform/core/grid_events.py b/platform/core/grid_events.py index 18e268c93e26717c76c58190e932f4e2e98f5180..ed7311b29a7b9025555213d08fd29642957741df 100644 --- a/platform/core/grid_events.py +++ b/platform/core/grid_events.py @@ -257,6 +257,48 @@ def _ag_overview_id(): EVENT_ORIGIN = {'client': 'grid-events', 'ip': None} +def _event_rev(event): + """THE STORE REVISION THIS BROWSER DECLARED IT WAS LOOKING AT, or None if it declared none. + + ⭐⭐ W51-T33 — THE ONE LINK THAT WAS MISSING, AND IT IS THE WHOLE TICKET. + `CustomerGrid.tsx::stampViewWrite` has put `rev` on every view write since W50-T28, + `table_store._audited_update` has enforced it on both backends since W50-T25, and + `main.py::_view_revision_stale` has answered `409 view_revision_stale {rev_current}` for any + door that raises — while THIS channel, the one the browser actually writes through, read the + stamp nowhere and passed no `rev=` at all. Every layer was green and the guard was inert + ([[a-rev-guard-inert-on-the-events-channel]]): two people editing one view still produced two + 200s and the first edit still vanished. Reading the value here is the only thing that was + missing, which is why this helper is four lines and not a subsystem. + + ⛔ THE EXCEPTION IS NOT CAUGHT ANYWHERE BELOW, DELIBERATELY. `ViewRevisionStale` is a + `RuntimeError` precisely so the `except Exception` fallbacks dotted through these handlers + cannot swallow it (`view_audit.py`'s own class docstring says so), and `main.py:232`'s + handler names THIS channel as the door it exists for: *"the grid events channel above all, + which raises straight out of `table_store` with nothing between it and the client"*. Catching + it here to convert it into a toast would make a shipped, documented handler unreachable and + answer 200 for a write that was refused. + + ⛔ ABSENT IS None, AND None IS ACCEPTED — the pre-C3 behaviour, unchanged. A write that + declares no revision is simply not asked the question, which is what keeps every unstamped + door (and every caller that predates the stamp) writing exactly as it does today. + + ⚠ ANYTHING UNREADABLE AS AN INTEGER IS TREATED AS ABSENT RATHER THAN AS ZERO, and that is + not tidiness. `store_pg.revision()` reports a MISSING key as rev 0, so coercing junk to 0 + would turn a malformed stamp into a confident claim about an empty bucket — the one value + most likely to disagree with the store and refuse a write nobody was racing. + ⚠ `bool` is an `int` in Python, so `True` would arrive as revision 1. Refused by name. + """ + if not isinstance(event, dict): + return None + raw = event.get('rev') + if raw is None or isinstance(raw, bool): + return None + try: + return int(raw) + except (TypeError, ValueError): + return None + + def _tops(ctx): """The table-ops object this ctx operates on — the customer table unless the caller chose another topic. ONE resolution point so 'which bucket does this write land in' has exactly @@ -1358,7 +1400,24 @@ def handle_one(event, ctx): agg = value.get('agg') # The vocabulary is `aios_grid.SUMMARY_AGGS` plus `'none'` — NOT `FIELD_AGGS`, which is # `field.agg`'s six-name write vocabulary and rejects `count_distinct`/`percentile`. - if agg != 'none' and agg not in _ag_summary.SUMMARY_AGGS: + # + # ⭐⭐ W51-T02 / OWNER RULING R3 — AND PLUS `'share'`, ALLOWLISTED BY NAME RIGHT HERE + # RATHER THAN BY WIDENING `aios_grid.SUMMARY_AGGS`. + # + # R3 puts "% of total" on the bottom-bar picker, so `share` is a choice a reader can + # store and it has to survive this door — this whitelist REBUILDS the config from + # named keys, so an unlisted value is not rejected loudly, it simply never gets + # written and the choice vanishes on the next reconcile (the bug the note above + # closed for `count_distinct`). + # ⛔ IT IS NOT A WIRE AGG AND MUST NOT JOIN `aios_grid.SUMMARY_AGGS`. That tuple is + # C1's eight-name clause, `verify_grid_ux.py::summary_bar_shape` holds it byte-for-byte + # against the client's `iconShapes.SUMMARY_AGGS`, and it is what the `/aggregates` + # route compiles into SQL. No engine has a "share of the view" aggregate: a share is a + # DIVISION of two ordinary ones (a numeric column's sum, anything else's count) and + # the client does it. So the picker's extra name is admitted where choices are STORED + # and nowhere a query is COMPILED — which is also why `aios_grid.py`, another lane's + # file, is never opened for this. + if agg != 'none' and agg != 'share' and agg not in _ag_summary.SUMMARY_AGGS: continue choice = {'agg': agg} if agg == 'percentile': @@ -1629,9 +1688,14 @@ def handle_one(event, ctx): # the audit `owner`; `uname` is who DID it. On the foreign-owner branch above they # differ, and a row that conflated them would name the wrong person in the one # record whose entire job is naming the right one. + # ⭐⭐ W51-T33 — `rev=` IS THE STAMP THE BROWSER ALREADY SENDS, finally read. + # See `_event_rev`. The refusal is NOT caught: `main.py:232` turns + # `ViewRevisionStale` into `409 view_revision_stale {rev_current}` for exactly this + # door, and `RevisionUnverifiable` into a 503 beside it, so both reach the client in + # the shape `routes_tables.py`'s direct view routes already answer. view = (_tops(ctx).save_view( _save_as, view, reserved_names=_reserved_view_names, - actor=uname, origin=EVENT_ORIGIN) or view) + actor=uname, origin=EVENT_ORIGIN, rev=_event_rev(event)) or view) else: _session_ready() _view_names = list(_reserved_view_names) @@ -2629,8 +2693,18 @@ def handle_one(event, ctx): # ⛔ LEFT AS A CORRECTION RATHER THAN DELETED. A comment asserting a guard is dead is # exactly what stops the next reader checking, and this one would have outlived the fix. try: + # ⭐⭐ W51-T33 — THE SECOND STAMPED VIEW WRITE, and it is stamped by the client's + # own decision: `CustomerGrid.tsx:10075` emits the views-rail `item_move` through + # `stampViewWrite`, with the comment *"`move` is one of C3's seven audited actions + # and it is a view WRITE like any other"*. `save_folders` has taken `rev=` since + # W50-T25, so the value had a door on both sides and no line between them. + # ⚠ THE OTHER FOUR KINDS THAT LAND HERE ARE UNAFFECTED. `folder_create`, + # `folder_rename`, `folder_delete` and `folder_reorder` carry no stamp, and neither + # does `ViewSidebar.tsx:2022`'s folder-nest `item_move`, so `_event_rev` answers None + # for every one of them and the comparison is not asked — byte-identical behaviour. _receipt = _tops(ctx).save_folders(uname, _res[0], _res[1], - actor=uname, origin=EVENT_ORIGIN) + actor=uname, origin=EVENT_ORIGIN, + rev=_event_rev(event)) except _tstore.FolderTreeError as _fte: return _folder_refuse(ctx, kind, str(getattr(_fte, 'reason', '') or 'folder_tree_illegal'), diff --git a/platform/core/relations.py b/platform/core/relations.py new file mode 100644 index 0000000000000000000000000000000000000000..4d8fee534346b077dfee20412986f09c0f008e34 --- /dev/null +++ b/platform/core/relations.py @@ -0,0 +1,475 @@ +"""relations.py — THE ONE DECLARATION OF WHAT IS RELATED TO WHAT (W51-T05, contract C6, ruling R2). + +R2, verbatim: *"A 'Linked database' tab exists for FORWARD link fields, REVERSE links (another +table's link field pointing at this table) and the ODOO BRIDGES (customers -> orders, order lines, +open invoices; products -> order lines), one tab per related table, resolved server-side; two links +between the same pair give two tabs subtitled by the field."* + +So there are exactly THREE ways one database is related to another, and this module is the single +place that can name all three: + + * ``forward`` — a ``type: "link"`` field ON this table, pointing at another. Declared by the + tenant (``core.user_tables._clean_link``) or, for the two registry modules, by + ``aios-web/api/odoo_relational.module_link_fields``. + * ``reverse`` — ANOTHER table's link field pointing AT this table. Nothing declares this; it is + found by scanning every definition in the tenant, which is why it needs a function rather than + a constant. + * ``bridge`` — a pair of columns that joins two Odoo grains where no link field exists and no + user could create one. ``BRIDGES`` below is the whole list, and it is the only list. + +⛔⛔ THIS MODULE DOES NOT MOVE, RENAME OR SHADOW ``odoo_relational.module_link_fields``. +That function is reached BY STRING: ``automation_engine._module_link_fields`` calls +``getattr(_rel, "module_link_fields", None)``, so renaming it raises no ImportError and silently +kills the pre-set relation columns on ``customer_data``. It keeps owning the pre-set link FIELDS +(the columns a grid renders); this module owns the BRIDGES (the joins that were never fields). +Neither list is copied into the other — ``related()`` takes the fields as an ARGUMENT rather than +importing them, so this file has no opinion about where the field list came from and there is +exactly one declaration of each edge. + +⛔⛔ THE TWO LISTS ARE **NOT** DISJOINT, AND AN EARLIER DRAFT OF THIS HEADER SAID THEY WERE. +``module_link_fields('customer_data')`` declares ``orders`` on ``ut_odoo_orders``, joined +``partner_id`` from ``pid`` — which is ``bridge_customer_orders``, column for column. Declaring +both and concatenating them offered ``customer_data`` two tabs, both labelled Orders, over +identical rows. ``related()`` therefore DEDUPLICATES on ``edge_identity`` and the FIELD wins; see +its docstring for why ``where`` has to be part of that identity. + +⛔ LAYERING. ``core`` never imports up. ``harness.filter_sql`` is imported LAZILY inside the one +function that needs it, exactly as ``core.perm_scope`` imports ``harness.filter_eval``. + +⛔⛔ A CORRECTION TO C6'S OWN MECHANISM, MEASURED 2026-09-03 AND REPORTED RATHER THAN WORKED +AROUND IN SILENCE. C6 says the pin is *"compiled through ``compile_filter_tree(member_ids=, +id_sql=)``"*. That call CANNOT express a pinned read, for two independent reasons in +``platform/harness/filter_sql.py``: + + 1. ``compile_filter_tree`` returns ``None`` the moment the tree is inactive (``_compile_node`` + answers None for an empty node list), and the ``member_ids`` branch sits BELOW that return. + A pinned read with no client filter is exactly the inactive case, so the ids would be + dropped and the WHOLE TABLE served. + 2. When it does run, ``:588`` emits ``(tree OR id_sql IN (...))``. Its own docstring says so: + *"``member_ids`` reproduces ``members.has(r.pid) || matchFilterTree(...)``"*. That is a + UNION. A pinned read needs an INTERSECTION, and ORing a pin onto a filter WIDENS. + +So the pin is compiled HERE, as ``pin_sql`` below, in the SAME spelling ``compile_filter_tree`` +uses for ``member_ids`` (proven byte for byte by ``verify_pivot.py`` section 20 rather than +asserted in a comment), and ANDed into the read ahead of the client predicate. +⇒ EXIT CONDITION: when ``filter_sql`` grows a narrowing member mode (an amendment against lane B, +booked in this ticket's handoff), ``pin_sql`` delegates to it and this note is deleted. +""" + +#: The three ways a database can be related to another. `via.direction` is always one of these. +DIRECTIONS = ('forward', 'reverse', 'bridge') + +#: The identity column of a module grid, as the wire spells it. `customer_data.pid` IS the Odoo +#: `res.partner` id and `ut_odoo_orders.pid` IS the `sale_order` id, so a bridge hanging off `pid` +#: needs no second lookup. `product_data.pid` is NOT an Odoo id (it is `crc32(default_code)`), +#: which is why the product bridge below hangs off `product_id` instead. +IDENTITY_COL = 'pid' + +#: ⛔ THE OPEN-INVOICE PREDICATE IS PART OF THE BRIDGE, NOT DECORATION. "Open invoices" is a +#: different edge from "invoices": a bridge that carried only the column pair would serve EVERY +#: posted document under a tab labelled Open invoices, which is a wrong number wearing the right +#: name. It is spelled here in the same SQL `odoo_relational._AR_WHERE` uses, and section 20 of +#: `verify_pivot.py` asserts the two agree rather than trusting this copy. +OPEN_INVOICE_WHERE = ("state = 'posted' AND move_type IN ('out_invoice','out_refund') " + "AND payment_state IN ('not_paid','partial')") + +#: ⭐⭐ THE FIVE BRIDGES C6 NAMES, AND NOTHING ELSE MAY BE ADDED WITHOUT A RULING. +#: +#: `source_col` is the column on the SOURCE row that carries the join value; `target_col` is the +#: column on the TARGET grid it is matched against. `where` is an extra SQL predicate the edge +#: itself carries (only the open-invoice bridge has one today). +#: +#: ⚠ `served` RECORDS WHETHER THE PINNED READ CAN ANSWER THIS EDGE TODAY, and it is a measurement +#: rather than a wish. The pinned read is built into `routes_odoo_tables._compiled_read`, which +#: serves the READ-THROUGH grids only (`GRID_SOURCES` binds exactly `ut_odoo_orders`, +#: `ut_odoo_order_lines`, `ut_odoo_gl_lines` and `ut_odoo_accounts`). `ut_odoo_invoices` is +#: MATERIALISED, so its rows come from `routes_tables.table_rows`, which takes no predicate at all +#: and is in no lane's fence this wave. The edge is still DECLARED, because a tab that is known to +#: exist and cannot yet be served is a reported limit, while an undeclared one is a silent absence. +BRIDGES = ( + {'key': 'bridge_customer_orders', + 'label': 'Orders', + 'source': 'customer_data', 'target': 'ut_odoo_orders', + 'source_col': IDENTITY_COL, 'target_col': 'partner_id', + 'where': None, 'served': True}, + + {'key': 'bridge_customer_order_lines', + 'label': 'Order lines', + 'source': 'customer_data', 'target': 'ut_odoo_order_lines', + 'source_col': IDENTITY_COL, 'target_col': 'partner_id', + 'where': None, 'served': True}, + + {'key': 'bridge_customer_open_invoices', + 'label': 'Open invoices', + 'source': 'customer_data', 'target': 'ut_odoo_invoices', + 'source_col': IDENTITY_COL, 'target_col': 'partner_id', + 'where': OPEN_INVOICE_WHERE, 'served': False}, + + # ⚠ `product_id`, NOT `pid`, AND THE OBVIOUS CHOICE WOULD HAVE JOINED NOTHING AT ALL. + # `product_data.pid` is `crc32(default_code)` (`modules/product_data.sku_pid`), so matching it + # against `sale_order_line.product_id` resolves zero rows on every product, silently, with a + # perfectly plausible empty tab. `product_data` carries Odoo's own id as the `product_id` + # column (W33-T43 / A2) and that is the column this bridge hangs off. + # ⚠ MEASURED LIMIT, REPORTED BY THE READ (standing rule 1's second sentence): 8 SKU codes on + # this catalogue carry two Odoo product ids each, the archived half of each pair having no + # `product_data` row. Pinning by id therefore reaches the live id's lines and not the archived + # sibling's. Joining on the CODE instead would fix it, and the line grain carries no code + # column to join to. + {'key': 'bridge_product_order_lines', + 'label': 'Order lines', + 'source': 'product_data', 'target': 'ut_odoo_order_lines', + 'source_col': 'product_id', 'target_col': 'product_id', + 'where': None, 'served': True}, + + {'key': 'bridge_order_order_lines', + 'label': 'Order lines', + 'source': 'ut_odoo_orders', 'target': 'ut_odoo_order_lines', + 'source_col': IDENTITY_COL, 'target_col': 'order_id', + 'where': None, 'served': True}, +) + + +def bridges_from(source): + """Every declared bridge whose SOURCE is `source`, in declaration order.""" + key = str(source or '') + return [dict(b) for b in BRIDGES if b['source'] == key] + + +def bridges_into(target): + """Every declared bridge whose TARGET is `target`. The other end of `bridges_from`.""" + key = str(target or '') + return [dict(b) for b in BRIDGES if b['target'] == key] + + +def _link_bag(field): + """The `link` bag off a field, or None when the field is not a link.""" + if not isinstance(field, dict) or field.get('type') != 'link': + return None + bag = field.get('link') + return bag if isinstance(bag, dict) else None + + +def _entry(key, label, target, direction, field=None, on=None, frm=None, served=True, + where=None): + """ONE `/related` entry, in C6's shape. + + ⚠ TWO ADDITIONS TO C6'S LITERAL `{direction, field?, on?}`, both deliberate, both declared in + this ticket's handoff rather than left for the client half to discover. C6 spells its optional + keys with a `?`, so an extra optional key is additive rather than a contradiction. + + * `via.key` — ⛔⛔ WITHOUT IT `via` DOES NOT IDENTIFY AN EDGE, AND THE FIRST DRAFT OF THIS FILE + SHIPPED THE WRONG-JOIN BUG BECAUSE OF IT. `customer_data` has TWO bridges whose direction is + `bridge` and whose `on` column is `partner_id` (orders, and order lines): matching on + `{direction, on}` returns whichever is declared first, so asking for a customer's order + LINES would have been answered with their ORDERS, in the right shape, with every gate green. + Two reverse links named `cust` on two different tables collide the same way. The entry key + is the only thing that is unique, so it rides inside `via` and `find` refuses an ambiguous + bag rather than guessing. + * `via.from` — WHICH value of the source record the edge is keyed on. Without it the caller + cannot tell an edge keyed on the row identity from one keyed on an ordinary column + (`agent_link`'s `from` is the agent NAME), and those two need different handling. + """ + via = {'direction': direction, 'key': str(key)} + if field: + via['field'] = str(field) + if on: + via['on'] = str(on) + if frm: + via['from'] = str(frm) + out = {'key': str(key), 'label': str(label), 'via': via, 'target': str(target), + 'served': bool(served)} + if where: + out['where'] = str(where) + return out + + +def forward_links(table, fields): + """The FORWARD entries for `table`: every `type: "link"` field on it, in field order. + + `fields` is whatever the caller's permission wall handed back, so a link field this account + may not see is not here and cannot become a tab. That is the point of taking it as an argument + instead of reading the store: this module never decides who may see what. + + ⭐ TWO LINKS BETWEEN THE SAME PAIR GIVE TWO ENTRIES, and R2 says so in as many words. The entry + `key` is the FIELD key, not the target key, which is what keeps them apart on the wire. + """ + out = [] + for field in (fields or ()): + bag = _link_bag(field) + if bag is None: + continue + target = str(bag.get('table') or '') + if not target: + continue + out.append(_entry( + key=str(field.get('key') or ''), + label=str(field.get('label') or field.get('key') or target), + target=target, direction='forward', + field=field.get('key'), on=bag.get('on'), + frm=bag.get('from') or IDENTITY_COL)) + return out + + +def reverse_links(table, defs): + """The REVERSE entries for `table`: every OTHER table's link field that points at it. + + `defs` is `{key: definition}` as `core.user_tables.all_defs` returns it, already narrowed to + what this account may open. Nothing declares a reverse link, so this scan IS the declaration + and there is no second place it could be written down. + + ⛔ A TABLE'S LINK TO ITSELF IS NOT A REVERSE LINK. It is already a forward one, and emitting + both would give the same edge two tabs pointing at the same grid, one of them labelled from + the wrong end. + """ + me = str(table or '') + out = [] + for key, defn in sorted((defs or {}).items()): + key = str(key) + if key == me or not isinstance(defn, dict): + continue + for field in (defn.get('fields') or ()): + bag = _link_bag(field) + if bag is None or str(bag.get('table') or '') != me: + continue + out.append(_entry( + key=f"{key}__{field.get('key') or ''}", + label=str(defn.get('label') or key), + target=key, direction='reverse', + field=field.get('key'), + # ⛔ THE COLUMNS SWAP WITH THE DIRECTION, AND GETTING THIS BACKWARDS IS THE + # SILENT-WRONG-JOIN BUG. Forward, the SOURCE row's `from` value is matched against + # the TARGET's `on` column. Read from the other end the roles invert: the reverse + # tab pins the OTHER table on ITS OWN link column (`bag['from']`), keyed by the + # value this table's `on` column carries. `verify_pivot.py` drives a reverse edge + # mislabelled `forward` as a negative control for exactly this. + on=bag.get('from') or IDENTITY_COL, + frm=bag.get('on') or IDENTITY_COL)) + return out + + +def bridge_entries(table): + """The BRIDGE entries for `table`, from `BRIDGES` and from nowhere else.""" + return [_entry(key=b['key'], label=b['label'], target=b['target'], direction='bridge', + on=b['target_col'], frm=b['source_col'], served=b['served'], + where=b['where']) + for b in bridges_from(table)] + + +def edge_identity(entry): + """WHAT MAKES TWO ENTRIES THE SAME EDGE: the target, both join columns, and the predicate. + + ⛔ `where` IS PART OF THE IDENTITY AND DROPPING IT WOULD DELETE A REAL TAB. "Open invoices" + and "Invoices" are the same target joined on the same two columns; the ONLY thing that makes + them different questions is the AR predicate. An identity of `(target, on, from)` alone would + fold the open-invoice bridge into the pre-set `invoices` link and R2's third bridge would + silently stop existing. + """ + via = entry.get('via') or {} + return (str(entry.get('target') or ''), str(via.get('on') or ''), + str(via.get('from') or ''), str(entry.get('where') or '')) + + +def related(table, fields=None, defs=None): + """THE `/related` ANSWER for one table: forward, then reverse, then bridge. + + `[{key, label, via: {direction, key, field?, on?, from?}, target, served, where?}]`. + + ⛔ THE ORDER IS PART OF THE ANSWER. Forward links are the ones the reader created and can see + as columns; reverse links are inferred; bridges are ours. A stable order means a tab strip + does not reshuffle between two reads of the same record. + + ⛔⛔ A BRIDGE THAT REPEATS A LINK FIELD IS DROPPED, AND THIS FILE'S HEADER USED TO CLAIM THE + TWO LISTS WERE DISJOINT WITHOUT CHECKING. THEY ARE NOT. `module_link_fields('customer_data')` + already declares `orders` -> `ut_odoo_orders` on `partner_id` from `pid`, which is + `bridge_customer_orders` column for column, so the first build of this function offered + `customer_data` TWO tabs both labelled Orders, over the same rows, differing only in which one + the reader happened to click. R2 says *"one tab per related table"* and allows two only when + there are genuinely two links. + ⭐ THE FIELD WINS, NOT THE BRIDGE. The field is the one the grid renders as a column, the one + `automation_engine` resolves, and the one an administrator can see; the bridge exists exactly + for the edges that are NOT fields. Suppressing the bridge therefore removes a duplicate rather + than a capability, and `bridge_customer_open_invoices` survives because its predicate makes it + a different question about the same pair. + ⚠ ON A TENANT WITH NO PRE-SET LINKS the bridge is not a duplicate of anything and is offered + unchanged, which is the whole reason the suppression is computed rather than declared. + """ + forward = forward_links(table, fields or ()) + reverse = reverse_links(table, defs or {}) + seen = {edge_identity(e) for e in forward} | {edge_identity(e) for e in reverse} + bridges = [b for b in bridge_entries(table) if edge_identity(b) not in seen] + return forward + reverse + bridges + + +def find(table, via, fields=None, defs=None): + """The ONE entry of `related(table, ...)` that `via` names, or None. See `pick`.""" + return pick(related(table, fields, defs), via) + + +def pick(entries, via): + """The ONE entry `via` names out of an ALREADY-BUILT list, or None. + + ⛔ THE LIST IS AN ARGUMENT SO THE ROUTE LAYER CAN HAND IN A **SCOPED** ONE. The read side + resolves a pin against exactly the entries the listing door would have offered this account, + which is what makes "an edge you cannot see is an edge you cannot pin" true by construction + rather than by two functions agreeing. + + ⛔⛔ EXACTLY ONE, OR NONE. `via.key` identifies an edge on its own; a bag without one is + matched on `direction` plus whichever of `field` / `on` it carries, and **an ambiguous match + answers None**. It does NOT answer the first hit. `customer_data` really does carry two + bridges reading `{direction: "bridge", on: "partner_id"}` (orders and order lines), so + first-hit would have served one record's orders under the order-lines tab, correctly shaped + and wrong. Refusing sends the caller back with a sentence; guessing sends it a number. + """ + if not isinstance(via, dict): + return None + want_dir = str(via.get('direction') or '') + if want_dir not in DIRECTIONS: + return None + want_key = str(via.get('key') or '') + want_field = str(via.get('field') or '') + want_on = str(via.get('on') or '') + if not (want_key or want_field or want_on): + return None # a direction alone names no edge; refuse rather than guess + hits = [] + for entry in (entries or ()): + got = entry['via'] + if got['direction'] != want_dir: + continue + if want_key: + if entry['key'] == want_key: + return entry + continue + if want_field and str(got.get('field') or '') != want_field: + continue + if want_on and str(got.get('on') or '') != want_on: + continue + hits.append(entry) + return hits[0] if len(hits) == 1 else None + + +def unknown_via_refusal(table, via): + """The SENTENCE an unknown `via` earns: what was asked, why it cannot be answered, what to do. + + ⛔ A SENTENCE, NOT A CODE. C6 says an unknown `via` *"refuses with a sentence"*, and the reason + is that the alternative to refusing is serving the whole table under a tab that claims to show + one record's related rows. A bare 400 leaves the caller unable to tell a typo from a link an + administrator has since deleted. + ⛔ NO EM DASH AND NO EN DASH: this string reaches a screen (standing rule 2). + """ + named = '' + if isinstance(via, dict): + named = str(via.get('field') or via.get('on') or via.get('direction') or '') + return ("this account cannot resolve a relation " + + (f"named '{named}' " if named else "") + + f"on '{table}', so there is no edge to pin these rows to. Ask for the relation by " + f"one of the entries GET /api/v1/grid/" + str(table) + "/related returns, or open " + "the linked database on its own and filter it there") + + +def unresolvable_source_refusal(table, entry): + """The sentence an edge earns when the source record's JOIN VALUE cannot be read. + + ⭐ IT FIRES ONLY FOR AN EDGE KEYED ON A COLUMN. When `via.from` is the record identity the + value IS the record and there is nothing to resolve; when it is an ordinary column + (`agent_link` is keyed on the agent NAME, `bridge_product_order_lines` on `product_id`) the + cell is read off the source row, and it comes back missing two ways: the record is not in the + set this reader may see, or that cell is empty on that row. + + ⛔ REFUSING BEATS FALLING BACK TO THE RECORD ID. `product_data.pid` is `crc32(default_code)`, + so a fallback would join a hash against an Odoo id, match nothing, and paint as "this product + has never been ordered" - a claim about the business made out of a missing input. + ⛔ AND IT NAMES NEITHER CAUSE AS THE CAUSE. Saying "you may not see that record" would leak + whether the record exists; saying "that cell is empty" would be a guess. Both are offered. + """ + via = entry.get('via') or {} + frm = str(via.get('from') or '') + return (f"the relation '{entry.get('key')}' is keyed on the '{frm}' value of the record you " + f"asked to pin, and that value could not be read from '{table}' for this record, " + f"either because it is not a record this account may see or because the cell is " + f"empty on it. Open '{entry.get('target')}' on its own and filter it on " + f"'{via.get('on') or frm}', or pin a record that carries a '{frm}'") + + +def unserved_target_refusal(entry): + """The sentence a DECLARED but UNSERVED edge earns. + + `served: False` means the target grid stores its rows rather than being read through, so its + window has no predicate to push a pin into. Naming it is the whole difference between a + reported limit and a feature that quietly does nothing. + """ + return (f"'{entry.get('target')}' is served from its stored copy rather than read through the " + "live mirror, and that door takes no row filter, so this relation cannot be pinned " + "yet. Open that database directly, or ask for the stored read to accept a relation " + "pin") + + +# --------------------------------------------------------------------------- the pin + +def member_ids_tail(id_sql, member_ids): + """`(sql, params)` for "the row identity is one of these ids", in filter_sql's OWN spelling. + + ⛔⛔ READ THE MODULE HEADER BEFORE CHANGING THIS. It is deliberately the SAME expression + `harness.filter_sql.compile_filter_tree` emits for its `member_ids` argument + (`f"{id_sql} IN ({','.join('?' for _ in ids)})"`, `:588`) and NOT the `COALESCE(..., FALSE)` + form `_compile_cohort` uses at `:528`. The difference is real and this is the right side of + it: a NULL row identity is not a member of any set, so SQL dropping the row is the answer we + want, whereas COALESCE-to-FALSE would matter only under a NOT. + + `verify_pivot.py` proves the two spellings agree by compiling a real tree through + `compile_filter_tree(member_ids=..., id_sql=...)` and extracting its tail, rather than by this + comment. That is what stops the two drifting apart. + + ⛔ AN EMPTY MEMBER SET IS `1=0`, NEVER "NO PIN". `compile_filter_tree` treats an empty + `member_ids` as falsy and emits nothing, which on a UNION is correct and on a pinned read is + the whole table. A record with no related rows must answer zero rows. + """ + ident = str(id_sql or '') + if not ident: + raise ValueError('a pinned read needs id_sql (the row-identity column). Refusing rather ' + 'than defaulting: a pin on the wrong column is a wrong answer with ' + 'nothing red beside it') + ids = [int(x) for x in (member_ids or ())] + if not ids: + return ('1=0', []) + return (f"{ident} IN ({','.join('?' for _ in ids)})", ids) + + +def pin_sql(id_sql, member_ids): + """THE PINNED-READ PREDICATE. `(sql, params)`, to be ANDed AHEAD of any client filter. + + ⛔ ANDED, NOT OR'ED, AND THAT IS WHY THIS FUNCTION EXISTS RATHER THAN A `member_ids=` ARGUMENT + ON `compile_filter_tree`. See the module header: that argument is a documented UNION and is + skipped entirely when the client sends no filter. + """ + return member_ids_tail(id_sql, member_ids) + + +def compiled_pin_matches_filter_sql(id_sql, member_ids, columns=None): + """Does `pin_sql` still spell the member tail exactly as `filter_sql` spells it? + + Returns `(ours, theirs)` — two SQL fragments a gate can compare. `theirs` is extracted from a + REAL `compile_filter_tree` call carrying `member_ids=`, so the day lane B changes that + spelling this answers two different strings instead of agreeing by assumption. + + ⚠ The tree handed to `compile_filter_tree` must be ACTIVE or the call returns None before the + member branch runs at all, which is the first half of the correction in this module's header. + """ + from harness import filter_sql as _fs # noqa: PLC0415 - layering + + cols = dict(columns or {'__pin_probe__': {'sql': 'probe', 'type': 'text', + 'aggregate': False}}) + probe = next(iter(cols)) + got = _fs.compile_filter_tree([{'colId': probe, 'op': 'isNotEmpty'}], + conj='and', columns=cols, + member_ids=list(member_ids or ()), id_sql=id_sql) + ours = pin_sql(id_sql, member_ids)[0] + theirs = None + if got is not None and ' OR ' in got.sql: + # ⛔ EXACTLY ONE closing paren, never `rstrip(')')`. The tail is `sol.id IN (?,?,?))` — + # the last `)` closes `compile_filter_tree`'s own wrapper and the one before it closes the + # IN list. `rstrip` eats both and the gate then compares `sol.id IN (?,?,?` against a + # correct fragment and reports a drift that is entirely its own. + theirs = got.sql.rsplit(' OR ', 1)[1] + if theirs.endswith(')'): + theirs = theirs[:-1] + return ours, theirs diff --git a/platform/core/shares.py b/platform/core/shares.py index 455b1f55517a26ecf909930e2c5262a5ee689db6..7219234a6cf300afaa20ff1daa6c0f068dd2c50b 100644 --- a/platform/core/shares.py +++ b/platform/core/shares.py @@ -80,7 +80,7 @@ SHARES_KEY = 'object_shares' #: here is this tuple member. That is the point of one registry: the new object's WALL is written #: once in `core.perm_scope`, and its DOORS once in `routes_shares.py` — never a fourth #: permission decision in a fourth file ([[one-evaluator-per-question]]). -KINDS = ('view', 'folder', 'database', 'field', 'cohort') +KINDS = ('view', 'folder', 'database', 'field', 'cohort', 'workbook') #: `*` is "everyone who can already open the surface". It is NOT "every account on the platform". #: Spelled as a single character so it can never collide with a username (usernames are lower-case diff --git a/platform/core/sheet_import.py b/platform/core/sheet_import.py new file mode 100644 index 0000000000000000000000000000000000000000..b9b349048dc04751ecbf4422af7dd0e0285d08dc --- /dev/null +++ b/platform/core/sheet_import.py @@ -0,0 +1,980 @@ +"""core/sheet_import.py — the .xlsx IMPORTER (wave 51, instruction 7, ticket W51-T24, contract C4). + +WHAT GOES HERE: + + One pure function, `import_workbook(path)`, that turns an .xlsx file on disk into the C1/C2 + document `core/sheets.py` already knows how to store, plus a REPORT of what did not survive. + It resolves nothing, writes nothing and knows no store: the job, the temp file, the thread and + the differential all belong to `aios-web/api/routes_sheet.py`, which is the one place that can + recompute a formula and persist a document. + +⭐⭐ **THE IMPORT IS TWO OPENPYXL PASSES, AND BOTH ARE NEEDED FOR THE SAME CELL.** With +`data_only=False` a formula cell hands back its FORMULA TEXT and with `data_only=True` it hands +back the value Excel last CACHED for it. R1's done-when is a differential between those two +readings and our own engine, so a one-pass import cannot be checked at all: it would store 11,336 +formulas and have nothing to compare our answers against. + +⭐⭐ **THE CACHED VALUE RIDES OUT ON `imported_value` AND IS NEVER STORED.** `clean_cell` builds a +fresh dict from the keys it names, so an unnamed key is dropped by the ordinary save path anyway; +this module puts the cached reading there deliberately so the caller can run the differential in +memory and then drop it. ⛔ THE ALTERNATIVE WAS MEASURED AND REJECTED: parking it in `source` +(a dict `clean_cell` does carry) would persist a second copy of every formula's value, which is +about 0.9 MiB on the owner's model against a 16 MiB cap, to store a number the recalc has already +replaced. + +⛔⛔ **A COLOUR ARRIVES AS ARGB HEX AND MUST NOT BE STORED AS ONE.** `sheets._COLOUR` would accept +`FF1F4E78` in silence, which would freeze a palette decision into a stored document that outlives +every palette change (DESIGN.md 3, and `types.ts` is token only). So every colour is QUANTIZED to +the nearest `--lp-*` token by RGB distance, and the two defaults (ink on white) are stored as an +ABSENCE for `_clean_style`'s reason: a cell painted the colour it already is must compare equal to +the cell that was never painted. On the owner's model that absence is what keeps 43,285 explicit +font colours from becoming 43,285 stored style wrappers. + +⛔ **UNSUPPORTED IS A LIST, NOT A SILENCE (standing rule 1's second sentence).** Everything this +module cannot carry is named once, with a count, in the tab's `imported.unsupported` and in the +report. An importer that drops a hidden tab, a theme colour or a scatter chart without saying so +hands back a workbook that looks complete and is not. + +⚠ Every note in here reaches a screen, so none carries an em dash or an en dash (standing rule 2). +""" + +from __future__ import annotations + +import re +from datetime import date, datetime, time, timezone + +from core import sheets + +#: C4's upload ceiling. ⚠ IT IS THE FILE, NOT THE DOCUMENT. An .xlsx is zipped, so 25 MB of file +#: can be far more than `sheets.MAX_WORKBOOK_BYTES` of document; the document cap is enforced +#: where it belongs, by `_json_safe` on the save, and this one only stops an upload nothing could +#: parse in reasonable time. +MAX_IMPORT_BYTES = 25 * 1024 * 1024 + +#: C4's job states, in the order a job walks them. `refused` is the exit that replaces `done`. +IMPORT_STATES = ("reading", "cells", "formats", "recalc", "done", "refused") + +#: ⛔ THE PALETTE, COPIED FROM `aios-web/web/src/index.css` `:root`, TOKEN FOR TOKEN. It is copied +#: rather than read because `platform/core` may not reach up into the web tree (ARCHITECTURE.md's +#: one-way layering), and `verify_sheet.py` section 4 parses the CSS and asserts every pair below +#: still matches it, so the copy cannot drift in silence. +#: +#: ⚠ ONLY PAINTABLE TOKENS ARE HERE. The `--lp-fs-*`, `--lp-r-*` and layout tokens in that block +#: are sizes, not colours, and quantizing a fill onto one of them would be nonsense. +PALETTE = { + "--lp-surface": "#ffffff", + "--lp-surface-2": "#f7f7f6", + "--lp-ink": "#202433", + "--lp-muted": "#6b7280", + "--lp-line": "#e6e9ef", + "--lp-wash": "#fafbfc", + "--lp-blue": "#9dbff2", + "--lp-blue-tint": "#edf3fd", + "--lp-blue-deep": "#768fb6", + "--lp-blue-solid": "#5b8fd9", + "--lp-map-selected": "#1b4f9c", + "--lp-yellow": "#f5d989", + "--lp-yellow-tint": "#fbf4e0", + "--lp-yellow-deep": "#7e6428", + "--lp-red": "#f0a8a0", + "--lp-red-tint": "#fceeec", + "--lp-red-deep": "#a3453c", + "--lp-green": "#a5d8b4", + "--lp-green-tint": "#ebf6ef", + "--lp-green-deep": "#35754e", + "--lp-purple": "#c3b3ee", + "--lp-purple-tint": "#f1eefb", + "--lp-purple-deep": "#6b57a8", + "--lp-brand": "#6e56cf", + "--lp-primary": "#5433cc", + "--lp-primary-hover": "#472bad", + "--lp-primary-tint": "#eeeafc", +} + +#: ⭐ THE TWO DEFAULTS, STORED AS AN ABSENCE. Ink on white is what every unpainted cell already +#: is, so writing them would make a cell somebody coloured black compare unequal to the cell that +#: was never coloured, and would cost a style wrapper on tens of thousands of cells that look +#: exactly the same either way. +DEFAULT_INK = "--lp-ink" +DEFAULT_FILL = "--lp-surface" + +#: The four font steps A1 froze, in points. A size is a STEP and never a pixel count, for +#: `_clean_style`'s reason: a stored pixel size is a layout decision that outlives the layout. +_SIZE_STEPS = ((9.5, "s"), (12.5, "m"), (16.5, "l")) + +#: Excel's horizontal alignments that have a home in `CELL_ALIGNS`. Everything else is named in +#: `unsupported` rather than guessed at: `justify` and `distributed` are not `left`. +_ALIGNS = {"left": "left", "center": "center", "centre": "center", "right": "right"} +_VALIGNS = {"top": "top", "center": "middle", "centre": "middle", "bottom": "bottom"} + +#: openpyxl's `cellIs` operators, mapped onto `sheets.SHEET_RULE_OPS`. ⛔ AN OPERATOR THAT IS NOT +#: HERE IS NAMED IN `unsupported` AND THE RULE IS DROPPED, never passed through: `_clean_rules` +#: REFUSES an op outside its ten by name, so a guess here would 400 a whole import over one rule. +_RULE_OPS = { + "lessThan": "lt", "lessThanOrEqual": "lte", "greaterThan": "gt", + "greaterThanOrEqual": "gte", "equal": "eq", "notEqual": "neq", "between": "between", +} + +#: openpyxl chart classes mapped onto `sheets.SHEET_CHART_KINDS`, by class NAME so this module +#: does not import four chart classes it would then have to keep in step. +_CHART_KINDS = {"BarChart": "bar", "BarChart3D": "bar", "LineChart": "line", + "LineChart3D": "line", "AreaChart": "area", "AreaChart3D": "area", + "PieChart": "donut", "PieChart3D": "donut", "DoughnutChart": "donut"} + +#: The currency symbols a number format may wear, mapped to the ISO code `CellFormat.currency` +#: carries. ⚠ AN UNKNOWN SYMBOL FALLS TO `code`, which renders it EXACTLY as the file asked; +#: guessing an ISO code from a glyph we do not know is how a number acquires the wrong currency. +_CURRENCY_SYMBOLS = {"$": "USD", "€": "EUR", "£": "GBP", "¥": "JPY", + "₩": "KRW", "₹": "INR", "₽": "RUB", "Rp": "IDR"} + +_QUOTED = re.compile(r'"[^"]*"') +_BRACKET = re.compile(r"\[[^\]]*\]") +_PLAIN_NUMBER = re.compile(r"^[#0,.\s+-]+$") +_DATE_LETTERS = re.compile(r"[ymdhs]", re.I) +_A1_CELL = re.compile(r"^([A-Z]{1,3})([0-9]{1,7})$") + +#: How many addresses one validation or one conditional rule may paint onto cells that do not +#: otherwise exist. ⚠ A DATA VALIDATION IS ROUTINELY ATTACHED TO A WHOLE COLUMN, so expanding +#: its `sqref` blindly would invent a million style-only cells out of one dropdown. +_MAX_SPREAD = 2000 + +#: How many mismatches the caller's report lists individually. Past this the count still tells the +#: truth and the list stops growing; a report is read by a person, not by a diff tool. +MAX_MISMATCHED = 500 + + +# ── colour ─────────────────────────────────────────────────────────────────────────────────── + +def _rgb_of(token_hex): + h = token_hex.lstrip("#") + return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)) + + +_PALETTE_RGB = {name: _rgb_of(value) for name, value in PALETTE.items()} + + +def argb_of(colour): + """The six hex digits of an openpyxl colour, or "" when it is not an explicit RGB one. + + ⚠ THEME AND INDEXED COLOURS ANSWER "" ON PURPOSE. Resolving a theme colour needs the + workbook's theme XML and its tint arithmetic, and a wrong resolution paints a cell a colour + nobody chose. The caller names them in `unsupported` instead. + """ + if colour is None: + return "" + raw = getattr(colour, "rgb", None) + if not isinstance(raw, str): + return "" + text = raw.strip().upper() + if len(text) == 8: + # ⚠ A FULLY TRANSPARENT COLOUR IS NOT A COLOUR. `00000000` is openpyxl's "auto", which + # means "whatever the theme says", not "black". + if text[:2] == "00": + return "" + text = text[2:] + if len(text) != 6 or any(c not in "0123456789ABCDEF" for c in text): + return "" + return text + + +def quantize(argb): + """The nearest `--lp-*` token to six ARGB hex digits, or "" when there is nothing to quantize. + + ⛔ NEAREST BY SQUARED RGB DISTANCE, and that is a deliberate simplification rather than an + oversight: a perceptual distance would need a colour space this layer has no business + carrying, and the palette is small and widely spaced enough that the two agree on every token + in it. What matters is that the ANSWER IS A TOKEN, so no hex reaches a stored document. + """ + if not argb: + return "" + r, g, b = _rgb_of(argb) + best, best_d = "", None + for name, (pr, pg, pb) in _PALETTE_RGB.items(): + d = (r - pr) ** 2 + (g - pg) ** 2 + (b - pb) ** 2 + if best_d is None or d < best_d: + best, best_d = name, d + return best + + +# ── number formats ─────────────────────────────────────────────────────────────────────────── + +def classify_format(code): + """`(format_dict_or_None, note_or_empty)` for one Excel number format code. + + ⭐⭐ THE FALLBACK IS `code`, NOT A GUESS, AND THAT IS WHY 53% OF THE OWNER'S MODEL SURVIVES. + `CellFormat` can say number, currency, percent and date; it cannot say accounting, cannot say + "negatives in brackets" and cannot carry a per-section branch. A code we do not recognise is + handed on VERBATIM as `{kind: "code", code}` so the client's formatter renders exactly what + the file asked for, and only a code `_clean_format_code` would refuse becomes a note. + + ⛔ A MULTI-SECTION CODE IS NEVER CLASSIFIED. `_(* #,##0_);_(* \\(#,##0\\);...` reduces to + something that looks like a plain number pattern once its pads and escapes are stripped, and + reading it as `number` would silently stop showing negatives in brackets. Any `;` sends the + code straight to `code`. + """ + text = str(code or "").strip() + if not text or text.lower() == "general": + return None, "" + + def _as_code(): + try: + return {"kind": "code", "code": sheets._clean_format_code(text)}, "" + except sheets.SheetRefusal as exc: + return None, "a number format could not be carried (" + exc.code + ")" + + if ";" in text: + return _as_code() + #: A pad (`_x`), a fill (`*x`) or an escape (`\\x`) is layout this model does not express, so + #: the whole code goes through verbatim rather than being partly understood. + if any(ch in text for ch in ("_", "*", "\\")): + return _as_code() + if "@" in text: + return _as_code() + + quoted = [q[1:-1] for q in _QUOTED.findall(text)] + bare = _BRACKET.sub("", _QUOTED.sub("", text)) + brackets = _BRACKET.findall(text) + + if _DATE_LETTERS.search(bare): + return {"kind": "date"}, "" + + decimals = 0 + dot = bare.split(".") + if len(dot) > 1: + decimals = len(re.match(r"[0#]*", dot[1]).group(0)) + thousands = "#,#" in bare or "0,0" in bare or ",##" in bare + + if "%" in bare: + out = {"kind": "percent"} + if decimals: + out["decimals"] = decimals + return out, "" + + symbols = [s for s in quoted if s.strip()] + [b.strip("[]$-") for b in brackets if "$" in b] + symbols += [ch for ch in bare if ch in _CURRENCY_SYMBOLS] + iso = "" + for sym in symbols: + key = sym.strip() + if key in _CURRENCY_SYMBOLS: + iso = _CURRENCY_SYMBOLS[key] + break + if len(key) == 3 and key.isalpha(): + iso = key.upper() + break + + stripped = bare + for ch in _CURRENCY_SYMBOLS: + stripped = stripped.replace(ch, "") + if iso and _PLAIN_NUMBER.match(stripped or "0"): + out = {"kind": "currency", "currency": iso} + if decimals: + out["decimals"] = decimals + return out, "" + + if not quoted and not brackets and _PLAIN_NUMBER.match(bare): + out = {"kind": "number"} + if decimals: + out["decimals"] = decimals + if thousands: + out["thousands"] = True + return out, "" + + return _as_code() + + +# ── one cell's style ───────────────────────────────────────────────────────────────────────── + +def _size_step(points): + if not isinstance(points, (int, float)): + return "" + for limit, step in _SIZE_STEPS: + if points < limit: + return step + return "xl" + + +def style_of(cell, notes): + """The C2 style for one openpyxl cell, or `{}` when nothing about it is worth storing. + + ⚠ FONT FAMILY IS DROPPED IN SILENCE AND THAT IS THE DESIGN, not an omission: the app is Inter + everywhere (DESIGN.md), so carrying Arial would either be ignored or would put a second + typeface on a screen the design forbids. It is still NAMED in the report, once, because a + person who imported an Arial workbook should be told why it does not look like Arial. + """ + out = {} + font = getattr(cell, "font", None) + if font is not None: + if font.b: + out["bold"] = True + if font.i: + out["italic"] = True + if font.u: + out["underline"] = True + step = _size_step(font.sz) + if step and step != "m": + out["size"] = step + argb = argb_of(font.color) + if argb: + token = quantize(argb) + if token and token != DEFAULT_INK: + out["color"] = token + elif font.color is not None and getattr(font.color, "type", "") in ("theme", "indexed"): + notes.add("a theme or indexed font colour was replaced by the default ink") + + fill = getattr(cell, "fill", None) + if fill is not None and getattr(fill, "patternType", None) == "solid": + argb = argb_of(fill.fgColor) + if argb: + token = quantize(argb) + if token and token != DEFAULT_FILL: + out["fill"] = token + elif getattr(fill.fgColor, "type", "") in ("theme", "indexed"): + notes.add("a theme or indexed cell fill was left unpainted") + elif fill is not None and getattr(fill, "patternType", None): + notes.add("a patterned cell fill was left unpainted, because a fill is a flat colour here") + + align = getattr(cell, "alignment", None) + if align is not None: + horizontal = str(align.horizontal or "") + if horizontal in _ALIGNS: + out["align"] = _ALIGNS[horizontal] + elif horizontal and horizontal != "general": + notes.add("the " + horizontal + " horizontal alignment has no equivalent here") + vertical = str(align.vertical or "") + if vertical in _VALIGNS: + if _VALIGNS[vertical] != "bottom": + out["valign"] = _VALIGNS[vertical] + elif vertical: + notes.add("the " + vertical + " vertical alignment has no equivalent here") + if align.wrapText: + out["wrap"] = True + if isinstance(align.indent, (int, float)) and int(align.indent) > 0: + out["indent"] = min(sheets._MAX_INDENT, int(align.indent)) + + border = getattr(cell, "border", None) + if border is not None: + sides = {} + for side in sheets._BORDER_SIDES: + edge = getattr(border, side, None) + if edge is not None and getattr(edge, "style", None): + sides[side] = True + if sides: + out["border"] = sides + notes.add("a border keeps its side but not its weight, style or colour") + + fmt, note = classify_format(getattr(cell, "number_format", "")) + if fmt: + out["format"] = fmt + if note: + notes.add(note) + return out + + +# ── values ─────────────────────────────────────────────────────────────────────────────────── + +def json_value(value): + """One openpyxl value as something the store can hold, or None when it cannot be carried. + + ⛔ A `datetime` IS NOT JSON. `_json_safe` refuses a value it cannot serialize, so a date cell + handed straight through would refuse the WHOLE workbook on save; it becomes an ISO string, + which is what every other date on the wire in this app already is. + """ + if value is None or isinstance(value, (str, int, float, bool)): + #: ⚠ A float that is not finite is not JSON either, and `json.dumps` emits `NaN`, which + #: no other JSON reader accepts. It is carried as absent rather than as a number. + if isinstance(value, float) and (value != value or value in (float("inf"), + float("-inf"))): + return None + return value + if isinstance(value, datetime): + return value.replace(microsecond=0).isoformat() + if isinstance(value, (date, time)): + return value.isoformat() + return str(value) + + +def values_match(computed, cached, *, tolerance=1e-6): + """R1's differential test for ONE cell: numbers within `tolerance` relative, strings exact. + + ⭐ A RELATIVE TOLERANCE, WITH AN ABSOLUTE FLOOR. Excel caches a double and our engine computes + one, so the last bits differ on any long sum; a relative test says that is the same number, + and the floor is what stops `0.0` versus `1e-18` from being a 100% relative miss. + + ⚠ `True == 1` IN PYTHON, so booleans are compared as booleans first. Without that leg a cell + Excel cached as `TRUE` would silently match a computed `1`. + """ + if computed is None and cached is None: + return True + if isinstance(computed, bool) or isinstance(cached, bool): + return bool(computed) is bool(cached) and type(computed) is type(cached) + if isinstance(computed, (int, float)) and isinstance(cached, (int, float)): + gap = abs(float(computed) - float(cached)) + scale = max(abs(float(computed)), abs(float(cached)), 1.0) + return gap <= tolerance * scale + if computed is None or cached is None: + return False + return str(computed) == str(cached) + + +def mismatch_kind(computed, cached): + """The CLASS of a mismatch, which is what a report is read for. + + ⚠ It answers what the two readings ARE, not why they differ: a class tells the reader whether + the engine got a number wrong, refused outright, or returned a different SHAPE of thing, and + those three send them to three different places. + """ + if computed is None: + return "refused" + if isinstance(computed, (int, float)) and isinstance(cached, (int, float)) \ + and not isinstance(computed, bool) and not isinstance(cached, bool): + return "number" + if isinstance(computed, str) and isinstance(cached, str): + return "text" + return "type" + + +# ── geometry helpers ───────────────────────────────────────────────────────────────────────── + +def col_index(letters): + """`A` -> 0. The zero-based column a chart rectangle and a hidden column count in.""" + n = 0 + for ch in str(letters).upper(): + if not ch.isalpha(): + return -1 + n = n * 26 + (ord(ch) - 64) + return n - 1 + + +def _corner(ref): + """`$B$4` -> `(1, 3)` zero-based, or None.""" + found = _A1_CELL.match(str(ref or "").replace("$", "").upper()) + if not found: + return None + return col_index(found.group(1)), int(found.group(2)) - 1 + + +def rect_of(ref): + """A zero-based inclusive rectangle for `'Tab'!$B$2:$D$40`, or None. The tab part is ignored.""" + text = str(ref or "").split("!")[-1].replace("$", "").upper() + parts = text.split(":") + first = _corner(parts[0]) + last = _corner(parts[-1]) if len(parts) > 1 else first + if first is None or last is None: + return None + return {"col0": min(first[0], last[0]), "row0": min(first[1], last[1]), + "col1": max(first[0], last[0]), "row1": max(first[1], last[1])} + + +def sheet_of_ref(ref): + """The tab a `'Tab'!$B$2` reference names, unquoted, or "" when it names none.""" + text = str(ref or "") + if "!" not in text: + return "" + head = text.rsplit("!", 1)[0].strip() + if head.startswith("'") and head.endswith("'") and len(head) > 1: + head = head[1:-1].replace("''", "'") + return head + + +def freeze_of(anchor): + """`A2` -> `{"rows": 1}`. The anchor is the first cell BELOW and RIGHT of the frozen panes.""" + corner = _corner(anchor) + if corner is None: + return {} + cols, rows = corner + out = {} + if cols > 0: + out["cols"] = cols + if rows > 0: + out["rows"] = rows + return out + + +def width_px(chars): + """Excel's character width to pixels, clamped into `MIN_COL_WIDTH..MAX_COL_WIDTH`. + + ⚠ THE CONVERSION IS EXCEL'S OWN APPROXIMATION (7 px per character of the default face plus + 5 px of padding), not a measurement of Inter. It cannot be exact across two typefaces, and a + column that is one character too narrow is a drag away from right; a column stored in + CHARACTERS would be a unit the grid cannot lay out at all. + """ + if not isinstance(chars, (int, float)) or chars <= 0: + return 0 + return max(sheets.MIN_COL_WIDTH, min(sheets.MAX_COL_WIDTH, int(round(chars * 7.0 + 5)))) + + +def _spread(sqref, limit=_MAX_SPREAD): + """Every A1 address a `sqref` covers, at most `limit` of them, plus whether it was cut.""" + out = [] + for part in str(sqref or "").replace("$", "").upper().split(): + rect = rect_of(part) + if rect is None: + continue + for row in range(rect["row0"], rect["row1"] + 1): + for col in range(rect["col0"], rect["col1"] + 1): + if len(out) >= limit: + return out, True + out.append(_addr(col, row)) + return out, False + + +def _addr(col, row): + """`(1, 3)` -> `B4`. Zero-based in, A1 out.""" + letters, n = "", col + 1 + while n > 0: + n, rem = divmod(n - 1, 26) + letters = chr(65 + rem) + letters + return letters + str(row + 1) + + +# ── the import ─────────────────────────────────────────────────────────────────────────────── + +class ImportRefusal(Exception): + """A named refusal the job reports as `state: refused` with a sentence a person can act on.""" + + def __init__(self, code, message): + super().__init__(message) + self.code = code + self.message = message + + +def _note_list(notes): + """The notes as a sorted list, capped where `_clean_imported` caps them.""" + return sorted(notes)[:sheets._MAX_UNSUPPORTED] + + +#: ⛔ THE ONLY TWO STYLE KEYS A CELL WITH NO VALUE CAN SHOW. It is a shorter list than +#: `sheet/types.ts::stylePaints` on purpose, and each omission is the same argument: `format` +#: decides how a VALUE reads and there is no value; `bold`, `italic`, `underline` and `color` +#: draw GLYPHS and there are none; `align`, `wrap` and `indent` lay out text that is not there. +#: A fill and a border are the two marks a reader can actually see on an empty cell. +_PAINT_KEYS = ("fill", "border") + + +def _painting(style): + """The part of a style worth keeping on an EMPTY cell, or `{}` when it paints nothing.""" + return {k: v for k, v in (style or {}).items() if k in _PAINT_KEYS} + + +def _cells_of(ws, cached, notes, counts): + """One tab's cell map, keyed A1, from the formula pass plus the cached-value pass.""" + cells = {} + style_only = {} + counts["blank_styles"] = 0 + max_row = min(int(ws.max_row or 1), sheets.MAX_SHEET_ROWS) + max_col = min(int(ws.max_column or 1), sheets.MAX_SHEET_COLS) + if int(ws.max_row or 1) > sheets.MAX_SHEET_ROWS or int(ws.max_column or 1) > \ + sheets.MAX_SHEET_COLS: + notes.add("this tab is larger than one sheet holds, so its far rows or columns were " + "not read") + for row in ws.iter_rows(min_row=1, max_row=max_row, min_col=1, max_col=max_col): + for cell in row: + addr = cell.coordinate + raw = cell.value + has_style = bool(getattr(cell, "has_style", False)) + if raw is None and not has_style: + continue + style = style_of(cell, notes) if has_style else {} + if raw is None: + #: ⛔⛔ A STYLE-ONLY CELL IS STORED ONLY IF ITS STYLE PAINTS, AND THAT ONE TEST IS + #: WORTH 26 MiB ON THE OWNER'S MODEL (MEASURED: 41.9 MiB before it, 15.6 after). + #: Excel stamps a number format down whole columns, so 148,327 blank cells + #: arrived carrying an accounting code and nothing else. A number format on an + #: empty cell formats NOTHING: there is no value to render, so the cell is + #: byte for byte invisible, and storing it is pure weight against a 16 MiB cap. + #: A FILL, A BORDER, AN INK OR A MARK is different: that is paint somebody can + #: see on an empty cell, and `sheets.CELL_KINDS`' `empty` exists to carry it. + paint = _painting(style) + if paint: + style_only[addr] = {"kind": "empty", "style": paint} + elif style: + #: ⛔ COUNTED AND SAID, NEVER SILENT (standing rule 1's second sentence). This + #: is a deliberate lossy decision, so it belongs in the DOCUMENT the person + #: keeps, not only in the notes of whoever wrote the importer. + counts["blank_styles"] += 1 + continue + if isinstance(raw, str) and raw.startswith("="): + counts["formulas"] += 1 + cell_out = {"kind": "formula", "state": "stale", + "formula": raw[:sheets._MAX_FORMULA]} + #: The cached reading, for the differential. Dropped before the save; see the + #: module note for why it is not parked in `source`. + cell_out["imported_value"] = json_value(cached.get(addr)) + cell_out["value"] = cell_out["imported_value"] + elif type(raw).__name__ in ("ArrayFormula", "DataTableFormula"): + counts["formulas"] += 1 + text = str(getattr(raw, "text", "") or "") + notes.add("an array formula was imported as an ordinary formula") + cell_out = {"kind": "formula", "state": "stale", + "formula": (text if text.startswith("=") else "=" + text + )[:sheets._MAX_FORMULA]} + cell_out["imported_value"] = json_value(cached.get(addr)) + cell_out["value"] = cell_out["imported_value"] + else: + value = json_value(raw) + cell_out = {"kind": "literal", "state": "typed", "value": value} + #: ⚠ ONLY A STRING KEEPS A `text`, and a number deliberately does not. `text` is + #: what a person TYPED; for a number the value is the content and a second copy + #: of it is about 0.5 MiB of duplication on the owner's model. + if isinstance(value, str): + cell_out["text"] = value[:sheets._MAX_TEXT] + if style: + cell_out["style"] = style + cells[addr] = cell_out + counts["cells"] += len(cells) + #: ⛔ THE CONTENT CELLS WIN THE CAP. A tab at the ceiling drops its decoration rather than + #: refusing the import, and says so, because a style-only cell is paint and a value is data. + room = sheets._MAX_CELLS_PER_SHEET - len(cells) + if room < len(style_only): + notes.add("this tab holds more cells than one sheet does, so " + + str(len(style_only) - max(0, room)) + " cells that carried only colour were " + "left out") + for addr, blank in list(style_only.items())[:max(0, room)]: + cells[addr] = blank + if counts["blank_styles"]: + notes.add("on " + str(counts["blank_styles"]) + " cells that hold no value, a number " + "format or a text style was not kept, because it shapes a value that is not " + "there") + return cells + + +def _validations_of(ws, cells, notes): + """C2's in-cell lists, applied to the cells a `dataValidation` covers.""" + try: + found = list(ws.data_validations.dataValidation) + except Exception: # noqa: BLE001 + return + for dv in found: + if str(getattr(dv, "type", "") or "") != "list": + notes.add("a " + str(getattr(dv, "type", "") or "cell") + " validation rule was not " + "imported, because a cell carries a list of choices here") + continue + formula = str(getattr(dv, "formula1", "") or "").strip() + if not (formula.startswith('"') and formula.endswith('"')): + notes.add("a dropdown that reads its choices from a range of cells was not imported") + continue + entries = [e.strip() for e in formula[1:-1].split(",") if e.strip()] + if not entries: + continue + addrs, cut = _spread(dv.sqref) + if cut: + notes.add("a dropdown covered more cells than one import carries, so it was applied " + "to the first " + str(_MAX_SPREAD) + " of them") + for addr in addrs: + cell = cells.get(addr) + if cell is None: + cell = {"kind": "empty"} + cells[addr] = cell + cell["validation"] = {"list": entries[:sheets._MAX_VALIDATION_ENTRIES]} + + +def _dxf_style(dxf, notes): + """What a conditional format's differential style repaints, as C2's rule style.""" + out = {} + if dxf is None: + return out + font = getattr(dxf, "font", None) + if font is not None: + if font.b: + out["bold"] = True + token = quantize(argb_of(font.color)) + if token and token != DEFAULT_INK: + out["color"] = token + fill = getattr(dxf, "fill", None) + if fill is not None: + #: ⚠ A DIFFERENTIAL FILL CARRIES ITS COLOUR ON `bgColor`, not on `fgColor`, which is the + #: opposite of an ordinary cell fill. Reading only `fgColor` here yields a rule that + #: paints nothing, with nothing red anywhere. + token = quantize(argb_of(getattr(fill, "bgColor", None))) \ + or quantize(argb_of(getattr(fill, "fgColor", None))) + if token and token != DEFAULT_FILL: + out["fill"] = token + if not out: + notes.add("a conditional format rule had no colour this model could carry") + return out + + +def _rules_of(ws, notes): + """C2's `cellIs` conditional rules for one tab, one rule per range it paints.""" + out = [] + try: + blocks = list(ws.conditional_formatting) + except Exception: # noqa: BLE001 + return out + for block in blocks: + for rule in list(getattr(block, "rules", []) or []): + kind = str(getattr(rule, "type", "") or "") + if kind != "cellIs": + notes.add("a " + (kind or "conditional") + " conditional format rule was not " + "imported, because a rule compares a cell to a value here") + continue + op = _RULE_OPS.get(str(getattr(rule, "operator", "") or "")) + if not op: + notes.add("the " + str(getattr(rule, "operator", "") or "unnamed") + " condition " + "has no equivalent here, so that rule was not imported") + continue + operands = [] + for raw in list(getattr(rule, "formula", []) or [])[:2]: + text = str(raw).strip().strip('"') + try: + operands.append(float(text)) + except ValueError: + operands.append(text) + style = _dxf_style(getattr(rule, "dxf", None), notes) + for part in str(getattr(block, "sqref", "") or "").split(): + rect = sheets._clean_range(part.replace("$", "").upper()) + if rect is None: + continue + row = {"range": rect, "op": op, "style": style} + if operands: + row["value"] = operands[0] + if len(operands) > 1: + row["value2"] = operands[1] + out.append(row) + if len(out) >= sheets._MAX_RULES: + notes.add("this tab holds more conditional format rules than one sheet " + "carries, so the rest were not imported") + return out + return out + + +def _charts_of(ws, tab_name, notes): + """C2's charts for one tab, with the rectangle their series READ (R15).""" + out = [] + for chart in list(getattr(ws, "_charts", []) or []): + kind = _CHART_KINDS.get(type(chart).__name__) + if not kind: + notes.add("a " + type(chart).__name__ + " chart has no equivalent here, so it was " + "not imported") + continue + rect = None + for series in list(getattr(chart, "series", []) or []): + refs = [] + for holder in (getattr(series, "val", None), getattr(series, "cat", None)): + for attr in ("numRef", "strRef", "multiLvlStrRef"): + node = getattr(holder, attr, None) if holder is not None else None + if node is not None and getattr(node, "f", None): + refs.append(str(node.f)) + for ref in refs: + named = sheet_of_ref(ref) + if named and named != tab_name: + #: ⛔ A SERIES THAT READS ANOTHER TAB CANNOT BE DRAWN AS A RECTANGLE ON THIS + #: ONE. Folding it in would give the chart a range that points at this tab's + #: cells, which is a picture of the wrong numbers. + notes.add("a chart series that reads another tab was not imported") + continue + piece = rect_of(ref) + if piece is None: + continue + rect = piece if rect is None else { + "col0": min(rect["col0"], piece["col0"]), + "row0": min(rect["row0"], piece["row0"]), + "col1": max(rect["col1"], piece["col1"]), + "row1": max(rect["row1"], piece["row1"])} + if rect is None: + notes.add("a chart whose series range could not be read was not imported") + continue + out.append({"range": rect, "kind": kind}) + notes.add("a chart keeps its data range but not its title, colours or placement") + return out + + +def _geometry_of(ws, notes): + """`(cols, rows, colWidths, freeze, hiddenRows, hiddenCols)` for one tab. + + ⛔⛔ HIDDEN LINES ARE STORED ONE-BASED, THE WAY A PERSON READS THEM: row 1 is `1` and column A + is `1`. Nothing in `sheet/types.ts` pinned a basis when this was written (`_clean_hidden` + admits any non negative whole number and says so), so this is the convention the importer + sets, and it is the one the address vocabulary already uses. ⚠ A CHART RECTANGLE IS STILL + ZERO-BASED, because `SheetChartSpec` says so; the two are different quantities and the + difference is stated here rather than discovered. + """ + cols = max(sheets.MIN_SHEET_COLS, min(sheets.MAX_SHEET_COLS, int(ws.max_column or 1))) + rows = max(sheets.MIN_SHEET_ROWS, min(sheets.MAX_SHEET_ROWS, int(ws.max_row or 1))) + widths, hidden_cols = {}, [] + for letter, dim in (ws.column_dimensions or {}).items(): + first, last = col_index(letter), col_index(letter) + if getattr(dim, "min", None) and getattr(dim, "max", None): + first, last = int(dim.min) - 1, int(dim.max) - 1 + if first < 0 or last - first > sheets.MAX_SHEET_COLS: + continue + px = width_px(getattr(dim, "width", None)) + for index in range(first, last + 1): + if index >= sheets.MAX_SHEET_COLS: + break + if px: + widths[_addr(index, 0).rstrip("0123456789")] = px + if getattr(dim, "hidden", False): + hidden_cols.append(index + 1) + hidden_rows = [] + for number, dim in (ws.row_dimensions or {}).items(): + if getattr(dim, "hidden", False) and isinstance(number, int) and number > 0: + hidden_rows.append(number) + if getattr(dim, "customHeight", False): + notes.add("a row height was not imported, because a row is one height here") + freeze = freeze_of(getattr(ws, "freeze_panes", "") or "") + if getattr(ws, "merged_cells", None) and list(ws.merged_cells.ranges): + notes.add("a merged cell was imported as its top left cell alone") + return cols, rows, widths, freeze, sorted(set(hidden_rows)), sorted(set(hidden_cols)) + + +def import_workbook(path, *, source="", progress=None): + """Read an .xlsx at `path` and return `{"workbook", "report"}`. Pure: no store, no session. + + `workbook` is `{"name", "sheets": [...]}` in the C1/C2 shape `sheets.put_workbook` accepts, + with every formula cell carrying `imported_value` for the caller's differential. + `report` is C4's `{cells, formulas, matched, mismatched, unsupported}` with the differential + legs left at zero, because only the caller can recompute a formula. + + ⚠ `progress(state, fraction)` IS CALLED FROM WHATEVER THREAD RUNS THIS. It must not raise and + must not block; the job's registry entry is the only thing it touches. + """ + import openpyxl + + def _say(state, fraction): + if progress: + try: + progress(state, fraction) + except Exception: # noqa: BLE001 + pass + + _say("reading", 0.02) + try: + formulas = openpyxl.load_workbook(path, data_only=False, read_only=False, + keep_links=False) + except Exception as exc: # noqa: BLE001 + raise ImportRefusal("import_unreadable", + "That file could not be read as a workbook. Save it again as .xlsx " + "and try once more.") from exc + _say("reading", 0.25) + try: + values = openpyxl.load_workbook(path, data_only=True, read_only=True, keep_links=False) + except Exception as exc: # noqa: BLE001 + raise ImportRefusal("import_unreadable", + "That file could not be read as a workbook. Save it again as .xlsx " + "and try once more.") from exc + + names = list(formulas.sheetnames)[:sheets._MAX_SHEETS] + if len(formulas.sheetnames) > sheets._MAX_SHEETS: + skipped = len(formulas.sheetnames) - sheets._MAX_SHEETS + names_note = str(skipped) + " tabs past the first " + str(sheets._MAX_SHEETS) + \ + " were not imported" + else: + names_note = "" + + counts = {"cells": 0, "formulas": 0} + book_notes = set() + if names_note: + book_notes.add(names_note) + stamp = datetime.now(timezone.utc).replace(microsecond=0).isoformat() + tabs = [] + total = max(1, len(names)) + for index, name in enumerate(names): + ws = formulas[name] + notes = set() + if str(getattr(ws, "sheet_state", "visible")) != "visible": + #: ⛔ A HIDDEN TAB HAS NO HOME IN `_clean_sheet`, which builds a fresh dict from the + #: keys it names, so a `hidden` key would be dropped on the first save with nothing + #: red anywhere. It is SHOWN and SAID rather than silently lost. + notes.add("this tab was hidden in the original file and is shown here") + _say("cells", 0.3 + 0.4 * (index / total)) + cached = {} + try: + source_ws = values[name] + for row in source_ws.iter_rows(): + for cell in row: + if cell.value is not None: + cached[cell.coordinate] = cell.value + except Exception: # noqa: BLE001 + notes.add("this tab's stored answers could not be read, so its formulas start unfilled") + cells = _cells_of(ws, cached, notes, counts) + _say("formats", 0.7 + 0.25 * (index / total)) + _validations_of(ws, cells, notes) + cols, rows, widths, freeze, hidden_rows, hidden_cols = _geometry_of(ws, notes) + tab = {"id": "", "name": name[:sheets._MAX_NAME], "cols": cols, "rows": rows, + "cells": cells} + if widths: + tab["colWidths"] = widths + if freeze: + tab["freeze"] = freeze + rules = _rules_of(ws, notes) + if rules: + tab["rules"] = rules + if hidden_rows: + tab["hiddenRows"] = hidden_rows + if hidden_cols: + tab["hiddenCols"] = hidden_cols + charts = _charts_of(ws, name, notes) + if charts: + tab["charts"] = charts + tab["imported"] = {"at": stamp, "source": source[:sheets._MAX_NAME], + "unsupported": _note_list(notes)} + book_notes.update(notes) + tabs.append(tab) + + try: + values.close() + except Exception: # noqa: BLE001 + pass + #: ⭐ THE FONT NOTE IS WORKBOOK-WIDE AND UNCONDITIONAL, because the answer is the same on + #: every file: the app is one typeface, so no imported font survives and the reader is told + #: once rather than per tab. + book_notes.add("every font was replaced by the app's own, which is the one typeface it uses") + + name = str(source or "").rsplit(".", 1)[0] or "Imported workbook" + return { + "workbook": {"name": name[:sheets._MAX_NAME], "sheets": tabs}, + "report": {"cells": counts["cells"], "formulas": counts["formulas"], + "matched": 0, "mismatched": [], "unsupported": _note_list(book_notes)}, + } + + +def take_imported_values(book): + """Pull every `imported_value` off the document and return `{(tab, addr): cached}`. + + ⛔⛔ IT REMOVES THE KEY AS IT READS IT, AND THAT IS THE POINT. `clean_cell` would drop the key + on save anyway, so leaving it behind would not corrupt anything; it would simply mean the + document held in memory during the job does not match the one that comes back out of the + store, and the differential would then be run against a copy nobody can reproduce. + """ + out = {} + for tab in (book or {}).get("sheets") or (): + tab_name = str(tab.get("name") or "") + for addr, cell in (tab.get("cells") or {}).items(): + if isinstance(cell, dict) and "imported_value" in cell: + out[(tab_name, addr)] = cell.pop("imported_value") + return out + + +def differential(book, cached, *, limit=MAX_MISMATCHED): + """`{matched, mismatched, compared}` for a RECOMPUTED workbook against its cached readings. + + ⛔⛔ THE DENOMINATOR IS THE CELLS THAT CARRIED A USABLE CACHED VALUE, NOT EVERY FORMULA, and + the difference is 117 cells on the owner's model. A formula Excel never cached has nothing to + be right or wrong against, so counting it as a mismatch would report a failure of ours where + the file simply held no answer, and counting it as a match would be worse. + """ + matched, mismatched, compared = 0, [], 0 + for tab in (book or {}).get("sheets") or (): + tab_name = str(tab.get("name") or "") + for addr, cell in (tab.get("cells") or {}).items(): + if not isinstance(cell, dict) or cell.get("kind") != "formula": + continue + key = (tab_name, addr) + if key not in cached: + continue + want = cached[key] + if want is None: + continue + compared += 1 + got = cell.get("value") + if values_match(got, want): + matched += 1 + elif len(mismatched) < limit: + mismatched.append({"addr": addr, "tab": tab_name, + "kind": mismatch_kind(got, want)}) + else: + mismatched.append(None) + shown = [m for m in mismatched if m is not None] + return {"matched": matched, "mismatched": shown, "compared": compared, + "mismatched_total": len(mismatched)} diff --git a/platform/core/sheets.py b/platform/core/sheets.py index c4765d8f9b4e6b8bd4148d8f98396067f935e745..6532f433ae4e25c8d47d287566bd58006ea07618 100644 --- a/platform/core/sheets.py +++ b/platform/core/sheets.py @@ -7,22 +7,29 @@ WHAT GOES HERE: document, its `rev`, and the CELL VOCABULARY that every later Sheet ticket consumes. It resolves nothing: no aggregate, no formula, no permission decision. -⭐ **THE VOCABULARY IS FROZEN HERE AND `verify_api.py` PROVES THE CLIENT AGREES.** `CELL_KINDS` and +⭐ **THE VOCABULARY IS FROZEN HERE AND TWO GATES PROVE THE CLIENT AGREES.** `CELL_KINDS` and `CELL_STATES` are the whole of it, name for name, and `web/src/sheet/types.ts` carries the same two -lists. A parity check compares them so the two halves cannot drift; adding a name on one side only -is what that check exists to catch. +lists. `verify_api.py` compares them and `verify_sheet.py` section 1 diffs the WHOLE wave-51 +vocabulary both ways, so the two halves cannot drift; adding a name on one side only is what those +checks exist to catch. + +⭐⭐ **WAVE 51 AMENDS THE VOCABULARY (contract C2, W51-T21), AND EVERY AMENDMENT IS PAIRED.** +`CELL_KINDS` gains `empty` (a cell that carries a style and nothing else), `CELL_FORMAT_KINDS` +gains `code` (a custom number format, which is what an imported accounting format arrives as), a +style gains `valign` / `wrap` / `indent` / `size` (R8's Alignment group), a cell gains +`validation`, and a tab gains `rules` / `hiddenRows` / `hiddenCols` / `imported`. Each of those +names must appear in `sheet/types.ts` too, or `verify_sheet.py` goes red by family. ⛔ **THERE IS NO `chart` KIND, AND ADDING ONE IS A CONTRACT CHANGE, NOT A CONVENIENCE.** W49-T08 stores a chart as a sibling `charts:[{range, anchor, kind}]` array on the SHEET, precisely so a chart never has to pretend to be a cell. Only the ROOT may amend C1. -⛔⛔ **AND `charts` DOES NOT SURVIVE A SAVE TODAY (found by W50-T20, booked, NOT fixed here).** -`_clean_sheet` builds a FRESH dict from the keys it names, so every unnamed key on a tab is -dropped by the ordinary PUT path: a chart created by W49-T08 is gone on the next reload. A2's four -geometry keys are named below precisely because of that rule. Fixing `charts` means writing a -`_clean_charts` allow-list of its own (id, range corners, kind) and shifting a chart's range on a -structural insert, which is W49-T08's surface rather than this ticket's; it is booked with a -testable exit condition instead of half done here. +⭐⭐ **`charts` NOW SURVIVES A SAVE (D-640, fixed by W51-T21; it did NOT before).** `_clean_sheet` +builds a FRESH dict from the keys it names, so every unnamed key on a tab was dropped by the +ordinary PUT path and a chart created by W49-T08 was gone on the next reload. `_clean_charts` +below is the allow-list that keeps it: id, the four range corners, and the kind. ⚠ WHAT IS STILL +NOT DONE is shifting a chart's range on a structural insert; that is W49-T08's surface and stays +booked. A2's four geometry keys are named below for the same fresh-dict reason. ⭐ **WHY A PER-WORKBOOK DOCUMENT NEEDS AN INDEX.** C1 names the document key, which makes a workbook cheap to read and cheap to write without touching its neighbours. It also means nothing @@ -54,26 +61,80 @@ WORKBOOK_KEY_PREFIX = "sheet_workbook_" #: The companion pointer list. See the module note for why a per-document key needs one. INDEX_KEY = "sheet_workbooks" -#: ⛔ THE FROZEN VOCABULARY (contract C1). `verify_api.py` asserts `web/src/sheet/types.ts` carries -#: exactly these, name for name. -CELL_KINDS = ("literal", "formula", "bound") +#: ⛔ THE FROZEN VOCABULARY (contract C1, amended by C2). `verify_api.py` and `verify_sheet.py` +#: assert `web/src/sheet/types.ts` carries exactly these, name for name. +#: +#: ⭐ `empty` IS C2's STYLE ONLY CELL, and it is a KIND rather than a flag because every other way +#: of saying it lies: a `literal` with no text claims something was typed, and a cell absent from +#: the map cannot carry a fill. A person who paints an empty cell yellow has made a real edit and +#: the document has to be able to hold it. +CELL_KINDS = ("literal", "formula", "bound", "empty") CELL_STATES = ("fresh", "stale", "typed", "refused") #: A literal is ALWAYS this state (R19). Stated once, here, so no caller has to remember it. +#: ⚠ AN `empty` CELL TAKES THE SAME STATE, deliberately: it holds no binding, so `stale` would say +#: a refresh is owed for a value that does not exist, and a reader counting stale cells would +#: count decoration. Nothing computed it, nothing can refresh it, so it reads as hand made. LITERAL_STATE = "typed" -#: ⛔ A1 (wave 50, W50-T19). The NUMBER FORMATS a cell may carry. `web/src/sheet/types.ts` holds -#: the same list and `verify_api.py` compares the two, exactly as it does for kinds and states. -CELL_FORMAT_KINDS = ("general", "number", "currency", "percent", "date") +#: The kinds that hold no value of their own, and therefore take `LITERAL_STATE`. +_TYPED_KINDS = ("literal", "empty") + +#: ⛔ A1 (wave 50, W50-T19), extended by C2 (wave 51, W51-T21). The NUMBER FORMATS a cell may +#: carry. `web/src/sheet/types.ts` holds the same list and both gates compare the two, exactly as +#: they do for kinds and states. +#: +#: ⭐⭐ `code` IS THE ONE C4 CANNOT SHIP WITHOUT. 49% of the owner's real treasury model uses an +#: accounting format, which arrives from openpyxl as a format CODE and not as one of the four +#: named kinds. Without this name every imported cell's format hits `cell_format_kind_unknown` and +#: the whole import REFUSES, so the trap is not a missing decoration, it is a save that fails. +CELL_FORMAT_KINDS = ("general", "number", "currency", "percent", "date", "code") #: The three horizontal alignments. Mirrored in `types.ts::CELL_ALIGNS`. CELL_ALIGNS = ("left", "center", "right") -#: The style keys A1 names. Anything else is DROPPED, in silence and on purpose; see +#: C2 / R8's vertical alignments and the four font steps. Mirrored in `types.ts`. +CELL_VALIGNS = ("top", "middle", "bottom") +CELL_SIZES = ("s", "m", "l", "xl") + +#: The style keys A1 and C2 name. Anything else is DROPPED, in silence and on purpose; see #: `_clean_style` for why that is not the same decision as an unknown `format.kind`. _STYLE_MARKS = ("bold", "italic", "underline") _BORDER_SIDES = ("top", "right", "bottom", "left") +#: R8's indent, in steps rather than pixels: a stored pixel count would be a layout decision that +#: outlives every layout change, exactly as a stored hex outlives a palette. +_MAX_INDENT = 8 + +#: C2's custom format code. ⚠ THE CAPS ARE PART OF THE VOCABULARY, not a guess: a format code is +#: interpreted by the client's formatter, so an unbounded one is an unbounded parse, and Excel's +#: own grammar holds at most four sections (positive; negative; zero; text). +_MAX_FORMAT_CODE = 64 +_MAX_FORMAT_SECTIONS = 4 + +#: C2's in-cell list validation. The cap is on ENTRIES; the whole document still meets the byte cap. +_MAX_VALIDATION_ENTRIES = 200 +_MAX_VALIDATION_ENTRY = 200 + +#: ⛔ C2's TEN conditional format operators, spelled once. An op outside this list is REFUSED by +#: name for `_clean_format`'s reason: a rule with an operator nothing can evaluate never fires, so +#: dropping it would leave a person looking at a rule they believe is painting their sheet. +SHEET_RULE_OPS = ("gt", "lt", "gte", "lte", "eq", "neq", "between", "contains", "empty", + "notEmpty") + +#: The style keys a conditional format rule may repaint. A rule is a PAINT, never a format: it +#: cannot change how a number reads, so it carries no `format`. +_RULE_STYLE_MARKS = ("bold",) +_RULE_STYLE_COLOURS = ("fill", "color") + +#: The chart kinds W49-T08 draws. Mirrored in `types.ts::SheetChartSpec`. +SHEET_CHART_KINDS = ("bar", "line", "area", "donut") + +_MAX_RULES = 100 +_MAX_HIDDEN = 5000 +_MAX_CHARTS = 50 +_MAX_UNSUPPORTED = 200 + #: A colour is a `--lp-*` TOKEN NAME, not a hue. Hex is allowed so a future palette door is not #: locked out, but nothing free form reaches a canvas `fillStyle` from a stored document. _COLOUR = re.compile(r"^[A-Za-z0-9#_-]{1,40}$") @@ -110,16 +171,40 @@ _MAX_TEXT = 4000 _MAX_FORMULA = 4000 _MAX_DISPLAY = 400 _MAX_SHEETS = 50 -_MAX_CELLS_PER_SHEET = 20000 + +#: ⭐⭐ R4 / AMENDMENT A1 (wave 51, W51-T22). THE CAPS FIT THE MODEL, and the model is the owner's +#: real treasury workbook: 58,083 populated cells with its largest tab at 42,148, which the wave-49 +#: figure of 20,000 refused outright. 100,000 leaves that tab room to grow and still sits far below +#: the byte cap, which is the one that actually binds. +#: +#: ⛔ DO NOT CROSS THIS WITH `MAX_SHEET_ROWS = 100000` ABOVE. They are the same digits and +#: different quantities: that one is how many ROWS a tab may address, this one is how many of its +#: cells may hold something. A tab at the row ceiling with one cell filled is one cell. +_MAX_CELLS_PER_SHEET = 100_000 #: A client may not park an unbounded blob in the tenant store. A BYTE CAP is not interpretation: #: it never looks at a key, only at the serialized length. Mirrors `chart_system.MAX_CONFIG_BYTES`. -MAX_WORKBOOK_BYTES = 4 * 1024 * 1024 +#: +#: ⭐⭐ 16 MiB IS THE BINDING CAP (A1), and it is the reason the grill's 500,000-cell figure is +#: unreachable: the recalc prototype measured 89 B for a BARE cell, so 16 MiB is about 150,000 +#: styled cells and the byte cap runs out first on any real workbook. The wave-49 figure of 4 MiB +#: refused the owner's 4.92 MB model on every save, so the module could not hold its own use case. +#: +#: ⚠ IT IS NOT ONLY THE DOCUMENT CAP. `clean_cell` runs `_json_safe` over a cell's `value`, +#: `binding`, `source` and `refusal` too, so raising this raises the per-value ceiling with it. +#: That is harmless (a single value at the cap would fail the document check one line later) but +#: it is not obvious from the name. +MAX_WORKBOOK_BYTES = 16 * 1024 * 1024 #: A stored address is plain A1 with no `$`. Anchoring is a property of a FORMULA's text, not of #: the cell it lands in, so a `$` here would be a second way to say the same thing. _ADDR = re.compile(r"^[A-Z]{1,3}[1-9][0-9]{0,6}$") +#: A stored RANGE, which is what a conditional format rule paints over. `A1` alone is the one cell +#: range and is normalized to `A1:A1`, so every stored rule reads the same way and no consumer has +#: to carry two shapes. +_RANGE = re.compile(r"^([A-Z]{1,3}[1-9][0-9]{0,6}):([A-Z]{1,3}[1-9][0-9]{0,6})$") + _ID_CLEAN = re.compile(r"[^a-z0-9_-]+") @@ -136,6 +221,26 @@ class SheetRefusal(Exception): self.message = message +class SheetStaleRefusal(SheetRefusal): + """C3's stale-revision refusal, carrying the revision that IS live. + + ⭐⭐ THE SHAPE IS COPIED, NOT INVENTED. `view_audit.ViewRevisionStale` already carries + `rev_current` and `main.py::_view_revision_stale` already answers it as + `{"error": {"code", "message", "rev_current"}}`, so a Sheet 409 arrives in the shape the app + already has rather than a second one. + + ⛔ IT IS A DIFFERENT CODE FROM `put_workbook`'s `workbook_revision_stale` AND THAT IS + DELIBERATE. The PUT door replaces a whole workbook and its client reloads the workbook; the + PATCH door replaces a range inside ONE TAB and its client reloads that tab. The two recoveries + are different, so the two refusals are named differently and the existing PUT branch in the + client keeps working untouched. + """ + + def __init__(self, code, message, rev_current=0): + super().__init__(code, message) + self.rev_current = int(rev_current or 0) + + def _now(): return datetime.now(timezone.utc).replace(microsecond=0).isoformat() @@ -184,6 +289,23 @@ def _persist(st, key, mutate, seed=None): return result.get("value") +def _mb(byte_count): + """A byte count as MB with one decimal, because a person cannot read 16777216. + + ⚠ IT IS DIGITS ON PURPOSE (R16, and W51-T22's done-when). "larger than the store accepts" told + the reader nothing they could act on: they could not tell whether they were 2% over or ten + times over, and therefore could not tell whether deleting a tab would help. + """ + return "%.1f MB" % (float(byte_count) / (1024.0 * 1024.0)) + + +def _too_many_cells_message(count): + """The sentence a tab over `_MAX_CELLS_PER_SHEET` wears. Names the COUNT and the CAP.""" + return ("That sheet holds " + str(int(count)) + " cells and one sheet holds at most " + + str(_MAX_CELLS_PER_SHEET) + ", so it cannot be saved. Delete some cells or move " + "them onto another tab.") + + def _json_safe(payload, what): """Strictly JSON-serializable and under the byte cap, or a named refusal. @@ -195,13 +317,49 @@ def _json_safe(payload, what): except (TypeError, ValueError): raise SheetRefusal("workbook_not_serializable", "That " + what + " holds a value the store cannot save.") - if len(blob.encode("utf-8")) > MAX_WORKBOOK_BYTES: - raise SheetRefusal("workbook_too_large", - "That workbook is larger than the tenant store accepts.") + size = len(blob.encode("utf-8")) + if size > MAX_WORKBOOK_BYTES: + raise SheetRefusal( + "workbook_too_large", + "That " + what + " is " + _mb(size) + " and the tenant store holds at most " + + _mb(MAX_WORKBOOK_BYTES) + ", so it cannot be saved. Delete some cells or move " + "them into a second workbook.") return payload -# ── the cell STYLE (A1, wave 50, W50-T19) ──────────────────────────────────────────────────── +# ── the cell STYLE (A1, wave 50, W50-T19; C2, wave 51, W51-T21) ────────────────────────────── + +def _clean_format_code(raw): + """C2's CUSTOM number format code, or a named refusal. Never dropped, never truncated. + + ⛔⛔ A TRUNCATED FORMAT CODE IS A WRONG NUMBER ON A SCREEN, which is why every rule here + refuses rather than repairs. `#,##0.00;(#,##0.00)` cut at its semicolon stops showing negatives + in brackets and nobody is told; a code with one quote left open swallows the rest of itself and + formats as literal text. Both read as a plausible number, and that is the one class of defect + a gate downstream cannot see. + + The three rules are Excel's own, restated: at most 64 characters, at most four sections + (positive; negative; zero; text) split on `;`, and every double quote closed. + """ + code = str(raw if raw is not None else "").strip() + if not code: + raise SheetRefusal("cell_format_code_missing", + "A custom number format needs a format code.") + if len(code) > _MAX_FORMAT_CODE: + raise SheetRefusal( + "cell_format_code_too_long", + "A custom number format code holds at most " + str(_MAX_FORMAT_CODE) + + " characters, so this one cannot be saved.") + if len(code.split(";")) > _MAX_FORMAT_SECTIONS: + raise SheetRefusal( + "cell_format_code_too_many_sections", + "A custom number format holds at most " + str(_MAX_FORMAT_SECTIONS) + + " sections separated by a semicolon.") + if code.count('"') % 2: + raise SheetRefusal("cell_format_code_unbalanced", + "A custom number format code has a quote that was never closed.") + return code + def _clean_format(raw): """The number format, or None. An unknown `kind` is REFUSED, never dropped. @@ -230,6 +388,9 @@ def _clean_format(raw): if kind == "general": return None + if kind == "code": + return {"kind": "code", "code": _clean_format_code(raw.get("code"))} + out = {"kind": kind} decimals = raw.get("decimals") if isinstance(decimals, bool): @@ -274,6 +435,27 @@ def _clean_style(raw): if align in CELL_ALIGNS: out["align"] = align + #: C2 / R8's Alignment group. ⚠ EACH ONE STORES ITS DEFAULT AS AN ABSENCE, for the falsey mark + #: reason above: `wrap: false`, `indent: 0` and the middle font step are what every cell + #: already is, so writing them would make a cell that was indented and un indented compare + #: unequal to the cell it started as. + valign = _text(raw.get("valign"), 12) + if valign in CELL_VALIGNS: + out["valign"] = valign + + if raw.get("wrap") is True: + out["wrap"] = True + + indent = raw.get("indent") + if not isinstance(indent, bool) and isinstance(indent, (int, float)): + steps = max(0, min(_MAX_INDENT, int(indent))) + if steps: + out["indent"] = steps + + size = _text(raw.get("size"), 4) + if size in CELL_SIZES and size != "m": + out["size"] = size + fmt = _clean_format(raw.get("format")) if fmt: out["format"] = fmt @@ -289,6 +471,33 @@ def _clean_style(raw): # ── the cell ───────────────────────────────────────────────────────────────────────────────── +def _clean_validation(raw): + """C2's in-cell list validation `{list: [...]}`, or None when nothing survives. + + ⚠ THE LIST IS CLAMPED, NOT REFUSED, and that is the opposite decision from a format code one + screen up. A validation list is an AID: 200 entries or 500, the cell still shows the value it + holds and every entry beyond the cap is one nobody could have found in a dropdown anyway. A + format code changes what a number READS AS, which is why that one refuses. + """ + if raw is None: + return None + if not isinstance(raw, dict): + raise SheetRefusal("cell_validation_invalid", "A cell validation must be an object.") + items = raw.get("list") + if not isinstance(items, list): + return None + out, seen = [], set() + for item in items[:_MAX_VALIDATION_ENTRIES]: + if isinstance(item, (dict, list)): + continue + value = _text(item, _MAX_VALIDATION_ENTRY) + if not value or value in seen: + continue + seen.add(value) + out.append(value) + return {"list": out} if out else None + + def clean_cell(raw, addr=""): """Normalize ONE cell, or raise `SheetRefusal` with a named code. @@ -309,17 +518,30 @@ def clean_cell(raw, addr=""): "cell_kind_unknown", "A cell kind must be one of " + ", ".join(CELL_KINDS) + ".") - state = _text(raw.get("state"), 40) or ("typed" if kind == "literal" else "stale") + state = _text(raw.get("state"), 40) or (LITERAL_STATE if kind in _TYPED_KINDS else "stale") if state not in CELL_STATES: raise SheetRefusal( "cell_state_unknown", "A cell state must be one of " + ", ".join(CELL_STATES) + ".") - if kind == "literal": + if kind in _TYPED_KINDS: state = LITERAL_STATE cell = {"kind": kind, "state": state} + #: ⭐ C2's STYLE ONLY CELL. `empty` says the cell holds no content, so nothing that would BE + #: content is carried out of here, whatever arrived. It is DROPPED rather than refused on + #: purpose: a client that clears a cell and leaves `text: ""` behind has done nothing wrong, + #: and refusing would 400 a whole workbook save over a blank string. + if kind == "empty": + style = _clean_style(raw.get("style")) + if style: + cell["style"] = style + validation = _clean_validation(raw.get("validation")) + if validation: + cell["validation"] = validation + return cell + if raw.get("text") is not None: cell["text"] = _text(raw.get("text"), _MAX_TEXT) if raw.get("formula") is not None: @@ -344,6 +566,11 @@ def clean_cell(raw, addr=""): if raw.get("refreshed_at") is not None: cell["refreshed_at"] = _text(raw.get("refreshed_at"), 120) + #: C2: the in-cell list. Normalized before the style so a refusing style still reports first. + validation = _clean_validation(raw.get("validation")) + if validation: + cell["validation"] = validation + #: A1: the style slot. It is normalized last because `_clean_format` can REFUSE, and a #: refusal that fires after every other key has been read names the whole cell it came from. style = _clean_style(raw.get("style")) @@ -359,8 +586,7 @@ def _clean_cells(raw, sheet_name=""): if not isinstance(raw, dict): raise SheetRefusal("cells_not_an_object", "A sheet's cells must be an object.") if len(raw) > _MAX_CELLS_PER_SHEET: - raise SheetRefusal("sheet_too_many_cells", - "That sheet holds more cells than one sheet accepts.") + raise SheetRefusal("sheet_too_many_cells", _too_many_cells_message(len(raw))) out = {} for addr, cell in raw.items(): key = _text(addr, 12).upper() @@ -439,13 +665,193 @@ def _clean_freeze(raw, cols, rows): return out +# ── the tab's C2 STRATA: rules, hidden lines, charts and the import record ─────────────────── +# +# ⛔⛔ NOTHING IN THIS TREE PINNED THE SHAPE OF A RULE'S `range` WHEN THIS WAS WRITTEN +# (2026-09-03, checked across `sheet/types.ts`, the wave-51 board and every importer). The only +# `range` that exists is the CHART's zero-based `{col0,row0,col1,row1}` rectangle, and an importer +# naturally produces the A1 string `B2:D40` instead. So this accepts BOTH and stores ONE: the +# chart's rectangle, because it is the shape already on the wire and a stored document with two +# spellings of the same rectangle is a document every later reader has to branch on. +# +# ⚠ A MALFORMED RANGE IS DROPPED, NOT REFUSED, and the split from the unknown `op` beside it is +# deliberate. C2 NAMES the ten ops, so an eleventh is a request this server understands well +# enough to know it cannot serve. C2 names no range GRAMMAR at all, so refusing one would be +# refusing a whole workbook save on a guess about a peer that is not built yet. + + +def _col_index(letters): + """`A` -> 0, `Z` -> 25, `AA` -> 26. The zero-based column the chart rectangle counts in.""" + n = 0 + for ch in letters: + n = n * 26 + (ord(ch) - 64) + return n - 1 + + +def _clean_range(raw): + """A rule's rectangle, or None. Accepts `"B2:D40"`, `"B2"` and `{col0,row0,col1,row1}`.""" + if isinstance(raw, str): + text = raw.strip().upper().replace("$", "") + if ":" not in text: + text = text + ":" + text + found = _RANGE.match(text) + if not found: + return None + corners = [] + for part in (found.group(1), found.group(2)): + letters = "".join(c for c in part if c.isalpha()) + digits = "".join(c for c in part if c.isdigit()) + corners.append((_col_index(letters), int(digits) - 1)) + (c0, r0), (c1, r1) = corners + return {"col0": min(c0, c1), "row0": min(r0, r1), + "col1": max(c0, c1), "row1": max(r0, r1)} + if isinstance(raw, dict): + out = {} + for key in ("col0", "row0", "col1", "row1"): + value = raw.get(key) + if isinstance(value, bool) or not isinstance(value, (int, float)): + return None + out[key] = max(0, int(value)) + if out["col1"] < out["col0"] or out["row1"] < out["row0"]: + return None + return out + return None + + +def _clean_rule_style(raw): + """What a rule REPAINTS: a fill, an ink and bold. Never a format (see `SHEET_RULE_OPS`).""" + if not isinstance(raw, dict): + return {} + out = {} + for key in _RULE_STYLE_COLOURS: + token = _text(raw.get(key), 40) + if token and _COLOUR.match(token): + out[key] = token + for mark in _RULE_STYLE_MARKS: + if raw.get(mark) is True: + out[mark] = True + return out + + +def _clean_rules(raw): + """C2's conditional format rules for one tab, at most `_MAX_RULES` of them. + + ⛔ AN OP OUTSIDE `SHEET_RULE_OPS` IS REFUSED BY NAME, for `_clean_format`'s reason: a rule + whose operator nothing can evaluate never fires, so dropping it would leave a person looking + at a sheet they believe is painted by a rule that is not there. + + ⚠ THE COUNT IS CLAMPED rather than refused: the rules past the cap are ones nobody could see + the effect of, and refusing would make a sheet that can never be saved again. + """ + if raw is None: + return [] + if not isinstance(raw, list): + raise SheetRefusal("sheet_rules_not_a_list", "A sheet's rules must be a list.") + out = [] + for row in raw[:_MAX_RULES]: + if not isinstance(row, dict): + continue + op = _text(row.get("op"), 20) + if op not in SHEET_RULE_OPS: + raise SheetRefusal( + "sheet_rule_op_unknown", + "A sheet rule condition must be one of " + ", ".join(SHEET_RULE_OPS) + ".") + rect = _clean_range(row.get("range")) + if rect is None: + continue + rule = {"id": _text(row.get("id"), _MAX_ID) or uuid.uuid4().hex[:12], + "range": rect, "op": op, "style": _clean_rule_style(row.get("style"))} + #: ⚠ `empty` and `notEmpty` take NO operand, and carrying one would store a rule whose + #: text says it compares against something it can never read. + if op not in ("empty", "notEmpty"): + for key in ("value", "value2"): + if row.get(key) is not None: + rule[key] = _json_safe(row.get(key), "sheet rule value") + out.append(rule) + return out + + +def _clean_hidden(raw, what): + """`hiddenRows` / `hiddenCols`: whole numbers, deduped and sorted, at most `_MAX_HIDDEN`. + + ⚠ THE BASIS IS THE CLIENT'S AND THIS FUNCTION DOES NOT SECOND GUESS IT. Nothing in the tree + pinned whether a hidden line is counted from 0 or from 1 when this was written, and a server + that rejected `0` would silently refuse to hide column A under a zero-based client. So it + admits every non negative whole number and stores it unchanged; the two halves agree on the + basis, or `verify_sheet.py` section 1 says so. + """ + if raw is None: + return [] + if not isinstance(raw, list): + raise SheetRefusal("sheet_hidden_not_a_list", + "A sheet's hidden " + what + " must be a list.") + seen = set() + for item in raw[:_MAX_HIDDEN]: + if isinstance(item, bool) or not isinstance(item, (int, float)): + continue + line = int(item) + if line >= 0: + seen.add(line) + return sorted(seen) + + +def _clean_charts(raw): + """D-640: the allow-list that lets a chart SURVIVE a save. + + ⛔⛔ WITHOUT THIS FUNCTION A CHART IS GONE ON THE NEXT RELOAD, and nothing goes red: the sheet + saves, the document is valid, and the picture the person made is simply not in it. + `_clean_sheet` returns a fresh dict, so a tab key that is not named here is dropped. + """ + if raw is None: + return [] + if not isinstance(raw, list): + raise SheetRefusal("sheet_charts_not_a_list", "A sheet's charts must be a list.") + out = [] + for row in raw[:_MAX_CHARTS]: + if not isinstance(row, dict): + continue + kind = _text(row.get("kind"), 20) + rect = _clean_range(row.get("range")) + if kind not in SHEET_CHART_KINDS or rect is None: + continue + out.append({"id": _text(row.get("id"), _MAX_ID) or uuid.uuid4().hex[:12], + "range": rect, "kind": kind}) + return out + + +def _clean_imported(raw): + """C4's import record: when, from what, and WHAT DID NOT SURVIVE. + + ⭐⭐ `unsupported` IS THE HALF THAT MATTERS AND IT IS STANDING RULE 1's SECOND SENTENCE. An + importer that quietly drops a pivot, a macro or a chart type it cannot draw hands back a + workbook that looks complete and is not. The list travels with the document so the app can + say what was left behind, months after the import. + """ + if raw is None: + return None + if not isinstance(raw, dict): + raise SheetRefusal("sheet_imported_invalid", "A sheet's import record must be an object.") + out = {"at": _text(raw.get("at"), 120), "source": _text(raw.get("source"), _MAX_NAME)} + items = raw.get("unsupported") + notes = [] + if isinstance(items, list): + for item in items[:_MAX_UNSUPPORTED]: + if isinstance(item, (dict, list)): + continue + note = _text(item, 200) + if note: + notes.append(note) + out["unsupported"] = notes + return out if (out["at"] or out["source"] or notes) else None + + def _clean_sheet(raw, index=0): - """ONE tab: identity, cells, and A2's geometry. + """ONE tab: identity, cells, A2's geometry and C2's strata. ⛔ EVERY KEY THIS FUNCTION DOES NOT NAME IS DROPPED, and that is worth knowing before adding one: the return below is a fresh dict, not an amended copy of `raw`. A2's four geometry keys - are named here for exactly that reason. See the module's own note on `charts`, which is - dropped today by the same rule. + and C2's five strata are named here for exactly that reason, and `charts` is named because it + was the one this rule silently ate until W51-T21 (D-640). """ if not isinstance(raw, dict): raise SheetRefusal("sheet_not_an_object", "A sheet must be an object.") @@ -467,6 +873,22 @@ def _clean_sheet(raw, index=0): freeze = _clean_freeze(raw.get("freeze"), cols, rows) if freeze: sheet["freeze"] = freeze + #: C2's five strata. Each is written only when it holds something, for `_clean_style`'s + #: reason: a tab with no rules and a tab with `rules: []` read identically, so one of them is + #: what gets stored and a reload compares equal to the thing it saved. + rules = _clean_rules(raw.get("rules")) + if rules: + sheet["rules"] = rules + for key, what in (("hiddenRows", "rows"), ("hiddenCols", "columns")): + hidden = _clean_hidden(raw.get(key), what) + if hidden: + sheet[key] = hidden + charts = _clean_charts(raw.get("charts")) + if charts: + sheet["charts"] = charts + imported = _clean_imported(raw.get("imported")) + if imported: + sheet["imported"] = imported return sheet @@ -574,6 +996,177 @@ def put_workbook(st, workbook_id, raw, expect_rev=None): return saved +# ── C3: ONE TAB AT A TIME, and the range PATCH (wave 51, W51-T22) ──────────────────────────── +# +# ⭐⭐ WHY A SECOND WRITE DOOR EXISTS AT ALL. `put_workbook` sends the WHOLE document on every +# commit, and A1 raised the ceiling to 16 MiB, so a person typing into the owner's treasury model +# would upload 5 MB per keystroke commit and the tab they are not looking at would ride along with +# it. C3's answer is a door whose payload is the range that changed: the client sends the dirty +# addresses and the `rev` it read, and structure (adding a tab, resizing, freezing) keeps going +# through PUT because that is a whole-document change and honestly is one. + + +def _tab_index(tabs, tab_ref): + """Where `tab_ref` lives in `tabs`, matched on `id` first and then on `name`, or None. + + ⚠ `id` FIRST, AND THE ORDER IS LOAD BEARING. Two tabs may legally share a name (nothing in + `_clean_sheet` dedupes one) and no two may share an id, so resolving a name first would let a + rename decide which tab a save lands in. The name fallback exists because a tab is addressed by + the thing a person can see when a client has not read the document yet. + """ + key = str(tab_ref if tab_ref is not None else "").strip() + if not key: + return None + for i, tab in enumerate(tabs): + if isinstance(tab, dict) and str(tab.get("id") or "") == key: + return i + for i, tab in enumerate(tabs): + if isinstance(tab, dict) and str(tab.get("name") or "") == key: + return i + folded = key.casefold() + for i, tab in enumerate(tabs): + if isinstance(tab, dict) and str(tab.get("name") or "").casefold() == folded: + return i + return None + + +def find_tab(book, tab_ref): + """ONE tab of a workbook, or a named refusal. C3's `GET /sheets/{id}/tabs/{tab}`.""" + tabs = list((book or {}).get("sheets") or []) + at = _tab_index(tabs, tab_ref) + if at is None: + raise SheetRefusal("tab_missing", + "Tab " + (str(tab_ref) or "(unnamed)") + " is not in this workbook.") + return tabs[at] + + +def workbook_meta(book): + """The workbook WITHOUT any cells, for C3's `?tabs=meta`. + + ⭐ THE IDENTITIES STAY AND ONLY `cells` GOES. A tab rail has to name its tabs, and the geometry, + the freeze, the widths and the strata are what the grid needs to draw an empty tab before its + contents arrive; dropping them would make the meta read useless and the client would go + straight back to fetching everything. + + ⭐ `cellCount` REPLACES the map it removes. Without it a client that opens one tab has no way + to say how close the workbook is to `_MAX_CELLS_PER_SHEET` short of loading every tab, which is + the exact fetch this door exists to avoid. + """ + meta = {k: v for k, v in (book or {}).items() if k != "sheets"} + tabs = [] + for tab in (book or {}).get("sheets") or (): + if not isinstance(tab, dict): + continue + thin = {k: v for k, v in tab.items() if k != "cells"} + thin["cellCount"] = len(tab.get("cells") or {}) + tabs.append(thin) + meta["sheets"] = tabs + return meta + + +def patch_cells(st, workbook_id, tab_ref, raw_cells, expect_rev=None): + """Merge a RANGE of cells into ONE tab. Returns `{rev, tab, refused}` (contract C3). + + ⭐⭐ ONE BAD CELL DOES NOT THROW THE COMMIT AWAY. Every address is cleaned on its own and a + cell that refuses lands in `refused` as `{addr, code, sentence}` while the rest of the patch + still commits. That is the opposite of `put_workbook`, and deliberately: a PUT is one document + the caller assembled, so a bad cell in it means the caller's document is wrong; a PATCH is a + range a person just typed into, and refusing forty good edits over one bad one would lose work + somebody did. + + ⭐ `{"A1": null}` DELETES A1. An empty cell is not the same thing as an absent one after C2 + (`kind: "empty"` carries a style), so a client needs a way to say "this address holds nothing + at all" that is distinguishable from "this address is painted yellow". + + ⛔⛔ THE CAPS ARE MEASURED ON THE MERGED DOCUMENT, NEVER ON THE PATCH, AND THAT IS THE WHOLE + TRAP IN THIS FUNCTION. `_json_safe` weighs the WHOLE workbook on every write, so a 200 byte + patch onto a workbook already at 15.9 MB is a write that takes it over the cap; measuring the + patch would report 200 bytes, store the document, and leave the tenant with a workbook the + store cannot hold. Same for the cell count: the merged TAB is what has to fit. + + ⚠ THE MEASUREMENT RUNS INSIDE `_persist`'s CALLBACK, which is the opposite of `save_folders`'s + rule that validation runs before the update. It has to: the merged document is only knowable + after the current state has been read under the store's own lock. Nothing is persisted, because + the raise happens before the callback returns its next state. + + ⚠ `rev` BUMPS BY EXACTLY ONE ON EVERY ACCEPTED PATCH, including one where every cell refused. + A conditional bump would leave the client holding a rev the server never issued, and the very + next patch would then answer 409 for a conflict that never happened. + """ + wid = _slug_id(workbook_id) + if raw_cells is None: + raw_cells = {} + if not isinstance(raw_cells, dict): + raise SheetRefusal("cells_not_an_object", "A cell patch must be an object.") + if len(raw_cells) > _MAX_CELLS_PER_SHEET: + raise SheetRefusal("sheet_too_many_cells", _too_many_cells_message(len(raw_cells))) + + #: Cleaned BEFORE the lock: `clean_cell` is pure, and doing it here keeps the store's lock + #: held for the merge alone rather than for every cell in the range. + #: ⚠ `addr` IS ECHOED AS THE CALLER SENT IT, not as this module would store it. The client's + #: dirty set is keyed by what it sent, so a refusal reported under a normalized address would + #: be one the sender cannot match back to the cell the person is looking at. + merged, deleted, refused = {}, [], [] + for addr, cell in raw_cells.items(): + sent = _text(addr, 12) + key = sent.upper() + if not _ADDR.match(key): + refused.append({"addr": sent, "code": "cell_address_invalid", + "sentence": "Cell address " + (sent or str(addr)) + + " is not an A1 address."}) + continue + if cell is None: + deleted.append(key) + continue + try: + merged[key] = clean_cell(cell, addr=key) + except SheetRefusal as exc: + refused.append({"addr": sent, "code": exc.code, "sentence": exc.message}) + + saved, out = {}, {} + + def _apply(state): + prior = state if state.get("id") else None + if prior is None: + raise SheetRefusal("workbook_missing", "That workbook no longer exists.") + current = int(prior.get("rev") or 0) + if expect_rev is not None and current != int(expect_rev): + raise SheetStaleRefusal( + "sheet_revision_stale", + "This sheet changed somewhere else while you had it open, so this save was not " + "applied. Reload the tab and try again.", + rev_current=current) + book = copy.deepcopy(prior) + tabs = book.get("sheets") or [] + at = _tab_index(tabs, tab_ref) + if at is None: + raise SheetRefusal( + "tab_missing", + "Tab " + (str(tab_ref) or "(unnamed)") + " is not in this workbook.") + tab = tabs[at] + cells = dict(tab.get("cells") or {}) + for key in deleted: + cells.pop(key, None) + cells.update(merged) + if len(cells) > _MAX_CELLS_PER_SHEET: + raise SheetRefusal("sheet_too_many_cells", _too_many_cells_message(len(cells))) + tab["cells"] = cells + book["sheets"] = tabs + book["rev"] = current + 1 + book["updated_at"] = _now() + _json_safe(book, "workbook") + out["rev"] = book["rev"] + out["tab"] = str(tab.get("id") or tab.get("name") or "") + out["cells"] = len(cells) + saved.update(book) + return book, book + + _persist(st, workbook_key(wid), _apply) + _index_upsert(st, saved) + out["refused"] = refused + return out + + def delete_workbook(st, workbook_id): """Empty the document and drop its index row. Returns True when something was there.""" wid = _slug_id(workbook_id) @@ -585,6 +1178,16 @@ def delete_workbook(st, workbook_id): _persist(st, workbook_key(wid), _apply) _index_drop(st, wid) + # ⛔ C5 / W51-T25: THE GRANTS DIE WITH THE OBJECT, and this is `core.shares.drop_objects`'s own + # stated contract rather than an extra: "a deleted object's grants must die with it — + # `shared_with` would otherwise serve ghost ids into every receiver's Shared with me forever, + # and the ghost would 404 on open." A share record also keeps an owner HUSK after a full + # revoke, so nothing short of dropping the record clears it. + try: + import core.shares as shares + shares.drop_objects([("workbook", wid)], st=st) + except Exception: + pass return bool(existed.get("yes")) @@ -617,6 +1220,75 @@ def _index_upsert(st, book): _persist(st, INDEX_KEY, _apply, seed={"workbooks": []}) +# ── C5: the grant join, and the rail's own revision (wave 51, W51-T25) ─────────────────────── +# +# ⭐⭐ SHARES ARE JOINED ONTO THE ROW AT READ TIME AND ARE NEVER STORED ON IT, AND THAT IS A +# STRUCTURAL DECISION RATHER THAN A STYLISTIC ONE. `_index_upsert`'s `_apply` above drops the +# prior row and appends a FRESHLY REBUILT `_index_row(book)` whose seven keys are all read off the +# DOCUMENT, and `create_workbook`, `put_workbook` and `patch_cells` all call it. A `shares` key +# stored on that row would therefore be DELETED BY THE NEXT PATCH OF ANY CELL, with nothing going +# red anywhere: the share door would answer 200, the registry would look right, and the mark would +# simply be gone the next time somebody typed in a cell. That is D-640 in a different function and +# W51-T21's own durable lesson ("a fresh dict deletes any key nobody names") arriving one layer up. +# +# `core.shares` is the ONE grant registry for every shareable object (wave 20, owner R10), it +# treats `kind` as an opaque bucket key, and it already answers "what am I shared on" across +# kinds. So the grants live there, this module reads them, and the failure above is impossible +# rather than merely guarded against. +# +# ⚠ THE COST, STATED RATHER THAN DISCOVERED: `shares.grants(kind, oid)` re-reads the WHOLE grant +# bucket per call, so a rail of N workbooks costs N reads of the tenant's registry. `granted_oids` +# exists in that module for exactly this reason but answers a different question (which ids carry +# ANY grant, with no roles and no owner). A `records(kind)` bulk read belongs there and is booked, +# not written here: reaching into another module's bucket from this one is how two readers of one +# document come apart. + +#: C5's wire words for a share role, and the registry's. `core.shares.ROLES` is `('view', 'edit')`; +#: C5 says `"viewer"` and `"editor"`. ⛔ THE TRANSLATION HAS EXACTLY ONE HOME AND IT IS +#: `routes_sheet.py::wire_role` / `::store_role` — this module only ever stores and reads the +#: registry's words, so a second spelling cannot be introduced here by accident. + + +def workbook_shares(st, workbook_id): + """C5's `shares` list for ONE workbook, computed from `core.shares` and never stored. + + `[{who, role}]` with `role` in the REGISTRY's vocabulary (`view` / `edit`); the route + translates to C5's `viewer` / `editor` at the boundary, which is the only place either + spelling of that fact exists. + + ⚠ C5 ALSO NAMES AN `at`, AND THERE IS NOTHING TO PUT IN IT. `core.shares._clean_entries` + normalises an entry to `{user, role, by?}` and stores no timestamp, so the key is OMITTED + rather than synthesised: a grant made last month would otherwise render as "shared just now", + which is worse than absent because it looks like an answer. Booked as an amendment finding; + the exit is a timestamp member on `_clean_entries`, which is not this ticket's fence. + """ + try: + import core.shares as shares + rec = shares.grants("workbook", str(workbook_id), st=st) + except Exception: + return [] + return [{"who": e["user"], "role": e["role"]} for e in (rec.get("entries") or [])] + + +def project_shares(st, rows): + """Join `shares` onto a list of index rows. Returns NEW rows; the stored ones are untouched. + + ⚠ Called by `read_index`, `save_folders` and `routes_sheet.list_sheets` — the three doors a + client reads the rail through. `list_workbooks` itself stays a bare pointer list on purpose: + `iter_workbooks` walks it to answer W49-T10's dependents question, and paying a grant-registry + read per workbook there would put a permission lookup inside a scan that asks no permission + question at all. + """ + out = [] + for row in rows or (): + if not isinstance(row, dict) or not row.get("id"): + continue + joined = dict(row) + joined["shares"] = workbook_shares(st, row["id"]) + out.append(joined) + return out + + def _index_drop(st, workbook_id): """Drop a workbook's pointer row AND everything the rail filed against it. @@ -635,6 +1307,8 @@ def _index_drop(st, workbook_id): starred = state.get("starred") if isinstance(starred, list): state["starred"] = [w for w in starred if w != workbook_id] + # D-639: this write rewrites `itemFolders` and `starred`, so it MOVES the rail's revision. + state["rev"] = _index_rev(state) + 1 return state, rows _persist(st, INDEX_KEY, _apply, seed={"workbooks": []}) @@ -665,6 +1339,163 @@ def iter_workbooks(st): continue +# ── R11 / W51-T26: WHAT A PURGED VIEW LEAVES BEHIND ────────────────────────────────────────── +# +# ⭐⭐ R11, verbatim: *"A view-scoped cell keeps pointing at a TRASHED view for the 30 days (it +# still resolves); its filter is copied into the cell's own scope AT PURGE (30-day purge or +# 'Delete forever'); restoring the view re-links for free."* +# +# ⛔⛔ THE ADOPTION IS ON THE PURGE PATH ONLY, AND THAT IS THE WHOLE RULING. Adopting at TRASH +# would make Restore a lie: the cell would already carry a copied filter, so putting the view back +# would leave forty cells pointing at a frozen snapshot of what that view USED to say, and every +# later edit of the view would stop reaching them. Restore re-links for free precisely because +# nothing was copied while the view sat in the trash. +# +# ⛔ AND IT IS IDEMPOTENT BY CONSTRUCTION, because `TableStore.trash()` runs the 30-day purge ON +# EVERY READ: this function will be called again for the same view id the next time anyone opens +# the panel. A cell whose `scope.view_id` is already gone is not this function's subject, so the +# second call finds nothing and writes nothing - and an `adoptedFrom` that already names THIS view +# is KEPT, so the receipt says when the purge happened rather than when it was last re-checked. + +#: ⚠ MUST AGREE with `aios_grid.LOCKED_VIEW_KIND`. Restated rather than imported for the same +#: reason `MAX_FOLDER_DEPTH` below is: this module imports nothing from the grid or the harness, +#: and a deferred import inside a hot scan is a cost paid per workbook. +LOCKED_VIEW_KIND = "locked" + +#: ⚠ MUST AGREE with `harness/filter_sql.COHORT_FIELD` and `types.ts`'s `COHORT_FIELD`. The +#: reserved pseudo-column of a cohort-membership leaf. +COHORT_FIELD = "__cohort__" + +#: The cohort op a single-set membership leaf uses. `filter_sql.COHORT_OPS`. +COHORT_ANY_OF = "anyOf" + + +def adopted_scope_filter(view): + """The filter tree a binding INHERITS from `view` at purge, as `{conj, nodes}`, or None. + + ⛔⛔ A LOCKED VIEW ADOPTS ITS MEMBER SET, NEVER ITS FILTER TREE (the three locks, `DESIGN.md` + section 4). A locked view IS a curated ROW SET: `aios_grid.locked_view_projection` says the + lock is the view's IDENTITY, membership lives in the cohort store and is never copied into the + view's config, and the config's `filters` are whatever the user happened to be looking at when + the set was made. Adopting those filters would silently replace a hand-picked cohort with a + predicate that never defined it, and the number would still look plausible. So the adopted + shape is the cohort leaf the engine already speaks: `{colId: "__cohort__", op: "anyOf", + value: }`, which is the view's own id. + + ⚠ THE FILTERS LIVE UNDER `config`, and reading them off the top level is silently EMPTY rather + than an error. `(view.get("config") or view)` mirrors `routes_alerts.py:518`, which is the + reader that gets this right; `routes_sheet.py::_view_filter` reads the top level and therefore + resolves EVERY view-scoped cell with no filter at all today (reported, W51-T26 finding 3). + + ⚠ AN EMPTY TREE IS A REAL ANSWER, NOT A REFUSAL. A view that filters nothing means "every row", + and `{conj: "and", nodes: []}` is exactly how `compile_scope` spells that (None -> no + predicate). Returning None here would leave the binding pointing at an id that no longer + exists, which is the state this whole function exists to prevent. + """ + record = view if isinstance(view, dict) else {} + config = record.get("config") if isinstance(record.get("config"), dict) else record + vid = str(record.get("id") or "").strip() + if str(record.get("kind") or "").strip() == LOCKED_VIEW_KIND: + cohort = str(config.get("cohortLock") or vid).strip() + if not cohort: + return None + return {"conj": "and", + "nodes": [{"colId": COHORT_FIELD, "op": COHORT_ANY_OF, "value": cohort[:120]}]} + tree = config.get("filters") + if isinstance(tree, dict): + nodes, conj = tree.get("nodes"), tree.get("conj") + else: + nodes, conj = tree, config.get("filterConj") + nodes = [copy.deepcopy(node) for node in nodes if isinstance(node, dict)] \ + if isinstance(nodes, list) else [] + return {"conj": "or" if conj == "or" else "and", "nodes": nodes} + + +def _scope_of(cell): + """One cell's binding scope, when it has one and it is an object. Else None.""" + if not isinstance(cell, dict): + return None + binding = cell.get("binding") + if not isinstance(binding, dict): + return None + scope = binding.get("scope") + return scope if isinstance(scope, dict) else None + + +def _bound_to_view(book, view_id): + """Every `(tab, addr, scope)` in one workbook document whose scope NAMES `view_id`.""" + vid = str(view_id or "").strip() + out = [] + if not vid or not isinstance(book, dict): + return out + for tab in book.get("sheets") or (): + if not isinstance(tab, dict): + continue + for addr, cell in (tab.get("cells") or {}).items(): + scope = _scope_of(cell) + if scope is not None and str(scope.get("view_id") or "").strip() == vid: + out.append((tab, str(addr), scope)) + return out + + +def count_view_bindings(st, view_id): + """How many Sheet cells are scoped to `view_id` RIGHT NOW. A pure read. + + ⛔⛔ THIS IS THE NUMBER IN THE CONFIRM SENTENCE ("3 Sheet cells will keep this view's + filter"), and it comes from the SERVER because a client cannot see another person's + workbooks. A hardcoded or client-guessed count passes every visual check and lies to the one + person who is deciding whether to destroy something. + + ⚠ IT WALKS THE SAME `iter_workbooks` SCAN `adopt_view_filter` WALKS, so the sentence and the + act cannot disagree by construction. An unreadable document is SKIPPED by that generator, so + this is a floor rather than a guess; there is no second scan to drift. + """ + return sum(len(_bound_to_view(book, view_id)) for book in iter_workbooks(st)) + + +def adopt_view_filter(st, view, at=None): + """Copy a purged view's scope into every binding that named it. Returns cells changed. + + ⛔⛔ CALL IT FROM A PURGE, NEVER FROM A TRASH OR A RESTORE. See the section note above. + + ⛔ IT RAISES RATHER THAN SWALLOWING A FAILED WORKBOOK WRITE, and the caller must not purge + when it does. A trash bucket emptied beside a workbook that never took the filter is a cell + pointing at an id that no longer exists anywhere, with nothing to report it. Because the + adoption is idempotent, the honest recovery is simply to retry on the next read: the workbooks + that DID take it are already done and are not this function's subject any more. + + `at` is injectable so a gate can pin the receipt without patching the clock. + """ + vid = str((view or {}).get("id") or "").strip() + if not vid: + return 0 + adopted = adopted_scope_filter(view) + if adopted is None: + return 0 + receipt = {"view_id": vid[:120], + "name": (str((view or {}).get("name") or "").strip() or vid)[:200], + "at": str(at or _now())[:120]} + changed = 0 + for book in iter_workbooks(st): + hits = _bound_to_view(book, vid) + if not hits: + continue + for _tab, _addr, scope in hits: + scope["filter"] = copy.deepcopy(adopted) + scope.pop("view_id", None) + # ⚠ `view_name` was carried ONLY so `view_missing` could name the view. The name now + # lives in the receipt, where it says something true; leaving it on a filter scope + # would be a second copy that `clean_binding` drops on the next save anyway. + scope.pop("view_name", None) + prior = scope.get("adoptedFrom") + if not (isinstance(prior, dict) + and str(prior.get("view_id") or "").strip() == vid): + scope["adoptedFrom"] = dict(receipt) + put_workbook(st, book["id"], book, expect_rev=book.get("rev")) + changed += len(hits) + return changed + + # ── the rail: folders, placements and stars (wave 50, W50-T17) ─────────────────────────────── # # ⭐⭐ THE MODEL IS COPIED FROM `core/table_store.py::validate_folder_tree` / `::save_folders`, @@ -901,13 +1732,35 @@ def _clean_starred(raw, known_ids, repairs): return out -def read_index(st): - """The whole rail document: `{workbooks, folders, itemFolders, starred}`. +def _index_rev(doc): + """The rail document's revision, as an int, however junk the stored value is.""" + try: + return int((doc or {}).get("rev") or 0) + except (TypeError, ValueError): + return 0 + + +def read_index(st, viewer=None): + """The whole rail document: `{workbooks, folders, itemFolders, starred, rev}`, plus + `sharedWithMe` when a `viewer` is named. ⛔ A STORED TREE CANNOT BRICK THE RAIL. The wall runs on WRITE, so a cycle should be unreachable here; a document written before that wall existed, or edited by hand, would otherwise make every GET raise and leave the module unopenable with no way back. So a stored tree that refuses is FLATTENED to roots and revalidated, which cannot refuse a second time. + + ⭐⭐ D-639 — `rev` RIDES THE READ, AND THAT IS ONE HALF OF A GUARD THAT NEEDS BOTH. + `save_folders` below CHECKS an `expect_rev`, and a client cannot send one it was never given, + so a `rev` here without the check there (or the check without this) is a guard nothing can + reach ([[a-rev-guard-inert-on-the-events-channel]]). The pair lands together or not at all. + + ⚠ WHICH WRITES MOVE IT IS PART OF THE CONTRACT: `save_folders` and `_index_drop`, which are + the two that rewrite the folder, placement and star strata this guard protects. + `_index_upsert` deliberately does NOT, because it is called by `create_workbook`, + `put_workbook` AND `patch_cells` — bumping there would make every cell edit 409 a folder drag + that touched nothing the guard is about. + + ⚠ `viewer` IS A USERNAME AND IS OPTIONAL. Absent, this reads exactly as it did before C5. """ doc = _read(st, INDEX_KEY) rows = [dict(r) for r in (doc.get("workbooks") or []) @@ -920,15 +1773,28 @@ def read_index(st): flat = [dict(f, parent=None) for f in (doc.get("folders") or []) if isinstance(f, dict) and f.get("id")] folders, placed, _repairs = validate_folder_tree(flat, placements) - return { - "workbooks": rows, + out = { + "workbooks": project_shares(st, rows), "folders": folders, "itemFolders": {k: v for k, v in placed.items() if k in ids}, "starred": _clean_starred(doc.get("starred"), ids, []), + "rev": _index_rev(doc), } + if viewer: + # C5's `sharedWithMe`. ⚠ FREE, and that is the point of using the registry: `shared_with` + # already answers "what was granted TO me" across kinds and already EXCLUDES what the + # caller owns, so the "Shared with me" partition of the rail needs no second store and no + # second definition of what being shared means. + try: + import core.shares as shares + granted = (shares.shared_with(viewer, kind="workbook", st=st) or {}).get("workbook") + except Exception: + granted = [] + out["sharedWithMe"] = [w for w in (granted or []) if w in ids] + return out -def save_folders(st, folders, item_folders, starred=None): +def save_folders(st, folders, item_folders, starred=None, expect_rev=None): """Replace the folder, placement and star strata WHOLESALE, once the tree is proven legal. Wholesale rather than per folder because the three are interdependent: a placement is only @@ -939,13 +1805,31 @@ def save_folders(st, folders, item_folders, starred=None): callback would abandon a half touched transaction; raising first means a refused tree leaves the store exactly as it was. The callback below only PRUNES, and cannot raise. - RETURNS `{workbooks, folders, itemFolders, starred, repairs}`. RAISES `SheetFolderRefusal` - on a cycle or an over deep chain, having written nothing. + RETURNS `{workbooks, folders, itemFolders, starred, rev, repairs}`. RAISES + `SheetFolderRefusal` on a cycle or an over deep chain, having written nothing. + + ⭐⭐ D-639 — `expect_rev` IS THE OTHER HALF OF `read_index`'s `rev`, AND IT IS CHECKED INSIDE + THE CALLBACK BECAUSE THAT IS THE ONLY PLACE THE STORED REVISION EXISTS. That is a deliberate + exception to the paragraph above: the folder TREE is pure and can be validated before the + update, but "is this the document you decided against" cannot be asked without reading it + under the store's own lock, so this follows `put_workbook` and `patch_cells`, which raise from + inside `_apply` for the same reason. `store.update` discards the callback's work when it + raises, so a refused save still writes nothing. + + ⚠ `expect_rev=None` OPTS OUT, exactly as `put_workbook`'s does. A client that has never read + the rail cannot send a revision, and refusing would make the first folder ever created + impossible. """ tree, placed, repairs = validate_folder_tree(folders, item_folders) out = {} def _apply(state): + if expect_rev is not None and _index_rev(state) != int(expect_rev): + raise SheetStaleRefusal( + "index_revision_stale", + "The Sheet rail changed somewhere else, so this save was not applied. Reload the " + "rail and try again.", + rev_current=_index_rev(state)) rows = [r for r in (state.get("workbooks") or []) if isinstance(r, dict) and r.get("id")] ids = {r["id"] for r in rows} @@ -959,16 +1843,23 @@ def save_folders(st, folders, item_folders, starred=None): state["itemFolders"] = kept if starred is not None: state["starred"] = _clean_starred(starred, ids, repairs) + # D-639: this write IS the one the guard protects, so it moves the revision. + state["rev"] = _index_rev(state) + 1 out["value"] = { "workbooks": [dict(r) for r in rows], "folders": [dict(f) for f in tree], "itemFolders": dict(kept), "starred": list(state.get("starred") or []), + "rev": _index_rev(state), } return state, None _persist(st, INDEX_KEY, _apply, seed={"workbooks": []}) result = dict(out.get("value") or {"workbooks": [], "folders": [], "itemFolders": {}, - "starred": []}) + "starred": [], "rev": 0}) + # ⚠ THE GRANT JOIN RUNS AFTER `_persist`, NEVER INSIDE THE CALLBACK. `shares.grants` reads the + # store, and reading one document from inside another document's update callback puts a second + # store call under a lock this one already holds. + result["workbooks"] = project_shares(st, result.get("workbooks")) result["repairs"] = repairs return result diff --git a/platform/core/table_store.py b/platform/core/table_store.py index 68c40f914d2f64c8fc0bfd017cf1c32217573481..19aed664b8ecc5e9808ea6bc8186afe52832d4a5 100644 --- a/platform/core/table_store.py +++ b/platform/core/table_store.py @@ -617,7 +617,7 @@ class TableStore: same tenant's buckets this workspace lives in (wave 21, C1).""" return self._st - def find_view(self, view_id, prefer_owner=None): + def find_view(self, view_id, prefer_owner=None, include_trashed=False): """`(owner_username, view)` for a view living in ANY personal stratum, else None. ⭐ Wave 21 (item 9, C1): the R10 grant registry names bare ids, so projecting a granted @@ -631,7 +631,21 @@ class TableStore: scan therefore answered whichever stratum the dict happened to yield first - so starring `All products` wrote `important` onto a colleague's overlay record and the caller's own rail never changed, with a 200 and nothing red. A caller that names itself gets its own - record when one exists; the scan below is unchanged otherwise.""" + record when one exists; the scan below is unchanged otherwise. + + ⭐⭐ `include_trashed` (wave 51, W51-T26, ruling R11) - "MISSING" AND "TRASHED" ARE + DIFFERENT ANSWERS. A deleted view is MOVED out of `views` into `.trash`, so this + scan answered None for it and every consumer reported it as gone: a Sheet cell scoped to a + view somebody deleted an hour ago refused with `view_missing` for the whole 30 days it was + still restorable. R11 says such a cell keeps working until the view is PURGED, so a caller + that wants that promise asks for it by name. + + ⛔ IT DEFAULTS TO FALSE, AND THE DEFAULT IS THE LOAD-BEARING HALF. Nine call sites read + this method and several are permission-adjacent (`routes_shares`, `routes_starred`, + `routes_publish`, `routes_forms`): a resolver that silently starts answering for a record + it used to refuse widens every one of them with every gate still green. So the fallback is + OPT IN, the live scan always wins, an EXPIRED entry is never offered (retention is not a + display filter) and `prefer_owner` is honoured in the trash exactly as it is above.""" # A direct lookup is a runtime read too. Do not leave a stale compatibility-shaped # personal record reachable merely because this caller did not first go through the grid # workspace assembler. @@ -655,6 +669,24 @@ class TableStore: v = (ws.get('views') or {}).get(vid) if isinstance(v, dict): return str(username), dict(v) + if not include_trashed: + return None + # R11's 30 days. Same preference order as above, and only an UNEXPIRED entry: an entry + # past retention is being destroyed, so answering with it would let a cell resolve + # through a view the very next read is going to purge. + order = ([mine] if mine and mine not in RESERVED_MEMBERS else []) + order += [str(who) for who in data if who not in RESERVED_MEMBERS and who != mine] + for who in order: + ws = data.get(who) + if not isinstance(ws, dict): + continue + bucket = ws.get(TRASH_KEY) + entry = bucket.get(vid) if isinstance(bucket, dict) else None + if not isinstance(entry, dict) or trash_expired(entry): + continue + record = entry.get('view') + if isinstance(record, dict): + return str(who), dict(record, id=vid) return None def find_folder(self, folder_id): @@ -1675,6 +1707,98 @@ class TableStore: self._audited_update(_up, rev=rev, flush='async') + # ---------------------------------------------- W51-T26 / R11: what a PURGE leaves behind + def _adopt_purged(self, entries): + """Copy each purged view's scope into every Sheet cell that named it. True when it held. + + ⛔⛔ THE PURGE PATH ONLY, and never a trash or a restore. R11: a view-scoped cell keeps + pointing at a TRASHED view for the whole 30 days and re-links for free if the view comes + back; the filter is copied into the cell's own scope only when the view is destroyed. + Adopting at trash would make Restore a lie - the cell would already hold a frozen snapshot + of what the view used to say, and every later edit of the view would stop reaching it. + + ⚠ A DEFERRED core-to-core IMPORT, matching `choice_removal` above. `core/sheets.py` + imports nothing from `core` at module level and this module is imported by half the API, + so a top-level import here is an import cycle. + + ⚠ A MALFORMED ENTRY IS SKIPPED, NOT FAILED. `trash_expired` counts an entry with no + restorable `view` as expired precisely so it can be dropped; it names no filter, so there + is nothing for a binding to adopt and refusing to purge it would grow the document forever. + + ⚠ IT RETURNS FALSE RATHER THAN RAISING BECAUSE ITS ONE CALLER IS HOUSEKEEPING ON A READ. + `trash()` turns a False into "do not purge yet" and answers the list anyway. `purge_view` + below deliberately does NOT come through here: a person clicked a destructive button and + was shown a count, so a failure there has to be loud rather than quietly deferred. + + ⛔ MEASURED RESIDUE, BOOKED RATHER THAN HIDDEN: the adoption writes ONE WORKBOOK AT A TIME + and there is no transaction across documents. If the second workbook's write refuses, the + first has already taken the filter while the view is still in the trash and still + restorable, so a Restore in that window re-links every cell EXCEPT the ones that already + adopted. It self-heals on the next purge (the adoption is idempotent) and it is pinned by + its own leg in `verify_shared_views.py` section 10d rather than described here. + """ + from core import sheets as _sheets + try: + for entry in entries or (): + record = (entry or {}).get('view') + if not isinstance(record, dict): + continue + record = dict(record) + record.setdefault('id', str((entry or {}).get('id') or '')) + _sheets.adopt_view_filter(self._st, record) + except Exception: # noqa: BLE001 + return False + return True + + def purge_view(self, username, view_id, *, rev=None): + """R11's "Delete forever": destroy one trashed view NOW. `(name, adopted_cell_count)`. + + ⛔ THE ADOPTION RUNS FIRST AND A FAILURE REFUSES THE PURGE. Unlike the retention sweep on + `trash()`, this one is a deliberate act by a person who is about to be told how many cells + will keep the filter, so failing silently and destroying the view anyway would break the + promise that sentence just made. It raises, the route reports it, and nothing is lost. + + ⚠ NO AUDIT ROW, DELIBERATELY. C3 names seven actions and `purge` is not one of them; + inventing an eighth here would widen a vocabulary two gates pin. The `delete` row written + when the view entered the trash is still the record of its removal. Booked as a finding. + + ⚠ IT STILL GOES THROUGH `_audited_update`, for the C3 revision guard and the one locked + read-modify-write. `action=None` is how that door spells "no row" (see `delete_view`). + """ + vid = str(view_id or '').strip() + owner = str(username or '').strip().lower() + if not vid: + raise ValueError('view id is required') + if not owner or owner in RESERVED_MEMBERS: + raise ValueError('reserved username') + data = self._st.get(self.table_key) or {} + ws = data.get(owner) + bucket = ws.get(TRASH_KEY) if isinstance(ws, dict) else None + entry = bucket.get(vid) if isinstance(bucket, dict) else None + if not isinstance(entry, dict) or trash_expired(entry): + raise ViewNotInTrash( + 'that view is not in the trash. Deleted views are kept for ' + f'{TRASH_RETENTION_DAYS} days.') + record = entry.get('view') if isinstance(entry.get('view'), dict) else {} + name = str(record.get('name') or vid) + + from core import sheets as _sheets + adopted = _sheets.adopt_view_filter(self._st, dict(record, id=vid)) + + def _up(current, audit): + live = (current.get(owner) or {}).get(TRASH_KEY) if isinstance( + current.get(owner), dict) else None + if isinstance(live, dict): + live.pop(vid, None) + purge_trash(live, now=time.time()) + if not live: + current[owner].pop(TRASH_KEY, None) + audit(action=None, owner=owner, view_id=vid) + return current + + self._audited_update(_up, rev=rev, flush='async') + return name, int(adopted) + # ------------------------------------------------------- W50-T26: the trash and its restore def trash(self, username, now=None): """One owner's trashed views, NEWEST DELETION FIRST, expired entries PURGED on the way. @@ -1704,7 +1828,25 @@ class TableStore: return [] stamp = float(now if now is not None else time.time()) expired = [vid for vid, entry in bucket.items() if trash_expired(entry, now=stamp)] - if expired: + # ⛔⛔ R11's ADOPTION RUNS BEFORE THE UPDATE AND OUTSIDE ITS CALLBACK (W51-T26). + # `sheets.py::save_folders` states the rule for this codebase in as many words: validation + # runs before the update, never inside its callback, because a raise from inside would + # abandon a half touched transaction. Here it is a CROSS DOCUMENT write - the workbooks - + # inside what is otherwise a list door, so the ordering is the whole safety property: the + # filters land first, and only then does the bucket lose the views they came from. + # + # ⛔ AND WHEN THE ADOPTION FAILS THE PURGE DOES NOT RUN. A trash bucket emptied beside a + # workbook that never took the filter leaves a cell pointing at an id that exists nowhere, + # with nothing left to report it. `adopt_view_filter` is idempotent, so the honest + # recovery is to leave the entry where it is and retry on the next read. The entry stays + # out of the ANSWER either way: retention is a promise about what is kept, and serving a + # 31-day-old row because housekeeping could not commit would be a second, louder bug. + adopted = self._adopt_purged( + [{'id': vid, + 'view': (bucket[vid] or {}).get('view') if isinstance(bucket.get(vid), dict) + else None} + for vid in expired]) if expired else True + if expired and adopted: def _purge(current): current = current if isinstance(current, dict) else {} ws = current.get(owner) diff --git a/platform/harness/filter_eval.py b/platform/harness/filter_eval.py index d9040b370571069c0983f267bfe9d1094c2a2074..72bc9e4063e0d37579313edfff454741da303bd3 100644 --- a/platform/harness/filter_eval.py +++ b/platform/harness/filter_eval.py @@ -51,8 +51,9 @@ import math from collections import namedtuple from harness.filter_sql import ( # noqa: F401 (COHORT_OPS re-exported for callers) - COHORT_FIELD, COHORT_OPS, COHORT_OP_ALIASES, FILTER_OPS, RANK_OPS, - is_rule_active, parse_cohort_ids, to_num, _resolve_anchor, _window_bounds, + COHORT_FIELD, COHORT_OPS, COHORT_OP_ALIASES, FILTER_OPS, MULTI_VALUE_OPS, RANK_OPS, + is_rule_active, parse_cohort_ids, parse_filter_values, to_num, + _resolve_anchor, _window_bounds, ) #: The CLIENT's numeric family, which is WIDER than `filter_sql.NUMERIC_TYPES`. `rating` (an @@ -176,6 +177,61 @@ def _cmp_text(op, a, v): return True +def _as_choice_text(raw): + """The client's ``String(raw ?? "")`` over a CHOICE-SET cell, lowercased. + + ⚠ NOT ``_as_text``. A multi-select value can still arrive from the wire as a LIST (see + ``_is_blank``, which already carries that case), and Python's ``str(['a', 'b'])`` renders + ``"['a', 'b']"`` where JS's ``String(["a","b"])`` renders ``"a,b"`` — the comma-joined form + the storage layer uses and the one the membership test below has to see. + """ + if isinstance(raw, (list, tuple)): + return ','.join('' if x is None else str(x) for x in raw).lower() + return _as_text(raw) + + +def _cell_members(raw): + """The MEMBERS of one cell, mirroring `useVisibleRows.cellMembers`. + + A multi-select cell is a comma-joined set; a single-valued cell is a one-member set, so + ``hasAnyOf`` over a select column means exactly what ``isAnyOf`` does there. A BLANK cell has + NO members, which is the blank decision the three engines pin as a lock-step case. + """ + return [m for m in (part.strip() for part in _as_choice_text(raw).split(',')) if m] + + +def _match_multi_value(op, raw, values): + """⭐ W51-T07 — the five multi-value operators, COMPOSED from `_cmp_text`. + + ⛔ THIS FUNCTION IS THE POINT OF THE WHOLE AMENDMENT. This module imports ``FILTER_OPS`` from + ``filter_sql``, and its only vocabulary guard is ``op not in FILTER_OPS -> False``. The moment + the five ops joined that set, the guard began PASSING them straight into ``_cmp_text``, whose + tail returns True for an operator it does not know — so every row would have matched, in the + module that is BOTH the server-side display mirror (``matches``) and the PERMISSION wall + (``permits``). A bare ``return False`` would have been no better: the server would then + disagree with the browser about real rows, which is the drift this module exists to prevent. + + ``isAnyOf`` is the OR of ``_cmp_text('eq', ...)`` over the values, so it is the union of the + equivalent single-value leaves by construction rather than by testing. + """ + want = [v.strip().lower() for v in values] + # ⛔ NO VALUES = UNANSWERABLE = MATCHES NOTHING, uniformly. A SECOND layer: `_eval` already + # calls such a leaf inactive via `is_rule_active`. Written anyway because the vacuous cases + # go the WIDENING way — `all(... for v in [])` is True, so `hasAllOf []` would match every + # row, on a permission wall. `filter_sql` answers `1=0` for the identical input. + if not want: + return False + if op in ('isAnyOf', 'isNoneOf'): + a = _as_choice_text(raw) + hit = any(_cmp_text('eq', a, v) for v in want) + return hit if op == 'isAnyOf' else not hit + members = _cell_members(raw) + if op == 'hasAllOf': + return all(v in members for v in want) + hit = any(v in members for v in want) + return hit if op == 'hasAnyOf' else not hit + + def _is_blank(raw): """The condition-builder blank contract: absent, empty choice set, or ``'(none)'``. @@ -280,6 +336,17 @@ def _match_filter(rule, row, columns, today): if op in RANK_OPS: return False + # ⭐ W51-T07 — the MULTI-VALUE family, ON THE OP and before the type dispatch. Every branch + # below ends in a blank-value short-circuit and these leaves carry a blank `value`; one + # fall-through and a permission wall reading `Agent is any of [...]` admits every row. + if op in MULTI_VALUE_OPS: + # Numeric and date columns REFUSE, matching the other two engines exactly: `_cmp_num`'s + # documented `default: True` would widen, and comparing a number against its own string + # form would make the three engines disagree about a rendering rather than a value. + if ftype in NUMERIC_TYPES or ftype in DATE_TYPES: + return False + return _match_multi_value(op, raw, parse_filter_values(rule.get('values'))) + rhs = rule.get('rhs') has_rhs = rhs is not None other = row.get(_rhs_col(rhs) or '') if has_rhs else None diff --git a/platform/harness/filter_sql.py b/platform/harness/filter_sql.py index c8ba44452a051b514e3ba65b544cbc39ba18e49c..09ba6b30a586aee99465b7b150e30af461d46118 100644 --- a/platform/harness/filter_sql.py +++ b/platform/harness/filter_sql.py @@ -77,7 +77,18 @@ FILTER_OPS = frozenset({ 'gt', 'gte', 'lt', 'lte', 'between', 'within', 'topN', 'bottomN', 'inTopPct', 'inBottomPct', 'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile', + 'isAnyOf', 'isNoneOf', 'hasAnyOf', 'hasAllOf', 'hasNoneOf', }) +#: ⭐ W51-T07 (owner instruction 25): the MULTI-VALUE subset — operators whose operand is the +#: leaf's ``values`` LIST rather than its ``value`` string. Mirrors types.ts MULTI_VALUE_OPS. +#: ⛔ These leaves leave ``value`` BLANK, so `is_rule_active`'s tail rule ("blank value means the +#: rule is half-typed") would call a fully built one INACTIVE — and inactive means no predicate +#: at all, i.e. every row, under a row_count that still looks authoritative. `is_rule_active` +#: therefore answers them from ``values``, and `_compile_leaf` intercepts them on the OP before +#: any type branch can apply its own blank-value short-circuit. +MULTI_VALUE_OPS = frozenset({'isAnyOf', 'isNoneOf', 'hasAnyOf', 'hasAllOf', 'hasNoneOf'}) +#: Mirrors types.ts MAX_FILTER_VALUES / aios_grid.MAX_FILTER_VALUES. +MAX_FILTER_VALUES = 100 #: Wave 2026-08-02 (C-OPS): the RANK subset — set-ranked over the sibling-filtered domain. #: Vocabulary here, execution NOWHERE in this module: a per-row WHERE cannot express Top-N, #: and compiling to 1=0 would answer "nothing" to a question that has an answer, under a @@ -107,6 +118,28 @@ def parse_cohort_ids(value): 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()`. + + A real LIST, never a comma-joined string: a select OPTION is tenant prose and may itself + contain a comma, so joining would split one real choice into two that match nothing. Order + preserved, blanks dropped, duplicates collapsed, members capped at 120 chars, the list capped + at MAX_FILTER_VALUES. Unknown option strings are KEPT — a value that no longer exists then + filters to nothing, honestly, rather than silently asking a wider question. + """ + out = [] + if not isinstance(values, (list, tuple)): + return out + for raw in values: + v = ('' if raw is None else str(raw)).strip()[:120] + if not v or v in out: + continue + out.append(v) + if len(out) >= MAX_FILTER_VALUES: + break + return out # types.ts VALUE_FREE_OPS: no value control is rendered, and they must never be judged # "inactive because the value is blank" — that would turn them into no-ops. VALUE_FREE_OPS = frozenset({'isEmpty', 'isNotEmpty', 'aboveAvg', 'belowAvg'}) @@ -249,6 +282,12 @@ def is_rule_active(rule, columns): if col not in columns: return False op = rule.get('op') + # ⭐ W51-T07 — a MULTI-VALUE leaf is driven by the LIST it names and by nothing else, exactly + # as the cohort arm above is driven by its set. FIRST among the op tests, because these + # leaves carry a BLANK `value` and the tail rule below ("blank value = inactive") would + # otherwise IGNORE a fully built condition, emitting no predicate and showing every row. + if op in MULTI_VALUE_OPS: + return bool(parse_filter_values(rule.get('values'))) if op in VALUE_FREE_OPS: return True if op == 'within': @@ -375,6 +414,13 @@ def _compile_leaf(rule, columns, state): v = _value_sql(spec) t = spec['type'] + # --- ⭐ W51-T07: the MULTI-VALUE family, ON THE OP and before every type branch ---------- + # Placed with the value-free ops above rather than inside the text branch, and for the same + # reason: every type branch below ends in a blank-value short-circuit, and these leaves carry + # a blank `value`. One fall-through and `Agent is any of [A, B, C]` compiles to `1=1`. + if op in MULTI_VALUE_OPS: + return _compile_multi_value(op, v, t, rule, used) + # --- CG-9: the comparand is another COLUMN, coerced through the LEFT field's type -------- # `_value_sql` on a spec whose `sql` is the RIGHT column and whose `type` is the LEFT one — # exactly what TS does (`toNum(other)` for a numeric LHS, `String(other ?? "")` for a date, @@ -484,6 +530,51 @@ def _resolve_anchor(mode, value, today): return _windows().resolve_anchor(mode, value, today) +def _compile_multi_value(op, v, t, rule, used): + """⭐ W51-T07 — the five multi-value operators, as bound-parameter SQL. + + ``isAnyOf`` is COMPOSED from the very fragment ``eq`` compiles to (``{v} = LOWER(?)``), + OR-joined. That is the ticket's correctness target expressed in code rather than in a test: + ``Agent is any of [A, B, C]`` is the union of three ``Agent eq`` leaves by construction, with + the same folding, the same COALESCE of a NULL cell and the same treatment of the connector's + ``'(none)'`` sentinel. ``isNoneOf`` is its negation. + + The three ``has*`` operators answer a ``multiselect`` cell, which is a comma-joined SET, so + they compare whole MEMBERS: ``list_contains(list_transform(str_split(...), trim), needle)`` + mirrors the client's split/trim/fold exactly. ⚠ NOT ``strpos``: substring membership is what + makes ``contains`` find *Done* inside *Not done*, and removing that is half of why these + operators exist. ``hasAllOf`` is the AND of the memberships, per the ticket's `how` line. + + BLANKS, decided once for all three engines: a blank cell has NO members and equals no listed + value, so ``isNoneOf`` / ``hasNoneOf`` answer TRUE over it and the other three answer FALSE. + ``str_split('', ',')`` yields one empty member, which ``list_contains`` never matches because + `parse_filter_values` drops empty values. + + NUMERIC and DATE columns REFUSE (``1=0``, matches nothing) rather than compare. They do not + offer these operators, but a saved view whose column later changed type can carry one, and + the alternatives are both wrong: SQL_TRUE would widen exactly as the client's documented + ``default: true`` would, and stringifying the number would compare against a RENDERING the + three engines do not spell the same way. + + Every value is BOUND, never interpolated: these strings are tenant prose. + """ + if t in NUMERIC_TYPES or t in ('date', 'created_time'): + return ('1=0', []) + vals = parse_filter_values(rule.get('values')) + if not vals: + # Unreachable: `is_rule_active` already demanded a non-empty list. Never SQL_TRUE. + return ('1=0', []) + if op in ('isAnyOf', 'isNoneOf'): + union = '(' + ' OR '.join(f"({v} = LOWER(?))" for _ in vals) + ')' + return used((f"(NOT {union})" if op == 'isNoneOf' else union), vals) + members = f"list_transform(str_split({v}, ','), x -> trim(x))" + parts = [f"list_contains({members}, TRIM(LOWER(?)))" for _ in vals] + if op == 'hasAllOf': + return used('(' + ' AND '.join(parts) + ')', vals) + union = '(' + ' OR '.join(parts) + ')' + return used((f"(NOT {union})" if op == 'hasNoneOf' else union), vals) + + def _compile_cohort(rule, state): """Port of evalNode's cohort branch: membership in a SET of hand-curated sets of row ids. diff --git a/platform/modules/sheet.py b/platform/modules/sheet.py index ae2b6ab18ece010563c677fb41614bff362071dd..e8ac50b5559337145d61dcd81ed1dff3ee6e8638 100644 --- a/platform/modules/sheet.py +++ b/platform/modules/sheet.py @@ -31,10 +31,30 @@ The only SQL this module writes itself is the aggregate wrapper and the spec's o from __future__ import annotations +import re + #: C2's aggregate vocabulary. `metric_key` is the other arm of that union and is resolved by the #: route against the same catalogue `routes_query.py::_compatible_metric_dtos` serves. AGGREGATE_FNS = ("sum", "count", "avg", "min", "max") +#: ⭐ R9's PERIOD (wave 51, W51-T21). The three units a bound cell can be pinned to, and the month +#: its window starts in. `web/src/sheet/types.ts` carries the same three names. +PERIOD_UNITS = ("month", "quarter", "year") + +#: `YYYY-MM`. A period starts in a MONTH whatever its unit, because a quarter and a year are both +#: named by the month they open on, and one spelling means a copied cell cannot mean two things. +_PERIOD_START = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$") + +#: A `period.ref` points at a cell that holds the period, so it is a plain A1 address with no `$`, +#: exactly as `core/sheets.py::_ADDR` spells one. +_PERIOD_REF = re.compile(r"^[A-Z]{1,3}[1-9][0-9]{0,6}$") + +#: ⭐ R10's DRAG, and it is TWO settings rather than one because the two axes answer different +#: questions. Across columns a drag walks the PERIOD; down rows it walks the next value of a +#: chosen field. Defaults: across "period", down "none". +DRAG_ACROSS = ("period", "none") +DRAG_DOWN_NONE = "none" + #: C2's refusal codes, spelled once. ⚠ Each message reaches a screen, so none carries an em dash or #: an en dash (standing rule 2) and each names both the cause and the subject. REFUSALS = { @@ -48,6 +68,21 @@ REFUSALS = { "binding_invalid": "That cell's source is not set up correctly.", "aggregate_unknown": "{subject} is not an aggregate this cell can compute.", "field_unknown": "{subject} is not a column on this database.", + "period_invalid": "{subject} is not a period this cell can use.", + # ── C5's two sharing refusals (wave 51, W51-T25) ────────────────────────────────────────── + # + # ⭐⭐ THEY LIVE HERE, WITH C2's, BECAUSE THIS DICT IS THE ONE PLACE A SHEET REFUSAL IS + # WORDED. `routes_sheet._refuse` decides the STATUS from the code and `_formula_message` + # reads this table for a sentence, so a code worded at the route would arrive with two + # spellings depending on which door refused ([[one-question-two-normalizers]]). + # + # ⚠ `{subject}` IS THE WORKBOOK'S OWNER, so the sentence tells the reader who to ask rather + # than only that they were stopped. `SheetRefusal(code, subject)` falls back to "this + # database" when no subject is given, which reads wrongly here, so both doors pass one. + "workbook_read_only": "This workbook was shared with you to read, so it cannot be changed " + "here. Ask {subject} for permission to edit it.", + "workbook_owner_only": "Only the person who created this workbook can do that. Ask " + "{subject}.", } @@ -62,11 +97,96 @@ class SheetRefusal(Exception): super().__init__(self.message) +def clean_period(raw): + """R9's period, or None. `{unit, start, locked, ref?}`, with `{ref}` / `{window}` still read. + + ⛔ AN UNKNOWN UNIT OR A MALFORMED START IS REFUSED BY NAME, and that is not the same call as + the cosmetic keys next door. A period decides WHICH ROWS ARE COUNTED. Dropping `unit: "week"` + would answer for every row the binding can see and hand back a bigger number with nobody told, + which is standing rule 1's second sentence turned into a defect. + + ⚠ `locked` STORES ONLY TRUE. R9's lock means "a copy of this cell keeps this period"; an + unlocked period is what every cell already is, so storing `false` would make a cell that was + locked and unlocked compare unequal to the cell it started as. + """ + if not isinstance(raw, dict): + return None + out = {} + + unit = str(raw.get("unit") or "").strip().lower() + if unit: + if unit not in PERIOD_UNITS: + raise SheetRefusal("period_invalid", unit) + out["unit"] = unit + + start = str(raw.get("start") or "").strip() + if start: + if not _PERIOD_START.match(start): + raise SheetRefusal("period_invalid", start) + out["start"] = start + + if raw.get("locked") is True: + out["locked"] = True + + ref = str(raw.get("ref") or "").strip().upper().replace("$", "") + if ref: + if not _PERIOD_REF.match(ref): + raise SheetRefusal("period_invalid", ref) + out["ref"] = ref + + #: ⚠ The wave-49 spelling, kept so a binding written before R9 still round trips. It is not a + #: second dialect for the same thing: `window` is a raw relative window, `unit` + `start` is a + #: named calendar period, and a document carrying the old one is not rewritten on read. + if raw.get("window") is not None and "unit" not in out and "start" not in out: + out["window"] = raw["window"] + + return out or None + + +def clean_on_drag(raw): + """R10's two directional drag settings, or None when the caller sent none. + + ⚠ BOTH KEYS COME OUT WHENEVER ONE WENT IN. The two axes are answered together or a drag has + to guess one of them, and a guess is exactly what R10 replaced. The defaults are R10's own: + across "period", down "none". + """ + if not isinstance(raw, dict): + return None + across = str(raw.get("across") or "").strip().lower() + if across not in DRAG_ACROSS: + across = "period" + down = raw.get("down") + if isinstance(down, dict) and str(down.get("field") or "").strip(): + out_down = {"field": str(down["field"]).strip()} + else: + out_down = DRAG_DOWN_NONE + return {"across": across, "down": out_down} + + +def clean_adopted_from(raw): + """W51-T26's adoption receipt, or None. `{view_id, name, at}`. + + ⭐⭐ IT IS WHAT A PURGED VIEW LEAVES BEHIND. When a view is purged the binding keeps that + view's FILTER, so the number stays right; without this receipt the cell would show a number + with no way to say where its scope came from, and the person would find a filter they never + wrote. It rides on the FILTER scope for exactly that reason, not only on the view scope. + """ + if not isinstance(raw, dict): + return None + out = {} + for key, limit in (("view_id", 120), ("name", 200), ("at", 120)): + value = str(raw.get(key) or "").strip()[:limit] + if value: + out[key] = value + return out or None + + def clean_binding(raw): """Normalize a C2 `Binding`, or raise `SheetRefusal`. - `Binding = {database, aggregate:{fn, field?} | {metric_key}, scope:{view_id} | {filter}, - period?: {ref} | {window}}` + `Binding = {database, aggregate:{fn, field?} | {metric_key}, + scope:{view_id} | {filter} (+ adoptedFrom?), + period?: {unit, start, locked, ref?} | {window}, onDrag?: {across, down}}` """ if not isinstance(raw, dict): raise SheetRefusal("binding_invalid") @@ -111,12 +231,20 @@ def clean_binding(raw): else: raise SheetRefusal("binding_invalid") + adopted = clean_adopted_from(scope.get("adoptedFrom")) + if adopted: + out_scope["adoptedFrom"] = adopted + out = {"database": database, "aggregate": out_agg, "scope": out_scope} - period = raw.get("period") - if isinstance(period, dict) and (period.get("ref") or period.get("window")): - out["period"] = ({"ref": str(period["ref"]).strip()} if period.get("ref") - else {"window": period["window"]}) + period = clean_period(raw.get("period")) + if period: + out["period"] = period + + on_drag = clean_on_drag(raw.get("onDrag")) + if on_drag: + out["onDrag"] = on_drag + return out diff --git a/web/src/assistant/AssistantPage.tsx b/web/src/assistant/AssistantPage.tsx index 820da69732d27ccb55df441c02de7129d9d316d2..ee0b529288bcb7d8d113761572ae87843f1b8f85 100644 --- a/web/src/assistant/AssistantPage.tsx +++ b/web/src/assistant/AssistantPage.tsx @@ -11,6 +11,8 @@ import { answerSourceFooter, deleteQuery, deleteThread, fetchQueries, rateMessage, submitChat, type QueryCitation, type QueryIndex, type QueryMessage, type SavedQuery, } from "../query/queryApi"; +// W51-T31 — the ONE Escape arbiter (C8). See the registration in `AssistantMessage`. +import { useEscapeClose } from "../ui/useEscapeClose"; import "./assistant.css"; import "../styles/wave45/agent-operator.css"; @@ -186,6 +188,12 @@ export function AssistantMessage({ const [slackOpen, setSlackOpen] = useState(false); const [artifacts, setArtifacts] = useState(governedArtifacts || null); const [artifactStatus, setArtifactStatus] = useState(""); + const slackRef = useRef(null); + // W51-T31 — the Slack correction card calls itself a `role="dialog"`, so it owes a dialog's + // dismissal: Escape closes it, through the ONE stack (C8 / DESIGN.md §4). Registered here at + // the top level rather than beside the markup, because the markup sits behind a conditional + // and the early return for a user message is two lines below. + useEscapeClose(slackOpen, () => setSlackOpen(false), { container: () => slackRef.current }); const matching = citations.filter((citation) => (message.citationIds || []).includes(citation.id)); if (message.role === "user") { return ( @@ -237,7 +245,8 @@ export function AssistantMessage({ {artifactStatus ?

{artifactStatus}

: null} {slackOpen ? ( -
+

Slack correction

Slack can correct Filter, Sort, and Group after the Query capability check. Complex edits open the exact server-returned Query in Loopable.

{(["filters", "sorts", "group"] as const).map((key) =>
); } diff --git a/web/src/customer-grid/OverlaySurface.tsx b/web/src/customer-grid/OverlaySurface.tsx index 8c40fb160dcc5d4a7c08aec8282d2368bc721ec5..27aa37f736a5a2f968659af571a8850fb08e01b4 100644 --- a/web/src/customer-grid/OverlaySurface.tsx +++ b/web/src/customer-grid/OverlaySurface.tsx @@ -17,6 +17,7 @@ import type { RefObject, } from "react"; import { createPortal } from "react-dom"; +import { useEscapeClose } from "../ui/useEscapeClose"; import { computeOverlayPosition } from "./overlayPlacement"; import type { Placement as OverlayPlacement } from "./overlayPlacement"; @@ -130,6 +131,9 @@ interface OverlayLayerOptions { restoreFocus?: boolean; trapFocus?: boolean; outsideElements?: Array; + /** Escape cancels a live text edit inside the panel before it closes it. Default + * FALSE, which is the one-press blur-and-close every overlay had before W51-T01. */ + cancelEditFirst?: boolean; } /** Shared dismissal/focus contract for anchored menus and fixed drawers. */ @@ -142,6 +146,7 @@ export function useOverlayLayer({ restoreFocus = true, trapFocus = false, outsideElements = [], + cancelEditFirst = false, }: OverlayLayerOptions): void { const id = useId(); const stack = useContext(OverlayStackContext); @@ -152,6 +157,11 @@ export function useOverlayLayer({ useEffect(() => stack?.register(id), [id, stack]); + // The ONE Escape path for this layer. Mounted means claiming, so `active` is true. + const onEscape = useCallback(() => dismissRef.current(), []); + const escapeContainer = useCallback(() => panelRef.current as HTMLElement | null, [panelRef]); + useEscapeClose(true, onEscape, { cancelEditFirst, container: escapeContainer }); + useEffect(() => { const onPointerDown = (event: PointerEvent) => { if (!dismissOnOutside || (stack && !stack.isTop(id))) return; @@ -167,17 +177,11 @@ export function useOverlayLayer({ }; const onKeyDown = (event: KeyboardEvent) => { if (stack && !stack.isTop(id)) return; - if (event.key === "Escape") { - event.preventDefault(); - event.stopPropagation(); - if ( - document.activeElement instanceof HTMLElement && - panelRef.current?.contains(document.activeElement) - ) - document.activeElement.blur(); - dismissRef.current(); - return; - } + // ⛔ ESCAPE IS NOT HANDLED HERE ANY MORE (W51-T01). It is arbitrated by the ONE + // module-level stack in `ui/useEscapeClose`, registered by this hook above, because + // `OverlayStackContext` cannot order this layer against a portalled dialog that + // never joins it — a menu opened inside a ConfirmDialog used to race the dialog. + // Outside-click still uses the context stack, unchanged, on purpose. if (event.key !== "Tab" || !trapFocus) return; const focusable = Array.from( panelRef.current?.querySelectorAll(FOCUSABLE) ?? [] diff --git a/web/src/customer-grid/RecordDetail.tsx b/web/src/customer-grid/RecordDetail.tsx index e98d2172b433aa37532d10ab56045b8cfd20412d..c2d27da5a6b4a7b58850b2085b9840e290687220 100644 --- a/web/src/customer-grid/RecordDetail.tsx +++ b/web/src/customer-grid/RecordDetail.tsx @@ -1,10 +1,16 @@ -import { lazy, Suspense, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } - from "react"; +import { lazy, Suspense, useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, + useState } from "react"; import type { ReactNode, TextareaHTMLAttributes } from "react"; import { BodyPortal, useOverlayLayer } from "./OverlaySurface"; /** - * ⭐ WAVE-27 item 20 (R5 / contract C10) — the embedded grid a Details section renders. + * ⭐⭐ W51-T06 (R5, contract C6) — THE GRID A RELATED TAB MOUNTS. + * + * ⛔ IT IS NOT `LinkedGrid` AND IT IS NOT THE SAME MOUNT. Wave 27's `LinkedGrid` passed + * `embedded` + `embeddedRecordIds`: the whole target table fetched and filtered to an id list in + * the browser, with its view rail suppressed. R5 asks for the opposite of both halves — the + * OTHER DATABASE'S OWN SAVED VIEWS, rail included, over rows the SERVER already narrowed. So the + * identifier is gone with the props it carried, and what survives is the lazy mechanism. * * ⛔ LAZY BECAUSE THE IMPORT IS A CYCLE, not because it is big. `CustomerGrid` mounts * `RecordDetail`; a static import back the other way is `A -> B -> A`, which bundlers resolve by @@ -12,9 +18,9 @@ import { BodyPortal, useOverlayLayer } from "./OverlaySurface"; * module happens to evaluate first, i.e. the kind that survives every local test and lands in * production. `React.lazy` defers the resolution to first RENDER, by which point both modules * exist. It also composes with item 34's route-level splitting instead of fighting it: a reader - * who never opens a Details tab never downloads a second copy of anything. + * who never opens a related tab never downloads a second copy of anything. */ -const LinkedGrid = lazy(() => import("./CustomerGrid")); +const RelatedGrid = lazy(() => import("./CustomerGrid")); import { automationDetail, automationState, @@ -36,19 +42,20 @@ import { actionHref } from "./display"; import JsonViewer, { CodeViewer } from "./JsonViewer"; import { StarRow, StarIcon } from "./Stars"; import { AI_STATE_PREFIX, choiceOptions, codeLanguageOf, isPickType, mayEditField, ratingMax } from "./types"; -/* ⭐⭐ W41-T44 (owner instruction 25) — THE PIVOT'S VOCABULARY IS IMPORTED, NEVER RESTATED. - W41-T42 declared all of it in `types.ts` precisely because this ticket and W41-T43 open the - same feature through other doors and neither may edit that file. A second `buildPivotRequest` - inlined here would be a second opinion about what a pivot request is, and two spellings of one - wire contract is how a feature ships dead with both halves correct +/* ⭐⭐ W51-T06 (R2/R5, C6) — THE RELATED VOCABULARY IS IMPORTED, NEVER RESTATED, which is the + same discipline the retired pivot vocabulary was held to and for the same reason: `types.ts` + declares what a `/related` entry and a pinned read ARE, so this panel and `CustomerGrid` + cannot come to hold two opinions about one wire contract [[two-lanes-one-contract-dead-feature]]. */ -import { buildPivotRequest, emptyViewConfig, PIVOT_PATH, PIVOT_WINDOWS, PIVOT_WINDOW_LABELS, - pivotResponse, relationalTargets } from "./types"; -import type { CustomerDoc, DisplaySpec, Field, FilterRule, PivotResponse, PivotWindow, - Row, Viewer } from "./types"; -/* The pivot is a SERVER question (contract C10), so this panel needs the same two constants the - grid's own pivot fetch uses. One door, one credential mode. */ -import { API_V1, CREDENTIALS } from "../apiContract"; +import { CUSTOMER_TOPIC, PRODUCT_TOPIC, relatedTabs, topicForScope } from "./types"; +import type { CustomerDoc, DisplaySpec, Field, RelatedEntry, RelatedVia, Row, + Viewer } from "./types"; +/* ⭐ THE THREE DOORS THIS PANEL ASKS, ALL OF THEM ALREADY OWNED BY `apiBridge`: what is related + to this table, what the databases are called, and whether an edge's pinned read can be served + today. No `fetch` is written here — `apiBridge` owns the credential mode, the session handling + and the refusal reading, and a fourth copy of that in a drawer is how one surface stops + noticing an expired cookie. */ +import { fetchLinkTargets, fetchRelated, probeRelatedRead, readThroughTables } from "./apiBridge"; /** * ⭐⭐ WAVE-34 (owner ruling R13) — whose value sits in this enrichment cell, in words. @@ -333,74 +340,23 @@ function SixDots() { ); } -/* ══════════════════════════════════════════════════════════════════════════════════════════ - ⭐⭐ W41-T44 · OWNER INSTRUCTION 25 · RULING R12 · CONTRACTS C4 + C5 + C7 — - A RECORD PIVOTS TO ITS OWN RELATED RECORDS. - - Owner: *"opening a customer record offers Relational, and choosing Odoo Products shows only - that customer's ordered SKUs."* +/* ════════════════════════════════════════════════════════════════════════════════════════ + ⭐⭐ W51-T06 (R2/R5, contract C6) — THE RECORD-LEVEL PIVOT AND ITS BRIDGE CONSTANT ARE GONE, + AND WHAT REPLACED THEM IS SMALLER RATHER THAN LARGER. - ⛔⛔ THIS IS **NOT** `embeddedRecordIds`, AND THE DISTINCTION IS THE WHOLE TICKET. An embedded - grid FETCHES ITS WHOLE TABLE and filters to an id list in the browser (the note on `openLinks` - below states it, and it is why the link sections are collapsed until asked for). A record - pivot built that way would pull the entire product table into the tab to show one customer's - SKUs, which is standing rule 1 in the direction that matters: not a cap, but an uncapped - connected-source table dragged client-side to be filtered locally. The pivot's rows come from - contract C10's endpoint, server side, and this panel renders what comes back. + Wave 41 asked this panel to work out for itself which column of the record was an Odoo id, + build a one-leaf filter out of it, and post that to a pivot endpoint. Every one of those + three steps was the CLIENT deciding what is related to what, and the constant naming the two + bridge columns was the only place in the product where that answer was written down. - ⛔ NO JOIN IS COMPUTED HERE, for the same reason the grid computes none. Customers to products - is two hops through `sales_lines`, and the naive join (`sales_lines.product`) yields a column - of nulls that reads as "never sold". This names a source, a target, a link field and ONE - record; the resolution belongs to the server. - ══════════════════════════════════════════════════════════════════════════════════════════ */ - -/** - * ⛔⛔ CONTRACT C4's TWO BRIDGE COLUMNS, AND THIS CONSTANT IS THE ONLY PLACE THEY ARE SPELLED. - * - * C4: *"`product_data.product_id` ("Odoo ID", `type:int`) is the relational bridge, mirroring - * `customer_data.partner_id`. It is instruction 25's answer."* So the id a record pivots ON is - * its Odoo id, carried by one of exactly these two columns, and the order is the order the - * contract names them in. - * - * ⚠ `customer_data.partner_id` EXISTS TODAY (`odoo_customers.yml`, W33-T43, and its `identity` - * line says there is one id per row and no second one). `product_data.product_id` DOES NOT exist - * on this branch: it is C4's own server work and it is not lane D's. Until it lands, a product - * record finds no bridge here and this panel says so rather than sending a filter naming a - * column that is not there. - * - * ⛔ NOT `pid` AS A FALLBACK. A pid is the row identity, and the filter tree is compiled against - * DECLARED COLUMNS (`filter_sql.compile_filter_tree`); the pid set travels as `member_ids` on a - * different rail entirely. A leaf naming `pid` would be dropped on the way in, which is a filter - * that silently matches everything, which is every record's related rows presented as this one's. - */ -const RECORD_BRIDGE_KEYS = ["partner_id", "product_id"] as const; - -/** - * ⭐ THE ONE FILTER THAT NAMES THIS RECORD. T44's `how:` line calls the record pivot *"W41-T42's - * engine with a one-element member set"*, and this is that element: ONE leaf in the REQUEST, not - * one id list filtered in the client. - * - * ⚠ `null` MEANS "THIS TABLE HAS NO BRIDGE COLUMN, OR THIS RECORD'S IS BLANK", and it is refused - * rather than smoothed. An unfiltered pivot request would ask the server for the related records - * of the WHOLE table and this panel would present the answer under one record's name, which is a - * wrong answer rather than a missing one. - */ -function recordPivotFilter(fields: Field[], record: Row): FilterRule | null { - for (const key of RECORD_BRIDGE_KEYS) { - if (!fields.some((f) => f.key === key)) continue; - const value = record[key]; - /* ⛔ ZERO IS SKIPPED, AND IT IS NOT AN OFF-BY-ONE. An Odoo id is a positive integer, so `0` - here means the derived column produced nothing for this row, not that the record is id 0. - A leaf carrying `"0"` is an ACTIVE rule (only an EMPTY `value` is inactive), so it would be - sent, match nothing, and print "No related records for this record in this time window" -- - the one line reserved for a served answer of genuinely none. A wrong answer wearing the - shape of a true one is worse than the refusal below. */ - if (value === null || value === undefined || value === "") continue; - if (!(Number(value) > 0)) continue; - return { colId: key, op: "eq", value: String(value) }; - } - return null; -} + R2 moves the whole decision server-side: `GET /api/v1/grid/{table}/related` answers with the + forward links, the reverse links and the Odoo bridges this account may follow, and the read + takes `{table, record, via}` and compiles the pin into SQL. So the panel names an EDGE and + renders what comes back. There is no join here, no id to guess and no column to spell. + ⚠ `PIVOT_PATH`, `buildPivotRequest` and `pivotResponse` are NOT orphaned by this and stay in + `types.ts`: `CustomerGrid` still calls all three for the grid's own pivot region, which is a + different surface and is not this ticket's subject. + ════════════════════════════════════════════════════════════════════════════════════════ */ /** The record drawer's equivalent of the grid picker's `Add option` row. */ function ChoiceCreateInput({ @@ -444,24 +400,118 @@ function ChoiceCreateInput({ } /** - * ⭐ THE SAME FOUR STATES `CustomerGrid` KEEPS, AND THE SAME WORDS FOR THEM. `absent` is not an - * empty result: it is "the endpoint that answers this question is not there, or did not answer" - * (C10's server half is W41-T20). Collapsing it into a served answer of zero rows would put "no - * related records" on screen as the answer to a question nobody has asked yet. + * ⭐⭐ W51-T06 (R2/R5, C6) — THE FOUR STATES A **RELATED TAB** CAN BE IN, and they are the + * shape of the record view now that the record-level pivot and its endpoint are gone. * - * ⚠ Declared locally because `CustomerGrid`'s copy is a local type in that module and `types.ts` - * is closed to this ticket. It is the vocabulary that must not fork, and it has not: four names, - * same four meanings. + * ⛔ `refused` IS NOT AN EMPTY RESULT AND NOT AN ERROR SCREEN. It is a DECLARED edge whose + * pinned read cannot be served yet, carrying the SERVER's own sentence: `ut_odoo_invoices` is + * materialised rather than read through, so its door takes no predicate, and an ordinary user + * table's door (`routes_tables.table_rows`) takes none either. R6's second sentence makes that + * a REPORTED limit with a cause and a recommendation, never a tab that quietly shows nothing + * and never a tab that quietly shows EVERYTHING. + * ⚠ `ready` is the only state that mounts a grid. Collapsing `refused` into it would paint the + * whole target database under a chip that names one record. */ -type RecordPivotState = - | { status: "idle" } - | { status: "loading" } - | { status: "absent" } - | { status: "ok"; answer: PivotResponse }; +type RelatedTabState = + | { status: "probing" } + | { status: "ready" } + | { status: "refused"; reason: string }; + +/** + * ⭐ W51-T06 CLAUSE 9 — ONE HOP of the record view's navigation, carrying everything needed to + * render it. See the shadow note inside the component for why the row and the field contract + * travel with the pid instead of being fetched here. + */ +interface RecordFrame { + table: string; + pid: number; + label: string; + record: Row; + fields: Field[]; +} + +/** + * ⭐⭐ CLAUSE 10's STORE, AND IT IS `localStorage` BECAUSE R5 SAYS **"nothing new is stored"**. + * + * ⛔ THE VIEW ITSELF IS NOT STORED HERE, ONLY WHICH ONE WAS LAST OPEN. The views are the target + * database's own saved views, written through its own door; this remembers a reading position, + * per person, per browser, and no server record learns it. + * ⚠ Every access is wrapped: a private window, a full quota or a disabled store all throw from + * `localStorage` itself, and a record drawer that cannot open because a preference could not be + * read is a much worse defect than a preference that does not persist. + */ +/* ⚠ IT SHARES THE `aios-grid:` NAMESPACE WITH THE WORKSPACE BUCKETS AND CANNOT COLLIDE WITH + ONE, checked rather than assumed: `CustomerGrid::readLocal` keys on `aios-grid:${storageKey}` + and a real storage key is `_table_workspace`-shaped (or `local:`), neither of + which can spell `record-tab-views`. One prefix keeps the app's own keys findable in a browser + inspector; a second prefix would hide this one from whoever goes looking. */ +const TAB_VIEWS_KEY = "aios-grid:record-tab-views"; + +function readTabViews(): Record { + try { + const raw = localStorage.getItem(TAB_VIEWS_KEY); + if (!raw) return {}; + const parsed = JSON.parse(raw) as unknown; + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {}; + const out: Record = {}; + for (const [key, value] of Object.entries(parsed as Record)) + if (typeof value === "string" && value) out[key] = value; + return out; + } catch { + return {}; + } +} + +function writeTabViews(value: Record): void { + try { + localStorage.setItem(TAB_VIEWS_KEY, JSON.stringify(value)); + } catch { + /* a preference that cannot be written is a preference that does not persist, and nothing + more; the tab still opens on the database's own resolution. */ + } +} + +/** + * The renderer SCOPE a target table is drawn under. + * + * ⛔ IT READS THE TOPIC CONSTANTS RATHER THAN RESTATING THEIR STRINGS, and it does NOT import + * `CustomerGrid::scopeForLinkTable` even though that is the same mapping: a static import from + * this module into `CustomerGrid` is the `A -> B -> A` cycle the lazy mount at the top of this + * file exists to avoid, and it would leave one side `undefined` at module-evaluation time. The + * two registry modules are the only keys whose scope is not their own name, and the constants + * that say so are the same ones `topicForScope` answers from, so there is no second spelling. + */ +/** + * ⭐ THE ONE STATE WITH NO SERVER SENTENCE, AND IT IS DECLARED RATHER THAN IMPROVISED. + * + * `relations.py` authors a sentence for every refusal it can see: an unknown relation, an + * unreadable source value, a declared-but-unserved target. It cannot author one for "the + * read-through roster does not name this table on this deployment", because that is a fact about + * the CLIENT's read path rather than about the relation. So this is the fourth sentence, it + * exists for exactly one state, and it says the same three things the server's own do: what was + * asked, why it cannot be answered, and what to do instead. + * ⛔ NO EM DASH AND NO EN DASH: this reaches a screen (standing rule 2). + */ +function unpinnableNote(target: string): string { + return `'${target}' is not read through the live mirror on this deployment, so its rows door ` + + `takes no relation pin and these records cannot be narrowed to this one. Open that ` + + `database on its own and filter it there, or ask for its stored read to accept a pin`; +} + +function relatedScope(target: string): SurfaceScope { + if (target === CUSTOMER_TOPIC.key) return CUSTOMER_TOPIC.scope as SurfaceScope; + if (target === PRODUCT_TOPIC.key) return PRODUCT_TOPIC.scope as SurfaceScope; + return target as SurfaceScope; +} export default function RecordDetail({ - fields, - record, + /* ⭐⭐ W51-T06 CLAUSE 9 — THE HOST'S RECORD IS THE **BASE**, NOT NECESSARILY WHAT IS ON SCREEN. + Clicking a row in a related tab navigates this panel to that record, and a back arrow + returns. Renaming the two props and re-binding `fields` / `record` a dozen lines down is + what lets the ENTIRE body below stay unchanged: one place decides which record is being + rendered, rather than forty call sites each asking. */ + fields: baseFields, + record: baseRecord, titleKey, positionLabel, canPrev, @@ -489,7 +539,55 @@ export default function RecordDetail({ const panelRef = useRef(null); const titleId = useId(); const tabsId = useId(); - const title = String(record[titleKey] ?? "Untitled"); + /** + * ⭐⭐ W51-T06 CLAUSE 9 — THE NAVIGATION STACK, and it is a STACK rather than one slot because + * a related tab of a pushed record is itself navigable: customer -> order -> order line is one + * back arrow per hop, in the order they were taken. + * + * ⛔ IT IS CLEARED WHEN THE HOST CHANGES RECORD. `onPrev`/`onNext` move the BASE record under + * this panel; a stack left standing across that move would leave the reader looking at an + * order that belongs to the previous customer, with a back arrow to a record nobody is on. + */ + const [stack, setStack] = useState([]); + const frame = stack.length > 0 ? stack[stack.length - 1] : null; + /** + * ⛔⛔ THE SHADOW IS THE WHOLE MECHANISM, AND IT IS DELIBERATE RATHER THAN CLEVER. Every one of + * the ~40 references below (`renderRow`, the ordering, the editors, the viewers) reads `fields` + * and `record`; re-pointing them ONCE here is a four-line change, where threading a second pair + * through each of them would be forty places to get one of them wrong. + * ⚠ A PUSHED FRAME CARRIES ITS OWN FIELD CONTRACT, handed over by the grid that was already + * holding it (`CustomerGrid::openRecord`). This panel cannot resolve a row of another database + * on its own: that door takes no predicate, and a filter leaf naming `pid` is dropped on the + * way in, which is a filter that matches everything. + */ + const fields = frame ? frame.fields : baseFields; + const record = frame ? frame.record : baseRecord; + useEffect(() => { + setStack((prev) => (prev.length ? [] : prev)); + }, [baseRecord.pid, scope]); + /** + * ⭐ CLAUSE 9's FORWARD HALF. The row, the fields and the table all arrive from the grid that + * already had them; only the LABEL is derived here, and only from what came with the row. + * ⚠ `title` on a frame is the frame's own label: `titleKey` belongs to the base table and + * reading it off a foreign row answers "Untitled" for every one of them. + */ + const pushFrame = useCallback( + (pid: number, table: string, row?: Row, rowFields?: Field[]) => { + if (!row || !rowFields || rowFields.length === 0) return; + const first = rowFields[0]; + const named = first ? String(row[first.key] ?? "") : ""; + setStack((prev) => [...prev, { + table, + pid, + label: named || `Record ${pid}`, + record: row, + fields: rowFields, + }]); + }, + [] + ); + const popFrame = useCallback(() => setStack((prev) => prev.slice(0, -1)), []); + const title = frame ? frame.label : String(record[titleKey] ?? "Untitled"); // Wave 19 (item 12): `scope` joins the predicate — the comments rail addresses a server // endpoint per topic now, so a host that names no surface gets no rail rather than a rail // pointed at a guess. In practice CustomerGrid always names one; this is the fail-closed edge. @@ -565,7 +663,12 @@ export default function RecordDetail({ // `defaultOrder` is the whole vocabulary, so this is a PERMUTATION of it and nothing else — // a saved layout can reorder the panel, never change what is in it. See recordLayout.ts. - const orderedKeys = resolveFieldOrder(pendingOrder ?? recordLayout, defaultOrder); + /* ⚠ W51-T06 — THE SAVED ORDER BELONGS TO THE BASE TABLE. A pushed frame's fields are + another database's, so its stored order names none of them; `resolveFieldOrder` would + prune every key and answer the default anyway, and saying so here is cheaper than + leaving a reader to work out why a drag on a frame does nothing durable. */ + const orderedKeys = resolveFieldOrder( + frame ? undefined : (pendingOrder ?? recordLayout), defaultOrder); // The key being dragged, twice over, written only in `onDragStart`/`onDragEnd` and always // together. The REF is what the handlers read: `dragover` must call preventDefault for a @@ -599,175 +702,224 @@ export default function RecordDetail({ const commitOrder = (next: string[]) => { if (next === orderedKeys) return; // moveKey/nudgeKey return the input on a no-op + // ⛔ W51-T06 — A FRAME NEVER WRITES THE HOST'S LAYOUT. `recordLayout` is a per-user order + // for the BASE table; persisting a frame's arrangement into it would fill that preference + // with keys the base table does not have, which the resolver then prunes on every open. + if (frame) return; setPendingOrder(next); onRecordLayout?.(next); }; - // --- C-EMBED (item 13) — Fields | Insights --------------------------------------------- - // - // The owner's framing: in the record, the FILTER IS THE LOCK — you are looking at one - // customer, so the pid set is not a control, it is the premise. Hence `locked`, and hence a - // panel that is otherwise the same component the table mounts, with the same server, the - // same buckets and the same additivity rules. Two implementations of "sales by month" that - // could disagree is the thing worth avoiding here, not the duplicated markup. - // - // The display state is LOCAL and deliberately not persisted (v1): a bucket chosen while - // reading one customer is a way of looking, not a property of the record. `onDisplay` is - // passed all the same — the panel DISABLES its controls without one, and the contract says - // the controls stay live. - // No scope, no Insights — see the prop's note. `tab` is forced back rather than merely - // unreachable, so a host that stops supplying the scope mid-session cannot leave the modal - // showing a panel it can no longer address. - // ⭐ WAVE-27 item 20 (owner ruling R5, contract C10) — the tab is "Details" now, and the - // rename is the smaller half. It USED to be "Insights" and hold exactly one thing, a - // time-series panel; R5 makes it the record's whole relational context — every database this - // record LINKS to, rendered as a real grid of just its linked rows — with the time series - // demoted to one section among them. - const [tab, setTab] = useState<"fields" | "details">("fields"); - const canInsights = scope != null; - const activeTab = canInsights ? tab : "fields"; - // `mode: "timeseries"` is the only required member of DisplaySpec and it is a truthful one - // here: this IS the time-series reading of the record. Every other key is absent, which the - // panel reads as "use my defaults". - const [tsDisplay, setTsDisplay] = useState({ mode: "timeseries" }); - // ⚠ Memoised, not `[Number(record.pid)]` inline: the panel's fetch effect depends on `pids` - // by identity, so a fresh array every render would re-fetch on every render — forever. - const insightPids = useMemo(() => [Number(record.pid)], [record.pid]); - // wave17 item 5 — the same population as `insightPids`, as VALUES, so a snapshot metric can - // read this record's own numbers. Memoised for the identical reason the pid list is. - const insightRows = useMemo(() => [record], [record]); + /* ═══════════════════════════════════════════════════════════════════════════════════════ + ⭐⭐ W51-T06 · RULINGS R2 + R5 · CONTRACT C6 — + **FIELDS, THEN ONE TAB PER RELATED DATABASE, RESOLVED SERVER-SIDE.** + + R2: *"A 'Linked database' tab exists for FORWARD link fields, REVERSE links … and the ODOO + BRIDGES … one tab per related table, resolved server-side."* + R5: *"A related tab is the OTHER DATABASE'S OWN SAVED VIEWS plus the pinned record: its view + rail included … **nothing new is stored.**"* + + ⛔⛔ WHAT THIS REPLACES, AND WHY IT IS NOT THE SAME THING WEARING NEW WORDS. The Details tab + held two mechanisms, and both decided client-side what is related to what: + · `linkSections` mounted one EMBEDDED grid per link column, and an embedded grid fetches + its WHOLE table and filters to an id list in the browser. On a connected source that is + standing rule 1 in the direction that matters. + · the record pivot read a bridge column off the row, built a one-leaf filter out of it and + posted it to `grid/pivot` — the client naming a join. + Both are gone. The edges come from `GET /api/v1/grid/{table}/related`, already narrowed to + what this account may open, and the rows come from a read the SERVER pinned. + + ⭐ NOTHING NEW IS STORED, and that clause is load-bearing three times over: + 1. the pinned record is a PROP the filter bar draws, never a filter-tree leaf, so no saved + view on the target database is poisoned with one record's pin (clause 8); + 2. the views a related tab offers are the target database's OWN saved views, written + through its own door under its own permissions (clause 7); + 3. the last-opened view per tab lives in `localStorage`, per person, per browser + (clause 10) — no server record learns which tab anybody last looked at. + ═══════════════════════════════════════════════════════════════════════════════════════ */ + + /** The DATABASE this record lives in, as the wire spells it (`customer_data`, `ut_*`). */ + /* ⚠ IT FOLLOWS THE FRAME. A pushed record has its OWN related databases, so navigating + to an order and asking what an order is related to is the same code path as the first + hop, not a special case. */ + const recordTable = frame ? frame.table : topicForScope(scope ?? "customer").key; + /** - * ⭐ WAVE-27 item 20 (R5 / C10) — one section per LINK column on this record's table. - * - * ⚠ A link cell is a COMMA-JOINED LIST OF ROW IDS (the scalar `Row` contract — an array cell - * cannot exist here), parsed exactly the way `CustomerGrid`'s own link modal parses it: trim, - * to number, keep positive integers, de-duplicate. A second parse that disagreed about a - * trailing comma would show a different set of records than the picker just wrote. - * - * ⚠ A link with NO TARGET TABLE is skipped rather than rendered empty. `_clean_field` refuses - * a `link` without its bag, so this can only be a definition older than that rule — and an - * embedded grid of `scope: ""` would fetch the customer table and present somebody else's - * records under this column's name. + * R2's answer for this table. Empty until it arrives and empty on any failure, which is the + * honest degradation: a record whose relations cannot be listed still opens on its Fields tab. + */ + const [entries, setEntries] = useState([]); + /** + * ⭐ CLAUSE 2's OTHER HALF — `target key -> the DATABASE's own name`. * - * Memoised: `embeddedRecordIds` is read by identity inside the grid's own row projection, so a - * fresh array per render would re-project on every keystroke in the drawer. + * ⛔ THE `/related` ENTRY'S OWN `label` IS NOT IT, measured in `relations.py` rather than + * assumed: a FORWARD entry is labelled with the FIELD's label, which is exactly what clause 2 + * wants as the SUBTITLE. The roster behind the link picker (`GET /tables?brief=1`) is the one + * producer of a database's display name in this product, so the name comes from there and the + * entry's own label is only the fallback. */ + const [tableLabels, setTableLabels] = useState>({}); + useEffect(() => { + // No scope, no tabs: the same fail-closed edge the comments rail takes. A pid means nothing + // without the table it belongs to, and guessing one asks a question nobody asked. + if (scope == null) { + setEntries([]); + return; + } + let live = true; + void fetchRelated(recordTable).then((got) => { + if (live) setEntries(got); + }); + void fetchLinkTargets().then((targets) => { + if (!live) return; + const map: Record = {}; + for (const target of targets) map[target.key] = target.label; + setTableLabels(map); + }); + return () => { + live = false; + }; + }, [scope, recordTable]); + + /** Clause 1 + clause 2 — the tab strip, in the server's order (forward, reverse, bridge). */ + const tabs = useMemo( + () => relatedTabs(entries, (target) => tableLabels[target] ?? ""), + [entries, tableLabels] + ); + /** - * ⭐ WAVE-27 item 20 — which Details sections have been OPENED. + * Which tab is open, by EDGE KEY. `"fields"` is the default and the fallback: a tab whose edge + * has disappeared (a link column deleted while the drawer was open) drops back to Fields + * rather than rendering a panel for an edge that is no longer offered. + */ + const [tab, setTab] = useState("fields"); + const activeTab = tabs.some((entry) => entry.entry.key === tab) ? tab : "fields"; + const activeRelated = tabs.find((entry) => entry.entry.key === activeTab) ?? null; + + /** + * ⭐⭐ CLAUSE 10 — THE LAST-OPENED VIEW **PER TAB**, PER PERSON, IN `localStorage`. * - * ⛔ THE SECTIONS ARE COLLAPSED UNTIL ASKED FOR, and that is a correctness decision as much - * as a performance one. An embedded grid FETCHES ITS WHOLE TABLE and filters to - * `embeddedRecordIds` client-side (`CustomerGrid.tsx:621-628`) — so on an Instagram profile, - * whose preset carries FOUR link columns (`posts_link`, `profile_snapshots_link`, - * `post_snapshots_link`, `comments_link`), opening this tab would mount four glide canvases - * and pull four tables, two of them append-only snapshot tables. The count in each heading is - * already known WITHOUT the grid (it is the length of the parsed id list), so a collapsed - * section still tells you what is in it. + * ⛔ PER TAB, NOT PER DATABASE. R2 gives two links between the same pair two tabs, so two tabs + * can point at one database; a memory keyed by the target alone would make each of them reopen + * on the other's view. The key is `:`, and the EDGE KEY is what makes it + * unique: `relations._entry`'s own note says the entry key is the only member of `via` that + * identifies an edge on its own, precisely because `{direction, on}` does not. + * ⚠ `writeTabViews` runs inside the updater rather than beside it, so the write and the + * decision that there IS something to write are one expression. Under StrictMode the updater + * is invoked twice in development, which writes the same value twice; the write is idempotent + * and that is cheaper than a second effect whose only job is to mirror this state. */ - const [openLinks, setOpenLinks] = useState>(new Set()); - const linkSections = useMemo( - () => - fields - .filter((f) => f.type === "link" && typeof f.link?.table === "string" && f.link.table) - .map((f) => ({ - field: f, - table: f.link!.table as SurfaceScope, - ids: [...new Set( - String(record[f.key] ?? "") - .split(",") - .map((part) => Number(part.trim())) - .filter((pid) => Number.isInteger(pid) && pid > 0) - )], - })), - [fields, record] + const [tabViews, setTabViews] = useState>(readTabViews); + const tabViewKey = activeRelated ? `${recordTable}:${activeRelated.entry.key}` : ""; + const rememberTabView = useCallback( + (viewId: string) => { + if (!tabViewKey) return; + setTabViews((prev) => { + // ⛔ THE SAME OBJECT ON A NO-OP. This callback fires from an effect in the mounted grid + // that depends on the view id; returning a fresh map for an unchanged value would + // re-render this panel, re-create the prop, and re-run that effect. React bails out on + // identity, so identity is what has to be preserved. + if (prev[tabViewKey] === viewId) return prev; + const next = { ...prev, [tabViewKey]: viewId }; + writeTabViews(next); + return next; + }); + }, + [tabViewKey] ); - /* ⭐⭐ W41-T44 — THE RECORD-LEVEL PIVOT'S STATE. Four hooks, all at the top level of this - component and all above its single `return` (there is no early return in this body, which - is checked rather than assumed: a hook after one runs a different number of times on the - two renders and React #310 takes the surface down [[react-hooks-order-gate]]). */ - /** R9 — what this record can pivot to IS its table's link fields. `relationalTargets` is the - * ONE derivation and the grid's toolbar uses the same one. */ - const relTargets = useMemo(() => relationalTargets(fields), [fields]); /** - * ⭐ COLLAPSED UNTIL ASKED FOR, following the link sections' own precedent one block up, and - * for the reason that note gives: opening the Details tab must not fire work for a section - * nobody looked at. A pivot is a server join; firing one per record opened would be the same - * mistake the link sections were written to avoid, one rail over. + * ⭐ CLAUSE 6 — THE PIN, and it is the whole of what makes these rows this record's. + * + * ⚠ MEMOISED ON A SERIALISED KEY. The grid takes this as an effect dependency; a fresh object + * per render would re-read on every keystroke in the drawer. */ - const [relOpen, setRelOpen] = useState(false); - const [relVia, setRelVia] = useState(null); - /** R10 — all time is the default AND the meaning of an absent value. */ - const [relWindow, setRelWindow] = useState("all"); - const [relPivot, setRelPivot] = useState({ status: "idle" }); - const relTarget = relVia ? relTargets.find((t) => t.viaField === relVia) ?? null : null; - const relFilter = recordPivotFilter(fields, record); + const relatedPinKey = activeRelated + ? JSON.stringify({ + table: recordTable, + record: Number(record.pid), + via: activeRelated.entry.via, + label: title, + }) + : ""; + const relatedPin = useMemo( + () => (relatedPinKey + ? (JSON.parse(relatedPinKey) as + { table: string; record: number; via: RelatedVia; label: string }) + : null), + [relatedPinKey] + ); + /** - * The request, serialised, as BOTH the effect's dependency and its body — the grid's own - * pattern, for its own reason: one string, so a re-render that changes nothing cannot re-fire - * the fetch and the body can never disagree with the key that decided to send it. + * ⭐⭐ CAN THIS EDGE BE SERVED, AND IF NOT, IN WHOSE WORDS? See `RelatedTabState`. * - * ⚠ EMPTY UNLESS ALL FOUR HOLD: the section is open, a target is chosen, the host said which - * surface this is, and the record has a C4 bridge id. Each missing one has its own line on - * screen; none of them is a reason to ask the server anything. + * ⛔ TWO REASONS A DECLARED EDGE CANNOT BE PINNED TODAY, AND THE CLIENT CAN ONLY SEE ONE OF + * THEM ON ITS OWN. `served: false` is carried by the entry (`ut_odoo_invoices` is materialised + * and absent from `GRID_SOURCES`); the second is a target that is not read through at all, + * which `odoo-tables/status` answers and the entry does not. Both end in the same place: ask + * the pinned door for ONE row and print the sentence it refuses with. + * ⛔ THE SENTENCE IS THE SERVER'S, NOT THIS FILE'S. `relations.py` writes three of them, each + * naming a cause and a recommendation (R6's second sentence). A fourth spelled here would be a + * second opinion about one wire contract. + * + * ⛔⛔ THE **ROSTER** DECIDES WHETHER THE TAB MOUNTS. THE PROBE ONLY SUPPLIES WORDS, AND AN + * EARLIER DRAFT HAD THIS INVERTED WITH A WHOLE-DATABASE BUG IN IT. + * The mount has to be gated on THE SAME FACT THE READ CONSULTS, and the read consults + * `readThroughTables()` (`useCustomerData`: the pin reaches the server only for a `ut_*` scope + * that roster names). The probe asks a DIFFERENT question of a DIFFERENT door. Those two come + * apart on one flaky `odoo-tables/status` call, which fails SOFT to the empty set by design: + * the roster would answer "not read through", the genuinely-served orders door would answer + * 200 to the probe, the tab would mount `ready`, and `useCustomerData` would fall back to the + * whole-book read. The result is the ENTIRE orders table painted under a chip that reads + * "Linked to " - a wrong answer wearing the right chrome, which is exactly the + * failure class this ticket exists to delete. + * ⇒ Not pinnable by the roster ⇒ REFUSED, whatever the probe says. The probe's only job is to + * fetch the server's sentence for the state, and `unpinnableNote` covers the one state that + * has no server sentence (the roster says no while the door answers 200). */ - const relRequestBody = - relOpen && relTarget && relFilter && scope - ? JSON.stringify( - buildPivotRequest(scope, [relFilter], "and", { - database: relTarget.database, - viaField: relTarget.viaField, - window: relWindow, - config: emptyViewConfig(), - }) - ) - : ""; + const [tabState, setTabState] = useState({ status: "probing" }); useEffect(() => { - if (!relRequestBody) { - setRelPivot({ status: "idle" }); + if (!activeRelated || !relatedPin) { + setTabState({ status: "probing" }); return; } let live = true; - setRelPivot({ status: "loading" }); - (async () => { - try { - const res = await fetch(`${API_V1}/${PIVOT_PATH}`, { - method: "POST", - credentials: CREDENTIALS, - headers: { "Content-Type": "application/json" }, - body: relRequestBody, - }); - if (!live) return; - if (!res.ok) { - setRelPivot({ status: "absent" }); - return; - } - const answer = pivotResponse(await res.json().catch(() => null)); - if (!live) return; - /* ⛔ `null` is NOT smoothed into an empty answer: "the endpoint is not there" and "this - record has no related records" are different facts and only one is ours to state. */ - setRelPivot(answer ? { status: "ok", answer } : { status: "absent" }); - } catch { - if (live) setRelPivot({ status: "absent" }); + setTabState({ status: "probing" }); + const target = activeRelated.entry.target; + const pin = { table: relatedPin.table, record: relatedPin.record, via: relatedPin.via }; + void (async () => { + const through = await readThroughTables(); + if (!live) return; + // ⛔ THE ONE MOUNT CONDITION, and it is the read path's own. See the note above. + const pinnable = activeRelated.entry.served && through.has(target); + if (pinnable) { + setTabState({ status: "ready" }); + return; } + const reason = await probeRelatedRead(target, pin); + if (!live) return; + setTabState({ status: "refused", reason: reason ?? unpinnableNote(target) }); })(); return () => { live = false; }; - }, [relRequestBody]); - /* The four non-served states, kept apart in LOGIC as well as in copy, because collapsing any - two of them puts a wrong answer on screen where a missing one belongs. Ordinary values, not - hooks: they are re-derived every render from `relPivot` and nothing memoises usefully. */ - const relAnswer = relPivot.status === "ok" ? relPivot.answer : null; - const relRefusal = relAnswer?.refusal ?? null; - const relServed = !!relAnswer && !relRefusal && relAnswer.fields.length > 0; - /** Served, and carrying no shape to paint. Every other branch is false here, so it needs its - * own line or the reader gets a chooser and silence. */ - const relColumnless = !!relAnswer && !relRefusal && relAnswer.fields.length === 0; - const relColumns = relServed && relAnswer ? relAnswer.fields : []; - /** ⛔ STANDING RULE 1's SECOND HALF. This panel truncates nothing, so a gap between the count - * and the rows can only have come from the server, and it is REPORTED rather than absorbed. */ - const relShort = !!relAnswer && relAnswer.targetCount > relAnswer.rows.length; + }, [activeRelated, relatedPin]); + + /* ⭐ The time series KEEPS ITS SURFACE. R5 replaces the Details tab with the related tabs and + says nothing about retiring the record's own time series, and deleting a working panel + because its container was renamed would be this ticket removing behaviour nobody asked it + to remove. It moves to the foot of the Fields tab, which is where the record's own data + already lives. */ + // `mode: "timeseries"` is the only required member of DisplaySpec and it is a truthful one + // here: this IS the time-series reading of the record. Every other key is absent, which the + // panel reads as "use my defaults". + const [tsDisplay, setTsDisplay] = useState({ mode: "timeseries" }); + // ⚠ Memoised, not `[Number(record.pid)]` inline: the panel's fetch effect depends on `pids` + // by identity, so a fresh array every render would re-fetch on every render — forever. + const insightPids = useMemo(() => [Number(record.pid)], [record.pid]); + // wave17 item 5 — the same population as `insightPids`, as VALUES, so a snapshot metric can + // read this record's own numbers. Memoised for the identical reason the pid list is. + const insightRows = useMemo(() => [record], [record]); /** * The six-dot handle. `draggable` sits HERE and not on the row: a draggable ancestor @@ -830,7 +982,12 @@ export default function RecordDetail({ // ONE verdict, `types.mayEditField` — stratum + read-only-by-nature + permissions. // No second permission test anywhere below: a `formula` or `created_time` field must stay // read-only after item 9, and that is this function's answer, not a type check of mine. - const mayEdit = mayEditField(field, viewer); + /* ⛔⛔ W51-T06 CLAUSE 9 — A PUSHED FRAME IS READ-ONLY, AND IT HAS TO BE. Every write door + this panel owns (`onNotesChange`, `onNotesCommit`, `onChoiceAdded`) was handed over by the + host for the BASE record's table; firing one from a frame would PATCH a customer's column + with an order's value, on a door that answers 200. The field permission wall still runs + underneath this for the base record; nothing here loosens it. */ + const mayEdit = !frame && mayEditField(field, viewer); // The ONE exception, and it is a vocabulary problem rather than a permission one: a `user` // field with no supplied people has nothing to offer, so it reads rather than pretends. const noVocabulary = field.type === "user" && !userOptions?.length; @@ -1434,6 +1591,25 @@ export default function RecordDetail({ >
+ {/* ⭐⭐ W51-T06 CLAUSE 9 — THE BACK ARROW, AND IT **REPLACES** PREV/NEXT RATHER THAN + JOINING THEM. Prev/next walk the HOST grid's row order, which a pushed record is + not in: offering them here would move the base record silently underneath the + one on screen. One way in, one way out, and the way out is the way back. + ⚠ The glyph is the same `‹` the previous-record key uses, on purpose: this is + the same gesture (go back one) reading the same direction, and inventing a second + arrow shape for it would make two controls out of one idea. */} + {frame ? ( + + ) : ( + <> + + )} {/* ⭐⭐ W35-T29 (R5, R6) — THE SAME RECORD STAR AS THE GRID'S, in the drawer. ⛔ THE SAME STATE, NOT A SECOND ONE: `starred`/`onStar` come from the grid's own `useRecordStars`, so starring here and starring in the row are one act on one list. @@ -1467,8 +1645,12 @@ export default function RecordDetail({ star floated alone in the middle of the bar, attached to nothing. Owner: *"the 'Star record' place is so out of placed there. Put it just beside the < > under record detail."* Inside `.cg-detail-nav` it is one of three 28px keys, and the - position caption reads after them. */} - {onStar && ( + position caption reads after them. + ⚠ W51-T06 — AND NOT ON A PUSHED FRAME. The star belongs to the record this + drawer was opened for; painted over a frame it would star the customer while the + reader is looking at one of their orders, which is a write nobody asked for on a + record nobody is on. */} + {!frame && onStar && ( )} - {positionLabel} + {/* ⚠ W51-T06 — the caption counts the HOST grid's rows, so a pushed frame has + no position in it and says nothing rather than a number about somewhere else. */} + {frame ? "" : positionLabel}
- {/* C-EMBED (item 13) — the two ways of reading one record. This row is also - what the interleaved field list lost when its two section headings went - (see C-LAYOUT's amendment): the label for the list as a whole. */} - {canInsights && ( + {/* ⭐⭐ W51-T06 CLAUSE 1 + CLAUSE 2 — FIELDS, THEN ONE TAB PER `/related` ENTRY. + ⛔ ONE TAB PER EDGE, NOT PER TARGET, and R2 says so in as many words: two links + between the same pair give two tabs. The strip is keyed by the EDGE key, which + is the only thing that is unique when two of them point at one database. + ⭐ THE LABEL IS THE TARGET DATABASE'S NAME; the field appears as a SUBTITLE and + only where it is doing work (two edges, one target). A second line under a tab + that has no sibling would be over-explaining (DESIGN section 4). + ⚠ A `served: false` tab IS IN THIS STRIP. A declared relation that cannot be + pinned yet is a REPORTED limit, and hiding it would make the limit invisible + rather than absent. */} + {tabs.length > 0 && (
- {(["fields", "details"] as const).map((key) => ( + + {tabs.map((entry) => ( ))}
@@ -1527,314 +1733,53 @@ export default function RecordDetail({
0 ? "tabpanel" : undefined} + aria-labelledby={tabs.length > 0 ? `${tabsId}-${activeTab}` : undefined} > - {activeTab === "details" && scope ? ( -
- {/* ⭐ WAVE-27 item 20 (R5 / C10) — ONE SECTION PER LINK FIELD, each an embedded - grid of the linked database showing exactly this record's linked rows. - - ⚠ THE ROWS ARE THE PREMISE, NOT A FILTER, which is the same idea `locked` - states for the time series below: you are reading ONE record, so "which rows" - is settled by the record and the embedded grid's toolbar narrows within them. - `embeddedRecordIds` is the projection that already enforces that - (`CustomerGrid.tsx:621-628`), so nothing new decides it here. */} - {linkSections.map((sec) => ( -
-

- {sec.ids.length === 0 ? ( - {sec.field.label} - ) : ( - - )} - - {sec.ids.length.toLocaleString()}{" "} - {sec.ids.length === 1 ? "record" : "records"} - -

- {sec.ids.length === 0 ? ( - // Stated, never an empty grid. An embedded grid of nothing looks like a - // surface that failed to load; a sentence says which of the two it is. -

- Nothing linked yet. Open the {sec.field.label} cell on the Fields tab to - link records. + {activeRelated && relatedPin && scope ? ( +

+ {/* ⭐⭐ CLAUSES 4 + 6 + 7 — THE TARGET DATABASE'S OWN GRID, over rows the SERVER + narrowed to this record. + ⛔ NO `embedded` AND NO `embeddedRecordIds`. That pair is the mode that hides + the view rail and pulls the whole table into the browser to filter it there; + R5 asks for the target's own saved views WITH the rail, over a pre-filtered + read. Passing `related` and passing `embedded` are mutually exclusive by + design, and this mount passes only the first. + ⛔ THE GRID IS THE PANEL, not a card inside one. DESIGN section 4 allows ONE + containment layer and the drawer is already it; a bordered box around a grid + inside a drawer inside a modal is the card-in-card the section names. */} + {tabState.status === "refused" ? ( + /* ⭐ R6's SECOND SENTENCE — the limit, its cause and what to do instead, in the + SERVER's words. `role="status"` rather than `alert`: a declared relation that + is not served yet is a reported boundary, not a failure. */ +

{tabState.reason}

+ ) : tabState.status === "probing" ? ( + /* Owner R6 — one small bare rotating mark, NO WORDS on screen. The `aria-label` + is not a word on screen and stays, or the wait is announced as nothing at all + (C-SPIN). */ +

+ +

+ ) : ( + +

- ) : !openLinks.has(sec.field.key) ? null : ( -
- {/* ⚠ LAZY, and it is load-bearing rather than a performance nicety: - `CustomerGrid` mounts THIS component, so a static import here would be - a module cycle. `React.lazy` breaks it at the module graph (the import - only resolves when a section actually renders) and composes with the - route-level splitting rather than fighting it. */} - {/* ⛔ THE SHARED MARK, NEVER A SENTENCE (owner R6, and `verify_icons` - enforces it across every source file — it caught a "Loading…" here on - this gate's first run). `aria-label` is REQUIRED by C-SPIN: "no words" - means no words ON SCREEN, and deleting the label would take the wait - away from a screen reader entirely. */} - - -
- } - > - {/* ⛔ ONE ATTRIBUTE IS MISSING ON PURPOSE AND IT IS THE VIEW-KIND - SWITCHER — `embeddedMode="browse"`. R5 asks for the FULL switcher - here; `CustomerGrid.tsx:4113` suppresses the mode control for every - embedded grid (`serverWindowed || embedded ? undefined : …`), so the - prop that distinguishes a BROWSE embed from the link PICKER embed - does not exist yet. It is requested as dated amendment A3 to contract - C10 in the wave-27 split doc (SESSION C owns `CustomerGrid.tsx`). - - Everything else in this section is already correct — the target - table, the pinned rows and the toolbar all work today — so this ships - useful rather than waiting. When the prop lands, this becomes one - added line and nothing else moves. It is deliberately NOT smuggled in - through a cast: a spread that passed an unknown prop would typecheck - forever and silently do nothing, which is the failure mode this wave - keeps paying for. */} - -
-
- )} -
- ))} - {/* ⭐⭐ W41-T44 (owner instruction 25, R12, contracts C4/C5/C7) — RELATIONAL. - It mounts BESIDE the link sections and wears their shape: a section, a - disclosure heading with a count, and nothing rendered until it is asked for. - DESIGN §4, new nav joins the existing rhythm rather than inventing a control - shape, so the choices are the same `.cg-radio-row` rows the toolbar's own - Relational popover uses (`Toolbar.tsx`) and not a second kind of picker. */} -
-

- {relTargets.length === 0 ? ( - Related - ) : ( - - )} - - {relTargets.length.toLocaleString()}{" "} - {relTargets.length === 1 ? "database" : "databases"} - -

- {relTargets.length === 0 ? ( - /* ⚠ AN EMPTY OFFER IS A TRUTHFUL ANSWER, not a failure: R9 derives the offer - from this table's LINK FIELDS and this one has none yet. Said in a sentence, - never as a chooser with nothing in it. */ -

- No related database yet. Add a Link column on this table to pivot to one. -

- ) : !relOpen ? null : ( -
-
Related database
- - {relTargets.map((t) => ( - - ))} - {/* R10 — the window belongs to the PIVOT, not to the target, so it exists - only once a target is chosen. A window with no relation to apply it to - is a control that cannot mean anything. */} - {relTarget && ( - <> -
Time window
- {PIVOT_WINDOWS.map((w) => ( - - ))} - - )} - - {relTarget && !relFilter && ( - /* ⛔ CONTRACT C4 — NO BRIDGE ID, NO REQUEST. Refused rather than sent - unfiltered: a pivot with no leaf naming this record would return the - whole table's related rows and this panel would present them under one - record's name, which is a wrong answer rather than a missing one. Two - causes land here (the table has no Odoo ID column, or this record's is - blank) and the sentence covers both without claiming either. */ -

- This record carries no Odoo ID, so there is nothing to match its related - records on. -

- )} - - {relPivot.status === "loading" && ( - /* wave17 GRID item 3 / owner R6: one small bare rotating icon, NO WORDS. - `aria-label` is not a word on screen and stays, because `.lp-spin` is an - empty span and the wait would otherwise be announced as nothing at all - (C-SPIN). No `--lg`: the mark sits inside a section, not alone on a - surface. */ -

- -

- )} - - {relRefusal && ( - /* ⛔ C10's REFUSAL, SAID OUT LOUD, and `subject` is ON SCREEN because it - names WHICH database the wall stands in front of, which is the one thing - the reader can go and ask for. The `reason` is the server's word: only - it knows which wall it hit, and a sentence authored here would be this - panel guessing. An empty result in this slot would read as "no related - records", which is a wrong answer where "you may not see this" is the - true one. */ -

- {relRefusal.subject - ? `${relRefusal.subject}: ${relRefusal.reason}` - : relRefusal.reason} -

- )} - - {relPivot.status === "absent" && ( - /* ⛔⛔ NOTHING, PLUS ONE LINE. C10's endpoint is W41-T20 and it is not on - this branch. An absent answer means "not built yet", never "false", and - never an empty table. Same sentence as the grid's, deliberately: two - spellings of one state is two states to the reader. */ -

- The related view is not available yet, so there is nothing to show. -

- )} - - {relColumnless && ( -

- The related view answered with no columns, so there is nothing to lay out - yet. -

- )} - - {relServed && relAnswer && ( -
") : undefined} - > - - {`This record to ${relTarget?.label ?? ""}`} - - - {`${relAnswer.targetCount.toLocaleString()} ` + - `${relTarget?.label ?? "records"}`} - - {PIVOT_WINDOW_LABELS[relWindow]} -
- )} - - {relServed && relAnswer && relAnswer.rows.length === 0 && ( - /* ⭐ THE ONLY STATE ENTITLED TO SAY THIS. The endpoint answered, it was - allowed to answer, and the answer is none. */ -

- No related records for this record in this time window. -

- )} - - {relServed && relAnswer && relAnswer.rows.length > 0 && ( -
- - - - {relColumns.map((f) => ( - - ))} - - - - {/* ⛔ STANDING RULE 1 — every row the server sent is painted. No - slice, no window, no client cap on connected-source data. */} - {relAnswer.rows.map((row, i) => ( - - {relColumns.map((f) => { - const cell = row[f.key]; - /* A BLANK IS A BLANK: null and undefined print nothing rather - than the words "null" or a 0 that then reads as a figure. */ - return ( - - ); - })} - - ))} - -
- {f.label} -
- {cell === null || cell === undefined ? "" : String(cell)} -
-
- )} - - {relShort && relAnswer && ( -

- {`Showing ${relAnswer.rows.length.toLocaleString()} of ` + - `${relAnswer.targetCount.toLocaleString()}. The server sent fewer ` + - `records than it counted and did not say why. The pivot endpoint ` + - `should report the cause of that limit and how to lift it.`} -

- )} -
- )} -
- {/* The time series STAYS, as ONE section (R5's own wording). `locked` says the pid - set is the PREMISE, not a control: you are reading one customer, so the filter - surface is the record itself (the owner's words). The panel keeps its own - bucket/span/field controls live against local state. */} -
- setTsDisplay((d) => ({ ...d, ...next }))} - locked - /> -
+ } + > + + + )}
) : ( <> @@ -1848,8 +1793,12 @@ export default function RecordDetail({ {/* Wave-8 I12c (C5) — Documents. Rendered only when the host actually serves them: a section with a dead upload control on a deployment - that has no document storage would be a promise the app cannot keep. */} - {onDocAdd && onDocFetch && onDocDelete && ( + that has no document storage would be a promise the app cannot keep. + ⚠ W51-T06 — AND ONLY ON THE HOST'S OWN RECORD (`!frame`). The document handlers + belong to the record this drawer was opened for; a pushed frame is a row of another + database, and feeding its pid to them would file one record's upload against + another's. */} + {!frame && onDocAdd && onDocFetch && onDocDelete && ( )} + + {/* ⭐⭐ W51-T06 — THE TIME SERIES KEEPS ITS SURFACE, at the foot of the Fields tab. + ⛔ IT DID NOT GO WITH THE DETAILS TAB, and that is a decision rather than an + oversight. The done-when deletes the TAB and its two client-side relation + mechanisms; the time series is neither, it answers a question about THIS record's + own numbers, and removing a working panel because its container was renamed would + be this ticket taking away behaviour nobody asked it to take away. + `locked` says the pid set is the PREMISE, not a control: you are reading one + record, so the filter surface is the record itself (the owner's words). + ⚠ NOT ON A PUSHED FRAME: the panel addresses an endpoint per SCOPE, and this + drawer's scope is the host record's. A frame's pid sent under it would ask the + customer endpoint about an order id and be answered, plausibly and wrongly. */} + {!frame && scope != null && ( +
+ setTsDisplay((d) => ({ ...d, ...next }))} + locked + /> +
+ )} )}
@@ -1871,7 +1847,10 @@ export default function RecordDetail({ a key that only changed on the number would REUSE this component across a surface switch, painting one record's comments under another's name until the fetch returned. */} - {showComments && scope != null && ( + {/* ⚠ W51-T06 — NOT ON A PUSHED FRAME. The rail addresses an endpoint per + scope+pid, and this drawer's scope is the HOST record's; a frame's pid under it + would ask the customer endpoint about an order id and be answered. */} + {!frame && showComments && scope != null && ( (null); + /* ⭐⭐ W51-T28 / R6 — THE PENDING DELETE IS HOISTED TO THE COMPONENT, AND THAT IS THE WHOLE + TRICK. Both row menus close themselves (`setMenu(null)`) in the same handler that used to + raise `window.confirm`, and each menu is a conditional subtree + (`{menu && menu.id === item.id && (`). A dialog rendered inside that + subtree unmounts in the same commit and the person sees nothing at all. So the menu records + WHAT was asked for, and the dialog is mounted from the component's own returned JSX, outside + every menu conditional and outside `renderLevel`. + ⚠ ONE state serves both deletes because it is DISCRIMINATED. Two booleans would let a folder + delete and a route delete be pending at once, which is two dialogs on one screen. */ + const [pendingDelete, setPendingDelete] = useState< + | { kind: "folder"; folder: MapRouteFolderDto } + | { kind: "route"; item: MapRouteDto } + | null + >(null); const [renameId, setRenameId] = useState(null); const [busy, setBusy] = useState(false); const [deliveryMapsPerLink, setDeliveryMapsPerLink] = useState(10); @@ -944,6 +961,37 @@ export function RouteNav({ routes, folders, selectedIds, activeRouteId, sources, const timerLabel = !dragging && settledLabel ? settledLabel : estimateLabel; const timerTone = !dragging && routeAnswer ? routeTimeTone(routeAnswer.current) : "estimated"; + /* ═════════ W51-T28 / C8 — ESCAPE BACKS OUT OF AN OPEN SAVED ROUTE ══════════════════════ + * + * ⭐ THE LADDER THIS COMPLETES, TOP DOWN: the kit dialog, then the open Route, then the map + * NAVIGATOR itself. The third rung is genuinely unreachable from this file and from MapView: + * `mapNavigator === "routes"` is `routePanelOpen && !zoneNavigatorOpen`, and `routePanelOpen` + * is `useState` in `CustomerGrid.tsx:3206` handed down as a read-only prop with no close + * callback and no event channel. An optional prop nobody passes, or a client-side emit with no + * listener, would each look exactly like a working close to a source scan while doing nothing + * at all, so neither is here and no gate leg claims the rung. + * + * ⛔ THE CLAIM IS DROPPED WHILE THE TITLE IS BEING RENAMED, and that is not fussiness. The + * arbiter's listener is CAPTURE PHASE on `document` and calls `stopPropagation`, so it runs + * ahead of React's own handlers and the rename input's `Escape`-cancels-the-draft would simply + * never fire again. Standing down while `titleDraft` is live leaves that behaviour exactly as + * it shipped, and one Escape still means one close everywhere else. + * + * ⛔ `!deleteConfirm` IS THE SAME RULE APPLIED TO THE OTHER LIVE OVERLAY IN THIS PANEL. The + * inline `role="alertdialog"` delete confirm below does not register with the arbiter and is + * deliberately left as it is, because `verify_w44_map_routes.py`'s `route-update-delete` leg + * pins that markup. Without this term Escape would resolve past it and close the whole Route + * out from under an open confirm, which is a behaviour this ticket would have INTRODUCED. + * ⚠ AND IT IS REACHED, THOUGH A GREP SAYS OTHERWISE. `grep deleteConfirm` finds no setter, + * because the setter is `setDeleteConfirm` and the capital D breaks the substring; `Delete + * Route` calls it, so that confirm really does open. + * + * ⚠ `cancelEditFirst` STAYS FALSE, matching the two Zone panels. One press, one close, which is + * what every other overlay in this app already does. + */ + const backToRoutes = useCallback(() => onActiveRouteChange(null), [onActiveRouteChange]); + useEscapeClose(route !== null && titleDraft === null && !deleteConfirm, backToRoutes); + if (route) { // ⭐ W46-T25 / RULING R2's guard stood here: a Route projected from a legacy `route_order` // column was refused until an administrator migrated it, because unlocking an unmigrated one @@ -980,7 +1028,7 @@ export function RouteNav({ routes, folders, selectedIds, activeRouteId, sources, }; return (
- {/* ── W46-T23 / INSTRUCTION 19: THE ONE PLACE A ROUTE IS RENAMED. ────────────── @@ -1725,7 +1773,7 @@ export function RouteNav({ routes, folders, selectedIds, activeRouteId, sources, Move into {target.name} )} + onClick={() => { setMenu(null); setPendingDelete({ kind: "folder", folder }); }}>Delete )}
@@ -1822,7 +1870,7 @@ export function RouteNav({ routes, folders, selectedIds, activeRouteId, sources, {item.folderId && } + onClick={() => { setMenu(null); setPendingDelete({ kind: "route", item }); }}>Delete )} @@ -1903,6 +1951,34 @@ export function RouteNav({ routes, folders, selectedIds, activeRouteId, sources, } {error && {error}} + {/* ⛔ RENDERED FROM THE COMPONENT ROOT, OUTSIDE `renderLevel` AND OUTSIDE EVERY MENU + CONDITIONAL. See the note over `pendingDelete`: a dialog inside the menu subtree that + set it would never paint. `ConfirmDialog` portals to itself, so its position in + this tree governs only its LIFETIME, and that is exactly what needed fixing. */} + { + const target = pendingDelete; + if (!target || busy) return; + setBusy(true); + void (target.kind === "folder" ? onFolderDelete(target.folder) : onDelete(target.item)) + .then(setError) + .finally(() => { setBusy(false); setPendingDelete(null); }); + }} + onCancel={() => setPendingDelete(null)} + /> ); } diff --git a/web/src/customer-grid/ViewSidebar.tsx b/web/src/customer-grid/ViewSidebar.tsx index 67f0165cab1cc1a1f0298008c8ca7412f0a7a5e6..df0564eb9bfe9f7943eb2cb92c3eaad347eca3c6 100644 --- a/web/src/customer-grid/ViewSidebar.tsx +++ b/web/src/customer-grid/ViewSidebar.tsx @@ -170,6 +170,57 @@ import { */ const NEST_HOLD_MS = 6_000; +/** + * ⭐⭐ WAVE 51 · T35 (ruling R18) — A VIEW SHARED TO YOU READ-ONLY IS NOT YOURS TO FILE. + * + * Owner, R18, 2026-09-03: *"a READ-ONLY shared view REFUSES a folder move with a sentence + * ('Shared to you by ; only they can move it') and snaps back; D-249's exit condition is + * rewritten to this."* + * + * ⛔ THIS IS A DELIBERATE REVERSAL AND IT DOES NOT TOUCH `mayFileView`, which is the part that + * matters most to get right. D-249 (R4, W34-T22) made a read-only shared view DRAGGABLE, because + * a gesture that cannot begin has nothing to explain and the owner's report was silence. R18 does + * not take the gesture away, it gives the gesture a VOICE: the drag still starts, the row still + * offers "Move to", and the refusal arrives as a sentence at the moment of the drop. So + * `mayFileView` stays exactly what it was — `view.shared === true || mayEdit`, the AFFORDANCE + * test at the drag site and on the `...` menu — and this narrower predicate sits BESIDE it as the + * ACTION test. Reversing `mayFileView` itself would make the row inert again and put back the + * exact defect D-249 was raised to fix. [[two-gates-can-assert-opposite-things]] + * + * ⚠ `assigned` counts as read-only here without a special case, because `mayEditView`'s first + * line already refuses an assigned view; an assigned view that is also shared refuses too, which + * is the answer either ruling would give on its own. + */ +export function isReadOnlyShare(view: SavedView, viewer?: Viewer): boolean { + return view.shared === true && !mayEditView(view, viewer); +} + +/** + * ⭐⭐ W51-T35 (R18) — THE ONE SENTENCE A REFUSED FOLDER MOVE CARRIES, or `null` to proceed. + * + * ⛔ ONE FUNCTION FOR EVERY DOOR, and that is the point rather than tidiness. A view can be filed + * from four places — the rail's drag-and-drop, the "Move to" popover on the `...` menu, a view + * created inside a folder, and the grid's own `onItemMove` sink — and a refusal that is worded at + * each door separately arrives in four shapes that drift apart one wave at a time. The caller + * asks here, prints what it gets back, and emits nothing when it gets a sentence. + * + * ⛔ THE CALLER MUST REFUSE **BEFORE** IT EMITS, never by reverting after (D-636). A revert-after + * implementation looks identical on screen and still leaves an `item_move` on the wire, which the + * host may well store. The snap-back R18 asks for is then automatic and needs no mechanism: the + * row never moved, because nothing was sent. + * + * ⚠ `createdBy` IS OPTIONAL (`types.ts::SavedView`) and absent on host-seeded and pre-wave-9 + * views, so the owner's name cannot be assumed. The fallback still refuses and still explains, + * rather than printing "Shared to you by undefined". + */ +export function viewMoveRefusal(view: SavedView, viewer?: Viewer): string | null { + if (!isReadOnlyShare(view, viewer)) return null; + const owner = (view.createdBy ?? "").trim(); + return owner + ? `Shared to you by ${owner}; only they can move it.` + : "This view was shared to you; only its owner can move it."; +} + function ShareMark({ size = 13 }: { size?: number }) { return ( @@ -2188,6 +2239,15 @@ export default function ViewSidebar({ // keep in step, and the bug being fixed here is exactly what happens when two // layers disagree about what absence means. For an unshared view the two are // equivalent — `groupByFolder` maps the sentinel onto the same root bucket. + // ⭐⭐ W51-T35 (R18) — THE REFUSAL IS HERE, BEFORE THE EMIT, AND IT SNAPS BACK BY + // NOT MOVING. `dropHandlers` is a plain arrow rebuilt every render, so `views` and + // `viewer` are the current ones and no dependency array can hold a stale grant. + const dragged = id ? views.find((view) => view.id === id) : undefined; + const refusal = dragged ? viewMoveRefusal(dragged, viewer) : null; + if (refusal) { + signal(TOAST_EVENT, refusal); + return; + } if (id) onItemMove?.(id, folderId ?? ROOT_FOLDER_ID); }, } @@ -2247,24 +2307,33 @@ export default function ViewSidebar({ */ pendingFileRef.current = null; if (!arrived) return; - // The same verdict the drag site asks (`mayFileView` over `mayEditView`, W34-T22), so a view - // that could not be filed by dragging cannot be filed by being born here either. + // The same verdict every other filing door asks, so a view that cannot be filed by dragging + // cannot be filed by being born here either. /** * ⭐⭐ W50-T11 / D-249 — AND IT SAYS SO. This return was silent, and a silent refusal on a * door the user just used reads as the app losing the click: they pick "New view in folder", * the view appears at the top level, and nothing anywhere explains why. DESIGN §4 asks a - * refusal to be a plain sentence naming its subject, so this one names the view and the - * reason rather than reporting that something failed. - * ⛔ THE PREDICATE IS UNCHANGED. `mayFileView` still returns true for a shared view whatever - * its role — that IS D-249's ruling (R4, W34-T22) and reversing it here would silently undo - * a shipped fix. What changes is only that the minority case which was already refused now - * has a voice. + * refusal to be a plain sentence naming its subject, so this one gives the reason rather than + * reporting that something failed. + * + * ⛔⛔ W51-T35 (R18) — THE PREDICATE HERE IS NOW `viewMoveRefusal`, AND THE SENTENCE IS R18'S. + * ⚠ THE PARAGRAPH THIS REPLACES SAID THE OPPOSITE and it was right at the time: *"the + * predicate is unchanged; `mayFileView` still returns true for a shared view whatever its + * role, that IS D-249's ruling (R4, W34-T22), and reversing it here would silently undo a + * shipped fix."* R18 is the owner reversing the EXIT CONDITION on purpose — a read-only + * shared view now refuses a folder move with a sentence — so the tombstone stays rather than + * the claim. `mayFileView` itself is STILL unchanged and still gates the drag and the `...` + * menu; what moved is which predicate an ACTION door asks. See `viewMoveRefusal` above. + * + * ⚠ `mayFileView` NO LONGER RUNS AT THIS DOOR, and that costs nothing observable: the arrival + * is a view this user just created, so it is their own, unshared and unassigned, and + * `mayFileView` was true on every path that can reach here. The one case it refused that + * `viewMoveRefusal` does not is a view neither shared nor editable, which cannot be a view + * that was born from this pane one commit ago. */ - if (!mayFileView(arrived, mayEditView(arrived, viewer))) { - signal( - TOAST_EVENT, - `"${viewDisplayName(arrived)}" is read only for you, so it stays at the top level.` - ); + const refusal = viewMoveRefusal(arrived, viewer); + if (refusal) { + signal(TOAST_EVENT, refusal); return; } onItemMove?.(arrived.id, pending.into); @@ -3880,6 +3949,16 @@ export default function ViewSidebar({ {moveFor && moveView && (() => { const currentId = folderIdOf ? folderIdOf(moveFor.viewId) : null; const fileInto = (folderId: string | null) => { + // ⭐⭐ W51-T35 (R18) — THE `...` MENU'S FOLDER SUBMENU SAYS THE SAME THING THE DRAG DOES. + // The row is still OFFERED (`canFileMenuView` keeps asking `mayFileView`, the affordance + // test), because a menu item that vanishes explains nothing; the sentence is what + // explains. Refused BEFORE the emit, so there is no placement to take back. + const refusal = viewMoveRefusal(moveView, viewer); + if (refusal) { + signal(TOAST_EVENT, refusal); + setMoveFor(null); + return; + } onItemMove?.(moveFor.viewId, folderId ?? ROOT_FOLDER_ID); setMoveFor(null); }; diff --git a/web/src/customer-grid/aggregations.ts b/web/src/customer-grid/aggregations.ts index 597edae360d73c4fcff79d0468f20383e681cfec..a1237a92a32991bfff91716d017e1f7407df4330 100644 --- a/web/src/customer-grid/aggregations.ts +++ b/web/src/customer-grid/aggregations.ts @@ -15,10 +15,12 @@ import { isNumericFieldType } from "./types"; // note. Two copies is how a cell painted blank while the total under it counted 1,234.50. import { numericOrUndefined } from "./display"; import type { - AggName, Field, Row, SummaryAggName, SummaryChoice, SummaryMap, + AggName, Field, Row, SummaryAggName, SummaryChoice, SummaryMap, SummaryPickAgg, } from "./types"; // ⭐⭐ W29-T74 — IMPORTED, NOT RE-DECLARED, which is what `iconShapes.ts` always claimed. -import { FIELD_AGGS, FIELD_AGG_LABELS, SUMMARY_AGGS, SUMMARY_AGG_LABELS } from "./iconShapes"; +import { + FIELD_AGGS, FIELD_AGG_LABELS, SUMMARY_AGGS as WIRE_SUMMARY_AGGS, SUMMARY_AGG_LABELS, +} from "./iconShapes"; /** * ⭐⭐ WAVE-29 CONTRACT C7 — **THE CLIENT MIRROR of `platform/aios_grid.FIELD_AGGS`**, published @@ -100,11 +102,33 @@ export function cleanPercent(p: number | undefined): number { return Math.max(0, Math.min(100, p)); } -/** ⭐ WAVE 50 · W50-T03 — the SUMMARY BAR's vocabulary and its words, re-exported under this - * module's own name for the same reason `FIELD_AGGS` is: every runtime consumer imports - * `./aggregations`, and a second declaration is a second thing to keep in step. */ -export { SUMMARY_AGGS }; -export const SUMMARY_LABELS: Record = SUMMARY_AGG_LABELS; +/** + * ⭐⭐ WAVE 51 · W51-T02 (owner ruling R3) — **THE PICKER'S VOCABULARY IS THE WIRE'S PLUS + * `share`, AND IT IS DECLARED HERE RATHER THAN WHERE THE WIRE ONE LIVES.** + * + * ⛔ WHY THE DECLARATION MOVED (W50-T03 re-exported the icon array bare). C1's summary + * vocabulary is EIGHT names and it exists twice — `iconShapes.SUMMARY_AGGS` and + * `platform/aios_grid.SUMMARY_AGGS` — with `verify_grid_ux.py::summary_bar_shape` holding the + * two byte-for-byte so neither engine can widen the wire alone. R3's "% of total" is a PICKER + * choice, never a wire agg: its numerator and denominator are ordinary wire aggregates (a + * numeric column's `sum`, anything else's `count`) and the division is client-side. Adding it to + * either array would break that parity leg and would tell lane F's route to compile an + * aggregate that does not exist in SQL. + * + * ⚠ AND THE TWO FILES IT WOULD OTHERWISE HAVE TO TOUCH BELONG TO OTHER LANES (`iconShapes.ts` to + * lane C, `aios_grid.py` to lane B), so the wire array is IMPORTED under an alias and the + * picker's array is spread out of it. One list still, plus one name this module owns — the + * wire cannot drift, because nothing here writes to it. + */ +export const SUMMARY_AGGS: readonly SummaryPickAgg[] = [...WIRE_SUMMARY_AGGS, "share"]; + +/** The picker's words. `share` reads "% of total" (sentence case, DESIGN.md §2) and the other + * eight come from the icon module's table unchanged, for the reason above: one table, extended + * where the extra name is declared rather than where the wire one is. */ +export const SUMMARY_LABELS: Record = { + ...SUMMARY_AGG_LABELS, + share: "% of total", +}; /** * ⭐⭐ W50-T03 / OWNER RULING R2 — **WHAT THIS COLUMN MAY BE SUMMARISED BY, AND IT IS THE TYPE @@ -118,11 +142,17 @@ export const SUMMARY_LABELS: Record = SUMMARY_AGG_LABELS * * `count` and `count_distinct` read ROWS and VALUES rather than numbers, so they are legal on * every type; the six numeric folds are offered only where a number can exist. + * + * ⭐⭐ W51-T02 / R3 — **`share` IS LEGAL ON EVERY TYPE, AND THAT IS THE RULING'S SECOND HALF.** + * R3: *"the primary column: Count / % of total"*. A share of a text column is that group's ROW + * COUNT over the view's, which is a question every column can answer; on a numeric column it is + * that column's own SUM over the view's. So it joins the two counting aggregates in the + * non-numeric arm rather than being filtered out with the six folds. */ -export function summaryOptions(field: Field): readonly SummaryAggName[] { +export function summaryOptions(field: Field): readonly SummaryPickAgg[] { return isNumericFieldType(field.type) ? SUMMARY_AGGS - : SUMMARY_AGGS.filter((a) => a === "count" || a === "count_distinct"); + : SUMMARY_AGGS.filter((a) => a === "count" || a === "count_distinct" || a === "share"); } /** Today's behaviour, unchanged, for every caller that has no view map to offer (the per-group @@ -199,10 +229,53 @@ function foldNumeric(nums: number[], agg: SummaryAggName, p: number | undefined) return percentile([...nums].sort((a, b) => a - b), cleanPercent(p)); } +/** Every readable number in one column of `rows`. ⛔ ONE numeric reading (`numOf`), shared with + * the canvas renderer — see this module's head note; two readings is how a cell painted blank + * while the total under it counted 1,234.50. */ +function numbersOf(rows: Row[], key: string): number[] { + const nums: number[] = []; + for (const r of rows) { + const n = numOf(r[key]); + if (n !== undefined) nums.push(n); + } + return nums; +} + +/** + * ⭐⭐ W51-T02 / R3 — **WHAT A `share` DIVIDES, AND IT IS ONE FUNCTION SO A NUMERATOR AND A + * DENOMINATOR CANNOT BE MEASURED TWO DIFFERENT WAYS.** + * + * A numeric column's share is its own SUM over the view's sum. Every other column's — the + * primary key column above all, which is instruction 4's whole subject — is that bucket's ROW + * COUNT over the view's row count, because a column of text has no quantity to add up. + * + * ⛔ BLANK, NEVER ZERO, on the numeric arm: a set holding no readable number at all is `undefined` + * rather than `0`, exactly as `computeAggs` returns nothing there. A row COUNT of zero is a real + * measurement and stays `0` — `formatShare` then refuses the division only if the WHOLE is zero. + * ⛔ NOTHING IS ROUNDED HERE. Rounding a numerator and a denominator separately is how a column + * of shares stops adding to 100 (`computeAggNumbers`' own note). + */ +function shareBase(rows: Row[], field: Field): number | undefined { + if (!isNumericFieldType(field.type)) return rows.length; + const nums = numbersOf(rows, field.key); + // ⚠ `foldNumeric`, not a second `reduce`: the sum a share divides and the sum the bar prints + // must be ONE arithmetic, which is the same argument W50-T04 extracted that function for. + return nums.length ? foldNumeric(nums, "sum", undefined) : undefined; +} + export function computeAggs( rows: Row[], fields: Field[], - summary?: SummaryMap + summary?: SummaryMap, + /** + * ⭐⭐ W51-T02 / R3 — the VIEW's totals, keyed exactly as `computeAggNumbers` returns them, and + * the ONLY thing a `share` may divide by. Absent means "this fold IS the view" — the bottom + * bar, which therefore reads 100.0% under "% of total", which is what the done-when says. + * ⛔ It is never the sum of the groups and never the painted list: R4 fixed the base at the + * MATCHED, UNFOLDED set and a base that followed the fold would change every share on screen + * as somebody tidied it. + */ + totals?: Record ): Record { const out: Record = {}; for (const f of fields) { @@ -227,12 +300,20 @@ export function computeAggs( out[f.key] = seen.size.toLocaleString(); continue; } - if (!isNumericFieldType(f.type)) continue; - const nums: number[] = []; - for (const r of rows) { - const n = numOf(r[f.key]); - if (n !== undefined) nums.push(n); + /* ⭐⭐ W51-T02 / R3 — "% OF TOTAL" IS A PERCENT WHATEVER THE COLUMN'S UNIT, WHICH IS WHY IT + RETURNS BEFORE `wearColumnUnit` EVER SEES IT. A share dressed in a money column's unit + prints "$12.4" where it means "12.4%" — a number that is true of nothing, and one no type + and no screenshot can catch. `formatShare` owns the arithmetic and the one decimal, and + refuses a zero or absent denominator rather than painting `0%`. */ + if (agg === "share") { + const base = shareBase(rows, f); + const whole = totals?.[f.key]; + const text = formatShare(base, whole === undefined ? base : whole); + if (text !== undefined) out[f.key] = text; + continue; } + if (!isNumericFieldType(f.type)) continue; + const nums = numbersOf(rows, f.key); if (!nums.length) continue; // blank, never zero const clean = Math.round(foldNumeric(nums, agg, choice.p) * 100) / 100; // drop float artifacts // ⭐ W41-T40 (instruction 16) — A SUMMARY WEARS ITS COLUMN'S UNIT. `display.cellText` paints @@ -281,12 +362,18 @@ export function computeAggNumbers( out[f.key] = seen.size; continue; } - if (!isNumericFieldType(f.type)) continue; - const nums: number[] = []; - for (const r of rows) { - const n = numOf(r[f.key]); - if (n !== undefined) nums.push(n); + /* ⭐⭐ W51-T02 / R3 — a `share` UNDRESSED is its BASE, not its percentage, and that is what + makes this function the denominator source. `groupAnalytics` folds this over the whole + matched set and hands the result back in as `computeAggs`' `totals`, so the group's base + and the view's base are measured by one function over two scopes. Summary mode also sorts + on it, and ordering by the base is the same order as by the share under one denominator. */ + if (agg === "share") { + const base = shareBase(rows, f); + if (base !== undefined) out[f.key] = base; + continue; } + if (!isNumericFieldType(f.type)) continue; + const nums = numbersOf(rows, f.key); if (!nums.length) continue; // blank, never zero out[f.key] = foldNumeric(nums, agg, choice.p); } @@ -314,8 +401,21 @@ export function computeAggNumbers( */ export const SHARE_AGGS: readonly SummaryAggName[] = ["sum", "count"]; +/** + * ⛔⛔ W51-T02 — **THIS IS THE ROW-LEVEL `Show as` GATE, AND R3 EXPLICITLY KEEPS IT.** R3, in its + * own words: *"The row-level Show as (wave 50 R4) STAYS on the field."* Its one caller is + * `CustomerGrid.tsx::getCellContent`, which composes a CELL's value with its share of the view + * total through `ui/fmt.ts::withShare` under `field.showAs`. + * + * ⛔ IT IS NOT WHAT PAINTS A GROUP HEADER ANY MORE. W50-T04's `groupHeaderAggs` used this to + * append an automatic SECOND number to every composable column's header, which is exactly what + * instruction 1 called out; the header now paints one value, the bar's picker's choice, and + * "% of total" is one of the choices rather than an extra. + * ⚠ `share` can never be a member: it IS a share, and a share of a share is not a quantity. + */ export function sharesTheTotal(choice: SummaryChoice): boolean { - return choice.agg !== "none" && SHARE_AGGS.includes(choice.agg); + if (choice.agg === "none" || choice.agg === "share") return false; + return SHARE_AGGS.includes(choice.agg); } /** @@ -340,35 +440,25 @@ export function formatShare( } /** - * ⭐⭐ W50-T04 / OWNER RULING R3 — **WHAT A GROUP HEADER PAINTS, PER COLUMN.** + * ⭐⭐ W51-T02 / OWNER RULING R3 — **`groupHeaderAggs` IS GONE, AND ITS ABSENCE IS THE TICKET.** + * + * W50-T04 declared a function here that composed `"$12,340 12.4%"` — the column's aggregate, + * then an AUTOMATIC share of the view total for every fold in `SHARE_AGGS`. Instruction 1, in + * the owner's words: *"Under the Group function with numerics, do not show BOTH common size % + * and the sum/average/median: the toggle for sum/average/median includes the common size."* * - * R3: *"every group header carries the same summary bar as the footer (every chosen aggregate, - * count, % of total)."* So the string is the group's own aggregate followed by its share of the - * VIEW's total for that column — `"$12,340 12.4%"` — and a column whose fold does not compose - * (see `SHARE_AGGS`) carries the aggregate alone. + * R3 replaced it: *"The bottom-bar picker OWNS group headers and the bar: one value, the + * picker's choice, with '% of total' as an option."* So a group header is now `computeAggs` over + * that group's bucket under the view's summary map, with the view's own totals handed in as the + * share denominator — the SAME function the bottom bar folds itself with, at a smaller scope. + * There is nothing left to compose, so there is no composer. * - * ⚠ TWO SPACES, NOT A SEPARATOR GLYPH. A group header is a dense strip and the two quantities - * are already visually distinct (one wears a unit, the other a `%`); a bullet or a slash between - * them is chrome, and a dash of any width is forbidden outright in copy that reaches a screen. + * ⚠ WHAT THE HEADER STILL CARRIES BESIDE ITS COLUMNS is the group's ROW COUNT as a share of the + * view's, appended to the group LABEL (`CustomerGrid.tsx::groupAnalytics`' `share` map). That is + * a property of the grouping rather than of a column, it is not gated on `sharesTheTotal`, and + * `export.ts::summaryExportSheet` files it as the "% of total" column of the Summary-mode + * export. Deleting it would empty a shipped column to answer a ruling that speaks about columns. */ -export function groupHeaderAggs( - fields: Field[], - summary: SummaryMap, - groupText: Record, - groupNums: Record, - grandNums: Record -): Record { - const out: Record = {}; - for (const f of fields) { - const text = groupText[f.key]; - if (text === undefined) continue; - const share = sharesTheTotal(resolveSummary(f, summary)) - ? formatShare(groupNums[f.key], grandNums[f.key]) - : undefined; - out[f.key] = share === undefined ? text : `${text} ${share}`; - } - return out; -} /** The formatting half of the fold, extracted so C1's SERVER numbers wear the same unit the * client's own fold does. Two formatters is how the same column reads "$1,204" on a small @@ -387,13 +477,25 @@ function wearColumnUnit(field: Field, clean: number): string { * that a fold with nothing to measure returns nothing, because `0` is a measurement. * ⚠ The two counting aggregates are plain integers: a count of rows in a money column is not * money, and dressing it as "$412" is a number nobody can reconcile. + * + * ⭐⭐ W51-T02 / R3 — **AND A `share` IS A PERCENT WHATEVER THE COLUMN'S UNIT, so it returns + * before `wearColumnUnit` too.** On a server-windowed table there is no page to fold: `value` is + * the server's aggregate for this group (a numeric column's `sum`, anything else's `count`, + * which is what `CustomerGrid.tsx::summaryRequest` asks for in a share column's name) and + * `whole` is C1's TOP-LEVEL overall answer for the same column. Both come from the aggregates + * endpoint, so the share describes the whole predicate rather than the loaded window. + * ⛔ NO SERVER ANSWER IS NO DENOMINATOR AND THEREFORE NO SHARE — `formatShare` refuses an absent + * or zero `whole` and this returns `undefined`, which the callers paint as blank. Never `0%`. */ export function formatServerAgg( field: Field, choice: SummaryChoice, - value: number | null | undefined + value: number | null | undefined, + whole?: number | null | undefined ): string | undefined { if (typeof value !== "number" || !Number.isFinite(value)) return undefined; + if (choice.agg === "share") + return formatShare(value, typeof whole === "number" ? whole : undefined); if (choice.agg === "count" || choice.agg === "count_distinct") return Math.round(value).toLocaleString(); return wearColumnUnit(field, Math.round(value * 100) / 100); diff --git a/web/src/customer-grid/apiBridge.ts b/web/src/customer-grid/apiBridge.ts index ac9fb6863f22a3dab88cffbd9d6669b00dcd3461..67428da668b410b6ed600d2b23a2e61f269843f5 100644 --- a/web/src/customer-grid/apiBridge.ts +++ b/web/src/customer-grid/apiBridge.ts @@ -55,9 +55,9 @@ import { import { setStandaloneSink } from "./hostBridge"; import { changedBuckets } from "./liveWorkspace"; import type { ChangeTokens } from "./liveWorkspace"; -import { CUSTOMER_TOPIC } from "./types"; -import type { CustomersPayload, Field, FilterNode, GridLimit, GridWorkspace, HostEvent, Row, - SortSpec, TopicConfig } from "./types"; +import { CUSTOMER_TOPIC, relatedEntries } from "./types"; +import type { CustomersPayload, Field, FilterNode, GridLimit, GridWorkspace, HostEvent, + RelatedEntry, RelatedPin, Row, SortSpec, TopicConfig } from "./types"; import type { TsPayload, TsRequest } from "./timeSeriesData"; const JSON_HEADERS = { "Content-Type": "application/json" }; @@ -323,6 +323,17 @@ export interface RowWindowRequest { filterConj?: string; sorts?: SortSpec | null; search?: string; + /** + * ⭐⭐ W51-T06 / C6 — THE PINNED READ. `{table, record, via}`: narrow this window to the rows + * related to ONE record of another database, ahead of `filters`. + * + * ⛔ IT IS PART OF THE PATH, therefore part of the CACHE KEY, and that is not a nicety. + * `rowsCache` is keyed by path (see `windowRowsPath`), so a pin that stayed out of the string + * would make a pinned read a cache HIT on the unpinned one this browser already holds — the + * whole table painted under a tab that names one record, served from memory, with no request + * to see in the network panel. + */ + related?: RelatedPin | null; } /** @@ -354,6 +365,13 @@ export function windowRowsPath(tableKey: string, req: RowWindowRequest): string if (req.sorts && req.sorts.length) q.set("sorts", JSON.stringify(req.sorts)); const search = (req.search ?? "").trim(); if (search) q.set("search", search); + /* ⭐⭐ W51-T06 / C6 — THE PIN RIDES AS A JSON QUERY STRING, copying the `filters` precedent one + argument over, because `GET /odoo-tables/{key}/rows` is a GET and its `related` argument is + `Query(default=None)` (`routes_odoo_tables.py::odoo_table_rows`). ⛔ THE AGGREGATES DOOR IS + A POST AND TAKES THE SAME OBJECT AS A BODY KEY — see `fetchAggregates`. Two transports, one + payload; assuming both were bodies is the half-wired contract that paints the right rows + under a summary computed over the whole table. */ + if (req.related) q.set("related", JSON.stringify(req.related)); return `odoo-tables/${encodeURIComponent(tableKey)}/rows?${q.toString()}`; } @@ -539,6 +557,17 @@ export interface AggregateRequest { search?: string; groupBy?: string; aggs: { colId: string; agg: string; p?: number }[]; + /** + * ⭐⭐ W51-T06 / C6 — THE SAME PIN THE WINDOW CARRIES, or the summaries describe a different + * population than the rows under them. + * + * ⛔⛔ THIS IS THE HALF-WIRING TRAP, NAMED. Wire only `/rows` and the grid shows one record's + * related rows under a count and a summary bar folded over the WHOLE table: a plausible + * number, which is exactly the fabricated aggregate `no-unverifiable-aggregates` exists to + * forbid. `_compiled_read` is shared between the two doors server-side, so the ONLY way they + * can pin differently is this argument being dropped on one of them. + */ + related?: RelatedPin | null; } /** C1's response, as this client reads it. `null` for a column means the server ANSWERED and @@ -603,6 +632,9 @@ export async function fetchAggregates( filterConj: req.filterConj === "or" ? "or" : "and", search: (req.search ?? "").trim(), ...(req.groupBy ? { groupBy: req.groupBy } : {}), + /* ⛔ A BODY KEY HERE, A QUERY STRING ON `/rows` (`windowRowsPath`). Same object, two + transports, because this door is a POST and that one is a GET. */ + ...(req.related ? { related: req.related } : {}), aggs: req.aggs, }), } @@ -614,6 +646,70 @@ export async function fetchAggregates( return aggregatePayload(await readJson(res)); } +// ═══════════════════════════════════════════════════════════════════════════════════════════ +// ⭐⭐ W51-T06 · RULING R2 · CONTRACT C6 — WHAT THIS DATABASE IS RELATED TO, AND WHETHER THE +// RELATION CAN BE PINNED TODAY. +// ═══════════════════════════════════════════════════════════════════════════════════════════ + +/** + * `GET /api/v1/grid/{table}/related` — every edge THIS ACCOUNT may follow, forward then reverse + * then bridge. + * + * ⛔ AN EMPTY LIST ON ANY FAILURE, NEVER A THROW. A record whose relations cannot be listed + * still opens on its Fields tab; a rejected promise here would take the whole drawer down for a + * list that is chrome. + * ⚠ The permission narrowing happens SERVER-SIDE (`routes_grid.related_entries` filters on + * `_may_open`), so an edge that is not in this answer is also an edge that cannot be pinned. + * There is deliberately no second, laxer resolution on this side. + */ +export async function fetchRelated(table: string): Promise { + try { + const res = await fetch( + `${API_V1}/grid/${encodeURIComponent(table)}/related`, + { credentials: CREDENTIALS } + ); + if (handledSession(res) || !res.ok) return []; + return relatedEntries(await readJson(res)); + } catch { + return []; + } +} + +/** + * ⭐⭐ CAN THIS EDGE BE SERVED AS A PINNED READ, AND IF NOT, IN WHOSE WORDS? + * + * ⛔⛔ THE SENTENCE HAS EXACTLY ONE AUTHOR, AND IT IS THE SERVER. `relations.py` already writes + * three of them (`unknown_via_refusal`, `unresolvable_source_refusal`, + * `unserved_target_refusal`), each naming a cause and a recommendation. Spelling a fourth here + * would be a second opinion about one wire contract, which is how a feature ships with both + * halves correct and disagreeing [[two-lanes-one-contract-dead-feature]]. So this asks for ONE + * row and reports what came back: `null` when the pin is served, the server's own sentence when + * it is not. + * + * ⛔ AND IT IS WHY THE TAB DOES NOT SIMPLY MOUNT AND HOPE. `useCustomerData`'s failure channel + * is `DATA_ERROR_EVENT`, which REPLACES the surface with an error card; a declared-but-unserved + * relation is a reported limit, not a broken screen. `bridge_customer_open_invoices` is the one + * such edge today (`ut_odoo_invoices` is materialised and absent from `GRID_SOURCES`), and a + * link whose target is an ordinary user table is the same shape for a different reason: that + * door (`routes_tables.table_rows`) takes no predicate at all. + */ +export async function probeRelatedRead( + tableKey: string, + related: RelatedPin +): Promise { + const path = windowRowsPath(tableKey, { offset: 0, limit: 1, related }); + let res: Response; + try { + res = await fetch(`${API_V1}/${path}`, { credentials: CREDENTIALS }); + } catch { + return "The server could not be reached, so these related records cannot be shown yet. " + + "Check the connection and open this tab again."; + } + if (handledSession(res)) return null; + if (res.ok) return null; + return refusalMessage(await readJson(res), res.status); +} + /** * `GET /api/v1/workspace` — the saved views, custom fields, folders and cohorts * for the session user (S1's amendment, 2026-07-30). It exists because X2 pins @@ -1584,7 +1680,30 @@ export async function fetchCalendarMetrics( */ export const MAX_REPLAY = 24; -let pending: HostEvent[] = []; +/** + * ⭐⭐ W51-T06 (R5, clause 7) — AN EVENT CARRIES THE SCOPE IT WAS CREATED UNDER, STAMPED AT + * ENQUEUE. + * + * ⛔⛔ IT USED TO BE READ AT DRAIN, AND A SECOND WRITABLE GRID MAKES THAT A SILENT WRONG WRITE. + * `drain` sent `scopeKey: surfaceScope` — the module global, read whenever the flush happened. + * That was safe while exactly one grid on the page could write: the only nested grid was the + * link-record embed, which is `bindSurface: false` AND `writable: false`, so it emitted nothing. + * A related tab (R5) mounts the TARGET database's own grid with its own view rail and its own + * saved-view writes, so two grids on two scopes are now live at once — and a `view_upsert` + * queued from the related tab could flush after the parent's next render and be filed against + * the PARENT's database. A 200, no error, one view on the wrong table. + * + * ⛔ THE FIX IS THE STAMP, NOT A LOCK. Each queued event remembers its own scope; `drain` sends + * the LEADING RUN of one scope per request and comes back for the rest, so ordering is + * preserved exactly (`field_upsert` before `view_upsert` is still a field that exists before a + * view that shows it) and a single-scope session batches byte-identically to before. + */ +interface QueuedEvent { + event: HostEvent; + scope: SurfaceScope; +} + +let pending: QueuedEvent[] = []; let inFlight = false; /** @@ -1631,7 +1750,7 @@ export function _resetQueue(): void { } export function _pendingIds(): string[] { - return pending.map((e) => e.id); + return pending.map((q) => q.event.id); } /** @@ -1652,15 +1771,22 @@ export function _pendingIds(): string[] { async function drain(): Promise { if (inFlight || pending.length === 0) return; inFlight = true; - const batch = pending; - pending = []; + /* ⭐⭐ W51-T06 — THE LEADING RUN OF ONE SCOPE, NOT THE WHOLE QUEUE. `scopeKey` is a property + of the REQUEST, so a batch may only carry events that agree about it; the rest stay queued + in order and ride the follow-up drain the `finally` below already schedules. With one grid + writing (every session before a related tab existed) the run IS the whole queue and this is + byte-identical to the previous behaviour. */ + const scopeKey = pending[0].scope; + const cut = pending.findIndex((q) => q.scope !== scopeKey); + const batch = cut < 0 ? pending : pending.slice(0, cut); + pending = cut < 0 ? [] : pending.slice(cut); let requeue = false; try { const res = await fetch(`${API_V1}/grid/events`, { method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS, - body: JSON.stringify({ events: batch, scopeKey: surfaceScope }), + body: JSON.stringify({ events: batch.map((q) => q.event), scopeKey }), }); // A dead session is NOT retryable — replaying into a 401 forever would // turn one expired cookie into an unbounded request loop. @@ -1716,7 +1842,9 @@ function applyEventResult(body: unknown): void { /** The sink hostBridge falls through to in standalone. Returns true: the event * is now OURS (queued and owned), which is all the caller ever needed. */ function standaloneSink(event: HostEvent): boolean { - pending.push(event); + // ⭐⭐ W51-T06 — STAMPED HERE, at the moment the event is created, which is the only moment + // the surface it belongs to is knowable. See `QueuedEvent`. + pending.push({ event, scope: surfaceScope }); if (pending.length > MAX_REPLAY) pending.shift(); void drain(); return true; diff --git a/web/src/customer-grid/iconShapes.ts b/web/src/customer-grid/iconShapes.ts index 1903c8acc507da7aa1a91980d2e281f23e203352..d4908ebc634347d8092c980884f378bab7404582 100644 --- a/web/src/customer-grid/iconShapes.ts +++ b/web/src/customer-grid/iconShapes.ts @@ -932,6 +932,26 @@ export const SHARE_SHAPE: IconShape[] = [ { d: "M10.6 4.1a2.2 2.2 0 0 1 0 4.2M11.4 9.7c1.6.3 2.7 1.4 2.7 2.9" }, ]; +/** + * ⭐ W51-T10 — THE SHEET MODULE'S GLYPH, AS DATA. A page ruled into cells: one outlined sheet with + * two rules across and two down. + * + * ⛔ IT IS TRANSCRIBED FROM `shell/Shell.tsx::SheetIcon`, NOT DRAWN AGAIN. Same 16x16 box, same + * coordinates, same 1.35 stroke; the only change is that the component's + * `` is written below as the equivalent + * rounded-rectangle PATH, because an `IconShape` is path data and one serializer paints the whole + * vocabulary. The corners are the same 1.3 radius arcs the rect asked for. + * + * ⚠ THE GEOMETRY MOVED HERE BECAUSE THE COMPONENT COULD NOT. `Shell.tsx` is another lane's file + * this wave, so `SheetIcon` cannot be exported and cannot be imported; the Sheet rail's create + * menu still has to wear the mark the shell's nav row wears, and a second hand-drawn sheet would + * be a second icon language the first time either was touched. One shape, three renderers. + */ +export const SHEET_SHAPE: IconShape[] = [ + { d: "M3.6 2.7h8.8a1.3 1.3 0 0 1 1.3 1.3v8a1.3 1.3 0 0 1-1.3 1.3H3.6a1.3 1.3 0 0 1-1.3-1.3V4a1.3 1.3 0 0 1 1.3-1.3z" }, + { d: "M2.3 6.2h11.4M2.3 9.8h11.4M6.4 2.7v10.6M10.1 2.7v10.6" }, +]; + export const HEADER_ICONS: Record string> = { ...TYPE_SPRITES, /** diff --git a/web/src/customer-grid/summary/SummaryBar.tsx b/web/src/customer-grid/summary/SummaryBar.tsx index 878012e9d5adb5ac930e55c34a20710694115b4f..24388a19b559c567bba5e465ceca9c0038275200 100644 --- a/web/src/customer-grid/summary/SummaryBar.tsx +++ b/web/src/customer-grid/summary/SummaryBar.tsx @@ -186,8 +186,16 @@ function SummaryPicker({ onDismiss={onDismiss} > {row("None", choice.agg === "none", { agg: "none" })} + {/* ⭐⭐ W51-T02 / R3 — **`share` IS FILTERED OUT HERE AND RENDERED LAST, BECAUSE THE + PERCENTILE GROUP SITS BETWEEN THEM.** The done-when's order is None / Sum / Average / + Median / Min / Max / Count / Unique / Percentile / % of total, and Percentile is not a + row but a labelled group with five points and a custom door. Left in this map, "% + of total" would print BEFORE the group it is supposed to follow — the array's order and + the menu's order are not the same thing once one member expands. On a text or primary + column there is no percentile group at all, so the three rows read Count / Unique / + % of total, which is the ruling's list for that column verbatim. */} {options - .filter((agg) => agg !== "percentile") + .filter((agg) => agg !== "percentile" && agg !== "share") .map((agg) => row(SUMMARY_LABELS[agg], choice.agg === agg, { agg }))} {options.includes("percentile") && ( @@ -223,6 +231,8 @@ function SummaryPicker({ )} + {options.includes("share") + && row(SUMMARY_LABELS.share, choice.agg === "share", { agg: "share" })} ); } diff --git a/web/src/customer-grid/types.ts b/web/src/customer-grid/types.ts index 1bacb77ee71fbb38320a0ea5a93cb636aebb17e1..55bb4a3f609f112b0add0a0b07c081843060477d 100644 --- a/web/src/customer-grid/types.ts +++ b/web/src/customer-grid/types.ts @@ -2790,6 +2790,28 @@ export type AggName = "sum" | "average" | "median" | "min" | "max" | "count"; */ export type SummaryAggName = AggName | "count_distinct" | "percentile"; +/** + * ⭐⭐ WAVE 51 · W51-T02 (owner ruling R3) — **THE PICKER'S VOCABULARY, WHICH IS THE WIRE'S PLUS + * ONE, AND THE SPLIT IS WHAT KEEPS THE WIRE BYTE-IDENTICAL ON BOTH ENGINES.** + * + * R3 puts "% of total" on the bottom-bar picker, so `share` is a choice a reader can store. It + * is NOT a wire name: `platform/aios_grid.SUMMARY_AGGS` is C1's eight-name clause and + * `verify_grid_ux.py::summary_bar_shape` holds it byte-for-byte against `iconShapes.SUMMARY_AGGS` + * — one array on each engine, and neither may drift alone. + * + * ⛔ SO `SummaryAggName` DOES NOT GROW, AND THAT IS A COMPILE FACT RATHER THAN A PREFERENCE. + * `iconShapes.ts:850` declares `SUMMARY_AGG_LABELS: Record` over exactly + * the eight wire names; adding a ninth member to this union makes that literal incomplete and + * reds a file this ticket may not open. The picker's extra name therefore lives in its own + * union, the same way `aggregations.ts` declares the picker's ARRAY locally over the imported + * wire one. + * + * ⚠ A `share` never reaches C1's `/aggregates` route. Its numerator and denominator are ordinary + * wire aggregates (a numeric column's `sum`, anything else's `count`) and the division happens + * client-side, which is why the wire vocabulary does not need the word at all. + */ +export type SummaryPickAgg = SummaryAggName | "share"; + /** * One column's summary choice, as stored in `ViewConfig.summary`. * @@ -2799,7 +2821,7 @@ export type SummaryAggName = AggName | "count_distinct" | "percentile"; * ⚠ `p` is meaningful only for `percentile` and is the 0-100 percent point C1 puts on the wire. */ export interface SummaryChoice { - agg: SummaryAggName | "none"; + agg: SummaryPickAgg | "none"; p?: number; } @@ -2874,7 +2896,14 @@ export type FilterOp = | "aboveAvg" | "belowAvg" | "inQuartile" - | "inDecile"; + | "inDecile" + // W51-T07 (instruction 25) - the MULTI-VALUE family. See MULTI_VALUE_OPS below: these five + // read their operand from the leaf's `values` list, never from `value`. + | "isAnyOf" + | "isNoneOf" + | "hasAnyOf" + | "hasAllOf" + | "hasNoneOf"; /** * C-OPS — the RANK family: operators whose truth depends on the OTHER rows, not on this row's @@ -2937,6 +2966,7 @@ const FILTER_OPS_LIST = [ "gt", "gte", "lt", "lte", "between", "within", "topN", "bottomN", "inTopPct", "inBottomPct", "aboveAvg", "belowAvg", "inQuartile", "inDecile", + "isAnyOf", "isNoneOf", "hasAnyOf", "hasAllOf", "hasNoneOf", ] as const; /** Compile-time `never` assertion — instantiating it with anything else is an error. */ @@ -2945,7 +2975,7 @@ type _NoneMissing = AssertNever>; export type { _NoneMissing, _NoneExtra }; -/** All 20 operators, as data. Mirrors `aios_grid.FILTER_OPS` / `filter_sql.FILTER_OPS`. */ +/** All 25 operators, as data. Mirrors `aios_grid.FILTER_OPS` / `filter_sql.FILTER_OPS`. */ export const FILTER_OPS: readonly FilterOp[] = FILTER_OPS_LIST; /** Membership test for the engine's fail-closed `default:` branch. */ @@ -2962,6 +2992,28 @@ export const VALUE_FREE_OPS: ReadonlySet = new Set([ "belowAvg", ]); +/** + * ⭐ W51-T07 (owner instruction 25) — the MULTI-VALUE family: operators whose operand is a LIST + * of allowed values rather than one typed string. + * + * `isAnyOf` / `isNoneOf` answer a single-valued cell (status / select / user); `hasAnyOf` / + * `hasAllOf` / `hasNoneOf` answer a multi-select cell, which is a comma-joined SET. + * + * ⛔ THE MEMBERSHIP TEST IS LOAD-BEARING IN ALL FOUR ENGINES, and for the same reason + * VALUE_FREE_OPS above is. These leaves leave `value` BLANK, and every engine carries a + * historical "blank value means the rule is half-typed, so ignore it" short-circuit. An ignored + * leaf shows EVERY row under a count nobody would doubt. So each engine intercepts these ops on + * the OP, before any type dispatch and before any blank-value guard, and `isRuleActive` below + * answers them from `values` instead. Mirrored by `filter_sql.MULTI_VALUE_OPS`. + */ +export const MULTI_VALUE_OPS: ReadonlySet = new Set([ + "isAnyOf", + "isNoneOf", + "hasAnyOf", + "hasAllOf", + "hasNoneOf", +]); + /** How sibling conditions at ONE nesting level combine. Airtable allows exactly * one conjunction per level (not per condition) — see FilterGroup. */ export type Conjunction = "and" | "or"; @@ -3095,6 +3147,45 @@ export function cohortIds(value: string | undefined): string[] { return out; } +/** + * ⭐ W51-T07 — how many values one multi-value condition may name. + * + * Bounded for the same reason MAX_COHORT_IDS is: the tree is re-evaluated for EVERY row on + * EVERY render, and each named value is one more comparison per row. 100 is generous against a + * declared option list a person is expected to read. + * + * ⚠ Three hand-kept copies (here, `aios_grid.MAX_FILTER_VALUES`, `filter_sql.MAX_FILTER_VALUES`), + * held together by verify_filter_engine.py — a drifted cap silently asks a NARROWER question on + * one side than the other. + */ +export const MAX_FILTER_VALUES = 100; + +/** + * The values a multi-value leaf names, parsed out of `values`. + * + * ⛔ A REAL LIST, not the comma-joined string `cohortIds` parses, and the difference is the + * decision. A cohort id is minted from `[a-z0-9_]` so a comma cannot occur inside one; a SELECT + * OPTION is tenant prose, and `Bouquets, mixed` is a perfectly ordinary choice. Joining on a + * comma would split that option into two that match nothing, so the leaf persists a JSON array + * and every layer down to the SQL binder keeps it as one. + * + * Same discipline as `cohortIds` otherwise: order preserved (it is the order the user picked), + * blanks dropped, duplicates collapsed, each member capped at 120 characters, the list capped + * at MAX_FILTER_VALUES. Unknown values are KEPT: an option that no longer exists filters to + * nothing, honestly, and the chip that says so is what lets somebody remove it. + */ +export function filterValues(values: readonly string[] | undefined): string[] { + const out: string[] = []; + if (!Array.isArray(values)) return out; + for (const raw of values) { + const v = String(raw ?? "").trim().slice(0, 120); + if (v === "" || out.includes(v)) continue; + out.push(v); + if (out.length >= MAX_FILTER_VALUES) break; + } + return out; +} + /** * ⭐⭐ W37-T26 / CONTRACT C4 — **THE CYCLE REFUSAL, WHICH IS THE TICKET'S `done-when` AND NOT AN * AFTERTHOUGHT.** View X filtered on "is in View Y" where Y is filtered on X is an infinite loop: @@ -3236,6 +3327,18 @@ export interface FilterRule { op: FilterOp | CohortOp | ViewOp; value: string; value2?: string; + /** + * ⭐ W51-T07 — the operand of a MULTI_VALUE_OPS leaf ("Agent is any of [A, B, C]"). + * + * ⛔ A LIST, not a comma-joined string, and that is not a style choice. `value` is an opaque + * string every layer already truncates and round-trips, so a set could have ridden in it the + * way `cohortIds` does — but a cohort id cannot contain a comma and a SELECT OPTION can + * ("Bouquets, mixed"), so joining would split one real choice into two that match nothing. + * The list survives as a list through `clean_filter_tree`, the SQL binder and both row + * evaluators. Present only on those five ops; absent everywhere else, which is what keeps + * every persisted leaf's cleaned shape byte-identical to what it always was. + */ + values?: string[]; /** * CG-8. Present on a MEASURE condition: the window the measure is summed over. Its presence * is what MAKES this a measure condition — no column condition has one, which is why every @@ -3298,6 +3401,12 @@ export function isRuleActive(rule: FilterRule): boolean { // whitespace value is INACTIVE rather than active-and-unanswerable. First, for the reason the // cohort line above it is first. if (rule.colId === VIEW_FIELD) return viewRuleId(rule.value) !== ""; + // W51-T07 — a MULTI-VALUE leaf is driven by the LIST it names and by nothing else. Third in + // the same family as the two arms above it, and placed here for the same reason: these ops + // leave `value` blank, so the tail rule "blank value means half-typed" would call a fully + // built `Agent is any of [A, B, C]` inactive and show every row. + if (MULTI_VALUE_OPS.has(rule.op as FilterOp)) + return filterValues(rule.values).length > 0; if (VALUE_FREE_OPS.has(rule.op as FilterOp)) return true; // "is within" is driven by its RANGE, never by `value`. if (rule.op === "within") return normalizeWindow(rule.dateWindow) != null; @@ -4007,6 +4116,138 @@ export interface RelationalTarget { */ export const PIVOT_PATH = "grid/pivot"; +/* ═══════════════════════════════════════════════════════════════════════════════════════════ + ⭐⭐ W51-T06 · RULINGS R2 + R5 · CONTRACT C6 — THE RELATED-DATABASE VOCABULARY. + + R2: *"A 'Linked database' tab exists for FORWARD link fields, REVERSE links … and the ODOO + BRIDGES … one tab per related table, resolved SERVER-SIDE."* So this file declares the SHAPE + of the server's answer and nothing about which edges exist: `platform/core/relations.py` is + the one declaration of that, and W51-T05 shipped it. + + ⛔⛔ `via` TRAVELS BACK VERBATIM, AND REBUILDING IT IS THE SILENT-WRONG-JOIN BUG. + `via.key` is the only member that identifies an edge on its own. `customer_data` really does + carry two bridges reading `{direction: "bridge", on: "partner_id"}` — orders, and order + lines — and `relations.pick` answers None on an ambiguous bag rather than returning the first + hit. A client that reconstructed `via` from `{direction, on}` would ask for a customer's order + LINES and be served their ORDERS: right shape, wrong question, every gate green. + ═══════════════════════════════════════════════════════════════════════════════════════════ */ + +/** The three ways one database is related to another. Mirrors `relations.DIRECTIONS`. */ +export type RelatedDirection = "forward" | "reverse" | "bridge"; + +/** `relations._entry`'s `via` bag, echoed back to the pinned read UNCHANGED. */ +export interface RelatedVia { + direction: RelatedDirection; + key: string; + field?: string; + on?: string; + from?: string; +} + +/** + * ONE entry of `GET /api/v1/grid/{table}/related`. + * + * ⚠ `served: false` IS NOT AN ERROR AND NOT A HIDDEN TAB. It records that the target grid is + * served from its stored copy rather than read through the mirror, so its window takes no + * predicate and the pin cannot be pushed into it yet. `bridge_customer_open_invoices` is the + * one such edge today. The tab RENDERS and REFUSES with the server's own sentence. + */ +export interface RelatedEntry { + key: string; + label: string; + target: string; + served: boolean; + via: RelatedVia; + where?: string; +} + +/** + * C6's pinned-read payload — `{table, record, via}` — identical on both Odoo doors. + * + * ⛔ NO `label` AND NO DISPLAY WORDS. The chip's sentence is a rendering concern; putting it on + * the wire would fork the rows cache key (`windowRowsPath`) on a rename and ask the server for + * two different reads of one edge. + */ +export interface RelatedPin { + table: string; + record: number; + via: RelatedVia; +} + +/** One TAB of the record view: the edge, plus the two lines of chrome clause 2 asks for. */ +export interface RelatedTab { + entry: RelatedEntry; + /** The TARGET DATABASE's own name, never the edge's label. */ + label: string; + /** The FIELD, and ONLY when two edges share one target. Empty string otherwise. */ + subtitle: string; +} + +/** + * The server's `/related` envelope, read defensively. An unreadable body is an EMPTY list, never + * a throw: a record whose relations cannot be listed still has to open its Fields tab. + */ +export function relatedEntries(body: unknown): RelatedEntry[] { + const b = body as { ok?: unknown; related?: unknown } | null; + if (!b || b.ok === false || !Array.isArray(b.related)) return []; + const out: RelatedEntry[] = []; + for (const raw of b.related as Record[]) { + const via = raw?.via as Record | undefined; + const direction = String(via?.direction ?? ""); + if (direction !== "forward" && direction !== "reverse" && direction !== "bridge") continue; + const target = String(raw?.target ?? ""); + const key = String(raw?.key ?? ""); + if (!target || !key) continue; + const bag: RelatedVia = { direction, key: String(via?.key ?? key) }; + if (via?.field) bag.field = String(via.field); + if (via?.on) bag.on = String(via.on); + if (via?.from) bag.from = String(via.from); + const entry: RelatedEntry = { + key, + label: String(raw?.label ?? target), + target, + // ⛔ ABSENT MEANS SERVED. A body from an older server that has not learned the key must + // not turn every tab into a refusal; the pinned read is the thing that answers for real. + served: raw?.served !== false, + via: bag, + }; + if (raw?.where) entry.where = String(raw.where); + out.push(entry); + } + return out; +} + +/** + * ⭐ CLAUSE 2 — a tab is labelled by the TARGET DATABASE, and SUBTITLED BY THE FIELD only when + * two edges share that target. + * + * ⛔ THE ENTRY'S OWN `label` IS NOT THE DATABASE'S NAME, and this is measured rather than + * assumed: `relations.forward_links` labels an entry with the FIELD's label, `reverse_links` + * with the source definition's label, `bridge_entries` with the bridge's. So the display name + * comes from `labelFor` (the link-target roster, which is the one producer of a database's name + * in this product) and the entry's own label falls back only when the roster cannot answer. + * + * ⛔ THE SUBTITLE IS CONDITIONAL, NOT DECORATIVE. R2 gives two tabs to two links between the + * same pair; printing the field under a target that has only ONE edge would be a second line + * that answers a question nobody asked (DESIGN section 4, never over-explain). + */ +export function relatedTabs( + entries: readonly RelatedEntry[], + labelFor: (target: string) => string, +): RelatedTab[] { + const perTarget = new Map(); + for (const entry of entries) + perTarget.set(entry.target, (perTarget.get(entry.target) ?? 0) + 1); + return entries.map((entry) => ({ + entry, + label: labelFor(entry.target) || entry.label || entry.target, + subtitle: + (perTarget.get(entry.target) ?? 0) > 1 + ? entry.via.field || entry.label || entry.key + : "", + })); +} + /** C10's request, verbatim. */ export interface PivotRequest { source: string; diff --git a/web/src/customer-grid/useCustomerData.ts b/web/src/customer-grid/useCustomerData.ts index 6438659b30c38d1ae5a226955170fa365776c91c..60689d937647c324f2419a968db9b7df7d7db5cd 100644 --- a/web/src/customer-grid/useCustomerData.ts +++ b/web/src/customer-grid/useCustomerData.ts @@ -22,10 +22,10 @@ // overlayEdits only holds this session's un-refetched changes. // --------------------------------------------------------------------------- -import { useCallback, useEffect, useRef, useState } from "react"; +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import type { Dispatch, SetStateAction } from "react"; import { topicForScope } from "./types"; -import type { CustomersPayload, Field, GridWorkspace, Row } from "./types"; +import type { CustomersPayload, Field, GridWorkspace, RelatedPin, Row } from "./types"; import { clearTopicRowsCache, dropTableRowsCache, @@ -233,6 +233,17 @@ interface CustomerDataOptions { includeWorkspace?: boolean; /** Defence in depth for read-only nested grids. */ writable?: boolean; + /** + * ⭐⭐ W51-T06 / C6 / R5 — THE PINNED READ: `{table, record, via}`, forwarded on EVERY read of + * a read-through grid so the rows arrive already narrowed to one record's related set. + * + * ⛔ THIS IS NOT `embeddedRecordIds` AND MUST NEVER BECOME IT. That path fetches the WHOLE + * table and filters to an id list in the browser, which on a connected source is standing + * rule 1 in the direction that matters: an uncapped mirror dragged client-side to be filtered + * locally. The predicate is compiled to SQL by the same `_compiled_read` the count and the + * aggregates run through, so `total` describes the pinned set rather than the table. + */ + related?: RelatedPin | null; } export function useCustomerData( @@ -242,6 +253,22 @@ export function useCustomerData( const bindSurface = options.bindSurface !== false; const includeWorkspace = options.includeWorkspace !== false; const writable = options.writable !== false; + /** + * ⭐⭐ W51-T06 / C6 — THE PIN, AS A STRING, AND THAT IS THE WHOLE OF THE STALE-CLOSURE FIX. + * + * ⛔ `requestWindow` IS A `useCallback`, AND A PIN READ OUT OF ITS CLOSURE GOES STALE. Its + * dependency list decides which copy of this value the SCROLL sends: the first window (fired + * by the load effect) would be correctly pinned and every page after it would be the whole + * table, appended underneath, under a count that still described the pinned set. A plausible + * screen with two populations in it and nothing red anywhere. The serialised form is the + * dependency BOTH readers take, so the two cannot disagree — the same discipline + * `windowRowsPath` uses to make a path and its cache key one value. + */ + const relatedKey = options.related ? JSON.stringify(options.related) : ""; + const related = useMemo( + () => (relatedKey ? (JSON.parse(relatedKey) as RelatedPin) : null), + [relatedKey] + ); // ⛔ SET BEFORE THE FIRST FETCH, not in an effect. Every event the grid emits carries this // scope, and an effect would run AFTER the first render — so a write triggered by that render // would be posted as `customer` from the Cohort surface. Module scope + a synchronous set is @@ -511,7 +538,19 @@ export function useCustomerData( // from the workspace that is still in flight beside this call, so it does not exist // yet. The grid re-asks with the saved view's predicate the moment it does — see // `windowPredicateKey` and the effect that consumes it. - ? fetchTableWindow(tableKey, { offset: 0, limit: WINDOW_ROWS }) + /* ⭐⭐ W51-T06 / C6 — THE PIN RIDES THE FIRST WINDOW TOO. It is not a predicate the + grid applies later: it is the PREMISE of the tab, so the very first read has to + carry it or the tab paints the whole database for one frame and then narrows, + which is a wrong answer that happens to be brief. */ + ? fetchTableWindow(tableKey, { offset: 0, limit: WINDOW_ROWS, related }) + /* ⛔ AND THE WHOLE-BOOK DOOR TAKES NO PREDICATE, MEASURED RATHER THAN ASSUMED. + `routes_tables.table_rows` (which `fetchTopicRows` reaches) accepts no filter + arguments at all and is in no lane's fence this wave, so a related tab whose target + is an ordinary user table has no pre-filtered read to call. The honest answer is a + REPORTED limit, not a client-side filter over the whole table -- that is precisely + the `embeddedRecordIds` pattern W51-T06 exists to delete. `RecordDetail` therefore + probes the pinned door first (`probeRelatedRead`) and prints the server's refusal + instead of mounting this read under a chip that claims one record. */ : fetchTopicRows(topic), wsPromise, ]); @@ -587,7 +626,10 @@ export function useCustomerData( // `topic` is a stable module constant per scope (topicForScope — ut topics are memoized // per key for exactly this dependency), so this cannot loop. `rowsBump` re-runs it on the // rows-stale signal only. - }, [scope, topic, rowsBump, includeWorkspace]); + // ⚠ `relatedKey` JOINS THE DEPS, W51-T06. The pin is part of the question this effect asks, + // so switching from one related tab to another (same target table, different edge) has to + // re-read. Without it the second tab would paint the first tab's rows. + }, [scope, topic, rowsBump, includeWorkspace, related, relatedKey]); // Optimistic overlay write: apply the edit immediately (so the grid cell and // the detail panel reflect it at once), snapshot the pre-edit entry, then @@ -683,12 +725,17 @@ export function useCustomerData( if (offset > 0 && inflightOffset.current === offset) return; const seq = ++windowSeq.current; if (offset > 0) inflightOffset.current = offset; - void fetchTableWindow(scope, { ...req, offset }).then((next) => { + /* ⭐⭐ W51-T06 / C6 — AND THE SCROLL CARRIES THE PIN, WHICH IS THE HALF A CLOSURE LOSES. + ⛔ `related` IS IN THE DEPENDENCY LIST BELOW FOR THIS ONE LINE. Left out, this callback + would keep the pin it was built with: the first page correct and every appended page the + WHOLE table, under a `total` that still described the pinned set. Nothing errors, the + count agrees with itself, and the rows are two different populations stacked. */ + void fetchTableWindow(scope, { ...req, related, offset }).then((next) => { if (offset > 0 && inflightOffset.current === offset) inflightOffset.current = null; if (seq !== windowSeq.current || !next) return; setData((prev) => mergeWindow(prev, next, offset)); }); - }, [scope]); + }, [scope, related]); const selectAssignedView = useCallback((viewId: string) => { // Assigned projections currently exist on the governed Customer surface. diff --git a/web/src/customer-grid/useVisibleRows.ts b/web/src/customer-grid/useVisibleRows.ts index cf13a4a2142d6dbe540c85938b03e4cac5a67b6c..bc72e90c2dda94141427f6b5fc37e929914707d3 100644 --- a/web/src/customer-grid/useVisibleRows.ts +++ b/web/src/customer-grid/useVisibleRows.ts @@ -17,12 +17,14 @@ import type { Conjunction, Field, FilterNode, + FilterOp, FilterRule, Row, SortSpec, VisibleRow, } from "./types"; -import { FILTER_OPS, cohortIds, isCohortRule, isFilterGroup, isMeasureRule, isRankOp, +import { FILTER_OPS, MULTI_VALUE_OPS, filterValues, + cohortIds, isCohortRule, isFilterGroup, isMeasureRule, isRankOp, isViewRule, normalizeViewOp, viewRuleId, ROUTE_PROJECTION_KEY, routeStopPosition, singleRouteScope, isBlankValue, isRuleActive, normalizeCohortOp, rhsColId } from "./types"; @@ -158,6 +160,21 @@ function matchFilter( // is a property of today's call graph and this file outlives it. if (isRankOp(rule.op)) return false; + // --- ⭐ W51-T07: the MULTI-VALUE family, ON THE OP and before every type branch ---------- + // Placed here for the reason the two value-free lines above are: these leaves carry a BLANK + // `value`, and each type branch below ends in a "blank value -> active and always true" + // short-circuit. Falling through even one of them would make `Agent is any of [A, B, C]` + // match every row under a count nobody would doubt. + if (MULTI_VALUE_OPS.has(rule.op as FilterOp)) { + // A numeric or date column does not OFFER these, but a stale saved view can carry one (a + // column that has since changed type). Matching NOTHING is the decision, in all three + // engines: `cmpNum`'s documented `default: true` would widen, and comparing a rounded + // number against its own string form would have the engines disagree about the RENDERING + // rather than the value (`String(5000)`, `str(5000)` and DuckDB's CAST do not agree). + if (isNumericType(f.type) || isDateType(f.type)) return false; + return matchMultiValue(rule.op, raw, filterValues(rule.values)); + } + // --- CG-9: the comparand is another CELL of this row, not a typed value ---------------- // Read once, here, so every type branch below coerces it through the LEFT field's type — the // same type this function is already dispatching on. `evalNode` has already established that @@ -280,6 +297,54 @@ function cmpText(op: FilterRule["op"], a: string, v: string): boolean { } } +/** + * ⭐ W51-T07 — the MEMBERS of one cell, for the multi-value SET ops. + * + * A `multiselect` cell is a comma-joined set (and may still arrive as an ARRAY from the wire, + * which `String()` joins on the same comma). A single-valued cell is a one-member set, so + * `hasAnyOf` over a select column means exactly what `isAnyOf` does there — one definition, not + * two that could disagree. + * + * Folded and trimmed exactly as `cmpText`'s operands are. A BLANK cell yields NO members, which + * is the decision the three engines pin as a lock-step case: a blank is not a member of + * anything, so `hasNoneOf` and `isNoneOf` answer TRUE over it and the other three answer FALSE. + */ +function cellMembers(raw: unknown): string[] { + return String(raw ?? "") + .toLowerCase() + .split(",") + .map((s) => s.trim()) + .filter((s) => s !== ""); +} + +/** + * ⭐ W51-T07 — the five multi-value operators, COMPOSED from the single-value comparator rather + * than written again beside it. + * + * That composition is the ticket's correctness target, not an economy: `isAnyOf [A, B, C]` is + * literally the OR of three `cmpText("eq", …)` calls, so it is the union of three `eq` leaves + * by construction, including how each one treats the connector's `(none)` sentinel. A parallel + * comparison would have to be shown equal to `eq` by testing, and only for the values tested. + */ +function matchMultiValue(op: FilterRule["op"], raw: unknown, values: string[]): boolean { + const want = values.map((v) => v.trim().toLowerCase()); + // ⛔ NO VALUES = UNANSWERABLE = MATCHES NOTHING, uniformly, and this is a SECOND layer: + // `isRuleActive` already calls such a leaf inactive, so `evalNode` never gets here. It is + // written anyway because the vacuous cases go the WIDENING way — `[].every(...)` is `true`, so + // `hasAllOf []` would match every row, and `!want.some(...)` would do the same for the two + // `none` operators. `filter_sql` answers `1=0` for the identical input; one definition. + if (!want.length) return false; + if (op === "isAnyOf" || op === "isNoneOf") { + const a = String(raw ?? "").toLowerCase(); + const hit = want.some((v) => cmpText("eq", a, v)); + return op === "isAnyOf" ? hit : !hit; + } + const members = cellMembers(raw); + if (op === "hasAllOf") return want.every((v) => members.includes(v)); + const hit = want.some((v) => members.includes(v)); + return op === "hasAnyOf" ? hit : !hit; +} + /** * Evaluate one node of the filter TREE against a row. * returns true/false = the node decided diff --git a/web/src/filter-kit/FilterBuilderPanel.tsx b/web/src/filter-kit/FilterBuilderPanel.tsx index caa168a456fbfc4c5e7ebafdd23da05462e012e6..2ae9086fd706cef4ed650a86d67ab10ce427ab79 100644 --- a/web/src/filter-kit/FilterBuilderPanel.tsx +++ b/web/src/filter-kit/FilterBuilderPanel.tsx @@ -12,8 +12,8 @@ // same panel serve a module whose rows this browser has never loaded. // --------------------------------------------------------------------------- -import { useCallback, useMemo, useState } from "react"; -import type { ReactNode } from "react"; +import { useCallback, useMemo, useRef, useState } from "react"; +import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react"; import type { Conjunction, Field, @@ -27,9 +27,10 @@ import type { Measure, } from "../customer-grid/types"; import { - COHORT_FIELD, MAX_COHORT_IDS, MAX_FILTER_DEPTH, RANK_OPS, STAT_KINDS, STAT_LABELS, + COHORT_FIELD, MAX_COHORT_IDS, MAX_FILTER_DEPTH, MAX_FILTER_VALUES, MULTI_VALUE_OPS, + RANK_OPS, STAT_KINDS, STAT_LABELS, VIEW_FIELD, VIEW_OPS, VIEW_OP_LABELS, normalizeViewOp, - VALUE_FREE_OPS, choiceOptions, cohortIds, filterTreeConj, filterTreeNodes, + VALUE_FREE_OPS, choiceOptions, cohortIds, filterTreeConj, filterTreeNodes, filterValues, filterableFields, isFilterGroup, isMeasureRule, isRankOp, normalizeCohortOp, rhsColId, } from "../customer-grid/types"; import type { CohortOp, StatKind } from "../customer-grid/types"; @@ -37,6 +38,10 @@ import type { AnchorMode } from "../customer-grid/windows"; import { ANCHOR_LABELS, ANCHOR_MODES, MAX_N } from "../customer-grid/windows"; import { FieldSelectButton } from "../customer-grid/FieldSelect"; import type { FieldSelectItem } from "../customer-grid/FieldSelect"; +// ⭐ W51-T07 — the house popover shell. `FieldSelectButton` above is SINGLE-select by +// construction and its file is not this ticket's to widen, so the multi-value picker below is a +// local control built on the same overlay every other picker in this panel opens through. +import { AnchoredOverlay } from "../customer-grid/OverlaySurface"; // W47-T13 (owner instruction 15) — the remove-a-condition mark, taken from the ONE icon // vocabulary rather than hand-drawn a second time. `filter-kit/FieldsHidePanel.tsx` already // imports across this same boundary for `FieldTypeIcon`, so the direction is established. @@ -180,13 +185,20 @@ function ConditionValue({ statusOptions, onValue, onValue2, + onValues, }: { rule: FilterRule; type: Field["type"]; statusOptions: string[]; onValue: (v: string) => void; onValue2: (v: string) => void; + onValues: (v: string[]) => void; }) { + // ⭐ W51-T07 — FIRST, and on the OP alone. Every arm below is untouched, which is the + // done-when's "the old single-value ops keep working for saved filters": a view holding + // `Status is Growing` renders through exactly the code that always rendered it. + if (MULTI_VALUE_OPS.has(rule.op as FilterOp)) + return ; if (rule.op === "between") { const inputType = type === "date" || type === "created_time" ? "date" : "number"; return ( @@ -373,6 +385,211 @@ function CohortPicker({ ); } +/** The house tick, drawn to the same 16px path `FieldSelect`'s own list rows wear, so a ticked + * row reads identically in both popovers. Same glyph, same class, no new icon language. */ +function TickMark() { + return ( + + + + ); +} + +/** The caret every closed picker on this surface wears. `FieldSelect`'s copy is local to that + * file; this is the same 16px path, not a second mark. */ +function PickerCaret() { + return ( + + + + ); +} + +/** + * ⭐ W51-T07 (owner instruction 25) — the value control for a MULTI-VALUE condition: + * `Where [Agent] [is any of] [Naomi] [Ravi] [Sam]`. + * + * CHIPS PLUS A TICK LIST, modelled on `CohortPicker` directly above, because it answers the same + * shape of question and the two must not read as two different controls. What is chosen is said + * in words beside the operator; what is available is ticked in a popover that STAYS OPEN, so + * three or more values are chosen in one visit rather than one reopen each. + * + * ⚠ NOT `FieldSelectButton`. That control is single-select by construction (`onChange(key)` + * replaces), and widening it belongs to its own file, not to this ticket. The trigger below + * borrows its CLASSES so the two look like one control family, and its `is-empty` modifier is + * what renders an unfinished condition as unfinished (D-229) — the same muted placeholder state + * every other value picker in this panel already uses. There is no second incompleteness mark. + * + * ⛔ EXACTLY ONE `.cg-cond-val` in the row, on the trigger. A chip is not a value control, and + * the shipped round-trip gate locates the value control by that class. + * + * A chosen value the column no longer declares is KEPT and marked `cg-chip--gone` (the same + * amber the cohort picker uses for a list that is gone), showing the value's own text. It + * filters to nothing, honestly, and the chip is what lets somebody remove it. + */ +function MultiValuePicker({ + rule, + options, + onValues, +}: { + rule: FilterRule; + options: string[]; + onValues: (values: string[]) => void; +}) { + const [open, setOpen] = useState(false); + const [q, setQ] = useState(""); + const triggerRef = useRef(null); + const listRef = useRef(null); + + const chosen = filterValues(rule.values); + const declared = new Set(options); + const atCap = chosen.length >= MAX_FILTER_VALUES; + const needle = q.trim().toLowerCase(); + const shown = needle + ? options.filter((o) => o.toLowerCase().includes(needle)) + : options; + + const close = () => { + setOpen(false); + setQ(""); + }; + const toggle = (value: string) => { + if (chosen.includes(value)) return onValues(chosen.filter((c) => c !== value)); + if (atCap) return; // the cap sentence in the popover says why + onValues([...chosen, value]); + }; + + /** Arrows walk the rows, and the find box is part of the loop — the same contract + * `FieldSelect`'s list keeps, so one keyboard habit serves both popovers. */ + const onListKeyDown = (event: ReactKeyboardEvent) => { + if (event.key !== "ArrowDown" && event.key !== "ArrowUp" + && event.key !== "Home" && event.key !== "End") return; + const rows = Array.from( + listRef.current?.querySelectorAll("button.cg-type-row") ?? [] + ).filter((el) => !el.disabled); + if (!rows.length) return; + event.preventDefault(); + const at = rows.indexOf(document.activeElement as HTMLButtonElement); + if (event.key === "Home") return rows[0].focus(); + if (event.key === "End") return rows[rows.length - 1].focus(); + const step = event.key === "ArrowDown" ? 1 : -1; + const next = at < 0 ? (step === 1 ? 0 : rows.length - 1) + : (at + step + rows.length) % rows.length; + rows[next].focus(); + }; + + return ( + + {chosen.map((value) => ( + + {value} + + + ))} + + {open && triggerRef.current && ( + +
+
+ + + + + setQ(event.target.value)} + /> +
+
+ {shown.map((value) => { + const on = chosen.includes(value); + return ( + + ); + })} + {shown.length === 0 && ( + // D-236: a column that declares nothing says so in its own words. A search that + // matched nothing is a DIFFERENT sentence, because it is a different situation. +
+ {options.length === 0 ? "No values yet" : "No value matches"} +
+ )} +
+ {atCap && ( +
+ {`A condition can name up to ${MAX_FILTER_VALUES} values. Remove one to add another.`} +
+ )} +
+
+ )} +
+ ); +} + // --- Filter: an Airtable-style RECURSIVE condition builder ----------------- // Anatomy per Airtable (captured from the live product 2026-07-25): // row 0 : static "Where" @@ -634,6 +851,18 @@ function LeafRow({ // these three" are the same three cohorts asked about differently, and clearing them would // make the obvious edit destructive. if (isCohort) return patch({ op }); + // ⭐ W51-T07 — a MULTI-VALUE leaf keeps its SET when the set operator changes, for exactly + // the reason the cohort line above it does: "is any of these three" and "is none of these + // three" are the same three values asked about differently, and clearing them would make the + // obvious edit destructive. The comparand goes, because a set question has no other side. + if (MULTI_VALUE_OPS.has(op as FilterOp)) + return onRule({ ...rule, op: op as FilterOp, value: "", value2: undefined, + rhs: undefined, dateWindow: undefined, + values: filterValues(rule.values) }); + // Leaving the family drops the list rather than leaving it to ride along invisibly on a + // condition that no longer reads it (`clean_filter_tree` emits `values` for these ops only). + if (MULTI_VALUE_OPS.has(rule.op as FilterOp)) + return onRule({ ...rule, op, values: undefined }); // C-OPS: a rank op arrives with its N already chosen (see rankDefault) and drops every // comparand — "the top 10 compared with another field" is not a question. if (isRankOp(op as string)) @@ -657,8 +886,11 @@ function LeafRow({ .filter((f) => f.key !== rule.colId && (isNumericType(t) ? isNumericType(f.type) : f.type === t)) .map((f) => ({ key: f.key, label: f.label, type: f.type })); + // W51-T07: and never for a multi-value op — "is any of [a list]" has no second side to + // compare against, so offering "another field" would promise a question no engine answers. const canCompareField = !isCohort && rule.op !== "within" && !VALUE_FREE_OPS.has(rule.op as FilterOp) && !isRankOp(rule.op) + && !MULTI_VALUE_OPS.has(rule.op as FilterOp) && rhsOptions.length > 0 && (isMeasure || isNumericType(t) || isDateFamily(t) || isTextComparable(t)); // ⭐ W46-T30 — the tail moved, and NOTHING ELSE DID. Everything under a text comparand was @@ -894,6 +1126,7 @@ function LeafRow({ statusOptions={choicesFor(rule.colId)} onValue={(v) => patch({ value: v })} onValue2={(v) => patch({ value2: v })} + onValues={(v) => patch({ values: v })} /> )} {/* W47-T13 (owner instruction 15) — A TRASH MARK, NOT AN ×. The glyph was ambiguous diff --git a/web/src/filter-kit/ops.ts b/web/src/filter-kit/ops.ts index 8d88c206935765cec4ebf17ee50bb16ec8ef3431..08e35bf84520b7334507ba5a96536562bc8ea255 100644 --- a/web/src/filter-kit/ops.ts +++ b/web/src/filter-kit/ops.ts @@ -20,7 +20,7 @@ import type { Measure, } from "../customer-grid/types"; import { - COHORT_FIELD, COHORT_OPS, MEASURE_OPS, MEASURE_PAIR_OPS, isFilterGroup, + COHORT_FIELD, COHORT_OPS, MEASURE_OPS, MEASURE_PAIR_OPS, MULTI_VALUE_OPS, isFilterGroup, isDateFamilyType, isNumericFieldType, isRankOp, normalizeCohortOp, } from "../customer-grid/types"; import type { CohortOp } from "../customer-grid/types"; @@ -72,15 +72,25 @@ export function opsForType(t: FieldType): FilterOp[] { // `select` and `user` are picked from a fixed list, so they behave like `status`: is / is // not / empty. `contains` on a chosen value is a substring test against a closed vocabulary — // it would find "Done" inside "Not done" and read as a bug. + // ⭐ W51-T07 (owner instruction 25) — "is any of" / "is none of" APPENDED, never prepended. + // The first entry is what `newCondition` seeds, and a new condition that starts on a + // multi-value op would open with an empty list, i.e. INACTIVE, which reads as a control that + // does nothing. `eq` stays the default; the set question is the second thing you reach for. if (t === "status" || t === "select" || t === "user") - return ["eq", "neq", "isEmpty", "isNotEmpty"]; + return ["eq", "neq", "isAnyOf", "isNoneOf", "isEmpty", "isNotEmpty"]; // A `multiselect` cell is a comma-joined SET, so the useful question is membership — "has" — // which is the EXISTING `contains` op over the joined string (no new engine vocabulary; the // ops are mirrored in filter_sql.py and inventing one here would break the lock-step). The // value is still picked from the declared options, so the substring caveat above is bounded // by the user's own choice list. `eq` reads "is exactly": the whole set is that one choice. + // + // ⭐ W51-T07 — and the three SET questions beside them, because the substring caveat above is + // exactly what `hasAnyOf` / `hasAllOf` / `hasNoneOf` remove: they compare whole MEMBERS of the + // joined set, so "has any of [Done]" can no longer find Done inside Not done. Appended, so + // `contains` stays the seeded default (see the status branch above). if (t === "multiselect") - return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"]; + return ["contains", "doesNotContain", "hasAnyOf", "hasAllOf", "hasNoneOf", + "eq", "neq", "isEmpty", "isNotEmpty"]; // ⭐ Wave-23 C7 — `json` gets EXACTLY the two value-free ops, and the omissions are the // decision. `contains` over a serialized document is a substring test against punctuation and // key names: `contains "12"` would match a key `id_12`, a value 12, a timestamp and a @@ -209,6 +219,25 @@ export function opLabel(op: FilterOp, t: FieldType): string { // Type-independent: Airtable words these identically for every field type. if (op === "isEmpty") return "is empty"; if (op === "isNotEmpty") return "is not empty"; + // ⭐ W51-T07 — the MULTI-VALUE family, type-independently and BEFORE the type branches, for + // the reason the rank line at the top of this function is first: a saved view whose column has + // since changed type must still SAY what it holds rather than falling through to a raw key. + // The wording matches `cohortOpLabel`, which has answered the same set question since + // 2026-07-27 — one vocabulary for "any of" / "all of" / "none of" across the whole builder. + if (MULTI_VALUE_OPS.has(op)) { + switch (op) { + case "isAnyOf": + return "is any of"; + case "isNoneOf": + return "is none of"; + case "hasAnyOf": + return "has any of"; + case "hasAllOf": + return "has all of"; + case "hasNoneOf": + return "has none of"; + } + } if (isDateFamily(t)) { switch (op) { case "eq": diff --git a/web/src/filter-kit/standalone.html b/web/src/filter-kit/standalone.html new file mode 100644 index 0000000000000000000000000000000000000000..464735ed6dcbd0daa5de5f9edd8185f52d183949 --- /dev/null +++ b/web/src/filter-kit/standalone.html @@ -0,0 +1,12 @@ + + + + + + Filter kit standalone + + +
+ + + diff --git a/web/src/filter-kit/standalone.tsx b/web/src/filter-kit/standalone.tsx new file mode 100644 index 0000000000000000000000000000000000000000..695adbc8c17aea703c52f6104d639bab9efa7956 --- /dev/null +++ b/web/src/filter-kit/standalone.tsx @@ -0,0 +1,66 @@ +// --------------------------------------------------------------------------- +// filter-kit / standalone.tsx — THE VISUAL-PROOF MOUNT, and nothing else. +// +// W51-T07 owed `shots/T07-multi-value-filter.png` and neither of the ordinary routes to a +// screenshot was open: deployed staging does not carry an unmerged lane branch, and the local +// app needs `STORE_BACKEND=pg` (the `hf` store repos have been 404 since 2026-08-30), which +// means Neon, which wave 51's shared-resources table reserves to ROOT. `FilterBuilderPanel` +// fetches nothing — every vocabulary it needs arrives as a prop — so it mounts here against +// fixtures with no backend, no auth and no tenant data at all. +// +// ⛔ THIS FILE NEVER SHIPS. `vite build`'s only input is `index.html`; the dev server serves any +// `.html` under the project root by path, which is what makes this work with no `vite.config.ts` +// change (that file belongs to no lane's fence). Confirm after any build that no emitted chunk +// names it. +// --------------------------------------------------------------------------- +import { useState } from "react"; +import { createRoot } from "react-dom/client"; +import { FilterBuilderPanel } from "./FilterBuilderPanel"; +import type { Field, FilterTree } from "../customer-grid/types"; +import "../index.css"; + +// A backend is never reached, but a stray fetch must not throw into the render either. +globalThis.fetch = (() => + Promise.resolve(new Response("{}", { status: 200 }))) as typeof fetch; + +const FIELDS: Field[] = [ + { key: "name", label: "Customer", type: "text" }, + { key: "agent", label: "Agent", type: "select", + options: ["Naomi", "Tara", "Devon", "Priya", "Marcus", "Yuki"] }, + { key: "stage", label: "Stage", type: "status", + options: ["New", "Qualified", "Proposal", "Won", "Lost"] }, + { key: "tags", label: "Tags", type: "multiselect", + options: ["VIP", "Wholesale", "Net 30", "Seasonal", "Do not call"] }, + { key: "owner", label: "Owner", type: "user" }, + { key: "no_options", label: "Region", type: "select" }, +] as unknown as Field[]; + +function App() { + const [filters, setFilters] = useState({ + conj: "and", + nodes: [ + // The money shot: three values ticked on a select column. + { colId: "agent", op: "isAnyOf", value: "", values: ["Naomi", "Tara", "Devon"] }, + // D-229 and D-236 in the same frame: a multi-value leaf with NO values yet, on a column + // that declares no options at all. It must render INCOMPLETE, never silently inactive, + // and its popover must say "No values yet" rather than "No value matches". + { colId: "no_options", op: "isAnyOf", value: "", values: [] }, + ], + } as unknown as FilterTree); + return ( +
+ +
+        {JSON.stringify(filters, null, 2)}
+      
+
+ ); +} + +createRoot(document.getElementById("root")!).render(); diff --git a/web/src/index.css b/web/src/index.css index b0f951fc64e9c75bc002c4edd30e1516fa7d9de5..2f69337eeb2d8ac9ce613a7d3af04051d1f0bceb 100644 --- a/web/src/index.css +++ b/web/src/index.css @@ -19,6 +19,16 @@ to inherit its spacing -- an @imported sheet loses every equal-specificity fight with this one. */ @import "./styles/wave42/hop-editor.css"; @import "./styles/wave42/rail-views.css"; +/* ⭐ WAVE 51 base kit (W51-T01). Imported HERE and not from the component, unlike every + wave since 43: ConfirmDialog is shared by three lanes on unrelated pages, and a + per-component import would land these rules in one lazy chunk and leave the dialog + unstyled everywhere else, with tsc and the build both green. */ +@import "./styles/wave51/kit.css"; +/* wave 51 -- one stylesheet per lane, pre-created at the wave base so no lane edits THIS file + (a shared file is a merge collision): A grid.css, C sheet-chrome.css, E sheet-engine.css. */ +@import "./styles/wave51/grid.css"; +@import "./styles/wave51/sheet-chrome.css"; +@import "./styles/wave51/sheet-engine.css"; @font-face { font-family: "Inter"; diff --git a/web/src/sheet/BindingEditor.tsx b/web/src/sheet/BindingEditor.tsx index cf9eba08354a64c9805f93ae60a976bdc586be90..ed7cb0310b534f68b291a82543ccbc39a88eda8f 100644 --- a/web/src/sheet/BindingEditor.tsx +++ b/web/src/sheet/BindingEditor.tsx @@ -1,4 +1,5 @@ -// sheet/BindingEditor.tsx — what a bound cell points at (wave 49, W49-T06, R4/R8/R14). +// sheet/BindingEditor.tsx — what a bound cell points at (wave 49, W49-T06, R4/R8/R14; +// wave 51, W51-T12, R9/R10/R11). // // ⭐⭐ R4 SAYS "THE FILTER USES THE EXACT SAME UI AS A VIEW'S FILTER", SO THIS MOUNTS // `filter-kit/FilterBuilderPanel` ITSELF. That component turned out to need NO change to run here: @@ -12,16 +13,37 @@ // filter through the same `compile_filter_tree`, so two shapes would mean two dialects and one of // them would eventually stop being tested. // +// ⛔⛔ W51-T12 - THE ROOT NODE IS `.sheet-binding-panel` AND NOT `.sheet-binding`, AND THAT ONE +// CLASS IS THE WHOLE TICKET. `styles/wave49/sheet.css` declares `.sheet-binding` as +// `position: fixed; z-index: var(--cg-z-drawer)` - an OVERLAY, floating over the canvas it +// describes. W50-QA-1 is what that costs: an absolutely positioned panel over the map made every +// pin beneath it unclickable, and no z-index repairs document-order stacking. The design contract's +// clause is that the right-side panel is a real COLUMN and the content beside it SHRINKS. +// `.sheet-page` is already a flex row (`align-items: stretch`) and this component already renders +// as one of its direct children, so a root of `flex: 0 0 380px` narrows `.sheet-body` - and that is +// observable as a MEASUREMENT (the grid's own width with the panel open versus closed), which is +// the one thing a screenshot cannot tell apart from an overlay. +// +// ⚠ THE NEW CLASS IS DELIBERATE, NOT COSMETIC. `wave49/sheet.css` loads from inside SheetPage's +// LAZY chunk and therefore BEATS `styles/wave51/sheet-chrome.css` (imported eagerly by index.css) +// at equal specificity, so an override of `.sheet-binding`'s `position` written in this lane's +// sheet would lose the cascade and change nothing on screen +// ([[a-lazy-chunk-stylesheet-beats-an-eager-one]]). A name nothing else declares has no fight to +// lose. The INNER classes (`.sheet-field`, `.sheet-scope`, `.sheet-radio`, `.sheet-binding-title`, +// `.sheet-binding-actions`) are all top-level selectors rather than descendants of `.sheet-binding`, +// so every one of them keeps its shipped paint. +// // ⚠ DESIGN CONTRACT: sentence case, quiet buttons, token-only colour and type, motion 150 ms // ease-out on opacity and transform, no emoji, and no em dash or en dash in any string on screen. -import { useEffect, useMemo, useState } from "react"; +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import { fetchWorkspace } from "../customer-grid/apiBridge"; import type { SurfaceScope } from "../customer-grid/apiBridge"; import { FieldTypeIcon } from "../customer-grid/icons"; import type { Field, FilterTree } from "../customer-grid/types"; import { FilterBuilderPanel } from "../filter-kit"; import { isNumericType } from "../filter-kit/ops"; +import { useEscapeClose } from "../ui/useEscapeClose"; import { previewCell } from "./sheetApi"; const AGGREGATES = [ @@ -39,6 +61,166 @@ const scopeOf = (database: string): SurfaceScope | null => { return database.startsWith("ut_") ? (database as SurfaceScope) : null; }; +// ══ THE PERIOD (R9) ═══════════════════════════════════════════════════════════════════════════ +// +// ⛔⛔ CONTRACT C2 SPELLS THIS ON THE WIRE AND THE UI DOES NOT GET A VOTE: +// `period: {unit: "month"|"quarter"|"year", start: "YYYY-MM", locked: boolean, ref?: A1}`. The +// unit values are LOWERCASE on the wire even though the picker reads Month / Quarter / Year, and +// `start` is a MONTH string for every unit. +// +// ⭐ `start` IS THE PERIOD'S FIRST MONTH, and that is the decision the ticket leaves implicit. +// `unit` and `start` have to jointly name exactly one period, so Q3 2026 is `2026-07` and the year +// 2026 is `2026-01`. Stamping today's month under a quarter unit would agree with nothing: the +// server compiler reads the pair, and two readings of `2026-08` under `quarter` (August, or Q3) +// are a silent disagreement that no screen shows. + +export type PeriodUnit = "month" | "quarter" | "year"; + +export interface PeriodBinding { + unit: PeriodUnit; + start: string; + locked: boolean; + ref?: string; +} + +export const PERIOD_UNITS: { unit: PeriodUnit; label: string }[] = [ + { unit: "month", label: "Month" }, + { unit: "quarter", label: "Quarter" }, + { unit: "year", label: "Year" }, +]; + +const MONTH_NAMES = [ + "January", "February", "March", "April", "May", "June", + "July", "August", "September", "October", "November", "December", +]; + +/** How many months one step of a unit covers. The only place that arithmetic is stated. */ +const MONTHS_PER_UNIT: Record = { month: 1, quarter: 3, year: 12 }; + +/** The noun a sentence uses for one step. Sentence case, and no dash anywhere near it. */ +const UNIT_NOUN: Record = { + month: "month", quarter: "quarter", year: "year", +}; + +const pad2 = (n: number) => String(n).padStart(2, "0"); + +/** `{year, month}` out of a `"YYYY-MM"`; today when the string is absent or malformed. */ +function splitYm(ym: string): { y: number; m: number } { + const hit = /^(\d{4})-(\d{2})$/.exec(ym ?? ""); + if (!hit) { + const now = new Date(); + return { y: now.getFullYear(), m: now.getMonth() + 1 }; + } + const m = Number(hit[2]); + return { y: Number(hit[1]), m: m >= 1 && m <= 12 ? m : 1 }; +} + +const joinYm = (y: number, m: number) => `${y}-${pad2(m)}`; + +/** THE PERIOD'S FIRST MONTH, which is what `start` means. See the block above. */ +export function normalizePeriodStart(unit: PeriodUnit, ym: string): string { + const { y, m } = splitYm(ym); + if (unit === "year") return joinYm(y, 1); + if (unit === "quarter") return joinYm(y, 1 + 3 * Math.floor((m - 1) / 3)); + return joinYm(y, m); +} + +/** Move a start by whole periods. Negative steps go back; this is also the drag rule's maths. */ +export function shiftPeriodStart(unit: PeriodUnit, ym: string, steps: number): string { + const { y, m } = splitYm(normalizePeriodStart(unit, ym)); + const total = y * 12 + (m - 1) + steps * MONTHS_PER_UNIT[unit]; + return joinYm(Math.floor(total / 12), (total % 12) + 1); +} + +/** The period a person reads: "July 2026", "Q3 2026", "2026". */ +export function periodLabel(unit: PeriodUnit, ym: string): string { + const { y, m } = splitYm(normalizePeriodStart(unit, ym)); + if (unit === "year") return String(y); + if (unit === "quarter") return `Q${Math.floor((m - 1) / 3) + 1} ${y}`; + return `${MONTH_NAMES[m - 1]} ${y}`; +} + +const todayYm = () => { + const now = new Date(); + return joinYm(now.getFullYear(), now.getMonth() + 1); +}; + +/** + * ⭐⭐ W51-T12 - THE READ-SIDE MIGRATION, AND IT IS A NAMED FUNCTION SO A GATE CAN PIN IT. + * + * Before this ticket a binding's period was `{ref}` and nothing else: a raw typed A1 string, with + * no unit, no start and no lock. Under R9 an UNLOCKED period SHIFTS when the cell is copied across + * columns, so reading an old binding as unlocked would change what a shipped cell answers the first + * time somebody dragged it - a value moving on its own, with no edit and no warning. + * + * ⛔ SO A `ref`-ONLY PERIOD BECOMES LOCKED. `unit` and `start` are non-optional in C2 and have to + * carry something, but on a ref-driven period they are INERT: the referenced cell decides the + * period, and `locked: true` is what stops the drag rule from touching it either way. + */ +export function migratePeriod(raw: unknown): PeriodBinding | null { + if (!raw || typeof raw !== "object") return null; + const p = raw as Record; + const ref = typeof p.ref === "string" && p.ref.trim() ? p.ref.trim() : ""; + const declared = PERIOD_UNITS.some((u) => u.unit === p.unit); + if (!declared) { + // The legacy shape. Nothing shifts by surprise: it reads back LOCKED. + if (!ref) return null; + return { unit: "month", start: normalizePeriodStart("month", todayYm()), locked: true, ref }; + } + const unit = p.unit as PeriodUnit; + const start = normalizePeriodStart( + unit, typeof p.start === "string" ? p.start : todayYm(), + ); + const locked = p.locked === true; + return ref ? { unit, start, locked, ref } : { unit, start, locked }; +} + +// ══ THE DRAG RULES (R10) ══════════════════════════════════════════════════════════════════════ +// +// TWO DIRECTIONAL SETTINGS, and C2 spells them `onDrag: {across: "period"|"none", +// down: {field: key}|"none"}`. Defaults: across = period, down = none. + +export type DragAcross = "period" | "none"; + +export interface OnDragBinding { + across: DragAcross; + down: { field: string } | "none"; +} + +/** + * WHICH COLUMNS "next value of" CAN WALK, and it is NOT `isNumericType`. + * + * ⛔ R10 names a SINGLE-SELECT or a LINK, because those are the only two field kinds with an + * ORDER to advance through: a select has its declared option order, a link has the linked table's + * view order. `multiselect` is excluded by name and `multi` is excluded again by flag, because a + * cell holding a SET has no next value - it has several, and picking one of them would be this + * component inventing an answer. + */ +export function isDragDownField(f: Field): boolean { + if (f.multi) return false; + return f.type === "select" || f.type === "status" || f.type === "link"; +} + +/** The saved `onDrag`, defaulted. `down` is carried as a field key, empty meaning nothing. */ +export function readOnDrag(raw: unknown): { across: DragAcross; down: string } { + const d = (raw && typeof raw === "object" ? raw : {}) as Record; + const across: DragAcross = d.across === "none" ? "none" : "period"; + const down = d.down; + if (down && typeof down === "object") { + const key = (down as Record).field; + if (typeof key === "string" && key) return { across, down: key }; + } + return { across, down: "" }; +} + +/** `scope.adoptedFrom` (R11): the view was purged and its filter was copied into this cell. */ +function adoptedFromOf(initial: Record | null | undefined): string { + const scope = initial?.scope as Record | undefined; + const adopted = scope?.adoptedFrom as Record | undefined; + const name = adopted?.name; + return typeof name === "string" ? name : ""; +} + export interface BindingEditorProps { workbookId: string; addr: string; @@ -60,12 +242,40 @@ export default function BindingEditor({ const [scopeKind, setScopeKind] = useState<"view" | "filter">("view"); const [viewId, setViewId] = useState(""); const [tree, setTree] = useState({ conj: "and", nodes: [] }); - const [periodRef, setPeriodRef] = useState(""); const [fields, setFields] = useState([]); const [views, setViews] = useState<{ id: string; name: string }[]>([]); const [preview, setPreview] = useState(""); const [notice, setNotice] = useState(""); + // ⚠ THE MIGRATION RUNS ONCE, AT MOUNT, and its result seeds the controls. Running it on every + // render would re-read `initial` after the person had already changed a control, which is how an + // editor forgets an edit the moment its parent re-renders for an unrelated reason. + const migrated = useState(() => migratePeriod(initial?.period))[0]; + const savedDrag = useState(() => readOnDrag(initial?.onDrag))[0]; + + const [unit, setUnit] = useState(migrated?.unit ?? "month"); + const [start, setStart] = useState( + migrated?.start ?? normalizePeriodStart("month", todayYm()), + ); + const [locked, setLocked] = useState(migrated?.locked ?? false); + const [periodRef, setPeriodRef] = useState(migrated?.ref ?? ""); + // "Use a cell" is a LINK that REVEALS the A1 input (R9). The input was the whole period control + // before this ticket and it is not deleted, only demoted to the thing behind that link. + const [refOpen, setRefOpen] = useState(Boolean(migrated?.ref)); + const [across, setAcross] = useState(savedDrag.across); + const [downField, setDownField] = useState(savedDrag.down); + + const adoptedFrom = adoptedFromOf(initial); + + // ⭐ ESCAPE CLOSES THE PANEL, through the base kit's ONE arbiter (C8) rather than a listener of + // this component's own. `cancelEditFirst` stays FALSE: the done-when says the panel closes on + // Escape, and opting in would make the FIRST Escape do nothing whenever focus sat in one of the + // text inputs this panel is full of. + const panelRef = useRef(null); + const onEscape = useCallback(() => onCancel(), [onCancel]); + const escapeContainer = useCallback(() => panelRef.current, []); + useEscapeClose(true, onEscape, { container: escapeContainer }); + // The field and view lists come from the SAME door the grid uses, so a cell can never offer a // column the grid does not have. useEffect(() => { @@ -96,6 +306,12 @@ export default function BindingEditor({ [fields], ); + /** R10's list, and a DIFFERENT predicate from the one above. See `isDragDownField`. */ + const dragDownFields = useMemo( + () => fields.filter(isDragDownField), + [fields], + ); + /** * ⭐⭐ W50-T21 (owner instruction 24: *"Sheet column picker (sum/count) shows the Field icons."*) * @@ -128,12 +344,22 @@ export default function BindingEditor({ const scope: Record = scopeKind === "view" ? { view_id: viewId, view_name: views.find((v) => v.id === viewId)?.name ?? "" } : { filter: tree }; + // R11: a filter ADOPTED from a purged view keeps saying so. The sentence in the panel is the + // only trace of where that filter came from, and re-saving the cell must not erase it. + const adopted = (initial?.scope as Record | undefined)?.adoptedFrom; + if (scopeKind === "filter" && adopted) scope.adoptedFrom = adopted; const out: Record = { database, aggregate: agg, scope }; - // R14: a period SOURCE is a `$`-anchored cell reference. The A1 resolver reads it BEFORE the - // query is built, so it is an INPUT to the filter and never a post-filter. - if (periodRef.trim()) out.period = { ref: periodRef.trim() }; + // C2's period, spelled the contract's way. R14: a period SOURCE is a `$`-anchored cell + // reference; the A1 resolver reads it BEFORE the query is built, so it is an INPUT to the + // filter and never a post-filter. It rides ALONGSIDE the unit and the start rather than + // replacing them, because the pair still names what the cell falls back to. + const period: Record = { unit, start, locked }; + if (refOpen && periodRef.trim()) period.ref = periodRef.trim(); + out.period = period; + out.onDrag = { across, down: downField ? { field: downField } : "none" }; return out; - }, [database, fn, field, scopeKind, viewId, views, tree, periodRef]); + }, [database, fn, field, scopeKind, viewId, views, tree, initial, + unit, start, locked, refOpen, periodRef, across, downField]); // ⭐ THE NUMBER APPEARS BEFORE SAVING. `preview` evaluates the binding without persisting it, // which is what lets someone see whether they picked the right thing while they can still change @@ -152,111 +378,330 @@ export default function BindingEditor({ const ready = Boolean(database) && (fn === "count" || Boolean(field)) && (scopeKind === "filter" || Boolean(viewId)); - return ( -
-

{`What ${addr} points at`}

+ const { y: startYear, m: startMonth } = splitYm(start); + const thisYear = new Date().getFullYear(); + const years: number[] = []; + for (let y = thisYear - 6; y <= thisYear + 1; y += 1) years.push(y); + if (!years.includes(startYear)) years.push(startYear); + years.sort((a, b) => a - b); - + const setYear = (y: number) => setStart(normalizePeriodStart(unit, joinYm(y, startMonth))); + const setMonthOfYear = (m: number) => setStart(normalizePeriodStart(unit, joinYm(startYear, m))); -
+ const downLabel = dragDownFields.find((f) => f.key === downField)?.label ?? ""; + + return ( +
+
+

{`What ${addr} points at`}

+ +
+ + {/* ⛔ THE SCROLLER IS THIS WRAPPER, NOT THE PANEL. A 380px column holding the whole filter + builder is taller than the page, and a panel that scrolls as a whole pushes Save below + the fold with nothing on screen saying it is there. */} +
- {/* Count takes no column, and offering one would suggest count(column), which skips - blanks and answers a smaller number than the person meant. */} - {fn !== "count" && ( -
- Column - {/* ⭐ THE SEARCH BOX HAS NO CONDITION AROUND IT (R16). See the note on `shownFields`. */} -
- - - - - setFieldQuery(e.currentTarget.value)} - /> + +
+ + {/* Count takes no column, and offering one would suggest count(column), which skips + blanks and answers a smaller number than the person meant. */} + {fn !== "count" && ( +
+ Column + {/* ⭐ THE SEARCH BOX HAS NO CONDITION AROUND IT (R16). See the note on `shownFields`. */} +
+ + + + + setFieldQuery(e.currentTarget.value)} + /> +
+
+ {shownFields.map((f) => ( + + ))} +
+ {/* ⛔ AN EMPTY LIST SAYS WHY (R16), because a blank box reads as a broken picker and + the two causes need different acts from the reader. */} + {shownFields.length === 0 && ( +

+ {numericFields.length === 0 + ? "This database has no number column to total." + : "No column matches that search."} +

+ )}
-
- {shownFields.map((f) => ( -
+ +
+ Rows to include + + {scopeKind === "view" && ( + + )} + + {scopeKind === "filter" && ( + + )} +
+ + {/* ══ R9: THE PERIOD ══════════════════════════════════════════════════════════════════ */} +
+ Period + + + +
+ + {unit === "month" && ( + + )} + {unit === "quarter" && ( + )}
- )} -
-
- Rows to include - - {scopeKind === "view" && ( - - )} - - {scopeKind === "filter" && ( - - )} -
- - - - {preview &&

{`This cell would show ${preview}`}

} - {notice &&

{notice}

} + {/* THE QUICK PICKS. They normalize through the same function the pickers do, so This + never stamps today's month under a quarter or a year. */} +
+ + +
+ + {/* ⭐ R9's LOCK. A switch rather than a checkbox: it has two states with names, and the + sentence under it says what each one costs when the cell is copied. */} +
+ +

+ {locked + ? "Locked, so any copy of this cell keeps this period." + : `Not locked, so copying right or left moves the period by one ${UNIT_NOUN[unit]} ` + + "per column, and copying up or down keeps it."} +

+
+ + {/* ⭐ "Use a cell" STAYS A LINK (R9). It reveals the A1 input rather than replacing the + picker, so the ordinary reader never meets a cell reference and the person who wants + one is one click away from it. */} + {!refOpen && ( + + )} + {refOpen && ( + + )} + + + {/* ══ R10: THE DRAG RULES ═════════════════════════════════════════════════════════════ */} +
+ When dragged + + + + + + {dragDownFields.length === 0 && ( +

+ This database has no single select or link column to walk, so dragging down repeats + the same rows. +

+ )} +
+ + {/* ══ WHAT THIS CELL POINTS AT, IN SENTENCES ══════════════════════════════════════════ + The panel's whole reason for being a panel: the period, the lock, the two drag rules + and, when the view behind it was purged, where its filter came from. */} +
+

+ {refOpen && periodRef.trim() + ? `Period: taken from cell ${periodRef.trim()}.` + : `Period: ${periodLabel(unit, start)}.`} +

+

+ {locked + ? "The period is locked, so a copy keeps it." + : `The period is not locked, so it shifts by one ${UNIT_NOUN[unit]} per column.`} +

+

+ {across === "period" + ? `Dragged across: the period moves forward one ${UNIT_NOUN[unit]} per column.` + : "Dragged across: nothing changes."} +

+

+ {downField + ? `Dragged down: the next value of ${downLabel}.` + : "Dragged down: nothing changes."} +

+ {adoptedFrom && ( +

+ {`Filter adopted from the deleted view ${adoptedFrom}`} +

+ )} +
+ + {preview &&

{`This cell would show ${preview}`}

} + {notice &&

{notice}

} +
+ + + void; + /** The import landed: this is the workbook it made, and the host opens it. */ + onOpened: (workbookId: string) => void; +} + +/** 750ms x 240 ticks is three minutes, which is the cap and the sentence below agrees with it. */ +const POLL_MS = 750; +const POLL_TICKS = 240; +const POLL_MINUTES = Math.round((POLL_MS * POLL_TICKS) / 60000); + +/** The word each state wears, sentence case, exactly as the done-when names them. */ +const STATE_LABEL: Record = { + reading: "Reading", + cells: "Cells", + formats: "Formats", + recalc: "Recalculating", + done: "Done", + refused: "Stopped", +}; + +/** ...and the sentence under it, because a single word is a label and not an explanation. */ +const STATE_NOTE: Record = { + reading: "Reading the file.", + cells: "Reading the cells and their values.", + formats: "Reading the number formats.", + recalc: "Recalculating every formula and comparing it to the file.", + done: "Opening the workbook.", + refused: "The import stopped.", +}; + +const NOT_AVAILABLE = "Importing a workbook is not available yet."; + +const wait = (ms: number) => new Promise((done) => { window.setTimeout(done, ms); }); + +/** + * ⛔⛔ THE ORDER OF THESE BRANCHES IS THE WHOLE OF THE CHECK, and it is ordered by WHAT EACH STATUS + * PROVES rather than by the numbers. A 413 and any NAMED refusal both prove the route is THERE and + * answered about this file; only an unnamed 4xx is evidence of absence. Read the other way round, + * the first oversized file would convince this client permanently that import does not exist, with + * nothing on screen saying what actually happened. + * + * ⚠ AND THE FALLBACK IS KEYED ON `>= 400` EXCEPT 403, NEVER ON A CODE LIST. An unbuilt route under + * a path parameter answers 405, not 404 [[an-unbuilt-route-under-a-path-param-answers-405]], and a + * 403 is a permission answer from a route that plainly exists. + */ +/** + * ⛔⛔ `unknown` IS NOT THE ONLY UNNAMED CODE, AND THAT COST THIS TICKET ITS DONE-WHEN. + * The API wraps EVERY HTTP error in its own envelope, so an unbuilt route answers + * {"error": {"code": "http_405", "message": "Method Not Allowed"}} + * and `res.code !== "unknown"` reads that as a NAMED refusal. The dialog then showed the reason + * phrase `Method Not Allowed` to a person who asked to import a spreadsheet, and the + * not-available-yet sentence below was unreachable. Measured in a live browser, not predicted. + * ⭐ A code the SERVER'S OWN VOCABULARY defines (`sheet_too_many_cells`, `workbook_too_large`) + * is a sentence worth showing. `http_` is the transport restating itself. + */ +const HTTP_ENVELOPE = /^http_\d{3}$/; + +export function refusalSentence(res: { status: number; code: string; message: string }): string { + const named = res.code !== "unknown" && !HTTP_ENVELOPE.test(res.code); + if (res.status === 0) return res.message; + if (res.status === 413) { + return named + ? res.message + : `That file is over the ${IMPORT_MAX_MB} MB limit the server accepts.`; + } + if (named) return res.message; + if (res.status === 403) return res.message; + if (res.status >= 400 && res.status !== 403) return NOT_AVAILABLE; + return res.message; +} + +/** + * The client's own two refusals, said as sentences naming the cap and the count. + * + * ⚠ THE COMPARISON AND THE PRINTED NUMBER SHARE ONE DIVISOR, or a file could read "25.0 MB" on + * screen and still be refused. The test is `>` rather than `>=`, so a file exactly at the cap is + * offered to the server, which is the side that owns the limit. + */ +export function fileRefusal(file: File): string { + if (!/\.xlsx$/i.test(file.name)) { + return "Loopable reads .xlsx workbooks. Choose a file saved in that format."; + } + if (file.size > IMPORT_MAX_BYTES) { + const mb = (file.size / BYTES_PER_MB).toFixed(1); + return `This file is ${mb} MB; the limit is ${IMPORT_MAX_MB} MB.`; + } + return ""; +} + +/** How many formula cells the differential is over. Zero means there is nothing to state. */ +export function formulaCellsSeen(job: ImportJob | null): number { + const report = job?.report; + return report ? report.matched + report.mismatched.length : 0; +} + +type Phase = "idle" | "running" | "ended"; + +export default function ImportDialog({ open, onCancel, onOpened }: ImportDialogProps) { + const [file, setFile] = useState(null); + const [phase, setPhase] = useState("idle"); + const [job, setJob] = useState(null); + const [sentence, setSentence] = useState(""); + /** Remounts the native input, which is the only way to clear what it is showing. */ + const [pick, setPick] = useState(0); + + /** + * ⛔ THE RUN TOKEN IS WHAT MAKES CANCEL AND UNMOUNT TERMINAL. Bumping it orphans every pending + * tick of the loop that read the old value, so a poll whose dialog is gone cannot call + * `setState` on an unmounted component or reopen a stale progress bar over a fresh import. + */ + const runRef = useRef(0); + const stop = useCallback(() => { runRef.current += 1; }, []); + useEffect(() => () => { runRef.current += 1; }, []); + + const poll = useCallback(async (id: string, run: number) => { + for (let tick = 0; tick < POLL_TICKS; tick += 1) { + await wait(POLL_MS); + if (run !== runRef.current) return; + const read: Result = await readImportJob(id); + if (run !== runRef.current) return; + if (!read.ok) { + setPhase("ended"); + setSentence(refusalSentence(read)); + return; + } + setJob(read.value); + if (read.value.state === "refused") { + setPhase("ended"); + setSentence(read.value.sentence || "The import stopped and the server did not say why."); + return; + } + if (read.value.state === "done") { + setPhase("ended"); + if (read.value.workbook_id) { + onOpened(read.value.workbook_id); + return; + } + setSentence("The import finished and the server did not say which workbook it made."); + return; + } + } + setPhase("ended"); + setSentence( + `Nothing has come back from the import for ${POLL_MINUTES} minutes. ` + + "Close this and try again.", + ); + }, [onOpened]); + + const start = useCallback(async () => { + if (!file) { + setSentence("Choose an .xlsx file to import."); + return; + } + const refused = fileRefusal(file); + if (refused) { + setSentence(refused); + return; + } + stop(); + const run = runRef.current; + setSentence(""); + setJob(null); + setPhase("running"); + const started = await importWorkbook(file); + if (run !== runRef.current) return; + if (!started.ok) { + setPhase("ended"); + setSentence(refusalSentence(started)); + return; + } + if (!started.value.job) { + setPhase("ended"); + setSentence("The server accepted the file and did not say which job is reading it."); + return; + } + await poll(started.value.job, run); + }, [file, poll, stop]); + + /** After a refusal the primary starts over rather than silently re-posting the same file. */ + const reset = useCallback(() => { + stop(); + setJob(null); + setSentence(""); + setFile(null); + setPick((n) => n + 1); + setPhase("idle"); + }, [stop]); + + const dismiss = useCallback(() => { stop(); onCancel(); }, [onCancel, stop]); + + const onPrimary = () => { + if (phase === "running") return; + if (phase === "ended") { reset(); return; } + void start(); + }; + + const running = phase === "running"; + const ended = phase === "ended"; + const pct = Math.round((job?.progress ?? 0) * 100); + const seen = formulaCellsSeen(job); + const report = job?.report; + + return ( + +

+ Loopable reads the values, the formulas, the number formats and the layout. Files up to + {` ${IMPORT_MAX_MB}`} MB. +

+ + {/* ⛔ THE NATIVE INPUT, ON PURPOSE. It is keyboard reachable, it carries the operating + system's own file browser, and `accept` filters the picker without ever opening a + byte. A custom drop zone would be a second control shape for a job the platform + already does better. */} + { + const next = event.currentTarget.files?.[0] ?? null; + setFile(next); + setSentence(next ? fileRefusal(next) : ""); + }} + /> + + {job ? ( +
+

{STATE_LABEL[job.state]}

+
+ +
+

{STATE_NOTE[job.state]}

+
+ ) : null} + + {/* ⭐ R1'S DIFFERENTIAL, AND IT IS GUARDED ON HAVING SEEN A FORMULA AT ALL. "Matched 0 of + 0 formula cells" is a measurement nobody took, printed on a screen, which is the same + rule `sheetApi.ts` states for a recalc time the server never measured. A workbook with + no formulas shows no line rather than a row of zeroes. */} + {report && seen > 0 ? ( +

+ {`Matched ${report.matched} of ${seen} formula cells.`} +

+ ) : null} + + {report && report.unsupported.length > 0 ? ( +
+

These parts of the file did not come across.

+ {report.unsupported.map((item) => ( +

{item}

+ ))} +
+ ) : null} + + {/* The server's own words, verbatim. A rephrasing here would be this client inventing a + reason for something only the server watched happen. */} + {sentence ?

{sentence}

: null} +
+ } + /> + ); +} diff --git a/web/src/sheet/Ribbon.tsx b/web/src/sheet/Ribbon.tsx index 433e58cba1d860ad6d68117cd50face67537b45e..d9c5327abad90050311a153b8a8156eaffd05cd7 100644 --- a/web/src/sheet/Ribbon.tsx +++ b/web/src/sheet/Ribbon.tsx @@ -1,21 +1,31 @@ -// sheet/Ribbon.tsx — the Sheet's formatting ribbon (wave 50, W50-T19, amendment A1). +// sheet/Ribbon.tsx — the Sheet's HOME ribbon (wave 50, W50-T19/A1; wave 51, W51-T15, ruling R8). // // ⭐⭐ WHAT THIS COMPONENT IS AND IS NOT. It is a `role="toolbar"` of STATELESS controls: every -// button reports one patch and holds nothing. The selection, the cells and the commit all live in -// `SheetGrid.tsx`, which routes a patch through the page's ONE commit door so a format change is -// one history step and one save, exactly like a paste. A ribbon that kept its own idea of the -// current style would drift from the cell the moment an undo landed. +// button reports one patch or one named act and holds nothing. The selection, the cells and the +// commit all live in `SheetGrid.tsx`, which routes a patch through the page's ONE commit door so a +// format change is one history step and one save, exactly like a paste. A ribbon that kept its own +// idea of the current style would drift from the cell the moment an undo landed. // -// ⚠ THERE ARE NOW TWO `role="toolbar"` REGIONS ON THIS PAGE, AND THEY ARE DIFFERENT TOOLBARS. -// `.sheet-toolbar` (aria-label "Sheet") carries the workbook's own acts: its title and Refresh. -// This one (aria-label "Formatting") carries acts on the SELECTION. Two labelled toolbars is the -// correct answer for a screen reader; one toolbar holding both would announce Refresh as a -// formatting control. +// ⭐⭐ W51-T15 — TWO EMISSIONS, AND THE SECOND ONE IS A CONTRACT WITH A LATER TICKET. +// `onApply(CellStylePatch)` is a style the document already understands. `onAction({kind, arg})` +// is a NAMED ACT, and its `kind` is a closed TypeScript union on purpose: W51-T16 implements the +// acts, and a union is what stops it inventing a name this file does not emit or handling one that +// never arrives. Every control in R8's roster is present, labelled and focusable NOW even where +// its act is still owned by that ticket; a control that exists but is unreachable is the harder +// defect to find later. // -// ⭐ ROVING FOCUS, WHICH NOTHING ELSE IN THIS TREE HAD. `CellActionBar` is a `role="toolbar"` of -// plain buttons with no `onKeyDown`, so a keyboard user tabs through every control in it. Here -// the toolbar is ONE tab stop and the arrows move within it (ArrowLeft / ArrowRight, Home / End), -// which is the WAI-ARIA toolbar pattern and what the PRD's interaction layer names. +// ⛔ THERE IS EXACTLY ONE `role="toolbar"` HERE AND NONE IN `SheetGrid.tsx` (W51-T15). It used to +// be two: this one, plus a second strip labelled "Rows and columns" carrying Insert row, Delete +// row, Insert column, Delete column, Add rows, Add columns and Freeze panes. R8 puts those +// acts in the Cells group of the Home row, so the strip is folded in and gone. Two toolbars over +// one grid was also the thing instruction 8 was complaining about: a second white line. +// +// ⭐ ROVING FOCUS, AND IT SURVIVES A COLLAPSE. The whole ribbon is ONE tab stop and the arrows move +// within it (ArrowLeft / ArrowRight, Home / End), which is the WAI-ARIA toolbar pattern. When the +// ribbon is COLLAPSED the roving order shrinks to the tab strip and the chevron rather than +// disappearing, because a collapsed ribbon a keyboard cannot re-open is a trap. The handler and +// the ref both live on the SHELL, one level above the toolbar row, which is what lets the row +// itself unmount without taking the keyboard with it. // // ⛔ THE ROVING HANDLER IS GATED ON `open === ""`. A colour swatch grid and a format menu are // their own arrow-key surfaces; leaving the toolbar handler live underneath would move the @@ -28,11 +38,45 @@ // labels with no ALL CAPS chrome; motion is 150 ms ease-out on opacity and transform only; z-order // rides a `--cg-z-*` token. No em dash or en dash in any string that reaches a screen. -import { useCallback, useEffect, useRef, useState } from "react"; +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import type { KeyboardEvent, ReactNode } from "react"; import { CELL_FORMAT_KINDS } from "./types"; import type { CellFormatKind, CellStyle, CellStylePatch } from "./types"; +/** + * ⭐⭐ THE ACT VOCABULARY, CLOSED. W51-T16 builds against this union and nothing else; adding a + * control means adding its name here first, which is exactly the review moment that was missing + * when the borders button shipped doing nothing (instruction 17). + */ +export type RibbonActionKind = + // Clipboard + | "paste" | "cut" | "copy" | "format-painter" + // Font + | "font-size" + // Alignment + | "align-top" | "align-middle" | "align-bottom" + | "wrap-text" | "indent-decrease" | "indent-increase" + // Number (the two formats the document model does not carry yet) + | "format-accounting" | "format-custom" + // Styles + | "conditional-formatting" + // Cells + | "insert-row" | "insert-column" | "delete-row" | "delete-column" + | "add-rows" | "add-columns" + | "row-height" | "column-width" + | "hide-rows" | "hide-columns" | "unhide" | "freeze" + // Editing + | "autosum" | "fill-down" | "fill-right" + | "clear-contents" | "clear-formats" | "clear-all" + // The workbook's own acts, which R8 puts on the SAME row rather than on a line of their own + | "refresh" | "import"; + +export interface RibbonAction { + kind: RibbonActionKind; + /** A step name (`small`), a count, or nothing. Never a free sentence. */ + arg?: string | number; +} + export interface RibbonProps { /** * The style of the cell the selection is ANCHORED on, which is what the toggles report as @@ -42,19 +86,66 @@ export interface RibbonProps { style: CellStyle | null; /** No selection, or a workbook that is saving: every control is inert but still readable. */ disabled?: boolean; + /** Whether the sheet currently freezes its leading column, so the Freeze item reads back. */ + frozen?: boolean; + /** ⛔ NO FAKE AFFORDANCE. Import is offered only where the page actually has a door for it. */ + canImport?: boolean; onApply: (patch: CellStylePatch) => void; + onAction: (action: RibbonAction) => void; } -/** The tab order INSIDE the toolbar, in the order the controls are read. */ +// ═══════════════════════════════════════════════════════════════════════════════════════════════ +// THE ROVING ORDER, DERIVED FROM THE GROUPS RATHER THAN RESTATED BESIDE THEM. +// +// ⛔ A HAND MAINTAINED PARALLEL ARRAY IS HOW ROVING FOCUS DIES SILENTLY: one `data-ribbon` typo and +// `focusControl`'s query returns null, with every gate still green. `ControlKey` is derived from +// these arrays, so a control rendered under a name that is not in one of them is a TYPE ERROR. +// ═══════════════════════════════════════════════════════════════════════════════════════════════ + +const STRIP = ["tab-home", "collapse"] as const; +const CLIPBOARD = ["paste", "cut", "copy", "painter"] as const; +const FONT = ["bold", "italic", "underline", "border", "fill", "color", "size"] as const; +const ALIGNMENT = [ + "top", "middle", "bottom", "left", "center", "right", "wrap", "outdent", "indent", +] as const; +const NUMBER = ["format", "currency", "percent", "comma", "decless", "decmore"] as const; +const STYLES = ["conditional"] as const; +const CELLS = ["insert", "delete", "cellformat"] as const; +const EDITING = ["autosum", "filldown", "fillright", "clear"] as const; +const UTILITY = ["import", "refresh"] as const; + const ORDER = [ - "bold", "italic", "underline", - "color", "fill", - "left", "center", "right", - "format", "border", + ...STRIP, ...CLIPBOARD, ...FONT, ...ALIGNMENT, ...NUMBER, ...STYLES, ...CELLS, ...EDITING, + ...UTILITY, ] as const; type ControlKey = (typeof ORDER)[number]; -type Popover = "" | "color" | "fill" | "format" | "border"; +type Popover = + | "" | "color" | "fill" | "format" | "border" | "size" | "insert" | "delete" | "cellformat" + | "clear"; + +/** + * ⭐ COLLAPSE IS REMEMBERED PER PERSON, and the key is namespaced so nothing else in the app can + * collide with it. A throwing read (a private window refuses storage) renders EXPANDED, which is + * the state that shows every control rather than the state that hides them. + */ +const COLLAPSE_KEY = "aios.sheet.ribbon.collapsed"; + +const readCollapsed = (): boolean => { + try { + return window.localStorage.getItem(COLLAPSE_KEY) === "1"; + } catch { + return false; + } +}; + +const writeCollapsed = (next: boolean) => { + try { + window.localStorage.setItem(COLLAPSE_KEY, next ? "1" : "0"); + } catch { + // Storage is refused in a private window. The ribbon still collapses for this session. + } +}; /** * The ink a person may choose, as TOKEN NAMES. @@ -84,6 +175,12 @@ const FILLS: { token: string; label: string }[] = [ { token: "--lp-purple-tint", label: "Purple" }, ]; +/** + * ⛔ THE FIVE THE DOCUMENT MODEL CARRIES, AND ONLY THOSE. `CELL_FORMAT_KINDS` is mirrored in + * `platform/core/sheets.py` and a sixth spelling is REFUSED by name on the way in, so R8's + * Accounting and Custom code are offered as ACTS (`format-accounting`, `format-custom`) rather + * than smuggled in here as a kind the server would reject. + */ const FORMAT_LABEL: Record = { general: "General", number: "Number", @@ -100,6 +197,14 @@ const BORDERS: { id: string; label: string; sides: Record }[] = { id: "left", label: "Left", sides: { left: true } }, ]; +/** R8's four step size scale. Inter only, so a step is a SIZE and never a typeface. */ +const SIZE_STEPS: { id: string; label: string }[] = [ + { id: "small", label: "Small" }, + { id: "normal", label: "Normal" }, + { id: "large", label: "Large" }, + { id: "heading", label: "Heading" }, +]; + function IconAlign({ to }: { to: "left" | "center" | "right" }) { // Four rules; the short ones move, which is what says left, centre or right without a word. const short = to === "left" ? "M2.5 8h6M2.5 12h7" @@ -113,6 +218,39 @@ function IconAlign({ to }: { to: "left" | "center" | "right" }) { ); } +/** The vertical three: a cell box, with the text rule sitting where the value would land. */ +function IconVAlign({ to }: { to: "top" | "middle" | "bottom" }) { + const y = to === "top" ? 5 : to === "middle" ? 8 : 11; + return ( + + ); +} + +function IconWrap() { + return ( + + ); +} + +function IconIndent({ out }: { out: boolean }) { + const arrow = out ? "M6.6 6.4L4.6 8l2 1.6" : "M4.6 6.4L6.6 8l-2 1.6"; + return ( + + ); +} + function IconInk() { return (
+
{body}
+ {name} +
+ ); + + /** A plain word inside a control. A ribbon is not an icon quiz. */ + const word = (text: string) => {text}; + + const item = (label: string, onClick: () => void, on = false, role = "menuitem") => ( + + ); + const swatches = ( which: "color" | "fill", list: { token: string; label: string }[], @@ -268,156 +500,337 @@ export default function Ribbon({ style, disabled = false, onApply }: RibbonProps const format = style?.format; const kind: CellFormatKind = format?.kind ?? "general"; const decimals = format?.decimals ?? (kind === "currency" ? 2 : 0); + /** Stepping decimals on a date or on an unformatted cell means the cell becomes a number. */ + const numeric: CellFormatKind = + kind === "currency" || kind === "percent" ? kind : "number"; + + const stepDecimals = (delta: number) => onApply({ + format: { + ...format, + kind: numeric, + decimals: Math.min(10, Math.max(0, decimals + delta)), + }, + }); return ( -
- {control("bold", "Bold", B, - () => apply({ bold: !style?.bold }), style?.bold === true)} - {control("italic", "Italic", I, - () => apply({ italic: !style?.italic }), style?.italic === true)} - {control("underline", "Underline", U, - () => apply({ underline: !style?.underline }), style?.underline === true)} - -