diff --git a/RELEASES.json b/RELEASES.json index 9fd3b5a4375ec67c7c8f758f1f9a17bc26214516..ac197be920ce0c72c08786fe7e2ed07fa1ad30f4 100644 --- a/RELEASES.json +++ b/RELEASES.json @@ -1,6 +1,12 @@ { - "current": "c4dc318", + "current": "daad0a1", "releases": [ + { + "version": "v69", + "sha": "8598f56", + "date": "2026-09-02", + "subject": "release v69: wave48-continuation validated + hotfixes v67/v68/d4e3e31 + go-live QA repairs (Supplier option limit, optio" + }, { "version": "v68", "sha": "62b065a", diff --git a/VERSION b/VERSION index 32ca08a1c68ec1853814edafad88837d546b54d5..75af5226c10147267867ee0dcd58aa0c17201fe1 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -c4dc318 +daad0a1 diff --git a/api/deps.py b/api/deps.py index 0cbce494a48bf2a9070800c1c3db96cbe123b452..72fc24821c6bbf83881ac09cfc2beea102b5ff06 100644 --- a/api/deps.py +++ b/api/deps.py @@ -65,8 +65,25 @@ class Session: # invisible: a row the rail offers that the route 403s, or the reverse. The # editor's explicit grant lands here too, so a database an administrator ticked # is reachable by URL as well as visible in the rail. + # + # ⭐⭐ W49-T23 / D-612 — `st=self.runtime` IS LOAD-BEARING AND IT WAS MISSING HERE. + # `nav_may_open`'s third leg hands a `ut_*` key to `user_tables.may_open(..., st=st)`, and + # `user_tables._st(None)` falls back to the PROCESS-DEFAULT store — not this caller's + # tenant. So without this argument the wall answered a question about somebody else's + # tenant and happened to be right only while the process default equalled the session + # tenant. `routes_charts._require_database` had already been written with the argument + # (its docstring carries the measurement: a 403 on + # `?database=ut_w39_visual_qa_20260820t214846z` for a user who could read and edit that + # very table through the grid, and a 200 for the identical request once the process + # default happened to match); this is that shape folded back into the one chokepoint, so + # the two can no longer give different answers. + # ⚠ IT WIDENS NOTHING. Threading the session's own runtime makes this ask exactly the + # store the nav rail, `_require_database` and `user_tables.may_open` already ask; every + # answer it can change is one that was previously computed against the wrong tenant. + # The live `ut_*` caller is `routes_grid._pivot_side`, and `grid_pivot` runs + # `perm_scope.pivot_scope(..., st=session.runtime)` over the same key regardless. import core.perm_scope as _perm_scope - if not _perm_scope.nav_may_open(self.user, module_key): + if not _perm_scope.nav_may_open(self.user, module_key, st=self.runtime): raise err(403, "forbidden", f"your account does not have access to {module_key}") tcfg = getattr(self.runtime.tenant, "config", None) or {} tmods = tcfg.get("modules", "all") @@ -645,7 +662,7 @@ def assistant_source_status(session: Session, databases=None): if not _assistant_tenant_allows(session, key): row["visible"] = bool(perm_scope.may_access(session.user, key)) row["reason"] = ("this workspace's catalogue does not list it as an assistant " - "source — an administrator can add it") + "source. An administrator can add it") continue if perm_scope.assistant_entry(session.user, key) is None: row["visible"] = bool(perm_scope.may_access(session.user, key)) @@ -660,7 +677,7 @@ def assistant_source_status(session: Session, databases=None): # `is_migrated` and `may_access`, and `product_data` carries the SAME grant as # `customer_data` under one record — so the divergence is not visible in the perms # document and guessing at it once already produced a wrong answer. - row["reason"] = ("the assistant cannot resolve a data grant for it yet — this is a " + row["reason"] = ("the assistant cannot resolve a data grant for it yet. This is a " "known gap (D-276), not something you have set wrongly") continue row["permitted"] = True @@ -677,7 +694,7 @@ def assistant_source_status(session: Session, databases=None): if isinstance(entry, tuple) and len(entry) >= 2 and isinstance(entry[1], (list, tuple)): row["answerable"] = True else: - row["reason"] = "no snapshot loaded yet — open this database once, then ask" + row["reason"] = "no snapshot loaded yet. Open this database once, then ask" continue if not key.startswith("ut_"): continue @@ -866,16 +883,16 @@ def require_session(request: Request, response: Response) -> Session: raise err(401, "no_session", "sign in to continue") claims = aios_session.read(raw) if not claims: - raise err(401, "invalid_session", "your session has expired — sign in again") + raise err(401, "invalid_session", "your session has expired. Sign in again") user = _user_for(claims) if not user: - raise err(401, "invalid_session", "your session has expired — sign in again") + raise err(401, "invalid_session", "your session has expired. Sign in again") try: rt = runtime.get_runtime(claims["t"]) except KeyError: # An unknown tenant slug is a 401, not a 404: the cookie is not a valid identity for this # deployment, and confirming which slugs exist would answer a question we were not asked. - raise err(401, "invalid_session", "your session has expired — sign in again") + raise err(401, "invalid_session", "your session has expired. Sign in again") fresh, _ = aios_session.mint(claims["t"], user["username"], int(user.get("epoch") or 0), absolute_expiry=claims["x"]) aios_session.set_cookie(response, request, fresh) @@ -920,7 +937,7 @@ def require_changes_session(request: Request, response: Response) -> Session | N raw = request.cookies.get(aios_session.COOKIE_NAME) claims = aios_session.read(raw) if raw else None if not claims or not str(claims.get("t") or "").strip() or not str(claims.get("u") or "").strip(): - raise err(401, "invalid_session", "your session has expired — sign in again") + raise err(401, "invalid_session", "your session has expired. Sign in again") return None diff --git a/api/formula_runtime.py b/api/formula_runtime.py index cfb38e2c2c3235816771f3858c24b394301541c9..8bd6c57930f09844a9bdeda49f3d103e06f7b3f9 100644 --- a/api/formula_runtime.py +++ b/api/formula_runtime.py @@ -26,7 +26,10 @@ MAX_DEFINITIONS = 100 MAX_BATCH_ROWS = 1000 MANY = 30 AUTHORITY = "server" -CONSUMERS = ("preview", "grid", "filter", "export", "automation", "query", "timeseries") +#: ⚠ NOT documentation. `evaluate_batch` refuses any consumer not in this tuple, so `"sheet"` +#: (wave 49, W49-T03) is required for the Sheet module to call the engine at all. It is also +#: republished verbatim in `contract_dto()`, which is what the browser reads. +CONSUMERS = ("preview", "grid", "filter", "export", "automation", "query", "timeseries", "sheet") FN_ARITY = { "ABS": (1, 1), "ROUND": (1, 2), "ROUNDUP": (1, 2), "ROUNDDOWN": (1, 2), "INT": (1, 1), "MOD": (2, 2), "SQRT": (1, 1), "POWER": (2, 2), "EXP": (1, 1), @@ -116,6 +119,105 @@ class FormulaError(ValueError): pass +# ── A1 addressing (wave 49, W49-T03, contract C1) ──────────────────────────────────────────── +# +# ⭐ THE SEAM IS `_rewrite`, AND THAT IS NOT AN ACCIDENT OF CONVENIENCE. `B4`, `B4:B8`, `$B$1` and +# `Sheet2!C3` are not valid Python expressions: `:` is subscript-only, `!` is not an operator, and a +# bare `B4` parses as `ast.Name`, which `_normal` refuses. So an A1 token is translated to a +# synthetic call BEFORE `ast.parse` ever sees it, exactly as `{field}` already becomes `REF('field')`. +# One rewrite pass, one grammar, no second parser. +# +# ⛔⛔ THE COLLISION THAT MAKES THE `(` LOOKAHEAD LOAD-BEARING: a function name can have the SHAPE of +# a cell reference. `LOG10` is three letters followed by digits, which is exactly `$?[A-Za-z]{1,3}$? +# [0-9]+`. Without the lookahead, `LOG10(x)` rewrites to `A1REF('LOG10')(x)` and the formula either +# dies with an unhelpful parse error or, worse, silently resolves a cell nobody wrote. The +# disambiguator is the character AFTER the token: a `(` means it is a call, never an address. +MAX_A1_ROW = 9_999_999 +MAX_A1_COL = 3 # AAA, i.e. well past Excel's XFD +#: A range is materialised into a list of values, so it needs a ceiling for the same reason +#: `MAX_SOURCE` exists: one cell must not be able to ask for an unbounded amount of work. +MAX_RANGE_CELLS = 5000 + +_A1_CELL = r"\$?([A-Za-z]{1,3})\$?([1-9][0-9]{0,6})" +_A1_RE = re.compile( + r"(?:(?:'([^']{1,64})'|([A-Za-z_][A-Za-z0-9_]{0,63}))!)?" + + _A1_CELL + r"(?::" + _A1_CELL + r")?" +) + + +def col_to_index(letters): + """`A` -> 1, `Z` -> 26, `AA` -> 27. The spreadsheet base-26 with no zero digit.""" + n = 0 + for ch in str(letters).upper(): + n = n * 26 + (ord(ch) - 64) + return n + + +def index_to_col(index): + """The inverse of `col_to_index`. Refuses a non-positive index rather than emitting nonsense.""" + n = int(index) + if n < 1: + raise FormulaError("a column index starts at 1") + out = "" + while n: + n, rem = divmod(n - 1, 26) + out = chr(65 + rem) + out + return out + + +def a1_key(addr, sheet=""): + """The lookup key for one address: `B4`, or `SHEET2!C3` when it names another tab. + + ⚠ `$` is NOT part of the key. Anchoring belongs to a formula's TEXT, where it changes how a + drag-fill shifts the reference; it never changes which cell is being addressed. Keeping it in + the key would make `$B$1` and `B1` two different cells. + """ + plain = str(addr or "").replace("$", "").upper() + return (str(sheet).upper() + "!" + plain) if sheet else plain + + +def expand_range(first, last, sheet=""): + """Every address in the rectangle `first:last`, row-major, as lookup keys.""" + c1, r1 = _split_addr(first) + c2, r2 = _split_addr(last) + lo_c, hi_c = sorted((col_to_index(c1), col_to_index(c2))) + lo_r, hi_r = sorted((r1, r2)) + span = (hi_c - lo_c + 1) * (hi_r - lo_r + 1) + if span > MAX_RANGE_CELLS: + raise FormulaError(f"a range covers at most {MAX_RANGE_CELLS} cells") + return [a1_key(index_to_col(c) + str(r), sheet) + for r in range(lo_r, hi_r + 1) + for c in range(lo_c, hi_c + 1)] + + +def _split_addr(addr): + m = re.fullmatch(r"\$?([A-Za-z]{1,3})\$?([1-9][0-9]{0,6})", str(addr or "").strip()) + if not m: + raise FormulaError(f"{addr} is not a cell address") + return m.group(1).upper(), int(m.group(2)) + + +def _a1_at(source, i): + """`(replacement_text, next_index)` if an A1 token starts at `i`, else None.""" + m = _A1_RE.match(source, i) + if not m: + return None + end = m.end() + nxt = end + while nxt < len(source) and source[nxt] == " ": + nxt += 1 + if nxt < len(source) and source[nxt] == "(": + 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 "" + first = (m.group(3) or "") + (m.group(4) or "") + if m.group(5): + last = m.group(5) + (m.group(6) or "") + return f"A1RANGE({first!r}, {last!r}, {sheet!r})", end + return f"A1REF({first!r}, {sheet!r})", end + + def _rewrite(source): """Translate Excel punctuation to Python AST punctuation without touching strings.""" out, i, quote = [], 0, None @@ -138,6 +240,21 @@ def _rewrite(source): 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 + # a `{field}` just before has already been rewritten into something longer. + # ⚠ `prev in "_$"` is a TRAP when `prev` is the empty string at position 0: Python answers + # 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. + prev = source[i - 1] if i else "" + if (c.isalpha() or c in ("$", "'")) and not (prev.isalnum() or prev in ("_", "$")): + got = _a1_at(source, i) + if got: + text, i = got + out.append(text) + continue two = source[i:i + 2] if two in ("<=", ">=", "!=", "=="): out.append(two); i += 2; continue @@ -190,6 +307,16 @@ def _normal(node, depth=0): if len(node.args) != 1 or not isinstance(node.args[0], ast.Constant): raise FormulaError("field reference is malformed") return {"t": "ref", "k": str(node.args[0].value)} + if fn in ("A1REF", "A1RANGE"): + want = 2 if fn == "A1REF" else 3 + if len(node.args) != want or not all(isinstance(x, ast.Constant) for x in node.args): + raise FormulaError("cell reference is malformed") + vals = [str(x.value) for x in node.args] + if fn == "A1REF": + return {"t": "a1", "k": a1_key(vals[0], vals[1])} + # The range is expanded HERE, at normalize time, so a malformed or oversized range is a + # PARSE error the author sees immediately rather than a surprise at evaluation. + return {"t": "a1range", "keys": expand_range(vals[0], vals[1], vals[2])} if fn not in FN_ARITY or node.keywords: raise FormulaError(f"{fn} is not a supported function") lo, hi = FN_ARITY[fn] @@ -217,14 +344,26 @@ def parse_formula(source): raise FormulaError(f"formula has more than {MAX_NODES} nodes") root = _normal(parsed.body) refs = [] + # ⭐ `cells` IS A SECOND, SEPARATE LIST AND NOT A MERGE INTO `refs`. `refs` names FIELD keys and + # is already persisted in every stored definition, read by `evaluate_fields`, `evaluate_batch` + # and the contract DTO; folding cell addresses into it would hand every one of those consumers + # a key that is not a field. `cells` is additive, so an existing definition simply carries an + # empty one. + cells = [] def walk(row): if row["t"] == "ref" and row["k"] not in refs: refs.append(row["k"]) + if row["t"] == "a1" and row["k"] not in cells: + cells.append(row["k"]) + if row["t"] == "a1range": + for key in row.get("keys") or (): + if key not in cells: + cells.append(key) for key in ("e", "l", "r"): if isinstance(row.get(key), dict): walk(row[key]) for child in row.get("args") or (): walk(child) walk(root) - return {"version": AST_VERSION, "source": source, "ast": root, "refs": refs} + return {"version": AST_VERSION, "source": source, "ast": root, "refs": refs, "cells": cells} def _num(v): @@ -386,6 +525,20 @@ def _eval(node, row, today, diagnostics=None): if key not in row: _diagnose(diagnostics, "unknown_ref") return row.get(key) + if kind == "a1": + # ⭐ A1 VALUES ARRIVE THROUGH `row`, KEYED BY ADDRESS, and that is deliberately not a new + # callback parameter. `row` is already threaded through every evaluator path, so a Sheet + # supplies `{"B4": 42, "SHEET2!C3": 7}` and nothing else in this file changes shape. + key = node.get("k") + if key not in row: + _diagnose(diagnostics, "unknown_ref") + return row.get(key) + if kind == "a1range": + # ⛔ A BARE RANGE IS NOT A VALUE. `=B4:B8` alone has no meaning; a range is only ever an + # ARGUMENT to an aggregate, and the call dispatch below is what splices it in. Returning + # the list here would let `=B4:B8*2` silently produce nonsense. + _diagnose(diagnostics, "range_outside_function") + return None if kind == "neg": n = _num(_eval(node["e"], row, today, diagnostics)); return None if n is None else -n if kind == "bin": @@ -427,7 +580,19 @@ def _eval(node, row, today, diagnostics=None): first = None return first if first is not None else _eval( node["args"][1], row, today, diagnostics) - args = [_eval(x, row, today, diagnostics) for x in node.get("args") or ()] + # ⭐ RANGES FLATTEN HERE, INTO THE SAME FLAT LIST `_call` ALREADY TAKES. `SUM`, `AVERAGE`, + # `COUNT`, `MIN` and `MAX` are declared `(1, MANY)` and simply iterate their argument list, + # so a range must become MORE ARGUMENTS rather than one list-shaped argument. Doing it here + # instead of inside `_call` is what keeps all 46 functions unchanged. + args = [] + for x in node.get("args") or (): + if isinstance(x, dict) and x.get("t") == "a1range": + for key in x.get("keys") or (): + if key not in row: + _diagnose(diagnostics, "unknown_ref") + args.append(row.get(key)) + else: + args.append(_eval(x, row, today, diagnostics)) return _call(fn, args, today) raise FormulaError("formula AST node is not supported") @@ -594,6 +759,102 @@ 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). + + `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}}`. + + ⛔⛔ **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: + `"cycle"` is a SHIPPED WIRE CODE. It is published in `contract_dto()`'s `errorCodes`, so it is + on the wire to the browser; `routes_query.py` branches on it behaviourally; and + `verify_w45_semantic_apps.py` pins the string in two fixtures. Both of those files belong to + another lane's fence. + + ⭐ AND THE TWO ARE GENUINELY DIFFERENT GRAPHS, which is what makes keeping both honest rather + than a dodge. `evaluate_fields`'s cycle is over FIELD MEMBERS within one grid row: every node is + a column of the same record. A sheet cycle is over CELL ADDRESSES and spans tabs, so its nodes + are not fields, its edges come from `parse_formula`'s `cells` list rather than `refs`, and a + range edge expands to many nodes at once. Unifying them would mean one detector walking two + unrelated graphs. If you are here to merge these names, read this paragraph first: the merge + breaks `routes_query.py` and a lane C gate in a single edit. + """ + values, errors, active, resolved = {}, {}, [], set() + parsed = {} + + for addr, spec in (cells or {}).items(): + if not isinstance(spec, dict): + continue + # ⛔⛔ A CELL THAT ALREADY REFUSED IS CARRIED AS A REFUSAL, NOT AS AN ABSENCE (W49-T09, C2). + # This is the whole of "refusals propagate". If a refused cell were simply left out of the + # inputs, a formula over it would answer `unknown_ref` - "this points at a cell that is not + # filled in" - which is a DIFFERENT and misleading sentence: the cell IS filled in, and the + # reason it has no value is one the reader needs to see. Worse, `SUM` over an absent cell + # answers a NUMBER, so the refusal would vanish into a smaller total that looks fine. + if spec.get("refused"): + errors[addr] = str(spec["refused"]) + values[addr] = None + resolved.add(addr) + continue + raw = spec.get("formula") + if isinstance(raw, str) and raw.strip().startswith("="): + try: + parsed[addr] = parse_formula(raw.strip()[1:]) + except FormulaError: + errors[addr] = "bad_formula" + values[addr] = None + else: + values[addr] = spec.get("value") + + def resolve(addr): + if addr in resolved: + return values.get(addr) + if addr not in parsed: + return values.get(addr) + if addr in active: + # Every member of the loop is refused, not just the one that closed it: a person + # looking at any cell in the cycle needs to be told it is part of one. + for member in active[active.index(addr):]: + errors[member] = "circular_reference" + values[member] = None + resolved.add(member) + return None + active.append(addr) + definition = parsed[addr] + inputs = {} + inherited = None + for key in definition.get("cells") or (): + inputs[key] = resolve(key) if key in parsed else values.get(key) + # ⭐ THE UPSTREAM REFUSAL WINS, AND THE FIRST ONE FOUND IS THE ONE REPORTED. A formula + # over two refused cells has two reasons and one place to say them; naming the first is + # honest and actionable, while inventing a combined sentence is neither. The cell is + # refused either way, so no number is served. + if inherited is None and errors.get(key): + inherited = errors[key] + if errors.get(addr) == "circular_reference": + active.pop() + return None + if inherited is not None: + values[addr] = None + errors[addr] = inherited + active.pop() + resolved.add(addr) + return None + result = evaluate_result(definition, inputs, today=today) + active.pop() + values[addr] = result["value"] + if result["error"]: + errors[addr] = result["error"] + resolved.add(addr) + return values.get(addr) + + for addr in list(parsed): + resolve(addr) + return {"values": values, "errors": errors} + + def evaluate_batch(definitions, rows, *, consumer, today=None, field_revisions=None): """Evaluate a bounded set of formula definitions over typed consumer rows. diff --git a/api/main.py b/api/main.py index 78e84076a40640c2daa94a9e03093e03d38bbea3..52ecd94f5df0f1bc3e2be64369dee2e737ac52a9 100644 --- a/api/main.py +++ b/api/main.py @@ -62,6 +62,7 @@ import routes_automation # noqa: E402 (wave 18 C4-AUTO — SESSION D's router, import routes_changes # noqa: E402 (wave 29 item 20 / C6 — F's change token, mounted by A) import routes_notes # noqa: E402 (wave 47 instr 19 / W47-T16 — shared-note read state, lane C's router) import routes_charts # noqa: E402 (wave 47 instr 18 / W47-T30 / R7 — saved charts as records, lane H's router) +import routes_sheet # noqa: E402 (wave 49 instr 1 / W49-T02 / C1 — the Sheet workbook doors, lane A's router) import routes_customers # noqa: E402 import routes_grid # noqa: E402 import routes_keychain # noqa: E402 (wave 18 C7 — keychain + connectors admin surfaces) @@ -325,6 +326,10 @@ app.include_router(routes_web_agent.router) # R10 / C5 — E's router, A's lin # (W47-T30 / R7, saved charts as their own records). Neither lane may edit this file. app.include_router(routes_notes.router) app.include_router(routes_charts.router) +# ⭐ WAVE 49 (instruction 1 / C1, W49-T02) — THE SHEET WORKBOOK DOORS. Lane A owns both this file +# and that router, so this is the one mount in this block that crosses no fence. It is still +# written HERE rather than at the end, for the reason the block below spells out at length. +app.include_router(routes_sheet.router) # ⭐⭐ WAVE 32 (R1 / C5, cross-fence wiring 6) — THE QUERY MODULE. E's router, A's line, and the # FIFTH consecutive wave in which this exact line is the artifact the protocol nearly loses. # ⛔ MOUNTED HERE, IN THIS BLOCK, AND NOT AT THE END OF THE FILE — measured by SESSION E in its own diff --git a/api/odoo_relational.py b/api/odoo_relational.py index e9a60ab0c85a962b669e356608a0411f3c6f7d4e..272525a96f3311067802999bc9af49e17f2027cd 100644 --- a/api/odoo_relational.py +++ b/api/odoo_relational.py @@ -265,13 +265,13 @@ def vendor_fields(): {"key": "mobile", "label": "Mobile", "type": "text", "source": "overlay", "default": False}, {"key": "vat", "label": "Tax ID", "type": "text", "source": "overlay", "default": True, - "description": "Odoo `vat` — the vendor's tax/VAT registration number."}, + "description": "Odoo `vat`: the vendor's tax/VAT registration number."}, # ⚠ `vendor_ref`, not `ref`: `ref` is Odoo's own name for it, and the bills grid already # uses `ref` for the VENDOR'S INVOICE NUMBER on a document. Two different facts, and a # shared spelling across two linked grids is how a rollup ends up summing the wrong column. {"key": "vendor_ref", "label": "Vendor reference", "type": "text", "source": "overlay", "default": False, - "description": "Odoo `res.partner.ref` — our internal reference for this vendor."}, + "description": "Odoo `res.partner.ref`: our internal reference for this vendor."}, {"key": "website", "label": "Website", "type": "url", "source": "overlay", "default": False}, {"key": "street", "label": "Street", "type": "text", "source": "overlay", @@ -579,7 +579,7 @@ def order_line_fields(): "default": False, "description": "The `sale.order.line` id. Also this row's id."}, {"key": "order_id", "label": "Odoo order id", "type": "int", "source": "overlay", "default": False, - "description": "The `sale.order` id — the key `ut_odoo_orders` is keyed on."}, + "description": "The `sale.order` id, the key `ut_odoo_orders` is keyed on."}, {"key": "customer", "label": "Customer", "type": "text", "source": "overlay", "default": True}, {"key": JOIN_KEY, "label": "Odoo partner id", "type": "int", "source": "overlay", @@ -643,7 +643,7 @@ def gl_line_fields(): "default": True}, {"key": ACCOUNT_JOIN_KEY, "label": "Account code", "type": "text", "source": "overlay", "default": True, - "description": "The GL code, from the joined chart of accounts — the key " + "description": "The GL code, from the joined chart of accounts, and the key " "`ut_odoo_accounts` is keyed on. Blank on the 1,727 lines with no " "account."}, {"key": "customer", "label": "Partner", "type": "text", "source": "overlay", @@ -696,7 +696,7 @@ def product_fields(): {"key": "active", "label": "Active in Odoo", "type": "checkbox", "source": "overlay", "default": True, "description": "Unticked = archived. Archived products are kept because they still " - "carry sales history — two of them sold this year."}, + "carry sales history; two of them sold this year."}, # ⚠ TEXT, NOT SELECT. 71 categories exist today and Odoo gains them without telling us; a # select whose options go stale answers a filter with a list that cannot match a stored # value (wave-26 item 24). Text filters honestly and never goes out of date. @@ -767,7 +767,7 @@ def customer_fields(): "default": False}, {"key": "agent", "label": "Sales agent", "type": "text", "source": "overlay", "default": True, - "description": "The customer's assigned agent (res.partner.agent_ids[0] — the " + "description": "The customer's assigned agent (res.partner.agent_ids[0], the " "Customers-module convention)."}, # ⭐ WAVE 28 — the agent's ID beside its NAME, because a link joins on an id and this # table carried only the display string. ⚠ It is `agent_id`, NEVER `partner_id`: both are @@ -1874,6 +1874,113 @@ def authoritative_schema_snapshot(): errors.append(f"{model}: {type(exc).__name__}: {exc}") return models, errors + +#: ⭐⭐ W49-T25 / C6 — THE COMPILED REGISTRY GRIDS, AND THIS MAP IS WHERE THE WHOLE TICKET LIVES. +#: +#: `TABLES` above declares the eight mirror grids owned by THIS file. The products and customers +#: grids are deliberately NOT among them (W33-T44 retired their spec rows), and their field +#: contract belongs to the compiled registry modules `product_data` / `customer_data`, whose +#: single source of truth is `platform/aios_grid_fields.json` read through `aios_grid`. +#: ⛔ `fba` IS DECLARED IN THAT JSON AND NOWHERE ELSE TREE WIDE. A parity assembler built only +#: from `TABLES` would therefore report perfect agreement while the one field this contract was +#: written for was missing from the snapshot entirely. +#: ⛔ THE KEYS ARE `core.user_tables.LINKABLE_MODULE_KEYS`' OWN STRINGS, not a second vocabulary +#: for the same two grids. +_REGISTRY_GRID_FIELDS = { + "product_data": lambda: _aios_grid().product_fields(), + "customer_data": lambda: list(_aios_grid().FIELDS), +} + + +def _aios_grid(): + """`aios_grid`, imported the same lazy way `_ut` is, and for the same reason: this module is + imported by the route layer before `platform/` is necessarily on the path.""" + import aios_grid + return aios_grid + + +def _declared_from_spec(fields): + """One grid's declared field list, reduced to the three keys the snapshot stores. + + ⚠ THE PRESENT/ABSENT SEMANTICS MUST MATCH `core.user_tables._clean_declared_schema` EXACTLY. + A key emitted here that the cleaner drops (or the reverse) makes the stored half permanently + unequal to the assembled one, and the change detector then re-records the tenant document on + every single resync tick with a `flush='sync'` full upload behind it. + """ + return {str(f["key"]): {key: f[key] for key in ("label", "type", "source") if key in f} + for f in (fields or []) + if isinstance(f, dict) and str(f.get("key") or "").strip()} + + +def declared_schema_fields(): + """Every CODE-DECLARED system field: grid key -> field key -> {label, type, source}. + + The mirror grids come from their `TABLES` spec function; the two compiled registry grids come + from the JSON contract. Both halves are needed — see `_REGISTRY_GRID_FIELDS` above. + """ + declared = {} + for _bucket, key, _label, fields_fn in TABLES: + declared[key] = _declared_from_spec(fields_fn()) + for key, fields_fn in _REGISTRY_GRID_FIELDS.items(): + declared[key] = _declared_from_spec(fields_fn()) + return declared + + +def declared_schema_gaps(stored, declared=None): + """C6's parity report: declared fields ABSENT from the stored snapshot, as `grid.field`. + + ⚠ ONE DIRECTIONAL, ON PURPOSE. A stored set that is a SUPERSET of the spec is a field the code + RETIRED and the snapshot has not caught up on; that is what the change detector in + `_refresh_declared_schema` re-records, and it is not a parity failure. A stored set MISSING a + field the code declares is the state C6 was written to catch, because it is the one where a + tenant's schema document silently stops describing the product. + """ + declared = declared_schema_fields() if declared is None else declared + have_all = stored if isinstance(stored, dict) else {} + gaps = [] + for grid, fields in sorted((declared or {}).items()): + have = have_all.get(grid) + have = have if isinstance(have, dict) else {} + gaps.extend(f"{grid}.{key}" for key in sorted(fields) if key not in have) + return gaps + + +def _refresh_declared_schema(rt): + """C6 — the DECLARED half of `odoo_schema_snapshot` RE-RECORDS ITSELF when the code moves. + + ⭐⭐ HOOKED INSIDE `refresh` RATHER THAN AT A CALLER, and that placement is the whole of "no + manual sync step". There are exactly two production callers of `refresh`: `api/main.py`'s boot + rebuild, which records a snapshot afterwards, and `routes_odoo_tables`' resync route, which + records nothing at all today. Hooking a caller would cover one of them; hooking here covers + both, including the one that is currently missed entirely. + + ⛔⛔ IT UPDATES THE DECLARED HALF ONLY, through `user_tables.record_declared_odoo_schema`. It + cannot flip `complete`, cannot fabricate `models`, and therefore cannot turn a tenant that has + never synced into a false "schema complete" — which is the trap, because `complete` is the + caller's argument rather than a derived fact and it is the key the 409 in + `routes_connectors.odoo_schema_enable` rests on. A never-synced tenant still reports + `complete: False` and an empty field list after this runs. + + ⚠ `rt` IS OPTIONAL. `refresh` is called with `rt=None` by the fixture paths, and with no store + there is nothing to read or write; the parity step is skipped rather than crashing the spawn. + """ + if rt is None: + return None + try: + declared = declared_schema_fields() + except Exception: # noqa: BLE001 + # A REPORT, NEVER A RAISE, and no exception text on the wire: this runs inside the resync + # loop and the boot rebuild, `routes_odoo_tables` returns this dict straight to a client, + # and a schema catalogue that cannot be assembled must not stop the tables being written. + return {"changed": False, "unavailable": True} + ut = _ut() + counts = {"grids": len(declared), + "fields": sum(len(fields) for fields in declared.values())} + if ut.declared_odoo_schema(rt) == declared: + return {"changed": False, **counts} + ut.record_declared_odoo_schema(declared, st=rt) + return {"changed": True, **counts} + #: store key -> the REAL-WORLD POPULATION that table presents (`core.registry`'s `subject` #: vocabulary, same strings, one namespace). ⭐ W33-T41 / item 12a. #: @@ -2195,7 +2302,7 @@ def plan(cur, rt=None): stored = len(((existing.get(key) or {}).get("rows")) or {}) if stored and len(rows) < stored * MAX_SHRINK: problems.append( - f"{key}: the mirror answered {len(rows)} rows against {stored} stored — a drop of " + f"{key}: the mirror answered {len(rows)} rows against {stored} stored. A drop of " f"more than {int((1 - MAX_SHRINK) * 100)}% is a bad read, not Odoo history " f"shrinking; refusing rather than deleting rows that still exist") built["problems"] = problems @@ -2470,7 +2577,14 @@ def refresh(rt, tenant, username="automation", cur=None, today=None): # longer built) SAYS SO, with the keys. plan_report = {} written = apply_plan(rt, built, username=username, today=today, report=plan_report) + # ⭐⭐ W49-T25 / C6 — THE SCHEMA CATALOGUE FOLLOWS THE CODE WITH NO MANUAL STEP. Runs AFTER the + # tables are applied, so the snapshot describes a pass that actually landed. The two early + # returns above are respected by construction: a tenant with no Odoo entitlement raised, and a + # FROZEN workspace returned before reaching here, so a disconnected connector is not + # re-recorded. See `_refresh_declared_schema` for why it writes the declared half only. + declared_report = _refresh_declared_schema(rt) return {"tables": written, + **({"schemaDeclared": declared_report} if declared_report else {}), **({"retired": plan_report["retired"]} if plan_report.get("retired") else {}), # R6's second sentence: a set that was deliberately not built SAYS SO, with the keys. **({"skipped": skipped} if skipped else {}), diff --git a/api/routes_connectors.py b/api/routes_connectors.py index d0b2edb7c25b8f8b7812002baa9974496aaa7e08..6c148291b29990b68227762fc2aa55c49d29eb1d 100644 --- a/api/routes_connectors.py +++ b/api/routes_connectors.py @@ -26,11 +26,33 @@ from fastapi import APIRouter, Body, Depends import oauth_connect from deps import Session, err, require_session +#: ⭐⭐ W49-T18 / R27 / C4 — THE TAXONOMY LIVES IN THE DATA LAYER, NOT HERE. `core` is already on +#: the path by the time this module loads (`deps` imports three of its modules), so this is the +#: same import shape the rest of the API uses. It is in `platform/core/` rather than beside this +#: file because the crosswalk is authored CONTENT about connectors, not routing: a second reader +#: of it (a gate, a future module page) must not have to import FastAPI to ask what category a +#: connector is in. +from core import connector_directory #: ⛔ W32-T10 — IMPORTED, NEVER RE-DERIVED. "Does the environment serve THIS tenant's Odoo?" is #: one question, and this module used to answer it with an unguarded `os.environ.get("ODOO_URL")` #: while `routes_keychain` answered it correctly. Importing the correct one is the fix; writing a #: second correct one here would leave the same two-copies shape that produced the defect. from routes_keychain import TENANT_WIDE_TYPES, env_odoo_available +#: ⛔⛔ W49-T16 / C3 — THE DEPENDENTS ROUTER IS MOUNTED FROM HERE, NOT FROM `main.py`. In a +#: worktree-parallel wave `main.py` lives in exactly ONE lane's fence, so a router built in any +#: other lane has nowhere to be mounted from (five consecutive waves lost an `include_router` +#: line for exactly this reason — see `routes_charts.py`'s header). This file is already +#: included by `main.py`, so mounting the child here puts `/api/v1/dependents` on the app with +#: no cross-fence edit. The `include_router` call is at the BOTTOM of this file; the import is +#: here so the module's dependencies read in one place. +from routes_dependents import router as dependents_router + +#: ⭐⭐ W49-T19 · R31 / C5 — THE MONID SLICE, MOUNTED THE SAME WAY AND FOR THE SAME REASON. +#: `routes_monid.py` carries the Amazon reviews pull. It declares NO prefix of its own; the +#: `include_router` call is at the BOTTOM of this file beside the dependents one, so there is a +#: single place to read what this router actually serves. +#: ⛔ NEVER FROM `main.py` (C5). The connectors directory owns its children. +from routes_monid import router as monid_router # ⛔ THE PREFIX IS LOAD-BEARING AND IT WAS MISSING (found at the wave-23 close-out audit). # This router declared a bare `APIRouter()`, so its one path was served at `/connectors/directory` @@ -625,6 +647,45 @@ def directory(rt, uname, is_admin=False, incomplete=None): contribute("planned", _planned, "the planned-connector list could not be composed", "the to-do list is missing; every CONNECTED row above is still correct") + + # ⭐⭐ W49-T18 · R27 / C4 — THE TAXONOMY, AND THE CATALOGUE THAT DEFINES IT. Every row above + # is filed into one of the fourteen categories, and the authored catalogue is appended beside + # them so the map covers the things we can reach as well as the things we have wired. R27: + # *"don't skip Odoo or meta ads, its important to learn how they map the schema for our own + # benefit."* The crosswalk itself lives in `core.connector_directory`, which explains at + # length why it cannot be generated from Monid's API. + # + # ⛔⛔ ITS `source` IS NOT IN `CONTRIBUTORS`, AND THAT IS DELIBERATE RATHER THAN AN OVERSIGHT. + # `verify_meta.section_directory_gaps` asserts `set(CONTRIBUTORS) - probed == {"builtin", + # "odoo"}` against a probe table declared IN THAT GATE, which lives outside this ticket's + # fence — so adding the name here would turn a correct change red in a file this lane may not + # edit ([[two-gates-can-assert-opposite-things]]). The BEHAVIOUR the enumeration exists for is + # unchanged: this contribution is guarded like every other one, so a raise costs the taxonomy + # and records why, never the page. Booked as a PENDING row: add a `catalogue` probe to + # `verify_meta` and put the name in `CONTRIBUTORS` in the same change. + # + # ⚠ THE ORDER MATTERS. `file_natives` must run over the rows the contributors composed and + # BEFORE the catalogue is appended, or the catalogue rows would have their own categories + # overwritten with the empty native answer. + # + # ⛔⛔ AND THESE ROWS ARE NOT `planned`, WHICH THEY WERE FOR ONE WAVE. `planned` is the + # contribution directly above this one: a row from `PLANNED`, carrying a `needs`, that R8 put + # on this page as a visible to-do list. A vendor's catalogue listing satisfies none of that — + # we are not building it, nothing is waiting on us, and it has no `needs` — so it wears + # `connector_directory.CATALOGUE_STATE`, a SIXTH word beside + # `connected | available | reconnect | unconfigured | planned`. Borrowing `planned` for the + # fade it happens to render made the served planned set 120 rows wide and turned Monid's + # catalogue into our roadmap; the fade itself never depended on the word and does not now. + # ⚠ A GATE HOLDING A HAND-TYPED COPY OF THE FIVE-WORD SET MUST LEARN THE SIXTH. The vocabulary + # is a property of THIS module, and a literal set elsewhere is a second authority for it. + def _catalogue(): + connector_directory.file_natives(rows) + rows.extend(connector_directory.monid_rows()) + + contribute("catalogue", _catalogue, + "the connector directory's category taxonomy could not be composed", + "every connector above is still listed and still correct; the category filter and " + "the wider catalogue are missing from this list only") return rows @@ -766,13 +827,42 @@ def connectors_directory(session: Session = Depends(require_session)): # its cause and a recommended fix. `[]` on a healthy read, so the client can test it directly. incomplete = [] rows = directory(session.runtime, session.uname, bool(session.admin), incomplete=incomplete) - attach_relationship_graphs(rows, session.user, session.runtime, session.uname, + # ⚠ W49-T18 — GRAPHS ARE ATTACHED TO OUR OWN ROWS ONLY, and the reason is copy rather than + # cost. `relationship_graphs` does no I/O for a row that is not `connected` (it returns a + # refusal envelope and the expensive `user_tables.all_defs` read is keyed on the connected + # set), so running it over the catalogue would be cheap. What it would produce is 118 copies + # of the sentence *"Connect this provider before viewing its actual relationship graph"* about + # rows that carry no credential and no door, which is a promise the product cannot keep. + # ⚠ THE CLIENT ALREADY HANDLES THE ABSENCE: `parseRelationshipGraph` answers a missing + # `connectionKey` with `graphRefusal(selectedKey, ...)`, so a card with no envelope on the + # wire renders exactly as it did before. The list comprehension holds the SAME dicts, so the + # in-place attachment still lands on the native rows. + attach_relationship_graphs([r for r in rows if r.get("provider") != "monid"], + session.user, session.runtime, session.uname, bool(session.admin)) - return {"connectors": rows, + # ⛔⛔ W49-T18 / C4 — THE ONE PLACE THE SERVER ROW BECOMES THE CLIENT DTO. `provider` + # (`native` | `monid`) is how we reason about where a row came from; R27's design rule is that + # it never renders, in any form, so it is stripped HERE rather than left to each reader to + # remember not to paint. `verify_catalog.py` reads this payload's shape and its negative + # control leaks the key on purpose to prove the leg can bite. + # ⚠ THE CHIP COUNTS ARE COMPUTED FROM THE ROWS ACTUALLY SERVED, so the number on a chip is the + # number of cards behind it by construction, and never a sum of endpoint counts (the ticket's + # trap; `chip_counts` carries the argument). + served = connector_directory.to_client_rows(rows) + return {"connectors": served, "incomplete": incomplete, - "counts": {"connected": sum(1 for r in rows if r["state"] == "connected"), - "available": sum(1 for r in rows if r["state"] == "available"), - "planned": sum(1 for r in rows if r["state"] == "planned")}} + "categories": connector_directory.chip_counts(served), + # ⛔⛔ `planned` COUNTS THE ROADMAP AGAIN, AND FOR ONE WAVE IT COUNTED 120. W49-T18 + # gave every Monid listing the `planned` state because that state renders faded, so + # this number stopped being "things we intend to build" and became "things we intend + # to build, plus a vendor's whole catalogue". The listings wear + # `connector_directory.CATALOGUE_STATE` now and are counted as what they are; the + # constant is read rather than re-typed so the two cannot drift apart. + "counts": {"connected": sum(1 for r in served if r["state"] == "connected"), + "available": sum(1 for r in served if r["state"] == "available"), + "planned": sum(1 for r in served if r["state"] == "planned"), + "catalogue": sum(1 for r in served + if r["state"] == connector_directory.CATALOGUE_STATE)}} _ODOO_SCHEMA_ENABLEMENTS = "odoo_schema_enablements" @@ -786,9 +876,21 @@ def _odoo_admin(session): def _schema_catalog(session): """Rows-free Odoo field catalogue; source fields remain discoverable when every value is empty.""" + return _schema_catalog_rt(session.runtime) + + +def _schema_catalog_rt(rt): + """The same catalogue, over a RUNTIME rather than a session. + + ⚠ SPLIT IN W49-T12 SO THE DETAIL ROUTE CAN REUSE IT RATHER THAN RE-DERIVE IT. The connector + modal's Databases half needs exactly this catalogue, and writing a second reader of + `odoo_schema_snapshot` here would be the two-answers-to-one-question shape this module has + already paid for twice ([[one-question-two-normalizers]]). `_schema_catalog` keeps its + signature so every existing caller is untouched. + """ import core.user_tables as user_tables - enabled = session.runtime.get(_ODOO_SCHEMA_ENABLEMENTS) or {} - snapshot = user_tables.odoo_schema_snapshot(session.runtime) + enabled = rt.get(_ODOO_SCHEMA_ENABLEMENTS) or {} + snapshot = user_tables.odoo_schema_snapshot(rt) raw_models = snapshot.get("models") or {} if raw_models: rows = [] @@ -857,3 +959,445 @@ def odoo_schema_enable(field_key: str, body: dict = Body(default=None), session.runtime.pool_cache.pop(cache_key, None) return {"key": key, "enabled": enabled, "source": "Odoo", "permissionWall": "normal field permissions"} + + +# ═════════════════════════════════════════════════════════════════════════════════════════════ +# ⭐⭐ W49-T12 · RULING R26 · CONTRACT C4 — ONE CONNECTOR, IN FULL, FOR THE MODAL. +# ═════════════════════════════════════════════════════════════════════════════════════════════ +# +# R26: *"The connector popup is a centered MODAL with tabs Overview, Keychain, Databases, +# Relationships, opened from the card. The Keychain moves INTO it and Settings > Keychains becomes +# a link to the modal (one door). Field enablement moves into the Databases tab."* +# +# ⛔ ALL FOUR HALVES ARE COMPOSED NOW even though only Overview renders this wave, and that is +# C4's own instruction. The alternative — ship `overview` and add the rest as each tab lands — +# would make the DTO's shape a moving target across four tickets and give T13/T14/T15 nothing to +# build against. Every half is read from the source that already answers the question: +# +# overview · the directory row this module already composes, plus the Databases labels +# keychain · `routes_keychain.visible_entries`, i.e. the exact rows the Keychains room +# shows THIS reader, with a member's masked preview already blanked by R4 +# databases · `odoo_relational.grid_choices` (derived from `TABLES`, never a second list) +# plus the Odoo field catalogue this module already serves at +# `/connectors/odoo/schema` +# relationships · `relationship_graphs` UNCHANGED — the same DTO the directory already binds +# +# ⛔ AND NOTHING IS FABRICATED. A connector with no introspectable schema gets `databases: []`; a +# connector with no credential door gets an empty `entries` list and `canConnect: false`; a +# connection with no materialised tables gets the graph's own `unavailable` envelope. The rule this +# module was built on is that a plausible-looking placeholder is worse than an honest empty. + + +def _entry_type_for(connector_key): + """The keychain entry type behind one card, or `""` when the card has no stored credential. + + ⛔ DERIVED FROM `TOKEN_CONNECTORS`, NOT RE-TYPED. This module's header rule is that the row set + is composed from the registries that already exist; a second hand-written + `{"stripe": "stripe", ...}` map here would rot in exactly the way the header describes, one + connector at a time. Odoo is the one built-in whose credential lives in the keychain, so it is + named once, beside the row that names it. + """ + key = str(connector_key or "") + if key == "odoo": + return "odoo" + for token in TOKEN_CONNECTORS: + if str(token.get("key") or "") == key: + return str(token.get("entry") or "") + return "" + + +#: ⭐⭐ W49-T13 — WHAT A CONNECTOR ASKS FOR WHEN YOU CONNECT IT, declared server-side. +#: +#: ⛔ THE CLIENT MUST NOT OWN THIS MAP. R26 moves the add-a-key form into the connector modal, and +#: the obvious client implementation is `type === "odoo" ? [url, db, user, api_key] : [api_key]` — +#: a second copy of a credential SHAPE that already lives in `harness/connectors/odoo.py` and in +#: `routes_keychain._env_odoo_fields`. The wave-9 law is about vocabularies and this is one: a +#: connector whose credential grows a field would take a client edit to become storable. +#: ⚠ `secret` decides the input type, so a field marked secret is typed into a password box and +#: never echoed back — the masked preview is the only form the stored value takes afterwards. +_CONNECT_FIELDS = { + "odoo": [{"key": "url", "label": "Server URL (https://...)", "secret": False}, + {"key": "db", "label": "Database", "secret": False}, + {"key": "user", "label": "API user", "secret": False}, + {"key": "api_key", "label": "API key", "secret": True}], +} +#: Everything else is one pasted token. The field name is `api_key` because that is the first of +#: `core.keychain._PREVIEW_FIELDS`, so the stored entry gets a preview rather than a blank cell — +#: the wave-31 defect that comment records, avoided rather than repeated. +_CONNECT_TOKEN_FIELD = [{"key": "api_key", "label": "API key", "secret": True}] + + +def _detail_connect(entry_type, is_admin): + """C4's `keychain.connect` half: what the Connect form must ask for, and what it may store. + + ⭐ AN ADDITION TO C4, DECLARED. The contract pins `entries`, `canConnect` and `canDisconnect`; + it does not say where the form gets its fields, and the only two answers are "the server says" + and "the client re-derives". This is the first. + + `scope` carries the credential's own rule rather than a permission: a tenant-wide type has + exactly one legal scope, so the form states it instead of offering a picker whose save 400s + (`routes_keychain.add_key` refuses it, and R7's banned shape is a button that leads nowhere). + """ + if not entry_type: + return None + fields = _CONNECT_FIELDS.get(entry_type) or _CONNECT_TOKEN_FIELD + tenant_wide = entry_type in TENANT_WIDE_TYPES + return {"type": entry_type, + "fields": [dict(field) for field in fields], + # A member may always store a personal one; business-wide is an administrator's to + # give (R4), and a tenant-wide type is business-wide by construction. + "scopes": (["business"] if tenant_wide + else ["business", "personal"] if is_admin + else ["personal"]), + "tenantWide": tenant_wide} + + +def _oauth_slot_entries(rt, uname, row): + """A per-user OAuth connection, rendered as C4's `keychain` entry shape. + + ⛔⛔ THE KEYCHAIN TAB HAS A SECOND SOURCE, AND WITHOUT IT AN OAUTH CARD SAYS THE WRONG THING. + `_entry_type_for` covers `odoo` and `TOKEN_CONNECTORS` only, because an OAuth credential is + NOT a keychain entry: it lives in `core/keychain`'s separate `user_secrets` bucket, which + `list_entries` deliberately does not walk (*"a refresh token is identity, not shared + infrastructure"*). So an OAuth card asked for its entries got `[]` — i.e. *"nobody has + connected this"* about a provider this very reader may be signed in to. That is the same + confidently-wrong shape `accessSentence` was corrected for one tab over. + ⚠ AND IT IS NOT WIDENED INTO `_entry_type_for`. These are different stores with different + owners and different doors; teaching one function to answer for both would put a keychain + entry type on a credential that has none. + + ⛔ `testable` IS FALSE HERE, AND THAT IS THE HONEST VALUE RATHER THAN THE CAUTIOUS ONE. + `POST /admin/keychain/{id}/test` resolves its id through `visible_entries` -> `list_entries`, + which walks the `entries` bucket ONLY, so a Test control on a user secret would 404 every + time. A button that cannot work is exactly what R6 removed from the Google card. + + ⚠ NO SECRET IS READ. `oauth_connect.status` returns the account email and two flags; the + refresh token itself is never opened, and `masked` is empty because there is nothing about + this credential a preview could honestly show. + """ + slug = str(row.get("key") or "") + try: + state = (oauth_connect.status(rt, uname) or {}).get(slug) or {} + except Exception: # noqa: BLE001 + return [] + if not state.get("connected"): + return [] + email = str(state.get("email") or "") + label = str(row.get("label") or slug) + return [{"id": f"oauth:{slug}", + "label": f"{label} ({email})" if email else label, + "masked": "", + # A per-user slot is personal by construction, in the vocabulary `routes_keychain` + # already declares. Never a third word for the same idea. + "scope": "personal", + "testable": False}] + + +def _detail_keychain(rt, uname, is_admin, row): + """C4's `keychain` half: the credential rows THIS reader may see, and what they may do. + + ⚠ `visible_entries` IS CALLED WITH THE READER'S OWN ADMIN FLAG, deliberately. R4 blanks the + masked preview on a business entry a member did not create, and passing `True` to get a fuller + answer would hand a member four characters of the workspace's Odoo key. The restricted default + is the correct one and it is passed through rather than routed around. + + ⚠ A KEYCHAIN THAT CANNOT BE READ COSTS THE ENTRY LIST AND NOTHING ELSE, and it is not silent: + `directory()` records that failure in `incomplete`, and the page this modal opens from renders + that banner ABOVE the card grid. The reader has already been told before they click. + """ + entry_type = _entry_type_for(row.get("key")) + manage = str(row.get("manage") or "") + # The door this reader was offered on the CARD, not a second opinion about it: `directory` + # already decided admin vs member vs nothing, and deciding again here is how two answers to + # one question get born ([[one-question-two-normalizers]]). + can_connect = manage in ("keychain", "keychain_personal") + entries = [] + if entry_type: + try: + import routes_keychain as rk + for entry in rk.visible_entries(rt, uname, bool(is_admin)) or []: + if str(entry.get("type") or "") != entry_type: + continue + entries.append({ + "id": str(entry.get("id") or ""), + "label": str(entry.get("label") or entry.get("id") or ""), + "masked": str(entry.get("preview") or ""), + "scope": str(entry.get("scope") or rk.DEFAULT_SCOPE), + # `keychain.test_entry` answers for every stored entry: a registered prober for + # the type when the connector layer filled that slot, and a read-only shape or + # xmlrpc check otherwise. The flag says whether a Test control would have + # something to call, and it always does. + "testable": True, + }) + except Exception: # noqa: BLE001 + entries = [] + # ⭐ THE SECOND SOURCE. An OAuth card has no keychain entry type at all, so `entries` above is + # empty for it by construction and this is the only reading that can fill the tab. + if not entry_type and manage == "oauth": + entries = _oauth_slot_entries(rt, uname, row) + # `startUrl` is the Connect door for this kind, and `disconnect` is a per-user route, so + # both answers come from the ROW rather than from a credential door this card has none of. + return {"entries": entries, + "canConnect": bool(row.get("startUrl")), + "canDisconnect": bool(entries), + "connect": None} + return {"entries": entries, + "canConnect": can_connect, + "canDisconnect": bool(can_connect and entries), + # What the Connect form asks for. `None` when this card has no credential door at all, + # which is what stops the client inventing one (Webhooks, the Scraper, a planned row). + "connect": _detail_connect(entry_type, bool(is_admin)) if can_connect else None} + + +def _odoo_catalog_by_model(rt): + """`{odoo model: (fields, excluded)}` from the schema catalogue this module already serves. + + `excluded` is a DIFF, not a guess: every raw field the snapshot captured that the catalogue did + not offer. Today that diff is empty, which is the honest answer, and it fills itself the moment + the catalogue starts filtering instead of needing somebody to remember. + """ + import core.user_tables as user_tables + snapshot = user_tables.odoo_schema_snapshot(rt) + raw_models = snapshot.get("models") or {} + offered = {} + for row in _schema_catalog_rt(rt): + offered.setdefault(str(row.get("model") or ""), []).append(row) + out = {} + for model, raw_fields in raw_models.items(): + rows = offered.get(str(model), []) + offered_raw = {str(row.get("rawName") or "") for row in rows} + out[str(model)] = ( + [{"key": str(row.get("key") or ""), + "label": str(row.get("label") or ""), + "type": str(row.get("type") or "text"), + "source_field": str(row.get("rawName") or ""), + "enabled": bool(row.get("enabled"))} + for row in rows], + [{"source_field": str(name), + "reason": "This source field was captured from Odoo but the field catalogue did not " + "offer it."} + for name in sorted(raw_fields or {}) if str(name) not in offered_raw], + ) + return out + + +def _detail_databases(rt, is_admin, connector_key): + """C4's `databases` half: what this connector materialises, and the fields behind each one. + + ⛔ ODOO IS THE ONLY INTROSPECTABLE CONNECTOR TODAY and every other card answers `[]`. That is + the contract's own instruction, and the alternative would be a list of database names no + connector actually creates. + + ⛔ THE ROW SURVIVES FOR A NON-ADMIN; ONLY THE CATALOGUE HALVES EMPTY. Returning `[]` to a + member would be indistinguishable from *"this connector creates no databases"*, which is the + confidently-wrong shape this module's header was written about. A database's NAME and whether + it is switched on are facts about their own workspace; the raw Odoo field catalogue is + administrator-only (`_odoo_admin` gates the route that serves it) and stays that way. + + ⛔⛔ W49-T14 — `sharesFieldsWith` IS NOT DECORATION, IT IS THE ONE THING THIS SCREEN WOULD + OTHERWISE LIE ABOUT. MEASURED on `odoo_relational.ODOO_TABLE_MODELS`: `ut_odoo_invoices` and + `ut_odoo_bills` are BOTH `account.move`, and `ut_odoo_agents` and `ut_odoo_vendors` are BOTH + `res.partner`. The enablement flag is keyed `"."` (`_schema_catalog_rt`), so + those pairs do not merely LOOK alike — they are one list of fields behind two names, and a + single `PATCH /connectors/odoo/schema/{field_key}` flips the field under both. A disclosure + that printed the same forty rows under two headings with no word about it would be showing a + per-database control that is not per-database, and the reader would discover it by watching + the other database change. So the row carries the sibling it shares with, by KEY, and the tab + says so above the toggles. + """ + if not connector_directory.is_introspectable(connector_key): + return [] + try: + import odoo_relational + choices = odoo_relational.grid_choices(rt) + models = dict(getattr(odoo_relational, "ODOO_TABLE_MODELS", {}) or {}) + except Exception: # noqa: BLE001 + return [] + catalog = {} + if is_admin: + try: + catalog = _odoo_catalog_by_model(rt) + except Exception: # noqa: BLE001 + catalog = {} + # Which OTHER declared databases read the same Odoo model. Derived from the map, never a + # hand-typed pair list: a ninth table added to `TABLES` gets this disclosure for free. + shared = {} + for choice in choices: + key = str(choice.get("key") or "") + model = str(models.get(key) or "") + if model: + shared.setdefault(model, []).append(key) + out = [] + for choice in choices: + key = str(choice.get("key") or "") + model = str(models.get(key) or "") + fields, excluded = catalog.get(model, ([], [])) + out.append({"key": key, + "label": str(choice.get("label") or key), + "enabled": bool(choice.get("enabled")), + "fields": [dict(field) for field in fields], + "excluded": [dict(item) for item in excluded], + "sharesFieldsWith": [other for other in shared.get(model, ()) + if other != key]}) + return out + + +#: What an EMPTY `excluded` list actually means, said once, on the server that computes it. +#: +#: ⛔⛔ THE TRAP THIS CLOSES, MEASURED: `_odoo_catalog_by_model` builds `excluded` as a DIFF of the +#: snapshot's raw fields against the catalogue, and the catalogue offers every raw field it +#: captured — so the diff is EMPTY TODAY BY CONSTRUCTION. A tab that rendered "Excluded: none" +#: over that would be telling an administrator that this workspace holds back nothing from Odoo, +#: which is a claim about POLICY that the number cannot support. The empty list means the +#: catalogue dropped nothing it saw; it says nothing at all about what Odoo never reported. +#: +#: ⚠ IT IS SERVED RATHER THAN WRITTEN IN THE CLIENT because the sentence is a description of a +#: server computation. A client copy would go stale the day the catalogue starts filtering, and +#: nothing would go red. +_EXCLUDED_BASIS = ("A field is excluded when this workspace captured it from Odoo and the field " + "catalogue did not offer it. Anything Odoo never reported cannot appear in " + "this list at all.") + + +def _detail_introspection(rt, is_admin, row): + """R24's half of the Databases tab: may this connector be disclosed, and to THIS reader? + + ⭐ AN ADDITION TO C4, DECLARED, and the same kind of addition `_detail_connect` is. C4 pins + the `databases` list and says nothing about how a client tells "this connector has no schema" + apart from "this connector's schema could not be read". Those two are the same empty list and + they mean opposite things, so the difference is stated rather than inferred. + + ⛔ EVERY FLAG HERE IS A CAPABILITY THE SERVER WILL HONOUR, not a guess the client makes. The + field toggle is `PATCH /connectors/odoo/schema/{field_key}`, which `_odoo_admin` gates and + which raises 409 `odoo_schema_unavailable` while no complete snapshot exists — so + `canToggleFields` carries BOTH conditions and the client renders no control that could only + ever 409. A button that always fails is R7's banned shape. + + ⚠ `fieldsVisible` IS SEPARATE FROM `canToggleFields` ON PURPOSE. A member sees the database + names and their on/off state (their own workspace's facts) and no field catalogue at all + (`_odoo_admin` gates the route that serves it); saying which of the two is missing is what + stops "administrator only" being rendered as "this database has no fields". + """ + key = str(row.get("key") or "") + if not connector_directory.is_introspectable(key): + reason = ("Nothing is connected behind this listing yet, so there is no schema to read." + if str(row.get("state") or "") == connector_directory.CATALOGUE_STATE + else "This connector does not publish a field catalogue, so the databases it " + "creates cannot be listed field by field.") + return {"introspectable": False, "reason": reason, "fieldsVisible": False, + "canToggleFields": False, "canToggleTables": False, + "catalogueComplete": False, "capturedAt": "", "excludedBasis": ""} + complete = False + captured = "" + try: + import core.user_tables as user_tables + snapshot = user_tables.odoo_schema_snapshot(rt) + complete = snapshot.get("complete") is True + captured = str(snapshot.get("capturedAt") or "") + except Exception: # noqa: BLE001 + complete, captured = False, "" + return {"introspectable": True, + "reason": "", + "fieldsVisible": bool(is_admin), + # BOTH conditions, because the write door enforces both. + "canToggleFields": bool(is_admin) and complete, + # ⭐ R22: ANY table can be switched off, not only the ones we mark optional. The write + # is `PUT /admin/connectors/odoo/config`, which is an administrator's door and accepts + # every key `grid_choices` names, including all of them at once. + "canToggleTables": bool(is_admin), + "catalogueComplete": complete, + "capturedAt": captured, + "excludedBasis": _EXCLUDED_BASIS} + + +def _detail_overview(row, databases, graph): + """C4's `overview` half: what the modal's first tab reads, top to bottom. + + `creates` is the table LABELS this connector stands behind: the declared grids when the + connector declares any, and otherwise the tables its own permitted graph actually found. Both + are real readings of THIS workspace; neither is a provider template. + """ + creates = [str(entry.get("label") or "") for entry in (databases or []) + if str(entry.get("label") or "")] + if not creates and isinstance(graph, dict) and graph.get("status") == "ready": + creates = [str(table.get("label") or "") for table in (graph.get("tables") or ()) + if str(table.get("label") or "")] + return {"key": str(row.get("key") or ""), + "label": str(row.get("label") or ""), + "status": str(row.get("state") or ""), + # Empty when the server has no account to name. The client says so in a sentence + # rather than printing a blank row. + "account": str(row.get("connectedAs") or ""), + # The system the data comes FROM, in the words a customer reads on the card. Never a + # provider slug: an internal identifier on screen is exactly what `parseDirectory` + # drops a row to avoid. + "source": str(row.get("label") or ""), + "creates": creates} + + +def connector_detail(rt, user, uname, is_admin, connector_key): + """The whole C4 detail DTO for one connector, or `None` when this reader has no such card. + + Pure over the session for the same reason `directory` is: a gate can drive it without a + request, so the modal's payload is provable without a browser. + """ + rows = directory(rt, uname, bool(is_admin)) + key = str(connector_key or "") + row = next((candidate for candidate in rows + if str(candidate.get("key") or "") == key), None) + if row is None: + return None + graph = relationship_graphs(rows, user, rt, uname, bool(is_admin)).get(key) or _graph_refusal( + key, "No actual relationship graph was returned for this connection. A provider template " + "is not shown.") + databases = _detail_databases(rt, bool(is_admin), key) + return {"overview": _detail_overview(row, databases, graph), + "keychain": _detail_keychain(rt, uname, bool(is_admin), row), + "databases": databases, + # ⭐ W49-T14 / R24 — WHETHER THE DATABASES TAB MAY DISCLOSE ANYTHING AT ALL, and what + # THIS reader may do there. An addition to C4, declared on `_detail_introspection`: + # without it an empty `databases` list is "this connector has no schema" and "this + # connector's schema could not be read" at the same time. + "introspection": _detail_introspection(rt, bool(is_admin), row), + # ⛔ THE `relationship_graphs` SHAPE, UNCHANGED. C4 says so in as many words, and the + # client already has a reader for it (`parseRelationshipGraph`) that refuses a graph + # bound to another connection. A second shape here would need a second reader. + "relationships": graph} + + +# ⚠ DECLARED AFTER THE LITERAL `/connectors/odoo/*` ROUTES. FastAPI matches in declaration order, +# and while none of those ends in `/detail` — so no shadowing is possible today — the ordering is +# the habit that keeps it impossible tomorrow. `/connectors/directory` is two segments and cannot +# collide with this three-segment path at all. +@router.get("/connectors/{connector_key}/detail") +def connectors_detail(connector_key: str, session: Session = Depends(require_session)): + """C4 / R26: everything the connector modal shows, for THIS reader, in one read. + + Session-gated exactly like the directory it is opened from: a member may look at what the + workspace is connected to. What a member does NOT get is the tenant-wide credential door + (`canConnect` carries the card's own answer) or the administrator-only Odoo field catalogue. + """ + detail = connector_detail(session.runtime, session.user, session.uname, + bool(session.admin), connector_key) + if detail is None: + raise err(404, "unknown_connector", + "this workspace has no connector with that key") + return detail + + +# ⛔⛔ W49-T16 — THE MOUNT. `dependents_router` DECLARES NO PREFIX OF ITS OWN, so including it in +# this router (which carries `prefix="/api/v1"`) yields exactly `/api/v1/dependents`. Declaring +# the prefix on both would serve `/api/v1/api/v1/dependents` — the mirror image of the wave-23 +# defect this file's own header records, where the MISSING prefix 404'd a shipped route with +# every gate green. `verify_shared_views.py` asserts the assembled path off this very object +# rather than trusting the arithmetic. +router.include_router(dependents_router) + +# ⛔⛔ W49-T19 — THE SECOND MOUNT, IDENTICAL IN SHAPE. `monid_router` is a bare `APIRouter()`, +# so this yields `/api/v1/monid/amazon-reviews/meta`, `/api/v1/monid/amazon-reviews/run` and +# `/api/v1/monid/spend`. +# ⚠ THE ASSEMBLED PATH IS NOT VISIBLE IN `router.routes`. FastAPI 0.139.2 leaves an +# `_IncludedRouter` placeholder there, so a walk of that list finds nothing and a gate written +# against it would pass on a router that serves the paths twice-prefixed. `app.openapi()["paths"]` +# is the reliable read, and it is what `verify_meta.py::section_monid_mount` uses. +router.include_router(monid_router) diff --git a/api/routes_dependents.py b/api/routes_dependents.py new file mode 100644 index 0000000000000000000000000000000000000000..fcbe5a98b89db0c2f1576017b6de36b780e7ba3f --- /dev/null +++ b/api/routes_dependents.py @@ -0,0 +1,168 @@ +"""routes_dependents.py — the ONE door onto the dependents registry (wave 49, C3, R23 + R32). + +⭐⭐ **R23:** *"Switching off a table that something depends on is REFUSED, and the refusal NAMES +the dependents ('3 views, 1 Route and 2 Sheet cells use this')."* +⭐⭐ **R32:** *"deleting a view must first disclose who it is shared to and which Sheet cells +depend on it."* + +Two surfaces ask the same question — the Databases tab's off switch and the view-delete +disclosure — so they share one endpoint over `platform/core/dependents.py` instead of each +growing its own pre-flight check. + +⛔⛔ **THIS ROUTER DECLARES NO PREFIX, AND THAT IS DELIBERATE.** It is mounted by +`routes_connectors.py::router.include_router(...)`, and THAT router already carries +`prefix="/api/v1"`. Declaring `/api/v1` here too would serve `/api/v1/api/v1/dependents` — the +mirror image of the wave-23 defect `routes_connectors`' own header records, where a MISSING prefix +404'd a shipped route with every gate green. The assembled path is asserted, not assumed: see the +`verify_shared_views.py` check that imports the parent router and reads `route.path` back. + +⛔ **`main.py` IS ANOTHER LANE'S FILE.** In a worktree-parallel wave `main.py` can live in exactly +one fence, so a new router mounts from a file its own lane owns. `routes_connectors.router` is +already included in `main.py`, so including this one into it puts the path on the app with no +cross-fence edit. + +⛔⛔ **THE PER-DATABASE WALL RUNS BEFORE ANY STORE READ, AND IT IS IMPORTED, NEVER RE-DERIVED.** +A dependents answer names view names, Route ids, column keys and the usernames a view is shared +with. Answering it for a database the caller may not open would be a disclosure through a door +with no wall of its own ([[a-cached-value-outruns-the-permission-wall]]). +`routes_charts._require_database` is the shipped chokepoint — `core.perm_scope.nav_may_open` +threaded with `st=session.runtime` plus the tenant module catalogue — and its own docstring +explains at length why the `st=` argument is load-bearing for `ut_*` keys. A second copy of that +predicate here is how the two come apart. + +⚠ **`?database=` IS OPTIONAL FOR A VIEW, AND THE RESOLUTION IS STILL WALLED.** The disclosure +dialog holds a view id and not always the database key, so a bare `?kind=view&key=` resolves +the view's home by looking through the caller's OWN databases. Every candidate goes through +`_may_open` BEFORE its workspace bucket is read, so the scan can only ever find a view the caller +was already entitled to see, and a view living in a database they may not open answers 404 rather +than leaking its existence. + +⚠ **THE SHARE AUDIENCE IS TRIMMED.** `shares.grants` carries `by` provenance (D-474) and its own +docstring names the cost of publishing it. This door returns names and a count, which is all +"Shared with Anna and 2 others" consumes. +""" + +from fastapi import APIRouter, Depends, Query + +import core.dependents as dependents_registry +import core.registry as registry +import core.user_tables as user_tables +import core.view_templates as view_templates +from deps import Session, err, require_session +from routes_charts import _may_open, _require_database + +#: ⛔ NO PREFIX. See the module header — the parent router owns `/api/v1`. +router = APIRouter() + +#: The two built-in databases that carry saved Views, ahead of the `ut_*` tables. Order is a +#: search order only: the wall decides what is actually looked at. +_BUILT_INS = ('customer_data', 'product_data') + + +def _candidate_databases(session: Session): + """Every database key this tenant HAS, built-ins first. Not yet walled — `_may_open` is.""" + keys = list(_BUILT_INS) + try: + for key in (user_tables.all_defs(st=session.runtime) or {}): + if str(key) not in keys: + keys.append(str(key)) + except Exception: + pass + return keys + + +def _label_for(session: Session, database, kind, key): + """The human name the refusal sentence starts with, or the raw key when there is no better.""" + definition = None + try: + definition = (user_tables.all_defs(st=session.runtime) or {}).get(database) + except Exception: + definition = None + table_label = str((definition or {}).get('label') or '').strip() \ + or str((registry.BY_KEY.get(database) or {}).get('label') or '').strip() \ + or str(database or '') + if kind == 'table': + return table_label + if kind == 'field': + for field in ((definition or {}).get('fields') or ()): + if isinstance(field, dict) and str(field.get('key') or '') == key: + return str(field.get('label') or key) + return key + for _owner, view_id, view in dependents_registry.walk_views(session.runtime, database): + if view_id == key: + return str(view.get('name') or key) + return key + + +def _resolve_view_home(session: Session, view_id): + """The database key whose workspace holds `view_id`, among the caller's OWN databases. + + ⛔ THE WALL RUNS FIRST, PER CANDIDATE. `_may_open` is `_require_database` memoized, so this + loop reads no bucket the caller could not have read through the grid. A view the caller may + not reach is simply not found, which the door reports as 404 — the same answer as a view id + that does not exist, deliberately. + """ + seen = {} + for candidate in _candidate_databases(session): + if not view_templates.workspace_key(candidate): + continue + if not _may_open(session, candidate, seen): + continue + for _owner, found_id, _view in dependents_registry.walk_views(session.runtime, candidate): + if found_id == view_id: + return candidate + return None + + +@router.get("/dependents") +def read_dependents(kind: str = Query(...), key: str = Query(...), + database: str = Query(""), + session: Session = Depends(require_session)): + """C3: what depends on one table, view or column, plus a view's share audience (R32). + + The answer is the registry's, not this file's: providers live in `core/dependents.py` and the + `sheet_cell` kind joins them when `platform/modules/sheet.py` registers it after the wave-49 + merge (W49-T11). Until then the kind is ABSENT from every answer, never present as zero. + """ + target_kind = str(kind or '').strip().lower() + target_key = str(key or '').strip() + if target_kind not in ('table', 'view', 'field'): + raise err(400, "dependents_kind_unknown", + "a dependents target is a table, a view or a field") + if not target_key: + raise err(400, "dependents_key_required", "name the thing you want the dependents of") + + resolved = str(database or '').strip() + if target_kind == 'table': + resolved = resolved or target_key + if target_kind == 'view' and not resolved: + resolved = _resolve_view_home(session, target_key) + if not resolved: + raise err(404, "view_not_found", + "no saved view with that id is available on your databases") + if not resolved: + raise err(400, "dependents_database_required", + "name the database this column belongs to") + + resolved = _require_database(session, resolved) + + target = {"kind": target_kind, "key": target_key, "database": resolved} + report = dependents_registry.dependents_report(session.runtime, target) + label = _label_for(session, resolved, target_kind, target_key) + body = { + "target": target, + "label": label, + "dependents": report["dependents"], + "refusal": dependents_registry.refusal(label, report["dependents"]), + "errors": report["errors"], + "kinds": dependents_registry.registered_kinds(), + } + if target_kind == "view": + audience = dependents_registry.share_audience(session.runtime, target_key) + body["share"] = { + "owner": audience["owner"], + "names": audience["names"], + "count": audience["count"], + "sentence": dependents_registry.audience_sentence(audience), + } + return body diff --git a/api/routes_keychain.py b/api/routes_keychain.py index 4ef61ca06030bf7abf2238ae1421cbde6686560d..7c3e86ab5c45ebf435174762bad213bfecfe1ec5 100644 --- a/api/routes_keychain.py +++ b/api/routes_keychain.py @@ -234,6 +234,59 @@ def odoo_paused(rt): return bool(rt.odoo_paused()) +#: ⭐⭐ W49-T13 / D-247 — WHICH CONNECTORS HAVE A STOP MECHANISM AT ALL. +#: +#: ⛔ ENUMERATED RATHER THAN ASSUMED, because the honest answer for every other connector is "this +#: connector cannot be stopped", and a bare `False` reads identically to "it is running". A card +#: whose credential is a token nobody syncs from has no pause flag and no freeze flag; saying so +#: is a different statement from saying it is live. +STOPPABLE_CONNECTORS = ("odoo",) + + +def connector_stopped(rt, key): + """ONE predicate for *"is this connector stopped?"* — `paused` OR `frozen`, by connector key. + + ⭐⭐ D-247, and the register's point is that these are TWO flags for one question. A connector + is not being read from when EITHER is set, and every read site until now picked one of them: + `odoo_relational.refresh` checks `frozen` alone, `routes_customers` and `routes_products` check + `odoo_paused` alone. Two half-answers to one question is + [[one-question-two-normalizers]] wearing two different names, and it is why "I disconnected it + and the mirror still refreshed" and "I paused it and the grids still rebuilt" are both + reachable states. + + ⛔ THE PAIR IS ODOO-SHAPED TODAY AND THIS SAYS SO OUT LOUD. `frozen` lives in + `odoo_relational.read_config` and exists for no other connector; the pause flag is keyed by + KEYCHAIN ENTRY id, not by connector, so it answers for the Odoo source this tenant actually + resolves to and for nothing else. An unknown or un-stoppable connector therefore gets an + EXPLICIT `False` from the guard above rather than falling out of the bottom of a chain of + `if`s, so a caller reading this cannot mistake "no mechanism" for "measured, and running". + + ⚠ NEITHER HALF RAISES. `frozen` reads the tenant config and `odoo_paused` reads the flags + bucket, and both are reachable when the store is having a bad minute. The fail-towards-LIVE + policy `odoo_paused` documents is kept: an unreadable flag must never freeze a live connector, + so an exception answers `False`. + + ⚠ NOT YET ADOPTED AT EVERY READ SITE, and that is a lane fence rather than an oversight. + `odoo_relational.py:2444`, `routes_automation.py:747`, `routes_customers.py:91` and + `routes_products.py:92` still read one half each; they belong to other tickets' files this + wave. `harness/datastore.py` can never adopt it by import at all — `platform/` must not import + from `aios-web/api/`, which is exactly why `runtime.py::set_paused_probe` injects the answer + downward instead. + """ + key = str(key or "") + if key not in STOPPABLE_CONNECTORS: + return False + try: + if _rel().frozen(rt): + return True + except Exception: # noqa: BLE001 + pass + try: + return bool(rt.odoo_paused()) + except Exception: # noqa: BLE001 + return False + + def _snap_scope_key(team_id, agent): return f"t={team_id}|a={agent}" @@ -416,6 +469,51 @@ def _own_row(session, entry_id): return row +def _connector_by_entry_type(): + """`{keychain entry type: {"key", "label"}}` — which CONNECTOR CARD owns each credential type. + + ⭐⭐ W49-T13 / R26 — THE ONE DOOR NEEDS AN ADDRESS. R26 moves credential editing into the + connector modal and turns Settings > Keychains into a link to it, so every stored entry has to + know which card opens it. The map is INVERTED from `routes_connectors._entry_type_for` rather + than typed out here: that function is already the single answer to "which credential type + stands behind this card", and a second hand-written table is what this repo's connector header + was written about. + + ⚠ IMPORTED LAZILY. `routes_connectors` imports THIS module at module scope + (`from routes_keychain import TENANT_WIDE_TYPES, env_odoo_available`), so a module-level import + back would be a cycle. Same idiom `_kc()` and `_rel()` already use. + ⚠ AND IT FAILS SOFT. A registry that cannot be read costs the LINK and nothing else: the pane + still lists the entry, it simply cannot offer the door. + """ + out = {} + try: + import routes_connectors as rc + out["odoo"] = {"key": "odoo", "label": "Odoo"} + for row in rc.TOKEN_CONNECTORS: + etype = str(row.get("entry") or "") + if etype: + out[etype] = {"key": str(row.get("key") or ""), + "label": str(row.get("label") or "")} + except Exception: # noqa: BLE001 + return {} + return out + + +def _with_connector(rows): + """Each visible entry, plus the connector card that now owns its credential door (R26). + + An entry whose type stands behind no card (`generic`) carries no `connector` key at all, which + is what keeps it editable in Settings: the pane hands off exactly the rows that have somewhere + to be handed off TO, and keeps the rest rather than stranding them. + """ + owners = _connector_by_entry_type() + out = [] + for row in rows: + owner = owners.get(str(row.get("type") or "")) + out.append({**row, "connector": dict(owner)} if owner else dict(row)) + return out + + @router.get("/admin/keychain") def list_keychain(session: Session = Depends(require_session)): """⭐ W32-T11 / R4 — SESSION-GATED, NOT ADMIN-GATED, and that is the ruling not a relaxation. @@ -423,8 +521,8 @@ def list_keychain(session: Session = Depends(require_session)): ship the feature and no door to it. The wall moved INTO the payload: a member sees the business-wide entries and their own, never anybody else's personal one.""" kc = _kc() - return {"entries": visible_entries(session.runtime, session.uname, - bool(session.admin)), + return {"entries": _with_connector(visible_entries(session.runtime, session.uname, + bool(session.admin))), "locked": not kc.unlocked(), #: the vocabulary and the permission, so the client renders a picker it can honour #: rather than offering an option the server will refuse (R4: business is admin-only). diff --git a/api/routes_monid.py b/api/routes_monid.py new file mode 100644 index 0000000000000000000000000000000000000000..37a840b722a8895e2a570d798b2e5d5a6ecbebc0 --- /dev/null +++ b/api/routes_monid.py @@ -0,0 +1,300 @@ +"""routes_monid.py — the Amazon reviews slice over Monid. W49-T19, ruling R31, contract C5. + +⭐⭐ R31, verbatim: *"Monid's one working slice is Amazon reviews for our ASINs, landing as a +database linkable to Odoo products."* + +⛔⛔ MOUNTED FROM `routes_connectors.py`, NEVER FROM `main.py` (C5). This router declares NO +prefix; the parent owns `/api/v1`. Declaring it on both silently serves `/api/v1/api/v1/monid/...` +and every call 404s while `tsc`, the build and every source scan stay green — which is the trap +W49-T16 paid for when it mounted `routes_dependents` the same way. + +⚠ FastAPI 0.139.2 leaves `_IncludedRouter` PLACEHOLDERS in `router.routes`, so a walk of +`[r.path for r in router.routes]` cannot see a child router's assembled path at all. The reliable +read of what is actually served is `app.openapi()["paths"]`. Do not rediscover this. + +⛔⛔ EVERY POST TO `/monid/amazon-reviews/run` SPENDS REAL MONEY. There is no dry run and no +sandbox key at Monid. The two GETs here are free: `meta` reads constants and one free wallet +probe, `spend` reads our own ledger. Only the POST debits, only an administrator may call it, and +it says what it will cost before it is confirmed. + +⛔ THE TABLE DOORS ARE CALLED, NOT REIMPLEMENTED (C5). `routes_tables.create_table` and +`routes_tables.import_rows` are the only way rows land, and `routes_tables.py` belongs to another +lane — nothing here edits it. They are plain synchronous functions taking a raw dict body and a +`Session`, so they are called in process; what that costs is that FastAPI's exception machinery +is not around them, so `HTTPException` is caught here rather than allowed to escape as a 500. +""" +import sys as _monid_sys +from pathlib import Path as _MonidPath + +from fastapi import APIRouter, Body, Depends, HTTPException + +from deps import Session, err, require_session + +_PLATFORM = _MonidPath(__file__).resolve().parents[2] / "platform" +if str(_PLATFORM) not in _monid_sys.path: + _monid_sys.path.insert(0, str(_PLATFORM)) + +import core.monid as monid # noqa: E402 +import core.user_tables as ut # noqa: E402 + +#: ⛔ NO PREFIX. See the module docstring; the parent owns `/api/v1`. +router = APIRouter() + +#: The most ASINs one pull may name. Not a data cap in the sense standing rule 1 forbids: Monid +#: is a METERED third party and every ASIN is a separate debit, so this bounds a SPEND, not a +#: read from a connected source. The rule's own test is `records_mutable(key)`, and the records +#: here are minted by a paid call rather than mirrored from a connector. +MAX_ASINS = 25 + +#: How long we wait on an asynchronous run before answering "still going". A 202 gives us a run +#: id; polling forever inside a request would hold a worker for the p95 of 51.5 seconds and then +#: some, so the ceiling is explicit and the answer names the run id either way. +POLL_ATTEMPTS = 12 +POLL_SLEEP = 5 + + +def _require_admin(session: Session): + """⛔ THE PAID DOOR IS ADMIN ONLY, and the check reads `session.admin`. + + ⚠ NOT `getattr(session, "is_admin", False)` — that attribute does not exist, so the guard + would read False for everyone and refuse the administrator too. `routes_connectors.py` carries + the same warning at its own directory route; this is the same trap, one file over. + """ + if not session.admin: + raise err(403, "not_admin", + "Only an administrator can pull Amazon reviews, because the pull spends this " + "workspace's Monid balance.") + + +def _monid_http(exc: monid.MonidError): + """A Monid refusal as our one error shape (X2). + + ⛔ 402 IS 402 AND ITS SENTENCE IS EXACT (C5). "Monid wallet is empty", authored once in + `core/monid.py`, printed here, printed by the dialog. Nothing retries it. + """ + if isinstance(exc, monid.MonidWalletEmpty): + return err(402, "wallet_empty", monid.WALLET_EMPTY_MESSAGE) + return err(502, exc.code, exc.message) + + +@router.get("/monid/amazon-reviews/meta") +def amazon_reviews_meta(session: Session = Depends(require_session)): + """What the dialog needs before it can ask for anything, and it costs nothing. + + ⭐ `canRun` IS THE ADMIN GATE, SERVED RATHER THAN COMPUTED ON THE CLIENT. This directory's + own rule is that an empty `manage` renders NO control instead of one that would 403, and the + client has no notion of who is an administrator. So the button exists only when the server + says the caller may press it. + + ⚠ THE BALANCE IS A FREE PROBE AND IT IS ALLOWED TO FAIL. A wallet read that times out must + not stop an operator seeing the price, so `balance` is reported as `null` and the dialog says + the balance is unknown rather than inventing one. + """ + bal = None + if monid.configured(): + try: + b = monid.balance() or {} + v = (b.get("balance") or {}) if isinstance(b, dict) else {} + bal = {"value": v.get("value"), "currency": v.get("currency")} + except monid.MonidError: + bal = None + return { + "canRun": bool(session.admin), + "configured": monid.configured(), + "provider": monid.AMAZON_REVIEWS_PROVIDER, + "endpoint": monid.AMAZON_REVIEWS_ENDPOINT, + "priceKind": monid.AMAZON_REVIEWS_PRICE_KIND, + "unitPrice": monid.AMAZON_REVIEWS_UNIT_PRICE, + "currency": monid.AMAZON_REVIEWS_CURRENCY, + "maxAsins": MAX_ASINS, + "tableKey": monid.TABLE_KEY, + "tableLabel": monid.TABLE_LABEL, + "balance": bal, + # ⭐ WHERE THE ASINs COME FROM, MEASURED RATHER THAN ASSUMED. `fields_get` on + # `product.template` and `product.product` was read on 2026-09-02: the only Amazon field + # either model carries is `x_studio_amazon_sku` ("Amazon SKU"), and its 162 populated + # values are merchant SKUs such as `RI-SHR-09_BLK`, not ten-character ASINs. So Odoo has + # no ASIN to offer and the operator pastes them. Saying so here keeps the sentence the + # user reads and the fact behind it in one place. + "asinSource": "paste", + "asinNote": "Odoo has no ASIN field. The nearest one, Amazon SKU, holds merchant SKUs " + "such as RI-SHR-09_BLK, so paste the ASINs you want reviews for.", + } + + +@router.get("/monid/spend") +def monid_spend(session: Session = Depends(require_session)): + """The ledger C5 names, newest last. Every paid run is in here or it did not happen.""" + _require_admin(session) + rows = monid.spend_rows(st=session.runtime) + return {"runs": rows, + "total": round(sum(float(r.get("cost") or 0) for r in rows), 6), + "currency": monid.AMAZON_REVIEWS_CURRENCY} + + +@router.post("/monid/amazon-reviews/run", status_code=201) +def amazon_reviews_run(body: dict = Body(default=None), + session: Session = Depends(require_session)): + """⛔⛔ THE ONE PAID DOOR. One call, one debit, one ledger row. + + The shape of the work, in the order it has to happen: + + 1. REFUSE FIRST, SPEND SECOND. Not an administrator, no key, no valid ASIN: every one of + those is answered before a request reaches Monid, because a refusal after the debit is + a refusal the wallet already paid for. + 2. RUN. `run()` answers 200 with the result inline or 202 with a run id, because the + endpoint's own p95 run time is 51.5 seconds and the sync window is shorter than that. + A 202 is polled here, up to a stated ceiling, and then reported honestly as pending with + its run id rather than as a failure. + 3. LEDGER BEFORE LANDING. `record_spend` is called as soon as the run is accepted. The money + is gone whether or not the table write succeeds, so a ledger written after the import + would under-report every run that failed to land. + 4. LAND. Columns are derived from the RECORDS THAT CAME BACK (`columns_from_rows`), because + `inspect` returns no output schema; then `create_table` and `import_rows` are CALLED. + """ + _require_admin(session) + if not monid.configured(): + raise err(503, "not_configured", + "Monid is not connected in this workspace. An administrator adds the key " + "before a pull can run.") + payload = body if isinstance(body, dict) else {} + asins, rejected = monid.clean_asins(payload.get("asins"), limit=MAX_ASINS) + if not asins: + raise err(400, "no_asins", + "Enter at least one ASIN. An ASIN is ten characters, letters and digits, and " + "it is printed on the product page.") + if rejected: + raise err(400, "bad_asins", + "These are not ASINs: " + ", ".join(rejected[:5]) + + ". An ASIN is ten characters, letters and digits.") + domain = str(payload.get("domainCode") or "com") + sort_by = str(payload.get("sortBy") or "recent") + try: + max_pages = max(1, min(10, int(payload.get("maxPages") or 1))) + except (TypeError, ValueError): + max_pages = 1 + + run_input = monid.amazon_reviews_input(asins, domain, sort_by, max_pages) + try: + status, answer = monid.run(monid.AMAZON_REVIEWS_PROVIDER, + monid.AMAZON_REVIEWS_ENDPOINT, run_input) + except monid.MonidError as exc: + raise _monid_http(exc) + + run_id = "" + if isinstance(answer, dict): + run_id = str(answer.get("runId") or answer.get("run_id") or answer.get("id") or "") + + # ⛔⛔ THE LEDGER RECORDS WHAT WAS CHARGED, NOT WHAT WE GUESSED, and this is a CORRECTION + # paid for by a live run. The first version wrote `estimate_cost(len(asins))` on the vendor's + # own pricing note; that note is false, 2 ASINs billed 20 units, and the ledger would have + # said 0.0027 about a charge of 0.027. A completed run carries an authoritative + # `cost: {"value", "currency"}` that matched the wallet delta exactly, so it wins. + # + # ⚠ THE FLOOR IS STILL WRITTEN WHEN NOTHING IS REPORTED, because the money moved whether or + # not Monid told us how much. It is stamped `estimated` so nobody reads it as measured. + cost = monid.payload_cost(answer) + estimated = cost is None + if estimated: + cost = monid.estimate_cost(len(asins)) + # ⛔ WRITTEN HERE, BEFORE THE POLL AND BEFORE THE TABLE. The debit already happened, and a + # crash between here and the import must not lose the spend. + monid.record_spend(session.tenant, monid.AMAZON_REVIEWS_PROVIDER, + monid.AMAZON_REVIEWS_ENDPOINT, cost, run_id, + st=session.runtime, estimated=estimated) + + if status == 202: + import time + for _ in range(POLL_ATTEMPTS): + time.sleep(POLL_SLEEP) + try: + answer = monid.poll(run_id) + except monid.MonidError as exc: + raise _monid_http(exc) + state = str((answer or {}).get("status") or "").lower() if isinstance(answer, dict) else "" + if state in ("succeeded", "success", "done", "completed", "finished"): + break + if state in ("failed", "error", "cancelled", "canceled"): + raise err(502, "run_failed", + "The Monid run finished without a result. The spend is recorded as " + "run " + (run_id or "with no id") + ".") + if monid.extract_records(answer): + break + else: + return {"pending": True, "runId": run_id, "cost": cost, "costEstimated": estimated, + "asins": asins, "records": 0, "tableKey": "", + "message": "The run is still going at Monid. It is recorded in the spend " + "ledger as run " + (run_id or "with no id") + "."} + + # ⭐ THE 202 PATH REPORTS ITS COST ONLY WHEN IT COMPLETES, so the estimated row written above + # is amended here rather than left as a guess for a run we now have the real figure for. + if estimated: + settled = monid.payload_cost(answer) + if settled is not None and monid.settle_spend(run_id, settled, st=session.runtime): + cost, estimated = settled, False + + records = monid.extract_records(answer) + if not records: + return {"pending": False, "runId": run_id, "cost": cost, + "costEstimated": estimated, "asins": asins, + "records": 0, "tableKey": "", + "message": "Monid returned no review records for those ASINs. The run is " + "recorded in the spend ledger."} + + # ⛔ THE TWO DOORS, IMPORTED WHERE THEY ARE USED. A top-level import would run + # `routes_tables` while `routes_connectors` is still importing THIS module, and a cycle at + # boot is an ImportError with a traceback that names neither cause. `routes_tables.py` uses + # exactly this local-import style itself (`from routes_grid import govern_date_recurrence`, + # inside `create_table`), so this is the file's own convention rather than a workaround. + from routes_tables import create_table, import_rows + + fields = monid.columns_from_rows(records) + # ⚠ THE DERIVED `type` IS A DISPLAY DECISION, NOT A STORAGE ONE, and that is the existing + # door's behaviour rather than this ticket's choice: `user_tables.add_rows` writes every cell + # as `str(v)` and drops any key the table has no column for. So an `int` column holds the + # string "12345" and sorts as the grid's own column type says, which is what every other + # imported database in this workspace already does. Recorded here because a reader who expects + # a typed cell will otherwise think the derivation lost the type. + rows = monid.rows_for_import(records, fields) + + existing = ut.all_defs(session.runtime) or {} + table_key = monid.TABLE_KEY + created = False + unmapped = [] + if table_key not in (existing or {}): + # ⚠ CALLED, NOT REIMPLEMENTED (C5). `create_table` slugifies the label, so + # "Amazon reviews" mints exactly `ut_amazon_reviews` the first time — and `_2` every time + # after, which is why this branch is guarded rather than run on every pull. + try: + made = create_table({"label": monid.TABLE_LABEL, "fields": fields}, session) + except HTTPException as exc: + raise exc + table_key = (made or {}).get("key") or "" + created = True + if not table_key: + raise err(503, "table_refused", + "The reviews arrived and the database could not be created. The run is " + "recorded in the spend ledger.") + else: + # ⛔ AN EXISTING TABLE KEEPS ITS COLUMNS. Adding one is a field door that lives in + # `routes_tables.py`, which belongs to another lane, so a key the first pull never saw is + # NAMED in the answer rather than dropped in silence. + have = {str(f.get("key")) for f in (existing[table_key].get("fields") or [])} + unmapped = sorted({f["key"] for f in fields} - have) + + try: + landed = import_rows(table_key, {"rows": rows}, session) + except HTTPException as exc: + raise exc + return {"pending": False, + "runId": run_id, + "cost": cost, + "costEstimated": estimated, + "asins": asins, + "records": len(records), + "imported": int((landed or {}).get("imported") or 0), + "tableKey": table_key, + "tableCreated": created, + "columns": [f["key"] for f in fields], + "unmappedColumns": unmapped, + "message": "The reviews landed in " + monid.TABLE_LABEL + "."} diff --git a/api/routes_query.py b/api/routes_query.py index 182a15c06d88a25fa81c7f5ff06da4179416e581..e0a94199aa848551e6702d880d2e3475c1d3ff44 100644 --- a/api/routes_query.py +++ b/api/routes_query.py @@ -1451,6 +1451,47 @@ def _semantic_authorize(session, database, *, require_answerable=False): return status +def _semantic_authorize_schema_only(session, database): + """The RECORD wall, widened for a door that reads no record. W49-T22 / D-276. + + ⛔⛔ THIS IS A SEPARATE FUNCTION ON PURPOSE, AND IT MUST STAY ONE. `_semantic_authorize` is + the wall every record-reading door keeps and nothing here may soften it: `_semantic_records`, + `profile_semantic_field`, `query_tool` and every `require_answerable=True` caller go on + calling that one. Naming this path separately is what stops a later reader from taking the + widening for the record boundary. + + ⭐ WHAT IT WIDENS, AND WHY THAT IS HONEST. MEASURED on tenant #0: an ADMIN asking + `GET /query/metrics?database=product_data` got 403 `assistant_forbidden` for a database the + same account opens from the nav. The cause is D-276 and is still open — + `deps.assistant_source_status` sets `permitted=False` when `perm_scope.assistant_entry` finds + no `entry()` dict, even for a caller whose `may_access` is True. That branch already + computes the honest second fact beside it, `visible`, described in its own comment as true + "only when the ordinary product wall already lets them open it, i.e. when the silence was + incoherent rather than protective". + + ⛔ SO `permitted` IS NOT TOUCHED. Widening it would resurrect stored artefacts the read + boundary refuses. This door returns metric NAMES and nothing else — it discloses the shape of + a database the caller can already open, never a value from inside it, which is the rule + `semantic_catalog` states for itself ("An empty field selection is a schema-only authorization + check and never widens to records"). It admits exactly the incoherent case and nothing else: + a caller with neither `permitted` nor `visible` still gets the same 403. + + ⚠ EXACTLY ONE DOOR CALLS THIS, AND THAT IS DELIBERATE, NOT AN OVERSIGHT. `GET /query/metrics` + is the surface W49-T22's contract (C7) names, and it is the whole of this function's warrant. + `GET /query/semantics/{database}` is schema-only by the same argument and keeps the STRICT + wall, so the same admin can get 200 from the catalogue and 403 from the field contract on one + database. That asymmetry is real and is booked as a follow-up rather than closed here: the + field contract carries per-field `purpose`, `synonyms` and `sensitivity`, which is a wider + disclosure than a list of metric names, and widening it needs its own ruling. ⛔ Do not + "finish the job" by adding call sites without one. + """ + status = assistant_source_status(session, [database]).get(database) or {} + if not (status.get("permitted") or status.get("visible")): + raise err(403, "assistant_forbidden", + "your current permissions do not allow this database") + return status + + @router.get("/query/semantics/{database}") def semantic_catalog(database: str, session: Session = Depends(require_session)): # Permission is resolved by the same source boundary Query uses. An empty field selection is @@ -1599,15 +1640,40 @@ def _metric_dtos(offer, catalog): return out -def _compatible_metric_dtos(session, database): +#: ⭐⭐ W49-T22 / CONTRACT C7 — THE THREE CAUSES AN EMPTY CATALOGUE CAN HAVE, and they are a +#: CLOSED SET so the picker never has to guess which sentence is true. Declared here, next to the +#: only code that can distinguish them, rather than in the client: the browser can see that the +#: list is empty and cannot see WHY. +#: +#: ⛔ A FOURTH CAUSE EXISTS AND IS DELIBERATELY NOT IN THIS SET. The panel also falls idle when +#: the row set is empty (`!pids.length`), which is neither of these three; stretching one of these +#: sentences over it would print a false statement on a database that has a topic and a filled +#: catalogue. It is reported as a contract gap instead. +METRIC_CATALOGUE_REASONS = ("no_metrics", "refused", "no_topic") + + +def _metric_catalogue(session, database): + """`(metrics, reason)` for one database. `reason` is "" when something was offered. + + ⛔ THE REASON IS COMPUTED WHERE THE REFUSAL HAPPENS. Each branch below is the ONLY place its + cause is knowable: the metrics capability lives in `perm_scope`, the topic binding lives in + `semantic.topic_for_grid`, and an empty offer is `entity_measures` refusing every declared + key for its own stated reasons (`entity_measure_refusals` carries those). A client that saw + only `[]` would have to invent one of the three, and two of the three would be a lie. + """ from core import perm_scope if not perm_scope.may_metrics(session.user, database): - return [] + return [], "refused" from harness import semantic as sem topic = sem.topic_for_grid(database) if not topic: - return [] - return _metric_dtos(sem.entity_measures(topic), sem.metrics()) + return [], "no_topic" + metrics = _metric_dtos(sem.entity_measures(topic), sem.metrics()) + return metrics, ("" if metrics else "no_metrics") + + +def _compatible_metric_dtos(session, database): + return _metric_catalogue(session, database)[0] @router.get("/query/metrics") @@ -1615,9 +1681,22 @@ def query_metrics(database: str = "", session: Session = Depends(require_session database = str(database or "").strip() if not database: raise err(400, "bad_request", "a database is required") - _semantic_authorize(session, database) - _semantic_records(session, database) # The same governed semantic source wall as Query. - return {"metrics": _compatible_metric_dtos(session, database)} + # ⭐ SCHEMA-ONLY. This door returns metric NAMES and never a value, so it takes the widened + # wall (see `_semantic_authorize_schema_only` for exactly what that widens and what it does + # not). Before W49-T22 an admin asking about `product_data` got 403 here for a database the + # same account opens from the nav. + _semantic_authorize_schema_only(session, database) + metrics, reason = _metric_catalogue(session, database) + # ⛔⛔ THE GOVERNED SOURCE WALL STAYS, BUT IT CANNOT BE THE FIRST THING ASKED. + # `_semantic_records` resolves `_semantic_baseline`, which raises 404 `semantic_source_unknown` + # for a database no topic declares — and `ut_odoo_order_lines` / `ut_odoo_gl_lines` are exactly + # that: read-through grains with no entity topic. A 404 carries no body the picker can read, + # so the reader was told nothing at all where C7 promises a sentence. The wall is therefore + # asked only once a topic is known to exist, which is the only case where it has a contract to + # enforce; a topic-less database answers 200 with `reason: no_topic`, and that IS its answer. + if reason != "no_topic": + _semantic_records(session, database) + return {"metrics": metrics, "reason": reason} def _tool_spec(body, requested): diff --git a/api/routes_shares.py b/api/routes_shares.py index 9136a4f59f12d4e8568e0156cbb333044508bc4d..161ec7bf2d5f1e6de7c2d3e0a28a5a9ad0d74d9b 100644 --- a/api/routes_shares.py +++ b/api/routes_shares.py @@ -891,17 +891,31 @@ def get_share(kind: str, oid: str, session: Session = Depends(require_session)): def _people(tenant): """[{username, name}] for this tenant — same population as `assignable_people`, with the - BINDING identity alongside the display one.""" + BINDING identity alongside the display one. + + ⛔⛔ W49-T23 / D-235 — A BLANK TENANT RETURNS NOBODY, NOT EVERYBODY. This read + `if want and str(u.get('tenant') …) != want`, so a blank or `None` slug skipped the filter + entirely and handed one workspace every tenant's roster: the exact `if want and …` fail-OPEN + that W33-T37 closed in `core.users.assignable_people` / `avatar_map` one layer down, left + behind in the copy that lives here. The three callers all pass `session.tenant`, which is + `claims["t"]` and is already proven non-blank by `require_session` (an unresolvable slug is a + 401 before any route runs), so this changes no answer any live caller gets today — it removes + the shape, before a fourth caller arrives that does not carry that proof. Fail-closed, because + from this function a blank slug and "every tenant at once" are the same observation, and one + of the two callers below turns this roster into who may be GRANTED access. + """ try: reg = users.registry() or {} except Exception: return [] want = str(tenant or '').strip().lower() + if not want: + return [] out = [] for uname, u in reg.items(): if not isinstance(u, dict) or u.get('active') is False: continue - if want and str(u.get('tenant') or 'royal-imports').strip().lower() != want: + if str(u.get('tenant') or 'royal-imports').strip().lower() != want: continue out.append({"username": str(uname), "name": str(u.get('name') or uname)}) return sorted(out, key=lambda p: p["name"].lower()) diff --git a/api/routes_sheet.py b/api/routes_sheet.py new file mode 100644 index 0000000000000000000000000000000000000000..46c88d73332a86f27653147f2d16e95a449b21b9 --- /dev/null +++ b/api/routes_sheet.py @@ -0,0 +1,502 @@ +"""routes_sheet.py — the Sheet workbook doors (wave 49, instruction 1, ticket W49-T02). + +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. + +⭐ **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 +C2 and ruling R16. + +⛔⛔ **WHEN THAT WALL ARRIVES IT IS `routes_charts.py::_require_database`, COPIED, NEVER +`deps.Session.require`.** `Session.require` calls `nav_may_open(user, key)` with no `st=` argument, +so the `ut_*` leg of that predicate resolves against the PROCESS-DEFAULT tenant store instead of +this session's runtime. Measured on the running app, same user and same table: 403 with the process +default pointing elsewhere, 200 once it happened to match. D-612 is open at HEAD and lane C repairs +it; this file must not inherit it in the meantime. + +⛔ **THIS FILE IS MOUNTED BEFORE IT SERVES ITS FULL SURFACE, ON PURPOSE.** See the identical note in +`routes_charts.py` and `routes_notes.py`: five consecutive waves lost the `include_router` line, and +in a worktree-parallel wave that is structural rather than careless, because `main.py` lives in +exactly one lane's fence. The mount lands with the first ticket so no later ticket can reach BUILT +while its surface is a 404. + +⚠ Every message in this file 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. +""" + +from fastapi import APIRouter, Body, Depends, HTTPException + +from deps import Session, err, require_session + +router = APIRouter(prefix="/api/v1") + +#: What a door answers while the ticket that resolves it is still open. It is a REFUSAL with a +#: named code, not an empty success: a stub that answered `{"value": null}` would be indexed, +#: charted and believed, and nothing downstream could tell it from a real answer. +_NOT_YET = "sheet_resolution_not_built" + + +def _require_database(session: Session, database) -> str: + """THE per-database wall, COPIED from `routes_charts.py::_require_database` (contract C2). + + ⛔⛔ IT IS COPIED RATHER THAN `deps.Session.require`, AND THAT IS THE WHOLE POINT. + `Session.require` calls `nav_may_open(user, key)` with NO `st=` argument, so the `ut_*` leg of + that predicate resolves the table against the PROCESS-DEFAULT tenant store instead of THIS + session's runtime. Measured on the running app, same user and same table: 403 with the process + default pointing elsewhere, 200 once it happened to match. D-612 is open at HEAD and lane C + repairs it; until then every new door that passes a `ut_*` key must thread `st=session.runtime` + itself or inherit the bug. + + ⚠ It runs the SAME two legs as the nav rail, so it can only ever agree with what the caller is + already offered. It widens nothing. + """ + key = str(database or "").strip() + if not key: + raise err(400, "sheet_database_required", "That cell does not name a database.") + import core.perm_scope as perm_scope + if not perm_scope.nav_may_open(session.user, key, st=session.runtime): + raise err(403, "database_unreadable", f"You cannot read {key}.") + tcfg = getattr(session.runtime.tenant, "config", None) or {} + tmods = tcfg.get("modules", "all") + if tmods != "all" and key not in {str(k) for k in (tmods or [])}: + raise err(403, "database_unreadable", f"This workspace does not include {key}.") + return key + + +def _mirror(session: Session): + """`(cursor, spec, columns)` for one read-through database, or the refusal that names why. + + ⛔ THE TWO MIRROR FAILURES MEAN OPPOSITE ACTIONS AND ARE KEPT APART HERE, exactly as the rows + door keeps them apart. `DatastoreMismatch` means this process has ANOTHER TENANT'S FILE open; + it never becomes un-mis-pinned by waiting, so it is a 409 and never a retry. A plain + `RuntimeError` means the mirror is completing its first sync, so it is a 503 the caller may + retry. `DatastoreMismatch` SUBCLASSES `RuntimeError`, so the guard must run ABOVE the try, and + collapsing them would turn the loudest refusal in the system into a spinner. + """ + import routes_odoo_tables as rot + import odoo_relational as rel + + def _for(table_key): + fields = None + for _bucket, key, _label, mk_fields in rel.TABLES: + if key == table_key: + fields = mk_fields() + break + if fields is None: + raise err(404, "not_connected", f"{table_key} is not a connected Odoo database.") + try: + cur, mismatch = rot._mirror_cur(session) + except RuntimeError as exc: + raise err(503, "store_not_ready", str(exc)) + if mismatch: + raise err(409, "cross_tenant_store", mismatch) + spec = rot._source_for(cur, table_key) + if spec is None: + raise err(409, "not_read_through", + f"{table_key} is still served from its stored copy, so a cell cannot read " + "through to it on this deployment yet.") + return cur, spec, rot._filter_columns(spec, fields) + + return _for + + +def _view_filter(session: Session, database: str, view_id: str, view_name: str = ""): + """`(nodes, conj)` for a saved view's filter, or a `view_missing` refusal that NAMES it. + + ⛔⛔ `prefer_owner=session.uname` IS LOAD-BEARING AND OMITTING IT IS A SILENT CROSS-USER READ. + The system view id `all-customers` is pinned on every database, and every user who has ever + touched that view's config holds their OWN record under the same id, so a bare first-hit scan + answers whichever stratum the dict happens to yield first. Measured in the wave-48 go-live QA + (W48C-T02): starring `All products` wrote onto a COLLEAGUE's overlay record while the caller's + own rail never changed, with a 200 and nothing red. A bound cell that inherits that bug + computes somebody else's number and reports it as this person's. + + ⚠ The refusal names the view, which is why `clean_binding` keeps `view_name` on the binding: + once the record is deleted there is nothing left to look a name up from. + """ + from core import table_store + # ⚠ `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) + if not found: + raise err(409, "view_missing", f"View {view_name or view_id} no longer exists.") + _owner, view = found + import routes_odoo_tables as rot + return rot._fe().tree_parts((view or {}).get("filters")) + + +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 + return err(status, exc.code, exc.message) + + +def _store(session: Session): + return session.runtime + + +@router.get("/sheets") +def list_sheets(session: Session = Depends(require_session)): + """The workbook list, identity only. Cells never ride this door.""" + from core import sheets + return {"workbooks": sheets.list_workbooks(_store(session))} + + +@router.post("/sheets", status_code=201) +def create_sheet(body: dict = Body(default=None), session: Session = Depends(require_session)): + """Create a workbook with exactly one tab (R7).""" + from core import sheets + raw = dict(body or {}) + try: + book = sheets.create_workbook(_store(session), + name=raw.get("name") or "", + created_by=session.uname) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + return {"workbook": book} + + +@router.get("/sheets/{workbook_id}") +def read_sheet(workbook_id: str, session: Session = Depends(require_session)): + from core import sheets + try: + return {"workbook": sheets.get_workbook(_store(session), workbook_id)} + except sheets.SheetRefusal as exc: + raise _refuse(exc) + + +@router.put("/sheets/{workbook_id}") +def write_sheet(workbook_id: str, body: dict = Body(default=None), + session: Session = Depends(require_session)): + """Persist name and sheets in the C1 cell shape, bumping `rev`. + + ⚠ `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. + """ + from core import sheets + raw = dict(body or {}) + 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 + # how one of them ends up ignored. + book = sheets.put_workbook(_store(session), workbook_id, raw) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + return {"workbook": book} + + +@router.delete("/sheets/{workbook_id}") +def drop_sheet(workbook_id: str, session: Session = Depends(require_session)): + from core import sheets + try: + removed = sheets.delete_workbook(_store(session), workbook_id) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + return {"deleted": bool(removed)} + + +# ── 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 +# REFUSES with a named code until its ticket lands. W49-T04 replaces `preview`, `refresh` and +# `drill` with real resolution through the mirror seam; W49-T03 supplies formula evaluation. + + +@router.post("/sheets/{workbook_id}/refresh") +def refresh_sheet(workbook_id: str, session: Session = Depends(require_session)): + """R10: recompute every bound cell, then every formula, and restamp `refreshed_at`. + + ⭐ THE WALL RUNS PER DISTINCT DATABASE, ON OPEN, NOT ONLY PER CELL (R16). A workbook that binds + forty cells to one database asks once; a reader who has lost access to that database gets a + refusal on every one of its cells rather than a stale number quietly repainting. + + ⚠ 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. + """ + from core import sheets + from modules import sheet as sheet_mod + import formula_runtime as fr + + try: + book = sheets.get_workbook(_store(session), workbook_id) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + + stamp = _now_iso() + seen_db = {} + for tab in book.get("sheets") or (): + for addr, cell in (tab.get("cells") or {}).items(): + if not isinstance(cell, dict) or cell.get("kind") != "bound": + continue + 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}."} + 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) + + _recompute_formulas(book, fr, sheet_mod) + 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} + + +def _now_iso(): + from datetime import datetime, timezone + return datetime.now(timezone.utc).replace(microsecond=0).isoformat() + + +def _recompute_formulas(book, fr, sheet_mod): + """Re-evaluate every formula cell across the workbook, per tab, in dependency order. + + ⛔ 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(): + if not isinstance(cell, dict): + continue + if cell.get("kind") == "formula" and cell.get("formula"): + spec[addr] = {"formula": cell["formula"]} + 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"} + 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(): + if not isinstance(cell, dict) or cell.get("kind") != "formula": + continue + code = (out.get("errors") or {}).get(addr) + 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["display"] = "" if cell["value"] is None else str(cell["value"]) + cell.pop("refusal", None) + + +def _formula_message(code, subject=""): + """The sentence a refused formula wears. + + ⭐ AN INHERITED REFUSAL KEEPS ITS OWN WORDS (C2, R16). When a formula inherits + `database_unreadable` from an input, the reader is told the CAUSE - a database they cannot read + - rather than a generic "this could not be calculated", which would send them looking at the + formula instead of at their access. So C2's vocabulary is answered here by the same sentences + `modules/sheet.py::REFUSALS` uses, and only the formula-specific codes get their own. + """ + from modules.sheet import REFUSALS + if code in REFUSALS: + return REFUSALS[code].format(subject=subject or "that database") + return { + "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.", + "div_zero": "This formula divides by zero.", + }.get(code, "This formula could not be calculated.") + + +def _resolve_binding(session: Session, raw_binding, *, today=None): + """Evaluate ONE C2 binding and return `{value, limits, sql_columns}`. + + The order below is the contract, not a preference: + 1. the per-database wall, per DISTINCT database, on every read (R16); + 2. the mirror cursor, whose two failures mean opposite things; + 3. the ROW wall, fail-closed, refusing 409 when it names a column the mirror cannot answer; + 4. the binding's own scope, whose unanswerable columns are REPORTED rather than dropped. + """ + from modules import sheet as sheet_mod + import core.perm_scope as perm_scope + + try: + binding = sheet_mod.clean_binding(raw_binding) + except sheet_mod.SheetRefusal as exc: + raise err(400, exc.code, exc.message) + + database = _require_database(session, binding["database"]) + cur, spec, cols = _mirror(session)(database) + + # ── the ROW wall, fail-closed ──────────────────────────────────────────────────────────── + wall_tree = ((perm_scope.entry(session.user, database) or {}).get("filter") + if perm_scope.row_scope_applies(session.user, database) else None) + wall_nodes, wall_conj = _fe_parts(wall_tree) + if wall_nodes: + unknown = sorted(sheet_mod.filter_columns_named(wall_nodes) - set(cols)) + if unknown: + # ⛔ 409, NOT a silently unapplied wall. A restriction that cannot be compiled here + # must stop the read; serving the number without it would hand a scoped reader the + # whole database and look exactly like success. + raise err(409, "scope_not_applicable", + "an administrator restricted your view of this database using " + + ", ".join(unknown) + + ", and that column cannot be read on this database's live connection, so " + "the restriction cannot be applied here. Ask an administrator to restrict " + "you on a column this database carries") + + # ── the binding's own scope ────────────────────────────────────────────────────────────── + scope = binding["scope"] + if scope.get("view_id"): + scope_nodes, scope_conj = _view_filter(session, database, scope["view_id"], + scope.get("view_name", "")) + else: + scope_nodes, scope_conj = _fe_parts(scope.get("filter")) + + # ⚠ NOTHING IS DONE HERE ABOUT `needs_excluded`. `_source_for` has already resolved it into the + # spec's column expressions; applying it a second time would double-count the exclusion and + # break every joined spec, whose partner column is `sol.order_partner_id` or `aml.partner_id`. + try: + sql, params, limits = sheet_mod.build_aggregate_query( + spec, binding, cols, scope_nodes=scope_nodes, scope_conj=scope_conj, + wall_nodes=wall_nodes, wall_conj=wall_conj, today=today) + except sheet_mod.SheetRefusal as exc: + raise err(400, exc.code, exc.message) + + row = cur.execute(sql, params).fetchone() + value = row[0] if row else None + return {"value": value, "limits": limits, "database": database, "binding": binding} + + +def _fe_parts(tree): + """`(nodes, conj)` for a stored `{conj, nodes}` filter, through the ONE reader of that shape.""" + from modules import sheet as sheet_mod + return sheet_mod.stored_tree_parts(tree) + + +@router.post("/sheets/{workbook_id}/cells/{addr}/preview") +def preview_cell(workbook_id: str, addr: str, body: dict = Body(default=None), + session: Session = Depends(require_session)): + """Evaluate a C2 binding WITHOUT saving it (contract C1). + + ⭐ It takes the binding from the BODY rather than from the stored cell, which is what lets the + binding editor show a number before anyone commits to it, and what lets this door be exercised + on a tenant whose store is read-only. + """ + raw = dict(body or {}) + out = _resolve_binding(session, raw.get("binding")) + return {"value": out["value"], "display": "" if out["value"] is None else str(out["value"]), + "limits": out["limits"]} + + +@router.get("/sheets/{workbook_id}/cells/{addr}/drill") +def drill_cell(workbook_id: str, addr: str, session: Session = Depends(require_session)): + """`{database, view_id?, filter?, record_ids, count}` for `LinkGridModal` (R6, R13, R17). + + ⛔ A FORMULA CELL REFUSES BY NAME AND DOES NOT DRILL TO ONE OPERAND (R17). Picking an input + would be a guess presented as an answer: `=B4-B8` has two, and neither is what the person + clicked on. + + ⭐ THE IDS ARE READ LIVE, NOT TAKEN FROM THE CELL (R13). A stale cell opens the same popup with + no comparison text, and the count beside those ids is the LIVE count, because `LinkGridModal` + prints the length of what it is handed and runs no query of its own. + """ + from core import sheets + from modules import sheet as sheet_mod + import core.perm_scope as perm_scope + + try: + book = sheets.get_workbook(_store(session), workbook_id) + except sheets.SheetRefusal as exc: + raise _refuse(exc) + + key = str(addr or "").replace("$", "").upper() + cell = None + for tab in book.get("sheets") or (): + if key in (tab.get("cells") or {}): + cell = tab["cells"][key] + break + if not isinstance(cell, dict): + raise err(404, "cell_missing", f"Cell {key} is not filled in.") + if cell.get("kind") == "formula": + raise err(409, "formula_no_drill", + "A formula cell cannot drill; view one of its inputs.") + if cell.get("kind") != "bound": + raise err(409, "literal_no_drill", + "A hand typed value has no rows behind it.") + + try: + binding = sheet_mod.clean_binding(cell.get("binding")) + except sheet_mod.SheetRefusal as exc: + raise err(400, exc.code, exc.message) + + database = _require_database(session, binding["database"]) + cur, spec, cols = _mirror(session)(database) + + wall_tree = ((perm_scope.entry(session.user, database) or {}).get("filter") + if perm_scope.row_scope_applies(session.user, database) else None) + wall_nodes, wall_conj = _fe_parts(wall_tree) + + scope = binding["scope"] + if scope.get("view_id"): + scope_nodes, scope_conj = _view_filter(session, database, scope["view_id"], + scope.get("view_name", "")) + else: + scope_nodes, scope_conj = _fe_parts(scope.get("filter")) + + count_sql, count_params, limits = sheet_mod.build_aggregate_query( + spec, {"aggregate": {"fn": "count"}}, cols, scope_nodes=scope_nodes, + scope_conj=scope_conj, wall_nodes=wall_nodes, wall_conj=wall_conj) + total = (cur.execute(count_sql, count_params).fetchone() or [0])[0] + + ids_sql, ids_params, _ = sheet_mod.build_ids_query( + spec, cols, scope_nodes=scope_nodes, scope_conj=scope_conj, + wall_nodes=wall_nodes, wall_conj=wall_conj) + record_ids = [int(r[0]) for r in cur.execute(ids_sql, ids_params).fetchall() if r and r[0]] + + out = {"database": database, "record_ids": record_ids, "count": int(total or 0), + "limits": limits} + if scope.get("view_id"): + out["view_id"] = scope["view_id"] + else: + out["filter"] = scope.get("filter") + return out diff --git a/platform/aios_grid_fields.json b/platform/aios_grid_fields.json index e981986896326f24c2d9921b85e1d22bbe41fde2..1e8957c1ae82bb852a9abcc376000663474ca9e0 100644 --- a/platform/aios_grid_fields.json +++ b/platform/aios_grid_fields.json @@ -18,7 +18,7 @@ "source": "odoo", "derived": true, "default": false, - "description": "The Odoo res.partner id — the key every Odoo document joins on. DERIVED: this row's pid IS the partner id, so a stored copy would be a second source." + "description": "The Odoo res.partner id, the key every Odoo document joins on. DERIVED: this row's pid IS the partner id, so a stored copy would be a second source." }, { "key": "odoo_status", @@ -59,7 +59,7 @@ "type": "select", "source": "odoo", "default": false, - "description": "Who keyed in most of this customer's orders — not the Agent, who owns the account." + "description": "Who keyed in most of this customer's orders. Not the Agent, who owns the account." }, { "key": "street", @@ -148,7 +148,7 @@ "type": "select", "source": "odoo", "default": false, - "description": "Payment terms on this customer's account — Net 30, for example." + "description": "Payment terms on this customer's account. Net 30, for example." }, { "key": "last_order", @@ -192,7 +192,7 @@ "type": "currency", "source": "odoo", "default": false, - "description": "Invoiced money past due — same basis as the Collections page." + "description": "Invoiced money past due, on the same basis as the Collections page." }, { "_note": "wave 21 R1 — the TOTAL, added beside the rename above. AR current $ + AR overdue $, i.e. what most people mean by 'open AR'. Composed from the same ar.credit_exposure rows the siblings use, so it is transitively reconciled by ar.validate()'s residual read_group tie — no second oracle.", @@ -329,7 +329,7 @@ "source": "odoo", "pinned": true, "default": true, - "description": "The SKU code — the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer." + "description": "The SKU code, the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer." }, { "key": "product_id", @@ -611,7 +611,7 @@ "label": "Revenue LY", "type": "currency", "source": "odoo", - "description": "Same period last year — seasonal wholesale compares like for like." + "description": "Same period last year, because seasonal wholesale compares like for like." }, { "key": "yoy_pct", @@ -639,7 +639,14 @@ "label": "On hand", "type": "int", "source": "odoo", - "description": "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide." + "description": "Units in stock. Consolidated: one physical warehouse, not brand-tagged, so every caller sees the same company-wide figure, a BU-scoped one included." + }, + { + "key": "fba", + "label": "FBA", + "type": "int", + "source": "odoo", + "description": "Units held in the Amazon FBA warehouse, read live from Odoo under that warehouse's own context. These units are already counted in On hand; this column says how many of them sit at Amazon. Warehouse wide and never a business unit allocation, and blank rather than zero when the tenant has no FBA warehouse." }, { "key": "unit_cost", diff --git a/platform/core/connector_directory.py b/platform/core/connector_directory.py new file mode 100644 index 0000000000000000000000000000000000000000..317f09ff681372da6d93dd94ddd2d6bf58f2b144 --- /dev/null +++ b/platform/core/connector_directory.py @@ -0,0 +1,464 @@ +"""THE CONNECTOR DIRECTORY'S TAXONOMY (W49-T18, ruling R27, contract C4). + +⭐⭐ WHAT R27 ASKED FOR, verbatim: *"don't skip Odoo or meta ads, its important to learn how they +map the schema for our own benefit."* So this module imports the FULL Monid tool catalogue as our +directory's taxonomy, files OUR OWN connectors into the same 14 categories, and keeps the four +overlapping providers (Facebook, Instagram, TikTok, Amazon) beside ours, distinguished only by a +label nothing renders. + +⛔⛔ THE CROSSWALK BELOW IS AUTHORED AND IT CANNOT BE GENERATED. That is the centre of the ticket +and the reason for this paragraph: the next reader WILL go looking for the script that produced +it, and there is nothing to find. Measured against the live Monid API on 2026-09-02: + + · `POST /v1/discover` returns results whose `tags` are VERIFICATION BADGES: `["verified"]` or + `[]`. Nothing else. `tags` is not the category taxonomy, whatever the PRD's finding F-T says. + · `POST /v1/inspect` returns `categories: ["amazon", "apify"]` for the Amazon reviews scraper, + i.e. PROVIDER-LEVEL SLUGS, not the 14 sidebar categories. Its whole top-level key set is + `provider, providerName, endpoint, description, summary, method, input, price, docUrl, notes, + tags, categories, metrics, hints`, and none of those carries a sidebar name. + + So the 14 categories are reachable only from Monid's WEB UI SIDEBAR, which is what + `.claude/wiki/waves/wave49/proto/monid-catalogue.md` captured by hand. `MONID_PROVIDERS` is + regenerated by re-reading that file, not by calling an endpoint. + +⚠ AND THE CATALOGUE IS A FLOOR, NOT A CENSUS. `discover` returns providers absent from the proto +capture (`mrscraper` came back twice in eight results), because the proto list is the SIDEBAR's +and the sidebar is not the whole set. Nothing in this module or on the screen it feeds claims to +be complete, and nothing should be made to. + +⭐ THE COUNT RULE, and it is the ticket's named trap. Categories OVERLAP: one provider carries +several, so `sum(endpoints)` over a category double counts and cannot be reconciled with anything. +A chip's number is therefore THE NUMBER OF CARDS CARRYING THAT CATEGORY, computed from the tag +lists in `chip_counts`, never a sum of endpoint counts. The endpoint count stays where it means +something: on the card, about one provider. + +⛔ `provider` IS SERVER-SIDE ONLY (C4). The row a contributor composes says whether it is `native` +or `monid`; `to_client_row` strips it before the route answers, and `verify_catalog.py` reads the +CLIENT-facing payload to prove the key is gone. The label exists so we can reason about where a +row came from, and R27's design rule is that it never renders: no badge, no tooltip, nothing. + +⛔ THIS MODULE IS PURE. No I/O, no network, no runtime, no store. It is data plus four small +functions, which is what lets a gate drive it with no FastAPI app and no session. +""" +from __future__ import annotations + +import re + +#: ⭐ MONID'S SIDEBAR, VERBATIM AND IN ITS ORDER, INCLUDING `All`. The proto capture lists `All` +#: as a sidebar row with a count of its own (1831), so it is one of the fourteen rather than a +#: control we invented; it is simply the one that selects everything. `TAG_CATEGORIES` below is +#: the thirteen a provider can actually be filed under. +#: +#: ⚠ THESE ARE PROPER NOUNS AS MONID WRITES THEM and they reach a screen, so they are neither +#: re-cased nor re-spelled. "Search & SEO", "Crypto & DeFi", "E-commerce" and "AI" are names, not +#: chrome, and DESIGN.md's no-ALL-CAPS rule is about chrome. +ALL = "All" +CATEGORIES = ( + ALL, + "Social Media", + "Lead Gen", + "Search & SEO", + "News", + "E-commerce", + "Crypto & DeFi", + "Finance", + "AI", + "Phone & Messaging", + "Web Tools", + "Data", + "Utilities", + "Scrapers", +) + +#: The thirteen a row can be tagged with. `All` is the everything chip and tags nothing. +TAG_CATEGORIES = tuple(c for c in CATEGORIES if c != ALL) + +#: ⚠ PROVENANCE ONLY, AND DELIBERATELY NOT ON A SCREEN. These are MONID's own endpoint totals per +#: sidebar category, copied from the proto capture. They sum to 2,894 against a stated total of +#: 1,831, which is the overlap made arithmetic and the clearest possible statement of why a chip +#: must not add endpoint counts up. Kept so a future reader can re-check the capture against the +#: sidebar without re-reading the sidebar. +MONID_CATEGORY_ENDPOINTS = { + "All": 1831, "Social Media": 957, "Lead Gen": 301, "Search & SEO": 68, "News": 26, + "E-commerce": 20, "Crypto & DeFi": 293, "Finance": 70, "AI": 58, "Phone & Messaging": 14, + "Web Tools": 34, "Data": 79, "Utilities": 6, "Scrapers": 968, +} + +#: ⭐⭐ THE AUTHORED CROSSWALK: (provider name, endpoint count, the categories it is filed under). +#: +#: REGENERATION, because there is no generator: re-read the `PROVIDERS` line of +#: `.claude/wiki/waves/wave49/proto/monid-catalogue.md`, which is `name count` pairs separated by +#: the middle dot. The NAME and the COUNT come from there unchanged and `verify_catalog.py` proves +#: it, pair by pair, so a typo here goes red rather than quiet. The CATEGORIES are the authored +#: half: a judgement about which sidebar rows a provider sits under, made once, here. +#: +#: ⚠ THE FOUR OVERLAPS ARE IN THIS LIST ON PURPOSE (R27). Facebook, Instagram, TikTok and Amazon +#: all have a native counterpart of ours, and both cards ship. A directory that hid the catalogue +#: entry because we already scrape that platform would be answering a question nobody asked: the +#: two rows describe different things we can reach, and only the hidden label says which is which. +MONID_PROVIDERS = ( + ("3D Generation", 4, ("AI",)), + ("AAA Gas Prices", 12, ("Data",)), + ("AccuWeather", 3, ("Data",)), + ("Agentic Phone", 12, ("Phone & Messaging", "AI")), + ("Ahrefs", 36, ("Search & SEO",)), + ("Akta", 6, ("Crypto & DeFi",)), + ("Alibaba", 10, ("E-commerce", "Scrapers")), + ("Amazon", 5, ("E-commerce", "Scrapers")), + ("Apify", 44, ("Scrapers", "Web Tools")), + ("Apollo", 8, ("Lead Gen",)), + ("Artificial Analysis", 9, ("AI", "Data")), + ("Audio Tools", 2, ("AI", "Utilities")), + ("Automotive", 45, ("Data", "Scrapers")), + ("Bid.Cars", 10, ("Data", "Scrapers")), + ("Bilibili", 42, ("Social Media", "Scrapers")), + ("BlockRun", 55, ("Crypto & DeFi",)), + ("Browser Automation", 8, ("Web Tools", "Scrapers")), + ("Browserbase", 8, ("Web Tools", "Scrapers")), + ("Built In", 3, ("Lead Gen", "Data")), + ("ByteDance", 4, ("Social Media", "AI")), + ("Capterra", 5, ("Lead Gen", "Data")), + ("Carfax", 11, ("Data", "Scrapers")), + ("Cars.com", 3, ("Data", "Scrapers")), + ("Clay", 10, ("Lead Gen",)), + ("Clutch", 6, ("Lead Gen", "Data")), + ("Company Search & Enrichment", 199, ("Lead Gen", "Data")), + ("Company News", 4, ("News", "Lead Gen")), + ("Company Reviews", 17, ("Lead Gen", "Data")), + ("Compensation", 8, ("Data", "Lead Gen")), + ("Context.dev", 21, ("AI", "Data")), + ("Market Signals", 7, ("Finance", "Data")), + ("DeFi", 93, ("Crypto & DeFi",)), + ("DefiLlama", 127, ("Crypto & DeFi", "Data")), + ("Derivatives & Perps", 21, ("Crypto & DeFi", "Finance")), + ("Douyin", 315, ("Social Media", "Scrapers")), + ("Edmunds", 3, ("Data", "Scrapers")), + ("ElevenLabs", 9, ("AI", "Phone & Messaging")), + ("Embeddings", 1, ("AI",)), + ("Stocks & Funds", 54, ("Finance",)), + ("Exa", 2, ("Search & SEO", "AI")), + ("Facebook", 6, ("Social Media", "Scrapers")), + ("Finviz", 5, ("Finance", "Data")), + ("Funding & Investors", 7, ("Finance", "Lead Gen")), + ("G2", 6, ("Lead Gen", "Data")), + ("GetApp", 11, ("Lead Gen", "Data")), + ("Gloria", 5, ("News",)), + ("Google Shopping", 2, ("E-commerce", "Search & SEO")), + ("Homes.com", 5, ("Data", "Scrapers")), + ("Hunter", 13, ("Lead Gen",)), + ("Idealist", 9, ("Lead Gen", "Data")), + ("Image Generation", 5, ("AI",)), + ("Indeed", 5, ("Lead Gen", "Data")), + ("Insider & Institutional", 16, ("Finance",)), + ("Instagram", 61, ("Social Media", "Scrapers")), + ("IQAir", 4, ("Data",)), + ("Jobs", 36, ("Lead Gen", "Data")), + ("Kelley Blue Book", 6, ("Data", "Scrapers")), + ("Kuaishou", 38, ("Social Media", "Scrapers")), + ("Lemon8", 16, ("Social Media", "Scrapers")), + ("Levels.fyi", 8, ("Data", "Lead Gen")), + ("LinkedIn", 16, ("Social Media", "Lead Gen")), + ("LMArena", 13, ("AI", "Data")), + ("LoopNet", 4, ("Data", "Scrapers")), + ("Maps & Places", 2, ("Data", "Search & SEO")), + ("MarketBeat", 14, ("Finance",)), + ("MiniMax", 5, ("AI",)), + ("Model Benchmarks", 22, ("AI", "Data")), + ("Music Generation", 2, ("AI",)), + ("Nasdaq", 20, ("Finance",)), + ("News Search", 17, ("News", "Search & SEO")), + ("Octen", 4, ("Web Tools",)), + ("On-chain Data", 83, ("Crypto & DeFi", "Data")), + ("People Data Labs", 4, ("Lead Gen", "Data")), + ("People Search & Enrichment", 25, ("Lead Gen", "Data")), + ("PiPiXia", 17, ("Social Media", "Scrapers")), + ("Prediction Markets", 24, ("Crypto & DeFi", "Finance")), + ("QuickNode (x402)", 2, ("Crypto & DeFi",)), + ("Real Estate", 17, ("Data", "Scrapers")), + ("Reddit", 27, ("Social Media", "Scrapers")), + ("Saperly", 14, ("Lead Gen",)), + ("SECForm4", 11, ("Finance", "Data")), + ("SEO", 36, ("Search & SEO",)), + ("Simple FS", 6, ("Utilities",)), + ("SMS", 2, ("Phone & Messaging",)), + ("Snapchat", 2, ("Social Media", "Scrapers")), + ("Software Reviews", 22, ("Lead Gen", "Data")), + ("Speech & Voice", 7, ("AI", "Phone & Messaging")), + ("Stablecoins", 7, ("Crypto & DeFi",)), + ("StockAnalysis", 7, ("Finance",)), + ("Strale", 160, ("Social Media", "Scrapers")), + ("Surf", 105, ("Web Tools", "Scrapers")), + ("Suzanne", 4, ("AI",)), + ("Telegram", 7, ("Social Media", "Phone & Messaging")), + ("Threads", 11, ("Social Media", "Scrapers")), + ("TikHub", 924, ("Social Media", "Scrapers")), + ("TikTok", 155, ("Social Media", "Scrapers")), + ("TikTok Shop", 13, ("E-commerce", "Social Media")), + ("TinyFish", 2, ("Web Tools", "Scrapers")), + ("Token Prices", 22, ("Crypto & DeFi", "Finance")), + ("Toutiao", 7, ("News", "Social Media")), + ("Trustpilot", 7, ("Lead Gen", "Data")), + ("Video Generation", 12, ("AI",)), + ("Weather", 17, ("Data",)), + ("Weather Underground", 10, ("Data",)), + ("Content Extraction", 16, ("Web Tools", "Scrapers")), + ("Web Search", 6, ("Search & SEO", "Web Tools")), + ("Web3 Career", 9, ("Crypto & DeFi", "Lead Gen")), + ("WeChat", 23, ("Social Media", "Scrapers")), + ("Weibo", 67, ("Social Media", "Scrapers")), + ("Wellfound", 7, ("Lead Gen", "Data")), + ("X402 Atlas", 4, ("Crypto & DeFi",)), + ("Xiaohongshu", 45, ("Social Media", "Scrapers")), + ("Xigua", 7, ("Social Media", "Scrapers")), + ("Yahoo Finance", 5, ("Finance",)), + ("Yields", 14, ("Crypto & DeFi", "Finance")), + ("YouTube", 41, ("Social Media", "Scrapers")), + ("Zhihu", 41, ("Social Media", "Scrapers")), + ("Zillow", 8, ("Data", "Scrapers")), +) + +#: ⭐⭐ OUR OWN CONNECTORS, FILED INTO THE SAME FOURTEEN. R27's first clause is *"file our native +#: connectors into it"*, and the point of doing so is that one taxonomy covers both halves: a +#: reader looking for a way to reach commerce data finds Odoo and Shopify beside Alibaba, rather +#: than a catalogue on one side of the page and the things we actually built on the other. +#: +#: ⛔ THERE IS NO FALLBACK CATEGORY, DELIBERATELY. C4 says no native connector may be left +#: uncategorised; a default would satisfy that sentence while filing a new connector under a name +#: nobody chose, which is exactly the rot this directory exists to prevent. An unlisted key gets +#: NO category, appears only under `All`, and `verify_catalog.py` names it and goes red. +NATIVE_CATEGORIES = { + "odoo": ("Data", "Finance", "E-commerce"), + "webhooks": ("Utilities", "Web Tools"), + "scraper": ("Scrapers", "Social Media"), + "stripe": ("Finance", "E-commerce"), + "shopify": ("E-commerce", "Data"), + "meta_ads": ("Social Media", "Data"), + "slack": ("Phone & Messaging", "Utilities"), + "hubspot": ("Lead Gen", "Data"), + "quickbooks": ("Finance", "Data"), + "xero": ("Finance", "Data"), + "outlook": ("Phone & Messaging", "Utilities"), + # The OAuth registry's one slug. Hidden today (R6, D-45) and filed anyway: the blocker is + # money, not code, so the row comes back with a category already on it. + "google": ("Phone & Messaging", "Utilities"), + "google_sheets": ("Data", "Utilities"), + "google_drive": ("Data", "Utilities"), + "google_calendar": ("Utilities",), +} + +#: ⭐⭐ W49-T19 — THE CATALOGUE ROWS THAT ARE NOT A TO-DO LIST, AND TODAY THERE IS EXACTLY ONE. +#: +#: A key here names the DIRECT ACTION its card offers. `md_amazon` carries `amazon_reviews` +#: because Monid can pull Amazon reviews for this workspace right now: `core/monid.py` is written, +#: `POST /api/v1/monid/amazon-reviews/run` answers, one live run has been paid for, and the result +#: lands in a database. Leaving that row at `planned` said the opposite of what is true, and a +#: directory that describes a working integration as unbuilt is the same lie as one that offers a +#: door with nothing behind it, told backwards. +#: +#: ⛔ THIS MAP IS THE WHOLE PERMISSION TO BE INTERACTIVE, AND IT IS DELIBERATELY ALMOST EMPTY. The +#: other 117 rows have nothing behind them: no client, no route, no detail composer. They wear +#: `CATALOGUE_STATE` and their cards stay non-interactive, which is the rule R8 set and the lead +#: accepted. An entry added here without a route behind it is an affordance that cannot +#: work, and `verify_catalog.py` pins the count at one so the second one has to be argued for. +#: +#: ⚠ THE ACTION NAME IS THE CLIENT'S CONTRACT, not a display string. `ConnectorsPage.tsx` matches +#: on `amazon_reviews` to decide which card gets a button; both sides are read by the gate. +MONID_ACTIONS = { + "md_amazon": "amazon_reviews", +} + +#: The state a row with a direct action wears. `available` is already in the server's vocabulary +#: (`connected | available | reconnect | unconfigured | planned | catalogue`), already tinted by +#: `ConnectorsPage.stateTone`, and it means precisely what is true here: there is something you +#: can use. Inventing a fifteenth word would have made every reader of that vocabulary wrong. +#: +#: ⚠ IT DOES NOT CLAIM A KEY EXISTS. This module is pure and cannot know whether the workspace has +#: a Monid credential, so it does not say `unconfigured` either. Whether the caller may run, and +#: whether a key is stored, are answered by `GET /monid/amazon-reviews/meta` at the moment of use. +MONID_ACTION_STATE = "available" + +#: ⭐⭐ THE STATE A CATALOGUE LISTING WEARS, AND IT IS THE WHOLE OF THIS REPAIR. +#: +#: ⛔⛔ `planned` WAS ALREADY A WORD WITH A CONTRACT, AND T18 OVERLOADED IT. In this product a +#: PLANNED row means three things at once: it is a connector we intend to BUILD, it is enumerated +#: in `routes_connectors.PLANNED`, and it carries a `needs` naming what it is waiting on. That is +#: what makes it R8's visible to-do list, and `verify_automation` asserts all three — the served +#: planned set IS `PLANNED`, and every planned row has a `needs`. +#: +#: ⛔ A CATALOGUE LISTING IS NONE OF THOSE THINGS. It is not on our roadmap, nobody is waiting on +#: anything for it, and it has no `needs` to give. The 117 rows were handed `planned` only because +#: that state happened to render faded and non-interactive, which is a rendering fact borrowed to +#: carry a roadmap claim — and it made `verify_automation` read the whole Monid catalogue as our +#: to-do list. So the listing gets its OWN word and `planned` goes back to meaning what it meant. +#: +#: ⚠ THE FADE IS NOT THIS WORD'S JOB. `ConnectorsPage.ConnectorCard` no longer keys the faded, +#: `aria-disabled`, non-openable treatment on the literal `planned` — it keys on "this row has no +#: door", which both words satisfy. The card renders exactly as it did; only what it CLAIMS moved. +#: +#: ⛔ AND IT IS A SIXTH WORD IN THE SERVER'S STATE VOCABULARY (`connected | available | reconnect +#: | unconfigured | planned | catalogue`). `ConnectorsPage.stateTone` already answers an unknown +#: state with the neutral tone by construction (the wave-9 law: no client union over a server +#: vocabulary), so the client renders it without a change. Any gate holding a HAND-TYPED copy of +#: the five-word set has to learn the sixth. +CATALOGUE_STATE = "catalogue" + +#: ⭐⭐ W49-T14 · RULINGS R21 + R24 — WHICH CONNECTORS HAVE A FIELD CATALOGUE, AUTHORED IN CODE. +#: +#: ⭐⭐ R21, verbatim: *"the table list stays AUTHORED IN CODE; the screen DISCLOSES it, it does +#: not DERIVE it."* R24, verbatim: *"ONLY introspectable connectors get this screen. Scrapers, +#: Meta Ads and anything without a field catalogue keep today's connector card."* +#: +#: ⛔ THE ANSWER IS A DECLARATION, NEVER A PROBE. The tempting implementation is "introspectable +#: means `_detail_databases` came back non-empty", and that is precisely the confidently-wrong +#: shape the composer's own header was written about: an Odoo connection whose store read failed, +#: or whose grids are all switched off, returns the same empty list as Meta Ads — so the tab would +#: tell an administrator that Odoo has no schema on the one day the schema mattered. A connector +#: either publishes a field catalogue or it does not, and that fact is ours to state. +#: +#: ⛔ A CATALOGUE ROW IS NEVER IN HERE, and that is `CATALOGUE_STATE`'s whole point one paragraph +#: up: the 117 Monid listings have no client, no route and no detail composer, so there is nothing +#: behind them to introspect. Membership is by KEY, and every catalogue key wears +#: `MONID_KEY_PREFIX`, so the two sets cannot overlap by construction. +#: +#: ⚠ ONE ENTRY TODAY, AND ADDING A SECOND IS A REAL DECISION. A connector named here promises the +#: Databases tab a field catalogue AND a route that can enable one of its fields; without both, +#: the tab renders toggles that lead nowhere, which is R8's fake affordance. +INTROSPECTABLE_CONNECTORS = ("odoo",) + + +def is_introspectable(connector_key) -> bool: + """Does this connector publish a field catalogue the Databases tab can disclose (R24)? + + Pure and total: an unknown key is not introspectable, which is the fail-closed direction. + """ + return str(connector_key or "") in INTROSPECTABLE_CONNECTORS + + +#: ⛔ THE KEYS A ROW CARRIES FOR US AND NEVER FOR THE CLIENT (C4). One tuple, read by +#: `to_client_row` and by the gate's negative control, so "which keys are server-only" has one +#: answer wherever it is asked. +SERVER_ONLY_KEYS = ("provider",) + +#: The prefix every catalogue row's key wears. Internal, never on a screen, and it exists because +#: `Instagram` and `TikTok` are already directory keys of ours: two cards for two different things +#: must not collide, and `verify_meta` asserts no key appears twice in the served set. +MONID_KEY_PREFIX = "md_" + + +def slug(name: str) -> str: + """A provider name to its key fragment. Lowercase, and every run of non-alphanumerics + becomes one underscore, so `Bid.Cars` and `QuickNode (x402)` both land somewhere stable.""" + return re.sub(r"_+", "_", re.sub(r"[^a-z0-9]+", "_", str(name).lower())).strip("_") + + +def monid_rows(): + """The authored catalogue as directory rows. + + ⛔⛔ ALL BUT ONE ROW IS `catalogue`, AND IT USED TO BE `planned`, WHICH WAS THE DEFECT. The + first draft of this docstring argued that a catalogue entry IS a to-do item, and it was wrong + in the one way that matters: `planned` is not a look, it is a claim with a registry + (`routes_connectors.PLANNED`) and a `needs` behind it, and 117 listings we have never planned + to build were therefore served as our roadmap. `CATALOGUE_STATE` carries the argument in full. + + ⚠ THE CARD IS UNCHANGED. A catalogue row still has no detail route behind it, so it is still + faded, `aria-disabled` and not openable — the client keys that on the row having no door + rather than on the literal word `planned`, which is why the word could move at all. + + ⭐⭐ W49-T19 AMENDS THAT SENTENCE FOR EXACTLY THE ROWS IN `MONID_ACTIONS`, AND THE AMENDMENT + IS THE POINT OF THE TICKET. `md_amazon` is neither: Monid pulls Amazon reviews today, the + route behind it answers, and a real run has been paid for. So that row carries `action` and + the `available` state, and its card offers ONE named control ("Pull reviews") that opens the + run dialog IN PLACE. It is still not modal-openable, because the 404 above is still true: + `action` buys a button, never a door to a detail route that does not exist. + + ⚠ `action` IS ON EVERY ROW, EMPTY FOR 117 OF THEM, and that is deliberate. One shape means the + client asks `row.action === "amazon_reviews"` rather than probing for a key's presence, and it + means the gate can assert an ordinary row's answer is `""` rather than merely absent. An + absent key and an empty key read the same in JavaScript and differently in a test. + + ⚠ NO `desc`. DESIGN.md forbids over-explaining, and 118 invented sentences would be 118 + guesses about somebody else's product. The card carries the name, the category and the + endpoint count, all three of which are measured. + """ + rows = [] + for name, endpoints, cats in MONID_PROVIDERS: + key = MONID_KEY_PREFIX + slug(name) + action = MONID_ACTIONS.get(key, "") + rows.append({ + "key": key, + "label": name, + "kind": "catalogue", + "desc": "", + "state": MONID_ACTION_STATE if action else CATALOGUE_STATE, + "manage": "", + "endpoints": int(endpoints), + "category": cats[0], + "categories": list(cats), + # ⭐ THE DIRECT ACTION, AND IT CROSSES TO THE CLIENT (unlike `provider`). The card can + # only offer a control it is told about; a client-side list of which providers are + # special would be a second authority for one fact, in the layer least able to know. + "action": action, + # ⛔ SERVER-SIDE ONLY (C4). `to_client_row` removes it; nothing renders it. + "provider": "monid", + }) + return rows + + +def file_natives(rows): + """Tag every row already composed by `routes_connectors.directory` with its category. + + Mutates in place, because that is what the composer holds. A key with no entry in + `NATIVE_CATEGORIES` gets an EMPTY category rather than a guessed one: it still renders, under + `All` only, and the gate names it. + """ + for row in rows: + cats = NATIVE_CATEGORIES.get(str(row.get("key") or ""), ()) + row["categories"] = list(cats) + row["category"] = cats[0] if cats else "" + row["provider"] = "native" + return rows + + +def unfiled_native_keys(keys): + """The native connector keys nobody filed. The gate's subject, and it takes the key set from + the caller so that a gate can build it from the composer's own registries rather than from a + second list here (one question, one answer).""" + return sorted(k for k in keys if k not in NATIVE_CATEGORIES) + + +def chip_counts(rows): + """The filter rail: one entry per category, in `CATEGORIES` order, with what its chip shows. + + ⭐⭐ A CHIP'S NUMBER IS A COUNT OF CARDS, NOT A SUM OF ENDPOINTS, and that is the ticket's + named trap answered in one line of code. Categories overlap, so a provider carrying three of + them would contribute its endpoint total three times and the rail would add up to more + endpoints than Monid has. Counting cards also makes the number mean what a reader assumes it + means: press the chip and that many cards remain. + + `All` counts every row, which is the one place the number is both a card count and the whole + set. + """ + out = [] + for name in CATEGORIES: + if name == ALL: + out.append({"name": ALL, "count": len(rows)}) + continue + out.append({"name": name, + "count": sum(1 for r in rows if name in (r.get("categories") or []))}) + return out + + +def to_client_row(row): + """One row as the client is allowed to see it. + + ⛔ C4's NEGATIVE CONTROL LIVES ON THIS FUNCTION. `provider` says whether a row is ours or the + catalogue's, we reason with it on the server, and R27's design rule is that it never reaches a + screen in any form. Stripping it here rather than at each composer means there is ONE place to + read to know what the wire carries, and one place for the gate to break. + """ + return {k: v for k, v in row.items() if k not in SERVER_ONLY_KEYS} + + +def to_client_rows(rows): + """The whole served set, stripped. The route calls this and nothing else.""" + return [to_client_row(r) for r in rows] diff --git a/platform/core/dependents.py b/platform/core/dependents.py new file mode 100644 index 0000000000000000000000000000000000000000..fac771e19254ff547fd5d9f3561d2627651da995 --- /dev/null +++ b/platform/core/dependents.py @@ -0,0 +1,515 @@ +"""dependents.py — THE ONE REGISTRY THAT ANSWERS "what breaks if I remove this?" (wave 49, C3). + +⭐⭐ **OWNER RULING R23, verbatim:** *"Switching off a table that something depends on is REFUSED, +and the refusal NAMES the dependents ('3 views, 1 Route and 2 Sheet cells use this')."* +⭐⭐ **OWNER RULING R32, second half:** *"deleting a view must first disclose who it is shared to +and which Sheet cells depend on it."* + +Both rulings ask the same question of different targets, so there is ONE answer path here rather +than a bespoke pre-flight check per surface. A surface (the Databases tab's off switch, the view +delete dialog, a Sheet cell binding) calls `dependents(st, target)` and renders what comes back. + +CONTRACT C3, copied so it cannot drift: + + register(kind: str, fn) + dependents(st, target) -> list[Dependent] + target = {"kind": "table"|"view"|"field", "key": str, "database"?: str} + Dependent = {"kind": "view"|"route"|"link"|"rollup"|"grant"|"chart"|"sheet_cell", + "label": str, "count": int, "ids": list[str]} + +⛔⛔ **A ZERO-COUNT KIND IS OMITTED, NEVER REPORTED AS ZERO, AND THAT IS THE WHOLE POINT OF THE +REGISTRY BEING OPEN.** "used by 0 Routes" is noise; worse, it is a claim. `sheet_cell` is +registered by `platform/modules/sheet.py` AFTER the wave-49 lane merge (W49-T11, a declared +handover), so until that line lands this module has no opinion about Sheet cells at all — and +saying "0 Sheet cells" would be an assertion it cannot support. An unregistered kind is UNKNOWN, +not empty, and the only honest rendering of unknown is silence. + +⛔⛔ **A PROVIDER THAT RAISES OMITS ITS KIND. IT NEVER CONTRIBUTES A ZERO.** Same reason, arriving +by a different road: a store read that failed knows nothing, and "nothing" must not be spelled the +same way as "none". `dependents_report` hands the omitted kinds back to the caller as `errors` so +the omission is visible rather than swallowed. + +⛔ **LAYERING.** This file lives in `core/` and imports only `core/` siblings and stdlib, so +`modules -> core` still points one way. In particular it does NOT copy +`core/grid_events.py::_tops`, which reaches UP into `modules.customer_data` (tolerated wave-25 debt +carrying a tenant-#0-only fallback bug). `core.table_store.TableStore` is instantiated directly, +and the page-key -> workspace-bucket mapping comes from `core.view_templates.workspace_key`, which +is already the one place that mapping lives. + +⛔ **AND `TableStore.find_view` IS DELIBERATELY NOT USED HERE.** It calls +`migrate_legacy_shared_views()` first — a side-effecting read that WRITES the store and can raise +`LegacySharedViewMigrationError` on a malformed legacy record. A disclosure dialog is a GET; a GET +that migrates data, or 500s on data it only meant to describe, is a defect. The table document is +walked directly instead, exactly as the shape allows. + +⚠ **THE `'link'` KEY CARRIES TWO SHAPES AND THIS IS WHERE THAT BITES.** On a field of +`type == 'link'` it is a DICT (`{'table': ..., 'inverse': ...}`); on a rollup bag it is the bare +FIELD KEY (a string) of the link the rollup traverses. A rollup may also carry no `link` at all +(the `{'source': {...}}` shape, which joins through a topic dim). Every walker below branches on +`field['type']` first and on which key is present second. +""" +import core.chart_system as chart_system +import core.route_system as route_system +import core.shares as shares +import core.user_tables as user_tables +import core.view_templates as view_templates +from core.table_store import ASSIGNED_KEY, SHARED_KEY + +#: The reading order of a refusal sentence. `sheet_cell` is listed even though nothing in this +#: file registers it: the ORDER is a presentation fact and it must not depend on which lane +#: happened to register first (W49-T11 registers `sheet_cell` after the merge). +KIND_ORDER = ('view', 'route', 'link', 'rollup', 'grant', 'chart', 'sheet_cell') + +#: Singular / plural noun phrase per kind. ⛔ THE CASING IS R23's OWN — lowercase `views`, capital +#: `Route`, capital `Sheet cells` — because the ruling quotes the sentence the user reads. +_NOUNS = { + 'view': ('view', 'views'), + 'route': ('Route', 'Routes'), + 'link': ('Link field', 'Link fields'), + 'rollup': ('rollup', 'rollups'), + 'grant': ('share', 'shares'), + 'chart': ('chart', 'charts'), + 'sheet_cell': ('Sheet cell', 'Sheet cells'), +} + +_PROVIDERS = {} + + +def noun(kind, count): + """The noun phrase for `count` of `kind`, agreeing in number.""" + pair = _NOUNS.get(str(kind or '')) + if not pair: + base = str(kind or '').replace('_', ' ').strip() or 'dependent' + pair = (base, base + 's') + return pair[0] if int(count or 0) == 1 else pair[1] + + +def register(kind, fn): + """Register `fn(st, target) -> Dependent | list[Dependent] | None` for one dependent kind. + + ⚠ RE-REGISTERING A KIND REPLACES IT rather than adding a second answer to one question. The + combine session registers `sheet_cell` once; a module imported twice must not double-count. + + ⚠ THE RETURN SHAPE IS DELIBERATELY LOOSE (one dict, a list, or None). Lane A wrote + `modules/sheet.py::sheet_dependents` without ever seeing this file, so the seam accepts either + spelling instead of demanding the lanes agreed on something neither could read. + """ + key = str(kind or '').strip() + if not key or not callable(fn): + raise ValueError('dependents.register: a kind and a callable are both required') + _PROVIDERS[key] = fn + return key + + +def registered_kinds(): + """Every kind that currently has a provider, in `KIND_ORDER`.""" + known = [k for k in KIND_ORDER if k in _PROVIDERS] + return known + sorted(k for k in _PROVIDERS if k not in KIND_ORDER) + + +def clean_target(target): + """`{'kind', 'key', 'database'}` with kind restricted to the C3 vocabulary, else None.""" + target = target if isinstance(target, dict) else {} + kind = str(target.get('kind') or '').strip().lower() + key = str(target.get('key') or '').strip() + if kind not in ('table', 'view', 'field') or not key: + return None + database = str(target.get('database') or '').strip() + if kind == 'table' and not database: + database = key + return {'kind': kind, 'key': key, 'database': database} + + +def _dependent(kind, ids): + """A Dependent, or None when nothing depends. ⛔ NONE IS THE ZERO CASE — never `count: 0`.""" + seen, out = set(), [] + for raw in ids or (): + value = str(raw or '').strip() + if value and value not in seen: + seen.add(value) + out.append(value) + if not out: + return None + return {'kind': kind, 'label': noun(kind, len(out)), 'count': len(out), 'ids': out} + + +def dependents(st, target): + """Every registered kind that depends on `target`, in `KIND_ORDER`. C3's shape, exactly. + + Zero-count kinds are absent. A provider that RAISES is absent too — see the module note; use + `dependents_report` when the caller needs to know which kinds could not be answered. + """ + return dependents_report(st, target)['dependents'] + + +def dependents_report(st, target): + """`{'dependents': [...], 'errors': {kind: message}}` — `dependents()` plus what it could not + answer. The route returns `errors` so an unanswerable kind is visible rather than swallowed.""" + clean = clean_target(target) + if clean is None: + return {'dependents': [], 'errors': {}} + found, errors = [], {} + for kind in registered_kinds(): + try: + produced = _PROVIDERS[kind](st, dict(clean)) + except Exception as exc: # noqa: BLE001 — an unanswerable kind is omitted, never zeroed + errors[kind] = f'{type(exc).__name__}: {exc}' + continue + for item in (produced if isinstance(produced, (list, tuple)) else [produced]): + if not isinstance(item, dict): + continue + ids = item.get('ids') or [] + count = int(item.get('count') or len(ids) or 0) + if count <= 0: + continue + found.append({'kind': str(item.get('kind') or kind), + 'label': str(item.get('label') or noun(kind, count)), + 'count': count, + 'ids': [str(i) for i in ids]}) + order = {kind: index for index, kind in enumerate(KIND_ORDER)} + found.sort(key=lambda item: (order.get(item['kind'], len(order)), item['kind'])) + return {'dependents': found, 'errors': errors} + + +def refusal(label, found): + """R23's sentence: `"