Spaces:

fsanyoto
/

loopable

Running

@@ -1,591 +1,591 @@
-"""AI REVIEW — let a model decide which stage a card moves to (wave 23, owner ruling R4/R14).
-⭐ WHAT THIS IS. A review stage holds a record until somebody decides where it goes next. R4 made
-that somebody optionally a MODEL: the engine hands over the record's own values, the review's
-prompt, and the list of stages the review is allowed to send a card to, and gets back ONE of
-those stage labels plus a one-line reason. Every decision is written to the same `reviews` audit
-log a human click writes to, tagged `by: "ai"` with the provider and model that made it.
-⛔ FAIL-CLOSED IN EVERY DIRECTION, and this is the whole safety story. No key configured, a
-network failure, a slow answer, a malformed answer, or an answer naming a stage the review does
-not offer — all return `("", {...})`, and the caller leaves the card exactly where a human would
-have found it. The feature can be absent, broken or wrong and the worst outcome is a person doing
-the work. Nothing here can move a card somewhere the review does not already permit.
-⭐ CHEAP FIRST (owner R14, verbatim: *"Claude is a bit too expensive"*). The ladder is
-`groq → cerebras → openrouter → anthropic`; the first CONFIGURED provider wins, and Anthropic is
-last rather than absent — it is the quality backstop, not the default. `AIOS_AI_REVIEW_PROVIDER`
-pins one; `AIOS_AI_MODEL` overrides the model.
-⭐⭐ THE ANTHROPIC LEG IS ON THE OFFICIAL SDK NOW (D-346, W37-T39, 2026-08-19). ⛔ THIS PARAGRAPH
-USED TO ARGUE THE OPPOSITE and is rewritten rather than deleted, because a comment left asserting
-the reverse of its own code is [[two-gates-can-assert-opposite-things]] with no gate to catch it.
-The retired text said raw HTTP was *"a deliberate deviation … booked as a DEBT line so the
-integrator can overturn it deliberately rather than by drift"*. This is that overturn.
-Its two reasons were real and are both answered rather than waved away:
-  1. *"one SDK leg beside three hand-rolled ones is two implementations of the same call."* It is
-     not, because the leg does not live here: `providers.anthropic_send` owns the wire, prefers
-     the SDK, and normalises BOTH transports to one `(status, body)` pair. This file gained no
-     Anthropic knowledge — it lost some.
-  2. *"adding a pinned dependency rebuilds the container, a real deploy risk."* Still true, so the
-     import is LAZY and its absence is a FALLBACK, not a crash: with no `anthropic` package the
-     same raw POST runs and `LAST_ANTHROPIC_TRANSPORT` reports `'http'`. The pin is owed in BOTH
-     manifests ([[pin-deps-space-rebuilds]]) and is outside every worker fence this wave.
-⚠ The other three legs stay OpenAI-chat-shaped over `requests` — they have no shared SDK, and that
-half of the original reasoning never expired.
-The Messages shape below is the current one: `x-api-key` + `anthropic-version: 2023-06-01`, and
-`stop_reason: "refusal"` is checked BEFORE reading `content` — a refusal answers HTTP 200 with an
-empty content list, so code that indexes `content[0]` unconditionally breaks on it.
-"""
-from __future__ import annotations
-import json
-import os
-import re
-import requests
-#: The ladder. Order IS the policy (R14) — cheapest capable first, Anthropic last.
-PROVIDERS = [
-    # ⛔⛔ D-345, FIXED W37-T39 (2026-08-19). This read `llama-3.3-70b-versatile` and Groq RETIRED
-    # it: a real POST with the live key answers HTTP 404 `model_not_found`, and the id is absent
-    # from `GET /openai/v1/models`. ⚠ THE `openai/` PREFIX IS PART OF GROQ'S ID and is NOT a typo
-    # for the cerebras rung below, which serves the same family bare as `gpt-oss-120b`.
-    {"name": "groq", "env": "GROQ_API_KEY", "shape": "openai",
-     "url": "https://api.groq.com/openai/v1/chat/completions",
-     "model": "openai/gpt-oss-120b"},
-    {"name": "cerebras", "env": "CEREBRAS_API_KEY", "shape": "openai",
-     "url": "https://api.cerebras.ai/v1/chat/completions",
-     "model": "gpt-oss-120b"},
-    {"name": "openrouter", "env": "OPENROUTER_API_KEY", "shape": "openai",
-     "url": "https://openrouter.ai/api/v1/chat/completions",
-     "model": "openai/gpt-4o-mini"},
-    # ⚠ haiku-class DELIBERATELY, not the default Opus tier: R14 put Anthropic on this ladder as
-    # the backstop for a one-line classification, and this is the cheapest current Claude that
-    # does it well. A bigger model here would be spending the owner's money to pick between two
-    # labels it already has in front of it.
-    {"name": "anthropic", "env": "ANTHROPIC_API_KEY", "shape": "anthropic",
-     "url": "https://api.anthropic.com/v1/messages",
-     # ⚠ AN ENV LEVER, NOT A NEW DEFAULT (W36-T35): haiku stays the choice for the reasons above,
-     # and a deployment whose side rungs are out of credit can raise the tier without a release.
-     "model": os.environ.get("AIOS_AI_REVIEW_ANTHROPIC_MODEL") or "claude-haiku-4-5"},
-]
-ANTHROPIC_VERSION = "2023-06-01"
-TIMEOUT_SECONDS = float(os.environ.get("AIOS_AI_REVIEW_TIMEOUT") or 20)
-MAX_FIELD_CHARS = 200          # per value handed to the model
-MAX_FIELDS = 30                # columns handed to the model
-MAX_REASON = 200
-def ladder():
-    """The providers that are actually usable here, in order. Empty = the feature is off."""
-    pin = (os.environ.get("AIOS_AI_REVIEW_PROVIDER") or "").strip().lower()
-    live = [p for p in PROVIDERS if (os.environ.get(p["env"]) or "").strip()]
-    if pin:
-        live = [p for p in live if p["name"] == pin]
-    return live
-def configured():
-    return bool(ladder())
-def _record_text(row, fields):
-    """The record, as the model sees it. Values are truncated and the column set is bounded —
-    an automation table can carry a 32 KB JSON blob per row (C7) and a review decision does not
-    need it. Machine bookkeeping columns are dropped: a stage cell naming the stage the card is
-    sitting at would be the model reading its own question back."""
-    keys = [k for k in (fields or list((row or {}).keys()))
-            if not str(k).startswith("stage_")][:MAX_FIELDS]
-    lines = []
-    for k in keys:
-        v = (row or {}).get(k)
-        if v is None or str(v).strip() == "":
-            continue
-        lines.append(f"{k}: {str(v)[:MAX_FIELD_CHARS]}")
-    return "\n".join(lines) or "(this record has no filled-in values)"
-def _instruction(prompt, options, label):
-    return (
-        f"You are deciding what happens to one record waiting at a review step called "
-        f"{label!r} in a workflow.\n\n"
-        f"The person who built this workflow told you: {prompt}\n\n"
-        f"Choose EXACTLY ONE of these next steps, by its exact name:\n"
-        + "\n".join(f"- {o}" for o in options)
-        + "\n\nAnswer with one line of JSON and nothing else:\n"
-          '{"choice": "<one name from the list above>", "reason": "<one short sentence>"}\n'
-          "If the record does not give you enough to decide, answer "
-          '{"choice": "", "reason": "why not"} and a person will decide instead.'
-    )
-def _parse(text, options):
-    """The model's line → `(choice, reason)`. A choice that is not one of the offered stages is
-    DISCARDED, not fuzzy-matched: the offered list is a permission boundary, and a near-miss
-    resolved by string distance is how a card ends up somewhere nobody authorised."""
-    raw = str(text or "").strip()
-    obj = None
-    m = re.search(r"\{.*\}", raw, re.S)
-    if m:
-        try:
-            obj = json.loads(m.group(0))
-        except (ValueError, TypeError):
-            obj = None
-    if not isinstance(obj, dict):
-        return "", ""
-    choice = str(obj.get("choice") or "").strip()
-    reason = str(obj.get("reason") or "").strip()[:MAX_REASON]
-    for opt in options:
-        if choice.lower() == str(opt).lower():
-            return str(opt), reason           # the OFFERED spelling wins, never the model's
-    return "", reason
-# ⭐⭐ WAVE 35 · W35-T41 / C7 — THE TWO TRANSPORTS RETURN THE RESPONSE BODY'S `usage`.
-#
-# ⛔ THIS FILE'S OWN HEADER USED TO BE THE PRODUCT'S CONFESSION THAT NOTHING COUNTED: `ai_enrich`'s
-# docstring says *"`ai_review.decide` -- the product's only other LLM entry -- has no token
-# accounting of ANY kind"*. R9 asks for ONE meter for every AI surface, so the counting has to reach
-# this transport rather than be bolted onto its caller — the caller never sees the body.
-#
-# ⚠ A THIRD RETURN VALUE, NOT A MUTATED ARGUMENT, and both call sites are in `decide` below. The
-# tuple grew from `(text, err)` to `(text, err, usage)`; `usage` is the raw `usage` OBJECT (or None),
-# because reading it is `usage_ledger`'s job and a second reader here would be the two-normalizers
-# shape this repo keeps paying for.
-def _call_openai(p, model, system, user, timeout):
-    r = requests.post(p["url"], timeout=timeout,
-                      headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
-                               "Content-Type": "application/json"},
-                      json={"model": model, "max_tokens": 300, "temperature": 0,
-                            "messages": [{"role": "system", "content": system},
-                                         {"role": "user", "content": user}]})
-    if r.status_code >= 400:
-        # ⚠ NO BODY ON A 4xx/5xx: an error envelope carries no usage, and a provider that refused
-        # before running the model has nothing to bill. The call is still COUNTED by `decide`.
-        return "", f"{p['name']} answered {r.status_code}", None
-    body = r.json()
-    choices = body.get("choices") or []
-    if not choices:
-        return "", f"{p['name']} returned no choices", body
-    return str(((choices[0] or {}).get("message") or {}).get("content") or ""), "", body
-#: What transport the last Anthropic call actually used: `'sdk'`, `'http'`, or `''` before any.
-#: ⚠ PROCESS-LOCAL AND FOR REPORTING ONLY. It exists so `GET /meta` and `verify_web_agent` can say
-#: WHICH path ran rather than inferring it from a requirements file nobody in this lane can edit.
-LAST_ANTHROPIC_TRANSPORT = ""
-def _call_anthropic(p, model, system, user, timeout):
-    """One classification turn on the Messages API, through `providers.anthropic_send`.
-    ⭐ D-346 (W37-T39): this used to hand-roll the POST. It now goes through the shared wire, which
-    prefers the OFFICIAL `anthropic` SDK and falls back to the same raw POST when the package is
-    absent. The shape of what comes back is unchanged, deliberately: `anthropic_send` normalises
-    both transports to `(status, body)`, so every line below this call is untouched.
-    """
-    global LAST_ANTHROPIC_TRANSPORT
-    import providers as _prov                                           # noqa: PLC0415
-    # ⚠ NO TOOLS ON THIS PATH. The builder omits `tool_choice` for exactly that case, so there is
-    # nothing to strip here — the rule lives in `anthropic_request`, beside the thing it constrains.
-    req = _prov.anthropic_request(
-        model=model, key=os.environ[p["env"]].strip(), system=system,
-        messages=[{"role": "user", "content": user}], tools=[], max_tokens=300)
-    status, body, transport = _prov.anthropic_send(req, timeout=timeout)
-    LAST_ANTHROPIC_TRANSPORT = transport
-    if status >= 400 or status == 0:
-        # ⭐ THE SENTENCE COMES FROM THE LADDER, NOT FROM HERE. `refusal_sentence` already names the
-        # vendor and the action for every status R4 enumerated, so a bare "anthropic answered 402"
-        # (which is what this line used to say, and what the owner quoted back at us) cannot recur.
-        return "", _prov.refusal_sentence("anthropic", status, json.dumps(body)[:400]), None
-    body = body or {}
-    # ⛔ stop_reason FIRST. A safety refusal is a successful 200 with an EMPTY content list, so
-    # reading content[0] before this check turns a refusal into an IndexError inside a run.
-    # ⚠ A refusal IS billed and its body carries `usage`, so the body rides back on this branch too.
-    if body.get("stop_reason") == "refusal":
-        return "", "anthropic declined to answer this record", body
-    parts = [b.get("text") or "" for b in (body.get("content") or [])
-             if isinstance(b, dict) and b.get("type") == "text"]
-    if not parts:
-        return "", "anthropic returned no text", body
-    return "".join(parts), "", body
-def decide(*, prompt, options, row, fields=(), label="Review", timeout=None, st=None, user=""):
-    """Pick this record's next stage. Returns `(choice, meta)`.
-    `choice` is "" whenever a person should decide — which is every failure mode there is.
-    `meta` carries `provider`, `model`, `reason` on success, and `problem` on refusal to answer.
-    ⭐ W35-T41 / C7 — `st` and `user` are the USAGE LEDGER's target. Both default to absent because
-    this function's caller is `automation_engine.ai_decide(rt, ...)`, in another lane's fence: it
-    HAS the runtime and does not pass it yet, so until it does, a review's tokens are counted as
-    unattributed and REPORTED by `GET /usage` rather than dropped. See `usage_ledger`'s header for
-    why they cannot be resolved implicitly (measured: a contextvar does not survive a FastAPI
-    dependency).
-    """
-    import usage_ledger                                                 # noqa: PLC0415
-    opts = [str(o) for o in (options or []) if str(o).strip()]
-    if not opts:
-        return "", {"problem": "the review offers no next stages"}
-    if not str(prompt or "").strip():
-        return "", {"problem": "the review has no prompt for the model to follow"}
-    live = ladder()
-    if not live:
-        return "", {"problem": "no AI provider is configured on this deployment"}
-    system = _instruction(prompt, opts, label)
-    user = "Here is the record:\n\n" + _record_text(row, fields)
-    tmo = float(timeout or TIMEOUT_SECONDS)
-    override = (os.environ.get("AIOS_AI_MODEL") or "").strip()
-    problems = []
-    for p in live:
-        model = override or p["model"]
-        body = None
-        try:
-            text, err, body = (_call_anthropic if p["shape"] == "anthropic" else _call_openai)(
-                p, model, system, user, tmo)
-        except Exception as e:                                        # noqa: BLE001
-            text, err = "", f"{p['name']} failed: {type(e).__name__}"
-        # ⭐⭐ C7 — THE LEDGER LINE, BEFORE ANY BRANCH BELOW READS THE ANSWER.
-        # ⛔ IT IS WRITTEN ON EVERY OUTCOME THAT REACHED A PROVIDER, including a refusal and an
-        # unusable answer. A meter that books only successes reports a cheap week for a run that
-        # spent its budget being declined — and a declined call is billed. The only path that does
-        # NOT record is a transport that never reached the vendor (`body is None`), which spent
-        # nothing.
-        if body is not None:
-            ins, outs = usage_ledger.tokens_from(body)
-            usage_ledger.record("ai_review", p["name"], model, ins, outs,
-                                total=usage_ledger.total_from(body), st=st, user=user)
-        if err:
-            problems.append(err)
-            continue                      # ladder: a dead provider degrades to the next one
-        choice, reason = _parse(text, opts)
-        if not choice:
-            # The provider ANSWERED and declined (or answered unusably). That is a decision about
-            # this record, not a fault in the provider, so it does NOT fall through to a more
-            # expensive one — the card goes to a human, which is what the model just asked for.
-            return "", {"provider": p["name"], "model": model,
-                        "problem": reason or "the model did not choose one of the stages"}
-        return choice, {"provider": p["name"], "model": model, "reason": reason}
-    return "", {"problem": "; ".join(problems)[:300] or "no provider answered"}
-# ══════════════════════════════════════════════════════════════════ the FLOW WRITER
-# ⭐⭐ WAVE 33 · W33-T54/T55 (owner item 7, ruling R3) — A PROMPT BECOMES A DRAFT AUTOMATION.
-#
-# Owner, verbatim: *"lay out the foundation with custom tools we provide"* — and the tools are the
-# action catalog, which has been machine-readable since wave 23. So this writes no new vocabulary:
-# it hands the model the SAME `ACTION_CATALOG` the menu paints, the SAME `ACTION_REQUIRED` the
-# runner blocks on, and the SAME trigger keys `clean_trigger` accepts, and asks for one JSON object
-# in that vocabulary.
-#
-# ⛔ WHY IT LIVES IN `ai_review.py` RATHER THAN A NEW FILE. Two reasons, both about ownership. This
-# is the one module in the API package that already holds an LLM ladder and its credentials, so a
-# second one would be a second place a rotated key has to be noticed; and a new `routes_*.py` needs
-# a `main.py` line from another lane (contract C2) to be reachable at all, which is how wave 23
-# shipped three finished routers 404-dead behind green gates. The DOOR is a route on
-# `routes_automation.py`, which is already mounted.
-#
-# ⛔⛔ CONTRACT C7 IS THE DESIGN, NOT A CHECK AT THE END: *"the flow writer may emit only kinds
-# present in `ACTION_CATALOG`, and its output must pass `clean_actions` unchanged."* Both halves are
-# enforced mechanically rather than asked for politely — the kind list is an `enum` in the schema
-# the model fills, and the caller runs `clean_actions` and DIFFS the result. That diff matters
-# because `clean_actions` has no disclosure channel (D-75): it drops a key it does not recognise
-# and answers 200, so a draft accepted without the diff would show a person a flow that is not the
-# flow the model described, with nothing anywhere saying so.
-#
-# ⚠ `chat` IS INJECTABLE, exactly as `routes_query._call_model`'s is, and it is the reason this door
-# can be proven end to end with no API key and no spend. A gate that can only run where a
-# credential exists is a gate that never runs.
-#: Cerebras first, NOT the cheap-first order `ladder()` uses. Same reason `routes_query` inverts it:
-#: this contract includes a REFUSAL, and refusing honestly ("I cannot build that from the steps you
-#: have") is a model property. A cheaper rung answers an impossible request with a plausible flow,
-#: which is worse than no flow. Override with `AIOS_FLOW_PROVIDER`.
-FLOW_PROVIDER_ORDER = ("cerebras", "groq", "openrouter", "anthropic")
-MAX_DRAFT_ACTIONS = 12          # a draft a person reads in one screen; the engine's own cap is 25
-MAX_PROMPT_CHARS = 2000
-def flow_providers(pin=None):
-    """The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off.
-    ⭐ `pin` IS ASK D-18 (2026-08-18): the Agent chat's model toggle must configure something, and
-    the draft door used to read `prompt` off the body and nothing else — so the key the client sent
-    was accepted and dropped, and the picker was a control over nothing.
-    ⚠ AN UNKNOWN OR UNCONFIGURED PIN FALLS BACK TO THE LADDER rather than refusing. A model the
-    ladder stopped offering must not turn every later draft into an error; the caller is told which
-    rung actually answered, which is the honest half.
-    """
-    by_name = {p["name"]: p for p in PROVIDERS}
-    live = [n for n in FLOW_PROVIDER_ORDER
-            if n in by_name and (os.environ.get(by_name[n]["env"]) or "").strip()]
-    wanted = str(pin or os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
-    if wanted and wanted in live:
-        return [by_name[wanted]]
-    return [by_name[n] for n in live]
-def flow_schema(kinds, trigger_keys, table_keys):
-    """The tool schema the model fills — the catalog's OWN key lists as enums.
-    ⛔ `kind` AND `trigger` ARE ENUMS, not free strings, and that is C7's first half enforced by the
-    transport rather than by a check afterwards. A model asked for "any action name" invents
-    `send_slack_message` on a deployment that has no such kind, and the failure then surfaces as a
-    400 from `clean_actions` carrying a sentence about a word the person never typed.
-    ⚠ `required` IS `["kind"]` ALONE, deliberately: a REFUSAL carries no name and no actions, and a
-    schema demanding them turns an honest refusal into a provider-side 400 that reads exactly like a
-    transport failure (`routes_query._spec_schema` carries the same note, for the same measured
-    reason).
-    """
-    return {
-        "type": "object",
-        "properties": {
-            "kind": {"type": "string", "enum": ["flow", "refused"],
-                     "description": "refused = this cannot be built from the steps available"},
-            "refusal": {"type": "string",
-                        "description": "when kind=refused: ONE plain sentence naming what is "
-                                       "missing, in the words a non-technical person would use"},
-            "name": {"type": "string", "description": "a short title for the automation"},
-            "trigger": {"type": "string", "enum": sorted(trigger_keys),
-                        "description": "what starts this automation"},
-            "table": {"type": "string", "enum": sorted(table_keys),
-                      "description": "the database whose records this flow walks, if any"},
-            "actions": {
-                "type": "array",
-                "maxItems": MAX_DRAFT_ACTIONS,
-                "items": {
-                    "type": "object",
-                    "properties": {
-                        "kind": {"type": "string", "enum": sorted(kinds)},
-                        "why": {"type": "string",
-                                "description": "one short sentence: why this step is here"},
-                        "config": {"type": "object", "additionalProperties": True,
-                                   "description": "the step's settings, using ONLY the keys named "
-                                                  "for that kind in the system message"},
-                    },
-                    "required": ["kind"],
-                },
-            },
-        },
-        "required": ["kind"],
-    }
-def flow_system_prompt(catalog, required, triggers, tables):
-    """What the model is told it may build with — DERIVED, never written down twice.
-    Every list here is the server's own: the catalog rows the menu paints, the required-key table
-    the runner blocks on, the trigger keys `clean_trigger` accepts, and this tenant's real databases
-    with their real columns. Nothing about the vocabulary is restated by hand, so a kind added to
-    the catalog is offered here on the same deploy and a kind removed stops being offered.
-    """
-    lines = ["You build small automations for a business tool. You are given the EXACT set of "
-             "steps this tool can perform. You may use nothing else.",
-             "", "THE STEPS YOU MAY USE:"]
-    # ⚠ BOTH HALVES, `key (phrase)`. The KEY is what the model must write into `config` and the
-    # PHRASE is the only human wording of that requirement anywhere — the one the runner's own
-    # refusal sentence is built from. Keys alone leave the model guessing what `field` means on a
-    # `web_read` (it is a column to write into, not a form field); phrases alone leave it guessing
-    # what to call the setting. Handing it one and hoping is how a draft comes back configured
-    # against a key the validator drops.
-    req = {str(k): [f"{key} ({phrase})" for phrase, key in v] for k, v in (required or {}).items()}
-    for row in catalog or []:
-        if not row.get("ready"):
-            continue
-        kind = str(row.get("kind") or "")
-        need = req.get(kind) or []
-        lines.append(f"- {kind}: {row.get('label')} - {row.get('detail') or ''}"
-                     + (f"  REQUIRED settings: {', '.join(need)}" if need else ""))
-    lines += ["", "WHAT CAN START AN AUTOMATION:"]
-    for t in triggers or []:
-        if t.get("planned") or not t.get("ready", True):
-            continue
-        lines.append(f"- {t.get('key')}: {t.get('label')}")
-    lines += ["", "THE DATABASES THIS PERSON HAS:"]
-    for t in (tables or [])[:40]:
-        cols = ", ".join(str(f.get("key")) for f in (t.get("fields") or [])[:25])
-        lines.append(f"- {t.get('key')} ({t.get('label')}): {cols or 'no columns yet'}")
-    if not tables:
-        lines.append("- (none - do not name a database)")
-    lines += [
-        "",
-        "RULES:",
-        "1. Use ONLY the step kinds listed above. If what is asked needs a step that is not there, "
-        "answer kind=refused and say plainly which capability is missing.",
-        "2. Fill in every REQUIRED setting you can from what the person told you. Leave one blank "
-        "rather than inventing a web address, a CSS selector or a column name.",
-        "3. A web address must start with http:// or https://.",
-        "4. To use a value from the record the flow is walking, write it as {{Column name}}.",
-        "5. Name a database only from the list above, by its key.",
-        "6. Keep it short. Fewer steps that work beat more steps that guess.",
-    ]
-    return "\n".join(lines)
-def _flow_from_tool_call(obj):
-    """The model's tool arguments -> `(draft, refusal)`. A shape error is a refusal, never a crash."""
-    if not isinstance(obj, dict):
-        return None, "the assistant's answer could not be read"
-    if str(obj.get("kind") or "") == "refused":
-        return None, (str(obj.get("refusal") or "").strip()
-                      or "the assistant could not build this from the steps available")
-    acts = obj.get("actions")
-    if not isinstance(acts, list) or not acts:
-        return None, ("the assistant did not produce any steps - try describing what should "
-                      "happen, one action at a time")
-    out = []
-    for a in acts[:MAX_DRAFT_ACTIONS]:
-        if not isinstance(a, dict) or not str(a.get("kind") or "").strip():
-            continue
-        cfg = a.get("config")
-        out.append({"kind": str(a["kind"]).strip(),
-                    "config": cfg if isinstance(cfg, dict) else {},
-                    "why": str(a.get("why") or "").strip()[:200]})
-    if not out:
-        return None, "the assistant's steps could not be read"
-    return {"name": str(obj.get("name") or "").strip()[:80] or "New automation",
-            "trigger": str(obj.get("trigger") or "").strip(),
-            "table": str(obj.get("table") or "").strip(),
-            # ⛔⛔ THE TRUNCATION IS REPORTED, and it is a STANDING RULE that it must be (owner,
-            # 2026-08-12, W30/R6 second sentence): *"if there is lag or it can't be done, you need
-            # to explicitly tell me why and recommend a fix"* — **a silent truncation IS the
-            # violation, not the limit.** `acts[:MAX_DRAFT_ACTIONS]` above dropped everything past
-            # the twelfth and said nothing, so a model that answered with a twenty-step journey had
-            # eight steps deleted between the answer and the screen, with no key anywhere in the
-            # response naming them. `MAX_ACTIONS` is 20, so those steps were STORABLE — this
-            # ceiling is the draft door's own, which makes reporting it the whole obligation.
-            # ⚠ Found by the verifier that checked this ticket, not by a gate.
-            "asked": len([a for a in acts if isinstance(a, dict)]),
-            "actions": out}, ""
-def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeout=None,
-               st=None, user="", model=None):
-    """A sentence -> `(draft, refusal_sentence, provider)`. ⛔ NOTHING IS SAVED HERE.
-    Exactly one of `draft` and `refusal_sentence` is truthy — the same contract
-    `web_agent.run_step` keeps, so a caller has no third case to get wrong.
-    ⭐ W35-T41 / C7 — `st`/`user` are the usage ledger's target, exactly as on `decide` above and for
-    the same reason: both of this function's callers (`automation_engine._ai_agent_plan` and
-    `routes_automation`'s draft door) are in lane D's fence. C7 says E adds the ledger line here and
-    D asserts it; the two keywords are what D has to pass for the line to be attributable.
-    """
-    # ⚠ DECLARED AT THE TOP OF THE FUNCTION, not beside the assignment inside the provider loop.
-    # It parses either way; a reader scanning for the declaration does not look inside a `for`.
-    global LAST_ANTHROPIC_TRANSPORT
-    import usage_ledger                                                 # noqa: PLC0415
-    text = str(prompt or "").strip()[:MAX_PROMPT_CHARS]
-    if not text:
-        return None, "type what you want the automation to do", None
-    kinds = sorted({str(r.get("kind")) for r in (catalog or []) if r.get("ready")})
-    if not kinds:
-        return None, "this deployment offers no automation steps to build with", None
-    trigger_keys = sorted({str(t.get("key")) for t in (triggers or [])
-                           if t.get("key") and not t.get("planned")}) or ["manual"]
-    table_keys = sorted({str(t.get("key")) for t in (tables or []) if t.get("key")}) or [""]
-    tools = [{"type": "function", "function": {
-        "name": "build_automation",
-        "description": "Emit the automation, or refuse.",
-        "parameters": flow_schema(kinds, trigger_keys, table_keys)}}]
-    messages = [{"role": "system",
-                 "content": flow_system_prompt(catalog, required, triggers, tables)},
-                {"role": "user", "content": text}]
-    if chat is not None:
-        # ⚠ THE INJECTED PATH IS THE PROVEN PATH. It runs the SAME parse and the SAME refusal
-        # branches as a live call; only the transport is replaced.
-        draft, refusal = _flow_from_tool_call(chat(messages, tools))
-        return draft, refusal, "injected"
-    provs = flow_providers(model)
-    if not provs:
-        # ⛔ SAY SO. An AI feature that silently does nothing is indistinguishable from one that was
-        # never built [[flag-shipped-without-its-writer]].
-        return None, ("the assistant is not configured on this deployment, so an automation cannot "
-                      "be drafted from a description yet"), None
-    tmo = float(timeout or TIMEOUT_SECONDS)
-    problems = []
-    import providers as _prov
-    for p in provs:
-        # ⭐⭐ W36-T35 / R4 — THE OWNER QUOTED THIS LINE BACK AT US. It used to read
-        # `problems.append(f"{p['name']}: tool calls are not wired for this shape")` and `continue`,
-        # so the sentence *"anthropic: tool calls are not wired for this shape"* appeared under the
-        # Agent module verbatim. R4: *"Anthropic becomes the tool-calling path that always works."*
-        # It is wired now, through the ONE wire in `providers`, and it matters more than it looks:
-        # every side rung on this account is refusing today (cerebras 402, groq 404, openrouter
-        # 402), so without this branch the drafter cannot answer at all.
-        # ⚠ NO `effort` ON THIS DOOR — `output_config.effort` errors on Haiku 4.5, the tier this
-        # ladder runs. The parameter is the caller's to send, which is why the wire takes it.
-        # ⭐ D-346 (W37-T39): BOTH shapes now yield the SAME `(status, body)` pair, so every branch
-        # below reads one thing. The anthropic side gets there through `anthropic_send` (official
-        # SDK when installed, the identical raw POST when not); the openai side still posts here
-        # because there is no shared SDK across three different vendors on that wire.
-        global LAST_ANTHROPIC_TRANSPORT
-        try:
-            if p["shape"] == "anthropic":
-                req = _prov.anthropic_request(
-                    model=p["model"], key=os.environ[p["env"]].strip(), system=None,
-                    messages=messages, tools=tools, max_tokens=1500, tool_choice="required")
-                status, body, transport = _prov.anthropic_send(req, timeout=tmo)
-                LAST_ANTHROPIC_TRANSPORT = transport
-            else:
-                r = requests.post(p["url"], timeout=tmo,
-                                  headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
-                                           "Content-Type": "application/json"},
-                                  json={"model": p["model"], "messages": messages, "tools": tools,
-                                        "tool_choice": "required", "temperature": 0.1,
-                                        "max_tokens": 1500})
-                status = r.status_code
-                body = r.json() if (r.content and r.status_code == 200) else {"_text": r.text}
-        except Exception as e:                                    # noqa: BLE001
-            problems.append(f"{p['name']}: {type(e).__name__}")
-            continue
-        if status != 200:
-            # ⛔ A SENTENCE, NOT `HTTP 402` (R4's third clause). The owner read the status codes off
-            # this very door. `refusal_sentence` also decides whether this was a CREDIT failure, and
-            # the memo makes the next turn SKIP the empty account instead of paying for it again.
-            # ⚠ The body is re-serialised for the substring test because the SDK path never had a
-            # `.text` — that is the one thing this normalisation costs, and it costs nothing else.
-            detail = json.dumps(body)[:600] if isinstance(body, dict) else str(body)[:600]
-            if _prov.is_credit_failure(status, detail):
-                _prov.mark_no_credit(p["name"])
-            problems.append(_prov.refusal_sentence(p["name"], status, detail))
-            continue
-        try:
-            body = body or {}
-            if p["shape"] == "anthropic":
-                _text, args, _refused = _prov.anthropic_read(body)
-                if _refused:
-                    problems.append(f"{p['name']}: {_refused}")
-                    continue
-            else:
-                calls = (((body.get("choices") or [{}])[0].get("message") or {})
-                         .get("tool_calls") or [])
-                args = json.loads(calls[0]["function"]["arguments"]) if calls else None
-        except Exception as e:                                    # noqa: BLE001
-            problems.append(f"{p['name']}: unreadable answer ({type(e).__name__})")
-            continue
-        # ⭐⭐ C7 — THE LEDGER LINE. Placed after the parse rather than before it so an UNREADABLE
-        # answer is not double-counted by the `continue` above... ⚠ which means an unreadable answer
-        # is NOT counted at all, and that is a deliberate, disclosed loss: a body this code cannot
-        # parse is a body whose `usage` it also cannot trust, and `body` is out of scope in that
-        # branch by construction. The 200-with-junk case is rare and named here rather than
-        # silently rounded to zero.
-        ins, outs = usage_ledger.tokens_from(body)
-        usage_ledger.record("automation_draft", p["name"], p["model"], ins, outs,
-                            total=usage_ledger.total_from(body), st=st, user=user)
-        draft, refusal = _flow_from_tool_call(args)
-        if draft is None and isinstance(args, dict) and str(args.get("kind")) == "refused":
-            # ⛔ A REFUSAL IS AN ANSWER, NOT A FAULT, so it does NOT fall through to a more
-            # expensive rung — the model has just said this cannot be built. `decide()` takes the
-            # same posture for the same reason.
-            return None, refusal, p["name"]
-        if draft is not None:
-            return draft, "", p["name"]
-        problems.append(f"{p['name']}: {refusal}")
-    return None, ("; ".join(problems)[:300] or "no provider answered"), None

+"""AI REVIEW — let a model decide which stage a card moves to (wave 23, owner ruling R4/R14).
+⭐ WHAT THIS IS. A review stage holds a record until somebody decides where it goes next. R4 made
+that somebody optionally a MODEL: the engine hands over the record's own values, the review's
+prompt, and the list of stages the review is allowed to send a card to, and gets back ONE of
+those stage labels plus a one-line reason. Every decision is written to the same `reviews` audit
+log a human click writes to, tagged `by: "ai"` with the provider and model that made it.
+⛔ FAIL-CLOSED IN EVERY DIRECTION, and this is the whole safety story. No key configured, a
+network failure, a slow answer, a malformed answer, or an answer naming a stage the review does
+not offer — all return `("", {...})`, and the caller leaves the card exactly where a human would
+have found it. The feature can be absent, broken or wrong and the worst outcome is a person doing
+the work. Nothing here can move a card somewhere the review does not already permit.
+⭐ CHEAP FIRST (owner R14, verbatim: *"Claude is a bit too expensive"*). The ladder is
+`groq → cerebras → openrouter → anthropic`; the first CONFIGURED provider wins, and Anthropic is
+last rather than absent — it is the quality backstop, not the default. `AIOS_AI_REVIEW_PROVIDER`
+pins one; `AIOS_AI_MODEL` overrides the model.
+⭐⭐ THE ANTHROPIC LEG IS ON THE OFFICIAL SDK NOW (D-346, W37-T39, 2026-08-19). ⛔ THIS PARAGRAPH
+USED TO ARGUE THE OPPOSITE and is rewritten rather than deleted, because a comment left asserting
+the reverse of its own code is [[two-gates-can-assert-opposite-things]] with no gate to catch it.
+The retired text said raw HTTP was *"a deliberate deviation … booked as a DEBT line so the
+integrator can overturn it deliberately rather than by drift"*. This is that overturn.
+Its two reasons were real and are both answered rather than waved away:
+  1. *"one SDK leg beside three hand-rolled ones is two implementations of the same call."* It is
+     not, because the leg does not live here: `providers.anthropic_send` owns the wire, prefers
+     the SDK, and normalises BOTH transports to one `(status, body)` pair. This file gained no
+     Anthropic knowledge — it lost some.
+  2. *"adding a pinned dependency rebuilds the container, a real deploy risk."* Still true, so the
+     import is LAZY and its absence is a FALLBACK, not a crash: with no `anthropic` package the
+     same raw POST runs and `LAST_ANTHROPIC_TRANSPORT` reports `'http'`. The pin is owed in BOTH
+     manifests ([[pin-deps-space-rebuilds]]) and is outside every worker fence this wave.
+⚠ The other three legs stay OpenAI-chat-shaped over `requests` — they have no shared SDK, and that
+half of the original reasoning never expired.
+The Messages shape below is the current one: `x-api-key` + `anthropic-version: 2023-06-01`, and
+`stop_reason: "refusal"` is checked BEFORE reading `content` — a refusal answers HTTP 200 with an
+empty content list, so code that indexes `content[0]` unconditionally breaks on it.
+"""
+from __future__ import annotations
+import json
+import os
+import re
+import requests
+#: The ladder. Order IS the policy (R14) — cheapest capable first, Anthropic last.
+PROVIDERS = [
+    # ⛔⛔ D-345, FIXED W37-T39 (2026-08-19). This read `llama-3.3-70b-versatile` and Groq RETIRED
+    # it: a real POST with the live key answers HTTP 404 `model_not_found`, and the id is absent
+    # from `GET /openai/v1/models`. ⚠ THE `openai/` PREFIX IS PART OF GROQ'S ID and is NOT a typo
+    # for the cerebras rung below, which serves the same family bare as `gpt-oss-120b`.
+    {"name": "groq", "env": "GROQ_API_KEY", "shape": "openai",
+     "url": "https://api.groq.com/openai/v1/chat/completions",
+     "model": "openai/gpt-oss-120b"},
+    {"name": "cerebras", "env": "CEREBRAS_API_KEY", "shape": "openai",
+     "url": "https://api.cerebras.ai/v1/chat/completions",
+     "model": "gpt-oss-120b"},
+    {"name": "openrouter", "env": "OPENROUTER_API_KEY", "shape": "openai",
+     "url": "https://openrouter.ai/api/v1/chat/completions",
+     "model": "openai/gpt-4o-mini"},
+    # ⚠ haiku-class DELIBERATELY, not the default Opus tier: R14 put Anthropic on this ladder as
+    # the backstop for a one-line classification, and this is the cheapest current Claude that
+    # does it well. A bigger model here would be spending the owner's money to pick between two
+    # labels it already has in front of it.
+    {"name": "anthropic", "env": "ANTHROPIC_API_KEY", "shape": "anthropic",
+     "url": "https://api.anthropic.com/v1/messages",
+     # ⚠ AN ENV LEVER, NOT A NEW DEFAULT (W36-T35): haiku stays the choice for the reasons above,
+     # and a deployment whose side rungs are out of credit can raise the tier without a release.
+     "model": os.environ.get("AIOS_AI_REVIEW_ANTHROPIC_MODEL") or "claude-haiku-4-5"},
+]
+ANTHROPIC_VERSION = "2023-06-01"
+TIMEOUT_SECONDS = float(os.environ.get("AIOS_AI_REVIEW_TIMEOUT") or 20)
+MAX_FIELD_CHARS = 200          # per value handed to the model
+MAX_FIELDS = 30                # columns handed to the model
+MAX_REASON = 200
+def ladder():
+    """The providers that are actually usable here, in order. Empty = the feature is off."""
+    pin = (os.environ.get("AIOS_AI_REVIEW_PROVIDER") or "").strip().lower()
+    live = [p for p in PROVIDERS if (os.environ.get(p["env"]) or "").strip()]
+    if pin:
+        live = [p for p in live if p["name"] == pin]
+    return live
+def configured():
+    return bool(ladder())
+def _record_text(row, fields):
+    """The record, as the model sees it. Values are truncated and the column set is bounded —
+    an automation table can carry a 32 KB JSON blob per row (C7) and a review decision does not
+    need it. Machine bookkeeping columns are dropped: a stage cell naming the stage the card is
+    sitting at would be the model reading its own question back."""
+    keys = [k for k in (fields or list((row or {}).keys()))
+            if not str(k).startswith("stage_")][:MAX_FIELDS]
+    lines = []
+    for k in keys:
+        v = (row or {}).get(k)
+        if v is None or str(v).strip() == "":
+            continue
+        lines.append(f"{k}: {str(v)[:MAX_FIELD_CHARS]}")
+    return "\n".join(lines) or "(this record has no filled-in values)"
+def _instruction(prompt, options, label):
+    return (
+        f"You are deciding what happens to one record waiting at a review step called "
+        f"{label!r} in a workflow.\n\n"
+        f"The person who built this workflow told you: {prompt}\n\n"
+        f"Choose EXACTLY ONE of these next steps, by its exact name:\n"
+        + "\n".join(f"- {o}" for o in options)
+        + "\n\nAnswer with one line of JSON and nothing else:\n"
+          '{"choice": "<one name from the list above>", "reason": "<one short sentence>"}\n'
+          "If the record does not give you enough to decide, answer "
+          '{"choice": "", "reason": "why not"} and a person will decide instead.'
+    )
+def _parse(text, options):
+    """The model's line → `(choice, reason)`. A choice that is not one of the offered stages is
+    DISCARDED, not fuzzy-matched: the offered list is a permission boundary, and a near-miss
+    resolved by string distance is how a card ends up somewhere nobody authorised."""
+    raw = str(text or "").strip()
+    obj = None
+    m = re.search(r"\{.*\}", raw, re.S)
+    if m:
+        try:
+            obj = json.loads(m.group(0))
+        except (ValueError, TypeError):
+            obj = None
+    if not isinstance(obj, dict):
+        return "", ""
+    choice = str(obj.get("choice") or "").strip()
+    reason = str(obj.get("reason") or "").strip()[:MAX_REASON]
+    for opt in options:
+        if choice.lower() == str(opt).lower():
+            return str(opt), reason           # the OFFERED spelling wins, never the model's
+    return "", reason
+# ⭐⭐ WAVE 35 · W35-T41 / C7 — THE TWO TRANSPORTS RETURN THE RESPONSE BODY'S `usage`.
+#
+# ⛔ THIS FILE'S OWN HEADER USED TO BE THE PRODUCT'S CONFESSION THAT NOTHING COUNTED: `ai_enrich`'s
+# docstring says *"`ai_review.decide` -- the product's only other LLM entry -- has no token
+# accounting of ANY kind"*. R9 asks for ONE meter for every AI surface, so the counting has to reach
+# this transport rather than be bolted onto its caller — the caller never sees the body.
+#
+# ⚠ A THIRD RETURN VALUE, NOT A MUTATED ARGUMENT, and both call sites are in `decide` below. The
+# tuple grew from `(text, err)` to `(text, err, usage)`; `usage` is the raw `usage` OBJECT (or None),
+# because reading it is `usage_ledger`'s job and a second reader here would be the two-normalizers
+# shape this repo keeps paying for.
+def _call_openai(p, model, system, user, timeout):
+    r = requests.post(p["url"], timeout=timeout,
+                      headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
+                               "Content-Type": "application/json"},
+                      json={"model": model, "max_tokens": 300, "temperature": 0,
+                            "messages": [{"role": "system", "content": system},
+                                         {"role": "user", "content": user}]})
+    if r.status_code >= 400:
+        # ⚠ NO BODY ON A 4xx/5xx: an error envelope carries no usage, and a provider that refused
+        # before running the model has nothing to bill. The call is still COUNTED by `decide`.
+        return "", f"{p['name']} answered {r.status_code}", None
+    body = r.json()
+    choices = body.get("choices") or []
+    if not choices:
+        return "", f"{p['name']} returned no choices", body
+    return str(((choices[0] or {}).get("message") or {}).get("content") or ""), "", body
+#: What transport the last Anthropic call actually used: `'sdk'`, `'http'`, or `''` before any.
+#: ⚠ PROCESS-LOCAL AND FOR REPORTING ONLY. It exists so `GET /meta` and `verify_web_agent` can say
+#: WHICH path ran rather than inferring it from a requirements file nobody in this lane can edit.
+LAST_ANTHROPIC_TRANSPORT = ""
+def _call_anthropic(p, model, system, user, timeout):
+    """One classification turn on the Messages API, through `providers.anthropic_send`.
+    ⭐ D-346 (W37-T39): this used to hand-roll the POST. It now goes through the shared wire, which
+    prefers the OFFICIAL `anthropic` SDK and falls back to the same raw POST when the package is
+    absent. The shape of what comes back is unchanged, deliberately: `anthropic_send` normalises
+    both transports to `(status, body)`, so every line below this call is untouched.
+    """
+    global LAST_ANTHROPIC_TRANSPORT
+    import providers as _prov                                           # noqa: PLC0415
+    # ⚠ NO TOOLS ON THIS PATH. The builder omits `tool_choice` for exactly that case, so there is
+    # nothing to strip here — the rule lives in `anthropic_request`, beside the thing it constrains.
+    req = _prov.anthropic_request(
+        model=model, key=os.environ[p["env"]].strip(), system=system,
+        messages=[{"role": "user", "content": user}], tools=[], max_tokens=300)
+    status, body, transport = _prov.anthropic_send(req, timeout=timeout)
+    LAST_ANTHROPIC_TRANSPORT = transport
+    if status >= 400 or status == 0:
+        # ⭐ THE SENTENCE COMES FROM THE LADDER, NOT FROM HERE. `refusal_sentence` already names the
+        # vendor and the action for every status R4 enumerated, so a bare "anthropic answered 402"
+        # (which is what this line used to say, and what the owner quoted back at us) cannot recur.
+        return "", _prov.refusal_sentence("anthropic", status, json.dumps(body)[:400]), None
+    body = body or {}
+    # ⛔ stop_reason FIRST. A safety refusal is a successful 200 with an EMPTY content list, so
+    # reading content[0] before this check turns a refusal into an IndexError inside a run.
+    # ⚠ A refusal IS billed and its body carries `usage`, so the body rides back on this branch too.
+    if body.get("stop_reason") == "refusal":
+        return "", "anthropic declined to answer this record", body
+    parts = [b.get("text") or "" for b in (body.get("content") or [])
+             if isinstance(b, dict) and b.get("type") == "text"]
+    if not parts:
+        return "", "anthropic returned no text", body
+    return "".join(parts), "", body
+def decide(*, prompt, options, row, fields=(), label="Review", timeout=None, st=None, user=""):
+    """Pick this record's next stage. Returns `(choice, meta)`.
+    `choice` is "" whenever a person should decide — which is every failure mode there is.
+    `meta` carries `provider`, `model`, `reason` on success, and `problem` on refusal to answer.
+    ⭐ W35-T41 / C7 — `st` and `user` are the USAGE LEDGER's target. Both default to absent because
+    this function's caller is `automation_engine.ai_decide(rt, ...)`, in another lane's fence: it
+    HAS the runtime and does not pass it yet, so until it does, a review's tokens are counted as
+    unattributed and REPORTED by `GET /usage` rather than dropped. See `usage_ledger`'s header for
+    why they cannot be resolved implicitly (measured: a contextvar does not survive a FastAPI
+    dependency).
+    """
+    import usage_ledger                                                 # noqa: PLC0415
+    opts = [str(o) for o in (options or []) if str(o).strip()]
+    if not opts:
+        return "", {"problem": "the review offers no next stages"}
+    if not str(prompt or "").strip():
+        return "", {"problem": "the review has no prompt for the model to follow"}
+    live = ladder()
+    if not live:
+        return "", {"problem": "no AI provider is configured on this deployment"}
+    system = _instruction(prompt, opts, label)
+    user = "Here is the record:\n\n" + _record_text(row, fields)
+    tmo = float(timeout or TIMEOUT_SECONDS)
+    override = (os.environ.get("AIOS_AI_MODEL") or "").strip()
+    problems = []
+    for p in live:
+        model = override or p["model"]
+        body = None
+        try:
+            text, err, body = (_call_anthropic if p["shape"] == "anthropic" else _call_openai)(
+                p, model, system, user, tmo)
+        except Exception as e:                                        # noqa: BLE001
+            text, err = "", f"{p['name']} failed: {type(e).__name__}"
+        # ⭐⭐ C7 — THE LEDGER LINE, BEFORE ANY BRANCH BELOW READS THE ANSWER.
+        # ⛔ IT IS WRITTEN ON EVERY OUTCOME THAT REACHED A PROVIDER, including a refusal and an
+        # unusable answer. A meter that books only successes reports a cheap week for a run that
+        # spent its budget being declined — and a declined call is billed. The only path that does
+        # NOT record is a transport that never reached the vendor (`body is None`), which spent
+        # nothing.
+        if body is not None:
+            ins, outs = usage_ledger.tokens_from(body)
+            usage_ledger.record("ai_review", p["name"], model, ins, outs,
+                                total=usage_ledger.total_from(body), st=st, user=user)
+        if err:
+            problems.append(err)
+            continue                      # ladder: a dead provider degrades to the next one
+        choice, reason = _parse(text, opts)
+        if not choice:
+            # The provider ANSWERED and declined (or answered unusably). That is a decision about
+            # this record, not a fault in the provider, so it does NOT fall through to a more
+            # expensive one — the card goes to a human, which is what the model just asked for.
+            return "", {"provider": p["name"], "model": model,
+                        "problem": reason or "the model did not choose one of the stages"}
+        return choice, {"provider": p["name"], "model": model, "reason": reason}
+    return "", {"problem": "; ".join(problems)[:300] or "no provider answered"}
+# ══════════════════════════════════════════════════════════════════ the FLOW WRITER
+# ⭐⭐ WAVE 33 · W33-T54/T55 (owner item 7, ruling R3) — A PROMPT BECOMES A DRAFT AUTOMATION.
+#
+# Owner, verbatim: *"lay out the foundation with custom tools we provide"* — and the tools are the
+# action catalog, which has been machine-readable since wave 23. So this writes no new vocabulary:
+# it hands the model the SAME `ACTION_CATALOG` the menu paints, the SAME `ACTION_REQUIRED` the
+# runner blocks on, and the SAME trigger keys `clean_trigger` accepts, and asks for one JSON object
+# in that vocabulary.
+#
+# ⛔ WHY IT LIVES IN `ai_review.py` RATHER THAN A NEW FILE. Two reasons, both about ownership. This
+# is the one module in the API package that already holds an LLM ladder and its credentials, so a
+# second one would be a second place a rotated key has to be noticed; and a new `routes_*.py` needs
+# a `main.py` line from another lane (contract C2) to be reachable at all, which is how wave 23
+# shipped three finished routers 404-dead behind green gates. The DOOR is a route on
+# `routes_automation.py`, which is already mounted.
+#
+# ⛔⛔ CONTRACT C7 IS THE DESIGN, NOT A CHECK AT THE END: *"the flow writer may emit only kinds
+# present in `ACTION_CATALOG`, and its output must pass `clean_actions` unchanged."* Both halves are
+# enforced mechanically rather than asked for politely — the kind list is an `enum` in the schema
+# the model fills, and the caller runs `clean_actions` and DIFFS the result. That diff matters
+# because `clean_actions` has no disclosure channel (D-75): it drops a key it does not recognise
+# and answers 200, so a draft accepted without the diff would show a person a flow that is not the
+# flow the model described, with nothing anywhere saying so.
+#
+# ⚠ `chat` IS INJECTABLE, exactly as `routes_query._call_model`'s is, and it is the reason this door
+# can be proven end to end with no API key and no spend. A gate that can only run where a
+# credential exists is a gate that never runs.
+#: Cerebras first, NOT the cheap-first order `ladder()` uses. Same reason `routes_query` inverts it:
+#: this contract includes a REFUSAL, and refusing honestly ("I cannot build that from the steps you
+#: have") is a model property. A cheaper rung answers an impossible request with a plausible flow,
+#: which is worse than no flow. Override with `AIOS_FLOW_PROVIDER`.
+FLOW_PROVIDER_ORDER = ("cerebras", "groq", "openrouter", "anthropic")
+MAX_DRAFT_ACTIONS = 12          # a draft a person reads in one screen; the engine's own cap is 25
+MAX_PROMPT_CHARS = 2000
+def flow_providers(pin=None):
+    """The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off.
+    ⭐ `pin` IS ASK D-18 (2026-08-18): the Agent chat's model toggle must configure something, and
+    the draft door used to read `prompt` off the body and nothing else — so the key the client sent
+    was accepted and dropped, and the picker was a control over nothing.
+    ⚠ AN UNKNOWN OR UNCONFIGURED PIN FALLS BACK TO THE LADDER rather than refusing. A model the
+    ladder stopped offering must not turn every later draft into an error; the caller is told which
+    rung actually answered, which is the honest half.
+    """
+    by_name = {p["name"]: p for p in PROVIDERS}
+    live = [n for n in FLOW_PROVIDER_ORDER
+            if n in by_name and (os.environ.get(by_name[n]["env"]) or "").strip()]
+    wanted = str(pin or os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
+    if wanted and wanted in live:
+        return [by_name[wanted]]
+    return [by_name[n] for n in live]
+def flow_schema(kinds, trigger_keys, table_keys):
+    """The tool schema the model fills — the catalog's OWN key lists as enums.
+    ⛔ `kind` AND `trigger` ARE ENUMS, not free strings, and that is C7's first half enforced by the
+    transport rather than by a check afterwards. A model asked for "any action name" invents
+    `send_slack_message` on a deployment that has no such kind, and the failure then surfaces as a
+    400 from `clean_actions` carrying a sentence about a word the person never typed.
+    ⚠ `required` IS `["kind"]` ALONE, deliberately: a REFUSAL carries no name and no actions, and a
+    schema demanding them turns an honest refusal into a provider-side 400 that reads exactly like a
+    transport failure (`routes_query._spec_schema` carries the same note, for the same measured
+    reason).
+    """
+    return {
+        "type": "object",
+        "properties": {
+            "kind": {"type": "string", "enum": ["flow", "refused"],
+                     "description": "refused = this cannot be built from the steps available"},
+            "refusal": {"type": "string",
+                        "description": "when kind=refused: ONE plain sentence naming what is "
+                                       "missing, in the words a non-technical person would use"},
+            "name": {"type": "string", "description": "a short title for the automation"},
+            "trigger": {"type": "string", "enum": sorted(trigger_keys),
+                        "description": "what starts this automation"},
+            "table": {"type": "string", "enum": sorted(table_keys),
+                      "description": "the database whose records this flow walks, if any"},
+            "actions": {
+                "type": "array",
+                "maxItems": MAX_DRAFT_ACTIONS,
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "kind": {"type": "string", "enum": sorted(kinds)},
+                        "why": {"type": "string",
+                                "description": "one short sentence: why this step is here"},
+                        "config": {"type": "object", "additionalProperties": True,
+                                   "description": "the step's settings, using ONLY the keys named "
+                                                  "for that kind in the system message"},
+                    },
+                    "required": ["kind"],
+                },
+            },
+        },
+        "required": ["kind"],
+    }
+def flow_system_prompt(catalog, required, triggers, tables):
+    """What the model is told it may build with — DERIVED, never written down twice.
+    Every list here is the server's own: the catalog rows the menu paints, the required-key table
+    the runner blocks on, the trigger keys `clean_trigger` accepts, and this tenant's real databases
+    with their real columns. Nothing about the vocabulary is restated by hand, so a kind added to
+    the catalog is offered here on the same deploy and a kind removed stops being offered.
+    """
+    lines = ["You build small automations for a business tool. You are given the EXACT set of "
+             "steps this tool can perform. You may use nothing else.",
+             "", "THE STEPS YOU MAY USE:"]
+    # ⚠ BOTH HALVES, `key (phrase)`. The KEY is what the model must write into `config` and the
+    # PHRASE is the only human wording of that requirement anywhere — the one the runner's own
+    # refusal sentence is built from. Keys alone leave the model guessing what `field` means on a
+    # `web_read` (it is a column to write into, not a form field); phrases alone leave it guessing
+    # what to call the setting. Handing it one and hoping is how a draft comes back configured
+    # against a key the validator drops.
+    req = {str(k): [f"{key} ({phrase})" for phrase, key in v] for k, v in (required or {}).items()}
+    for row in catalog or []:
+        if not row.get("ready"):
+            continue
+        kind = str(row.get("kind") or "")
+        need = req.get(kind) or []
+        lines.append(f"- {kind}: {row.get('label')} - {row.get('detail') or ''}"
+                     + (f"  REQUIRED settings: {', '.join(need)}" if need else ""))
+    lines += ["", "WHAT CAN START AN AUTOMATION:"]
+    for t in triggers or []:
+        if t.get("planned") or not t.get("ready", True):
+            continue
+        lines.append(f"- {t.get('key')}: {t.get('label')}")
+    lines += ["", "THE DATABASES THIS PERSON HAS:"]
+    for t in (tables or [])[:40]:
+        cols = ", ".join(str(f.get("key")) for f in (t.get("fields") or [])[:25])
+        lines.append(f"- {t.get('key')} ({t.get('label')}): {cols or 'no columns yet'}")
+    if not tables:
+        lines.append("- (none - do not name a database)")
+    lines += [
+        "",
+        "RULES:",
+        "1. Use ONLY the step kinds listed above. If what is asked needs a step that is not there, "
+        "answer kind=refused and say plainly which capability is missing.",
+        "2. Fill in every REQUIRED setting you can from what the person told you. Leave one blank "
+        "rather than inventing a web address, a CSS selector or a column name.",
+        "3. A web address must start with http:// or https://.",
+        "4. To use a value from the record the flow is walking, write it as {{Column name}}.",
+        "5. Name a database only from the list above, by its key.",
+        "6. Keep it short. Fewer steps that work beat more steps that guess.",
+    ]
+    return "\n".join(lines)
+def _flow_from_tool_call(obj):
+    """The model's tool arguments -> `(draft, refusal)`. A shape error is a refusal, never a crash."""
+    if not isinstance(obj, dict):
+        return None, "the assistant's answer could not be read"
+    if str(obj.get("kind") or "") == "refused":
+        return None, (str(obj.get("refusal") or "").strip()
+                      or "the assistant could not build this from the steps available")
+    acts = obj.get("actions")
+    if not isinstance(acts, list) or not acts:
+        return None, ("the assistant did not produce any steps - try describing what should "
+                      "happen, one action at a time")
+    out = []
+    for a in acts[:MAX_DRAFT_ACTIONS]:
+        if not isinstance(a, dict) or not str(a.get("kind") or "").strip():
+            continue
+        cfg = a.get("config")
+        out.append({"kind": str(a["kind"]).strip(),
+                    "config": cfg if isinstance(cfg, dict) else {},
+                    "why": str(a.get("why") or "").strip()[:200]})
+    if not out:
+        return None, "the assistant's steps could not be read"
+    return {"name": str(obj.get("name") or "").strip()[:80] or "New automation",
+            "trigger": str(obj.get("trigger") or "").strip(),
+            "table": str(obj.get("table") or "").strip(),
+            # ⛔⛔ THE TRUNCATION IS REPORTED, and it is a STANDING RULE that it must be (owner,
+            # 2026-08-12, W30/R6 second sentence): *"if there is lag or it can't be done, you need
+            # to explicitly tell me why and recommend a fix"* — **a silent truncation IS the
+            # violation, not the limit.** `acts[:MAX_DRAFT_ACTIONS]` above dropped everything past
+            # the twelfth and said nothing, so a model that answered with a twenty-step journey had
+            # eight steps deleted between the answer and the screen, with no key anywhere in the
+            # response naming them. `MAX_ACTIONS` is 20, so those steps were STORABLE — this
+            # ceiling is the draft door's own, which makes reporting it the whole obligation.
+            # ⚠ Found by the verifier that checked this ticket, not by a gate.
+            "asked": len([a for a in acts if isinstance(a, dict)]),
+            "actions": out}, ""
+def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeout=None,
+               st=None, user="", model=None):
+    """A sentence -> `(draft, refusal_sentence, provider)`. ⛔ NOTHING IS SAVED HERE.
+    Exactly one of `draft` and `refusal_sentence` is truthy — the same contract
+    `web_agent.run_step` keeps, so a caller has no third case to get wrong.
+    ⭐ W35-T41 / C7 — `st`/`user` are the usage ledger's target, exactly as on `decide` above and for
+    the same reason: both of this function's callers (`automation_engine._ai_agent_plan` and
+    `routes_automation`'s draft door) are in lane D's fence. C7 says E adds the ledger line here and
+    D asserts it; the two keywords are what D has to pass for the line to be attributable.
+    """
+    # ⚠ DECLARED AT THE TOP OF THE FUNCTION, not beside the assignment inside the provider loop.
+    # It parses either way; a reader scanning for the declaration does not look inside a `for`.
+    global LAST_ANTHROPIC_TRANSPORT
+    import usage_ledger                                                 # noqa: PLC0415
+    text = str(prompt or "").strip()[:MAX_PROMPT_CHARS]
+    if not text:
+        return None, "type what you want the automation to do", None
+    kinds = sorted({str(r.get("kind")) for r in (catalog or []) if r.get("ready")})
+    if not kinds:
+        return None, "this deployment offers no automation steps to build with", None
+    trigger_keys = sorted({str(t.get("key")) for t in (triggers or [])
+                           if t.get("key") and not t.get("planned")}) or ["manual"]
+    table_keys = sorted({str(t.get("key")) for t in (tables or []) if t.get("key")}) or [""]
+    tools = [{"type": "function", "function": {
+        "name": "build_automation",
+        "description": "Emit the automation, or refuse.",
+        "parameters": flow_schema(kinds, trigger_keys, table_keys)}}]
+    messages = [{"role": "system",
+                 "content": flow_system_prompt(catalog, required, triggers, tables)},
+                {"role": "user", "content": text}]
+    if chat is not None:
+        # ⚠ THE INJECTED PATH IS THE PROVEN PATH. It runs the SAME parse and the SAME refusal
+        # branches as a live call; only the transport is replaced.
+        draft, refusal = _flow_from_tool_call(chat(messages, tools))
+        return draft, refusal, "injected"
+    provs = flow_providers(model)
+    if not provs:
+        # ⛔ SAY SO. An AI feature that silently does nothing is indistinguishable from one that was
+        # never built [[flag-shipped-without-its-writer]].
+        return None, ("the assistant is not configured on this deployment, so an automation cannot "
+                      "be drafted from a description yet"), None
+    tmo = float(timeout or TIMEOUT_SECONDS)
+    problems = []
+    import providers as _prov
+    for p in provs:
+        # ⭐⭐ W36-T35 / R4 — THE OWNER QUOTED THIS LINE BACK AT US. It used to read
+        # `problems.append(f"{p['name']}: tool calls are not wired for this shape")` and `continue`,
+        # so the sentence *"anthropic: tool calls are not wired for this shape"* appeared under the
+        # Agent module verbatim. R4: *"Anthropic becomes the tool-calling path that always works."*
+        # It is wired now, through the ONE wire in `providers`, and it matters more than it looks:
+        # every side rung on this account is refusing today (cerebras 402, groq 404, openrouter
+        # 402), so without this branch the drafter cannot answer at all.
+        # ⚠ NO `effort` ON THIS DOOR — `output_config.effort` errors on Haiku 4.5, the tier this
+        # ladder runs. The parameter is the caller's to send, which is why the wire takes it.
+        # ⭐ D-346 (W37-T39): BOTH shapes now yield the SAME `(status, body)` pair, so every branch
+        # below reads one thing. The anthropic side gets there through `anthropic_send` (official
+        # SDK when installed, the identical raw POST when not); the openai side still posts here
+        # because there is no shared SDK across three different vendors on that wire.
+        global LAST_ANTHROPIC_TRANSPORT
+        try:
+            if p["shape"] == "anthropic":
+                req = _prov.anthropic_request(
+                    model=p["model"], key=os.environ[p["env"]].strip(), system=None,
+                    messages=messages, tools=tools, max_tokens=1500, tool_choice="required")
+                status, body, transport = _prov.anthropic_send(req, timeout=tmo)
+                LAST_ANTHROPIC_TRANSPORT = transport
+            else:
+                r = requests.post(p["url"], timeout=tmo,
+                                  headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
+                                           "Content-Type": "application/json"},
+                                  json={"model": p["model"], "messages": messages, "tools": tools,
+                                        "tool_choice": "required", "temperature": 0.1,
+                                        "max_tokens": 1500})
+                status = r.status_code
+                body = r.json() if (r.content and r.status_code == 200) else {"_text": r.text}
+        except Exception as e:                                    # noqa: BLE001
+            problems.append(f"{p['name']}: {type(e).__name__}")
+            continue
+        if status != 200:
+            # ⛔ A SENTENCE, NOT `HTTP 402` (R4's third clause). The owner read the status codes off
+            # this very door. `refusal_sentence` also decides whether this was a CREDIT failure, and
+            # the memo makes the next turn SKIP the empty account instead of paying for it again.
+            # ⚠ The body is re-serialised for the substring test because the SDK path never had a
+            # `.text` — that is the one thing this normalisation costs, and it costs nothing else.
+            detail = json.dumps(body)[:600] if isinstance(body, dict) else str(body)[:600]
+            if _prov.is_credit_failure(status, detail):
+                _prov.mark_no_credit(p["name"])
+            problems.append(_prov.refusal_sentence(p["name"], status, detail))
+            continue
+        try:
+            body = body or {}
+            if p["shape"] == "anthropic":
+                _text, args, _refused = _prov.anthropic_read(body)
+                if _refused:
+                    problems.append(f"{p['name']}: {_refused}")
+                    continue
+            else:
+                calls = (((body.get("choices") or [{}])[0].get("message") or {})
+                         .get("tool_calls") or [])
+                args = json.loads(calls[0]["function"]["arguments"]) if calls else None
+        except Exception as e:                                    # noqa: BLE001
+            problems.append(f"{p['name']}: unreadable answer ({type(e).__name__})")
+            continue
+        # ⭐⭐ C7 — THE LEDGER LINE. Placed after the parse rather than before it so an UNREADABLE
+        # answer is not double-counted by the `continue` above... ⚠ which means an unreadable answer
+        # is NOT counted at all, and that is a deliberate, disclosed loss: a body this code cannot
+        # parse is a body whose `usage` it also cannot trust, and `body` is out of scope in that
+        # branch by construction. The 200-with-junk case is rare and named here rather than
+        # silently rounded to zero.
+        ins, outs = usage_ledger.tokens_from(body)
+        usage_ledger.record("automation_draft", p["name"], p["model"], ins, outs,
+                            total=usage_ledger.total_from(body), st=st, user=user)
+        draft, refusal = _flow_from_tool_call(args)
+        if draft is None and isinstance(args, dict) and str(args.get("kind")) == "refused":
+            # ⛔ A REFUSAL IS AN ANSWER, NOT A FAULT, so it does NOT fall through to a more
+            # expensive rung — the model has just said this cannot be built. `decide()` takes the
+            # same posture for the same reason.
+            return None, refusal, p["name"]
+        if draft is not None:
+            return draft, "", p["name"]
+        problems.append(f"{p['name']}: {refusal}")
+    return None, ("; ".join(problems)[:300] or "no provider answered"), None

api/automation_engine.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/connectors_tt.py CHANGED Viewed

@@ -1,568 +1,568 @@
-"""connectors_tt.py — the TIKTOK connector (wave 29 · item 7 · DEBT D-9 · rulings R1 + R2).
-Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
-automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
-exists at all rather than another thousand lines inside the engine.
-⛔ **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema — 40 profile / 43
-post / 17 comment fields, each with the vendor's own type, description and `pii` flag — was read
-live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
-`.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
-close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
-name below reads through a candidate list it is because the vendor has two names for one fact
-(`biography`/`signature`, `region`/`country`), never because the name is uncertain.
-⛔ **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned —
-public data through a supplier, exactly the rail `connectors_ig.py` states for Instagram. The
-vendor key is a key to a SUPPLIER.
-⭐ **THE TRANSPORT IS `connectors_bd.py` — SHARED, VENDOR-NAMED, AND NO LONGER BORROWED FROM THE
-OTHER PLATFORM'S CONNECTOR** (WAVE 30 · T09, DEBT D-128). `bd_call`, `bd_scrape` and
-`bd_filter_start` take the dataset id as a PARAMETER — they are Bright Data's wire, not
-Instagram's — and re-implementing them here would be a second copy of the deferral handling, the
-truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
-Until wave 30 the code was right and the NAME was wrong: this file imported thirteen symbols from
-`connectors_ig`, which read as a dependency on Instagram and was really a dependency on a supplier.
-⚠ **This file now imports ZERO names from `connectors_ig`, and a gate check asserts that**, because
-the sentence above is the kind that quietly stops being true.
-⚠ **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
-  1. the real ROW shape — `/metadata` describes a DATASET, and Instagram's rows carry undeclared
-     envelope keys (`timestamp`, `input`) that no metadata call mentions;
-  2. that a declared field POPULATES — Bright Data's Instagram Reels *declares* `views: number`
-     and delivers an account-grain wrong number (§4e). **Declared is not delivered**, and the one
-     TikTok claim that matters most (`play_count`) is exactly a declaration.
-"""
-from __future__ import annotations
-import automation_engine as engine
-# ⚠ T09 — FOUR NAMES CAME OFF THIS LIST AND NOTHING BROKE, which is the point of deriving an
-# import block from the AST both ways. `bd_call`, `bd_filter_start`, `bd_key` and `bd_ready` were
-# imported here under a comment claiming they were *"re-exported for the runners"*; no runner ever
-# read them off this module (the engine imports them from the transport itself), so they were four
-# lines of dependency nobody was paying for. `[[artifact-with-no-importer]]` in its smallest form.
-from connectors_bd import (
-    _bd_first_url,
-    _bd_flag,
-    _bd_list,
-    _bd_source_payload,
-    _first,
-    _ig_int,
-    bd_scrape,
-)
-# ---------------------------------------------------------------------------------------------
-# THE DATASETS
-# ---------------------------------------------------------------------------------------------
-# ⚠ CATALOGUE PRESENCE IS NOT ENTITLEMENT — the same finding Instagram produced. `GET
-# /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
-# full field list, and the two DISCOVERY halves answer **404 for our key**:
-#   `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
-# ⇒ TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
-# does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
-TT_DS_PROFILES = "gd_l1villgoiiidt09ci"       # TikTok - Profiles. 40 fields, 152,000,000 records
-TT_DS_POSTS = "gd_lu702nij2f790tmv9h"         # TikTok - Posts. 43 fields
-TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k"      # TikTok - Comments. 17 fields
-#: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
-#: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
-TT_POST_TYPE_VIDEO = "video"
-TT_POST_TYPE_CONTENT = "content"
-#: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
-#: beside the dataset ids because it is the same class of vendor fact.
-#: ⚠ ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
-#: string from `_PROFILE_RULES` (contract C2, E's half) — this exists for the connector's own
-#: batch calls, and the gate asserts the two agree rather than trusting that they do.
-TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
-def tt_profile_url(handle):
-    """`nurilab` → `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
-    h = str(handle or "").strip().lstrip("@")
-    return TT_PROFILE_URL.format(handle=h) if h else ""
-# ---------------------------------------------------------------------------------------------
-# THE FIELD MAPS
-# ---------------------------------------------------------------------------------------------
-# Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
-# in `automation_engine`. The rules they all obey, stated once:
-#
-#   * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
-#     so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
-#     returns `None` (never 0) when nothing matches, which is what makes that possible.
-#   * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
-#     rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
-#   * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
-#     vendor's side is preserved rather than silently discarded while our column model catches up.
-#   * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
-#     (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
-#     ride in `source_payload` where they make no claim.
-def _tt_str(node, *names):
-    """The first non-empty string among `names`, or None when the vendor sent nothing.
-    ⛔ `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest —
-    an empty string written into a cell claims "we looked and it is empty".
-    """
-    v = _first(node, *names)
-    if v is None:
-        return None
-    s = str(v).strip()
-    return s or None
-def _tt_pct(node, *names):
-    """A vendor 0–1 engagement fraction → our stored 0–100 percentage, or None.
-    ⛔ THE ×100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
-    the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` —
-    measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
-    """
-    v = _first(node, *names)
-    if v is None:
-        return None
-    out = engine._pct100(v)
-    return out or None
-def _tt_day(node, *names):
-    """A vendor stamp → `YYYY-MM-DD`, or None. Our `date` columns store a day."""
-    v = _first(node, *names)
-    if v is None:
-        return None
-    return engine._day(v) or None
-def _drop_blanks(row):
-    """The one place a mapped row loses its `None`s — see the BLANK MEANS NOT READ rule above."""
-    return {k: v for k, v in row.items() if v is not None and v != ""}
-def normalize_profile(node, handle=""):
-    """A TikTok Profiles row → the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
-    ⚠ TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
-      * `biography` is PRIMARY and `signature` the FALLBACK — the probe measured `signature`
-        populated on 85% of rows and they carry the same text;
-      * `region` is PRIMARY and `country` the FALLBACK — `region` is the one with a documented
-        two-letter-ISO description, `country` has no description at all.
-    ⚠ `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
-    `ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
-    only count of its kind the dataset offers.
-    """
-    node = node if isinstance(node, dict) else {}
-    account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
-    return _drop_blanks({
-        "platform": engine.PLATFORM_TIKTOK,
-        "handle": account,
-        "full_name": _tt_str(node, "nickname"),
-        "tt_id": _tt_str(node, "id"),
-        "profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
-        "bio": _tt_str(node, "biography", "signature"),
-        "external_url": _bd_first_url(_first(node, "bio_link")),
-        "verified": _bd_flag(node, "is_verified"),
-        "is_private": _bd_flag(node, "is_private"),
-        # ⚠ APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
-        # on their own description. It is the closest thing TikTok has to Instagram's
-        # `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent — so
-        # the approximation only ever fills a cell the vendor actually answered.
-        "is_business": _bd_flag(node, "is_commerce_user"),
-        "followers": _ig_int(_first(node, "followers")),
-        "following": _ig_int(_first(node, "following")),
-        "posts_count": _ig_int(_first(node, "videos_count")),
-        # ⚠ `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
-        # nulls). It is not a post-level number and it is not our `likes` column, which is why it
-        # is stored under a different name.
-        "likes_received": _ig_int(_first(node, "likes")),
-        "avg_engagement": _tt_pct(node, "awg_engagement_rate"),
-        "like_engagement": _tt_pct(node, "like_engagement_rate"),
-        "comment_engagement": _tt_pct(node, "comment_engagement_rate"),
-        "country_code": _tt_str(node, "region", "country"),
-        "region": _tt_str(node, "region"),
-        "predicted_lang": _tt_str(node, "predicted_lang"),
-        # ⚠ ACCOUNT AGE, NOT A MEASUREMENT STAMP — `create_time` on a profile is when the ACCOUNT
-        # was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
-        # which is why the append law dates a snapshot by when WE read it.
-        "account_created_at": _tt_day(node, "create_time"),
-        "source_payload": _bd_source_payload(node),
-    })
-def tt_post_type(node):
-    """A TikTok post row → one of OUR three type options, or None.
-    ⛔ THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
-    `"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
-    vendor's token would fail `_clean_field`'s option check on the way in and would put an
-    untranslated API word in front of a user on the way out.
-    So: `video` is `video`, and `content` — TikTok's photo-mode post — is `image`, EXCEPT when the
-    row carries more than one `carousel_images` entry, which is what a carousel IS on either
-    network. ⚠ The multi-image branch is decided from the IMAGES, never from the type token: the
-    token cannot express it, so inferring `carousel` from the word would be inventing a fact.
-    ⚠ An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
-    that is exactly what would make the wrong default invisible).
-    """
-    raw = str((node or {}).get("post_type") or "").strip().lower()
-    if raw == TT_POST_TYPE_VIDEO:
-        return "video"
-    if raw != TT_POST_TYPE_CONTENT:
-        return None
-    images = (node or {}).get("carousel_images")
-    return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
-def normalize_post(node):
-    """A TikTok Posts row → the `ut_tt_posts` cell shape. None when it carries no identity.
-    ⛔ THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
-    Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
-    fact — `play_count` IS the count TikTok displays under a video — so it maps to `views` and
-    `ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
-    manufacture a second measurement that a rollup could average or double-count, which is a worse
-    outcome than the missing column it would paper over.
-    ⚠ `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
-    the probe measured them as the same shape. That equality is what lets the comments→posts link
-    join with NO normaliser, which the Instagram side never had.
-    ⚠ `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
-    ⚠ `commerce_info` is a business/commerce LOCATION per its own description — cities and
-    countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
-    no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
-    """
-    node = node if isinstance(node, dict) else {}
-    shortcode = _tt_str(node, "shortcode", "post_id")
-    if not shortcode:
-        return None
-    return _drop_blanks({
-        "platform": engine.PLATFORM_TIKTOK,
-        "shortcode": shortcode,
-        # ⛔⛔ `account_id`, NOT `profile_username` — MEASURED on a real Posts row 2026-08-12.
-        # The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
-        # @handle (`"d1na_th"`) — the same field `normalize_profile` already reads for `handle`, so
-        # one name means one thing across both corpora. Reading the display name silently broke the
-        # only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
-        # NOTHING, so a person could not filter posts by creator and a rollup would count zero.
-        # ⚠ NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
-        # different fact, and filling a join key with it is worse than leaving it blank — a blank
-        # is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
-        # The URL is the honest second source: it carries the handle by construction.
-        "influencer_key": (_tt_str(node, "account_id")
-                           or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
-        "posted_at": _tt_day(node, "create_time"),
-        "type": tt_post_type(node),
-        "caption": _tt_str(node, "description"),
-        "url": _tt_str(node, "url"),
-        "hashtags": _bd_list(node, "hashtags"),
-        "tagged_location": _tt_str(node, "commerce_info"),
-        "views": _ig_int(_first(node, "play_count")),
-        "likes": _ig_int(_first(node, "digg_count")),
-        "comments": _ig_int(_first(node, "comment_count")),
-        "shares": _ig_int(_first(node, "num_share_count")),
-        "saves": _ig_int(_first(node, "collect_count")),
-        "video_duration": _ig_int(_first(node, "video_duration")),
-        "source_payload": _bd_source_payload(node),
-    })
-def normalize_comment(node):
-    """A TikTok Comments row → the `ut_tt_comments` cell shape. None without a comment id.
-    ⚠ THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
-    `replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
-    `source_payload`. Reading the array's length instead would be a second, disagreeing answer to
-    a question the vendor already answers — and it would disagree, because a page of replies is not
-    all of them.
-    ⚠ `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
-    text and needs defensive parsing. It still goes through `_tt_day` — one date path, so a vendor
-    that changes its mind cannot change ours.
-    ⚠ The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
-    PII) stay in `source_payload` and are promoted to no column, which is the same posture the
-    Instagram comment schema takes for the same D-24 reason.
-    """
-    node = node if isinstance(node, dict) else {}
-    comment_key = _tt_str(node, "comment_id")
-    if not comment_key:
-        return None
-    return _drop_blanks({
-        "platform": engine.PLATFORM_TIKTOK,
-        "comment_key": comment_key,
-        "shortcode": _tt_str(node, "post_id"),
-        # ⭐⭐ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
-        # vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
-        # primary first, so a row carrying the rich form is not silently served the plain one.
-        # ⛔ The commenter's identity is deliberately NOT promoted — see `TT_COMMENT_FIELDS`.
-        "text": _tt_str(node, "comment_text", "comment_text_only"),
-        "commented_at": _tt_day(node, "date_created"),
-        "likes": _ig_int(_first(node, "num_likes")),
-        "replies": _ig_int(_first(node, "num_replies")),
-        "source_payload": _bd_source_payload(node),
-    })
-#: ⭐ The three maps, addressable by name — so a gate (and the runners in T04-T06) can walk them
-#: rather than naming three functions, and so adding a fourth dataset is one entry.
-TT_NORMALIZERS = {
-    "tt_profile": normalize_profile,
-    "tt_post_metrics": normalize_post,
-    "tt_comments": normalize_comment,
-}
-# ---------------------------------------------------------------------------------------------
-# THE FETCH — wave 30 · W30-T08 (carrying wave-29's dropped T05)
-# ---------------------------------------------------------------------------------------------
-def tt_handle(url):
-    """A TikTok profile URL **or** a bare handle → the handle. `''` when it is neither.
-    Deliberately permissive about the input and strict about the output, because the two callers
-    hand it different things: an automation stores whatever a person typed in the profile column
-    (`@nurilab`, `nurilab`, or the full URL), while the discovery runner already holds a clean
-    `account_id`. One normaliser, so a row found by discovery and a row typed by hand cannot
-    resolve to two different handles.
-    """
-    s = str(url or "").strip()
-    if not s:
-        return ""
-    if "tiktok.com" in s.lower():
-        # Everything after the first `@`, up to the next path segment or query.
-        tail = s.split("@", 1)[1] if "@" in s else ""
-        s = tail.split("/")[0].split("?")[0].split("#")[0]
-    s = s.strip().lstrip("@").strip()
-    # A handle is the vendor's `account_id` shape: alphanumerics, dots and underscores.
-    return s if s and all(c.isalnum() or c in "._" for c in s) else ""
-def tt_post_urls(node, limit=0):
-    """⭐ WAVE 30 · T10 — the profile row's own post permalinks, newest-first as the vendor sends.
-    ⛔ THIS IS WHY TIKTOK POST CAPTURE COSTS NO EXTRA DISCOVERY. `top_videos` rides the PROFILE row
-    we have already bought, so the posts read is a scrape of links we hold, never a search for them.
-    The two TikTok DISCOVERY datasets (posts-by-profile, posts-by-keyword) are **404 for our key**,
-    so a design that reached for either would not merely be dearer, it would not work.
-    ⛔⛔ CORRECTED 2026-08-12 — THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
-    array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
-    read `/datasets/{id}/metadata` — a DATASET description — and the phrase quoted was the field's
-    `ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
-    (measured below), so the reader built against the quoted sentence found nothing, forever, in
-    silence. ⭐ The transferable half: *"the probe measured X"* and *"the probe read a declaration
-    of X"* are different claims, and prose cannot be told apart by a reader downstream — which is
-    why the correction names the method, not just the value.
-    ⚠ `top_posts_data` is deliberately NOT read: the probe calls it *"a thin dup of `top_videos`"*,
-    and preferring whichever happened to be longer is how one creator's window silently differs
-    from another's.
-    ⚠ `limit <= 0` means "everything the row carried". The CAP IS THE CALLER'S — `config.maxPosts`,
-    validated 1..12 — and it is applied here rather than after the scrape so an unwanted post is
-    never bought. [[a-constant-two-features-share]]: the 12 is the vendor's measured profile window,
-    not a number this function may invent.
-    """
-    raw = (node or {}).get("top_videos")
-    out = []
-    for item in raw if isinstance(raw, list) else []:
-        # ⛔⛔ MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
-        # `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
-        # live handle returns **19 DICTS**, keyed
-        # `video_url · video_id · playcount · diggcount · commentcount · share_count ·
-        #  favorites_count · create_date · cover_image`.
-        # The docstring above cites the $0 probe as having "measured" permalinks — it had not, and
-        # could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
-        # so in terms (*"what $0 cannot buy … the real ROW shape … that a declared field
-        # POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
-        # declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
-        # the first. [[reachable-is-not-the-same-as-built]]
-        # ⇒ The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
-        # list on every real profile — post capture could not have worked for anybody, and the
-        # T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
-        # written from a schema tests the schema.
-        # ⚠ `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
-        # because it costs nothing and is what a future corpus revision would most likely use. The
-        # bare-string branch stays for the same reason — this widens what is ACCEPTED and invents
-        # nothing: a shape that yields no `http…` value still degrades to "no posts", exactly as
-        # before, rather than to a URL built out of a guess.
-        # ⚠ `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
-        # whichever array happened to be longer is how one creator's window silently differs from
-        # another's, and that reasoning is unchanged by this correction.
-        if isinstance(item, dict):
-            u = str(item.get("video_url") or item.get("url") or "").strip()
-        else:
-            u = str(item or "").strip()
-        if u.lower().startswith("http") and u not in out:
-            out.append(u)
-    return out[:limit] if limit and limit > 0 else out
-def pull_posts_tt(post_urls, log=print, deferred=None):
-    """The TikTok Posts dataset for a list of permalinks → `(rows, note)`, already normalised.
-    ⚠ ONE CALL FOR THE WHOLE WINDOW. `bd_scrape` has always taken a list, and the Instagram side
-    measured what happens when a caller forgets: 25 records, one billed snapshot each, a walk still
-    running at 67 minutes. Nothing here loops per URL.
-    """
-    urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
-    if not urls:
-        return [], ""
-    rows, note = bd_scrape(TT_DS_POSTS, urls, deferred=deferred)
-    if note:
-        log(f"[aios-tt] posts: {note}")
-        return [], note
-    out = [r for r in (normalize_post(n) for n in rows) if r]
-    return out, ""
-def pull_comments_tt(post_urls, log=print, deferred=None):
-    """The TikTok Comments dataset for a list of POST permalinks → `(rows, note)`, normalised.
-    ⛔ THE MOST EXPENSIVE THING THIS PRODUCT BUYS, and the reason `commentMetrics` defaults OFF on
-    both networks: a comments scrape ingests identifiable third parties who never entered anybody's
-    list (D-24). The mapper already keeps every commenter field in `source_payload` and promotes
-    none of them to a column; this function adds no new exposure, it just has to be asked for.
-    """
-    urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
-    if not urls:
-        return [], ""
-    rows, note = bd_scrape(TT_DS_COMMENTS, urls, deferred=deferred)
-    if note:
-        log(f"[aios-tt] comments: {note}")
-        return [], note
-    out = [r for r in (normalize_comment(n) for n in rows) if r]
-    return out, ""
-#: ⭐⭐ WAVE 30 · D-156 — THE MEDIA DATASETS, AS A SET, SO THE HAND-OFF CAN FILTER ON IDENTITY.
-#: `_media_deferrals` uses this to lift ONLY posts/comments snapshots out of the local deferral
-#: list. That is what makes it structurally impossible to file a PROFILE snapshot in the engine's
-#: metric queue — the defect a draft of T10 shipped and A-39 booked as "the wrong fix is worse
-#: than the gap". A membership test cannot be got wrong by a later edit the way `if` order can.
-TT_MEDIA_DATASETS = (TT_DS_POSTS, TT_DS_COMMENTS)
-def _media_deferrals(deferred):
-    """The POSTS/COMMENTS entries of a `bd_scrape` deferral list — never the profile's.
-    ⚠ The engine, not this module, decides what a deferral MEANS: it stamps `kind` and the
-    handle and files it. TikTok needs no `_tag_metric_deferrals` twin because one dataset is one
-    kind here, so the id already carries everything a mapper choice depends on — and importing
-    Instagram's tagger is not available anyway (W30-T09 gates ZERO `from connectors_ig` lines).
-    """
-    out = []
-    for d in deferred or []:
-        if isinstance(d, dict) and str(d.get("datasetId") or "") in TT_MEDIA_DATASETS:
-            out.append(dict(d))
-    return out
-def pull_profile_tt(url, log=print, pending_profile=None, prefetch=None,
-                    max_posts=0, post_metrics=False, comment_metrics=False):
-    """ONE TikTok profile from the vendor. Same return contract as `pull_profile`.
-    `{state, profile, posts, comments, via, note}` with `state ∈ ok | partial | blocked | error`,
-    so the engine's enrich branch treats every network identically and no caller learns a new
-    shape.
-    ⭐ WAVE 30 · T10 — POSTS AND COMMENTS ARE REAL NOW, AND BOTH DEFAULT OFF, exactly as Instagram's
-    do. `post_metrics` scrapes the profile row's own `top_videos` permalinks (see `tt_post_urls` —
-    no discovery call, because both TikTok discovery datasets 404 for our key); `comment_metrics`
-    then scrapes the comments of the posts that came back. ⚠ COMMENTS REQUIRE POSTS by construction
-    rather than by a rule: their input IS a post permalink, so asking for comments with post capture
-    off is a request with no subject, and it returns none instead of quietly buying posts nobody
-    asked for.
-    ⛔ `partial` IS THE SUCCESS STATE WHENEVER NO MEDIA WAS READ, and that is deliberate rather than
-    pessimistic. The Instagram contract reads `ok` only when identity AND media both landed
-    (`pull_profile_bd`: *"identity without media is still partial ... a run that wrote a follower
-    count and no posts must not paint green over a posts table that did not grow"*). So: posts not
-    ASKED for → `partial`, saying so; posts asked for and landed → `ok`; asked for and none came →
-    `partial` with the vendor's reason. The state answers "did this pull deliver what it went for",
-    never "did the function finish".
-    ⚠ **NO FREE RUNG, AND NO FALLBACK CHAIN.** Instagram's `pull_profile` drops to Apify when the
-    paid rung refuses; `providers.DEFAULT_CHAINS["tt_profile"]` is deliberately single-provider,
-    with its own note explaining that a multi-provider chain is a promise something walks it and
-    that nothing walks Instagram's second name today either. So a refusal here is final, and it
-    says so instead of implying a retry somewhere.
-    """
-    handle = tt_handle(url)
-    if not handle:
-        return {"state": "error", "profile": {}, "posts": [], "comments": [], "via": "",
-                "note": f"{url!r} is not a TikTok profile URL or handle"}
-    # ⭐ THE BATCH FAST PATH, same shape as the Instagram side: `prefetch` is `{handle: node}` from
-    # one multi-URL scrape covering a whole selection. A hit is a vendor round trip that does not
-    # happen; a miss falls through to the single-URL call below.
-    cached = prefetch.get(handle) if isinstance(prefetch, dict) else None
-    _deferred = []
-    if isinstance(cached, dict) and cached:
-        rows, note = [cached], ""
-    else:
-        rows, note = bd_scrape(TT_DS_PROFILES, [tt_profile_url(handle)], deferred=_deferred)
-    node = rows[0] if rows else {}
-    profile = normalize_profile(node, handle) if node else {}
-    # ⛔ THE READABILITY TEST IS `followers`/`following`, NOT "did we get a dict". `normalize_profile`
-    # drops blanks, so an unreadable row still returns `{"platform": …, "handle": …}` — truthy, and
-    # carrying nothing anybody asked for. The Instagram rung tests exactly this pair for exactly
-    # this reason, and answering "0 followers" instead is the failure it exists to prevent.
-    unreadable = profile.get("followers") is None and profile.get("following") is None
-    if note or unreadable:
-        # ⭐ THE DEFERRAL IS HANDED OVER RATHER THAN DISCARDED. A snapshot the vendor is still
-        # building HAS ALREADY BEEN PAID FOR; dropping its id bills again on the next run for the
-        # same record. That was live on the Instagram profile path until 2026-08-09 — measured on
-        # nurilab as two runs, two fresh snapshots, both abandoned — and it is not being
-        # reintroduced here by omission.
-        if isinstance(pending_profile, list):
-            for d in _deferred:
-                pending_profile.append({**d, "kind": "profile", "influencer": handle})
-        why = note or ("the scrape answered, but no follower/following counts were readable in it "
-                       "(the field names may have moved - see tiktok-capture.md)")
-        return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
-                "deferredProfile": [d.get("snapshotId") for d in _deferred],
-                "note": why}
-    # --- W30-T10: THE MEDIA, ONLY WHEN IT WAS ASKED FOR. ------------------------------------
-    if not post_metrics:
-        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
-                "via": "brightdata",
-                "note": note or "profile read; post capture is off for this step"}
-    urls = tt_post_urls(node, limit=max_posts)
-    if not urls:
-        # ⚠ NOT AN ERROR AND NOT A RETRY. A creator with no `top_videos` has nothing to buy, and
-        # saying so is what stops the next run paying to be told the same thing.
-        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
-                "via": "brightdata",
-                "note": note or "profile read; this account's row carried no post links"}
-    posts, p_note = pull_posts_tt(urls, log=log, deferred=_deferred)
-    comments, c_note = ([], "")
-    if comment_metrics and posts:
-        # The comments dataset is keyed on a POST permalink, so it reads the posts we just bought —
-        # `url` from the mapper, never the profile's raw array, so a post the posts scrape refused
-        # is not silently asked about again one rung later.
-        comments, c_note = pull_comments_tt([p.get("url") for p in posts if p.get("url")],
-                                            log=log, deferred=_deferred)
-    # ⭐⭐ WAVE 30 · D-156 — THE MEDIA DEFERRALS ARE HANDED BACK, and the shape of the hand-off is
-    # the whole lesson. An earlier draft of T10 appended every `_deferred` entry to
-    # `pending_profile` tagged `kind: "profile"`. By the time control reaches here a PROFILE
-    # deferral is impossible — the profile branch above returns `blocked` on any note — so **every
-    # id fanned out that way was a POSTS or COMMENTS snapshot in the PROFILE queue**, whose
-    # collector writes preset profile cells onto somebody's record from post rows. The engine keeps
-    # the two queues apart deliberately (`_pending_profile_tasks` vs `_pending_metric_tasks`).
-    # ⇒ So this returns them under their OWN key, filtered by dataset identity
-    # (`_media_deferrals`), and the engine files them in the metric queue with the handle it
-    # already holds. Returning rather than appending also keeps the queue's vocabulary out of a
-    # connector: this module knows which CORPUS deferred, never what the engine calls it.
-    # ⚠ `deferredMedia` rides BOTH returns on purpose. The empty-posts case is the one that
-    # matters most — that is exactly the run where the vendor took too long, so a caller reading
-    # the ids only from the success path would lose every batch it actually paid for.
-    deferred_media = _media_deferrals(_deferred)
-    if not posts:
-        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
-                "via": "brightdata", "deferredMedia": deferred_media,
-                "note": p_note or note or "profile read; the post source returned nothing"}
-    return {"state": "ok", "profile": profile, "posts": posts, "comments": comments,
-            "via": "brightdata", "deferredMedia": deferred_media,
-            "note": c_note or note or ""}

+"""connectors_tt.py — the TIKTOK connector (wave 29 · item 7 · DEBT D-9 · rulings R1 + R2).
+Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
+automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
+exists at all rather than another thousand lines inside the engine.
+⛔ **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema — 40 profile / 43
+post / 17 comment fields, each with the vendor's own type, description and `pii` flag — was read
+live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
+`.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
+close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
+name below reads through a candidate list it is because the vendor has two names for one fact
+(`biography`/`signature`, `region`/`country`), never because the name is uncertain.
+⛔ **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned —
+public data through a supplier, exactly the rail `connectors_ig.py` states for Instagram. The
+vendor key is a key to a SUPPLIER.
+⭐ **THE TRANSPORT IS `connectors_bd.py` — SHARED, VENDOR-NAMED, AND NO LONGER BORROWED FROM THE
+OTHER PLATFORM'S CONNECTOR** (WAVE 30 · T09, DEBT D-128). `bd_call`, `bd_scrape` and
+`bd_filter_start` take the dataset id as a PARAMETER — they are Bright Data's wire, not
+Instagram's — and re-implementing them here would be a second copy of the deferral handling, the
+truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
+Until wave 30 the code was right and the NAME was wrong: this file imported thirteen symbols from
+`connectors_ig`, which read as a dependency on Instagram and was really a dependency on a supplier.
+⚠ **This file now imports ZERO names from `connectors_ig`, and a gate check asserts that**, because
+the sentence above is the kind that quietly stops being true.
+⚠ **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
+  1. the real ROW shape — `/metadata` describes a DATASET, and Instagram's rows carry undeclared
+     envelope keys (`timestamp`, `input`) that no metadata call mentions;
+  2. that a declared field POPULATES — Bright Data's Instagram Reels *declares* `views: number`
+     and delivers an account-grain wrong number (§4e). **Declared is not delivered**, and the one
+     TikTok claim that matters most (`play_count`) is exactly a declaration.
+"""
+from __future__ import annotations
+import automation_engine as engine
+# ⚠ T09 — FOUR NAMES CAME OFF THIS LIST AND NOTHING BROKE, which is the point of deriving an
+# import block from the AST both ways. `bd_call`, `bd_filter_start`, `bd_key` and `bd_ready` were
+# imported here under a comment claiming they were *"re-exported for the runners"*; no runner ever
+# read them off this module (the engine imports them from the transport itself), so they were four
+# lines of dependency nobody was paying for. `[[artifact-with-no-importer]]` in its smallest form.
+from connectors_bd import (
+    _bd_first_url,
+    _bd_flag,
+    _bd_list,
+    _bd_source_payload,
+    _first,
+    _ig_int,
+    bd_scrape,
+)
+# ---------------------------------------------------------------------------------------------
+# THE DATASETS
+# ---------------------------------------------------------------------------------------------
+# ⚠ CATALOGUE PRESENCE IS NOT ENTITLEMENT — the same finding Instagram produced. `GET
+# /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
+# full field list, and the two DISCOVERY halves answer **404 for our key**:
+#   `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
+# ⇒ TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
+# does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
+TT_DS_PROFILES = "gd_l1villgoiiidt09ci"       # TikTok - Profiles. 40 fields, 152,000,000 records
+TT_DS_POSTS = "gd_lu702nij2f790tmv9h"         # TikTok - Posts. 43 fields
+TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k"      # TikTok - Comments. 17 fields
+#: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
+#: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
+TT_POST_TYPE_VIDEO = "video"
+TT_POST_TYPE_CONTENT = "content"
+#: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
+#: beside the dataset ids because it is the same class of vendor fact.
+#: ⚠ ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
+#: string from `_PROFILE_RULES` (contract C2, E's half) — this exists for the connector's own
+#: batch calls, and the gate asserts the two agree rather than trusting that they do.
+TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
+def tt_profile_url(handle):
+    """`nurilab` → `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
+    h = str(handle or "").strip().lstrip("@")
+    return TT_PROFILE_URL.format(handle=h) if h else ""
+# ---------------------------------------------------------------------------------------------
+# THE FIELD MAPS
+# ---------------------------------------------------------------------------------------------
+# Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
+# in `automation_engine`. The rules they all obey, stated once:
+#
+#   * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
+#     so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
+#     returns `None` (never 0) when nothing matches, which is what makes that possible.
+#   * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
+#     rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
+#   * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
+#     vendor's side is preserved rather than silently discarded while our column model catches up.
+#   * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
+#     (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
+#     ride in `source_payload` where they make no claim.
+def _tt_str(node, *names):
+    """The first non-empty string among `names`, or None when the vendor sent nothing.
+    ⛔ `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest —
+    an empty string written into a cell claims "we looked and it is empty".
+    """
+    v = _first(node, *names)
+    if v is None:
+        return None
+    s = str(v).strip()
+    return s or None
+def _tt_pct(node, *names):
+    """A vendor 0–1 engagement fraction → our stored 0–100 percentage, or None.
+    ⛔ THE ×100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
+    the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` —
+    measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
+    """
+    v = _first(node, *names)
+    if v is None:
+        return None
+    out = engine._pct100(v)
+    return out or None
+def _tt_day(node, *names):
+    """A vendor stamp → `YYYY-MM-DD`, or None. Our `date` columns store a day."""
+    v = _first(node, *names)
+    if v is None:
+        return None
+    return engine._day(v) or None
+def _drop_blanks(row):
+    """The one place a mapped row loses its `None`s — see the BLANK MEANS NOT READ rule above."""
+    return {k: v for k, v in row.items() if v is not None and v != ""}
+def normalize_profile(node, handle=""):
+    """A TikTok Profiles row → the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
+    ⚠ TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
+      * `biography` is PRIMARY and `signature` the FALLBACK — the probe measured `signature`
+        populated on 85% of rows and they carry the same text;
+      * `region` is PRIMARY and `country` the FALLBACK — `region` is the one with a documented
+        two-letter-ISO description, `country` has no description at all.
+    ⚠ `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
+    `ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
+    only count of its kind the dataset offers.
+    """
+    node = node if isinstance(node, dict) else {}
+    account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
+    return _drop_blanks({
+        "platform": engine.PLATFORM_TIKTOK,
+        "handle": account,
+        "full_name": _tt_str(node, "nickname"),
+        "tt_id": _tt_str(node, "id"),
+        "profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
+        "bio": _tt_str(node, "biography", "signature"),
+        "external_url": _bd_first_url(_first(node, "bio_link")),
+        "verified": _bd_flag(node, "is_verified"),
+        "is_private": _bd_flag(node, "is_private"),
+        # ⚠ APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
+        # on their own description. It is the closest thing TikTok has to Instagram's
+        # `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent — so
+        # the approximation only ever fills a cell the vendor actually answered.
+        "is_business": _bd_flag(node, "is_commerce_user"),
+        "followers": _ig_int(_first(node, "followers")),
+        "following": _ig_int(_first(node, "following")),
+        "posts_count": _ig_int(_first(node, "videos_count")),
+        # ⚠ `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
+        # nulls). It is not a post-level number and it is not our `likes` column, which is why it
+        # is stored under a different name.
+        "likes_received": _ig_int(_first(node, "likes")),
+        "avg_engagement": _tt_pct(node, "awg_engagement_rate"),
+        "like_engagement": _tt_pct(node, "like_engagement_rate"),
+        "comment_engagement": _tt_pct(node, "comment_engagement_rate"),
+        "country_code": _tt_str(node, "region", "country"),
+        "region": _tt_str(node, "region"),
+        "predicted_lang": _tt_str(node, "predicted_lang"),
+        # ⚠ ACCOUNT AGE, NOT A MEASUREMENT STAMP — `create_time` on a profile is when the ACCOUNT
+        # was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
+        # which is why the append law dates a snapshot by when WE read it.
+        "account_created_at": _tt_day(node, "create_time"),
+        "source_payload": _bd_source_payload(node),
+    })
+def tt_post_type(node):
+    """A TikTok post row → one of OUR three type options, or None.
+    ⛔ THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
+    `"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
+    vendor's token would fail `_clean_field`'s option check on the way in and would put an
+    untranslated API word in front of a user on the way out.
+    So: `video` is `video`, and `content` — TikTok's photo-mode post — is `image`, EXCEPT when the
+    row carries more than one `carousel_images` entry, which is what a carousel IS on either
+    network. ⚠ The multi-image branch is decided from the IMAGES, never from the type token: the
+    token cannot express it, so inferring `carousel` from the word would be inventing a fact.
+    ⚠ An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
+    that is exactly what would make the wrong default invisible).
+    """
+    raw = str((node or {}).get("post_type") or "").strip().lower()
+    if raw == TT_POST_TYPE_VIDEO:
+        return "video"
+    if raw != TT_POST_TYPE_CONTENT:
+        return None
+    images = (node or {}).get("carousel_images")
+    return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
+def normalize_post(node):
+    """A TikTok Posts row → the `ut_tt_posts` cell shape. None when it carries no identity.
+    ⛔ THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
+    Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
+    fact — `play_count` IS the count TikTok displays under a video — so it maps to `views` and
+    `ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
+    manufacture a second measurement that a rollup could average or double-count, which is a worse
+    outcome than the missing column it would paper over.
+    ⚠ `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
+    the probe measured them as the same shape. That equality is what lets the comments→posts link
+    join with NO normaliser, which the Instagram side never had.
+    ⚠ `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
+    ⚠ `commerce_info` is a business/commerce LOCATION per its own description — cities and
+    countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
+    no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
+    """
+    node = node if isinstance(node, dict) else {}
+    shortcode = _tt_str(node, "shortcode", "post_id")
+    if not shortcode:
+        return None
+    return _drop_blanks({
+        "platform": engine.PLATFORM_TIKTOK,
+        "shortcode": shortcode,
+        # ⛔⛔ `account_id`, NOT `profile_username` — MEASURED on a real Posts row 2026-08-12.
+        # The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
+        # @handle (`"d1na_th"`) — the same field `normalize_profile` already reads for `handle`, so
+        # one name means one thing across both corpora. Reading the display name silently broke the
+        # only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
+        # NOTHING, so a person could not filter posts by creator and a rollup would count zero.
+        # ⚠ NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
+        # different fact, and filling a join key with it is worse than leaving it blank — a blank
+        # is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
+        # The URL is the honest second source: it carries the handle by construction.
+        "influencer_key": (_tt_str(node, "account_id")
+                           or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
+        "posted_at": _tt_day(node, "create_time"),
+        "type": tt_post_type(node),
+        "caption": _tt_str(node, "description"),
+        "url": _tt_str(node, "url"),
+        "hashtags": _bd_list(node, "hashtags"),
+        "tagged_location": _tt_str(node, "commerce_info"),
+        "views": _ig_int(_first(node, "play_count")),
+        "likes": _ig_int(_first(node, "digg_count")),
+        "comments": _ig_int(_first(node, "comment_count")),
+        "shares": _ig_int(_first(node, "num_share_count")),
+        "saves": _ig_int(_first(node, "collect_count")),
+        "video_duration": _ig_int(_first(node, "video_duration")),
+        "source_payload": _bd_source_payload(node),
+    })
+def normalize_comment(node):
+    """A TikTok Comments row → the `ut_tt_comments` cell shape. None without a comment id.
+    ⚠ THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
+    `replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
+    `source_payload`. Reading the array's length instead would be a second, disagreeing answer to
+    a question the vendor already answers — and it would disagree, because a page of replies is not
+    all of them.
+    ⚠ `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
+    text and needs defensive parsing. It still goes through `_tt_day` — one date path, so a vendor
+    that changes its mind cannot change ours.
+    ⚠ The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
+    PII) stay in `source_payload` and are promoted to no column, which is the same posture the
+    Instagram comment schema takes for the same D-24 reason.
+    """
+    node = node if isinstance(node, dict) else {}
+    comment_key = _tt_str(node, "comment_id")
+    if not comment_key:
+        return None
+    return _drop_blanks({
+        "platform": engine.PLATFORM_TIKTOK,
+        "comment_key": comment_key,
+        "shortcode": _tt_str(node, "post_id"),
+        # ⭐⭐ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
+        # vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
+        # primary first, so a row carrying the rich form is not silently served the plain one.
+        # ⛔ The commenter's identity is deliberately NOT promoted — see `TT_COMMENT_FIELDS`.
+        "text": _tt_str(node, "comment_text", "comment_text_only"),
+        "commented_at": _tt_day(node, "date_created"),
+        "likes": _ig_int(_first(node, "num_likes")),
+        "replies": _ig_int(_first(node, "num_replies")),
+        "source_payload": _bd_source_payload(node),
+    })
+#: ⭐ The three maps, addressable by name — so a gate (and the runners in T04-T06) can walk them
+#: rather than naming three functions, and so adding a fourth dataset is one entry.
+TT_NORMALIZERS = {
+    "tt_profile": normalize_profile,
+    "tt_post_metrics": normalize_post,
+    "tt_comments": normalize_comment,
+}
+# ---------------------------------------------------------------------------------------------
+# THE FETCH — wave 30 · W30-T08 (carrying wave-29's dropped T05)
+# ---------------------------------------------------------------------------------------------
+def tt_handle(url):
+    """A TikTok profile URL **or** a bare handle → the handle. `''` when it is neither.
+    Deliberately permissive about the input and strict about the output, because the two callers
+    hand it different things: an automation stores whatever a person typed in the profile column
+    (`@nurilab`, `nurilab`, or the full URL), while the discovery runner already holds a clean
+    `account_id`. One normaliser, so a row found by discovery and a row typed by hand cannot
+    resolve to two different handles.
+    """
+    s = str(url or "").strip()
+    if not s:
+        return ""
+    if "tiktok.com" in s.lower():
+        # Everything after the first `@`, up to the next path segment or query.
+        tail = s.split("@", 1)[1] if "@" in s else ""
+        s = tail.split("/")[0].split("?")[0].split("#")[0]
+    s = s.strip().lstrip("@").strip()
+    # A handle is the vendor's `account_id` shape: alphanumerics, dots and underscores.
+    return s if s and all(c.isalnum() or c in "._" for c in s) else ""
+def tt_post_urls(node, limit=0):
+    """⭐ WAVE 30 · T10 — the profile row's own post permalinks, newest-first as the vendor sends.
+    ⛔ THIS IS WHY TIKTOK POST CAPTURE COSTS NO EXTRA DISCOVERY. `top_videos` rides the PROFILE row
+    we have already bought, so the posts read is a scrape of links we hold, never a search for them.
+    The two TikTok DISCOVERY datasets (posts-by-profile, posts-by-keyword) are **404 for our key**,
+    so a design that reached for either would not merely be dearer, it would not work.
+    ⛔⛔ CORRECTED 2026-08-12 — THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
+    array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
+    read `/datasets/{id}/metadata` — a DATASET description — and the phrase quoted was the field's
+    `ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
+    (measured below), so the reader built against the quoted sentence found nothing, forever, in
+    silence. ⭐ The transferable half: *"the probe measured X"* and *"the probe read a declaration
+    of X"* are different claims, and prose cannot be told apart by a reader downstream — which is
+    why the correction names the method, not just the value.
+    ⚠ `top_posts_data` is deliberately NOT read: the probe calls it *"a thin dup of `top_videos`"*,
+    and preferring whichever happened to be longer is how one creator's window silently differs
+    from another's.
+    ⚠ `limit <= 0` means "everything the row carried". The CAP IS THE CALLER'S — `config.maxPosts`,
+    validated 1..12 — and it is applied here rather than after the scrape so an unwanted post is
+    never bought. [[a-constant-two-features-share]]: the 12 is the vendor's measured profile window,
+    not a number this function may invent.
+    """
+    raw = (node or {}).get("top_videos")
+    out = []
+    for item in raw if isinstance(raw, list) else []:
+        # ⛔⛔ MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
+        # `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
+        # live handle returns **19 DICTS**, keyed
+        # `video_url · video_id · playcount · diggcount · commentcount · share_count ·
+        #  favorites_count · create_date · cover_image`.
+        # The docstring above cites the $0 probe as having "measured" permalinks — it had not, and
+        # could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
+        # so in terms (*"what $0 cannot buy … the real ROW shape … that a declared field
+        # POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
+        # declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
+        # the first. [[reachable-is-not-the-same-as-built]]
+        # ⇒ The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
+        # list on every real profile — post capture could not have worked for anybody, and the
+        # T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
+        # written from a schema tests the schema.
+        # ⚠ `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
+        # because it costs nothing and is what a future corpus revision would most likely use. The
+        # bare-string branch stays for the same reason — this widens what is ACCEPTED and invents
+        # nothing: a shape that yields no `http…` value still degrades to "no posts", exactly as
+        # before, rather than to a URL built out of a guess.
+        # ⚠ `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
+        # whichever array happened to be longer is how one creator's window silently differs from
+        # another's, and that reasoning is unchanged by this correction.
+        if isinstance(item, dict):
+            u = str(item.get("video_url") or item.get("url") or "").strip()
+        else:
+            u = str(item or "").strip()
+        if u.lower().startswith("http") and u not in out:
+            out.append(u)
+    return out[:limit] if limit and limit > 0 else out
+def pull_posts_tt(post_urls, log=print, deferred=None):
+    """The TikTok Posts dataset for a list of permalinks → `(rows, note)`, already normalised.
+    ⚠ ONE CALL FOR THE WHOLE WINDOW. `bd_scrape` has always taken a list, and the Instagram side
+    measured what happens when a caller forgets: 25 records, one billed snapshot each, a walk still
+    running at 67 minutes. Nothing here loops per URL.
+    """
+    urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
+    if not urls:
+        return [], ""
+    rows, note = bd_scrape(TT_DS_POSTS, urls, deferred=deferred)
+    if note:
+        log(f"[aios-tt] posts: {note}")
+        return [], note
+    out = [r for r in (normalize_post(n) for n in rows) if r]
+    return out, ""
+def pull_comments_tt(post_urls, log=print, deferred=None):
+    """The TikTok Comments dataset for a list of POST permalinks → `(rows, note)`, normalised.
+    ⛔ THE MOST EXPENSIVE THING THIS PRODUCT BUYS, and the reason `commentMetrics` defaults OFF on
+    both networks: a comments scrape ingests identifiable third parties who never entered anybody's
+    list (D-24). The mapper already keeps every commenter field in `source_payload` and promotes
+    none of them to a column; this function adds no new exposure, it just has to be asked for.
+    """
+    urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
+    if not urls:
+        return [], ""
+    rows, note = bd_scrape(TT_DS_COMMENTS, urls, deferred=deferred)
+    if note:
+        log(f"[aios-tt] comments: {note}")
+        return [], note
+    out = [r for r in (normalize_comment(n) for n in rows) if r]
+    return out, ""
+#: ⭐⭐ WAVE 30 · D-156 — THE MEDIA DATASETS, AS A SET, SO THE HAND-OFF CAN FILTER ON IDENTITY.
+#: `_media_deferrals` uses this to lift ONLY posts/comments snapshots out of the local deferral
+#: list. That is what makes it structurally impossible to file a PROFILE snapshot in the engine's
+#: metric queue — the defect a draft of T10 shipped and A-39 booked as "the wrong fix is worse
+#: than the gap". A membership test cannot be got wrong by a later edit the way `if` order can.
+TT_MEDIA_DATASETS = (TT_DS_POSTS, TT_DS_COMMENTS)
+def _media_deferrals(deferred):
+    """The POSTS/COMMENTS entries of a `bd_scrape` deferral list — never the profile's.
+    ⚠ The engine, not this module, decides what a deferral MEANS: it stamps `kind` and the
+    handle and files it. TikTok needs no `_tag_metric_deferrals` twin because one dataset is one
+    kind here, so the id already carries everything a mapper choice depends on — and importing
+    Instagram's tagger is not available anyway (W30-T09 gates ZERO `from connectors_ig` lines).
+    """
+    out = []
+    for d in deferred or []:
+        if isinstance(d, dict) and str(d.get("datasetId") or "") in TT_MEDIA_DATASETS:
+            out.append(dict(d))
+    return out
+def pull_profile_tt(url, log=print, pending_profile=None, prefetch=None,
+                    max_posts=0, post_metrics=False, comment_metrics=False):
+    """ONE TikTok profile from the vendor. Same return contract as `pull_profile`.
+    `{state, profile, posts, comments, via, note}` with `state ∈ ok | partial | blocked | error`,
+    so the engine's enrich branch treats every network identically and no caller learns a new
+    shape.
+    ⭐ WAVE 30 · T10 — POSTS AND COMMENTS ARE REAL NOW, AND BOTH DEFAULT OFF, exactly as Instagram's
+    do. `post_metrics` scrapes the profile row's own `top_videos` permalinks (see `tt_post_urls` —
+    no discovery call, because both TikTok discovery datasets 404 for our key); `comment_metrics`
+    then scrapes the comments of the posts that came back. ⚠ COMMENTS REQUIRE POSTS by construction
+    rather than by a rule: their input IS a post permalink, so asking for comments with post capture
+    off is a request with no subject, and it returns none instead of quietly buying posts nobody
+    asked for.
+    ⛔ `partial` IS THE SUCCESS STATE WHENEVER NO MEDIA WAS READ, and that is deliberate rather than
+    pessimistic. The Instagram contract reads `ok` only when identity AND media both landed
+    (`pull_profile_bd`: *"identity without media is still partial ... a run that wrote a follower
+    count and no posts must not paint green over a posts table that did not grow"*). So: posts not
+    ASKED for → `partial`, saying so; posts asked for and landed → `ok`; asked for and none came →
+    `partial` with the vendor's reason. The state answers "did this pull deliver what it went for",
+    never "did the function finish".
+    ⚠ **NO FREE RUNG, AND NO FALLBACK CHAIN.** Instagram's `pull_profile` drops to Apify when the
+    paid rung refuses; `providers.DEFAULT_CHAINS["tt_profile"]` is deliberately single-provider,
+    with its own note explaining that a multi-provider chain is a promise something walks it and
+    that nothing walks Instagram's second name today either. So a refusal here is final, and it
+    says so instead of implying a retry somewhere.
+    """
+    handle = tt_handle(url)
+    if not handle:
+        return {"state": "error", "profile": {}, "posts": [], "comments": [], "via": "",
+                "note": f"{url!r} is not a TikTok profile URL or handle"}
+    # ⭐ THE BATCH FAST PATH, same shape as the Instagram side: `prefetch` is `{handle: node}` from
+    # one multi-URL scrape covering a whole selection. A hit is a vendor round trip that does not
+    # happen; a miss falls through to the single-URL call below.
+    cached = prefetch.get(handle) if isinstance(prefetch, dict) else None
+    _deferred = []
+    if isinstance(cached, dict) and cached:
+        rows, note = [cached], ""
+    else:
+        rows, note = bd_scrape(TT_DS_PROFILES, [tt_profile_url(handle)], deferred=_deferred)
+    node = rows[0] if rows else {}
+    profile = normalize_profile(node, handle) if node else {}
+    # ⛔ THE READABILITY TEST IS `followers`/`following`, NOT "did we get a dict". `normalize_profile`
+    # drops blanks, so an unreadable row still returns `{"platform": …, "handle": …}` — truthy, and
+    # carrying nothing anybody asked for. The Instagram rung tests exactly this pair for exactly
+    # this reason, and answering "0 followers" instead is the failure it exists to prevent.
+    unreadable = profile.get("followers") is None and profile.get("following") is None
+    if note or unreadable:
+        # ⭐ THE DEFERRAL IS HANDED OVER RATHER THAN DISCARDED. A snapshot the vendor is still
+        # building HAS ALREADY BEEN PAID FOR; dropping its id bills again on the next run for the
+        # same record. That was live on the Instagram profile path until 2026-08-09 — measured on
+        # nurilab as two runs, two fresh snapshots, both abandoned — and it is not being
+        # reintroduced here by omission.
+        if isinstance(pending_profile, list):
+            for d in _deferred:
+                pending_profile.append({**d, "kind": "profile", "influencer": handle})
+        why = note or ("the scrape answered, but no follower/following counts were readable in it "
+                       "(the field names may have moved - see tiktok-capture.md)")
+        return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
+                "deferredProfile": [d.get("snapshotId") for d in _deferred],
+                "note": why}
+    # --- W30-T10: THE MEDIA, ONLY WHEN IT WAS ASKED FOR. ------------------------------------
+    if not post_metrics:
+        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
+                "via": "brightdata",
+                "note": note or "profile read; post capture is off for this step"}
+    urls = tt_post_urls(node, limit=max_posts)
+    if not urls:
+        # ⚠ NOT AN ERROR AND NOT A RETRY. A creator with no `top_videos` has nothing to buy, and
+        # saying so is what stops the next run paying to be told the same thing.
+        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
+                "via": "brightdata",
+                "note": note or "profile read; this account's row carried no post links"}
+    posts, p_note = pull_posts_tt(urls, log=log, deferred=_deferred)
+    comments, c_note = ([], "")
+    if comment_metrics and posts:
+        # The comments dataset is keyed on a POST permalink, so it reads the posts we just bought —
+        # `url` from the mapper, never the profile's raw array, so a post the posts scrape refused
+        # is not silently asked about again one rung later.
+        comments, c_note = pull_comments_tt([p.get("url") for p in posts if p.get("url")],
+                                            log=log, deferred=_deferred)
+    # ⭐⭐ WAVE 30 · D-156 — THE MEDIA DEFERRALS ARE HANDED BACK, and the shape of the hand-off is
+    # the whole lesson. An earlier draft of T10 appended every `_deferred` entry to
+    # `pending_profile` tagged `kind: "profile"`. By the time control reaches here a PROFILE
+    # deferral is impossible — the profile branch above returns `blocked` on any note — so **every
+    # id fanned out that way was a POSTS or COMMENTS snapshot in the PROFILE queue**, whose
+    # collector writes preset profile cells onto somebody's record from post rows. The engine keeps
+    # the two queues apart deliberately (`_pending_profile_tasks` vs `_pending_metric_tasks`).
+    # ⇒ So this returns them under their OWN key, filtered by dataset identity
+    # (`_media_deferrals`), and the engine files them in the metric queue with the handle it
+    # already holds. Returning rather than appending also keeps the queue's vocabulary out of a
+    # connector: this module knows which CORPUS deferred, never what the engine calls it.
+    # ⚠ `deferredMedia` rides BOTH returns on purpose. The empty-posts case is the one that
+    # matters most — that is exactly the run where the vendor took too long, so a caller reading
+    # the ids only from the success path would lose every batch it actually paid for.
+    deferred_media = _media_deferrals(_deferred)
+    if not posts:
+        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
+                "via": "brightdata", "deferredMedia": deferred_media,
+                "note": p_note or note or "profile read; the post source returned nothing"}
+    return {"state": "ok", "profile": profile, "posts": posts, "comments": comments,
+            "via": "brightdata", "deferredMedia": deferred_media,
+            "note": c_note or note or ""}

api/main.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/odoo_relational.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/providers.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_admin.py CHANGED Viewed

@@ -546,6 +546,203 @@ def _perm_modules(session, surfaces=False):
 #: editor renders, so "shown" and "storable" cannot drift apart again.
 def _module_fields(key, session=None):
     """The field schema the editor builds its pickers from — the SAME vocabulary the grid uses,
     so an admin filters on exactly what the user sees.
@@ -679,7 +876,31 @@ def _module_fields(key, session=None):
     # skipped on a key collision so a declared column always wins its own key.
     taken = {f["key"] for f in out}
     out.extend(m for m in _metric_fields(key) if m["key"] not in taken)
-    return out
 def _metric_fields(key):
@@ -1218,6 +1439,19 @@ def _clean_perms(v, governed_keys=None, session=None):
         # per-user private one cannot, and those keep denying every leaf they are named in.
         row_wall_blind = _row_wall_blind_keys(key, session)
         filter_keys -= row_wall_blind
         hidden = raw.get("hiddenFields") or []
         if not isinstance(hidden, list):
             raise err(400, "bad_perms", f"{key}: hiddenFields must be a list")
@@ -1302,6 +1536,28 @@ def _clean_perms(v, governed_keys=None, session=None):
                               f"would hide EVERY row with nothing on screen saying why. Hide the "
                               f"column instead, or filter on one of the database's own columns "
                               f"or on a column shared with the whole workspace.")
                 cleaned = aios_grid.clean_filter_tree(nodes, filter_keys, cohort_ids=None)
                 if _leaf_count(cleaned) != _leaf_count(nodes):
                     raise err(400, "bad_filter",

 #: editor renders, so "shown" and "storable" cannot drift apart again.
+#: What a picker row says about provenance when nothing could be established: no author on the
+#: definition, no owner in the registry, and no answer to "does that owner hold admin".
+#: ⛔⛔ `ownerIsAdmin: None` IS NOT `False`, AND THE DIFFERENCE IS THE WHOLE POINT OF W41-T08.
+#: `False` asserts "a known account that is not an administrator owns this column"; `None` says
+#: "unresolved". R8 arms an ADMIN-CREATED-ONLY rule on top of this, and a consumer that read the
+#: unresolved answer as `False` would wall a column on a store outage — silently, and in the
+#: direction that breaks a live permission rule. Every consumer must treat `None` as "do not act".
+#: ⚠ `origin` FALLS TO `"preset"` for a row with no definition behind it (the `measure_`
+#: pseudo-fields), which is the truth rather than a default: the platform's metric catalogue made
+#: those, not a person. `field_origin`'s own docstring argues the same polarity.
+_PROVENANCE_UNKNOWN = {"createdBy": None, "owner": None, "ownerIsAdmin": None,
+                       "origin": "preset"}
+#: ⭐⭐ W41-T09 / RULING R8 / OWNER INSTRUCTION 15 — THE KEY A PICKER ROW CARRIES WHEN R8 IS WHAT
+#: TOOK IT OUT OF THE PERMISSION FILTER BUILDER. A MODULE CONSTANT rather than a literal, because
+#: the producer (`_module_fields`) and the consumer (`_clean_perms`' named refusal) sit 500 lines
+#: apart: two spellings of one key is wave 40's own scar, where a TITLE instruction shipped as a
+#: no-op with both lanes correct and every gate green because the consumer never read the
+#: producer's new name [[two-lanes-one-contract-dead-feature]].
+#: ⚠ PRESENT ONLY WHEN R8 IS THE CAUSE. A `measure_` pseudo-field and `est_missed` are
+#: `filterable: False` for reasons that predate this rule and carry no reason key, so the set of
+#: rows holding one IS exactly the set R8 refuses — which is what lets the validator derive its
+#: refusal from the very rows the picker was built from instead of recomputing the predicate.
+_FILTER_REASON_KEY = "filterableReason"
+#: ⛔ USER-FACING COPY (CONTRACT C7): no em dash, no en dash, no ALL-CAPS chrome. One sentence, and
+#: it NAMES THE OWNER because that is the repair rather than a diagnosis with no next step —
+#: W41-T03 shipped owner reassignment this wave, so "who owns it" is the actionable half.
+_ADMIN_ONLY_FILTER_REASON = ("Only a column owned by an administrator can be used in a permission "
+                             "filter, and {owner} owns this one.")
+def _apply_admin_only_filter_rule(row):
+    """RULING R8, ARMED: a column whose CURRENT OWNER does not hold admin leaves the permission
+    filter builder, and says why.
+    Owner instruction 15: *"only admin-created fields may be used for permissioning filtration."*
+    ⚠ THE PREMISE HAD NO SUBJECT UNTIL W41-T08 — a picker row carried `custom` and nothing else —
+    so R8 defines "admin-created" as THE FIELD'S CURRENT OWNER HOLDS THE ADMIN ROLE, repairable
+    through the ownership transfer W41-T03 shipped. On live today the two readings coincide:
+    `object_shares` holds no `field` namespace at all for this tenant, so every owner resolves
+    through C1's documented `createdBy` fallback (W41-T08's census, measured 2026-08-24).
+    ⛔⛔ `None` ADMITS, AND THAT DECISION IS THE WHOLE SAFETY PROPERTY OF THIS FUNCTION.
+    `ownerIsAdmin` is `False` only for a KNOWN account known not to hold admin; it is `None` for
+    "unresolved" — no owner recorded, the roster unreadable, or no session to read either with.
+    `store.get` answers `{}` on a transient failure, so a rule that refused on `None` would revoke
+    EVERY live permission filter in the tenant at once, off one bad read, in the direction that
+    hands an account the whole book. Admitting on `None` costs the opposite and it is bounded: a
+    degraded read leaves the offer exactly as wide as it was the day before R8 shipped.
+    ⚠ AND THE CHOICE IS MEASURED, NOT ONLY ARGUED. `verify_api`'s W40-T18 fixture
+    `custom_region_qa` carries no `createdBy` and no grant record, so it resolves `None`; refusing
+    on `None` turns that shipped ACCEPTANCE leg red. The safe direction and the measured one agree.
+    ⛔ NARROW THREE WAYS, and each one names a live column this must not touch:
+      * `origin == "user"` ONLY, and the badge comes from CONTRACT C1 (`field_origin`), never from
+        a second derivation in this file. A PLATFORM column is not "admin-created" either on a
+        literal reading, and walling `dba` or `revenue` because somebody was handed their
+        ownership would be R8 eating the database's own contract.
+      * A row that is ALREADY unfilterable is left alone, reason key and all. A `measure_`
+        pseudo-field and `est_missed` are out of the builder for causes that predate R8, and
+        stamping this sentence on them would explain their absence with the wrong reason.
+      * The FILTER only. �� R8 ARMS FILTRATION, NOT HIDING: `_clean_perms` validates
+        `hiddenFields` against EVERY key and the permanent filter against `filterable` alone, so
+        flipping this one flag reaches the builder and leaves the hide list whole. The nine
+        declared `shared` product columns and all five of these stay hideable.
+    ⚠ A KNOWN GAP, NAMED RATHER THAN PAPERED OVER: on a `ut_*` database `user_tables._clean_field`
+    is a strict allowlist that keeps neither `custom` nor `createdBy`, so its columns answer
+    `origin: "preset"` and R8 cannot fire there until a transfer writes a real grant record.
+    `field_origin`'s own docstring books that allowlist as the defect; this inherits the gap rather
+    than routing around it with the second badge C1 exists to forbid.
+    ⛔ THE STORED RECORD IS NOT TOUCHED, and that is deliberate. `get_perms`' I16 cascade prunes a
+    leaf naming a column the database no longer HAS; a column that still exists and merely changed
+    who may name it is not stale, and pruning it would DELETE a live permission rule silently, in
+    the WIDENING direction. An existing wall keeps working (`apply_row_scope` is unchanged) and a
+    re-save of it is refused LOUDLY by `_clean_perms`, with the column named.
+    ⚠ `owner` IS GUARDED STRUCTURALLY, not defensively: `_field_provenance` cannot answer `False`
+    without one, and the sentence is only well formed with a name in it.
+    """
+    owner = row.get("owner")
+    if (row.get("origin") != "user" or not row.get("filterable")
+            or row.get("ownerIsAdmin") is not False or not owner):
+        return row
+    return dict(row, filterable=False,
+                **{_FILTER_REASON_KEY: _ADMIN_ONLY_FILTER_REASON.format(owner=owner)})
+def _admin_usernames():
+    """Every account holding the `admin` role, lowercased — or `None` when that set could not be
+    established.
+    ⛔⛔ `None` IS NOT `set()`, for the reason `perm_scope.user_generated_fields` states one door
+    over: `set()` means "resolved: nobody here is an administrator" and `None` means "the roster
+    could not be read". `core.users.registry` is a LENIENT display read (`store.get`), so a store
+    outage hands back `{}` — indistinguishable from a tenant with no accounts, and reading that as
+    "no admins" would make every `ownerIsAdmin` answer `False` at exactly the moment nothing can be
+    verified. An EMPTY registry therefore answers `None`; a populated one with no admin in it is a
+    real (and reportable) `set()`.
+    ⚠ THE REGISTRY IS A GLOBAL CONTROL-PLANE BUCKET AND THAT IS WHY THIS IS NOT TENANT-SCOPED.
+    `list_users` says it in full: one bucket holds every tenant's accounts, keyed by username, so a
+    username resolves to exactly one record and exactly one role however the caller arrived. The
+    tenant filter there protects a ROSTER LISTING; this asks a per-username question that has one
+    answer.
+    """
+    try:
+        reg = users.registry() or {}
+    except Exception:                                                     # noqa: BLE001
+        return None
+    if not isinstance(reg, dict) or not reg:
+        return None
+    return {str(u).strip().lower() for u, rec in reg.items()
+            if isinstance(rec, dict)
+            and str(rec.get("role") or "user").strip().lower() == "admin"}
+def _field_provenance(src, key, session):
+    """`{field_key: {createdBy, owner, ownerIsAdmin, origin}}` for the definitions in `src`.
+    ⭐⭐ W41-T08 / RULING R8 / CONTRACT C1 — WHO MADE THIS COLUMN, WHO OWNS IT NOW, AND WHETHER
+    THAT OWNER HOLDS ADMIN. R8 wants permission filters restricted to admin-created columns, and
+    the premise could not even be CHECKED before this: a picker row carried `custom` and nothing
+    else, so "admin-created" had no subject on the wire. ⛔ THIS FUNCTION MEASURES AND REPORTS.
+    It arms nothing, filters nothing and drops nothing — W41-T09 is the ticket that decides what a
+    wall does with the answer, and it is blocked on the census this produces.
+    ⛔ THE OWNER COMES FROM CONTRACT C1 AND FROM NOWHERE ELSE. `field_permissions.field_classes` is
+    the ONE producer of a field's badges (`{origin, audience, sharedBy, values, owner}`) and the
+    permission-rule picker is one of its four named consumers. Re-reading `object_shares` here, or
+    treating `createdBy` as the owner, would be the second derivation C1 exists to forbid — and the
+    two would disagree the first time a column changed hands, which is precisely the question R8
+    asks. `createdBy` still travels, but as the RAW author stamp beside the owner, never as it.
+    ⚠ THE BATCH, NEVER `field_class` IN A LOOP. `field_classes` opens the grant registry ONCE for
+    the whole list; the per-field door deep-copies `object_shares` per column, which is the D-214
+    shape its own docstring spent a ticket removing. This runs on every admin GET.
+    ⚠ `values_shared=()` IS DELIBERATE AND IT IS WHY ONLY TWO MEMBERS OF THE BAG ARE READ HERE.
+    The `values` and `audience` badges are the two that depend on which columns hold a tenant-wide
+    stratum, and resolving that costs another document read on a hot path. `origin` and `owner` do
+    not depend on it at all. ⛔ SO NEITHER `values` NOR `audience` MAY BE EMITTED FROM THIS CALL:
+    lending an empty key set makes both of them answer for a world in which nothing is shared. A
+    consumer that needs those two badges asks `field_classes` with the real set, the way
+    `routes_customers`' grid assembly does.
+    ⚠ NO SESSION MEANS NO PROVENANCE, AND THAT IS HONEST DEGRADATION RATHER THAN A GAP. Two callers
+    arrive without one (`_fold_legacy_scope` on the live PUT path, `verify_api`'s W30a probe), and
+    the only reads that could answer them are TENANT-BLIND module-level ones: `shares.grants` with
+    no `st` opens the default repo's registry, which on any tenant but #0 is a different workspace's
+    grants attributed to this one. An unresolved answer costs those two callers nothing — neither
+    reads provenance — and a wrong one would be a tenant leak. `origin` is still answered, because
+    `field_origin` is a pure read of the definition in hand and touches no store.
+    """
+    try:
+        from core import field_permissions as _fp
+    except Exception:                                                     # noqa: BLE001
+        return {}
+    defs = [f for f in src if isinstance(f, dict) and f.get("key")]
+    classes = {}
+    admins = None
+    if session is not None:
+        admins = _admin_usernames()
+        try:
+            # ⛔ `grant_topic` IS THE MODULE KEY, NOT THE STORE BUCKET. `shares.field_oid` namespaces
+            # a grant by the topic the write doors already use — `"customer_data"` /
+            # `"product_data"` (`routes_customers`/`routes_products`) and the table key itself for a
+            # `ut_*` database (`routes_tables`) — which is `key` in every one of those three cases.
+            # Handing it `customer_table_workspace` finds no record for any column and every owner
+            # silently reads as absent, which is the `grant_records` docstring's own warning.
+            classes = _fp.field_classes(defs, getattr(session, "uname", ""),
+                                        grant_topic=key, values_shared=(),
+                                        st=getattr(session, "runtime", None))
+        except Exception:                                                 # noqa: BLE001
+            # A registry that will not open costs the OWNER, not the picker. The rows still ship,
+            # still carry every membership boolean, and say `None` about what they could not read.
+            classes = {}
+    out = {}
+    for f in defs:
+        fkey = f["key"]
+        bag = classes.get(fkey) or {}
+        owner = bag.get("owner") or None
+        try:
+            origin = _fp.field_origin(f)
+        except Exception:                                                 # noqa: BLE001
+            origin = "preset"
+        out[fkey] = {"createdBy": (str(f.get("createdBy") or "").strip().lower() or None),
+                     "owner": owner,
+                     "ownerIsAdmin": (None if not owner or admins is None
+                                      else owner in admins),
+                     "origin": origin}
+    return out
 def _module_fields(key, session=None):
     """The field schema the editor builds its pickers from — the SAME vocabulary the grid uses,
     so an admin filters on exactly what the user sees.
     # skipped on a key collision so a declared column always wins its own key.
     taken = {f["key"] for f in out}
     out.extend(m for m in _metric_fields(key) if m["key"] not in taken)
+    # ⭐⭐ W41-T08 / R8 / C1 — PROVENANCE, STAMPED AS A LAST PASS OVER THE FINISHED LIST.
+    # ⛔ A PASS, NOT A FILTER, AND THE POSITION IS THE PROOF. Every row that reached `out` above
+    # leaves this function, in the same order, with the same key/label/type/options/pinned and the
+    # same four membership booleans; the only difference is four ADDED keys. T09 arms R8's
+    # admin-only rule and it is blocked on the census this feeds — narrowing the offer here would
+    # build T09 by accident and break `Manual allocation of agent` the day after D-470 made it work.
+    # ⚠ A NEW DICT PER ROW, NEVER AN IN-PLACE STAMP — the rule `routes_customers`' grid assembly
+    # states over its own `class` bag, for the same reason. `owner` and `ownerIsAdmin` are THIS
+    # request's answer about a roster that changes, so stamping a row this function did not build
+    # itself (every `_metric_fields` row) would publish that answer to whatever else holds it.
+    # Those rows are freshly built today; the copy makes the aliasing impossible to reintroduce
+    # rather than merely untrue now.
+    # ⚠ A ROW WITH NO DEFINITION BEHIND IT (every `measure_` pseudo-field) takes
+    # `_PROVENANCE_UNKNOWN`, whose `origin` is `"preset"` — see the note there.
+    # ⭐⭐ W41-T09 / R8 — AND THE RULE IS APPLIED IN THE SAME PASS, ON THE STAMPED ROW.
+    # ⛔ THE ORDER IS THE POINT: the provenance has to be ON the row before anything can read
+    # `ownerIsAdmin` off it, and the rule reads nothing else — no second store call, no second
+    # derivation of who owns what. The list is still KEY-SET PRESERVING and still in the same
+    # order; a refused column keeps its row, its label and its four membership booleans, and
+    # loses exactly one flag while gaining one sentence. That is what keeps `hiddenFields`
+    # whole while the FILTER narrows, and it is why the picker and the validator below can
+    # still be the one vocabulary this function's docstring promises.
+    prov = _field_provenance(src, key, session)
+    return [_apply_admin_only_filter_rule(dict(r, **prov.get(r["key"], _PROVENANCE_UNKNOWN)))
+            for r in out]
 def _metric_fields(key):
         # per-user private one cannot, and those keep denying every leaf they are named in.
         row_wall_blind = _row_wall_blind_keys(key, session)
         filter_keys -= row_wall_blind
+        # ⭐⭐ W41-T09 / R8 — THE COLUMNS THE ADMIN-OWNER RULE TOOK OUT OF THE BUILDER, READ OFF
+        # THE ROWS THE PICKER WAS BUILT FROM rather than recomputed here.
+        # ⛔ THIS IS THE ONE-SOURCE INVARIANT DOING ITS JOB, not a convenience. Re-deriving "does
+        # this owner hold admin" in the validator would be a SECOND registry read at a SECOND
+        # moment, and the two would disagree the first time a role changed between the GET and
+        # the PUT: the admin would be refused a column the screen in front of them was still
+        # offering, or offered one the wall then rejected. `_apply_admin_only_filter_rule` already
+        # decided, on this very call, and the decision travels on the row.
+        # ⚠ `filter_keys` ALREADY EXCLUDES THESE (the rule cleared `filterable`), so this set is
+        # not what refuses them — the generic leaf-count check below would do that on its own,
+        # with the "unknown field" wording. It exists so the refusal can NAME THE COLUMN and give
+        # the cause, which is the half of done-when the generic message cannot carry.
+        admin_only_blocked = {f["key"] for f in fields_here if f.get(_FILTER_REASON_KEY)}
         hidden = raw.get("hiddenFields") or []
         if not isinstance(hidden, list):
             raise err(400, "bad_perms", f"{key}: hiddenFields must be a list")
                               f"would hide EVERY row with nothing on screen saying why. Hide the "
                               f"column instead, or filter on one of the database's own columns "
                               f"or on a column shared with the whole workspace.")
+                # ⭐⭐ W41-T09 / R8 / OWNER INSTRUCTION 15 — THE WRITE DOOR, AND IT NAMES THE
+                # COLUMN. Second rather than first on purpose: a column that is BOTH unwallable
+                # and non-admin-owned gets the message above, because reassigning its owner would
+                # not make it filterable and this one would send the admin to do exactly that.
+                # ⛔ AND IT IS NOT DECORATION OVER THE GENERIC CHECK BELOW. Without it the same
+                # submission still 400s, worded *"an unknown field"* about a column the picker
+                # listed one request ago and the grid renders every day. That wording sends an
+                # administrator to look for a typo, and they will simply try again; owner
+                # instruction 15 is a RULE, and a rule that cannot say its own name is
+                # indistinguishable from a bug [[a-declared-gate-is-an-unchecked-claim]].
+                # ⚠ BOTH DOORS ARE COVERED BY THIS ONE BRANCH: `put_perms` and
+                # `routes_slack.put_channel_agent_perms` call THIS validator, both threading a
+                # session, so a channel agent cannot be walled on a column a person cannot be.
+                denied = sorted(_leaf_col_ids(nodes) & admin_only_blocked)
+                if denied:
+                    raise err(400, "field_owner_not_admin",
+                              f"{key}: a permission filter cannot use {denied}. A permanent rule "
+                              f"may only name a column that an administrator owns, because "
+                              f"deleting a column also deletes the permission filter naming it, "
+                              f"and these columns belong to accounts without the admin role. "
+                              f"Reassign the column to an administrator, or write the rule on one "
+                              f"of the database's own columns.")
                 cleaned = aios_grid.clean_filter_tree(nodes, filter_keys, cohort_ids=None)
                 if _leaf_count(cleaned) != _leaf_count(nodes):
                     raise err(400, "bad_filter",

api/routes_agent_harness.py CHANGED Viewed

@@ -1,455 +1,455 @@
-"""routes_agent_harness.py — CONTRACT C4: the agent's HARNESS, kept as versioned files.
-Owner item 3, verbatim (2026-08-18): *"This new module under agent is supposed to host any file
-pertaining to the agent skills, router etc. So we build a user can build a custom harness for each
-agent through the chat interface."*
-    GET    /api/v1/agents/{id}/harness                      the file LIST (no bodies)
-    GET    /api/v1/agents/{id}/harness?path=…               one file: current body + its versions
-    GET    /api/v1/agents/{id}/harness?path=…&version=N     one older body, verbatim
-    PUT    /api/v1/agents/{id}/harness                      write a NEW version of one file
-    DELETE /api/v1/agents/{id}/harness?path=…               drop a file and its history
-⭐⭐ **R8 IS THE WHOLE SHAPE: BOTH PRINCIPALS WRITE, AND NOTHING IS EVER OVERWRITTEN.** A write
-appends a version; a roll-back is a write of an older body (`restoredFrom`), never a delete. So the
-history is a record of what happened rather than of what somebody last wanted it to look like.
-⛔ **R8 IS DELIBERATELY NOT R9.** An agent-authored ACTION's configuration is agent-only (item 8,
-`routes_automation`); a harness file is not. Do not copy this file's posture over there or that
-one's over here — the two rulings differ on purpose and they sit one screen apart in the product.
-⚠ **`author` IS THE SESSION, `authorKind` IS THE PROVENANCE, AND THEY ARE DIFFERENT FACTS.** Every
-write through this router is made BY a signed-in administrator, so `author` is stamped from the
-session and can never be supplied by the caller. `authorKind` says whether the BODY was drafted by
-a person or by the agent in the chat — a claim the client is entitled to make, because both are
-permitted (R8) and so nothing is bought by forging it. `record_version()` below is the server-side
-door the automation engine uses when the agent writes with no session at all; that one stamps the
-agent's own id as the author, which is the only case where `author` is not a username.
-⛔ **THE VERSION LIST IS CAPPED AND THE CAP IS REPORTED, NEVER SILENT.** `MAX_VERSIONS` versions of
-one file are kept; past that the OLDEST are dropped and the count of what was dropped rides in
-`trimmed` on every payload that mentions the file, so a reader can see that the history is partial
-rather than infer that the file was only ever saved twice. This is the tenant document, which is
-already 28.6 MB on tenant #0 and is deep-copied on every read: an unbounded per-agent history is
-a store-sized leak with a UI in front of it.
-"""
-from datetime import datetime, timezone
-from fastapi import APIRouter, Body, Depends
-from deps import Session, err, require_session
-router = APIRouter(prefix="/api/v1")
-#: The tenant's harness files: `{agent_id: {path: file_record}}`. A per-tenant bucket, so it rides
-#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace — the same rule
-#: `routes_slack.AGENTS_KEY` follows for the agent records these hang off.
-HARNESS_KEY = "agent_harness"
-#: One body. Generous for a skill or a router file and far under the point where a single write
-#: would move the tenant document measurably. A larger body is a REFUSAL at the door, not a
-#: truncation: a silently truncated skill file is a harness that does not do what its text says.
-MAX_BODY_BYTES = 128 * 1024
-#: Files per agent. A refusal, not a trim — creating the 65th file is a different act from saving
-#: the 101st version of one, and only the second can be a routine consequence of ordinary editing.
-MAX_FILES = 64
-#: Versions kept per file. Past this the oldest go and `trimmed` counts them (see the header).
-MAX_VERSIONS = 100
-MAX_PATH = 200
-#: What a path may contain. ⛔ THIS IS NOT A FILESYSTEM PATH AND NOTHING HERE EVER TOUCHES A DISK —
-#: the "files" are keys in a store bucket. The character rule exists so the key is displayable, is
-#: safe to put in a URL, and cannot carry a traversal sequence that would look meaningful to a
-#: future reader who assumes it IS a filesystem path. Fail-closed on the character set, not on a
-#: list of forbidden sequences: an allow-list cannot be walked around by a spelling.
-_PATH_OK = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-/")
-AUTHOR_KINDS = ("user", "agent")
-def _now():
-    return datetime.now(timezone.utc).isoformat(timespec="seconds")
-def _all(rt):
-    """`{agent_id: {path: record}}` for one tenant. `{}` on any failure — an unreadable bucket must
-    degrade to "this agent has no harness files", never to a 500 on the pane that lists them."""
-    try:
-        found = rt.get(HARNESS_KEY) or {}
-    except Exception:                                                        # noqa: BLE001
-        return {}
-    return found if isinstance(found, dict) else {}
-def _files(rt, agent_id):
-    found = _all(rt).get(str(agent_id))
-    return found if isinstance(found, dict) else {}
-#: What kind of principal an id names. `None` = this tenant has no agent with that id.
-#:
-#: ⛔⛔ THERE ARE TWO AGENT REGISTRIES IN THIS PRODUCT AND THE FIRST DRAFT OF THIS FILE KNEW ONLY
-#: ONE (ASK D-5, 2026-08-18). `routes_slack._agents` is the per-Slack-channel permission wall under
-#: Manage users. The **Agents module** the owner's item 3 is about is the AUTOMATION surface —
-#: `Shell.tsx` mounts `<Lazily surface="Agents"><AutomationSurface /></Lazily>`, and
-#: `AutomationDetail`'s `panelTabs` is literally the `Properties | Run history` strip R7 adds
-#: "Harness" to. Keyed on the Slack bucket alone, every `GET/PUT /agents/{id}/harness` from that
-#: tab would have answered **404 no_agent**: whole, gate-green and dead on arrival
-#: [[reachable-is-not-the-same-as-built]]. Verified independently before acting, not taken on
-#: report: `surface="Agents"` mounts `AutomationSurface`, and `ManageAgentPane` contains ZERO
-#: occurrences of Canvas, Properties, Run history or panelTabs.
-#:
-#: ⭐ ONE STORE, BOTH PRINCIPALS — never a second bucket keyed by surface. The owner's "agent
-#: skills, router" files in two places is the parallel code path item 13 exists to refuse.
-AGENT_SLACK = "slack"
-AGENT_AUTOMATION = "automation"
-def agent_kind(rt, agent_id):
-    """Which registry holds this id — `AGENT_SLACK`, `AGENT_AUTOMATION`, or `None`.
-    ⚠ A SYNTHETIC ROW IS NOT AN AGENT FOR THIS PURPOSE. `field:` and `system:` ids are DERIVED at
-    read time from a column definition or a connector schedule; they have no stored home, so a
-    harness file hung off one is an orphan the moment the column changes. `patch_automation`
-    already refuses those ids for the neighbouring reason, and this refuses them by simply not
-    finding them — `all_definitions` holds stored automations only.
-    """
-    import routes_slack
-    aid = str(agent_id or "")
-    if isinstance(routes_slack._agents(rt).get(aid), dict):
-        return AGENT_SLACK
-    import automation_engine as engine
-    try:
-        known = engine.all_definitions(rt) or {}
-    except Exception:                                                        # noqa: BLE001
-        return None
-    return AGENT_AUTOMATION if aid in known else None
-def _known_agent(rt, agent_id):
-    """Does this tenant have an agent with this id, in EITHER registry?"""
-    return agent_kind(rt, agent_id) is not None
-def agent_wall(session, agent_id):
-    """404 for an unknown id, else apply the wall THAT PRINCIPAL'S OWN SURFACE applies.
-    ⛔⛔ ONE DOOR, TWO WALLS, AND THAT IS NOT A SECOND CODE PATH — it is the refusal to invent a
-    THIRD wall. A Slack channel agent is administered under Manage users and every `/agents/*` door
-    in `routes_slack` is `admin_gate`; an automation lives in the Agents module and every door in
-    `routes_automation` is `module_gate("automation")`. A harness file is configuration OF the
-    agent it hangs off, so it is reached by whoever may already configure that agent. Picking one
-    of the two walls for both would either lock the Agents module's own users out of a tab the
-    owner asked for, or hand the Slack permission wall to anyone with an automation grant.
-    """
-    kind = agent_kind(session.runtime, agent_id)
-    if kind is None:
-        raise err(404, "no_agent", "there is no agent with that id in this workspace")
-    if kind == AGENT_SLACK:
-        import core.perms as perms
-        if not perms.is_admin(session.user):
-            raise err(403, "forbidden", "administrators only")
-    else:
-        session.require("automation")
-    return kind
-def normalize_path(raw):
-    """THE path rule, in ONE place. Returns the cleaned path, or `None` if it is not acceptable.
-    ⛔⛔ ONE RULE, TWO DOORS, AND THAT IS WHY THIS IS A FUNCTION RATHER THAN TWO IF-BLOCKS. There
-    are two ways into this store — the HTTP route (which must answer 400) and `record_version()`
-    (which must raise `ValueError`, having no response to put a status into). Written twice, the
-    two copies are [[one-question-two-normalizers]] waiting to happen: the first weakening of one
-    copy is invisible because the other still refuses, so nothing goes red and the wall is now
-    half there. Written once, a change to the rule is felt at both doors and by the gate.
-    """
-    path = str(raw or "").strip().strip("/")
-    if not path or len(path) > MAX_PATH:
-        return None
-    if set(path) - _PATH_OK or ".." in path or "//" in path:
-        return None
-    return path
-def _clean_path(raw):
-    """`normalize_path` at the HTTP door, where a refusal is a 400 with a reason."""
-    path = normalize_path(raw)
-    if path is None:
-        if not str(raw or "").strip().strip("/"):
-            raise err(400, "no_path", "a harness file needs a path, for example skills/router.md")
-        if len(str(raw)) > MAX_PATH:
-            raise err(400, "path_too_long", f"a harness path is at most {MAX_PATH} characters")
-        raise err(400, "bad_path",
-                  "a harness path may use letters, digits, dot, dash, underscore and / only")
-    return path
-def _blank(path, author, author_kind):
-    return {"path": path, "versions": [], "trimmed": 0,
-            "created": _now(), "createdBy": author, "createdKind": author_kind}
-def _append(record, body, author, author_kind, restored_from=None):
-    """Append ONE version to a file record, in place, and report what was trimmed.
-    The version NUMBER is monotonic and survives trimming — it counts writes, not stored entries.
-    A version list whose numbers restart at 1 after a trim would make two different bodies share a
-    name, and `restoredFrom` would then point at whichever one happened to be in the window.
-    """
-    # ⚠ A NEW LIST, NEVER `versions.append(...)` ON THE STORED ONE. `update()` hands the callback
-    # the live document and may run it more than once; appending in place would then stack two
-    # copies of the same version into the history on a retry.
-    prior = record.get("versions") if isinstance(record.get("versions"), list) else []
-    last = max((int(v.get("version") or 0) for v in prior if isinstance(v, dict)), default=0)
-    entry = {"version": last + 1, "body": body, "author": author, "authorKind": author_kind,
-             "created": _now(), "bytes": len(body.encode("utf-8"))}
-    if restored_from:
-        entry["restoredFrom"] = int(restored_from)
-    versions = [*prior, entry]
-    dropped = max(0, len(versions) - MAX_VERSIONS)
-    if dropped:
-        versions = versions[dropped:]
-    record["versions"] = versions
-    record["trimmed"] = int(record.get("trimmed") or 0) + dropped
-    return entry
-def _head(record):
-    """The newest version of a file record, or `None` for a record with no versions at all."""
-    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
-    return versions[-1] if versions else None
-def _row(record):
-    """One file, as the LIST door reports it: everything except the bodies.
-    ⚠ NO BODY, AND THAT IS THE POINT. A list door that carried every version of every file would
-    ship the whole harness on every pane render; the Harness tab lists first and opens one file
-    second, which is exactly the shape this answers.
-    """
-    head = _head(record) or {}
-    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
-    return {"path": record.get("path") or "",
-            "version": int(head.get("version") or 0),
-            "bytes": int(head.get("bytes") or 0),
-            "author": head.get("author") or record.get("createdBy") or "",
-            "authorKind": head.get("authorKind") or record.get("createdKind") or "user",
-            "updated": head.get("created") or record.get("created") or "",
-            "created": record.get("created") or "",
-            "versions": len(versions),
-            "trimmed": int(record.get("trimmed") or 0)}
-def _version_rows(record):
-    """The history of one file, newest first, WITHOUT the bodies.
-    A body per version is what makes a diff possible, and it is also what makes this payload big:
-    100 versions of a 128 KB file is 12 MB. The client asks for the two bodies it is diffing
-    (`?path=…&version=N`), which is two round trips for a diff and none for a history list.
-    """
-    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
-    out = []
-    for entry in reversed(versions):
-        if not isinstance(entry, dict):
-            continue
-        row = {"version": int(entry.get("version") or 0),
-               "author": entry.get("author") or "",
-               "authorKind": entry.get("authorKind") or "user",
-               "created": entry.get("created") or "",
-               "bytes": int(entry.get("bytes") or 0)}
-        if entry.get("restoredFrom"):
-            row["restoredFrom"] = int(entry["restoredFrom"])
-        out.append(row)
-    return out
-def _limits():
-    """The caps, IN the payload, so a client can say "this file is full" before a write fails.
-    ⚠ A limit the client cannot see is a limit the user meets as an error. `trimmed` reports the
-    one cap that acts without refusing; these report the three that refuse.
-    """
-    return {"maxBodyBytes": MAX_BODY_BYTES, "maxFiles": MAX_FILES,
-            "maxVersions": MAX_VERSIONS, "maxPath": MAX_PATH}
-# ── the write door the SERVER uses (no session) ────────────────────────────────────────────────
-def record_version(runtime, agent_id, path, body, author="", author_kind="agent",
-                   restored_from=None):
-    """Write one version from INSIDE the server — the agent's own half of R8.
-    ⭐ THIS IS THE FUNCTION, NOT THE ROUTE, THAT MAKES "editable by BOTH the user and the agent"
-    true. An agent acting inside an automation run holds no session and no cookie; if its only way
-    to write were the HTTP door it would have to borrow a person's identity, and the authorship
-    column would then be a record of who was logged in rather than of what wrote the file.
-    Returns the appended entry. Raises nothing the caller cannot handle: an unknown agent is a
-    `ValueError`, because a server-side caller has no HTTP response to put a 404 into.
-    """
-    agent_id = str(agent_id or "")
-    if not _known_agent(runtime, agent_id):
-        raise ValueError(f"no agent {agent_id!r} in this workspace")
-    path = normalize_path(path)
-    if path is None:
-        raise ValueError("that is not an acceptable harness path")
-    body = str(body or "")
-    if len(body.encode("utf-8")) > MAX_BODY_BYTES:
-        raise ValueError("harness body is over the size limit")
-    kind = author_kind if author_kind in AUTHOR_KINDS else "agent"
-    author = str(author or agent_id)
-    # ⛔ THE FILE-COUNT CEILING IS CHECKED HERE, NOT INSIDE `_set`. An exception raised inside a
-    # store `update` callback propagates out of a half-run read-modify-write, and the one thing a
-    # refusal must never do is leave the caller unsure whether the write happened.
-    existing = _files(runtime, agent_id)
-    if path not in existing and len(existing) >= MAX_FILES:
-        raise ValueError(f"this agent already has {MAX_FILES} harness files")
-    appended = {}
-    def _set(cur):
-        cur = dict(cur or {})
-        files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
-        record = dict(files[path]) if isinstance(files.get(path), dict) else _blank(path, author, kind)
-        appended.clear()
-        appended.update(_append(record, body, author, kind, restored_from))
-        files[path] = record
-        cur[agent_id] = files
-        return cur
-    runtime.update(HARNESS_KEY, _set, flush="sync")
-    return appended
-# ── the routes ────────────────────────────────────────────────────────────────────────────────
-@router.get("/agents/{agent_id}/harness")
-def get_harness(agent_id: str, path: str = "", version: int = 0,
-                session: Session = Depends(require_session)):
-    """The list, one file, or one older body — decided by the query string (C4).
-    ⚠ ADMIN-GATED LIKE EVERY OTHER AGENT DOOR (`routes_slack`), and for a stronger reason than
-    consistency: a harness file is what the agent is INSTRUCTED to do, so writing one is closer to
-    editing a permission than to editing a document.
-    """
-    agent_id = str(agent_id or "")
-    agent_wall(session, agent_id)
-    files = _files(session.runtime, agent_id)
-    if not path:
-        rows = [_row(rec) for _p, rec in sorted(files.items()) if isinstance(rec, dict)]
-        return {"agent": agent_id, "files": rows, "limits": _limits()}
-    wanted = _clean_path(path)
-    record = files.get(wanted)
-    if not isinstance(record, dict):
-        raise err(404, "no_file", f"this agent has no harness file at {wanted}")
-    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
-    if version:
-        for entry in versions:
-            if isinstance(entry, dict) and int(entry.get("version") or 0) == int(version):
-                return {"agent": agent_id, **_row(record), "body": entry.get("body") or "",
-                        "atVersion": int(version), "history": _version_rows(record),
-                        "limits": _limits()}
-        # ⛔ A TRIMMED VERSION IS A NAMED REFUSAL, NOT A 404 SHAPED LIKE A TYPO. The client asked
-        # for something that existed and no longer does, and telling it apart from a bad number is
-        # the difference between "roll back to v3" failing loudly and failing as if v3 never was.
-        trimmed = int(record.get("trimmed") or 0)
-        if trimmed and int(version) <= trimmed:
-            raise err(410, "version_trimmed",
-                      f"version {int(version)} is older than the {MAX_VERSIONS} versions kept "
-                      f"for this file, and its body is gone")
-        raise err(404, "no_version", f"this file has no version {int(version)}")
-    head = _head(record) or {}
-    return {"agent": agent_id, **_row(record), "body": head.get("body") or "",
-            "atVersion": int(head.get("version") or 0), "history": _version_rows(record),
-            "limits": _limits()}
-@router.put("/agents/{agent_id}/harness")
-def put_harness(agent_id: str, body: dict = Body(default=None),
-                session: Session = Depends(require_session)):
-    """Write a NEW version of one harness file. `{path, body, authorKind?, restoredFrom?}` (C4).
-    ⛔ THERE IS NO OVERWRITE HERE AND THERE IS NO EDIT-IN-PLACE. R8's "every version kept" is not a
-    UI affordance; it is this function refusing to have a code path that replaces a body. A
-    roll-back arrives as an ordinary write carrying `restoredFrom`, so the history records that
-    somebody went back rather than pretending the intervening versions never happened.
-    """
-    agent_id = str(agent_id or "")
-    agent_wall(session, agent_id)
-    body = body if isinstance(body, dict) else {}
-    path = _clean_path(body.get("path"))
-    text = body.get("body")
-    if not isinstance(text, str):
-        raise err(400, "no_body", "a harness file needs a body, even an empty one")
-    if len(text.encode("utf-8")) > MAX_BODY_BYTES:
-        raise err(413, "body_too_long",
-                  f"a harness file is at most {MAX_BODY_BYTES // 1024} KB; this one is larger")
-    # ⚠ THE CALLER DECLARES THE PROVENANCE AND THE SERVER STAMPS THE IDENTITY. `authorKind` is a
-    # claim about who WROTE the text (the person, or the agent in the chat panel); `author` is the
-    # session and is never read off the request. Nothing is bought by forging the first — both
-    # principals may write (R8) — and everything would be bought by forging the second.
-    kind = str(body.get("authorKind") or "user").strip().lower()
-    if kind not in AUTHOR_KINDS:
-        raise err(400, "bad_author_kind", "authorKind is either user or agent")
-    restored = body.get("restoredFrom")
-    try:
-        restored = int(restored) if restored else None
-    except (TypeError, ValueError):
-        raise err(400, "bad_version", "restoredFrom must be a version number")
-    files = _files(session.runtime, agent_id)
-    if path not in files and len(files) >= MAX_FILES:
-        raise err(409, "too_many_files",
-                  f"this agent already has {MAX_FILES} harness files; delete one to add another")
-    try:
-        record_version(session.runtime, agent_id, path, text,
-                       author=session.uname, author_kind=kind, restored_from=restored)
-    except ValueError as exc:
-        raise err(400, "refused", str(exc))
-    fresh = _files(session.runtime, agent_id).get(path)
-    if not isinstance(fresh, dict) or not _head(fresh):
-        # The store took the write and did not record it. A 200 here would tell an administrator
-        # their skill file was saved when it was not — the shape `routes_slack` refuses too.
-        raise err(503, "store_unavailable", "the harness file was NOT saved")
-    head = _head(fresh)
-    return {"agent": agent_id, **_row(fresh), "body": head.get("body") or "",
-            "atVersion": int(head.get("version") or 0), "history": _version_rows(fresh),
-            "limits": _limits()}
-@router.delete("/agents/{agent_id}/harness")
-def delete_harness(agent_id: str, path: str = "", session: Session = Depends(require_session)):
-    """Drop one harness file AND its history.
-    ⚠ THIS IS NOT THE THING R8 FORBIDS. R8 forbids a ROLL-BACK implemented as a delete — losing
-    versions as a side effect of an edit. Deleting a file is a person deciding the file should not
-    exist, which is a different act with a different button, and a store with no way to remove a
-    file is one where a typo'd path is permanent.
-    """
-    agent_id = str(agent_id or "")
-    agent_wall(session, agent_id)
-    wanted = _clean_path(path)
-    if wanted not in _files(session.runtime, agent_id):
-        raise err(404, "no_file", f"this agent has no harness file at {wanted}")
-    def _set(cur):
-        cur = dict(cur or {})
-        files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
-        files.pop(wanted, None)
-        # An agent with no harness files leaves NO key behind. An empty dict per agent id is how a
-        # bucket accumulates a row for every agent anybody ever opened the tab on.
-        if files:
-            cur[agent_id] = files
-        else:
-            cur.pop(agent_id, None)
-        return cur
-    session.runtime.update(HARNESS_KEY, _set, flush="sync")
-    return {"agent": agent_id, "deleted": wanted,
-            "files": [_row(rec) for _p, rec in sorted(_files(session.runtime, agent_id).items())
-                      if isinstance(rec, dict)],
-            "limits": _limits()}

+"""routes_agent_harness.py — CONTRACT C4: the agent's HARNESS, kept as versioned files.
+Owner item 3, verbatim (2026-08-18): *"This new module under agent is supposed to host any file
+pertaining to the agent skills, router etc. So we build a user can build a custom harness for each
+agent through the chat interface."*
+    GET    /api/v1/agents/{id}/harness                      the file LIST (no bodies)
+    GET    /api/v1/agents/{id}/harness?path=…               one file: current body + its versions
+    GET    /api/v1/agents/{id}/harness?path=…&version=N     one older body, verbatim
+    PUT    /api/v1/agents/{id}/harness                      write a NEW version of one file
+    DELETE /api/v1/agents/{id}/harness?path=…               drop a file and its history
+⭐⭐ **R8 IS THE WHOLE SHAPE: BOTH PRINCIPALS WRITE, AND NOTHING IS EVER OVERWRITTEN.** A write
+appends a version; a roll-back is a write of an older body (`restoredFrom`), never a delete. So the
+history is a record of what happened rather than of what somebody last wanted it to look like.
+⛔ **R8 IS DELIBERATELY NOT R9.** An agent-authored ACTION's configuration is agent-only (item 8,
+`routes_automation`); a harness file is not. Do not copy this file's posture over there or that
+one's over here — the two rulings differ on purpose and they sit one screen apart in the product.
+⚠ **`author` IS THE SESSION, `authorKind` IS THE PROVENANCE, AND THEY ARE DIFFERENT FACTS.** Every
+write through this router is made BY a signed-in administrator, so `author` is stamped from the
+session and can never be supplied by the caller. `authorKind` says whether the BODY was drafted by
+a person or by the agent in the chat — a claim the client is entitled to make, because both are
+permitted (R8) and so nothing is bought by forging it. `record_version()` below is the server-side
+door the automation engine uses when the agent writes with no session at all; that one stamps the
+agent's own id as the author, which is the only case where `author` is not a username.
+⛔ **THE VERSION LIST IS CAPPED AND THE CAP IS REPORTED, NEVER SILENT.** `MAX_VERSIONS` versions of
+one file are kept; past that the OLDEST are dropped and the count of what was dropped rides in
+`trimmed` on every payload that mentions the file, so a reader can see that the history is partial
+rather than infer that the file was only ever saved twice. This is the tenant document, which is
+already 28.6 MB on tenant #0 and is deep-copied on every read: an unbounded per-agent history is
+a store-sized leak with a UI in front of it.
+"""
+from datetime import datetime, timezone
+from fastapi import APIRouter, Body, Depends
+from deps import Session, err, require_session
+router = APIRouter(prefix="/api/v1")
+#: The tenant's harness files: `{agent_id: {path: file_record}}`. A per-tenant bucket, so it rides
+#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace — the same rule
+#: `routes_slack.AGENTS_KEY` follows for the agent records these hang off.
+HARNESS_KEY = "agent_harness"
+#: One body. Generous for a skill or a router file and far under the point where a single write
+#: would move the tenant document measurably. A larger body is a REFUSAL at the door, not a
+#: truncation: a silently truncated skill file is a harness that does not do what its text says.
+MAX_BODY_BYTES = 128 * 1024
+#: Files per agent. A refusal, not a trim — creating the 65th file is a different act from saving
+#: the 101st version of one, and only the second can be a routine consequence of ordinary editing.
+MAX_FILES = 64
+#: Versions kept per file. Past this the oldest go and `trimmed` counts them (see the header).
+MAX_VERSIONS = 100
+MAX_PATH = 200
+#: What a path may contain. ⛔ THIS IS NOT A FILESYSTEM PATH AND NOTHING HERE EVER TOUCHES A DISK —
+#: the "files" are keys in a store bucket. The character rule exists so the key is displayable, is
+#: safe to put in a URL, and cannot carry a traversal sequence that would look meaningful to a
+#: future reader who assumes it IS a filesystem path. Fail-closed on the character set, not on a
+#: list of forbidden sequences: an allow-list cannot be walked around by a spelling.
+_PATH_OK = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-/")
+AUTHOR_KINDS = ("user", "agent")
+def _now():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+def _all(rt):
+    """`{agent_id: {path: record}}` for one tenant. `{}` on any failure — an unreadable bucket must
+    degrade to "this agent has no harness files", never to a 500 on the pane that lists them."""
+    try:
+        found = rt.get(HARNESS_KEY) or {}
+    except Exception:                                                        # noqa: BLE001
+        return {}
+    return found if isinstance(found, dict) else {}
+def _files(rt, agent_id):
+    found = _all(rt).get(str(agent_id))
+    return found if isinstance(found, dict) else {}
+#: What kind of principal an id names. `None` = this tenant has no agent with that id.
+#:
+#: ⛔⛔ THERE ARE TWO AGENT REGISTRIES IN THIS PRODUCT AND THE FIRST DRAFT OF THIS FILE KNEW ONLY
+#: ONE (ASK D-5, 2026-08-18). `routes_slack._agents` is the per-Slack-channel permission wall under
+#: Manage users. The **Agents module** the owner's item 3 is about is the AUTOMATION surface —
+#: `Shell.tsx` mounts `<Lazily surface="Agents"><AutomationSurface /></Lazily>`, and
+#: `AutomationDetail`'s `panelTabs` is literally the `Properties | Run history` strip R7 adds
+#: "Harness" to. Keyed on the Slack bucket alone, every `GET/PUT /agents/{id}/harness` from that
+#: tab would have answered **404 no_agent**: whole, gate-green and dead on arrival
+#: [[reachable-is-not-the-same-as-built]]. Verified independently before acting, not taken on
+#: report: `surface="Agents"` mounts `AutomationSurface`, and `ManageAgentPane` contains ZERO
+#: occurrences of Canvas, Properties, Run history or panelTabs.
+#:
+#: ⭐ ONE STORE, BOTH PRINCIPALS — never a second bucket keyed by surface. The owner's "agent
+#: skills, router" files in two places is the parallel code path item 13 exists to refuse.
+AGENT_SLACK = "slack"
+AGENT_AUTOMATION = "automation"
+def agent_kind(rt, agent_id):
+    """Which registry holds this id — `AGENT_SLACK`, `AGENT_AUTOMATION`, or `None`.
+    ⚠ A SYNTHETIC ROW IS NOT AN AGENT FOR THIS PURPOSE. `field:` and `system:` ids are DERIVED at
+    read time from a column definition or a connector schedule; they have no stored home, so a
+    harness file hung off one is an orphan the moment the column changes. `patch_automation`
+    already refuses those ids for the neighbouring reason, and this refuses them by simply not
+    finding them — `all_definitions` holds stored automations only.
+    """
+    import routes_slack
+    aid = str(agent_id or "")
+    if isinstance(routes_slack._agents(rt).get(aid), dict):
+        return AGENT_SLACK
+    import automation_engine as engine
+    try:
+        known = engine.all_definitions(rt) or {}
+    except Exception:                                                        # noqa: BLE001
+        return None
+    return AGENT_AUTOMATION if aid in known else None
+def _known_agent(rt, agent_id):
+    """Does this tenant have an agent with this id, in EITHER registry?"""
+    return agent_kind(rt, agent_id) is not None
+def agent_wall(session, agent_id):
+    """404 for an unknown id, else apply the wall THAT PRINCIPAL'S OWN SURFACE applies.
+    ⛔⛔ ONE DOOR, TWO WALLS, AND THAT IS NOT A SECOND CODE PATH — it is the refusal to invent a
+    THIRD wall. A Slack channel agent is administered under Manage users and every `/agents/*` door
+    in `routes_slack` is `admin_gate`; an automation lives in the Agents module and every door in
+    `routes_automation` is `module_gate("automation")`. A harness file is configuration OF the
+    agent it hangs off, so it is reached by whoever may already configure that agent. Picking one
+    of the two walls for both would either lock the Agents module's own users out of a tab the
+    owner asked for, or hand the Slack permission wall to anyone with an automation grant.
+    """
+    kind = agent_kind(session.runtime, agent_id)
+    if kind is None:
+        raise err(404, "no_agent", "there is no agent with that id in this workspace")
+    if kind == AGENT_SLACK:
+        import core.perms as perms
+        if not perms.is_admin(session.user):
+            raise err(403, "forbidden", "administrators only")
+    else:
+        session.require("automation")
+    return kind
+def normalize_path(raw):
+    """THE path rule, in ONE place. Returns the cleaned path, or `None` if it is not acceptable.
+    ⛔⛔ ONE RULE, TWO DOORS, AND THAT IS WHY THIS IS A FUNCTION RATHER THAN TWO IF-BLOCKS. There
+    are two ways into this store — the HTTP route (which must answer 400) and `record_version()`
+    (which must raise `ValueError`, having no response to put a status into). Written twice, the
+    two copies are [[one-question-two-normalizers]] waiting to happen: the first weakening of one
+    copy is invisible because the other still refuses, so nothing goes red and the wall is now
+    half there. Written once, a change to the rule is felt at both doors and by the gate.
+    """
+    path = str(raw or "").strip().strip("/")
+    if not path or len(path) > MAX_PATH:
+        return None
+    if set(path) - _PATH_OK or ".." in path or "//" in path:
+        return None
+    return path
+def _clean_path(raw):
+    """`normalize_path` at the HTTP door, where a refusal is a 400 with a reason."""
+    path = normalize_path(raw)
+    if path is None:
+        if not str(raw or "").strip().strip("/"):
+            raise err(400, "no_path", "a harness file needs a path, for example skills/router.md")
+        if len(str(raw)) > MAX_PATH:
+            raise err(400, "path_too_long", f"a harness path is at most {MAX_PATH} characters")
+        raise err(400, "bad_path",
+                  "a harness path may use letters, digits, dot, dash, underscore and / only")
+    return path
+def _blank(path, author, author_kind):
+    return {"path": path, "versions": [], "trimmed": 0,
+            "created": _now(), "createdBy": author, "createdKind": author_kind}
+def _append(record, body, author, author_kind, restored_from=None):
+    """Append ONE version to a file record, in place, and report what was trimmed.
+    The version NUMBER is monotonic and survives trimming — it counts writes, not stored entries.
+    A version list whose numbers restart at 1 after a trim would make two different bodies share a
+    name, and `restoredFrom` would then point at whichever one happened to be in the window.
+    """
+    # ⚠ A NEW LIST, NEVER `versions.append(...)` ON THE STORED ONE. `update()` hands the callback
+    # the live document and may run it more than once; appending in place would then stack two
+    # copies of the same version into the history on a retry.
+    prior = record.get("versions") if isinstance(record.get("versions"), list) else []
+    last = max((int(v.get("version") or 0) for v in prior if isinstance(v, dict)), default=0)
+    entry = {"version": last + 1, "body": body, "author": author, "authorKind": author_kind,
+             "created": _now(), "bytes": len(body.encode("utf-8"))}
+    if restored_from:
+        entry["restoredFrom"] = int(restored_from)
+    versions = [*prior, entry]
+    dropped = max(0, len(versions) - MAX_VERSIONS)
+    if dropped:
+        versions = versions[dropped:]
+    record["versions"] = versions
+    record["trimmed"] = int(record.get("trimmed") or 0) + dropped
+    return entry
+def _head(record):
+    """The newest version of a file record, or `None` for a record with no versions at all."""
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    return versions[-1] if versions else None
+def _row(record):
+    """One file, as the LIST door reports it: everything except the bodies.
+    ⚠ NO BODY, AND THAT IS THE POINT. A list door that carried every version of every file would
+    ship the whole harness on every pane render; the Harness tab lists first and opens one file
+    second, which is exactly the shape this answers.
+    """
+    head = _head(record) or {}
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    return {"path": record.get("path") or "",
+            "version": int(head.get("version") or 0),
+            "bytes": int(head.get("bytes") or 0),
+            "author": head.get("author") or record.get("createdBy") or "",
+            "authorKind": head.get("authorKind") or record.get("createdKind") or "user",
+            "updated": head.get("created") or record.get("created") or "",
+            "created": record.get("created") or "",
+            "versions": len(versions),
+            "trimmed": int(record.get("trimmed") or 0)}
+def _version_rows(record):
+    """The history of one file, newest first, WITHOUT the bodies.
+    A body per version is what makes a diff possible, and it is also what makes this payload big:
+    100 versions of a 128 KB file is 12 MB. The client asks for the two bodies it is diffing
+    (`?path=…&version=N`), which is two round trips for a diff and none for a history list.
+    """
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    out = []
+    for entry in reversed(versions):
+        if not isinstance(entry, dict):
+            continue
+        row = {"version": int(entry.get("version") or 0),
+               "author": entry.get("author") or "",
+               "authorKind": entry.get("authorKind") or "user",
+               "created": entry.get("created") or "",
+               "bytes": int(entry.get("bytes") or 0)}
+        if entry.get("restoredFrom"):
+            row["restoredFrom"] = int(entry["restoredFrom"])
+        out.append(row)
+    return out
+def _limits():
+    """The caps, IN the payload, so a client can say "this file is full" before a write fails.
+    ⚠ A limit the client cannot see is a limit the user meets as an error. `trimmed` reports the
+    one cap that acts without refusing; these report the three that refuse.
+    """
+    return {"maxBodyBytes": MAX_BODY_BYTES, "maxFiles": MAX_FILES,
+            "maxVersions": MAX_VERSIONS, "maxPath": MAX_PATH}
+# ── the write door the SERVER uses (no session) ────────────────────────────────────────────────
+def record_version(runtime, agent_id, path, body, author="", author_kind="agent",
+                   restored_from=None):
+    """Write one version from INSIDE the server — the agent's own half of R8.
+    ⭐ THIS IS THE FUNCTION, NOT THE ROUTE, THAT MAKES "editable by BOTH the user and the agent"
+    true. An agent acting inside an automation run holds no session and no cookie; if its only way
+    to write were the HTTP door it would have to borrow a person's identity, and the authorship
+    column would then be a record of who was logged in rather than of what wrote the file.
+    Returns the appended entry. Raises nothing the caller cannot handle: an unknown agent is a
+    `ValueError`, because a server-side caller has no HTTP response to put a 404 into.
+    """
+    agent_id = str(agent_id or "")
+    if not _known_agent(runtime, agent_id):
+        raise ValueError(f"no agent {agent_id!r} in this workspace")
+    path = normalize_path(path)
+    if path is None:
+        raise ValueError("that is not an acceptable harness path")
+    body = str(body or "")
+    if len(body.encode("utf-8")) > MAX_BODY_BYTES:
+        raise ValueError("harness body is over the size limit")
+    kind = author_kind if author_kind in AUTHOR_KINDS else "agent"
+    author = str(author or agent_id)
+    # ⛔ THE FILE-COUNT CEILING IS CHECKED HERE, NOT INSIDE `_set`. An exception raised inside a
+    # store `update` callback propagates out of a half-run read-modify-write, and the one thing a
+    # refusal must never do is leave the caller unsure whether the write happened.
+    existing = _files(runtime, agent_id)
+    if path not in existing and len(existing) >= MAX_FILES:
+        raise ValueError(f"this agent already has {MAX_FILES} harness files")
+    appended = {}
+    def _set(cur):
+        cur = dict(cur or {})
+        files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
+        record = dict(files[path]) if isinstance(files.get(path), dict) else _blank(path, author, kind)
+        appended.clear()
+        appended.update(_append(record, body, author, kind, restored_from))
+        files[path] = record
+        cur[agent_id] = files
+        return cur
+    runtime.update(HARNESS_KEY, _set, flush="sync")
+    return appended
+# ── the routes ────────────────────────────────────────────────────────────────────────────────
+@router.get("/agents/{agent_id}/harness")
+def get_harness(agent_id: str, path: str = "", version: int = 0,
+                session: Session = Depends(require_session)):
+    """The list, one file, or one older body — decided by the query string (C4).
+    ⚠ ADMIN-GATED LIKE EVERY OTHER AGENT DOOR (`routes_slack`), and for a stronger reason than
+    consistency: a harness file is what the agent is INSTRUCTED to do, so writing one is closer to
+    editing a permission than to editing a document.
+    """
+    agent_id = str(agent_id or "")
+    agent_wall(session, agent_id)
+    files = _files(session.runtime, agent_id)
+    if not path:
+        rows = [_row(rec) for _p, rec in sorted(files.items()) if isinstance(rec, dict)]
+        return {"agent": agent_id, "files": rows, "limits": _limits()}
+    wanted = _clean_path(path)
+    record = files.get(wanted)
+    if not isinstance(record, dict):
+        raise err(404, "no_file", f"this agent has no harness file at {wanted}")
+    versions = record.get("versions") if isinstance(record.get("versions"), list) else []
+    if version:
+        for entry in versions:
+            if isinstance(entry, dict) and int(entry.get("version") or 0) == int(version):
+                return {"agent": agent_id, **_row(record), "body": entry.get("body") or "",
+                        "atVersion": int(version), "history": _version_rows(record),
+                        "limits": _limits()}
+        # ⛔ A TRIMMED VERSION IS A NAMED REFUSAL, NOT A 404 SHAPED LIKE A TYPO. The client asked
+        # for something that existed and no longer does, and telling it apart from a bad number is
+        # the difference between "roll back to v3" failing loudly and failing as if v3 never was.
+        trimmed = int(record.get("trimmed") or 0)
+        if trimmed and int(version) <= trimmed:
+            raise err(410, "version_trimmed",
+                      f"version {int(version)} is older than the {MAX_VERSIONS} versions kept "
+                      f"for this file, and its body is gone")
+        raise err(404, "no_version", f"this file has no version {int(version)}")
+    head = _head(record) or {}
+    return {"agent": agent_id, **_row(record), "body": head.get("body") or "",
+            "atVersion": int(head.get("version") or 0), "history": _version_rows(record),
+            "limits": _limits()}
+@router.put("/agents/{agent_id}/harness")
+def put_harness(agent_id: str, body: dict = Body(default=None),
+                session: Session = Depends(require_session)):
+    """Write a NEW version of one harness file. `{path, body, authorKind?, restoredFrom?}` (C4).
+    ⛔ THERE IS NO OVERWRITE HERE AND THERE IS NO EDIT-IN-PLACE. R8's "every version kept" is not a
+    UI affordance; it is this function refusing to have a code path that replaces a body. A
+    roll-back arrives as an ordinary write carrying `restoredFrom`, so the history records that
+    somebody went back rather than pretending the intervening versions never happened.
+    """
+    agent_id = str(agent_id or "")
+    agent_wall(session, agent_id)
+    body = body if isinstance(body, dict) else {}
+    path = _clean_path(body.get("path"))
+    text = body.get("body")
+    if not isinstance(text, str):
+        raise err(400, "no_body", "a harness file needs a body, even an empty one")
+    if len(text.encode("utf-8")) > MAX_BODY_BYTES:
+        raise err(413, "body_too_long",
+                  f"a harness file is at most {MAX_BODY_BYTES // 1024} KB; this one is larger")
+    # ⚠ THE CALLER DECLARES THE PROVENANCE AND THE SERVER STAMPS THE IDENTITY. `authorKind` is a
+    # claim about who WROTE the text (the person, or the agent in the chat panel); `author` is the
+    # session and is never read off the request. Nothing is bought by forging the first — both
+    # principals may write (R8) — and everything would be bought by forging the second.
+    kind = str(body.get("authorKind") or "user").strip().lower()
+    if kind not in AUTHOR_KINDS:
+        raise err(400, "bad_author_kind", "authorKind is either user or agent")
+    restored = body.get("restoredFrom")
+    try:
+        restored = int(restored) if restored else None
+    except (TypeError, ValueError):
+        raise err(400, "bad_version", "restoredFrom must be a version number")
+    files = _files(session.runtime, agent_id)
+    if path not in files and len(files) >= MAX_FILES:
+        raise err(409, "too_many_files",
+                  f"this agent already has {MAX_FILES} harness files; delete one to add another")
+    try:
+        record_version(session.runtime, agent_id, path, text,
+                       author=session.uname, author_kind=kind, restored_from=restored)
+    except ValueError as exc:
+        raise err(400, "refused", str(exc))
+    fresh = _files(session.runtime, agent_id).get(path)
+    if not isinstance(fresh, dict) or not _head(fresh):
+        # The store took the write and did not record it. A 200 here would tell an administrator
+        # their skill file was saved when it was not — the shape `routes_slack` refuses too.
+        raise err(503, "store_unavailable", "the harness file was NOT saved")
+    head = _head(fresh)
+    return {"agent": agent_id, **_row(fresh), "body": head.get("body") or "",
+            "atVersion": int(head.get("version") or 0), "history": _version_rows(fresh),
+            "limits": _limits()}
+@router.delete("/agents/{agent_id}/harness")
+def delete_harness(agent_id: str, path: str = "", session: Session = Depends(require_session)):
+    """Drop one harness file AND its history.
+    ⚠ THIS IS NOT THE THING R8 FORBIDS. R8 forbids a ROLL-BACK implemented as a delete — losing
+    versions as a side effect of an edit. Deleting a file is a person deciding the file should not
+    exist, which is a different act with a different button, and a store with no way to remove a
+    file is one where a typo'd path is permanent.
+    """
+    agent_id = str(agent_id or "")
+    agent_wall(session, agent_id)
+    wanted = _clean_path(path)
+    if wanted not in _files(session.runtime, agent_id):
+        raise err(404, "no_file", f"this agent has no harness file at {wanted}")
+    def _set(cur):
+        cur = dict(cur or {})
+        files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
+        files.pop(wanted, None)
+        # An agent with no harness files leaves NO key behind. An empty dict per agent id is how a
+        # bucket accumulates a row for every agent anybody ever opened the tab on.
+        if files:
+            cur[agent_id] = files
+        else:
+            cur.pop(agent_id, None)
+        return cur
+    session.runtime.update(HARNESS_KEY, _set, flush="sync")
+    return {"agent": agent_id, "deleted": wanted,
+            "files": [_row(rec) for _p, rec in sorted(_files(session.runtime, agent_id).items())
+                      if isinstance(rec, dict)],
+            "limits": _limits()}

api/routes_alerts.py CHANGED Viewed

@@ -1,668 +1,668 @@
-"""routes_alerts.py — the Alerts module (wave 20, owner item 25, contract C-ALERT).
-    GET    /api/v1/alerts                  -> {alerts:[...]}
-    POST   /api/v1/alerts                  <- {viewId, topic, label?}
-    DELETE /api/v1/alerts/{alert_id}
-    POST   /api/v1/alerts/{alert_id}/run   -> evaluate now (the pane's manual refresh)
-    GET    /api/v1/notifications           -> {unread, items:[...]}
-    POST   /api/v1/notifications/read      <- {ids:[...]|null, read?:bool}
-The semantics — an alert is a view plus a remembered matched set, a notification is a NEW
-ENTRANT, and the first evaluation seeds silently — live in `core.alerts` with the reasoning.
-This file owns the two things a route must: WHO may do it, and HOW the view gets evaluated.
-⭐ **THE EVALUATION RUNS AS THE ALERT'S OWNER, NOT AS THE CALLER.** `_run_alert` builds the pool
-for `rec['owner']`, never for whoever tripped the write hook. Any other choice leaks: a
-full-access admin editing a cell would otherwise evaluate a BU-scoped user's alert over the whole
-book, and the notification would name customers that user may not see — a permission leak wearing
-a notification's clothes. The owner's own scope is the only correct basis for their alert.
-⚠ **AN ALERT IS NOT A SECOND READ PATH.** It resolves rows through the same
-`routes_customers.grid_assembly` / `routes_tables.ut_assembly` the grid uses, so a row that an
-alert can see is by construction a row its owner could open. Re-implementing the filter here
-would be a second definition of "matches", and those two would drift.
-"""
-import re
-from fastapi import APIRouter, Body, Depends
-import core.alerts as alerts
-from deps import Session, err, require_session
-router = APIRouter(prefix="/api/v1")
-#: The alert-bearing surfaces. `ut_` tables are admitted by prefix, like everywhere else.
-_TOPICS = ("customer", "product")
-# ── ⭐⭐ WAVE 32 · T20 · CONTRACT C3 — THE INBOX SHAPE, DERIVED ON READ ────────────────────────
-#
-# `GET /notifications` gains `subject`, `kind` and `target` per item (`read` was always there).
-#
-# ⛔ DERIVED, NEVER STORED, AND THAT IS THE WHOLE OF WHY THIS WAVE EXISTS. Stamping the three
-# keys onto the record at write time would give them to notifications minted AFTER the deploy and
-# to nothing else — every notification already sitting in every tenant's inbox would open nothing,
-# and the feature would be correct in the source and absent from the product
-# ([[a-migration-that-runs-on-the-next-write]], D-201). A read-side derivation reaches a
-# notification queued last month. It also keeps the store shape out of `core/alerts.py`, which is
-# another lane's file this wave — but that is the convenience, not the reason.
-#
-# ⚠ TWO PRODUCERS WRITE TWO SHAPES into one inbox, and the vocabulary below is what tells them
-# apart. `_queue` (a record ENTERED a watched view) sets `topic`+`viewId`. `notify()` sets
-# `topic='automation'` and puts the producer's key in `alertId`, leaving `viewId` empty. Deciding
-# here means the client branches on ONE field instead of re-deriving the same split.
-#
-# ⛔ **D-101 IS CLOSED HERE, BY SUBTRACTION.** There was a THIRD shape — `kind='automation_review'`
-# + `autoId`, a card arriving at a review stage — and its producer `notify_review` was deleted by
-# W27/R3 with the review lanes. `automation_engine.py`'s own tombstone (search `notify_review`)
-# records the 2026-08-12 sweep: **no `.py` file anywhere produces one**, while the client branch,
-# its route and three gate legs stayed fully alive. D-101's exit condition is *"the client review
-# branch is deleted in the same change as any remaining residue, OR `notify_review` gains its real
-# caller"* — the residue is zero, so the branch goes. It is not carried into the Inbox: a stored
-# review notification (if any survives in a tenant from the wave-23 era) derives as an ordinary
-# `alert` with no target, i.e. an honest unclickable row, which is correct — the board it pointed
-# at was deleted two waves ago.
-#: C3's `kind` vocabulary. Plain strings on the wire — the client must never union over them
-#: (alertsModel's wave-9 law: a client union turns "the server grew a kind" into a dropped row).
-NOTIF_KIND_ALERT = "alert"
-NOTIF_KIND_AUTOMATION = "automation"
-NOTIF_KIND_SHARE = "share"
-#: C3's `target.module` vocabulary, and the automation sub-selection.
-TARGET_MODULE_DATABASE = "database"
-TARGET_MODULE_AUTOMATION = "automation"
-TARGET_TAB_RUNS = "runs"
-#: The topic `notify()` carries for a SHARE (W32-T28 writes it; nothing does yet, and a kind with
-#: no producer is a string that reads as a feature — the reason this constant is named here and
-#: cited from `routes_shares` rather than typed twice).
-SHARE_TOPIC = "share"
-#: `core.alerts.notify`'s default topic for a run outcome. Mirrors `inboxModel.AUTOMATION_TOPIC`.
-AUTOMATION_TOPIC = "automation"
-_UT_TOPIC = re.compile(r"ut_[A-Za-z0-9_]+\Z")
-def route_for_topic(topic):
-    """A grid SCOPE key -> the registry route that renders it, or None.
-    ⛔ THE SAME TABLE AS `alertsModel.routeForTopic`, and the parity is GATED
-    (`verify_alerts.py`'s vocabulary scan) rather than trusted. The two built-ins are the only
-    pair that differ — the registry names the surface (`customer_data`) while the grid names the
-    scope (`customer`) — so a topic passed through as a route sends every click to a page that
-    does not exist. `None` for anything else: a target this product cannot resolve must be ABSENT
-    rather than plausible, because an absent target renders as a row that does not pretend to be
-    clickable, and a wrong one renders as a click that silently goes nowhere.
-    """
-    t = str(topic or "").strip()
-    if t == "customer":
-        return "customer_data"
-    if t == "product":
-        return "product_data"
-    if _UT_TOPIC.match(t):
-        return t
-    return None
-def _refusal_code(exc):
-    """The `error.code` an `HTTPException` raised by `deps.err()` carries, or `""`.
-    ⭐ W32-T22. Four refusals travel up the assembly chain — `unknown_table` (404), `forbidden`
-    (403), `window_required` (409) and `store_not_ready` (503) — and each already names its own
-    cause. Anything that reduces all four to one word is throwing away the only information the
-    reader could have acted on. Returns `""` for a plain exception, so a caller can tell
-    "refused, and here is why" apart from "broke, and we do not know why".
-    """
-    detail = getattr(exc, "detail", None)
-    if isinstance(detail, dict):
-        inner = detail.get("error")
-        if isinstance(inner, dict):
-            return str(inner.get("code") or "")
-    return ""
-def notification_view(item):
-    """One STORED notification -> the shape the Inbox renders. PURE, and total.
-    Never raises and never drops a row: an item it cannot classify comes back as an `alert` with
-    no `target`, which the client renders as an unclickable row rather than hiding. An inbox that
-    silently omits what it does not understand is the one failure a reader cannot detect.
-    """
-    if not isinstance(item, dict):
-        return item
-    topic = str(item.get("topic") or "").strip()
-    alert_id = str(item.get("alertId") or "").strip()
-    # ⛔ THE ID TEST IS HALF OF EVERY BRANCH, and it is the load-bearing half. A row whose topic
-    # says `automation` but whose producer key never arrived (a truncated payload, a server
-    # mid-deploy) would otherwise be handed a target naming NOTHING — a click that appears to work
-    # and silently does not, which is this repo's most-repeated failure shape. Failing the test
-    # drops it to the `alert` branch, where `route_for_topic` refuses out loud by answering None.
-    if topic == AUTOMATION_TOPIC and alert_id:
-        kind = NOTIF_KIND_AUTOMATION
-        target = {"module": TARGET_MODULE_AUTOMATION, "id": alert_id, "tab": TARGET_TAB_RUNS}
-    elif topic == SHARE_TOPIC and alert_id:
-        # ⭐ W32-T28: the sharer writes `key=<the ROUTE to open>` and, for a shared VIEW,
-        # `row_id=<the view to select>`.
-        #
-        # ⛔ `key` IS ALREADY A ROUTE, NOT A RAW OBJECT ID, and the first version of this got it
-        # wrong in a way worth recording: a shared VIEW put the VIEW's id in `alertId`, so the
-        # target read `{module: "database", id: "view_42"}` — an instruction to open a database
-        # called `view_42`. It looked right in the payload and would have opened nothing. The
-        # producer resolves the object to its topic and hands over the route; this branch only
-        # shapes what it is given.
-        kind = NOTIF_KIND_SHARE
-        row_id = str(item.get("rowId") or "").strip()
-        target = {"module": TARGET_MODULE_DATABASE, "id": alert_id,
-                  **({"tab": row_id} if row_id else {})}
-    else:
-        kind = NOTIF_KIND_ALERT
-        route = route_for_topic(topic)
-        view_id = str(item.get("viewId") or "").strip()
-        target = None if route is None else (
-            {"module": TARGET_MODULE_DATABASE, "id": route,
-             **({"tab": view_id} if view_id else {})})
-    # The email split: `subject` is the HEADER (what this is about — the alert, the automation,
-    # the database), `label` stays the BODY (what happened — the record that entered, the run
-    # summary). They were one field, which is why a notification read as a sentence with no
-    # sender and the pane could not be laid out like mail.
-    subject = str(item.get("alertLabel") or "").strip() or str(item.get("label") or "").strip()
-    # ⚠ `kind` is OVERWRITTEN, not merged. There was one stored value (`automation_review`) and it
-    # is D-101's dead one; leaving it through would give the client two vocabularies for one
-    # question, which is the defect this wave's item 6 is about in a different file.
-    # ⭐⭐ W33-T28 (owner: "the Inbox reads like email") — THE SENDER, WHICH DID NOT EXIST.
-    #
-    # ⛔ A `verifier` reading the finished wave-32 surface found that the row's sender POSITION was
-    # occupied by `kindLabel(n.kind)` — the literals "Alert" / "Automation" / "Shared with you" —
-    # i.e. a CATEGORY standing where a who belongs, and no sender field anywhere on the wire, in
-    # the model or in the markup. Mail has a from. This is it.
-    #
-    # ⚠ IT IS DERIVED HERE, NOT STORED, FOR EVERY KIND BUT ONE — and the exception is the point.
-    # An alert firing and an automation landing rows have no person behind them; their honest
-    # sender is the machine that did it, named as the thing the reader recognises. A SHARE has a
-    # real person, and only the producer knows who: `routes_shares.py` writes it as `actor` and
-    # this reads it back. ⛔ It is NOT parsed out of the body prose ("<name> shared this with
-    # you") — a sender recovered by regexing a sentence breaks the first time the sentence is
-    # reworded, and it would break silently, in the header.
-    #
-    # ⚠ FALLS BACK, NEVER BLANK. A share queued BEFORE `actor` existed has none, and a row with an
-    # empty from column reads as a broken inbox rather than as an old notification.
-    actor = str(item.get("actor") or "").strip()
-    if kind == NOTIF_KIND_SHARE:
-        sender = actor or "A teammate"
-    elif kind == NOTIF_KIND_AUTOMATION:
-        # ⛔ "Agents", not "Automation" (W34-T40, corrected at QA 2026-08-17). The client's
-        # `senderOf` already falls back to `AGENTS_MODULE_LABEL` — but `if (sent) return sent`
-        # runs FIRST, so this server literal won and every actor-less automation notification
-        # showed the retired module name in the inbox's From column.
-        sender = actor or "Agents"
-    else:
-        sender = actor or "Alerts"
-    out = {**item, "read": bool(item.get("read")), "kind": kind,
-           "subject": subject or "Notification", "sender": sender}
-    if target is not None:
-        out["target"] = target
-    return out
-def inbox_view(box):
-    """`core.alerts.inbox()`'s answer, with every item put through {@link notification_view}.
-    ⚠ `unread` IS NOT RECOUNTED. It is the ACCOUNT's number and `items` is one page of it; a
-    recount here would make the badge a function of whatever this page happened to include, which
-    is the exact defect `alertsModel.parseInbox`'s own header records from the other side.
-    """
-    if not isinstance(box, dict):
-        return box
-    items = box.get("items")
-    if not isinstance(items, list):
-        return box
-    # ⭐⭐ W33-T28 / D-208 — THE SERVER'S CLOCK RIDES WITH THE PAGE, and it is what lets the client
-    # render a mail-shaped stamp ("09:41" today, "Aug 12" beyond) instead of `2026-08-13 09:41`.
-    #
-    # ⛔ THE CLIENT MUST NOT READ ITS OWN CLOCK, which is D-208's exit condition word for word and
-    # is why this key exists rather than a `new Date()` in the browser. `at` is sent as UTC WITH
-    # its offset (D-18) precisely so every reader sees the same instant; deciding "is this today?"
-    # against a browser clock would re-introduce the drift the offset exists to remove — a reader a
-    # day ahead being told an event happened tomorrow [[date-window-vocabulary]]. Both operands
-    # now come from the same machine.
-    # ⚠ Same funnel as the enrichment, so the read door and the mark-read door cannot disagree —
-    # the note two lines up records what happened last time only one of them was enriched.
-    return {**box, "now": alerts._now_iso(),
-            "items": [notification_view(n) for n in items]}
-def _view_by_id(g, view_id):
-    """One saved view out of an assembly, by id. `None` when there is no such view.
-    ⛔⛔ W33-T29 (owner: *"Alert me about new records"* answering "Something went wrong") — THIS
-    FUNCTION EXISTS BECAUSE TWO CALL SITES BOTH WROTE `(g.get("views") or {}).get(view_id)`, AND
-    `g["views"] IS A LIST`. `aios_grid.views_from_defs` returns `[{...}]`, `workspace_wire` passes
-    it straight out and both `ut_assembly` and `grid_assembly` return it unchanged — so `.get` on
-    it raises `AttributeError`, and `views_from_defs` always returns at least one element, so the
-    `or {}` never fires. **It raised on EVERY call, on every topic, since wave 20.**
-    ⛔ AND THE TWO SITES FAILED DIFFERENTLY, WHICH IS WHY ONLY ONE WAS EVER REPORTED. In
-    `_require_filtered_view` the raise lands ABOVE the handler's own `try`, so it leaves as a bare
-    FastAPI 500 and the client's `errorMessage` turns any 5xx into *"Something went wrong on our
-    side"* — the exact sentence the owner reported (D-107's shape, again: an attribute error above
-    the guard arrives as plain text rather than as our envelope). In `_evaluate` the identical
-    line is swallowed by `/notifications`' `except Exception: continue`, so **every stored
-    view-alert was silently dropped from the Inbox** and nobody had anything to report at all.
-    One expression, one loud symptom and one silent one.
-    ⚠ SO IT IS A FUNCTION, NOT TWO FIXED LINES. Two copies of "find the view" is what let one site
-    be discussed for three waves while its twin went unnoticed [[one-question-two-normalizers]].
-    ⚠ It accepts a dict too, and that is not defensive noise: `verify_alerts`' door fixture was
-    keyed `{id: view}` — which is precisely why the gate was green while production raised on
-    every call. The fixture is moving to the production shape in this same change, and tolerating
-    both here means a caller that legitimately holds one cannot resurrect the bug.
-    """
-    want = str(view_id or "")
-    if not want:
-        return None
-    views = (g or {}).get("views")
-    if isinstance(views, dict):
-        found = views.get(want)
-        return found if isinstance(found, dict) else None
-    if not isinstance(views, list):
-        return None
-    for v in views:
-        if isinstance(v, dict) and str(v.get("id") or "") == want:
-            return v
-    return None
-def _topic_or_400(raw):
-    topic = str(raw or "").strip().lower()
-    if topic.startswith("ut_") or topic in _TOPICS:
-        return topic
-    raise err(400, "bad_topic", f"topic must be one of {', '.join(_TOPICS)} or a ut_ table")
-def _owner_session(session: Session, owner: str):
-    """A `Session` for the alert's OWNER (see the module note on why the owner, not the caller).
-    ⚠ `Session` exposes `uname`/`admin` as PROPERTIES derived from `user`, not as fields — so an
-    owner session is built by swapping the `user` RECORD and letting both derive themselves. An
-    earlier version passed `uname=`/`admin=` to the constructor, which would have raised on the
-    first write hook of the wave; the properties are the single definition of who a session is,
-    and going around them is how a session with an admin flag and a non-admin record exists.
-    Returns None when the owner is gone or deactivated — their alerts then stop evaluating rather
-    than evaluating as somebody else, which is the fail-closed direction.
-    """
-    import core.users as users
-    if str(owner) == str(session.uname):
-        return session
-    rec = (users.registry() or {}).get(str(owner))
-    if not isinstance(rec, dict) or not rec.get("active", True):
-        return None
-    # `_public` is THE definition of what a session may know about its own account (never a hash
-    # or a salt) — the same one `routes_auth` uses. Building the dict by hand here would be a
-    # second definition, and the one that leaks is always the copy.
-    return Session(tenant=session.tenant, user=users._public(str(owner), rec),
-                   claims=session.claims, runtime=session.runtime)
-def _evaluate(session: Session, rec: dict, assemblies=None):
-    """Resolve `rec`'s view over its topic AS THE ALERT'S OWNER, then fold the result in.
-    ⭐⭐ W31-T24 — `assemblies` IS A PER-REQUEST MEMO, KEYED `(topic, owner)`, and it is the whole
-    of this ticket's server half. `/notifications` re-evaluates EVERY alert inline on read and each
-    one built a FULL assembly — the pool, the workspace, `rows_from_pool` over every row. Two
-    alerts on one view built that table twice; ten built it ten times. Nothing dedupes them,
-    because each `_evaluate` was a closed call.
-    ⚠ `(topic, owner)` and not `topic`: the assembly is built as the alert's OWNER (see the module
-    note — evaluating a BU-scoped user's alert on a full-access admin's pool is a permission leak
-    wearing a notification's clothes), so two owners on one topic are two DIFFERENT tables and
-    must never share an entry. Getting that key wrong is the one way this optimisation could leak.
-    ⚠ Passing nothing keeps the old behaviour exactly, which is what the create/run doors want:
-    they evaluate ONE alert and a memo for a single call is pure overhead.
-    """
-    import aios_grid
-    from harness import filter_eval
-    owner_sess = _owner_session(session, rec.get("owner"))
-    if owner_sess is None:
-        return {"skipped": "owner_unavailable"}
-    topic = str(rec.get("topic") or "")
-    memo_key = (topic, str(owner_sess.uname))
-    g = assemblies.get(memo_key) if isinstance(assemblies, dict) else None
-    if g is None:
-        try:
-            if topic.startswith("ut_"):
-                from routes_tables import ut_assembly
-                # ⛔ `consume_corrections=False`, and the default was a REAL BUG, not a tidy-up.
-                # `ut_assembly` defaults it True, so every `/notifications` read CONSUMED the
-                # one-shot field-name correction acks for every `ut_` topic that has an alert —
-                # taking them from the `/workspace` refresh that exists to show them to the person
-                # who made the edit. The customer branch below has always passed False; this one
-                # inherited a default nobody re-read. An inbox poll must never consume a one-shot.
-                g = ut_assembly(owner_sess, topic,
-                                storage_key=f"{owner_sess.tenant}:{topic}:{owner_sess.uname}",
-                                consume_corrections=False)
-            else:
-                from routes_customers import grid_assembly
-                g = grid_assembly(owner_sess, scope=topic, consume_corrections=False)
-        except Exception as e:                              # noqa: BLE001
-            # ⭐ W32-T22 — SKIPPING IS FINE HERE; SKIPPING ANONYMOUSLY IS NOT. This one must not
-            # raise (one bad alert cannot empty an inbox), so unlike `_require_filtered_view` it
-            # keeps a blanket catch — but it now reports the refusal's OWN code where there is
-            # one. `type(e).__name__` said `HTTPException` for four different causes, and
-            # `lastError` is the only place a user ever learns why an alert stopped firing.
-            #
-            # ⚠ `with_rows=True` STAYS on this path, deliberately: unlike the create door, an
-            # evaluation genuinely needs the rows to run the filter over. So an alert on a
-            # read-through grid is created (T22) and then skips at evaluation with
-            # `window_required` naming why — which is D-184's remaining half, and it is a
-            # SENTENCE now rather than silence.
-            return {"skipped": _refusal_code(e) or "unavailable", "detail": type(e).__name__}
-        if isinstance(assemblies, dict):
-            assemblies[memo_key] = g
-    view = _view_by_id(g, rec.get("viewId"))
-    if not isinstance(view, dict):
-        # Deleted, or un-shared out from under the alert. Say so on the RECORD rather than
-        # deleting the alert: an alert that silently vanishes is indistinguishable from one that
-        # never fires, and the user cannot debug what is not there.
-        return {"skipped": "view_missing"}
-    # The SAME row build the grid and `/customers` use — `rows_from_pool` is what puts derived
-    # and overlay values on a row. Evaluating a filter against raw pool dicts would silently
-    # never match any condition on a user-created or measure column.
-    #
-    # ⛔⛔ AND "THE SAME ROW BUILD" WAS NOT TRUE, WHICH MADE EVERY ALERT ON A `ut_*` DATABASE BLIND
-    # TO IMPORTED DATA. Found by a verifier driving one real assembly through both paths.
-    #
-    # `routes_tables.table_rows` — the grid the person is looking at — merges the DEFINITION rows
-    # underneath the overlay ("base first, overlay wins"; that merge is itself the fix for owner
-    # item 3, *"it all got reseted"*). `_evaluate` is a second copy of that read and never got it:
-    # it handed `ws['overlays']` to `rows_from_pool` raw, so for a `ut_*` table every base cell
-    # evaluated as BLANK. Measured on one assembly, same view, same rows:
-    #     rows_src        state='unpaid' / 'paid'
-    #     _evaluate saw   state=''       / ''          ⇐ every base cell blank
-    #     the GRID saw    state='unpaid' / 'paid'
-    # so `state eq unpaid` matched NOTHING while the view showed one row, and `state isEmpty`
-    # matched EVERYTHING while the view showed none. **The alert did not merely miss rows — it
-    # inverted.** End to end: a row whose value arrived by import, automation, paste or the create
-    # door never fired; only a value typed as a hand EDIT did.
-    #
-    # ⚠ Scope, so nobody widens the fix past its cause: materialised `ut_*` tables are hit;
-    # `customer`/`product` are not (their fields are `source: "odoo"` and read off `rows_src`);
-    # `ut_odoo_*` never reaches here (`with_rows=True` refuses first and returns
-    # `skipped: window_required`).
-    # ⛔ ORDER IS LOAD-BEARING AND IS THE GRID'S: base underneath, overlay ON TOP. Inverting it
-    # would let a stale definition value shadow an edit the user has just made — the same defect
-    # `table_rows`' own note records, arriving from the other side.
-    _ov = (g.get("ws") or {}).get("overlays") or {}
-    _merged = {}
-    for _r in g["rows_src"]:
-        _pid = str(_r.get("pid"))
-        _cells = {k: v for k, v in _r.items() if k != "pid"}
-        _o = _ov.get(_pid)
-        if isinstance(_o, dict):
-            _cells.update(_o)
-        _merged[_pid] = _cells
-    rows = aios_grid.rows_from_pool(g["rows_src"], g["fields"], _merged,
-                                    derived=g.get("derived"))
-    config = view.get("config") or view
-    ctx = filter_eval.EvalCtx(
-        cohort_sets={str(k): {str(p) for p in (v.get("memberPids") or ())}
-                     for k, v in (g.get("lists") or {}).items() if isinstance(v, dict)},
-        measure_sets=g.get("measure_sets") or {},
-        today=g.get("today"))
-    pids = filter_eval.visible_pids(config.get("filters") or [], rows, g["fields"], ctx,
-                                    member_pids=config.get("memberPids"))
-    labels = {str(r.get("pid")): str(r.get("name") or r.get("pid")) for r in rows}
-    return alerts.evaluate(rec.get("id"), [str(p) for p in pids],
-                           labels=labels, partial=False, st=session.runtime)
-@router.get("/alerts")
-def list_alerts(session: Session = Depends(require_session)):
-    return {"alerts": alerts.list_alerts(user=session.uname, is_admin=session.admin,
-                                         st=session.runtime)}
-@router.post("/alerts")
-def create_alert(body: dict = Body(default=None), session: Session = Depends(require_session)):
-    body = body or {}
-    view_id = str(body.get("viewId") or "").strip()
-    if not view_id:
-        raise err(400, "bad_view", "an alert needs the id of the view it watches")
-    topic = _topic_or_400(body.get("topic"))
-    _require_filtered_view(session, topic, view_id)
-    import uuid
-    aid = f"al_{uuid.uuid4().hex[:12]}"
-    rec = alerts.create(aid, view_id=view_id, topic=topic, owner=session.uname,
-                        label=body.get("label") or "", st=session.runtime)
-    # SEED IMMEDIATELY, so the alert starts from "everything currently matching is old news".
-    # Deferring this to the first write hook would mean the next edit announces the whole view.
-    outcome = _evaluate(session, rec)
-    return {"alert": {**rec, "seeded": True}, "first": outcome}
-def _require_filtered_view(session: Session, topic: str, view_id: str):
-    """400 unless `view_id` exists on `topic` AND actually narrows something.
-    ⛔ AN ALERT ON AN UNFILTERED VIEW IS SILENTLY INCAPABLE OF ALERTING, which is worse than one
-    that is refused. `filter_eval` treats an inactive tree as "no narrowing, every row shows"
-    (`visible_pids`'s own rule), so such an alert seeds with the entire table and can never see an
-    entrant again — there is nothing left to enter. The owner's words are *"when a Record gets
-    into that Filter's criteria"*: no criteria, no alert, and said at creation rather than
-    discovered by never being notified.
-    `is_rule_active` is the SAME activeness predicate the engine and the column tints use — a
-    half-typed rule is not a filter, and this must agree with what actually narrows or it would
-    accept a view whose one rule the engine then ignores.
-    ⭐⭐ WAVE 32 · T22 (owner item 17) — THIS FUNCTION WAS THE ERROR. Two defects, stacked, and
-    the second one hid the first.
-    (1) **IT ASKED FOR EVERY ROW OF A TABLE IT NEVER LOOKS AT.** The only thing read below is
-        `g["views"]`. `ut_assembly` defaults `with_rows=True`, so creating an alert on a
-        read-through grid built the whole pool — and `scoped_pool` refuses that with
-        `409 window_required` over 963,783 rows, exactly as it is supposed to. `with_rows=False`
-        (W31-T20's flag, built for precisely this) answers the same question with `scoped_pids`,
-        runs the SAME `_defn_or_refuse` wall, and does not refuse. **That is D-184's create half,
-        closed** — an alert on a read-through grid can now be made at all.
-    (2) **A BLANKET `except Exception` TURNED EVERY NAMED REFUSAL INTO A 503.** `HTTPException`
-        is an `Exception`, so `404 unknown_table`, `403 forbidden`, `409 window_required` and
-        `503 store_not_ready` — four refusals that each say what is wrong — were all replaced by
-        *"the table is unavailable — try again in a moment"*. ⛔ AND THAT SENTENCE NEVER REACHED
-        A USER EITHER: `alertsApi.errorMessage` discards the text of any status ≥ 500 by design
-        (a 5xx body is the server's internals), substituting *"Something went wrong on our
-        side."* — which is the owner's screenshot, word for word. A knowable cause returned as a
-        5xx is invisible by construction, so re-wording the 503 could never have fixed this.
-    ⚠ The except is narrowed, not deleted: an UNEXPECTED failure is still a 503, because that is
-    honest. What it may no longer do is catch a refusal that already knows its own name.
-    """
-    from fastapi import HTTPException
-    from harness import filter_eval
-    try:
-        if topic.startswith("ut_"):
-            from routes_tables import ut_assembly
-            # ⚠ `consume_corrections=False` — the customer branch has always passed it and this
-            # one inherited a default nobody re-read. Creating an alert must not eat the one-shot
-            # field-name correction acks belonging to the `/workspace` refresh that exists to show
-            # them to the person who made the edit. Same defect `_evaluate`'s header records.
-            g = ut_assembly(session, topic,
-                            storage_key=f"{session.tenant}:{topic}:{session.uname}",
-                            consume_corrections=False, with_rows=False)
-        else:
-            from routes_customers import grid_assembly
-            g = grid_assembly(session, scope=topic, consume_corrections=False)
-    except HTTPException:
-        raise                                               # it already names its own cause
-    except Exception as e:                                  # noqa: BLE001
-        # Genuinely unexpected. Still a 503, and now it carries the exception TYPE — without it,
-        # the one path that reaches this branch is also the one path with nothing to debug from.
-        raise err(503, "unavailable",
-                  f"the table could not be read ({type(e).__name__}) — try again in a moment")
-    view = _view_by_id(g, view_id)
-    if not isinstance(view, dict):
-        raise err(404, "no_view", "that view does not exist on this table")
-    nodes, _conj = filter_eval.tree_parts((view.get("config") or view).get("filters") or [])
-    # ⛔⛔ WAVE 33 · T29 — **CORRECTION: THE BLOCK BELOW IS TRUE ABOUT THE CODE AND FALSE ABOUT
-    # PRODUCTION, AND IT MUST BE READ SECOND.** It claims the missing-argument `TypeError` "IS
-    # owner item 17" — the owner's *"Something went wrong"*. It was not, and it could not have
-    # been: at `cbcf005`, the build the owner was using, the dict-read on `views` sat ~10 lines
-    # ABOVE this call and raised `AttributeError` on EVERY request, so the walk never reached the
-    # leaf and the arity bug was unreachable. `_view_by_id`'s own header records that fix.
-    #
-    # ⚠ WHY THE STALE PARAGRAPH STAYS RATHER THAN GETTING DELETED: the arity bug was real, the
-    # fix was right, and the three reasons it hid are the most transferable thing in this file.
-    # What was wrong is only its CLAIM TO BE THE CAUSE. Two comment blocks in one function each
-    # naming themselves as the origin of the same screenshot are mutually exclusive, and the next
-    # reader believes whichever they meet first — which is why this correction sits above rather
-    # than below. Caught by a verifier that read the SHIPPED file at the deployed commit instead
-    # of the working tree. [[grep-output-is-not-source]]
-    #
-    # ⛔⛔ WAVE 32 · T22 — **THE CALL BELOW WAS MISSING AN ARGUMENT** (and wave 32 believed, wrongly,
-    # that this was owner item 17 — see the correction directly above).
-    #
-    # `is_rule_active(rule, columns)` takes TWO parameters (`harness/filter_sql.py`; every other
-    # caller in the repo passes both). This one passed ONE, so the moment the walk reached a LEAF
-    # rule it raised `TypeError: is_rule_active() missing 1 required positional argument`.
-    #
-    # ⚠ READ WHAT THAT MEANS BEFORE FIXING ANYTHING ELSE: the walk only reaches a leaf when the
-    # view HAS a condition — and a view with a condition is the only kind an alert is allowed on.
-    # A view with no filters yields an empty `nodes`, so `_any_active` returns False without ever
-    # calling this, and the reader gets the honest 400 `no_filter`. **So the only path that
-    # worked was the refusal path: "Alert me about new records" had never once created an alert
-    # on a filtered view.** ⛔ And the raise lands OUTSIDE the `try` above, so it was not even the
-    # 503 — it was a bare FastAPI 500, which `alertsApi.errorMessage` renders as *"Something went
-    # wrong on our side. Try again in a moment."*, the owner's screenshot word for word.
-    #
-    # ⚠ THREE THINGS HID IT, and they are worth more than the fix. (1) Python does not check
-    # arity until the line RUNS, and this line runs only on the success path of a feature whose
-    # every test exercised its refusals. (2) The `no_filter` 400 above it is a real, correct,
-    # well-tested refusal, so the door looked alive. (3) `verify_alerts.py` asserts the refusal
-    # (`no_filter` reaches the user) and the transport — never a creation. A gate can be green,
-    # thorough and honest about everything except the one path the feature exists for.
-    #
-    # `_columns_map` is the DEFINITION of fields -> the membership set `is_rule_active` looks a
-    # column up in; building a second dict here would be a second answer to one question, which
-    # is this wave's other headline defect in a different file. Its leading underscore is a real
-    # smell and is BOOKED (PENDING, mailbox/C.md) rather than worked around.
-    columns = filter_eval._columns_map(g.get("fields") or [])
-    def _any_active(ns):
-        for n in ns or ():
-            if isinstance(n, dict) and isinstance(n.get("children"), list):
-                if _any_active(n["children"]):
-                    return True
-            elif filter_eval.is_rule_active(n, columns):
-                return True
-        return False
-    if not _any_active(nodes):
-        raise err(400, "no_filter",
-                  "this view has no active filter, so no record can ever ENTER it — add a "
-                  "condition to the view first, then create the alert")
-@router.delete("/alerts/{alert_id}")
-def delete_alert(alert_id: str, session: Session = Depends(require_session)):
-    rec = next((r for r in alerts.list_alerts(st=session.runtime)
-                if str(r.get("id")) == str(alert_id)), None)
-    if rec is None:
-        raise err(404, "no_alert", "that alert does not exist")
-    if str(rec.get("owner")) != str(session.uname) and not session.admin:
-        raise err(403, "not_yours", "only the alert's owner (or an administrator) can delete it")
-    alerts.delete(alert_id, st=session.runtime)
-    return {"ok": True}
-@router.post("/alerts/{alert_id}/run")
-def run_alert(alert_id: str, session: Session = Depends(require_session)):
-    rec = next((r for r in alerts.list_alerts(user=session.uname, is_admin=session.admin,
-                                              st=session.runtime)
-                if str(r.get("id")) == str(alert_id)), None)
-    if rec is None:
-        raise err(404, "no_alert", "that alert does not exist")
-    return _evaluate(session, rec)
-@router.get("/notifications")
-def notifications(session: Session = Depends(require_session)):
-    """The inbox — RE-EVALUATED on read, which is a deliberate design choice.
-    ⭐ A-S1-2 RESOLVED THE OTHER WAY, and the reason is structural rather than a shortcut. The
-    plan was a push hook: the automation engine calls `after_write` when it lands rows. But
-    `run_async` runs on a BACKGROUND THREAD with no `Session` in scope, and an alert must be
-    evaluated as its OWNER (see `_evaluate`) — so a push hook would have to mint a session inside
-    a worker thread from a tenant runtime, which is exactly the kind of ad-hoc identity
-    construction that leaks scope.
-    Pulling on read has none of that: the caller IS a session, the assemblies are already
-    scope-cached, and the user cannot observe the difference — an inbox is only ever read by
-    someone opening it. The cost is that a notification is minted when you LOOK rather than when
-    the row landed, so the `at` stamp is detection time, not arrival time.
-    `after_write` stays exported for the day the engine can hand over a real identity.
-    ⭐⭐ W31-T24 — ONE ASSEMBLY PER (TOPIC, OWNER), NOT ONE PER ALERT.
-    ⛔ MEASURED FIRST, AND THE MEASUREMENT CORRECTS AN EARLIER READING OF IT. This route is
-    **20 ms in-process and 3,280 ms live** on tenant #0 — but tenant #0 has **ZERO alerts**
-    (censused 2026-08-12), so the 20 ms is an EMPTY LOOP and says nothing at all about what the
-    re-evaluation costs. The live 3,280 ms is the two store reads either side of that loop. So the
-    body below is not slow today; it is UNEXERCISED, and every alert a tenant creates adds a whole
-    grid assembly to an inbox poll. The memo turns O(alerts) into O(distinct topic × owner), which
-    is the difference between "fine" and "three seconds per alert" the day somebody uses the
-    feature. ⚠ Making the read cheap by evaluating LESS is the obvious wrong fix and is not what
-    this does: every alert is still evaluated, against the same rows, in the same order.
-    """
-    assemblies = {}
-    for rec in alerts.list_alerts(user=session.uname, is_admin=False, st=session.runtime):
-        try:
-            _evaluate(session, rec, assemblies=assemblies)
-        except Exception:                                   # noqa: BLE001
-            continue                                        # one bad alert must not empty the pane
-    # ⭐ W32-T20 (C3): every item leaves through `inbox_view`, so a notification queued before
-    # this wave carries a `target` too. See `notification_view`'s header for why it is derived.
-    return inbox_view(alerts.inbox(session.uname, st=session.runtime))
-@router.post("/notifications/read")
-def read_notifications(body: dict = Body(default=None),
-                       session: Session = Depends(require_session)):
-    body = body or {}
-    ids = body.get("ids")
-    if ids is not None and not isinstance(ids, list):
-        raise err(400, "bad_ids", "ids must be a list, or null to mark every notification")
-    # ⚠ THE SAME ENRICHMENT ON BOTH DOORS. `mark_read` returns a fresh inbox, and the Inbox
-    # module re-renders from it — an un-enriched answer here would strip `target` off every row
-    # the moment somebody marked one read, i.e. the feature would work until first use.
-    return inbox_view(alerts.mark_read(session.uname, ids, read=bool(body.get("read", True)),
-                                       st=session.runtime))
-def after_write(session: Session, topic_key: str):
-    """THE WRITE HOOK — call after a write that could change what a view matches.
-    Exported as a plain function (not a route) so `core.grid_events`' callers and S2's automation
-    upserts reach it the same way. It never raises: an alert evaluation failing must not fail the
-    edit that triggered it.
-    ⭐ W31-T24 — it shares `/notifications`' memo shape for the same reason: a write that changes
-    one view can trip several alerts on the SAME topic, and each would otherwise rebuild the table.
-    ⚠ STILL ZERO PRODUCTION CALLERS (W31-T24 confirmed it; the route docstring above says why the
-    push hook was resolved the other way). Booked rather than wired: minting a session inside the
-    engine's worker thread is the ad-hoc identity construction this file exists to avoid.
-    """
-    try:
-        assemblies = {}
-        return alerts.after_write(topic_key, st=session.runtime,
-                                  runner=lambda rec: _evaluate(session, rec,
-                                                               assemblies=assemblies))
-    except Exception:                                       # noqa: BLE001
-        return {"evaluated": 0}

+"""routes_alerts.py — the Alerts module (wave 20, owner item 25, contract C-ALERT).
+    GET    /api/v1/alerts                  -> {alerts:[...]}
+    POST   /api/v1/alerts                  <- {viewId, topic, label?}
+    DELETE /api/v1/alerts/{alert_id}
+    POST   /api/v1/alerts/{alert_id}/run   -> evaluate now (the pane's manual refresh)
+    GET    /api/v1/notifications           -> {unread, items:[...]}
+    POST   /api/v1/notifications/read      <- {ids:[...]|null, read?:bool}
+The semantics — an alert is a view plus a remembered matched set, a notification is a NEW
+ENTRANT, and the first evaluation seeds silently — live in `core.alerts` with the reasoning.
+This file owns the two things a route must: WHO may do it, and HOW the view gets evaluated.
+⭐ **THE EVALUATION RUNS AS THE ALERT'S OWNER, NOT AS THE CALLER.** `_run_alert` builds the pool
+for `rec['owner']`, never for whoever tripped the write hook. Any other choice leaks: a
+full-access admin editing a cell would otherwise evaluate a BU-scoped user's alert over the whole
+book, and the notification would name customers that user may not see — a permission leak wearing
+a notification's clothes. The owner's own scope is the only correct basis for their alert.
+⚠ **AN ALERT IS NOT A SECOND READ PATH.** It resolves rows through the same
+`routes_customers.grid_assembly` / `routes_tables.ut_assembly` the grid uses, so a row that an
+alert can see is by construction a row its owner could open. Re-implementing the filter here
+would be a second definition of "matches", and those two would drift.
+"""
+import re
+from fastapi import APIRouter, Body, Depends
+import core.alerts as alerts
+from deps import Session, err, require_session
+router = APIRouter(prefix="/api/v1")
+#: The alert-bearing surfaces. `ut_` tables are admitted by prefix, like everywhere else.
+_TOPICS = ("customer", "product")
+# ── ⭐⭐ WAVE 32 · T20 · CONTRACT C3 — THE INBOX SHAPE, DERIVED ON READ ────────────────────────
+#
+# `GET /notifications` gains `subject`, `kind` and `target` per item (`read` was always there).
+#
+# ⛔ DERIVED, NEVER STORED, AND THAT IS THE WHOLE OF WHY THIS WAVE EXISTS. Stamping the three
+# keys onto the record at write time would give them to notifications minted AFTER the deploy and
+# to nothing else — every notification already sitting in every tenant's inbox would open nothing,
+# and the feature would be correct in the source and absent from the product
+# ([[a-migration-that-runs-on-the-next-write]], D-201). A read-side derivation reaches a
+# notification queued last month. It also keeps the store shape out of `core/alerts.py`, which is
+# another lane's file this wave — but that is the convenience, not the reason.
+#
+# ⚠ TWO PRODUCERS WRITE TWO SHAPES into one inbox, and the vocabulary below is what tells them
+# apart. `_queue` (a record ENTERED a watched view) sets `topic`+`viewId`. `notify()` sets
+# `topic='automation'` and puts the producer's key in `alertId`, leaving `viewId` empty. Deciding
+# here means the client branches on ONE field instead of re-deriving the same split.
+#
+# ⛔ **D-101 IS CLOSED HERE, BY SUBTRACTION.** There was a THIRD shape — `kind='automation_review'`
+# + `autoId`, a card arriving at a review stage — and its producer `notify_review` was deleted by
+# W27/R3 with the review lanes. `automation_engine.py`'s own tombstone (search `notify_review`)
+# records the 2026-08-12 sweep: **no `.py` file anywhere produces one**, while the client branch,
+# its route and three gate legs stayed fully alive. D-101's exit condition is *"the client review
+# branch is deleted in the same change as any remaining residue, OR `notify_review` gains its real
+# caller"* — the residue is zero, so the branch goes. It is not carried into the Inbox: a stored
+# review notification (if any survives in a tenant from the wave-23 era) derives as an ordinary
+# `alert` with no target, i.e. an honest unclickable row, which is correct — the board it pointed
+# at was deleted two waves ago.
+#: C3's `kind` vocabulary. Plain strings on the wire — the client must never union over them
+#: (alertsModel's wave-9 law: a client union turns "the server grew a kind" into a dropped row).
+NOTIF_KIND_ALERT = "alert"
+NOTIF_KIND_AUTOMATION = "automation"
+NOTIF_KIND_SHARE = "share"
+#: C3's `target.module` vocabulary, and the automation sub-selection.
+TARGET_MODULE_DATABASE = "database"
+TARGET_MODULE_AUTOMATION = "automation"
+TARGET_TAB_RUNS = "runs"
+#: The topic `notify()` carries for a SHARE (W32-T28 writes it; nothing does yet, and a kind with
+#: no producer is a string that reads as a feature — the reason this constant is named here and
+#: cited from `routes_shares` rather than typed twice).
+SHARE_TOPIC = "share"
+#: `core.alerts.notify`'s default topic for a run outcome. Mirrors `inboxModel.AUTOMATION_TOPIC`.
+AUTOMATION_TOPIC = "automation"
+_UT_TOPIC = re.compile(r"ut_[A-Za-z0-9_]+\Z")
+def route_for_topic(topic):
+    """A grid SCOPE key -> the registry route that renders it, or None.
+    ⛔ THE SAME TABLE AS `alertsModel.routeForTopic`, and the parity is GATED
+    (`verify_alerts.py`'s vocabulary scan) rather than trusted. The two built-ins are the only
+    pair that differ — the registry names the surface (`customer_data`) while the grid names the
+    scope (`customer`) — so a topic passed through as a route sends every click to a page that
+    does not exist. `None` for anything else: a target this product cannot resolve must be ABSENT
+    rather than plausible, because an absent target renders as a row that does not pretend to be
+    clickable, and a wrong one renders as a click that silently goes nowhere.
+    """
+    t = str(topic or "").strip()
+    if t == "customer":
+        return "customer_data"
+    if t == "product":
+        return "product_data"
+    if _UT_TOPIC.match(t):
+        return t
+    return None
+def _refusal_code(exc):
+    """The `error.code` an `HTTPException` raised by `deps.err()` carries, or `""`.
+    ⭐ W32-T22. Four refusals travel up the assembly chain — `unknown_table` (404), `forbidden`
+    (403), `window_required` (409) and `store_not_ready` (503) — and each already names its own
+    cause. Anything that reduces all four to one word is throwing away the only information the
+    reader could have acted on. Returns `""` for a plain exception, so a caller can tell
+    "refused, and here is why" apart from "broke, and we do not know why".
+    """
+    detail = getattr(exc, "detail", None)
+    if isinstance(detail, dict):
+        inner = detail.get("error")
+        if isinstance(inner, dict):
+            return str(inner.get("code") or "")
+    return ""
+def notification_view(item):
+    """One STORED notification -> the shape the Inbox renders. PURE, and total.
+    Never raises and never drops a row: an item it cannot classify comes back as an `alert` with
+    no `target`, which the client renders as an unclickable row rather than hiding. An inbox that
+    silently omits what it does not understand is the one failure a reader cannot detect.
+    """
+    if not isinstance(item, dict):
+        return item
+    topic = str(item.get("topic") or "").strip()
+    alert_id = str(item.get("alertId") or "").strip()
+    # ⛔ THE ID TEST IS HALF OF EVERY BRANCH, and it is the load-bearing half. A row whose topic
+    # says `automation` but whose producer key never arrived (a truncated payload, a server
+    # mid-deploy) would otherwise be handed a target naming NOTHING — a click that appears to work
+    # and silently does not, which is this repo's most-repeated failure shape. Failing the test
+    # drops it to the `alert` branch, where `route_for_topic` refuses out loud by answering None.
+    if topic == AUTOMATION_TOPIC and alert_id:
+        kind = NOTIF_KIND_AUTOMATION
+        target = {"module": TARGET_MODULE_AUTOMATION, "id": alert_id, "tab": TARGET_TAB_RUNS}
+    elif topic == SHARE_TOPIC and alert_id:
+        # ⭐ W32-T28: the sharer writes `key=<the ROUTE to open>` and, for a shared VIEW,
+        # `row_id=<the view to select>`.
+        #
+        # ⛔ `key` IS ALREADY A ROUTE, NOT A RAW OBJECT ID, and the first version of this got it
+        # wrong in a way worth recording: a shared VIEW put the VIEW's id in `alertId`, so the
+        # target read `{module: "database", id: "view_42"}` — an instruction to open a database
+        # called `view_42`. It looked right in the payload and would have opened nothing. The
+        # producer resolves the object to its topic and hands over the route; this branch only
+        # shapes what it is given.
+        kind = NOTIF_KIND_SHARE
+        row_id = str(item.get("rowId") or "").strip()
+        target = {"module": TARGET_MODULE_DATABASE, "id": alert_id,
+                  **({"tab": row_id} if row_id else {})}
+    else:
+        kind = NOTIF_KIND_ALERT
+        route = route_for_topic(topic)
+        view_id = str(item.get("viewId") or "").strip()
+        target = None if route is None else (
+            {"module": TARGET_MODULE_DATABASE, "id": route,
+             **({"tab": view_id} if view_id else {})})
+    # The email split: `subject` is the HEADER (what this is about — the alert, the automation,
+    # the database), `label` stays the BODY (what happened — the record that entered, the run
+    # summary). They were one field, which is why a notification read as a sentence with no
+    # sender and the pane could not be laid out like mail.
+    subject = str(item.get("alertLabel") or "").strip() or str(item.get("label") or "").strip()
+    # ⚠ `kind` is OVERWRITTEN, not merged. There was one stored value (`automation_review`) and it
+    # is D-101's dead one; leaving it through would give the client two vocabularies for one
+    # question, which is the defect this wave's item 6 is about in a different file.
+    # ⭐⭐ W33-T28 (owner: "the Inbox reads like email") — THE SENDER, WHICH DID NOT EXIST.
+    #
+    # ⛔ A `verifier` reading the finished wave-32 surface found that the row's sender POSITION was
+    # occupied by `kindLabel(n.kind)` — the literals "Alert" / "Automation" / "Shared with you" —
+    # i.e. a CATEGORY standing where a who belongs, and no sender field anywhere on the wire, in
+    # the model or in the markup. Mail has a from. This is it.
+    #
+    # ⚠ IT IS DERIVED HERE, NOT STORED, FOR EVERY KIND BUT ONE — and the exception is the point.
+    # An alert firing and an automation landing rows have no person behind them; their honest
+    # sender is the machine that did it, named as the thing the reader recognises. A SHARE has a
+    # real person, and only the producer knows who: `routes_shares.py` writes it as `actor` and
+    # this reads it back. ⛔ It is NOT parsed out of the body prose ("<name> shared this with
+    # you") — a sender recovered by regexing a sentence breaks the first time the sentence is
+    # reworded, and it would break silently, in the header.
+    #
+    # ⚠ FALLS BACK, NEVER BLANK. A share queued BEFORE `actor` existed has none, and a row with an
+    # empty from column reads as a broken inbox rather than as an old notification.
+    actor = str(item.get("actor") or "").strip()
+    if kind == NOTIF_KIND_SHARE:
+        sender = actor or "A teammate"
+    elif kind == NOTIF_KIND_AUTOMATION:
+        # ⛔ "Agents", not "Automation" (W34-T40, corrected at QA 2026-08-17). The client's
+        # `senderOf` already falls back to `AGENTS_MODULE_LABEL` — but `if (sent) return sent`
+        # runs FIRST, so this server literal won and every actor-less automation notification
+        # showed the retired module name in the inbox's From column.
+        sender = actor or "Agents"
+    else:
+        sender = actor or "Alerts"
+    out = {**item, "read": bool(item.get("read")), "kind": kind,
+           "subject": subject or "Notification", "sender": sender}
+    if target is not None:
+        out["target"] = target
+    return out
+def inbox_view(box):
+    """`core.alerts.inbox()`'s answer, with every item put through {@link notification_view}.
+    ⚠ `unread` IS NOT RECOUNTED. It is the ACCOUNT's number and `items` is one page of it; a
+    recount here would make the badge a function of whatever this page happened to include, which
+    is the exact defect `alertsModel.parseInbox`'s own header records from the other side.
+    """
+    if not isinstance(box, dict):
+        return box
+    items = box.get("items")
+    if not isinstance(items, list):
+        return box
+    # ⭐⭐ W33-T28 / D-208 — THE SERVER'S CLOCK RIDES WITH THE PAGE, and it is what lets the client
+    # render a mail-shaped stamp ("09:41" today, "Aug 12" beyond) instead of `2026-08-13 09:41`.
+    #
+    # ⛔ THE CLIENT MUST NOT READ ITS OWN CLOCK, which is D-208's exit condition word for word and
+    # is why this key exists rather than a `new Date()` in the browser. `at` is sent as UTC WITH
+    # its offset (D-18) precisely so every reader sees the same instant; deciding "is this today?"
+    # against a browser clock would re-introduce the drift the offset exists to remove — a reader a
+    # day ahead being told an event happened tomorrow [[date-window-vocabulary]]. Both operands
+    # now come from the same machine.
+    # ⚠ Same funnel as the enrichment, so the read door and the mark-read door cannot disagree —
+    # the note two lines up records what happened last time only one of them was enriched.
+    return {**box, "now": alerts._now_iso(),
+            "items": [notification_view(n) for n in items]}
+def _view_by_id(g, view_id):
+    """One saved view out of an assembly, by id. `None` when there is no such view.
+    ⛔⛔ W33-T29 (owner: *"Alert me about new records"* answering "Something went wrong") — THIS
+    FUNCTION EXISTS BECAUSE TWO CALL SITES BOTH WROTE `(g.get("views") or {}).get(view_id)`, AND
+    `g["views"] IS A LIST`. `aios_grid.views_from_defs` returns `[{...}]`, `workspace_wire` passes
+    it straight out and both `ut_assembly` and `grid_assembly` return it unchanged — so `.get` on
+    it raises `AttributeError`, and `views_from_defs` always returns at least one element, so the
+    `or {}` never fires. **It raised on EVERY call, on every topic, since wave 20.**
+    ⛔ AND THE TWO SITES FAILED DIFFERENTLY, WHICH IS WHY ONLY ONE WAS EVER REPORTED. In
+    `_require_filtered_view` the raise lands ABOVE the handler's own `try`, so it leaves as a bare
+    FastAPI 500 and the client's `errorMessage` turns any 5xx into *"Something went wrong on our
+    side"* — the exact sentence the owner reported (D-107's shape, again: an attribute error above
+    the guard arrives as plain text rather than as our envelope). In `_evaluate` the identical
+    line is swallowed by `/notifications`' `except Exception: continue`, so **every stored
+    view-alert was silently dropped from the Inbox** and nobody had anything to report at all.
+    One expression, one loud symptom and one silent one.
+    ⚠ SO IT IS A FUNCTION, NOT TWO FIXED LINES. Two copies of "find the view" is what let one site
+    be discussed for three waves while its twin went unnoticed [[one-question-two-normalizers]].
+    ⚠ It accepts a dict too, and that is not defensive noise: `verify_alerts`' door fixture was
+    keyed `{id: view}` — which is precisely why the gate was green while production raised on
+    every call. The fixture is moving to the production shape in this same change, and tolerating
+    both here means a caller that legitimately holds one cannot resurrect the bug.
+    """
+    want = str(view_id or "")
+    if not want:
+        return None
+    views = (g or {}).get("views")
+    if isinstance(views, dict):
+        found = views.get(want)
+        return found if isinstance(found, dict) else None
+    if not isinstance(views, list):
+        return None
+    for v in views:
+        if isinstance(v, dict) and str(v.get("id") or "") == want:
+            return v
+    return None
+def _topic_or_400(raw):
+    topic = str(raw or "").strip().lower()
+    if topic.startswith("ut_") or topic in _TOPICS:
+        return topic
+    raise err(400, "bad_topic", f"topic must be one of {', '.join(_TOPICS)} or a ut_ table")
+def _owner_session(session: Session, owner: str):
+    """A `Session` for the alert's OWNER (see the module note on why the owner, not the caller).
+    ⚠ `Session` exposes `uname`/`admin` as PROPERTIES derived from `user`, not as fields — so an
+    owner session is built by swapping the `user` RECORD and letting both derive themselves. An
+    earlier version passed `uname=`/`admin=` to the constructor, which would have raised on the
+    first write hook of the wave; the properties are the single definition of who a session is,
+    and going around them is how a session with an admin flag and a non-admin record exists.
+    Returns None when the owner is gone or deactivated — their alerts then stop evaluating rather
+    than evaluating as somebody else, which is the fail-closed direction.
+    """
+    import core.users as users
+    if str(owner) == str(session.uname):
+        return session
+    rec = (users.registry() or {}).get(str(owner))
+    if not isinstance(rec, dict) or not rec.get("active", True):
+        return None
+    # `_public` is THE definition of what a session may know about its own account (never a hash
+    # or a salt) — the same one `routes_auth` uses. Building the dict by hand here would be a
+    # second definition, and the one that leaks is always the copy.
+    return Session(tenant=session.tenant, user=users._public(str(owner), rec),
+                   claims=session.claims, runtime=session.runtime)
+def _evaluate(session: Session, rec: dict, assemblies=None):
+    """Resolve `rec`'s view over its topic AS THE ALERT'S OWNER, then fold the result in.
+    ⭐⭐ W31-T24 — `assemblies` IS A PER-REQUEST MEMO, KEYED `(topic, owner)`, and it is the whole
+    of this ticket's server half. `/notifications` re-evaluates EVERY alert inline on read and each
+    one built a FULL assembly — the pool, the workspace, `rows_from_pool` over every row. Two
+    alerts on one view built that table twice; ten built it ten times. Nothing dedupes them,
+    because each `_evaluate` was a closed call.
+    ⚠ `(topic, owner)` and not `topic`: the assembly is built as the alert's OWNER (see the module
+    note — evaluating a BU-scoped user's alert on a full-access admin's pool is a permission leak
+    wearing a notification's clothes), so two owners on one topic are two DIFFERENT tables and
+    must never share an entry. Getting that key wrong is the one way this optimisation could leak.
+    ⚠ Passing nothing keeps the old behaviour exactly, which is what the create/run doors want:
+    they evaluate ONE alert and a memo for a single call is pure overhead.
+    """
+    import aios_grid
+    from harness import filter_eval
+    owner_sess = _owner_session(session, rec.get("owner"))
+    if owner_sess is None:
+        return {"skipped": "owner_unavailable"}
+    topic = str(rec.get("topic") or "")
+    memo_key = (topic, str(owner_sess.uname))
+    g = assemblies.get(memo_key) if isinstance(assemblies, dict) else None
+    if g is None:
+        try:
+            if topic.startswith("ut_"):
+                from routes_tables import ut_assembly
+                # ⛔ `consume_corrections=False`, and the default was a REAL BUG, not a tidy-up.
+                # `ut_assembly` defaults it True, so every `/notifications` read CONSUMED the
+                # one-shot field-name correction acks for every `ut_` topic that has an alert —
+                # taking them from the `/workspace` refresh that exists to show them to the person
+                # who made the edit. The customer branch below has always passed False; this one
+                # inherited a default nobody re-read. An inbox poll must never consume a one-shot.
+                g = ut_assembly(owner_sess, topic,
+                                storage_key=f"{owner_sess.tenant}:{topic}:{owner_sess.uname}",
+                                consume_corrections=False)
+            else:
+                from routes_customers import grid_assembly
+                g = grid_assembly(owner_sess, scope=topic, consume_corrections=False)
+        except Exception as e:                              # noqa: BLE001
+            # ⭐ W32-T22 — SKIPPING IS FINE HERE; SKIPPING ANONYMOUSLY IS NOT. This one must not
+            # raise (one bad alert cannot empty an inbox), so unlike `_require_filtered_view` it
+            # keeps a blanket catch — but it now reports the refusal's OWN code where there is
+            # one. `type(e).__name__` said `HTTPException` for four different causes, and
+            # `lastError` is the only place a user ever learns why an alert stopped firing.
+            #
+            # ⚠ `with_rows=True` STAYS on this path, deliberately: unlike the create door, an
+            # evaluation genuinely needs the rows to run the filter over. So an alert on a
+            # read-through grid is created (T22) and then skips at evaluation with
+            # `window_required` naming why — which is D-184's remaining half, and it is a
+            # SENTENCE now rather than silence.
+            return {"skipped": _refusal_code(e) or "unavailable", "detail": type(e).__name__}
+        if isinstance(assemblies, dict):
+            assemblies[memo_key] = g
+    view = _view_by_id(g, rec.get("viewId"))
+    if not isinstance(view, dict):
+        # Deleted, or un-shared out from under the alert. Say so on the RECORD rather than
+        # deleting the alert: an alert that silently vanishes is indistinguishable from one that
+        # never fires, and the user cannot debug what is not there.
+        return {"skipped": "view_missing"}
+    # The SAME row build the grid and `/customers` use — `rows_from_pool` is what puts derived
+    # and overlay values on a row. Evaluating a filter against raw pool dicts would silently
+    # never match any condition on a user-created or measure column.
+    #
+    # ⛔⛔ AND "THE SAME ROW BUILD" WAS NOT TRUE, WHICH MADE EVERY ALERT ON A `ut_*` DATABASE BLIND
+    # TO IMPORTED DATA. Found by a verifier driving one real assembly through both paths.
+    #
+    # `routes_tables.table_rows` — the grid the person is looking at — merges the DEFINITION rows
+    # underneath the overlay ("base first, overlay wins"; that merge is itself the fix for owner
+    # item 3, *"it all got reseted"*). `_evaluate` is a second copy of that read and never got it:
+    # it handed `ws['overlays']` to `rows_from_pool` raw, so for a `ut_*` table every base cell
+    # evaluated as BLANK. Measured on one assembly, same view, same rows:
+    #     rows_src        state='unpaid' / 'paid'
+    #     _evaluate saw   state=''       / ''          ⇐ every base cell blank
+    #     the GRID saw    state='unpaid' / 'paid'
+    # so `state eq unpaid` matched NOTHING while the view showed one row, and `state isEmpty`
+    # matched EVERYTHING while the view showed none. **The alert did not merely miss rows — it
+    # inverted.** End to end: a row whose value arrived by import, automation, paste or the create
+    # door never fired; only a value typed as a hand EDIT did.
+    #
+    # ⚠ Scope, so nobody widens the fix past its cause: materialised `ut_*` tables are hit;
+    # `customer`/`product` are not (their fields are `source: "odoo"` and read off `rows_src`);
+    # `ut_odoo_*` never reaches here (`with_rows=True` refuses first and returns
+    # `skipped: window_required`).
+    # ⛔ ORDER IS LOAD-BEARING AND IS THE GRID'S: base underneath, overlay ON TOP. Inverting it
+    # would let a stale definition value shadow an edit the user has just made — the same defect
+    # `table_rows`' own note records, arriving from the other side.
+    _ov = (g.get("ws") or {}).get("overlays") or {}
+    _merged = {}
+    for _r in g["rows_src"]:
+        _pid = str(_r.get("pid"))
+        _cells = {k: v for k, v in _r.items() if k != "pid"}
+        _o = _ov.get(_pid)
+        if isinstance(_o, dict):
+            _cells.update(_o)
+        _merged[_pid] = _cells
+    rows = aios_grid.rows_from_pool(g["rows_src"], g["fields"], _merged,
+                                    derived=g.get("derived"))
+    config = view.get("config") or view
+    ctx = filter_eval.EvalCtx(
+        cohort_sets={str(k): {str(p) for p in (v.get("memberPids") or ())}
+                     for k, v in (g.get("lists") or {}).items() if isinstance(v, dict)},
+        measure_sets=g.get("measure_sets") or {},
+        today=g.get("today"))
+    pids = filter_eval.visible_pids(config.get("filters") or [], rows, g["fields"], ctx,
+                                    member_pids=config.get("memberPids"))
+    labels = {str(r.get("pid")): str(r.get("name") or r.get("pid")) for r in rows}
+    return alerts.evaluate(rec.get("id"), [str(p) for p in pids],
+                           labels=labels, partial=False, st=session.runtime)
+@router.get("/alerts")
+def list_alerts(session: Session = Depends(require_session)):
+    return {"alerts": alerts.list_alerts(user=session.uname, is_admin=session.admin,
+                                         st=session.runtime)}
+@router.post("/alerts")
+def create_alert(body: dict = Body(default=None), session: Session = Depends(require_session)):
+    body = body or {}
+    view_id = str(body.get("viewId") or "").strip()
+    if not view_id:
+        raise err(400, "bad_view", "an alert needs the id of the view it watches")
+    topic = _topic_or_400(body.get("topic"))
+    _require_filtered_view(session, topic, view_id)
+    import uuid
+    aid = f"al_{uuid.uuid4().hex[:12]}"
+    rec = alerts.create(aid, view_id=view_id, topic=topic, owner=session.uname,
+                        label=body.get("label") or "", st=session.runtime)
+    # SEED IMMEDIATELY, so the alert starts from "everything currently matching is old news".
+    # Deferring this to the first write hook would mean the next edit announces the whole view.
+    outcome = _evaluate(session, rec)
+    return {"alert": {**rec, "seeded": True}, "first": outcome}
+def _require_filtered_view(session: Session, topic: str, view_id: str):
+    """400 unless `view_id` exists on `topic` AND actually narrows something.
+    ⛔ AN ALERT ON AN UNFILTERED VIEW IS SILENTLY INCAPABLE OF ALERTING, which is worse than one
+    that is refused. `filter_eval` treats an inactive tree as "no narrowing, every row shows"
+    (`visible_pids`'s own rule), so such an alert seeds with the entire table and can never see an
+    entrant again — there is nothing left to enter. The owner's words are *"when a Record gets
+    into that Filter's criteria"*: no criteria, no alert, and said at creation rather than
+    discovered by never being notified.
+    `is_rule_active` is the SAME activeness predicate the engine and the column tints use — a
+    half-typed rule is not a filter, and this must agree with what actually narrows or it would
+    accept a view whose one rule the engine then ignores.
+    ⭐⭐ WAVE 32 · T22 (owner item 17) — THIS FUNCTION WAS THE ERROR. Two defects, stacked, and
+    the second one hid the first.
+    (1) **IT ASKED FOR EVERY ROW OF A TABLE IT NEVER LOOKS AT.** The only thing read below is
+        `g["views"]`. `ut_assembly` defaults `with_rows=True`, so creating an alert on a
+        read-through grid built the whole pool — and `scoped_pool` refuses that with
+        `409 window_required` over 963,783 rows, exactly as it is supposed to. `with_rows=False`
+        (W31-T20's flag, built for precisely this) answers the same question with `scoped_pids`,
+        runs the SAME `_defn_or_refuse` wall, and does not refuse. **That is D-184's create half,
+        closed** — an alert on a read-through grid can now be made at all.
+    (2) **A BLANKET `except Exception` TURNED EVERY NAMED REFUSAL INTO A 503.** `HTTPException`
+        is an `Exception`, so `404 unknown_table`, `403 forbidden`, `409 window_required` and
+        `503 store_not_ready` — four refusals that each say what is wrong — were all replaced by
+        *"the table is unavailable — try again in a moment"*. ⛔ AND THAT SENTENCE NEVER REACHED
+        A USER EITHER: `alertsApi.errorMessage` discards the text of any status ≥ 500 by design
+        (a 5xx body is the server's internals), substituting *"Something went wrong on our
+        side."* — which is the owner's screenshot, word for word. A knowable cause returned as a
+        5xx is invisible by construction, so re-wording the 503 could never have fixed this.
+    ⚠ The except is narrowed, not deleted: an UNEXPECTED failure is still a 503, because that is
+    honest. What it may no longer do is catch a refusal that already knows its own name.
+    """
+    from fastapi import HTTPException
+    from harness import filter_eval
+    try:
+        if topic.startswith("ut_"):
+            from routes_tables import ut_assembly
+            # ⚠ `consume_corrections=False` — the customer branch has always passed it and this
+            # one inherited a default nobody re-read. Creating an alert must not eat the one-shot
+            # field-name correction acks belonging to the `/workspace` refresh that exists to show
+            # them to the person who made the edit. Same defect `_evaluate`'s header records.
+            g = ut_assembly(session, topic,
+                            storage_key=f"{session.tenant}:{topic}:{session.uname}",
+                            consume_corrections=False, with_rows=False)
+        else:
+            from routes_customers import grid_assembly
+            g = grid_assembly(session, scope=topic, consume_corrections=False)
+    except HTTPException:
+        raise                                               # it already names its own cause
+    except Exception as e:                                  # noqa: BLE001
+        # Genuinely unexpected. Still a 503, and now it carries the exception TYPE — without it,
+        # the one path that reaches this branch is also the one path with nothing to debug from.
+        raise err(503, "unavailable",
+                  f"the table could not be read ({type(e).__name__}) — try again in a moment")
+    view = _view_by_id(g, view_id)
+    if not isinstance(view, dict):
+        raise err(404, "no_view", "that view does not exist on this table")
+    nodes, _conj = filter_eval.tree_parts((view.get("config") or view).get("filters") or [])
+    # ⛔⛔ WAVE 33 · T29 — **CORRECTION: THE BLOCK BELOW IS TRUE ABOUT THE CODE AND FALSE ABOUT
+    # PRODUCTION, AND IT MUST BE READ SECOND.** It claims the missing-argument `TypeError` "IS
+    # owner item 17" — the owner's *"Something went wrong"*. It was not, and it could not have
+    # been: at `cbcf005`, the build the owner was using, the dict-read on `views` sat ~10 lines
+    # ABOVE this call and raised `AttributeError` on EVERY request, so the walk never reached the
+    # leaf and the arity bug was unreachable. `_view_by_id`'s own header records that fix.
+    #
+    # ⚠ WHY THE STALE PARAGRAPH STAYS RATHER THAN GETTING DELETED: the arity bug was real, the
+    # fix was right, and the three reasons it hid are the most transferable thing in this file.
+    # What was wrong is only its CLAIM TO BE THE CAUSE. Two comment blocks in one function each
+    # naming themselves as the origin of the same screenshot are mutually exclusive, and the next
+    # reader believes whichever they meet first — which is why this correction sits above rather
+    # than below. Caught by a verifier that read the SHIPPED file at the deployed commit instead
+    # of the working tree. [[grep-output-is-not-source]]
+    #
+    # ⛔⛔ WAVE 32 · T22 — **THE CALL BELOW WAS MISSING AN ARGUMENT** (and wave 32 believed, wrongly,
+    # that this was owner item 17 — see the correction directly above).
+    #
+    # `is_rule_active(rule, columns)` takes TWO parameters (`harness/filter_sql.py`; every other
+    # caller in the repo passes both). This one passed ONE, so the moment the walk reached a LEAF
+    # rule it raised `TypeError: is_rule_active() missing 1 required positional argument`.
+    #
+    # ⚠ READ WHAT THAT MEANS BEFORE FIXING ANYTHING ELSE: the walk only reaches a leaf when the
+    # view HAS a condition — and a view with a condition is the only kind an alert is allowed on.
+    # A view with no filters yields an empty `nodes`, so `_any_active` returns False without ever
+    # calling this, and the reader gets the honest 400 `no_filter`. **So the only path that
+    # worked was the refusal path: "Alert me about new records" had never once created an alert
+    # on a filtered view.** ⛔ And the raise lands OUTSIDE the `try` above, so it was not even the
+    # 503 — it was a bare FastAPI 500, which `alertsApi.errorMessage` renders as *"Something went
+    # wrong on our side. Try again in a moment."*, the owner's screenshot word for word.
+    #
+    # ⚠ THREE THINGS HID IT, and they are worth more than the fix. (1) Python does not check
+    # arity until the line RUNS, and this line runs only on the success path of a feature whose
+    # every test exercised its refusals. (2) The `no_filter` 400 above it is a real, correct,
+    # well-tested refusal, so the door looked alive. (3) `verify_alerts.py` asserts the refusal
+    # (`no_filter` reaches the user) and the transport — never a creation. A gate can be green,
+    # thorough and honest about everything except the one path the feature exists for.
+    #
+    # `_columns_map` is the DEFINITION of fields -> the membership set `is_rule_active` looks a
+    # column up in; building a second dict here would be a second answer to one question, which
+    # is this wave's other headline defect in a different file. Its leading underscore is a real
+    # smell and is BOOKED (PENDING, mailbox/C.md) rather than worked around.
+    columns = filter_eval._columns_map(g.get("fields") or [])
+    def _any_active(ns):
+        for n in ns or ():
+            if isinstance(n, dict) and isinstance(n.get("children"), list):
+                if _any_active(n["children"]):
+                    return True
+            elif filter_eval.is_rule_active(n, columns):
+                return True
+        return False
+    if not _any_active(nodes):
+        raise err(400, "no_filter",
+                  "this view has no active filter, so no record can ever ENTER it — add a "
+                  "condition to the view first, then create the alert")
+@router.delete("/alerts/{alert_id}")
+def delete_alert(alert_id: str, session: Session = Depends(require_session)):
+    rec = next((r for r in alerts.list_alerts(st=session.runtime)
+                if str(r.get("id")) == str(alert_id)), None)
+    if rec is None:
+        raise err(404, "no_alert", "that alert does not exist")
+    if str(rec.get("owner")) != str(session.uname) and not session.admin:
+        raise err(403, "not_yours", "only the alert's owner (or an administrator) can delete it")
+    alerts.delete(alert_id, st=session.runtime)
+    return {"ok": True}
+@router.post("/alerts/{alert_id}/run")
+def run_alert(alert_id: str, session: Session = Depends(require_session)):
+    rec = next((r for r in alerts.list_alerts(user=session.uname, is_admin=session.admin,
+                                              st=session.runtime)
+                if str(r.get("id")) == str(alert_id)), None)
+    if rec is None:
+        raise err(404, "no_alert", "that alert does not exist")
+    return _evaluate(session, rec)
+@router.get("/notifications")
+def notifications(session: Session = Depends(require_session)):
+    """The inbox — RE-EVALUATED on read, which is a deliberate design choice.
+    ⭐ A-S1-2 RESOLVED THE OTHER WAY, and the reason is structural rather than a shortcut. The
+    plan was a push hook: the automation engine calls `after_write` when it lands rows. But
+    `run_async` runs on a BACKGROUND THREAD with no `Session` in scope, and an alert must be
+    evaluated as its OWNER (see `_evaluate`) — so a push hook would have to mint a session inside
+    a worker thread from a tenant runtime, which is exactly the kind of ad-hoc identity
+    construction that leaks scope.
+    Pulling on read has none of that: the caller IS a session, the assemblies are already
+    scope-cached, and the user cannot observe the difference — an inbox is only ever read by
+    someone opening it. The cost is that a notification is minted when you LOOK rather than when
+    the row landed, so the `at` stamp is detection time, not arrival time.
+    `after_write` stays exported for the day the engine can hand over a real identity.
+    ⭐⭐ W31-T24 — ONE ASSEMBLY PER (TOPIC, OWNER), NOT ONE PER ALERT.
+    ⛔ MEASURED FIRST, AND THE MEASUREMENT CORRECTS AN EARLIER READING OF IT. This route is
+    **20 ms in-process and 3,280 ms live** on tenant #0 — but tenant #0 has **ZERO alerts**
+    (censused 2026-08-12), so the 20 ms is an EMPTY LOOP and says nothing at all about what the
+    re-evaluation costs. The live 3,280 ms is the two store reads either side of that loop. So the
+    body below is not slow today; it is UNEXERCISED, and every alert a tenant creates adds a whole
+    grid assembly to an inbox poll. The memo turns O(alerts) into O(distinct topic × owner), which
+    is the difference between "fine" and "three seconds per alert" the day somebody uses the
+    feature. ⚠ Making the read cheap by evaluating LESS is the obvious wrong fix and is not what
+    this does: every alert is still evaluated, against the same rows, in the same order.
+    """
+    assemblies = {}
+    for rec in alerts.list_alerts(user=session.uname, is_admin=False, st=session.runtime):
+        try:
+            _evaluate(session, rec, assemblies=assemblies)
+        except Exception:                                   # noqa: BLE001
+            continue                                        # one bad alert must not empty the pane
+    # ⭐ W32-T20 (C3): every item leaves through `inbox_view`, so a notification queued before
+    # this wave carries a `target` too. See `notification_view`'s header for why it is derived.
+    return inbox_view(alerts.inbox(session.uname, st=session.runtime))
+@router.post("/notifications/read")
+def read_notifications(body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    body = body or {}
+    ids = body.get("ids")
+    if ids is not None and not isinstance(ids, list):
+        raise err(400, "bad_ids", "ids must be a list, or null to mark every notification")
+    # ⚠ THE SAME ENRICHMENT ON BOTH DOORS. `mark_read` returns a fresh inbox, and the Inbox
+    # module re-renders from it — an un-enriched answer here would strip `target` off every row
+    # the moment somebody marked one read, i.e. the feature would work until first use.
+    return inbox_view(alerts.mark_read(session.uname, ids, read=bool(body.get("read", True)),
+                                       st=session.runtime))
+def after_write(session: Session, topic_key: str):
+    """THE WRITE HOOK — call after a write that could change what a view matches.
+    Exported as a plain function (not a route) so `core.grid_events`' callers and S2's automation
+    upserts reach it the same way. It never raises: an alert evaluation failing must not fail the
+    edit that triggered it.
+    ⭐ W31-T24 — it shares `/notifications`' memo shape for the same reason: a write that changes
+    one view can trip several alerts on the SAME topic, and each would otherwise rebuild the table.
+    ⚠ STILL ZERO PRODUCTION CALLERS (W31-T24 confirmed it; the route docstring above says why the
+    push hook was resolved the other way). Booked rather than wired: minting a session inside the
+    engine's worker thread is the ad-hoc identity construction this file exists to avoid.
+    """
+    try:
+        assemblies = {}
+        return alerts.after_write(topic_key, st=session.runtime,
+                                  runner=lambda rec: _evaluate(session, rec,
+                                                               assemblies=assemblies))
+    except Exception:                                       # noqa: BLE001
+        return {"evaluated": 0}

api/routes_customers.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_grid.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_keychain.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_nav.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_oauth.py CHANGED Viewed

@@ -1,114 +1,114 @@
-"""routes_oauth.py — the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
-Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
-shapes and status codes here; every decision that could be wrong lives in the module a gate
-can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
-so the day a second provider lands here is the day nothing in this file changes.
-MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
-`main.py`, and `routes_automation` is already included there — so this router rides inside it
-(`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
-alters no path.
-⚠ THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
-screen** — it is a top-level navigation the client reaches by `<a href>`, never JSON. The
-callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
-`oauth_connect.safe_next`), so the user lands where they left — connected or not, whatever
-went wrong rides in the query string; a dead-end error page where the app used to be reads as
-"the product broke", not "the connect failed".
-"""
-import os
-from fastapi import APIRouter, Depends, Request
-from fastapi.responses import RedirectResponse
-import oauth_connect
-from deps import Session, err, require_session
-router = APIRouter(prefix="/oauth")
-def _redirect_uri(request: Request, provider: str) -> str:
-    """The redirect URI this deployment registers at the provider — env-pinned when the
-    container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
-    the request. MUST match a console-registered URI verbatim, so it is computed in exactly
-    one place.
-    ⭐ WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
-    the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
-    the request-derived fallback below is effectively dev-only.
-    ⛔ THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
-    this returns is where the provider sends the user BACK, and the session cookie is host-only
-    (`aios_session.py:114-117`, no `domain=`) — so a callback base that disagrees with the host
-    the user actually browsed plants the session on the wrong hostname and they return logged
-    out. Moving the app to a new hostname means moving this value AND re-registering the
-    resulting URI in the provider console; one without the other fails closed.
-    Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
-    base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
-    if not base:
-        base = f"{request.url.scheme}://{request.url.netloc}"
-    return f"{base}/api/v1/oauth/{provider}/callback"
-@router.get("/status")
-def oauth_status(session: Session = Depends(require_session)):
-    """C5's status shape for the SESSION user, one entry per registry provider:
-    `{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
-    `ready` reads through."""
-    return oauth_connect.status(session.runtime, session.uname)
-def _offered_or_404(provider: str):
-    """⛔⛔ W32-T14 / OWNER ITEM 12 / R6 — A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
-    The owner pasted the failure this replaces: clicking Connect on the Google card answered
-    `503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error — it is that the flow is
-    not offered at all, so the honest status is the one for a URL that does not exist. `404`
-    rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
-    coming back until somebody pays for CASA verification (D-45, ~$540–1,800/yr).
-    ⚠ Every door in this router goes through it, START included, because the JSON the owner saw
-    came from the start route and a guard on one leg is a guard on one leg.
-    """
-    if not oauth_connect.offered(provider):
-        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
-@router.get("/{provider}/start")
-def oauth_start(provider: str, request: Request, next: str = "",
-                session: Session = Depends(require_session)):
-    """302 to the provider's consent screen (A3 — a navigation, never JSON). `?next=` is the
-    RELATIVE path the callback returns the browser to; it rides inside the single-use state,
-    sanitised, so the round trip cannot be steered off-origin."""
-    _offered_or_404(provider)
-    url, problem = oauth_connect.start(provider, session.uname,
-                                       _redirect_uri(request, provider), next_path=next)
-    if problem:
-        raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
-    return RedirectResponse(url, status_code=302)
-@router.get("/{provider}/callback")
-def oauth_callback(provider: str, request: Request,
-                   session: Session = Depends(require_session),
-                   state: str = "", code: str = "", error: str = ""):
-    """The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
-    the browser back to the state's return path — connected or not (see module header)."""
-    _offered_or_404(provider)
-    if error:
-        home = "/#/"
-        return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
-    email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
-    sep = "&" if "?" in home else "?"
-    if problem:
-        return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
-    return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
-@router.post("/{provider}/disconnect")
-def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
-    _offered_or_404(provider)
-    if oauth_connect.provider_def(provider) is None:
-        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
-    oauth_connect.disconnect(session.runtime, session.uname, provider)
-    return {"disconnected": provider}

+"""routes_oauth.py — the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
+Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
+shapes and status codes here; every decision that could be wrong lives in the module a gate
+can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
+so the day a second provider lands here is the day nothing in this file changes.
+MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
+`main.py`, and `routes_automation` is already included there — so this router rides inside it
+(`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
+alters no path.
+⚠ THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
+screen** — it is a top-level navigation the client reaches by `<a href>`, never JSON. The
+callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
+`oauth_connect.safe_next`), so the user lands where they left — connected or not, whatever
+went wrong rides in the query string; a dead-end error page where the app used to be reads as
+"the product broke", not "the connect failed".
+"""
+import os
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import RedirectResponse
+import oauth_connect
+from deps import Session, err, require_session
+router = APIRouter(prefix="/oauth")
+def _redirect_uri(request: Request, provider: str) -> str:
+    """The redirect URI this deployment registers at the provider — env-pinned when the
+    container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
+    the request. MUST match a console-registered URI verbatim, so it is computed in exactly
+    one place.
+    ⭐ WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
+    the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
+    the request-derived fallback below is effectively dev-only.
+    ⛔ THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
+    this returns is where the provider sends the user BACK, and the session cookie is host-only
+    (`aios_session.py:114-117`, no `domain=`) — so a callback base that disagrees with the host
+    the user actually browsed plants the session on the wrong hostname and they return logged
+    out. Moving the app to a new hostname means moving this value AND re-registering the
+    resulting URI in the provider console; one without the other fails closed.
+    Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
+    base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
+    if not base:
+        base = f"{request.url.scheme}://{request.url.netloc}"
+    return f"{base}/api/v1/oauth/{provider}/callback"
+@router.get("/status")
+def oauth_status(session: Session = Depends(require_session)):
+    """C5's status shape for the SESSION user, one entry per registry provider:
+    `{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
+    `ready` reads through."""
+    return oauth_connect.status(session.runtime, session.uname)
+def _offered_or_404(provider: str):
+    """⛔⛔ W32-T14 / OWNER ITEM 12 / R6 — A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
+    The owner pasted the failure this replaces: clicking Connect on the Google card answered
+    `503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error — it is that the flow is
+    not offered at all, so the honest status is the one for a URL that does not exist. `404`
+    rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
+    coming back until somebody pays for CASA verification (D-45, ~$540–1,800/yr).
+    ⚠ Every door in this router goes through it, START included, because the JSON the owner saw
+    came from the start route and a guard on one leg is a guard on one leg.
+    """
+    if not oauth_connect.offered(provider):
+        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
+@router.get("/{provider}/start")
+def oauth_start(provider: str, request: Request, next: str = "",
+                session: Session = Depends(require_session)):
+    """302 to the provider's consent screen (A3 — a navigation, never JSON). `?next=` is the
+    RELATIVE path the callback returns the browser to; it rides inside the single-use state,
+    sanitised, so the round trip cannot be steered off-origin."""
+    _offered_or_404(provider)
+    url, problem = oauth_connect.start(provider, session.uname,
+                                       _redirect_uri(request, provider), next_path=next)
+    if problem:
+        raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
+    return RedirectResponse(url, status_code=302)
+@router.get("/{provider}/callback")
+def oauth_callback(provider: str, request: Request,
+                   session: Session = Depends(require_session),
+                   state: str = "", code: str = "", error: str = ""):
+    """The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
+    the browser back to the state's return path — connected or not (see module header)."""
+    _offered_or_404(provider)
+    if error:
+        home = "/#/"
+        return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
+    email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
+    sep = "&" if "?" in home else "?"
+    if problem:
+        return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
+    return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
+@router.post("/{provider}/disconnect")
+def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
+    _offered_or_404(provider)
+    if oauth_connect.provider_def(provider) is None:
+        raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
+    oauth_connect.disconnect(session.runtime, session.uname, provider)
+    return {"disconnected": provider}

api/routes_products.py CHANGED Viewed

@@ -433,14 +433,34 @@ def products(session: Session = Depends(module_gate(MODULE))):
     enforced as a post-filter yields a correct row list carrying both units' numbers.
     """
     import aios_grid
     g = product_assembly(session)
     rows = aios_grid.rows_from_pool(
         g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
     rows = _seed_image(_seed_shared(rows, g["rows_src"], g["fields"]), g["fields"])
     return {"fields": g["fields"], "rows": rows,
             "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
             "identity": {"pid": "pid", "businessKey": "code"},
             "scope": {"team_id": g["team_id"], "consolidated": g["team_id"] is None}}

     enforced as a post-filter yields a correct row list carrying both units' numbers.
     """
     import aios_grid
+    import modules.product_data as pd
     g = product_assembly(session)
     rows = aios_grid.rows_from_pool(
         g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
     rows = _seed_image(_seed_shared(rows, g["rows_src"], g["fields"]), g["fields"])
+    # ⭐⭐ W41-T17 (owner instruction 25) — THE IDENTITY REPORT RIDES THE ENVELOPE, because a
+    # report nothing reads is not a report. `product_data.identity_report` is standing rule 1's
+    # second sentence as data for this grid's two identity columns: `product_id` (the Odoo
+    # `product.product` id, newly declared in `aios_grid_fields.json`) and `code` (the business
+    # key, which 33 active products do not have and wear a `pid:<id>` fallback for instead).
+    #
+    # ⛔ BUILT OVER `rows_src`, THE WALLED ROWS, NOT OVER THE CATALOGUE. `scoped_pool` runs
+    # `perm_scope.apply_row_scope` before these pids are taken, so a reader with a permanent
+    # filter sees fewer products than Odoo has; counting the catalogue here would print 33 beside
+    # a grid that does not contain 33 such rows, and a number that disagrees with the screen is
+    # believed anyway. It is the same list `rows_from_pool` was just handed, so the two cannot
+    # drift.
+    #
+    # ⚠ A NEW TOP-LEVEL KEY, NOT A MEMBER OF `identity`. `verify_api`'s W16 section asserts
+    # `body["identity"] == {"pid": "pid", "businessKey": "code"}` by EQUALITY, so folding the
+    # report in there would red a gate outside this ticket's fence for a purely cosmetic nesting.
+    # The envelope check beside it filters to the four `/customers` keys, so an additive key is
+    # the shape this route already established with `identity` and `scope`.
     return {"fields": g["fields"], "rows": rows,
             "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
             "identity": {"pid": "pid", "businessKey": "code"},
+            "identity_report": pd.identity_report(g["rows_src"]),
             "scope": {"team_id": g["team_id"], "consolidated": g["team_id"] is None}}

api/routes_publish.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_records.py CHANGED Viewed

@@ -1,211 +1,211 @@
-"""Record detail routes: durable comments, scoped to the caller's book — ON EVERY DATABASE.
-⭐ WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
-customer-shaped wall bolted to the module import line: `_in_book` asked
-`routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
-typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
-panel answered "that customer is not in your book" — the owner's report. The dangerous half is
-the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
-is filed against somebody's customer where the whole team can read it.
-THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
-events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
-per scope — the GRANT and the ROW SET — by asking that topic's own route, never by re-deriving
-one here:
-    customer / cohort   `routes_customers.allowed_pids` behind the `customer_data` grant
-    product             `routes_products.scoped_pool` behind the `product_data` grant
-    ut_<slug>           `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
-                        (404 unknown / 403 not yours — a user table has no module grant).
-                        ⭐ W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` — the pool builds every
-                        ROW to derive a pid set this module discards, and RAISES 409 on a
-                        read-through grid past one window, which is why the record drawer painted
-                        an error page on `ut_odoo_gl_lines`.
-⚠ THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
-section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
-another session's gate mid-wave — the WALL is the query parameter, not the word.
-⚠ NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
-shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
-400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
-the same reason: a typo served as `customer` answers a question nobody asked).
-"""
-from fastapi import APIRouter, Body, Depends, Query
-from deps import Session, err, require_session
-router = APIRouter(prefix="/api/v1")
-#: The customer topic's two names — one book, two surfaces (the Cohort page is the customer table
-#: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
-_CUSTOMER_SCOPES = ("", "customer", "cohort")
-def _scope_or_400(raw):
-    scope = str(raw or "customer").strip().lower()
-    if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
-        return "customer" if scope in _CUSTOMER_SCOPES else scope
-    raise err(400, "bad_scope",
-              "scope must be customer, cohort, product or a ut_ database — refusing to guess")
-def _pool_or_refuse(session: Session, scope: str):
-    """The pids this session may attach comments to ON THIS DATABASE — grant wall included.
-    Returns **`(pids, unbounded)`** — a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
-    so a caller who may not open the surface never learns anything about the row they asked about.
-    ⛔ `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
-    one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
-    `frozenset()` for both — see the branch below.
-    ⚠ THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
-    do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
-    that REPLACES this function with its own lambda. A gate's test double is a caller
-    ([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
-    bare frozenset and the section died on `ValueError: too many values to unpack` — no tally, no
-    failing name. Change the shape here and that double changes with it.
-    """
-    if scope == "product":
-        from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
-        session.require(PRODUCT_MODULE)
-        pids, _team, _rows, _fields = scoped_pool(session)
-        # ⚠ `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
-        # after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
-        # a `TypeError` — a 500 on every product comment — while both other branches worked. A
-        # return shape is a contract even when the function is private.
-        return (pids, False)
-    if scope.startswith("ut_"):
-        # No module grant exists for a user table — `_defn_or_refuse` inside `scoped_pids` IS
-        # the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
-        # rows routes do.
-        #
-        # ⭐⭐ W33-T03 / D-183 — `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
-        # `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
-        # a read-through grid larger than one window it RAISES `409 window_required`. So opening the
-        # record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page — for a panel
-        # that renders comments about ONE row it already has. `scoped_pids` answers the identical
-        # question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
-        # W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
-        # used to become openable on those two grids.
-        from routes_tables import scoped_pids
-        limits = []
-        pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
-        # ⛔ AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
-        # how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
-        # database with no rows and for a read-through grid too big to enumerate — it distinguishes
-        # them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
-        # from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
-        # is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
-        # ⚠ ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
-        # THE TENANT IS THE UNIT — `scoped_pool` itself carries "no per-row owner filter; the
-        # table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
-        # `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
-        return (pids, bool(limits))
-    from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
-    session.require(CUSTOMER_MODULE)
-    return (frozenset(allowed_pids(session)), False)
-def _in_book(pid, session, scope):
-    pids, unbounded = _pool_or_refuse(session, scope)
-    if unbounded:
-        # The table wall passed and the row set is larger than this process will enumerate. Said
-        # out loud rather than silently admitting: R6's second sentence is that a limit which
-        # cannot be removed gets REPORTED, and this is the one place the report has no envelope to
-        # ride in.
-        print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) — "
-              f"admitting on the table wall alone, per D-72")
-        return
-    if pid not in pids:
-        # 403, not 404: the record may exist, but this session may not inspect it.
-        raise err(403, "out_of_scope", "that record is not in your book")
-def _unavailable():
-    return err(
-        503,
-        "store_unavailable",
-        "record comments are temporarily unavailable — no change was saved",
-    )
-# ⭐ WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments — comments hang off a RECORD
-# in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
-# wall was always the query param). The old path stays as an ALIAS because the shipped client
-# still calls it; verify_api pins the canonical path AND that the alias answers, so removing
-# the alias later is a decision, never an accident.
-@router.get("/records/{pid}/comments")
-@router.get("/customers/{pid}/comments")
-def comments(pid: int, scope: str = Query(default="customer"),
-             session: Session = Depends(require_session)):
-    from core import record_comments
-    scope = _scope_or_400(scope)
-    _in_book(pid, session, scope)
-    try:
-        rows = record_comments.list_comments(session.runtime, pid, scope=scope)
-    except record_comments.CommentsUnavailable:
-        raise _unavailable()
-    return {"comments": rows}
-@router.post("/records/{pid}/comments", status_code=201)
-@router.post("/customers/{pid}/comments", status_code=201)
-def create_comment(
-    pid: int,
-    body: dict = Body(default=None),
-    scope: str = Query(default="customer"),
-    session: Session = Depends(require_session),
-):
-    from core import record_comments
-    scope = _scope_or_400(scope)
-    _in_book(pid, session, scope)
-    try:
-        comment = record_comments.add_comment(
-            session.runtime,
-            pid,
-            (body or {}).get("body"),
-            session.uname,
-            session.user.get("name") or session.uname,
-            scope=scope,
-        )
-    except ValueError as exc:
-        raise err(400, "bad_comment", str(exc))
-    except record_comments.CommentsUnavailable:
-        raise _unavailable()
-    return {"comment": comment}
-@router.delete("/records/{pid}/comments/{comment_id}")
-@router.delete("/customers/{pid}/comments/{comment_id}")
-def remove_comment(
-    pid: int,
-    comment_id: str,
-    scope: str = Query(default="customer"),
-    session: Session = Depends(require_session),
-):
-    from core import record_comments
-    scope = _scope_or_400(scope)
-    _in_book(pid, session, scope)
-    try:
-        deleted = record_comments.delete_comment(
-            session.runtime,
-            pid,
-            comment_id,
-            session.uname,
-            admin=session.admin,
-            scope=scope,
-        )
-    except record_comments.CommentForbidden:
-        raise err(403, "comment_forbidden", "only the author may delete this comment")
-    except record_comments.CommentsUnavailable:
-        raise _unavailable()
-    if not deleted:
-        raise err(404, "comment_not_found", "that comment no longer exists")
-    return {"ok": True, "id": comment_id}

+"""Record detail routes: durable comments, scoped to the caller's book — ON EVERY DATABASE.
+⭐ WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
+customer-shaped wall bolted to the module import line: `_in_book` asked
+`routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
+typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
+panel answered "that customer is not in your book" — the owner's report. The dangerous half is
+the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
+is filed against somebody's customer where the whole team can read it.
+THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
+events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
+per scope — the GRANT and the ROW SET — by asking that topic's own route, never by re-deriving
+one here:
+    customer / cohort   `routes_customers.allowed_pids` behind the `customer_data` grant
+    product             `routes_products.scoped_pool` behind the `product_data` grant
+    ut_<slug>           `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
+                        (404 unknown / 403 not yours — a user table has no module grant).
+                        ⭐ W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` — the pool builds every
+                        ROW to derive a pid set this module discards, and RAISES 409 on a
+                        read-through grid past one window, which is why the record drawer painted
+                        an error page on `ut_odoo_gl_lines`.
+⚠ THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
+section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
+another session's gate mid-wave — the WALL is the query parameter, not the word.
+⚠ NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
+shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
+400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
+the same reason: a typo served as `customer` answers a question nobody asked).
+"""
+from fastapi import APIRouter, Body, Depends, Query
+from deps import Session, err, require_session
+router = APIRouter(prefix="/api/v1")
+#: The customer topic's two names — one book, two surfaces (the Cohort page is the customer table
+#: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
+_CUSTOMER_SCOPES = ("", "customer", "cohort")
+def _scope_or_400(raw):
+    scope = str(raw or "customer").strip().lower()
+    if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
+        return "customer" if scope in _CUSTOMER_SCOPES else scope
+    raise err(400, "bad_scope",
+              "scope must be customer, cohort, product or a ut_ database — refusing to guess")
+def _pool_or_refuse(session: Session, scope: str):
+    """The pids this session may attach comments to ON THIS DATABASE — grant wall included.
+    Returns **`(pids, unbounded)`** — a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
+    so a caller who may not open the surface never learns anything about the row they asked about.
+    ⛔ `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
+    one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
+    `frozenset()` for both — see the branch below.
+    ⚠ THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
+    do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
+    that REPLACES this function with its own lambda. A gate's test double is a caller
+    ([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
+    bare frozenset and the section died on `ValueError: too many values to unpack` — no tally, no
+    failing name. Change the shape here and that double changes with it.
+    """
+    if scope == "product":
+        from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
+        session.require(PRODUCT_MODULE)
+        pids, _team, _rows, _fields = scoped_pool(session)
+        # ⚠ `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
+        # after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
+        # a `TypeError` — a 500 on every product comment — while both other branches worked. A
+        # return shape is a contract even when the function is private.
+        return (pids, False)
+    if scope.startswith("ut_"):
+        # No module grant exists for a user table — `_defn_or_refuse` inside `scoped_pids` IS
+        # the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
+        # rows routes do.
+        #
+        # ⭐⭐ W33-T03 / D-183 — `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
+        # `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
+        # a read-through grid larger than one window it RAISES `409 window_required`. So opening the
+        # record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page — for a panel
+        # that renders comments about ONE row it already has. `scoped_pids` answers the identical
+        # question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
+        # W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
+        # used to become openable on those two grids.
+        from routes_tables import scoped_pids
+        limits = []
+        pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
+        # ⛔ AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
+        # how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
+        # database with no rows and for a read-through grid too big to enumerate — it distinguishes
+        # them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
+        # from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
+        # is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
+        # ⚠ ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
+        # THE TENANT IS THE UNIT — `scoped_pool` itself carries "no per-row owner filter; the
+        # table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
+        # `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
+        return (pids, bool(limits))
+    from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
+    session.require(CUSTOMER_MODULE)
+    return (frozenset(allowed_pids(session)), False)
+def _in_book(pid, session, scope):
+    pids, unbounded = _pool_or_refuse(session, scope)
+    if unbounded:
+        # The table wall passed and the row set is larger than this process will enumerate. Said
+        # out loud rather than silently admitting: R6's second sentence is that a limit which
+        # cannot be removed gets REPORTED, and this is the one place the report has no envelope to
+        # ride in.
+        print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) — "
+              f"admitting on the table wall alone, per D-72")
+        return
+    if pid not in pids:
+        # 403, not 404: the record may exist, but this session may not inspect it.
+        raise err(403, "out_of_scope", "that record is not in your book")
+def _unavailable():
+    return err(
+        503,
+        "store_unavailable",
+        "record comments are temporarily unavailable — no change was saved",
+    )
+# ⭐ WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments — comments hang off a RECORD
+# in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
+# wall was always the query param). The old path stays as an ALIAS because the shipped client
+# still calls it; verify_api pins the canonical path AND that the alias answers, so removing
+# the alias later is a decision, never an accident.
+@router.get("/records/{pid}/comments")
+@router.get("/customers/{pid}/comments")
+def comments(pid: int, scope: str = Query(default="customer"),
+             session: Session = Depends(require_session)):
+    from core import record_comments
+    scope = _scope_or_400(scope)
+    _in_book(pid, session, scope)
+    try:
+        rows = record_comments.list_comments(session.runtime, pid, scope=scope)
+    except record_comments.CommentsUnavailable:
+        raise _unavailable()
+    return {"comments": rows}
+@router.post("/records/{pid}/comments", status_code=201)
+@router.post("/customers/{pid}/comments", status_code=201)
+def create_comment(
+    pid: int,
+    body: dict = Body(default=None),
+    scope: str = Query(default="customer"),
+    session: Session = Depends(require_session),
+):
+    from core import record_comments
+    scope = _scope_or_400(scope)
+    _in_book(pid, session, scope)
+    try:
+        comment = record_comments.add_comment(
+            session.runtime,
+            pid,
+            (body or {}).get("body"),
+            session.uname,
+            session.user.get("name") or session.uname,
+            scope=scope,
+        )
+    except ValueError as exc:
+        raise err(400, "bad_comment", str(exc))
+    except record_comments.CommentsUnavailable:
+        raise _unavailable()
+    return {"comment": comment}
+@router.delete("/records/{pid}/comments/{comment_id}")
+@router.delete("/customers/{pid}/comments/{comment_id}")
+def remove_comment(
+    pid: int,
+    comment_id: str,
+    scope: str = Query(default="customer"),
+    session: Session = Depends(require_session),
+):
+    from core import record_comments
+    scope = _scope_or_400(scope)
+    _in_book(pid, session, scope)
+    try:
+        deleted = record_comments.delete_comment(
+            session.runtime,
+            pid,
+            comment_id,
+            session.uname,
+            admin=session.admin,
+            scope=scope,
+        )
+    except record_comments.CommentForbidden:
+        raise err(403, "comment_forbidden", "only the author may delete this comment")
+    except record_comments.CommentsUnavailable:
+        raise _unavailable()
+    if not deleted:
+        raise err(404, "comment_not_found", "that comment no longer exists")
+    return {"ok": True, "id": comment_id}

api/routes_script_views.py CHANGED Viewed

@@ -1,439 +1,439 @@
-"""routes_script_views.py — CONTRACT C3: a database View that is a PYTHON SCRIPT (R3 / R5 / R10).
-Owner item 6, verbatim (2026-08-18): *"Add code script as an interface (database View) so a user
-can build whatever they want through the Agent chat interface. be able to create any dashboard
-they want. User should have the ability to see the code AND the dashboard output of course… Limit
-the code script View per database… Any agent can add into more AI script, so we can see different
-versions or different things the AI code for us."*
-    GET    /api/v1/script-views?database=K      the views bound to ONE database
-    POST   /api/v1/script-views                 create one   {database, name?, source}
-    GET    /api/v1/script-views/{id}            one view, its source and its history
-    PUT    /api/v1/script-views/{id}            a NEW VERSION of the source
-    DELETE /api/v1/script-views/{id}            drop it
-    POST   /api/v1/script-views/{id}/run        run it  ->  {ok, spec | error, stdout, ms}
-    POST   /api/v1/script-views/{id}/revert     go back to an earlier version  {version}
-⭐⭐ **R3 IS "SCOPED, NOT CAPPED", AND THE TWO HALVES POINT OPPOSITE WAYS.** *Scoped*: a view may
-read ONLY the database it lives in, and a script that names another database is REFUSED with a
-message naming both. *Not capped*: there is **no limit on how many script views a database may
-carry**, because that is how an agent offers three attempts and the owner picks one. So nothing
-below counts views. What IS bounded is what makes them big — one source is capped, and one view's
-edit history is capped and REPORTS what it dropped.
-⛔ **THE RUN IS THE CALLER'S, NEVER THE AUTHOR'S (R5).** `script_sandbox.run_view` is handed
-`session.user`, so a script written by an administrator and opened by a scoped analyst reads the
-ANALYST's rows. The author decides what the code does; the reader decides what it can see.
-⚠ And the reverse case is safe rather than lucky: a narrowly-scoped author cannot write a script
-that exfiltrates anything, because the only thing a script can return is a render spec drawn on
-the screen of the person who ran it. There is no network, no file and no second reader.
-⛔ **`run` IS `def`, NOT `async def`.** It waits on a subprocess for up to ten seconds; as a
-coroutine that would block the event loop for every other request in the container. FastAPI runs a
-plain `def` in the threadpool, which is what makes one slow script one slow REQUEST.
-"""
-import threading
-from datetime import datetime, timezone
-from fastapi import APIRouter, Body, Depends
-from deps import Session, err, require_session
-router = APIRouter(prefix="/api/v1")
-#: The tenant's script views: `{id: record}`. Per tenant, so it rides `runtime.store_key`.
-VIEWS_KEY = "script_views"
-MAX_NAME = 80
-MAX_SOURCE_BYTES = 128 * 1024
-#: Edit history per view. ⚠ NOT a cap on the NUMBER of views (R3 forbids that) — a cap on how far
-#: back ONE view's source is kept. Past this the oldest go and `trimmed` counts them, so a reader
-#: can see the history is partial instead of concluding the view was only ever saved twice.
-MAX_HISTORY = 40
-#: ⛔ HOW MANY SCRIPTS MAY BE RUNNING IN THIS CONTAINER AT ONCE, and it is a REPORTED refusal
-#: rather than a queue. Each run is a real subprocess with a ten-second wall clock; without this,
-#: holding down refresh forks until the box gives up, and the tenant's ONE FastAPI process is what
-#: gives up. A 429 that says so is honest; an unbounded fork is not.
-MAX_CONCURRENT_RUNS = 4
-_RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
-def _now():
-    return datetime.now(timezone.utc).isoformat(timespec="seconds")
-def _all(rt):
-    """`{id: record}` for one tenant. `{}` on any failure — an unreadable bucket must degrade to
-    "this database has no script views", never to a 500 on the view rail."""
-    try:
-        found = rt.get(VIEWS_KEY) or {}
-    except Exception:                                                        # noqa: BLE001
-        return {}
-    return found if isinstance(found, dict) else {}
-def _database_ok(session, database):
-    """Does this database EXIST, and may this caller read it? Answered by C1, never by a list.
-    ⛔ `perm_scope.may_read` ALONE IS NOT ENOUGH and the reason is easy to miss: it answers True
-    for an ADMIN on any key at all, including one no database answers to. So a create validated
-    with `may_read` would let an administrator bind a view to a typo and leave an orphan nothing
-    can ever run. `scoped_fields` is the cheap half of C1 (a `ut_*` definition, no rows) and it
-    RAISES `UnknownTable`, which is exactly the question being asked.
-    """
-    import core.perm_scope as perm_scope
-    try:
-        perm_scope.scoped_fields(session.user, database, st=session.runtime)
-    except perm_scope.UnknownTable:
-        raise err(404, "no_database", f"there is no database '{database}' in this workspace")
-    except perm_scope.Denied:
-        raise err(403, "forbidden", f"your account may not read '{database}'")
-    except perm_scope.Unresolvable as exc:
-        # The database is real and cannot be served under this call's constraints. Standing rule
-        # 1's second sentence: report the cause and the recommendation, never a bare refusal.
-        raise err(409, "unresolvable", str(exc)) from None
-def _clean_source(raw, *, allow_empty=False):
-    """The stored source, or a 400. `allow_empty` is CREATE's alone and the asymmetry is the point.
-    ⭐⭐ W37-T41 — WHY CREATE MAY BE EMPTY AND SAVE MAY NOT.
-    Picking "Custom View" in the mode picker mints the view immediately, before a line of code
-    exists, so that `mode === 'script'` always implies a real id and no reader has to carry a
-    "the id might be missing" branch (the create semantics handed to lane C in mailbox E-7).
-    A view that has been created and not yet written is therefore a REAL, legible state: the editor
-    shows its starter placeholder and the Run control is right there.
-    A PUT is a different act. It appends a VERSION to a history capped at 40, and blanking a
-    working script by saving nothing over it is not an edit anybody means to make. So the guard
-    stays exactly where it was on that door, and a person who wants the view gone deletes it.
-    ⛔ THIS WAS FOUND BY THE GATE, NOT BY READING. `core.script_sandbox.check_source("")` returns
-    None, so "an empty script is storable" looked true and was written into a mailbox answer another
-    lane was about to build on. The refusal was HERE, one layer above, in a function the sandbox
-    knows nothing about. Two validators for one question, disagreeing
-    [[one-question-two-normalizers]] — and the one that would have bitten a person is the one no
-    unit of this feature was asserting.
-    """
-    source = str(raw or "")
-    if not source.strip() and not allow_empty:
-        raise err(400, "no_source", "a script view needs some code")
-    if len(source.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
-        raise err(413, "source_too_long",
-                  f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of code")
-    return source
-def _row(rec, *, source=False):
-    """One view as the list door reports it. ⚠ NO SOURCE unless asked: the rail lists names."""
-    out = {"id": rec.get("id") or "", "database": rec.get("database") or "",
-           "name": rec.get("name") or "", "author": rec.get("author") or "",
-           "version": int(rec.get("version") or 1),
-           "created": rec.get("created") or "", "updated": rec.get("updated") or "",
-           "versions": len(rec.get("history") or []) + 1,
-           "trimmed": int(rec.get("trimmed") or 0),
-           # ⭐ W37-T46: which version this one was RESTORED from, when it was. Present on the
-           # row (not only the history) because the editor's header is where a person reads "what
-           # am I looking at", and "v5, restored from v2" is the sentence that makes a roll-back
-           # legible as an event rather than as a coincidence of matching code.
-           "restoredFrom": rec.get("restoredFrom")}
-    if source:
-        out["source"] = rec.get("source") or ""
-        out["history"] = [{"version": int(h.get("version") or 0), "author": h.get("author") or "",
-                           "created": h.get("created") or "",
-                           "bytes": len(str(h.get("source") or "").encode("utf-8", "replace"))}
-                          for h in reversed(rec.get("history") or []) if isinstance(h, dict)]
-    return out
-def _limits():
-    return {"maxSourceBytes": MAX_SOURCE_BYTES, "maxName": MAX_NAME,
-            "maxHistory": MAX_HISTORY, "maxConcurrentRuns": MAX_CONCURRENT_RUNS,
-            # ⭐ SAID OUT LOUD, because R3's "not capped" half is the one a reader assumes wrong.
-            "maxViewsPerDatabase": None}
-def _put(session, view_id, mutate):
-    """Read-modify-write ONE view, synchronously — the client re-reads the rail immediately."""
-    def _set(cur):
-        cur = dict(cur or {})
-        nxt = mutate(cur.get(view_id) if isinstance(cur.get(view_id), dict) else None)
-        if nxt is None:
-            cur.pop(view_id, None)
-        else:
-            cur[view_id] = nxt
-        return cur
-    session.runtime.update(VIEWS_KEY, _set, flush="sync")
-def _mine_or_admin(session, rec):
-    """Who may EDIT or DELETE a view: its author, or an administrator.
-    ⚠ RUNNING IS A DIFFERENT QUESTION and deliberately wider — anybody who may read the database
-    may run any view on it, under their OWN scope. That is the whole of "so we can see different
-    versions or different things the AI code for us": a colleague's attempt is worth nothing if
-    only its author can open it.
-    """
-    if session.admin or str(rec.get("author") or "") == session.uname:
-        return
-    raise err(403, "forbidden", "only the author or an administrator can change this script view")
-# ── the routes ────────────────────────────────────────────────────────────────────────────────
-@router.get("/script-views")
-def list_script_views(database: str = "", session: Session = Depends(require_session)):
-    """Every script view bound to ONE database, newest first. `database` is required."""
-    key = str(database or "").strip()
-    if not key:
-        raise err(400, "no_database", "name the database whose script views you want")
-    _database_ok(session, key)
-    rows = [_row(rec) for rec in _all(session.runtime).values()
-            if isinstance(rec, dict) and str(rec.get("database") or "") == key]
-    rows.sort(key=lambda r: (r["created"], r["id"]), reverse=True)
-    return {"database": key, "views": rows, "limits": _limits()}
-@router.post("/script-views")
-def create_script_view(body: dict = Body(default=None),
-                       session: Session = Depends(require_session)):
-    """Create one. ⛔ THE SOURCE IS CHECKED BEFORE IT IS STORED, not first at run time.
-    A script view that cannot be run is a broken feature the reader discovers by pressing a button,
-    and the agent that wrote it is long gone by then. `check_source` is pure and costs no process,
-    so the refusal arrives while the author still has the code in front of them.
-    """
-    import secrets                                                           # noqa: PLC0415
-    import core.script_sandbox as sandbox                                    # noqa: PLC0415
-    body = body if isinstance(body, dict) else {}
-    database = str(body.get("database") or "").strip()
-    if not database:
-        raise err(400, "no_database", "a script view is bound to one database")
-    _database_ok(session, database)
-    # ⭐ `allow_empty` is CREATE's alone - see `_clean_source`. The picker mints a view the
-    # moment a person chooses the mode, so the empty source is the normal first state, not a slip.
-    source = _clean_source(body.get("source"), allow_empty=True)
-    refusal = sandbox.check_source(source)
-    if refusal is not None:
-        raise err(400, refusal.code, refusal.message)
-    view_id = "sv_" + secrets.token_urlsafe(9)
-    rec = {"id": view_id, "database": database,
-           "name": " ".join(str(body.get("name") or "Script view").split())[:MAX_NAME],
-           "source": source, "author": session.uname, "version": 1,
-           "created": _now(), "updated": _now(), "history": [], "trimmed": 0}
-    _put(session, view_id, lambda _prior: rec)
-    fresh = _all(session.runtime).get(view_id)
-    if not isinstance(fresh, dict):
-        # The store took the write and did not record it. A 200 here would tell the author their
-        # script was saved when it was not.
-        raise err(503, "store_unavailable", "the script view was NOT created")
-    return {"view": _row(fresh, source=True), "limits": _limits()}
-@router.get("/script-views/{view_id}")
-def get_script_view(view_id: str, session: Session = Depends(require_session)):
-    """One view WITH its source and its edit history. Owner item 6's *"see the code"* half."""
-    rec = _all(session.runtime).get(str(view_id))
-    if not isinstance(rec, dict):
-        raise err(404, "no_view", "there is no script view with that id")
-    _database_ok(session, str(rec.get("database") or ""))
-    return {"view": _row(rec, source=True), "limits": _limits()}
-@router.put("/script-views/{view_id}")
-def update_script_view(view_id: str, body: dict = Body(default=None),
-                       session: Session = Depends(require_session)):
-    """A NEW VERSION of one view's source. The prior source is KEPT, never replaced in place."""
-    import core.script_sandbox as sandbox                                    # noqa: PLC0415
-    view_id = str(view_id)
-    rec = _all(session.runtime).get(view_id)
-    if not isinstance(rec, dict):
-        raise err(404, "no_view", "there is no script view with that id")
-    _mine_or_admin(session, rec)
-    body = body if isinstance(body, dict) else {}
-    source = _clean_source(body.get("source"))
-    refusal = sandbox.check_source(source)
-    if refusal is not None:
-        raise err(400, refusal.code, refusal.message)
-    def _mutate(prior):
-        prior = dict(prior or rec)
-        history = list(prior.get("history") or [])
-        history.append({"version": int(prior.get("version") or 1),
-                        "source": prior.get("source") or "",
-                        "author": prior.get("author") or "", "created": prior.get("updated") or ""})
-        dropped = max(0, len(history) - MAX_HISTORY)
-        prior["history"] = history[dropped:] if dropped else history
-        prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
-        prior["source"] = source
-        prior["version"] = int(prior.get("version") or 1) + 1
-        prior["updated"] = _now()
-        if body.get("name"):
-            prior["name"] = " ".join(str(body["name"]).split())[:MAX_NAME]
-        return prior
-    _put(session, view_id, _mutate)
-    fresh = _all(session.runtime).get(view_id)
-    if not isinstance(fresh, dict):
-        raise err(503, "store_unavailable", "the new version was NOT saved")
-    return {"view": _row(fresh, source=True), "limits": _limits()}
-@router.post("/script-views/{view_id}/revert")
-def revert_script_view(view_id: str, body: dict = Body(default=None),
-                       session: Session = Depends(require_session)):
-    """Put one view back to an earlier version. D-338 / W37-T46.
-    ⭐⭐ A ROLL-BACK IS A NEW VERSION, NEVER A DELETE OF THE ONES AFTER IT, and that is the whole
-    point of the ticket rather than an implementation detail. The history is what lets a person
-    trust an agent with their code: if reverting destroyed the versions it stepped over, one
-    mistaken revert would cost exactly what the history existed to protect, and there would be no
-    way back from the way back. So this appends, and `restoredFrom` records where the text came
-    from — the same posture the agent-harness roll-back already takes, so a reader who has seen one
-    is not surprised by the other.
-    ⛔ IT LIVES ON THE SERVER BECAUSE THE HISTORY DOES. The list door deliberately serves history
-    entries WITHOUT their source (`_row`: the rail lists names), so a client cannot assemble an old
-    version's text to re-PUT it. Handing the source out just so the client could send it straight
-    back would widen a payload for a round trip that does not need to exist, and would make the
-    revert non-atomic: two calls, and a failure between them leaves the person looking at code that
-    is not what is stored.
-    ⚠ `_clean_source` is NOT re-run. The text being restored was already validated when it was
-    first saved, and a source that a later, stricter rule would now reject is exactly the source a
-    person is most likely to want back. `check_source` still runs, because the SANDBOX's refusal is
-    about what the code would DO and that must never be bypassed by a route.
-    """
-    import core.script_sandbox as sandbox                                    # noqa: PLC0415
-    view_id = str(view_id)
-    rec = _all(session.runtime).get(view_id)
-    if not isinstance(rec, dict):
-        raise err(404, "no_view", "there is no script view with that id")
-    _mine_or_admin(session, rec)
-    body = body if isinstance(body, dict) else {}
-    try:
-        want = int(body.get("version"))
-    except (TypeError, ValueError):
-        raise err(400, "no_version", "say which version to go back to") from None
-    history = [h for h in (rec.get("history") or []) if isinstance(h, dict)]
-    match = next((h for h in history if int(h.get("version") or 0) == want), None)
-    if match is None:
-        # ⛔ TWO REASONS A VERSION IS MISSING AND THEY ARE NOT THE SAME FACT. One was never
-        # written; the other was TRIMMED off the 40-deep history and the record even counts how
-        # many. Saying "that version is gone" for the first would be a lie a person could act on.
-        trimmed = int(rec.get("trimmed") or 0)
-        if trimmed and want <= trimmed:
-            raise err(410, "version_trimmed",
-                      f"version {want} is older than this view's history keeps "
-                      f"({trimmed} earlier versions have been dropped)")
-        raise err(404, "no_version", f"this view has no version {want}")
-    source = str(match.get("source") or "")
-    refusal = sandbox.check_source(source)
-    if refusal is not None:
-        # An older version that today's sandbox refuses. The person is told which version and why,
-        # rather than being handed a 400 about code they did not just type.
-        raise err(400, refusal.code, f"version {want} cannot be restored: {refusal.message}")
-    def _mutate(prior):
-        prior = dict(prior or rec)
-        history_now = list(prior.get("history") or [])
-        history_now.append({"version": int(prior.get("version") or 1),
-                            "source": prior.get("source") or "",
-                            "author": prior.get("author") or "",
-                            "created": prior.get("updated") or ""})
-        dropped = max(0, len(history_now) - MAX_HISTORY)
-        prior["history"] = history_now[dropped:] if dropped else history_now
-        prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
-        prior["source"] = source
-        prior["version"] = int(prior.get("version") or 1) + 1
-        prior["updated"] = _now()
-        # ⚠ ON THE RECORD, so the history reads as WHAT HAPPENED rather than as a version that
-        # mysteriously matches an older one. Without it a reader sees v5 and v2 with identical
-        # code and no way to tell a revert from a coincidence.
-        prior["restoredFrom"] = want
-        return prior
-    _put(session, view_id, _mutate)
-    fresh = _all(session.runtime).get(view_id)
-    if not isinstance(fresh, dict):
-        raise err(503, "store_unavailable", "the roll-back was NOT saved")
-    return {"view": _row(fresh, source=True), "restoredFrom": want, "limits": _limits()}
-@router.delete("/script-views/{view_id}")
-def delete_script_view(view_id: str, session: Session = Depends(require_session)):
-    view_id = str(view_id)
-    rec = _all(session.runtime).get(view_id)
-    if not isinstance(rec, dict):
-        raise err(404, "no_view", "there is no script view with that id")
-    _mine_or_admin(session, rec)
-    _put(session, view_id, lambda _prior: None)
-    return {"deleted": view_id}
-@router.post("/script-views/{view_id}/run")
-def run_script_view(view_id: str, body: dict = Body(default=None),
-                    session: Session = Depends(require_session)):
-    """CONTRACT C3's run door: `{ok, spec | error, stdout, ms}`.
-    ⛔ `spec` IS A DESCRIPTION THE CLIENT DRAWS. It is never HTML and never text the browser
-    executes — the sandbox refuses a spec carrying an `html`, `script`, `src`, `href` or `on*` key
-    before this function ever sees it, so a renderer cannot be talked into running something by a
-    script that was itself perfectly well behaved.
-    ⛔ AND IT IS PLAIN `def`, NOT `async def` — see this module's header. A ten-second subprocess
-    wait on the event loop is a ten-second outage for the whole container.
-    """
-    import core.script_sandbox as sandbox                                    # noqa: PLC0415
-    rec = _all(session.runtime).get(str(view_id))
-    if not isinstance(rec, dict):
-        raise err(404, "no_view", "there is no script view with that id")
-    database = str(rec.get("database") or "")
-    # A DRAFT run: the editor sends unsaved code so the author can try it before committing to it.
-    # It is checked exactly as a stored one is, because "unsaved" is not a permission.
-    draft = (body or {}).get("source") if isinstance(body, dict) else None
-    source = _clean_source(draft) if draft else str(rec.get("source") or "")
-    # ⚠ NO `_database_ok` CALL HERE. `run_view` asks C1 the identical question a line later, and
-    # asking twice builds a registry topic's pool twice. The three refusals are translated below
-    # instead, which is the same wall reached through the same door.
-    if not _RUN_SLOTS.acquire(blocking=False):
-        raise err(429, "busy",
-                  f"{MAX_CONCURRENT_RUNS} script views are already running on this server. "
-                  f"Try again in a moment")
-    try:
-        out = sandbox.run_view(session.user, database, source, st=session.runtime)
-    finally:
-        _RUN_SLOTS.release()
-    # ⛔ C1'S THREE REFUSALS ARE HTTP STATUSES, NOT `ok:false`. "You may not read this database"
-    # answered 200 would be a permission decision the client has to go looking for, and every
-    # other door in this app answers 403 for it. Everything BELOW this line is a well-formed
-    # request whose ANSWER is that the script did not produce a view — that is a 200 with
-    # `ok:false`, the shape `routes_web_agent.test` already uses for the same reason.
-    if out.get("code") == "unknown_table":
-        raise err(404, "no_database", out.get("message") or f"there is no database '{database}'")
-    if out.get("code") == "denied":
-        raise err(403, "forbidden", out.get("message") or "your account may not read that database")
-    if out.get("code") == "unresolvable":
-        refusal = err(409, "unresolvable", out.get("message") or "these rows cannot be served")
-        refusal.detail["error"]["limit"] = out.get("limit") or {}
-        raise refusal
-    answer = {"ok": bool(out.get("ok")), "spec": out.get("spec"),
-              "stdout": out.get("stdout") or "", "truncated": bool(out.get("truncated")),
-              "ms": int(out.get("ms") or 0), "code": out.get("code") or "",
-              # ⭐ `caps` RIDES ON THE ANSWER (standing rule 1). On a POSIX host all three limits
-              # were applied; on a Windows host the memory and CPU ones were not, and a screen
-              # that claims an enforcement which did not happen is the failure the rule is about.
-              "caps": out.get("caps") or {}}
-    if not answer["ok"]:
-        answer["error"] = out.get("message") or "the script view did not produce a view"
-    return answer

+"""routes_script_views.py — CONTRACT C3: a database View that is a PYTHON SCRIPT (R3 / R5 / R10).
+Owner item 6, verbatim (2026-08-18): *"Add code script as an interface (database View) so a user
+can build whatever they want through the Agent chat interface. be able to create any dashboard
+they want. User should have the ability to see the code AND the dashboard output of course… Limit
+the code script View per database… Any agent can add into more AI script, so we can see different
+versions or different things the AI code for us."*
+    GET    /api/v1/script-views?database=K      the views bound to ONE database
+    POST   /api/v1/script-views                 create one   {database, name?, source}
+    GET    /api/v1/script-views/{id}            one view, its source and its history
+    PUT    /api/v1/script-views/{id}            a NEW VERSION of the source
+    DELETE /api/v1/script-views/{id}            drop it
+    POST   /api/v1/script-views/{id}/run        run it  ->  {ok, spec | error, stdout, ms}
+    POST   /api/v1/script-views/{id}/revert     go back to an earlier version  {version}
+⭐⭐ **R3 IS "SCOPED, NOT CAPPED", AND THE TWO HALVES POINT OPPOSITE WAYS.** *Scoped*: a view may
+read ONLY the database it lives in, and a script that names another database is REFUSED with a
+message naming both. *Not capped*: there is **no limit on how many script views a database may
+carry**, because that is how an agent offers three attempts and the owner picks one. So nothing
+below counts views. What IS bounded is what makes them big — one source is capped, and one view's
+edit history is capped and REPORTS what it dropped.
+⛔ **THE RUN IS THE CALLER'S, NEVER THE AUTHOR'S (R5).** `script_sandbox.run_view` is handed
+`session.user`, so a script written by an administrator and opened by a scoped analyst reads the
+ANALYST's rows. The author decides what the code does; the reader decides what it can see.
+⚠ And the reverse case is safe rather than lucky: a narrowly-scoped author cannot write a script
+that exfiltrates anything, because the only thing a script can return is a render spec drawn on
+the screen of the person who ran it. There is no network, no file and no second reader.
+⛔ **`run` IS `def`, NOT `async def`.** It waits on a subprocess for up to ten seconds; as a
+coroutine that would block the event loop for every other request in the container. FastAPI runs a
+plain `def` in the threadpool, which is what makes one slow script one slow REQUEST.
+"""
+import threading
+from datetime import datetime, timezone
+from fastapi import APIRouter, Body, Depends
+from deps import Session, err, require_session
+router = APIRouter(prefix="/api/v1")
+#: The tenant's script views: `{id: record}`. Per tenant, so it rides `runtime.store_key`.
+VIEWS_KEY = "script_views"
+MAX_NAME = 80
+MAX_SOURCE_BYTES = 128 * 1024
+#: Edit history per view. ⚠ NOT a cap on the NUMBER of views (R3 forbids that) — a cap on how far
+#: back ONE view's source is kept. Past this the oldest go and `trimmed` counts them, so a reader
+#: can see the history is partial instead of concluding the view was only ever saved twice.
+MAX_HISTORY = 40
+#: ⛔ HOW MANY SCRIPTS MAY BE RUNNING IN THIS CONTAINER AT ONCE, and it is a REPORTED refusal
+#: rather than a queue. Each run is a real subprocess with a ten-second wall clock; without this,
+#: holding down refresh forks until the box gives up, and the tenant's ONE FastAPI process is what
+#: gives up. A 429 that says so is honest; an unbounded fork is not.
+MAX_CONCURRENT_RUNS = 4
+_RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
+def _now():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+def _all(rt):
+    """`{id: record}` for one tenant. `{}` on any failure — an unreadable bucket must degrade to
+    "this database has no script views", never to a 500 on the view rail."""
+    try:
+        found = rt.get(VIEWS_KEY) or {}
+    except Exception:                                                        # noqa: BLE001
+        return {}
+    return found if isinstance(found, dict) else {}
+def _database_ok(session, database):
+    """Does this database EXIST, and may this caller read it? Answered by C1, never by a list.
+    ⛔ `perm_scope.may_read` ALONE IS NOT ENOUGH and the reason is easy to miss: it answers True
+    for an ADMIN on any key at all, including one no database answers to. So a create validated
+    with `may_read` would let an administrator bind a view to a typo and leave an orphan nothing
+    can ever run. `scoped_fields` is the cheap half of C1 (a `ut_*` definition, no rows) and it
+    RAISES `UnknownTable`, which is exactly the question being asked.
+    """
+    import core.perm_scope as perm_scope
+    try:
+        perm_scope.scoped_fields(session.user, database, st=session.runtime)
+    except perm_scope.UnknownTable:
+        raise err(404, "no_database", f"there is no database '{database}' in this workspace")
+    except perm_scope.Denied:
+        raise err(403, "forbidden", f"your account may not read '{database}'")
+    except perm_scope.Unresolvable as exc:
+        # The database is real and cannot be served under this call's constraints. Standing rule
+        # 1's second sentence: report the cause and the recommendation, never a bare refusal.
+        raise err(409, "unresolvable", str(exc)) from None
+def _clean_source(raw, *, allow_empty=False):
+    """The stored source, or a 400. `allow_empty` is CREATE's alone and the asymmetry is the point.
+    ⭐⭐ W37-T41 — WHY CREATE MAY BE EMPTY AND SAVE MAY NOT.
+    Picking "Custom View" in the mode picker mints the view immediately, before a line of code
+    exists, so that `mode === 'script'` always implies a real id and no reader has to carry a
+    "the id might be missing" branch (the create semantics handed to lane C in mailbox E-7).
+    A view that has been created and not yet written is therefore a REAL, legible state: the editor
+    shows its starter placeholder and the Run control is right there.
+    A PUT is a different act. It appends a VERSION to a history capped at 40, and blanking a
+    working script by saving nothing over it is not an edit anybody means to make. So the guard
+    stays exactly where it was on that door, and a person who wants the view gone deletes it.
+    ⛔ THIS WAS FOUND BY THE GATE, NOT BY READING. `core.script_sandbox.check_source("")` returns
+    None, so "an empty script is storable" looked true and was written into a mailbox answer another
+    lane was about to build on. The refusal was HERE, one layer above, in a function the sandbox
+    knows nothing about. Two validators for one question, disagreeing
+    [[one-question-two-normalizers]] — and the one that would have bitten a person is the one no
+    unit of this feature was asserting.
+    """
+    source = str(raw or "")
+    if not source.strip() and not allow_empty:
+        raise err(400, "no_source", "a script view needs some code")
+    if len(source.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
+        raise err(413, "source_too_long",
+                  f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of code")
+    return source
+def _row(rec, *, source=False):
+    """One view as the list door reports it. ⚠ NO SOURCE unless asked: the rail lists names."""
+    out = {"id": rec.get("id") or "", "database": rec.get("database") or "",
+           "name": rec.get("name") or "", "author": rec.get("author") or "",
+           "version": int(rec.get("version") or 1),
+           "created": rec.get("created") or "", "updated": rec.get("updated") or "",
+           "versions": len(rec.get("history") or []) + 1,
+           "trimmed": int(rec.get("trimmed") or 0),
+           # ⭐ W37-T46: which version this one was RESTORED from, when it was. Present on the
+           # row (not only the history) because the editor's header is where a person reads "what
+           # am I looking at", and "v5, restored from v2" is the sentence that makes a roll-back
+           # legible as an event rather than as a coincidence of matching code.
+           "restoredFrom": rec.get("restoredFrom")}
+    if source:
+        out["source"] = rec.get("source") or ""
+        out["history"] = [{"version": int(h.get("version") or 0), "author": h.get("author") or "",
+                           "created": h.get("created") or "",
+                           "bytes": len(str(h.get("source") or "").encode("utf-8", "replace"))}
+                          for h in reversed(rec.get("history") or []) if isinstance(h, dict)]
+    return out
+def _limits():
+    return {"maxSourceBytes": MAX_SOURCE_BYTES, "maxName": MAX_NAME,
+            "maxHistory": MAX_HISTORY, "maxConcurrentRuns": MAX_CONCURRENT_RUNS,
+            # ⭐ SAID OUT LOUD, because R3's "not capped" half is the one a reader assumes wrong.
+            "maxViewsPerDatabase": None}
+def _put(session, view_id, mutate):
+    """Read-modify-write ONE view, synchronously — the client re-reads the rail immediately."""
+    def _set(cur):
+        cur = dict(cur or {})
+        nxt = mutate(cur.get(view_id) if isinstance(cur.get(view_id), dict) else None)
+        if nxt is None:
+            cur.pop(view_id, None)
+        else:
+            cur[view_id] = nxt
+        return cur
+    session.runtime.update(VIEWS_KEY, _set, flush="sync")
+def _mine_or_admin(session, rec):
+    """Who may EDIT or DELETE a view: its author, or an administrator.
+    ⚠ RUNNING IS A DIFFERENT QUESTION and deliberately wider — anybody who may read the database
+    may run any view on it, under their OWN scope. That is the whole of "so we can see different
+    versions or different things the AI code for us": a colleague's attempt is worth nothing if
+    only its author can open it.
+    """
+    if session.admin or str(rec.get("author") or "") == session.uname:
+        return
+    raise err(403, "forbidden", "only the author or an administrator can change this script view")
+# ── the routes ────────────────────────────────────────────────────────────────────────────────
+@router.get("/script-views")
+def list_script_views(database: str = "", session: Session = Depends(require_session)):
+    """Every script view bound to ONE database, newest first. `database` is required."""
+    key = str(database or "").strip()
+    if not key:
+        raise err(400, "no_database", "name the database whose script views you want")
+    _database_ok(session, key)
+    rows = [_row(rec) for rec in _all(session.runtime).values()
+            if isinstance(rec, dict) and str(rec.get("database") or "") == key]
+    rows.sort(key=lambda r: (r["created"], r["id"]), reverse=True)
+    return {"database": key, "views": rows, "limits": _limits()}
+@router.post("/script-views")
+def create_script_view(body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    """Create one. ⛔ THE SOURCE IS CHECKED BEFORE IT IS STORED, not first at run time.
+    A script view that cannot be run is a broken feature the reader discovers by pressing a button,
+    and the agent that wrote it is long gone by then. `check_source` is pure and costs no process,
+    so the refusal arrives while the author still has the code in front of them.
+    """
+    import secrets                                                           # noqa: PLC0415
+    import core.script_sandbox as sandbox                                    # noqa: PLC0415
+    body = body if isinstance(body, dict) else {}
+    database = str(body.get("database") or "").strip()
+    if not database:
+        raise err(400, "no_database", "a script view is bound to one database")
+    _database_ok(session, database)
+    # ⭐ `allow_empty` is CREATE's alone - see `_clean_source`. The picker mints a view the
+    # moment a person chooses the mode, so the empty source is the normal first state, not a slip.
+    source = _clean_source(body.get("source"), allow_empty=True)
+    refusal = sandbox.check_source(source)
+    if refusal is not None:
+        raise err(400, refusal.code, refusal.message)
+    view_id = "sv_" + secrets.token_urlsafe(9)
+    rec = {"id": view_id, "database": database,
+           "name": " ".join(str(body.get("name") or "Script view").split())[:MAX_NAME],
+           "source": source, "author": session.uname, "version": 1,
+           "created": _now(), "updated": _now(), "history": [], "trimmed": 0}
+    _put(session, view_id, lambda _prior: rec)
+    fresh = _all(session.runtime).get(view_id)
+    if not isinstance(fresh, dict):
+        # The store took the write and did not record it. A 200 here would tell the author their
+        # script was saved when it was not.
+        raise err(503, "store_unavailable", "the script view was NOT created")
+    return {"view": _row(fresh, source=True), "limits": _limits()}
+@router.get("/script-views/{view_id}")
+def get_script_view(view_id: str, session: Session = Depends(require_session)):
+    """One view WITH its source and its edit history. Owner item 6's *"see the code"* half."""
+    rec = _all(session.runtime).get(str(view_id))
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    _database_ok(session, str(rec.get("database") or ""))
+    return {"view": _row(rec, source=True), "limits": _limits()}
+@router.put("/script-views/{view_id}")
+def update_script_view(view_id: str, body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    """A NEW VERSION of one view's source. The prior source is KEPT, never replaced in place."""
+    import core.script_sandbox as sandbox                                    # noqa: PLC0415
+    view_id = str(view_id)
+    rec = _all(session.runtime).get(view_id)
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    _mine_or_admin(session, rec)
+    body = body if isinstance(body, dict) else {}
+    source = _clean_source(body.get("source"))
+    refusal = sandbox.check_source(source)
+    if refusal is not None:
+        raise err(400, refusal.code, refusal.message)
+    def _mutate(prior):
+        prior = dict(prior or rec)
+        history = list(prior.get("history") or [])
+        history.append({"version": int(prior.get("version") or 1),
+                        "source": prior.get("source") or "",
+                        "author": prior.get("author") or "", "created": prior.get("updated") or ""})
+        dropped = max(0, len(history) - MAX_HISTORY)
+        prior["history"] = history[dropped:] if dropped else history
+        prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
+        prior["source"] = source
+        prior["version"] = int(prior.get("version") or 1) + 1
+        prior["updated"] = _now()
+        if body.get("name"):
+            prior["name"] = " ".join(str(body["name"]).split())[:MAX_NAME]
+        return prior
+    _put(session, view_id, _mutate)
+    fresh = _all(session.runtime).get(view_id)
+    if not isinstance(fresh, dict):
+        raise err(503, "store_unavailable", "the new version was NOT saved")
+    return {"view": _row(fresh, source=True), "limits": _limits()}
+@router.post("/script-views/{view_id}/revert")
+def revert_script_view(view_id: str, body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    """Put one view back to an earlier version. D-338 / W37-T46.
+    ⭐⭐ A ROLL-BACK IS A NEW VERSION, NEVER A DELETE OF THE ONES AFTER IT, and that is the whole
+    point of the ticket rather than an implementation detail. The history is what lets a person
+    trust an agent with their code: if reverting destroyed the versions it stepped over, one
+    mistaken revert would cost exactly what the history existed to protect, and there would be no
+    way back from the way back. So this appends, and `restoredFrom` records where the text came
+    from — the same posture the agent-harness roll-back already takes, so a reader who has seen one
+    is not surprised by the other.
+    ⛔ IT LIVES ON THE SERVER BECAUSE THE HISTORY DOES. The list door deliberately serves history
+    entries WITHOUT their source (`_row`: the rail lists names), so a client cannot assemble an old
+    version's text to re-PUT it. Handing the source out just so the client could send it straight
+    back would widen a payload for a round trip that does not need to exist, and would make the
+    revert non-atomic: two calls, and a failure between them leaves the person looking at code that
+    is not what is stored.
+    ⚠ `_clean_source` is NOT re-run. The text being restored was already validated when it was
+    first saved, and a source that a later, stricter rule would now reject is exactly the source a
+    person is most likely to want back. `check_source` still runs, because the SANDBOX's refusal is
+    about what the code would DO and that must never be bypassed by a route.
+    """
+    import core.script_sandbox as sandbox                                    # noqa: PLC0415
+    view_id = str(view_id)
+    rec = _all(session.runtime).get(view_id)
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    _mine_or_admin(session, rec)
+    body = body if isinstance(body, dict) else {}
+    try:
+        want = int(body.get("version"))
+    except (TypeError, ValueError):
+        raise err(400, "no_version", "say which version to go back to") from None
+    history = [h for h in (rec.get("history") or []) if isinstance(h, dict)]
+    match = next((h for h in history if int(h.get("version") or 0) == want), None)
+    if match is None:
+        # ⛔ TWO REASONS A VERSION IS MISSING AND THEY ARE NOT THE SAME FACT. One was never
+        # written; the other was TRIMMED off the 40-deep history and the record even counts how
+        # many. Saying "that version is gone" for the first would be a lie a person could act on.
+        trimmed = int(rec.get("trimmed") or 0)
+        if trimmed and want <= trimmed:
+            raise err(410, "version_trimmed",
+                      f"version {want} is older than this view's history keeps "
+                      f"({trimmed} earlier versions have been dropped)")
+        raise err(404, "no_version", f"this view has no version {want}")
+    source = str(match.get("source") or "")
+    refusal = sandbox.check_source(source)
+    if refusal is not None:
+        # An older version that today's sandbox refuses. The person is told which version and why,
+        # rather than being handed a 400 about code they did not just type.
+        raise err(400, refusal.code, f"version {want} cannot be restored: {refusal.message}")
+    def _mutate(prior):
+        prior = dict(prior or rec)
+        history_now = list(prior.get("history") or [])
+        history_now.append({"version": int(prior.get("version") or 1),
+                            "source": prior.get("source") or "",
+                            "author": prior.get("author") or "",
+                            "created": prior.get("updated") or ""})
+        dropped = max(0, len(history_now) - MAX_HISTORY)
+        prior["history"] = history_now[dropped:] if dropped else history_now
+        prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
+        prior["source"] = source
+        prior["version"] = int(prior.get("version") or 1) + 1
+        prior["updated"] = _now()
+        # ⚠ ON THE RECORD, so the history reads as WHAT HAPPENED rather than as a version that
+        # mysteriously matches an older one. Without it a reader sees v5 and v2 with identical
+        # code and no way to tell a revert from a coincidence.
+        prior["restoredFrom"] = want
+        return prior
+    _put(session, view_id, _mutate)
+    fresh = _all(session.runtime).get(view_id)
+    if not isinstance(fresh, dict):
+        raise err(503, "store_unavailable", "the roll-back was NOT saved")
+    return {"view": _row(fresh, source=True), "restoredFrom": want, "limits": _limits()}
+@router.delete("/script-views/{view_id}")
+def delete_script_view(view_id: str, session: Session = Depends(require_session)):
+    view_id = str(view_id)
+    rec = _all(session.runtime).get(view_id)
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    _mine_or_admin(session, rec)
+    _put(session, view_id, lambda _prior: None)
+    return {"deleted": view_id}
+@router.post("/script-views/{view_id}/run")
+def run_script_view(view_id: str, body: dict = Body(default=None),
+                    session: Session = Depends(require_session)):
+    """CONTRACT C3's run door: `{ok, spec | error, stdout, ms}`.
+    ⛔ `spec` IS A DESCRIPTION THE CLIENT DRAWS. It is never HTML and never text the browser
+    executes — the sandbox refuses a spec carrying an `html`, `script`, `src`, `href` or `on*` key
+    before this function ever sees it, so a renderer cannot be talked into running something by a
+    script that was itself perfectly well behaved.
+    ⛔ AND IT IS PLAIN `def`, NOT `async def` — see this module's header. A ten-second subprocess
+    wait on the event loop is a ten-second outage for the whole container.
+    """
+    import core.script_sandbox as sandbox                                    # noqa: PLC0415
+    rec = _all(session.runtime).get(str(view_id))
+    if not isinstance(rec, dict):
+        raise err(404, "no_view", "there is no script view with that id")
+    database = str(rec.get("database") or "")
+    # A DRAFT run: the editor sends unsaved code so the author can try it before committing to it.
+    # It is checked exactly as a stored one is, because "unsaved" is not a permission.
+    draft = (body or {}).get("source") if isinstance(body, dict) else None
+    source = _clean_source(draft) if draft else str(rec.get("source") or "")
+    # ⚠ NO `_database_ok` CALL HERE. `run_view` asks C1 the identical question a line later, and
+    # asking twice builds a registry topic's pool twice. The three refusals are translated below
+    # instead, which is the same wall reached through the same door.
+    if not _RUN_SLOTS.acquire(blocking=False):
+        raise err(429, "busy",
+                  f"{MAX_CONCURRENT_RUNS} script views are already running on this server. "
+                  f"Try again in a moment")
+    try:
+        out = sandbox.run_view(session.user, database, source, st=session.runtime)
+    finally:
+        _RUN_SLOTS.release()
+    # ⛔ C1'S THREE REFUSALS ARE HTTP STATUSES, NOT `ok:false`. "You may not read this database"
+    # answered 200 would be a permission decision the client has to go looking for, and every
+    # other door in this app answers 403 for it. Everything BELOW this line is a well-formed
+    # request whose ANSWER is that the script did not produce a view — that is a 200 with
+    # `ok:false`, the shape `routes_web_agent.test` already uses for the same reason.
+    if out.get("code") == "unknown_table":
+        raise err(404, "no_database", out.get("message") or f"there is no database '{database}'")
+    if out.get("code") == "denied":
+        raise err(403, "forbidden", out.get("message") or "your account may not read that database")
+    if out.get("code") == "unresolvable":
+        refusal = err(409, "unresolvable", out.get("message") or "these rows cannot be served")
+        refusal.detail["error"]["limit"] = out.get("limit") or {}
+        raise refusal
+    answer = {"ok": bool(out.get("ok")), "spec": out.get("spec"),
+              "stdout": out.get("stdout") or "", "truncated": bool(out.get("truncated")),
+              "ms": int(out.get("ms") or 0), "code": out.get("code") or "",
+              # ⭐ `caps` RIDES ON THE ANSWER (standing rule 1). On a POSIX host all three limits
+              # were applied; on a Windows host the memory and CPU ones were not, and a screen
+              # that claims an enforcement which did not happen is the failure the rule is about.
+              "caps": out.get("caps") or {}}
+    if not answer["ok"]:
+        answer["error"] = out.get("message") or "the script view did not produce a view"
+    return answer

api/routes_shares.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_slack.py CHANGED Viewed

@@ -1,789 +1,789 @@
-"""routes_slack.py — MANAGE AGENT: a bot per Slack channel, walled by the engine that walls a
-person. (wave 33, owner item 10 · `W33-T38` / `W33-T39` / `W33-T67`.)
-Owner, verbatim (2026-08-14): *"Expand Slack we need to be able to configure an AI bot PER channel
-whose permissions we can toggle based on Fields etc of the databases, exactly like how we toggle
-permissioning per user."*
-────────────────────────────────────────────────────────────────────────────────────────────────
-⛔⛔ D-84 SAID THIS WAS "adapted from OpenTag" AND THAT PREMISE IS FALSE (PRD amendment A1).
-`PENDING.md` D-84 has named OpenTag as the model for per-Slack-channel permissioning since
-2026-08-08. **OpenTag has no permission model to adapt.** `app/runtime-host.ts` is
-`identifyUser: () => OPENTAG_SERVICE_USER` — ONE constant identity for every request — and its own
-`sender-context.ts` says the Slack sender is *"informational only… not gating access."* Its
-authorization ceiling is whole-MCP-server, decided once at process boot from env vars. It is a
-live specimen of identity that LOOKS like a permission and is not.
-`core/perm_scope.py` is already strictly more expressive: per database, per row, per FIELD, per
-principal. So item 10 is OUR engine projected onto a CHANNEL principal — see `agent_principal`
-below, which is the whole projection and is nine lines. Study:
-`.claude/wiki/research/opentag-adoption.md` (licence gate: MIT, PASSED).
-What OpenTag genuinely contributes is the WRITE-APPROVAL interceptor (`W33-T67`, `approval_card`
-below) and nothing else. Its TRANSPORT is AVOID wholesale — hosted CopilotKit Intelligence, a
-second Node process, a persistent outbound socket and each tenant's Slack credentials held by a
-third party, against ONE process on the HF free tier. The door here is `routes_forms.py`'s proven
-unauthenticated-public shape plus Slack's signing-secret check.
-────────────────────────────────────────────────────────────────────────────────────────────────
-⚠ A CHANNEL IS A PRINCIPAL, NOT A PERSON. The wall binds to the Slack conversation id, so every
-human in that channel reads through the same rules. That is the honest reading of "a bot per
-channel" and the pane says it out loud, because the alternative is an admin assuming per-person
-scoping from a screen that looks exactly like the per-person one.
-⚠ AND THE IDENTITY IS THE CHANNEL ID, NEVER ITS NAME. A channel can be renamed; its id cannot.
-A wall bound to `#sales` silently re-points the day somebody renames the channel.
-"""
-import hmac
-import json
-import os
-import secrets
-import time
-from datetime import datetime, timezone
-from fastapi import APIRouter, Body, Depends, Request
-from deps import Session, err, require_session
-from routes_admin import admin_gate
-router = APIRouter(prefix="/api/v1")
-#: The tenant's channel agents: `{id: record}`. A per-tenant bucket, so it rides
-#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace.
-AGENTS_KEY = "slack_agents"
-#: Pending mutations awaiting a human's click (`W33-T67`). Server-only, per tenant.
-PENDING_KEY = "slack_pending_writes"
-#: How long an approval card stays clickable. An approval is a statement about the world as it was
-#: when the card was rendered; an hour later the values it names may no longer be the values it
-#: would write. Expiring is the honest behaviour, and an expired card says so rather than 403ing.
-APPROVAL_TTL_S = 15 * 60
-#: Slack rejects a replayed request older than 5 minutes; so do we, before any signature work.
-SLACK_MAX_SKEW_S = 60 * 5
-MAX_BODY_BYTES = 64 * 1024
-#: ⛔ ROW-CAPPED BECAUSE AN APPROVER WHO CANNOT READ THE CARD CANNOT APPROVE IT. Copied
-#: deliberately from OpenTag's `agent/write_confirmation.py`, which caps for the same reason:
-#: past a certain length Slack collapses a message behind "Show more", and a human clicking
-#: Approve on a card whose tail they never saw is worse than no card at all.
-APPROVAL_MAX_ROWS = 12
-# ── the tenant's agent records ───────────────────────────────────────────────────────────────
-def _agents(rt):
-    """`{id: record}` for one tenant. `{}` on any failure — an unreadable bucket must degrade to
-    "this tenant has no agents", never to a 500 on the settings pane."""
-    try:
-        found = rt.get(AGENTS_KEY) or {}
-    except Exception:                                                        # noqa: BLE001
-        return {}
-    return found if isinstance(found, dict) else {}
-def _clean_agent(raw, prior=None):
-    """One stored record, built KEY BY KEY.
-    ⛔ Never `dict(raw)` and never `**raw`. This record is the SUBJECT of a permission decision;
-    a client-supplied key landing in it is a client-supplied input to `perm_scope`. The same rule
-    `routes_forms._public_form` follows on the way out, applied here on the way in.
-    """
-    prior = prior if isinstance(prior, dict) else {}
-    out = {
-        "id": str(prior.get("id") or raw.get("id") or ""),
-        "channel": str(raw.get("channel") or prior.get("channel") or "").strip()[:64],
-        "channelName": str(raw.get("channelName") or prior.get("channelName") or "").strip()[:80],
-        "label": " ".join(str(raw.get("label") or prior.get("label") or "").split())[:80],
-        "active": bool(raw.get("active", prior.get("active", True))),
-        # ⛔ DEFAULT TRUE, AND `is not False` RATHER THAN TRUTHINESS. A record written before this
-        # key existed must read as "approval required": the one direction a default here is
-        # allowed to be wrong in is the safe one, because an unattended write cannot be undone by
-        # revoking the bot afterwards [[default-must-pass-its-own-guard]].
-        "writeApproval": raw.get("writeApproval", prior.get("writeApproval", True)) is not False,
-        # The permission block. Same shape, same validator, same engine as a user's.
-        "perms": prior.get("perms") if isinstance(prior.get("perms"), dict) else {},
-        "perms_v": int(prior.get("perms_v") or 0),
-        "createdBy": str(prior.get("createdBy") or raw.get("createdBy") or ""),
-        "createdAt": str(prior.get("createdAt") or raw.get("createdAt") or ""),
-    }
-    return out
-def _put_agent(session, agent_id, mutate):
-    """Read-modify-write ONE agent under the tenant's bucket, synchronously.
-    `flush="sync"` because the client re-reads the list immediately after every write here, and an
-    async flush would let the refetch win the race and paint the pre-write state — the
-    [[refetch-eats-its-own-write]] shape.
-    """
-    def _set(cur):
-        cur = dict(cur or {})
-        rec = cur.get(agent_id) if isinstance(cur.get(agent_id), dict) else None
-        nxt = mutate(rec)
-        if nxt is None:
-            cur.pop(agent_id, None)
-        else:
-            cur[agent_id] = nxt
-        return cur
-    session.runtime.update(AGENTS_KEY, _set, flush="sync")
-# ── ⭐⭐ THE PROJECTION — THE WHOLE OF "the same engine that permissions a user" ───────────────
-def agent_principal(agent):
-    """A channel agent, as a PRINCIPAL `core/perm_scope` already understands.
-    ⭐⭐ THIS IS THE ENTIRE POINT OF THE TICKET AND IT IS NINE LINES. `perm_scope` takes a user
-    RECORD — a plain dict with `perms`, `perms_v` and `role` — not a User object and not a session.
-    So a channel agent carrying a `perms` block simply IS such a record, and `may_access`,
-    `visible_fields`, `hidden_keys` and `apply_row_scope` work on it unmodified. There is no second
-    engine, no parallel vocabulary, and nothing about a channel to keep in step with anything about
-    a person. That is what the owner's *"exactly like how we toggle permissioning per user"* means
-    when it is true in code rather than in appearance.
-    ⛔ `role` IS HARDCODED NON-ADMIN AND MUST STAY SO. `perm_scope.may_access` returns True
-    unconditionally for `role == 'admin'` — the break-glass clause that keeps the owner out of a
-    locked store. A bot has no such emergency and no hands: an agent record that could carry
-    `role: 'admin'` would be one stored key away from bypassing every wall on this page. The key is
-    not copied from the record; it is written here, every time.
-    ⛔ AND `perms_v` IS FORCED TO THE CURRENT VERSION, which makes an UNDECLARED database DENY
-    (C-PERM amendment 4). Without it a fresh agent would fall through to `perms.may_open`'s legacy
-    grant wall and read `modules: 'all'`-shaped defaults — i.e. a brand-new bot would start with
-    access to everything. Fail-closed from the first byte.
-    """
-    import core.perm_scope as perm_scope
-    return {
-        "username": f"slack:{(agent or {}).get('channel') or '?'}",
-        "role": "agent",
-        "perms": (agent or {}).get("perms") or {},
-        "perms_v": perm_scope.PERMS_VERSION,
-        # No `bus`, no `agent`: a channel is not a business unit and not a salesperson. Absent
-        # rather than 'all' — `perms.allowed_bu_labels` narrows on absence, which is the direction
-        # this must fail in.
-    }
-def agent_may_read(agent, module):
-    """May this channel open `module` at all?"""
-    import core.perm_scope as perm_scope
-    if not (agent or {}).get("active", True):
-        return False
-    return bool(perm_scope.may_access(agent_principal(agent), module))
-def agent_visible_fields(agent, fields, module):
-    """`fields` minus this channel's hidden closure — the SAME transitive closure a person gets,
-    so a formula over a hidden column cannot leak it back through arithmetic."""
-    import core.perm_scope as perm_scope
-    return perm_scope.visible_fields(fields, agent_principal(agent), module)
-def agent_rows(agent, rows, module, fields, ctx=None, st=None):
-    """The rows this channel may receive — `permits()`, so an unanswerable permanent filter DENIES
-    rather than being ignored.
-    ⭐⭐ `st` IS THE TENANT HANDLE AND IT IS HERE BECAUSE OF THE SENTENCE IN `agent_principal`:
-    a channel agent IS a principal of the same wall, so a permanent filter naming a
-    user-generated column has to mean the SAME thing here as it does on the grid (owner I16).
-    A door that lends the handle and a door that does not are one stored rule with two meanings.
-    ⚠ PASS THE TENANT'S OWN RUNTIME — every other store read in this file takes
-    `session.runtime`, and a channel is not a second tenancy. It is a keyword with a `None`
-    default for the same reason `perm_scope.apply_row_scope`'s is: without one this is
-    byte-identical to the wall that shipped before the argument existed.
-    ⚠ `hidden_keys` DELIBERATELY DOES NOT TAKE IT IN THIS CHANGE. Its field-grant leg
-    under-hides without a handle (see `perm_scope.visible_overlays`), which is a real and
-    separate gap on this surface — but it is the FIELD wall, it moves what a channel receives
-    rather than what I16 asked for, and widening two walls in one ticket is how a permission
-    change stops being reviewable.
-    """
-    import core.perm_scope as perm_scope
-    p = agent_principal(agent)
-    hide = perm_scope.hidden_keys(p, module, fields)
-    kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx, st=st)
-    # Both wires, never one: the field list and the row payload are separate, and stripping only
-    # the first leaves the value sitting in the second where anyone can read it.
-    return [perm_scope.strip_row(r, hide) for r in kept]
-# ── the credential ───────────────────────────────────────────────────────────────────────────
-def slack_creds(rt):
-    """This TENANT's Slack credentials from its own keychain, or None.
-    ⛔ NO ENVIRONMENT FALLBACK, DELIBERATELY, AND THIS IS D-202's LESSON APPLIED BEFORE IT
-    HAPPENS AGAIN. Meta Ads shipped loading end-to-end and was still not a connector, because
-    `keychain.meta_creds` had no caller and the token came from the owner's `.env` — making it a
-    tenant-#0 FACT indistinguishable from a screenshot. `keychain.meta_creds`' own docstring spells
-    out the rule: handing the environment's credential to a tenant whose admin has not stored one
-    is the leak the resolver exists to prevent. So a tenant with no entry gets None and the pane
-    SAYS so.
-    ⚠ Reads through `list_entries` + `read_fields` (both public) rather than `keychain._first_creds`
-    (private, and in a file outside this lane's fence). Same deterministic rule: entries are
-    id-sorted, so "first" is stable across reads rather than dict-order luck.
-    """
-    try:
-        import core.keychain as keychain
-        for row in keychain.list_entries(rt):
-            if str(row.get("type") or "") != "slack":
-                continue
-            fields = keychain.read_fields(rt, row.get("id"))
-            if isinstance(fields, dict) and fields.get("signing_secret"):
-                return fields
-    except Exception:                                                        # noqa: BLE001
-        # A locked or unreadable keychain reads as "not configured" for the PANE, which is honest;
-        # the signature check below fails closed regardless, so this cannot widen anything.
-        return None
-    return None
-# ── the authenticated doors (the Manage agent surface) ───────────────────────────────────────
-def _summary(agent, modules):
-    """One sentence per agent for the list row — computed here, because the alternative is one
-    round trip per row to fill one cell (the same reason `AdminUser.access` exists)."""
-    # ⭐ W36-T22 / C2 — every listed database is governed now; the `enforced` flag it used to
-    # filter on is DELETED, and `m.get("enforced")` would have gone silently falsy here and
-    # summarised every agent as "" (no databases at all).
-    governed = list(modules)
-    perms = agent.get("perms") or {}
-    open_n = sum(1 for m in governed if (perms.get(m["key"]) or {}).get("access"))
-    if not governed:
-        return ""
-    if open_n == 0:
-        return "No access"
-    restricted = sum(1 for m in governed
-                     if (perms.get(m["key"]) or {}).get("access")
-                     and ((perms.get(m["key"]) or {}).get("filter")
-                          or (perms.get(m["key"]) or {}).get("hiddenFields")))
-    head = (f"All {open_n} database{'' if open_n == 1 else 's'}" if open_n == len(governed)
-            else f"{open_n} of {len(governed)} databases")
-    return f"{head}, {restricted} restricted" if restricted else head
-@router.get("/agents")
-def list_channel_agents(session: Session = Depends(admin_gate)):
-    """This tenant's channel agents, plus whether Slack is reachable at all."""
-    import routes_admin
-    modules = routes_admin._perm_modules(session)
-    rows = []
-    for aid, a in sorted(_agents(session.runtime).items()):
-        if not isinstance(a, dict):
-            continue
-        rows.append({"id": aid, "channel": a.get("channel") or "",
-                     "channelName": a.get("channelName") or "",
-                     "label": a.get("label") or "", "active": a.get("active", True) is not False,
-                     "writeApproval": a.get("writeApproval", True) is not False,
-                     "summary": _summary(a, modules)})
-    return {"agents": rows, "configured": slack_creds(session.runtime) is not None}
-@router.post("/agents")
-def create_channel_agent(body: dict = Body(default=None),
-                         session: Session = Depends(admin_gate)):
-    body = body if isinstance(body, dict) else {}
-    channel = str(body.get("channel") or "").strip()
-    if not channel:
-        raise err(400, "no_channel", "a Slack channel ID is required")
-    existing = _agents(session.runtime)
-    # ⚠ ONE AGENT PER CHANNEL. Two records for one conversation would mean two walls, and nothing
-    # anywhere decides which one applies — the [[one-question-two-normalizers]] shape, in the one
-    # place where the two answers are "may read" and "may not".
-    for a in existing.values():
-        if isinstance(a, dict) and str(a.get("channel") or "") == channel:
-            raise err(409, "channel_taken",
-                      "that channel already has an agent — edit it instead of adding a second")
-    aid = secrets.token_urlsafe(9)
-    rec = _clean_agent(dict(body, id=aid, createdBy=session.uname,
-                            createdAt=datetime.now(timezone.utc).isoformat(timespec="seconds")))
-    _put_agent(session, aid, lambda _prior: rec)
-    fresh = _agents(session.runtime).get(aid)
-    if not isinstance(fresh, dict):
-        # The store took the write and did not record it. A 200 here would tell an administrator
-        # the agent exists when it does not.
-        raise err(503, "store_unavailable", "the agent was NOT created")
-    return {"agent": {"id": aid, "channel": rec["channel"], "channelName": rec["channelName"],
-                      "label": rec["label"], "active": rec["active"],
-                      "writeApproval": rec["writeApproval"], "summary": "No access"}}
-@router.get("/agents/{agent_id}")
-def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
-    """The agent PLUS the permission envelope — the SAME shape `get_perms` answers with.
-    ⭐ ONE PAYLOAD SHAPE FOR TWO ROOMS. `permsModel.parsePermsPayload` parses this, and
-    `settings/ModulePermsList` renders it, because they are literally the same client code. A
-    second envelope here would mean a second parser and a second set of defaults within a wave.
-    """
-    import routes_admin
-    a = _agents(session.runtime).get(str(agent_id))
-    if not isinstance(a, dict):
-        raise err(404, "no_such_agent", "no agent with that id")
-    modules = routes_admin._perm_modules(session)
-    # ⭐⭐ W36-T22 / C2 — EVERY listed database, `ut_*` included. ⛔ THIS IS WHY THE FLAG'S
-    # DELETION IS NOT A ONE-FILE CHANGE: `m.get("enforced")` on a row that no longer carries the
-    # key is None, so this list would have been EMPTY and the channel perms editor would have
-    # governed ZERO databases while looking entirely correct. A Slack channel is a principal of
-    # the SAME wall (`verify_perm_scope` section H) and gets the same catalogue.
-    governed = [m["key"] for m in modules]
-    stored = a.get("perms") or {}
-    principal = agent_principal(a)
-    import core.perm_scope as perm_scope
-    perms_out = {}
-    for k in governed:
-        e = stored.get(k)
-        # ⛔ W36-T22 — `may_read`, the same evaluator the read door uses, for the reason spelled
-        # out at `routes_admin.get_perms`. ⚠ It answers DIFFERENTLY here and correctly so: a
-        # channel agent is not a person with a share, so a `ut_*` key it has not been granted
-        # defaults CLOSED — which is the fail-closed direction for a bot, and the same answer the
-        # table routes would give it.
-        perms_out[k] = e if isinstance(e, dict) else {
-            "access": bool(perm_scope.may_read(principal, k, st=session.runtime)),
-            "filter": None, "hiddenFields": []}
-    return {"id": str(agent_id), "channel": a.get("channel") or "",
-            "channelName": a.get("channelName") or "", "label": a.get("label") or "",
-            "active": a.get("active", True) is not False,
-            "writeApproval": a.get("writeApproval", True) is not False,
-            "perms": perms_out,
-            # ⛔ ALWAYS THE CURRENT VERSION, because `agent_principal` forces it: the editor must
-            # render "undeclared = denied", not the legacy-grant reading it would show at 0.
-            "perms_v": perm_scope.PERMS_VERSION,
-            # A bot is NEVER an admin — see `agent_principal`. Sent so the editor never paints
-            # the "Everything (admin)" state for a principal that cannot have it.
-            "is_admin": False,
-            "modules": modules,
-            "fields_by_module": {k: routes_admin._module_fields(k, session=session)
-                                 for k in governed}}
-@router.put("/agents/{agent_id}/perms")
-def put_channel_agent_perms(agent_id: str, body: dict = Body(default=None),
-                            session: Session = Depends(admin_gate)):
-    """Replace this agent's permission block wholesale — the same validator a user's block gets."""
-    import routes_admin
-    body = body if isinstance(body, dict) else {}
-    if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
-        raise err(404, "no_such_agent", "no agent with that id")
-    if "perms" not in body:
-        raise err(400, "empty_patch", "no perms to save")
-    mods = routes_admin._perm_modules(session)
-    # ⭐ THE SAME `_clean_perms`, NOT A COPY OF IT. It refuses a filter this module cannot
-    # evaluate, refuses a hiddenFields key that names nothing, and refuses a BU condition the
-    # pushdown cannot read. Every one of those is exactly as true for a channel as for a person,
-    # and a second validator here is a second place for one of them to go missing.
-    # ⚠ CORRECTED W36-T22: this list used to end "refuses an unenforced `ut_*` key". That refusal
-    # is DELETED — W36-T21 armed the wall over every database, so there is no unenforced key left
-    # to refuse, and a comment naming a rule that no longer exists is how the next wave re-derives
-    # it ([[two-gates-can-assert-opposite-things]]).
-    cleaned = routes_admin._clean_perms(
-        body.get("perms"),
-        governed_keys={m["key"] for m in mods}, session=session) or {}
-    import core.perm_scope as perm_scope
-    def _mut(prior):
-        if not isinstance(prior, dict):
-            return None
-        nxt = dict(prior)
-        nxt["perms"] = cleaned
-        nxt["perms_v"] = perm_scope.PERMS_VERSION
-        return nxt
-    _put_agent(session, str(agent_id), _mut)
-    fresh = _agents(session.runtime).get(str(agent_id)) or {}
-    if (fresh.get("perms") or {}) != cleaned:
-        # The one direction this must never fail in: telling an administrator the wall is up when
-        # it is not.
-        raise err(503, "store_unavailable", "the permissions were not saved — the agent is UNCHANGED")
-    return {"id": str(agent_id), "perms": fresh.get("perms") or {},
-            "perms_v": int(fresh.get("perms_v") or 0)}
-@router.patch("/agents/{agent_id}")
-def patch_channel_agent(agent_id: str, body: dict = Body(default=None),
-                        session: Session = Depends(admin_gate)):
-    body = body if isinstance(body, dict) else {}
-    if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
-        raise err(404, "no_such_agent", "no agent with that id")
-    #: ⛔ `perms` IS NOT PATCHABLE HERE. It has its own door with its own validator; accepting it
-    #: on the metadata route would be a second, unvalidated way to write the wall.
-    allowed = {k: v for k, v in body.items()
-               if k in ("label", "active", "writeApproval", "channelName")}
-    if not allowed:
-        raise err(400, "empty_patch", "nothing to change")
-    def _mut(prior):
-        return _clean_agent(allowed, prior=prior) if isinstance(prior, dict) else None
-    _put_agent(session, str(agent_id), _mut)
-    import routes_admin
-    a = _agents(session.runtime).get(str(agent_id)) or {}
-    return {"agent": {"id": str(agent_id), "channel": a.get("channel") or "",
-                      "channelName": a.get("channelName") or "", "label": a.get("label") or "",
-                      "active": a.get("active", True) is not False,
-                      "writeApproval": a.get("writeApproval", True) is not False,
-                      "summary": _summary(a, routes_admin._perm_modules(session))}}
-@router.delete("/agents/{agent_id}")
-def delete_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
-    if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
-        raise err(404, "no_such_agent", "no agent with that id")
-    _put_agent(session, str(agent_id), lambda _prior: None)
-    if isinstance(_agents(session.runtime).get(str(agent_id)), dict):
-        raise err(503, "store_unavailable", "the agent was NOT removed")
-    return {"ok": True}
-# ── ⭐ W33-T67: THE WRITE-APPROVAL GATE ───────────────────────────────────────────────────────
-def _is_empty(value):
-    """Is this value ABSENT, as opposed to falsy?
-    ⛔ COPIED EXACTLY FROM OpenTag's `agent/write_confirmation.py`, and the exactness is the point:
-    `0` and `False` are VALUES a human must see on the card. Setting a price to 0 or a flag to
-    False is precisely the kind of write somebody needs to approve, and a naive `if not value`
-    drops both rows silently — the approver then reads a card that does not describe the write
-    they are approving. The MIT licence gate for this borrowing is recorded in
-    `.claude/wiki/research/opentag-adoption.md`.
-    """
-    return value is None or (isinstance(value, str) and value.strip() == "")
-def approval_card(action, values, agent=None):
-    """The card a human reads before a bot writes. `{action, rows, truncated, note}`.
-    ⛔ ROW-CAPPED, and the cap is a SAFETY property rather than a layout one: past a certain
-    length Slack collapses a message behind "Show more", and **an approver who cannot read the
-    card cannot approve it.** When rows are dropped the card SAYS how many — a truncation nobody
-    was told about is the violation, not the truncation (wave-30 R6's second sentence).
-    """
-    rows = [{"field": str(k), "value": v}
-            for k, v in (values or {}).items() if not _is_empty(v)]
-    rows.sort(key=lambda r: r["field"])
-    shown, dropped = rows[:APPROVAL_MAX_ROWS], max(0, len(rows) - APPROVAL_MAX_ROWS)
-    return {
-        "action": str(action or "")[:80],
-        "rows": shown,
-        "truncated": dropped,
-        "note": (f"{dropped} more field(s) not shown — open the record to review them before "
-                 f"approving." if dropped else ""),
-        "agent": (agent or {}).get("label") or (agent or {}).get("channel") or "",
-    }
-def intercept_write(agent, action, values, stash):
-    """THE INTERCEPTOR. Returns `("commit", None)` or `("await_approval", card)`.
-    ⭐ The one thing worth taking from OpenTag: a MUTATING tool call is halted, rendered as a card
-    naming the action and its values, and committed only on an explicit human accept. Everything
-    else in that repo — the transport, the runtime, the identity model — is AVOID (amendment A1).
-    ⛔ FAIL-CLOSED ON A MISSING FLAG: `is not False`, so a record written before `writeApproval`
-    existed requires approval. The unsafe direction here is not recoverable — revoking a bot does
-    not un-write what it wrote.
-    """
-    if (agent or {}).get("writeApproval", True) is not False:
-        card = approval_card(action, values, agent)
-        stash(card)
-        return "await_approval", card
-    return "commit", None
-def _pending(rt):
-    try:
-        found = rt.get(PENDING_KEY) or {}
-    except Exception:                                                        # noqa: BLE001
-        return {}
-    return found if isinstance(found, dict) else {}
-def stash_pending(rt, agent, action, values, now=None):
-    """Store one awaiting-approval mutation and return its token.
-    The token is what rides the card's button, so it is `secrets.token_urlsafe` and not the
-    action's id: a guessable value on an unauthenticated door is a way to approve somebody else's
-    write. Server-only bucket, per tenant, exactly as `routes_forms.TOKENS_KEY` is.
-    """
-    token = secrets.token_urlsafe(18)
-    row = {"at": float(now if now is not None else time.time()),
-           "channel": str((agent or {}).get("channel") or ""),
-           "action": str(action or "")[:80],
-           "values": values if isinstance(values, dict) else {}}
-    rt.update(PENDING_KEY, lambda cur: {**(cur or {}), token: row}, flush="sync")
-    return token
-#: `{action kind: fn(rt, row) -> None}`. Registered by whatever can actually perform a mutation.
-#:
-#: ⛔⛔ EMPTY IN PRODUCTION TODAY, AND SAYING SO IS THE POINT. `commit_pending` below is the ONE
-#: place an approved write may be performed, so it is the place a negative control can bite — but
-#: a gate is only as honest as what it guards. Until something registers here, an approved card
-#: performs NOTHING and `commit_pending` returns `no_committer` rather than pretending. That is a
-#: declared absence, not a silent one [[flag-shipped-without-its-writer]].
-_COMMITTERS = {}
-def register_committer(kind, fn):
-    """Declare who may perform an approved mutation of `kind`. Idempotent by key."""
-    _COMMITTERS[str(kind)] = fn
-def commit_pending(rt, token, approved, now=None):
-    """Resolve ONE approval card. Returns one of
-    `expired` · `unknown` · `rejected` · `no_committer` · `committed` · `failed`.
-    ⛔⛔ THIS IS THE WRITE GATE, AND IT IS A SEPARATE FUNCTION FROM THE ROUTE ON PURPOSE. T67's
-    `done-when` asks for an NC proving a REJECTED card writes nothing. A control aimed at the
-    route could not bite while the route had no write in it at all — it would stay green with the
-    guard deleted, because there would be nothing for the guard to be protecting anything from
-    ([[gate-can-report-green-on-nothing]], and a verifier caught exactly that on this ticket's
-    first draft). Putting the commit behind ONE named seam gives the control a real subject: the
-    gate registers a recorder, and `rejected` must leave it untouched while `approve` must call it
-    exactly once.
-    ⛔ THE TOKEN IS CONSUMED BEFORE EITHER BRANCH, and before any committer runs. A card that
-    survives its own click is a replayable write, and "approve twice" must never mean "write
-    twice". The delete is `flush="sync"` for the same reason.
-    """
-    now = float(now if now is not None else time.time())
-    row = _pending(rt).get(str(token))
-    if not isinstance(row, dict):
-        return "unknown"
-    # Consume FIRST — before the TTL verdict, before the approve/reject branch, before any write.
-    rt.update(PENDING_KEY,
-              lambda cur: {k: v for k, v in (cur or {}).items() if k != str(token)},
-              flush="sync")
-    if now - float(row.get("at") or 0) > APPROVAL_TTL_S:
-        return "expired"
-    if not approved:
-        # ⛔ NOTHING BELOW THIS LINE RUNS FOR A REJECTED CARD. The whole gate is this return.
-        return "rejected"
-    fn = _COMMITTERS.get(str(row.get("action") or ""))
-    if fn is None:
-        return "no_committer"
-    try:
-        fn(rt, row)
-    except Exception:                                                        # noqa: BLE001
-        # A committer that raises must not read as a commit. The card is already consumed, so the
-        # honest report is that it failed, and the human asks again.
-        return "failed"
-    return "committed"
-# ── the UNAUTHENTICATED Slack door ───────────────────────────────────────────────────────────
-#: Sliding window, keyed on the SLACK TEAM, never the client IP.
-#:
-#: ⛔ WHY NOT THE IP, WHICH IS WHAT `routes_forms` DOES. Every Slack event arrives from Slack's own
-#: infrastructure, so an IP window is one shared bucket for every workspace on the platform: one
-#: busy tenant would spend the allowance for all of them, and the symptom would be another
-#: tenant's bot going quiet. The team id is the closest thing to the actual noisy party.
-#: ⚠ It is attacker-CONTROLLED before the signature is checked, so the window is applied AFTER
-#: verification, never before — an unsigned request is refused on cost grounds anyway (a signature
-#: check is a single HMAC).
-RATE_WINDOW_S, RATE_PER_WINDOW = 60, 60
-_HITS: dict = {}
-def _rate_ok(key, now):
-    seen = [t for t in _HITS.get(key, ()) if now - t < RATE_WINDOW_S]
-    seen.append(now)
-    _HITS[key] = seen
-    if len(_HITS) > 4096:
-        for k in [k for k, v in _HITS.items() if not v or now - v[-1] > RATE_WINDOW_S]:
-            _HITS.pop(k, None)
-    return len(seen) <= RATE_PER_WINDOW
-async def _raw_body(request):
-    """The body as RAW BYTES, capped.
-    ⛔⛔ RAW, NOT PARSED, AND THAT IS NOT A STYLE CHOICE. Slack signs the literal string
-    `v0:{timestamp}:{body}` byte for byte. `routes_forms._bounded_body` — the function this is
-    otherwise copied from — returns only the parsed dict and DISCARDS the bytes, so a verbatim
-    copy of it could not verify a Slack signature at all: re-serialising the dict changes
-    whitespace and key order and the HMAC no longer matches. The bug would look like "Slack
-    signatures are always invalid", which is indistinguishable from a wrong secret.
-    ⚠ And it streams rather than calling `request.body()`: FastAPI would otherwise have buffered
-    the whole body before the handler's first line, so a content-length check inside the handler
-    caps nothing (`routes_forms`' own scar, recorded in its docstring).
-    """
-    size, chunks = 0, []
-    async for chunk in request.stream():
-        size += len(chunk)
-        if size > MAX_BODY_BYTES:
-            raise err(413, "body_too_large", "that request is too large")
-        chunks.append(chunk)
-    return b"".join(chunks)
-def _refuse():
-    """ONE refusal for every reason. No oracle.
-    A wrong signature, a stale timestamp, an unknown team, an unconfigured tenant and a channel
-    with no agent all answer identically — otherwise the door tells an unauthenticated caller
-    which tenants exist and which channels are configured, which is the question it was built to
-    not answer. `routes_forms._refuse` takes the same posture for the same reason.
-    """
-    return err(403, "bad_request", "that request could not be verified")
-def _verify(secret, timestamp, raw, signature, now):
-    """Slack's v0 signature, with the replay window checked FIRST."""
-    try:
-        ts = int(str(timestamp or "0"))
-    except ValueError:
-        return False
-    if abs(now - ts) > SLACK_MAX_SKEW_S:
-        return False
-    base = b"v0:" + str(ts).encode("ascii") + b":" + (raw or b"")
-    import hashlib
-    expected = "v0=" + hmac.new(str(secret).encode("utf-8"), base, hashlib.sha256).hexdigest()
-    return hmac.compare_digest(expected, str(signature or ""))
-def _resolve_tenant(raw, timestamp, signature, now):
-    """`(slug, runtime, creds)` for the tenant whose signing secret verifies this request.
-    ⛔ THE TENANT IS DECIDED BY THE SIGNATURE, NEVER BY THE PAYLOAD. A body-supplied `team_id`
-    would let an unauthenticated caller name the tenant it wants to be — the exact widening
-    `deps._user_for`'s tenant-equality check closes on the authenticated side. So every configured
-    tenant's secret is tried and the one that VERIFIES names the tenant.
-    ⚠ NO EARLY `break` ON A FAILED CANDIDATE and no per-tenant error: the loop's cost must not
-    depend on which tenant matched. `routes_forms._resolve` walks tenants the same way, for the
-    same reason — a public door has no session to ask.
-    """
-    from harness import runtime as _rt
-    hit = None
-    try:
-        slugs = list(_rt.known_tenants())
-    except Exception:                                                        # noqa: BLE001
-        return None, None, None
-    for slug in slugs:
-        try:
-            rt = _rt.get_runtime(slug)
-        except Exception:                                                    # noqa: BLE001
-            continue
-        creds = slack_creds(rt)
-        if not creds:
-            continue
-        if _verify(creds.get("signing_secret"), timestamp, raw, signature, now) and hit is None:
-            hit = (slug, rt, creds)
-    return hit if hit else (None, None, None)
-@router.post("/slack/events")
-async def slack_events(request: Request):
-    """Slack's Events API. UNAUTHENTICATED BY CONSTRUCTION — no `Depends(require_session)`.
-    ⭐ Built like `routes_forms.py`'s public door and not like OpenTag's: one process, no vendor,
-    no second runtime, no persistent outbound socket, and this tenant's Slack secret never leaves
-    this deployment (amendment A1).
-    """
-    now = time.time()
-    raw = await _raw_body(request)
-    ts = request.headers.get("x-slack-request-timestamp")
-    sig = request.headers.get("x-slack-signature")
-    slug, rt, _creds = _resolve_tenant(raw, ts, sig, now)
-    if not rt:
-        raise _refuse()
-    try:
-        payload = json.loads(raw or b"{}")
-    except ValueError:
-        raise _refuse()
-    if not isinstance(payload, dict):
-        raise _refuse()
-    # Slack's one-time endpoint handshake. Answered ONLY after the signature verified — an
-    # unsigned challenge echo would confirm the endpoint exists to anyone who probes it.
-    if payload.get("type") == "url_verification":
-        return {"challenge": str(payload.get("challenge") or "")[:512]}
-    team = str(payload.get("team_id") or slug)
-    if not _rate_ok(f"{slug}:{team}", now):
-        raise err(429, "too_many_requests", "too many requests — wait a moment and try again")
-    event = payload.get("event") if isinstance(payload.get("event"), dict) else {}
-    channel = str(event.get("channel") or "")
-    agent = None
-    for a in _agents(rt).values():
-        if isinstance(a, dict) and str(a.get("channel") or "") == channel:
-            agent = a
-            break
-    # ⛔ NO AGENT, OR AN INACTIVE ONE, IS SILENCE — a 200 with no action. Not a 403: Slack retries
-    # a non-2xx up to three times, so refusing here would turn "this channel is not configured"
-    # into three refusals per message, and the retry storm would be the only visible symptom.
-    # ⚠ And it must not say WHICH — a distinguishable answer tells an unauthenticated caller which
-    # channels this workspace has configured.
-    if not isinstance(agent, dict) or agent.get("active", True) is False:
-        return {"ok": True}
-    # ⛔⛔ THE ANSWERING HALF IS NOT BUILT YET, AND SAYING SO IS THE POINT. What ships here is the
-    # DOOR and the WALL: a verified request, resolved to a tenant by signature, matched to a
-    # channel agent whose `perms` block is a `perm_scope` principal (`agent_principal`). Composing
-    # a reply means an LLM call on the cheap-first ladder plus the read path, and a half-built
-    # answerer that returns something plausible is worse than one that returns nothing.
-    # Booked rather than faked [[flag-shipped-without-its-writer]].
-    return {"ok": True}
-@router.post("/slack/interact")
-async def slack_interact(request: Request):
-    """The approval card's button (`W33-T67`). UNAUTHENTICATED, signature-verified, same shape."""
-    now = time.time()
-    raw = await _raw_body(request)
-    slug, rt, _creds = _resolve_tenant(raw, request.headers.get("x-slack-request-timestamp"),
-                                       request.headers.get("x-slack-signature"), now)
-    if not rt:
-        raise _refuse()
-    # Slack posts interactions as `application/x-www-form-urlencoded` with a `payload=` field.
-    from urllib.parse import parse_qs
-    try:
-        form = parse_qs(raw.decode("utf-8"))
-        payload = json.loads((form.get("payload") or ["{}"])[0])
-    except Exception:                                                        # noqa: BLE001
-        raise _refuse()
-    if not isinstance(payload, dict):
-        raise _refuse()
-    if not _rate_ok(f"{slug}:interact", now):
-        raise err(429, "too_many_requests", "too many requests — wait a moment and try again")
-    actions = payload.get("actions") if isinstance(payload.get("actions"), list) else []
-    choice = (actions[0] if actions and isinstance(actions[0], dict) else {})
-    token = str(choice.get("value") or "")
-    # ⭐ ANYTHING THAT IS NOT LITERALLY "approve" IS A REJECT. Fail-closed on a malformed,
-    # truncated or unknown action id: the direction that can be wrong here without anyone
-    # noticing is the one that writes.
-    approved = str(choice.get("action_id") or "") == "approve"
-    # ⛔ THE ROUTE DOES NOT DECIDE — `commit_pending` does, and it is the ONE seam a negative
-    # control can aim at. Consumption, the TTL, the reject branch and the committer lookup all
-    # live there; this handler only turns its verdict into a sentence.
-    verdict = commit_pending(rt, token, approved, now=now)
-    return {"text": {
-        # An unknown, already-used or expired token is not an error: a person clicking a stale
-        # card should be told it is stale, not shown a failure.
-        "unknown": "That approval is no longer available. Ask the bot again.",
-        "expired": "That approval expired before it was answered. Ask the bot again.",
-        "rejected": "Rejected. Nothing was changed.",
-        # ⚠ HONEST, not reassuring: the answering half that would register a committer is booked,
-        # so an approved card today performs nothing and says exactly that rather than "Approved."
-        "no_committer": "Approved — but this workspace has nothing configured to carry it out yet.",
-        "failed": "That change could not be completed. Nothing was saved; ask the bot again.",
-        "committed": "Approved.",
-    }.get(verdict, "That approval is no longer available. Ask the bot again.")}
-@router.get("/slack/health")
-def slack_health(session: Session = Depends(require_session)):
-    """Is Slack configured for THIS tenant? Session-gated, and it answers about one tenant only —
-    enumerating the others would answer a question about our customer list."""
-    creds = slack_creds(session.runtime)
-    return {"configured": creds is not None,
-            "agents": len(_agents(session.runtime)),
-            "hasBotToken": bool((creds or {}).get("bot_token"))}

+"""routes_slack.py — MANAGE AGENT: a bot per Slack channel, walled by the engine that walls a
+person. (wave 33, owner item 10 · `W33-T38` / `W33-T39` / `W33-T67`.)
+Owner, verbatim (2026-08-14): *"Expand Slack we need to be able to configure an AI bot PER channel
+whose permissions we can toggle based on Fields etc of the databases, exactly like how we toggle
+permissioning per user."*
+────────────────────────────────────────────────────────────────────────────────────────────────
+⛔⛔ D-84 SAID THIS WAS "adapted from OpenTag" AND THAT PREMISE IS FALSE (PRD amendment A1).
+`PENDING.md` D-84 has named OpenTag as the model for per-Slack-channel permissioning since
+2026-08-08. **OpenTag has no permission model to adapt.** `app/runtime-host.ts` is
+`identifyUser: () => OPENTAG_SERVICE_USER` — ONE constant identity for every request — and its own
+`sender-context.ts` says the Slack sender is *"informational only… not gating access."* Its
+authorization ceiling is whole-MCP-server, decided once at process boot from env vars. It is a
+live specimen of identity that LOOKS like a permission and is not.
+`core/perm_scope.py` is already strictly more expressive: per database, per row, per FIELD, per
+principal. So item 10 is OUR engine projected onto a CHANNEL principal — see `agent_principal`
+below, which is the whole projection and is nine lines. Study:
+`.claude/wiki/research/opentag-adoption.md` (licence gate: MIT, PASSED).
+What OpenTag genuinely contributes is the WRITE-APPROVAL interceptor (`W33-T67`, `approval_card`
+below) and nothing else. Its TRANSPORT is AVOID wholesale — hosted CopilotKit Intelligence, a
+second Node process, a persistent outbound socket and each tenant's Slack credentials held by a
+third party, against ONE process on the HF free tier. The door here is `routes_forms.py`'s proven
+unauthenticated-public shape plus Slack's signing-secret check.
+────────────────────────────────────────────────────────────────────────────────────────────────
+⚠ A CHANNEL IS A PRINCIPAL, NOT A PERSON. The wall binds to the Slack conversation id, so every
+human in that channel reads through the same rules. That is the honest reading of "a bot per
+channel" and the pane says it out loud, because the alternative is an admin assuming per-person
+scoping from a screen that looks exactly like the per-person one.
+⚠ AND THE IDENTITY IS THE CHANNEL ID, NEVER ITS NAME. A channel can be renamed; its id cannot.
+A wall bound to `#sales` silently re-points the day somebody renames the channel.
+"""
+import hmac
+import json
+import os
+import secrets
+import time
+from datetime import datetime, timezone
+from fastapi import APIRouter, Body, Depends, Request
+from deps import Session, err, require_session
+from routes_admin import admin_gate
+router = APIRouter(prefix="/api/v1")
+#: The tenant's channel agents: `{id: record}`. A per-tenant bucket, so it rides
+#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace.
+AGENTS_KEY = "slack_agents"
+#: Pending mutations awaiting a human's click (`W33-T67`). Server-only, per tenant.
+PENDING_KEY = "slack_pending_writes"
+#: How long an approval card stays clickable. An approval is a statement about the world as it was
+#: when the card was rendered; an hour later the values it names may no longer be the values it
+#: would write. Expiring is the honest behaviour, and an expired card says so rather than 403ing.
+APPROVAL_TTL_S = 15 * 60
+#: Slack rejects a replayed request older than 5 minutes; so do we, before any signature work.
+SLACK_MAX_SKEW_S = 60 * 5
+MAX_BODY_BYTES = 64 * 1024
+#: ⛔ ROW-CAPPED BECAUSE AN APPROVER WHO CANNOT READ THE CARD CANNOT APPROVE IT. Copied
+#: deliberately from OpenTag's `agent/write_confirmation.py`, which caps for the same reason:
+#: past a certain length Slack collapses a message behind "Show more", and a human clicking
+#: Approve on a card whose tail they never saw is worse than no card at all.
+APPROVAL_MAX_ROWS = 12
+# ── the tenant's agent records ───────────────────────────────────────────────────────────────
+def _agents(rt):
+    """`{id: record}` for one tenant. `{}` on any failure — an unreadable bucket must degrade to
+    "this tenant has no agents", never to a 500 on the settings pane."""
+    try:
+        found = rt.get(AGENTS_KEY) or {}
+    except Exception:                                                        # noqa: BLE001
+        return {}
+    return found if isinstance(found, dict) else {}
+def _clean_agent(raw, prior=None):
+    """One stored record, built KEY BY KEY.
+    ⛔ Never `dict(raw)` and never `**raw`. This record is the SUBJECT of a permission decision;
+    a client-supplied key landing in it is a client-supplied input to `perm_scope`. The same rule
+    `routes_forms._public_form` follows on the way out, applied here on the way in.
+    """
+    prior = prior if isinstance(prior, dict) else {}
+    out = {
+        "id": str(prior.get("id") or raw.get("id") or ""),
+        "channel": str(raw.get("channel") or prior.get("channel") or "").strip()[:64],
+        "channelName": str(raw.get("channelName") or prior.get("channelName") or "").strip()[:80],
+        "label": " ".join(str(raw.get("label") or prior.get("label") or "").split())[:80],
+        "active": bool(raw.get("active", prior.get("active", True))),
+        # ⛔ DEFAULT TRUE, AND `is not False` RATHER THAN TRUTHINESS. A record written before this
+        # key existed must read as "approval required": the one direction a default here is
+        # allowed to be wrong in is the safe one, because an unattended write cannot be undone by
+        # revoking the bot afterwards [[default-must-pass-its-own-guard]].
+        "writeApproval": raw.get("writeApproval", prior.get("writeApproval", True)) is not False,
+        # The permission block. Same shape, same validator, same engine as a user's.
+        "perms": prior.get("perms") if isinstance(prior.get("perms"), dict) else {},
+        "perms_v": int(prior.get("perms_v") or 0),
+        "createdBy": str(prior.get("createdBy") or raw.get("createdBy") or ""),
+        "createdAt": str(prior.get("createdAt") or raw.get("createdAt") or ""),
+    }
+    return out
+def _put_agent(session, agent_id, mutate):
+    """Read-modify-write ONE agent under the tenant's bucket, synchronously.
+    `flush="sync"` because the client re-reads the list immediately after every write here, and an
+    async flush would let the refetch win the race and paint the pre-write state — the
+    [[refetch-eats-its-own-write]] shape.
+    """
+    def _set(cur):
+        cur = dict(cur or {})
+        rec = cur.get(agent_id) if isinstance(cur.get(agent_id), dict) else None
+        nxt = mutate(rec)
+        if nxt is None:
+            cur.pop(agent_id, None)
+        else:
+            cur[agent_id] = nxt
+        return cur
+    session.runtime.update(AGENTS_KEY, _set, flush="sync")
+# ── ⭐⭐ THE PROJECTION — THE WHOLE OF "the same engine that permissions a user" ───────────────
+def agent_principal(agent):
+    """A channel agent, as a PRINCIPAL `core/perm_scope` already understands.
+    ⭐⭐ THIS IS THE ENTIRE POINT OF THE TICKET AND IT IS NINE LINES. `perm_scope` takes a user
+    RECORD — a plain dict with `perms`, `perms_v` and `role` — not a User object and not a session.
+    So a channel agent carrying a `perms` block simply IS such a record, and `may_access`,
+    `visible_fields`, `hidden_keys` and `apply_row_scope` work on it unmodified. There is no second
+    engine, no parallel vocabulary, and nothing about a channel to keep in step with anything about
+    a person. That is what the owner's *"exactly like how we toggle permissioning per user"* means
+    when it is true in code rather than in appearance.
+    ⛔ `role` IS HARDCODED NON-ADMIN AND MUST STAY SO. `perm_scope.may_access` returns True
+    unconditionally for `role == 'admin'` — the break-glass clause that keeps the owner out of a
+    locked store. A bot has no such emergency and no hands: an agent record that could carry
+    `role: 'admin'` would be one stored key away from bypassing every wall on this page. The key is
+    not copied from the record; it is written here, every time.
+    ⛔ AND `perms_v` IS FORCED TO THE CURRENT VERSION, which makes an UNDECLARED database DENY
+    (C-PERM amendment 4). Without it a fresh agent would fall through to `perms.may_open`'s legacy
+    grant wall and read `modules: 'all'`-shaped defaults — i.e. a brand-new bot would start with
+    access to everything. Fail-closed from the first byte.
+    """
+    import core.perm_scope as perm_scope
+    return {
+        "username": f"slack:{(agent or {}).get('channel') or '?'}",
+        "role": "agent",
+        "perms": (agent or {}).get("perms") or {},
+        "perms_v": perm_scope.PERMS_VERSION,
+        # No `bus`, no `agent`: a channel is not a business unit and not a salesperson. Absent
+        # rather than 'all' — `perms.allowed_bu_labels` narrows on absence, which is the direction
+        # this must fail in.
+    }
+def agent_may_read(agent, module):
+    """May this channel open `module` at all?"""
+    import core.perm_scope as perm_scope
+    if not (agent or {}).get("active", True):
+        return False
+    return bool(perm_scope.may_access(agent_principal(agent), module))
+def agent_visible_fields(agent, fields, module):
+    """`fields` minus this channel's hidden closure — the SAME transitive closure a person gets,
+    so a formula over a hidden column cannot leak it back through arithmetic."""
+    import core.perm_scope as perm_scope
+    return perm_scope.visible_fields(fields, agent_principal(agent), module)
+def agent_rows(agent, rows, module, fields, ctx=None, st=None):
+    """The rows this channel may receive — `permits()`, so an unanswerable permanent filter DENIES
+    rather than being ignored.
+    ⭐⭐ `st` IS THE TENANT HANDLE AND IT IS HERE BECAUSE OF THE SENTENCE IN `agent_principal`:
+    a channel agent IS a principal of the same wall, so a permanent filter naming a
+    user-generated column has to mean the SAME thing here as it does on the grid (owner I16).
+    A door that lends the handle and a door that does not are one stored rule with two meanings.
+    ⚠ PASS THE TENANT'S OWN RUNTIME — every other store read in this file takes
+    `session.runtime`, and a channel is not a second tenancy. It is a keyword with a `None`
+    default for the same reason `perm_scope.apply_row_scope`'s is: without one this is
+    byte-identical to the wall that shipped before the argument existed.
+    ⚠ `hidden_keys` DELIBERATELY DOES NOT TAKE IT IN THIS CHANGE. Its field-grant leg
+    under-hides without a handle (see `perm_scope.visible_overlays`), which is a real and
+    separate gap on this surface — but it is the FIELD wall, it moves what a channel receives
+    rather than what I16 asked for, and widening two walls in one ticket is how a permission
+    change stops being reviewable.
+    """
+    import core.perm_scope as perm_scope
+    p = agent_principal(agent)
+    hide = perm_scope.hidden_keys(p, module, fields)
+    kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx, st=st)
+    # Both wires, never one: the field list and the row payload are separate, and stripping only
+    # the first leaves the value sitting in the second where anyone can read it.
+    return [perm_scope.strip_row(r, hide) for r in kept]
+# ── the credential ───────────────────────────────────────────────────────────────────────────
+def slack_creds(rt):
+    """This TENANT's Slack credentials from its own keychain, or None.
+    ⛔ NO ENVIRONMENT FALLBACK, DELIBERATELY, AND THIS IS D-202's LESSON APPLIED BEFORE IT
+    HAPPENS AGAIN. Meta Ads shipped loading end-to-end and was still not a connector, because
+    `keychain.meta_creds` had no caller and the token came from the owner's `.env` — making it a
+    tenant-#0 FACT indistinguishable from a screenshot. `keychain.meta_creds`' own docstring spells
+    out the rule: handing the environment's credential to a tenant whose admin has not stored one
+    is the leak the resolver exists to prevent. So a tenant with no entry gets None and the pane
+    SAYS so.
+    ⚠ Reads through `list_entries` + `read_fields` (both public) rather than `keychain._first_creds`
+    (private, and in a file outside this lane's fence). Same deterministic rule: entries are
+    id-sorted, so "first" is stable across reads rather than dict-order luck.
+    """
+    try:
+        import core.keychain as keychain
+        for row in keychain.list_entries(rt):
+            if str(row.get("type") or "") != "slack":
+                continue
+            fields = keychain.read_fields(rt, row.get("id"))
+            if isinstance(fields, dict) and fields.get("signing_secret"):
+                return fields
+    except Exception:                                                        # noqa: BLE001
+        # A locked or unreadable keychain reads as "not configured" for the PANE, which is honest;
+        # the signature check below fails closed regardless, so this cannot widen anything.
+        return None
+    return None
+# ── the authenticated doors (the Manage agent surface) ───────────────────────────────────────
+def _summary(agent, modules):
+    """One sentence per agent for the list row — computed here, because the alternative is one
+    round trip per row to fill one cell (the same reason `AdminUser.access` exists)."""
+    # ⭐ W36-T22 / C2 — every listed database is governed now; the `enforced` flag it used to
+    # filter on is DELETED, and `m.get("enforced")` would have gone silently falsy here and
+    # summarised every agent as "" (no databases at all).
+    governed = list(modules)
+    perms = agent.get("perms") or {}
+    open_n = sum(1 for m in governed if (perms.get(m["key"]) or {}).get("access"))
+    if not governed:
+        return ""
+    if open_n == 0:
+        return "No access"
+    restricted = sum(1 for m in governed
+                     if (perms.get(m["key"]) or {}).get("access")
+                     and ((perms.get(m["key"]) or {}).get("filter")
+                          or (perms.get(m["key"]) or {}).get("hiddenFields")))
+    head = (f"All {open_n} database{'' if open_n == 1 else 's'}" if open_n == len(governed)
+            else f"{open_n} of {len(governed)} databases")
+    return f"{head}, {restricted} restricted" if restricted else head
+@router.get("/agents")
+def list_channel_agents(session: Session = Depends(admin_gate)):
+    """This tenant's channel agents, plus whether Slack is reachable at all."""
+    import routes_admin
+    modules = routes_admin._perm_modules(session)
+    rows = []
+    for aid, a in sorted(_agents(session.runtime).items()):
+        if not isinstance(a, dict):
+            continue
+        rows.append({"id": aid, "channel": a.get("channel") or "",
+                     "channelName": a.get("channelName") or "",
+                     "label": a.get("label") or "", "active": a.get("active", True) is not False,
+                     "writeApproval": a.get("writeApproval", True) is not False,
+                     "summary": _summary(a, modules)})
+    return {"agents": rows, "configured": slack_creds(session.runtime) is not None}
+@router.post("/agents")
+def create_channel_agent(body: dict = Body(default=None),
+                         session: Session = Depends(admin_gate)):
+    body = body if isinstance(body, dict) else {}
+    channel = str(body.get("channel") or "").strip()
+    if not channel:
+        raise err(400, "no_channel", "a Slack channel ID is required")
+    existing = _agents(session.runtime)
+    # ⚠ ONE AGENT PER CHANNEL. Two records for one conversation would mean two walls, and nothing
+    # anywhere decides which one applies — the [[one-question-two-normalizers]] shape, in the one
+    # place where the two answers are "may read" and "may not".
+    for a in existing.values():
+        if isinstance(a, dict) and str(a.get("channel") or "") == channel:
+            raise err(409, "channel_taken",
+                      "that channel already has an agent — edit it instead of adding a second")
+    aid = secrets.token_urlsafe(9)
+    rec = _clean_agent(dict(body, id=aid, createdBy=session.uname,
+                            createdAt=datetime.now(timezone.utc).isoformat(timespec="seconds")))
+    _put_agent(session, aid, lambda _prior: rec)
+    fresh = _agents(session.runtime).get(aid)
+    if not isinstance(fresh, dict):
+        # The store took the write and did not record it. A 200 here would tell an administrator
+        # the agent exists when it does not.
+        raise err(503, "store_unavailable", "the agent was NOT created")
+    return {"agent": {"id": aid, "channel": rec["channel"], "channelName": rec["channelName"],
+                      "label": rec["label"], "active": rec["active"],
+                      "writeApproval": rec["writeApproval"], "summary": "No access"}}
+@router.get("/agents/{agent_id}")
+def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
+    """The agent PLUS the permission envelope — the SAME shape `get_perms` answers with.
+    ⭐ ONE PAYLOAD SHAPE FOR TWO ROOMS. `permsModel.parsePermsPayload` parses this, and
+    `settings/ModulePermsList` renders it, because they are literally the same client code. A
+    second envelope here would mean a second parser and a second set of defaults within a wave.
+    """
+    import routes_admin
+    a = _agents(session.runtime).get(str(agent_id))
+    if not isinstance(a, dict):
+        raise err(404, "no_such_agent", "no agent with that id")
+    modules = routes_admin._perm_modules(session)
+    # ⭐⭐ W36-T22 / C2 — EVERY listed database, `ut_*` included. ⛔ THIS IS WHY THE FLAG'S
+    # DELETION IS NOT A ONE-FILE CHANGE: `m.get("enforced")` on a row that no longer carries the
+    # key is None, so this list would have been EMPTY and the channel perms editor would have
+    # governed ZERO databases while looking entirely correct. A Slack channel is a principal of
+    # the SAME wall (`verify_perm_scope` section H) and gets the same catalogue.
+    governed = [m["key"] for m in modules]
+    stored = a.get("perms") or {}
+    principal = agent_principal(a)
+    import core.perm_scope as perm_scope
+    perms_out = {}
+    for k in governed:
+        e = stored.get(k)
+        # ⛔ W36-T22 — `may_read`, the same evaluator the read door uses, for the reason spelled
+        # out at `routes_admin.get_perms`. ⚠ It answers DIFFERENTLY here and correctly so: a
+        # channel agent is not a person with a share, so a `ut_*` key it has not been granted
+        # defaults CLOSED — which is the fail-closed direction for a bot, and the same answer the
+        # table routes would give it.
+        perms_out[k] = e if isinstance(e, dict) else {
+            "access": bool(perm_scope.may_read(principal, k, st=session.runtime)),
+            "filter": None, "hiddenFields": []}
+    return {"id": str(agent_id), "channel": a.get("channel") or "",
+            "channelName": a.get("channelName") or "", "label": a.get("label") or "",
+            "active": a.get("active", True) is not False,
+            "writeApproval": a.get("writeApproval", True) is not False,
+            "perms": perms_out,
+            # ⛔ ALWAYS THE CURRENT VERSION, because `agent_principal` forces it: the editor must
+            # render "undeclared = denied", not the legacy-grant reading it would show at 0.
+            "perms_v": perm_scope.PERMS_VERSION,
+            # A bot is NEVER an admin — see `agent_principal`. Sent so the editor never paints
+            # the "Everything (admin)" state for a principal that cannot have it.
+            "is_admin": False,
+            "modules": modules,
+            "fields_by_module": {k: routes_admin._module_fields(k, session=session)
+                                 for k in governed}}
+@router.put("/agents/{agent_id}/perms")
+def put_channel_agent_perms(agent_id: str, body: dict = Body(default=None),
+                            session: Session = Depends(admin_gate)):
+    """Replace this agent's permission block wholesale — the same validator a user's block gets."""
+    import routes_admin
+    body = body if isinstance(body, dict) else {}
+    if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
+        raise err(404, "no_such_agent", "no agent with that id")
+    if "perms" not in body:
+        raise err(400, "empty_patch", "no perms to save")
+    mods = routes_admin._perm_modules(session)
+    # ⭐ THE SAME `_clean_perms`, NOT A COPY OF IT. It refuses a filter this module cannot
+    # evaluate, refuses a hiddenFields key that names nothing, and refuses a BU condition the
+    # pushdown cannot read. Every one of those is exactly as true for a channel as for a person,
+    # and a second validator here is a second place for one of them to go missing.
+    # ⚠ CORRECTED W36-T22: this list used to end "refuses an unenforced `ut_*` key". That refusal
+    # is DELETED — W36-T21 armed the wall over every database, so there is no unenforced key left
+    # to refuse, and a comment naming a rule that no longer exists is how the next wave re-derives
+    # it ([[two-gates-can-assert-opposite-things]]).
+    cleaned = routes_admin._clean_perms(
+        body.get("perms"),
+        governed_keys={m["key"] for m in mods}, session=session) or {}
+    import core.perm_scope as perm_scope
+    def _mut(prior):
+        if not isinstance(prior, dict):
+            return None
+        nxt = dict(prior)
+        nxt["perms"] = cleaned
+        nxt["perms_v"] = perm_scope.PERMS_VERSION
+        return nxt
+    _put_agent(session, str(agent_id), _mut)
+    fresh = _agents(session.runtime).get(str(agent_id)) or {}
+    if (fresh.get("perms") or {}) != cleaned:
+        # The one direction this must never fail in: telling an administrator the wall is up when
+        # it is not.
+        raise err(503, "store_unavailable", "the permissions were not saved — the agent is UNCHANGED")
+    return {"id": str(agent_id), "perms": fresh.get("perms") or {},
+            "perms_v": int(fresh.get("perms_v") or 0)}
+@router.patch("/agents/{agent_id}")
+def patch_channel_agent(agent_id: str, body: dict = Body(default=None),
+                        session: Session = Depends(admin_gate)):
+    body = body if isinstance(body, dict) else {}
+    if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
+        raise err(404, "no_such_agent", "no agent with that id")
+    #: ⛔ `perms` IS NOT PATCHABLE HERE. It has its own door with its own validator; accepting it
+    #: on the metadata route would be a second, unvalidated way to write the wall.
+    allowed = {k: v for k, v in body.items()
+               if k in ("label", "active", "writeApproval", "channelName")}
+    if not allowed:
+        raise err(400, "empty_patch", "nothing to change")
+    def _mut(prior):
+        return _clean_agent(allowed, prior=prior) if isinstance(prior, dict) else None
+    _put_agent(session, str(agent_id), _mut)
+    import routes_admin
+    a = _agents(session.runtime).get(str(agent_id)) or {}
+    return {"agent": {"id": str(agent_id), "channel": a.get("channel") or "",
+                      "channelName": a.get("channelName") or "", "label": a.get("label") or "",
+                      "active": a.get("active", True) is not False,
+                      "writeApproval": a.get("writeApproval", True) is not False,
+                      "summary": _summary(a, routes_admin._perm_modules(session))}}
+@router.delete("/agents/{agent_id}")
+def delete_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
+    if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
+        raise err(404, "no_such_agent", "no agent with that id")
+    _put_agent(session, str(agent_id), lambda _prior: None)
+    if isinstance(_agents(session.runtime).get(str(agent_id)), dict):
+        raise err(503, "store_unavailable", "the agent was NOT removed")
+    return {"ok": True}
+# ── ⭐ W33-T67: THE WRITE-APPROVAL GATE ───────────────────────────────────────────────────────
+def _is_empty(value):
+    """Is this value ABSENT, as opposed to falsy?
+    ⛔ COPIED EXACTLY FROM OpenTag's `agent/write_confirmation.py`, and the exactness is the point:
+    `0` and `False` are VALUES a human must see on the card. Setting a price to 0 or a flag to
+    False is precisely the kind of write somebody needs to approve, and a naive `if not value`
+    drops both rows silently — the approver then reads a card that does not describe the write
+    they are approving. The MIT licence gate for this borrowing is recorded in
+    `.claude/wiki/research/opentag-adoption.md`.
+    """
+    return value is None or (isinstance(value, str) and value.strip() == "")
+def approval_card(action, values, agent=None):
+    """The card a human reads before a bot writes. `{action, rows, truncated, note}`.
+    ⛔ ROW-CAPPED, and the cap is a SAFETY property rather than a layout one: past a certain
+    length Slack collapses a message behind "Show more", and **an approver who cannot read the
+    card cannot approve it.** When rows are dropped the card SAYS how many — a truncation nobody
+    was told about is the violation, not the truncation (wave-30 R6's second sentence).
+    """
+    rows = [{"field": str(k), "value": v}
+            for k, v in (values or {}).items() if not _is_empty(v)]
+    rows.sort(key=lambda r: r["field"])
+    shown, dropped = rows[:APPROVAL_MAX_ROWS], max(0, len(rows) - APPROVAL_MAX_ROWS)
+    return {
+        "action": str(action or "")[:80],
+        "rows": shown,
+        "truncated": dropped,
+        "note": (f"{dropped} more field(s) not shown — open the record to review them before "
+                 f"approving." if dropped else ""),
+        "agent": (agent or {}).get("label") or (agent or {}).get("channel") or "",
+    }
+def intercept_write(agent, action, values, stash):
+    """THE INTERCEPTOR. Returns `("commit", None)` or `("await_approval", card)`.
+    ⭐ The one thing worth taking from OpenTag: a MUTATING tool call is halted, rendered as a card
+    naming the action and its values, and committed only on an explicit human accept. Everything
+    else in that repo — the transport, the runtime, the identity model — is AVOID (amendment A1).
+    ⛔ FAIL-CLOSED ON A MISSING FLAG: `is not False`, so a record written before `writeApproval`
+    existed requires approval. The unsafe direction here is not recoverable — revoking a bot does
+    not un-write what it wrote.
+    """
+    if (agent or {}).get("writeApproval", True) is not False:
+        card = approval_card(action, values, agent)
+        stash(card)
+        return "await_approval", card
+    return "commit", None
+def _pending(rt):
+    try:
+        found = rt.get(PENDING_KEY) or {}
+    except Exception:                                                        # noqa: BLE001
+        return {}
+    return found if isinstance(found, dict) else {}
+def stash_pending(rt, agent, action, values, now=None):
+    """Store one awaiting-approval mutation and return its token.
+    The token is what rides the card's button, so it is `secrets.token_urlsafe` and not the
+    action's id: a guessable value on an unauthenticated door is a way to approve somebody else's
+    write. Server-only bucket, per tenant, exactly as `routes_forms.TOKENS_KEY` is.
+    """
+    token = secrets.token_urlsafe(18)
+    row = {"at": float(now if now is not None else time.time()),
+           "channel": str((agent or {}).get("channel") or ""),
+           "action": str(action or "")[:80],
+           "values": values if isinstance(values, dict) else {}}
+    rt.update(PENDING_KEY, lambda cur: {**(cur or {}), token: row}, flush="sync")
+    return token
+#: `{action kind: fn(rt, row) -> None}`. Registered by whatever can actually perform a mutation.
+#:
+#: ⛔⛔ EMPTY IN PRODUCTION TODAY, AND SAYING SO IS THE POINT. `commit_pending` below is the ONE
+#: place an approved write may be performed, so it is the place a negative control can bite — but
+#: a gate is only as honest as what it guards. Until something registers here, an approved card
+#: performs NOTHING and `commit_pending` returns `no_committer` rather than pretending. That is a
+#: declared absence, not a silent one [[flag-shipped-without-its-writer]].
+_COMMITTERS = {}
+def register_committer(kind, fn):
+    """Declare who may perform an approved mutation of `kind`. Idempotent by key."""
+    _COMMITTERS[str(kind)] = fn
+def commit_pending(rt, token, approved, now=None):
+    """Resolve ONE approval card. Returns one of
+    `expired` · `unknown` · `rejected` · `no_committer` · `committed` · `failed`.
+    ⛔⛔ THIS IS THE WRITE GATE, AND IT IS A SEPARATE FUNCTION FROM THE ROUTE ON PURPOSE. T67's
+    `done-when` asks for an NC proving a REJECTED card writes nothing. A control aimed at the
+    route could not bite while the route had no write in it at all — it would stay green with the
+    guard deleted, because there would be nothing for the guard to be protecting anything from
+    ([[gate-can-report-green-on-nothing]], and a verifier caught exactly that on this ticket's
+    first draft). Putting the commit behind ONE named seam gives the control a real subject: the
+    gate registers a recorder, and `rejected` must leave it untouched while `approve` must call it
+    exactly once.
+    ⛔ THE TOKEN IS CONSUMED BEFORE EITHER BRANCH, and before any committer runs. A card that
+    survives its own click is a replayable write, and "approve twice" must never mean "write
+    twice". The delete is `flush="sync"` for the same reason.
+    """
+    now = float(now if now is not None else time.time())
+    row = _pending(rt).get(str(token))
+    if not isinstance(row, dict):
+        return "unknown"
+    # Consume FIRST — before the TTL verdict, before the approve/reject branch, before any write.
+    rt.update(PENDING_KEY,
+              lambda cur: {k: v for k, v in (cur or {}).items() if k != str(token)},
+              flush="sync")
+    if now - float(row.get("at") or 0) > APPROVAL_TTL_S:
+        return "expired"
+    if not approved:
+        # ⛔ NOTHING BELOW THIS LINE RUNS FOR A REJECTED CARD. The whole gate is this return.
+        return "rejected"
+    fn = _COMMITTERS.get(str(row.get("action") or ""))
+    if fn is None:
+        return "no_committer"
+    try:
+        fn(rt, row)
+    except Exception:                                                        # noqa: BLE001
+        # A committer that raises must not read as a commit. The card is already consumed, so the
+        # honest report is that it failed, and the human asks again.
+        return "failed"
+    return "committed"
+# ── the UNAUTHENTICATED Slack door ───────────────────────────────────────────────────────────
+#: Sliding window, keyed on the SLACK TEAM, never the client IP.
+#:
+#: ⛔ WHY NOT THE IP, WHICH IS WHAT `routes_forms` DOES. Every Slack event arrives from Slack's own
+#: infrastructure, so an IP window is one shared bucket for every workspace on the platform: one
+#: busy tenant would spend the allowance for all of them, and the symptom would be another
+#: tenant's bot going quiet. The team id is the closest thing to the actual noisy party.
+#: ⚠ It is attacker-CONTROLLED before the signature is checked, so the window is applied AFTER
+#: verification, never before — an unsigned request is refused on cost grounds anyway (a signature
+#: check is a single HMAC).
+RATE_WINDOW_S, RATE_PER_WINDOW = 60, 60
+_HITS: dict = {}
+def _rate_ok(key, now):
+    seen = [t for t in _HITS.get(key, ()) if now - t < RATE_WINDOW_S]
+    seen.append(now)
+    _HITS[key] = seen
+    if len(_HITS) > 4096:
+        for k in [k for k, v in _HITS.items() if not v or now - v[-1] > RATE_WINDOW_S]:
+            _HITS.pop(k, None)
+    return len(seen) <= RATE_PER_WINDOW
+async def _raw_body(request):
+    """The body as RAW BYTES, capped.
+    ⛔⛔ RAW, NOT PARSED, AND THAT IS NOT A STYLE CHOICE. Slack signs the literal string
+    `v0:{timestamp}:{body}` byte for byte. `routes_forms._bounded_body` — the function this is
+    otherwise copied from — returns only the parsed dict and DISCARDS the bytes, so a verbatim
+    copy of it could not verify a Slack signature at all: re-serialising the dict changes
+    whitespace and key order and the HMAC no longer matches. The bug would look like "Slack
+    signatures are always invalid", which is indistinguishable from a wrong secret.
+    ⚠ And it streams rather than calling `request.body()`: FastAPI would otherwise have buffered
+    the whole body before the handler's first line, so a content-length check inside the handler
+    caps nothing (`routes_forms`' own scar, recorded in its docstring).
+    """
+    size, chunks = 0, []
+    async for chunk in request.stream():
+        size += len(chunk)
+        if size > MAX_BODY_BYTES:
+            raise err(413, "body_too_large", "that request is too large")
+        chunks.append(chunk)
+    return b"".join(chunks)
+def _refuse():
+    """ONE refusal for every reason. No oracle.
+    A wrong signature, a stale timestamp, an unknown team, an unconfigured tenant and a channel
+    with no agent all answer identically — otherwise the door tells an unauthenticated caller
+    which tenants exist and which channels are configured, which is the question it was built to
+    not answer. `routes_forms._refuse` takes the same posture for the same reason.
+    """
+    return err(403, "bad_request", "that request could not be verified")
+def _verify(secret, timestamp, raw, signature, now):
+    """Slack's v0 signature, with the replay window checked FIRST."""
+    try:
+        ts = int(str(timestamp or "0"))
+    except ValueError:
+        return False
+    if abs(now - ts) > SLACK_MAX_SKEW_S:
+        return False
+    base = b"v0:" + str(ts).encode("ascii") + b":" + (raw or b"")
+    import hashlib
+    expected = "v0=" + hmac.new(str(secret).encode("utf-8"), base, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, str(signature or ""))
+def _resolve_tenant(raw, timestamp, signature, now):
+    """`(slug, runtime, creds)` for the tenant whose signing secret verifies this request.
+    ⛔ THE TENANT IS DECIDED BY THE SIGNATURE, NEVER BY THE PAYLOAD. A body-supplied `team_id`
+    would let an unauthenticated caller name the tenant it wants to be — the exact widening
+    `deps._user_for`'s tenant-equality check closes on the authenticated side. So every configured
+    tenant's secret is tried and the one that VERIFIES names the tenant.
+    ⚠ NO EARLY `break` ON A FAILED CANDIDATE and no per-tenant error: the loop's cost must not
+    depend on which tenant matched. `routes_forms._resolve` walks tenants the same way, for the
+    same reason — a public door has no session to ask.
+    """
+    from harness import runtime as _rt
+    hit = None
+    try:
+        slugs = list(_rt.known_tenants())
+    except Exception:                                                        # noqa: BLE001
+        return None, None, None
+    for slug in slugs:
+        try:
+            rt = _rt.get_runtime(slug)
+        except Exception:                                                    # noqa: BLE001
+            continue
+        creds = slack_creds(rt)
+        if not creds:
+            continue
+        if _verify(creds.get("signing_secret"), timestamp, raw, signature, now) and hit is None:
+            hit = (slug, rt, creds)
+    return hit if hit else (None, None, None)
+@router.post("/slack/events")
+async def slack_events(request: Request):
+    """Slack's Events API. UNAUTHENTICATED BY CONSTRUCTION — no `Depends(require_session)`.
+    ⭐ Built like `routes_forms.py`'s public door and not like OpenTag's: one process, no vendor,
+    no second runtime, no persistent outbound socket, and this tenant's Slack secret never leaves
+    this deployment (amendment A1).
+    """
+    now = time.time()
+    raw = await _raw_body(request)
+    ts = request.headers.get("x-slack-request-timestamp")
+    sig = request.headers.get("x-slack-signature")
+    slug, rt, _creds = _resolve_tenant(raw, ts, sig, now)
+    if not rt:
+        raise _refuse()
+    try:
+        payload = json.loads(raw or b"{}")
+    except ValueError:
+        raise _refuse()
+    if not isinstance(payload, dict):
+        raise _refuse()
+    # Slack's one-time endpoint handshake. Answered ONLY after the signature verified — an
+    # unsigned challenge echo would confirm the endpoint exists to anyone who probes it.
+    if payload.get("type") == "url_verification":
+        return {"challenge": str(payload.get("challenge") or "")[:512]}
+    team = str(payload.get("team_id") or slug)
+    if not _rate_ok(f"{slug}:{team}", now):
+        raise err(429, "too_many_requests", "too many requests — wait a moment and try again")
+    event = payload.get("event") if isinstance(payload.get("event"), dict) else {}
+    channel = str(event.get("channel") or "")
+    agent = None
+    for a in _agents(rt).values():
+        if isinstance(a, dict) and str(a.get("channel") or "") == channel:
+            agent = a
+            break
+    # ⛔ NO AGENT, OR AN INACTIVE ONE, IS SILENCE — a 200 with no action. Not a 403: Slack retries
+    # a non-2xx up to three times, so refusing here would turn "this channel is not configured"
+    # into three refusals per message, and the retry storm would be the only visible symptom.
+    # ⚠ And it must not say WHICH — a distinguishable answer tells an unauthenticated caller which
+    # channels this workspace has configured.
+    if not isinstance(agent, dict) or agent.get("active", True) is False:
+        return {"ok": True}
+    # ⛔⛔ THE ANSWERING HALF IS NOT BUILT YET, AND SAYING SO IS THE POINT. What ships here is the
+    # DOOR and the WALL: a verified request, resolved to a tenant by signature, matched to a
+    # channel agent whose `perms` block is a `perm_scope` principal (`agent_principal`). Composing
+    # a reply means an LLM call on the cheap-first ladder plus the read path, and a half-built
+    # answerer that returns something plausible is worse than one that returns nothing.
+    # Booked rather than faked [[flag-shipped-without-its-writer]].
+    return {"ok": True}
+@router.post("/slack/interact")
+async def slack_interact(request: Request):
+    """The approval card's button (`W33-T67`). UNAUTHENTICATED, signature-verified, same shape."""
+    now = time.time()
+    raw = await _raw_body(request)
+    slug, rt, _creds = _resolve_tenant(raw, request.headers.get("x-slack-request-timestamp"),
+                                       request.headers.get("x-slack-signature"), now)
+    if not rt:
+        raise _refuse()
+    # Slack posts interactions as `application/x-www-form-urlencoded` with a `payload=` field.
+    from urllib.parse import parse_qs
+    try:
+        form = parse_qs(raw.decode("utf-8"))
+        payload = json.loads((form.get("payload") or ["{}"])[0])
+    except Exception:                                                        # noqa: BLE001
+        raise _refuse()
+    if not isinstance(payload, dict):
+        raise _refuse()
+    if not _rate_ok(f"{slug}:interact", now):
+        raise err(429, "too_many_requests", "too many requests — wait a moment and try again")
+    actions = payload.get("actions") if isinstance(payload.get("actions"), list) else []
+    choice = (actions[0] if actions and isinstance(actions[0], dict) else {})
+    token = str(choice.get("value") or "")
+    # ⭐ ANYTHING THAT IS NOT LITERALLY "approve" IS A REJECT. Fail-closed on a malformed,
+    # truncated or unknown action id: the direction that can be wrong here without anyone
+    # noticing is the one that writes.
+    approved = str(choice.get("action_id") or "") == "approve"
+    # ⛔ THE ROUTE DOES NOT DECIDE — `commit_pending` does, and it is the ONE seam a negative
+    # control can aim at. Consumption, the TTL, the reject branch and the committer lookup all
+    # live there; this handler only turns its verdict into a sentence.
+    verdict = commit_pending(rt, token, approved, now=now)
+    return {"text": {
+        # An unknown, already-used or expired token is not an error: a person clicking a stale
+        # card should be told it is stale, not shown a failure.
+        "unknown": "That approval is no longer available. Ask the bot again.",
+        "expired": "That approval expired before it was answered. Ask the bot again.",
+        "rejected": "Rejected. Nothing was changed.",
+        # ⚠ HONEST, not reassuring: the answering half that would register a committer is booked,
+        # so an approved card today performs nothing and says exactly that rather than "Approved."
+        "no_committer": "Approved — but this workspace has nothing configured to carry it out yet.",
+        "failed": "That change could not be completed. Nothing was saved; ask the bot again.",
+        "committed": "Approved.",
+    }.get(verdict, "That approval is no longer available. Ask the bot again.")}
+@router.get("/slack/health")
+def slack_health(session: Session = Depends(require_session)):
+    """Is Slack configured for THIS tenant? Session-gated, and it answers about one tenant only —
+    enumerating the others would answer a question about our customer list."""
+    creds = slack_creds(session.runtime)
+    return {"configured": creds is not None,
+            "agents": len(_agents(session.runtime)),
+            "hasBotToken": bool((creds or {}).get("bot_token"))}

api/routes_statements.py CHANGED Viewed

@@ -1,298 +1,298 @@
-"""routes_statements.py — the statement-of-account sender, ported off Streamlit (EXIT-6).
-⛔ THIS IS THE ONE SANCTIONED ODOO WRITER IN THE ENTIRE SYSTEM. Everything else in AIOS is
-read-only on Odoo by hard block. `modules/collections_send.py` owns a narrow client that whitelists
-exactly `mail.mail create` (queueing an outbound email) and nothing else; these routes call it and
-add no write of their own.
-WHY IT EXISTS SEPARATELY FROM THE COLLECTIONS PAGE. Owner ruling wave-17 item 15 retired the
-Collections *dashboard* — the worklist is the shared "Collections" view on the Customer grid, from
-the same reconciled blocks. What that ruling explicitly left "untouched" is this send workflow, so
-when `app.py` is deleted it is the ONLY live Streamlit-only feature, and it moves here rather than
-dying with the host. Ported faithfully: same tiers, same filters, same template placeholders, same
-preview, same test-send, same two-step confirm.
-THE THREE GUARDRAILS, and where each is enforced:
-  1. SAFE_MODE (default ON) — in the DATA LAYER (`collections_send.queue_statement`), so no route,
-     payload or UI can bypass it. These routes only REPORT it; they never re-implement the check.
-  2. Admin only — `admin_gate` (role, fail-closed), mirroring the Streamlit `if not is_admin()`.
-  3. ⭐ TENANT — NEW HERE, and it did not exist in Streamlit because it could not. `cs_mod.Odoo()`
-     reads Odoo credentials from the ENVIRONMENT, which after the keychain cutover belongs to
-     TENANT #0 ALONE. On the multi-tenant API an unguarded route would let a nurilab or gtmlab
-     admin queue mail from Royal Imports' Odoo, as Royal Imports. `_royal_only` closes that; the
-     single-tenant Streamlit host never had the exposure, so this is a port that must ADD a wall
-     rather than copy one.
-NOTHING SENDS ON A GET. The send route requires an explicit customer list in the body; there is no
-"send all" parameter, deliberately — the confirm step is a product requirement, not a formality.
-"""
-from fastapi import APIRouter, Body, Depends
-from deps import Session, err
-from routes_admin import admin_gate
-# W35-T35 (C8): the tenant predicate, held once. See `_royal_only` for why the import runs this
-# way round. `main.py` already imports both modules, so this adds no load.
-import automation_engine as engine
-router = APIRouter(prefix="/api/v1")
-#: Cache the Odoo follow-up pull briefly. The Streamlit page used `@st.cache_data(ttl=1800)`; the
-#: list moves slowly (it is a dunning worklist, not a live feed) and the pull is a multi-model read.
-_TTL = 1800
-_cache = {"at": 0.0, "rows": None}
-def _cs():
-    import modules.collections_send as cs
-    return cs
-def _royal_only(session: Session) -> Session:
-    """⛔ See the module docstring, guardrail 3. The send client is env-credentialed, so it is
-    tenant #0's and only tenant #0's. Refuse for anyone else rather than send as the wrong company.
-    Keyed on the runtime, never on a request field: a tenant is a property of the SESSION.
-    ⭐⭐ WAVE 35 · T35 / CONTRACT C8 — THE TEST ITSELF NOW LIVES IN ONE PLACE. Statements became an
-    agent step this wave, so the automation engine has to answer the same question at two more
-    doors (which tenants see the action, which tenants may store it). C8's words are "the predicate
-    is imported, never re-expressed", and this is the direction that import can run: the engine
-    imports no route module and no FastAPI, so reaching `_royal_only` FROM it would drag `deps` and
-    `routes_admin` into a route-free module. The engine holds the boolean; this holds the refusal.
-    ⚠ WHAT STAYS HERE IS THE HTTP SHAPE, and that is deliberate — a 404 rather than a 403, so the
-    surface is invisible rather than forbidden. The engine must not know about status codes."""
-    if not engine.is_statement_tenant(session.runtime):
-        raise err(404, "not_found", "statements are not configured for this workspace")
-    return session
-def _gate(session: Session = Depends(admin_gate)) -> Session:
-    return _royal_only(session)
-def _rows(force=False):
-    import time
-    cs = _cs()
-    if force or _cache["rows"] is None or (time.time() - _cache["at"]) > _TTL:
-        _cache["rows"] = cs.load_collection_list(cs.Odoo())
-        _cache["at"] = time.time()
-    return _cache["rows"], time.strftime("%Y-%m-%d %H:%M", time.localtime(_cache["at"]))
-def _public(row):
-    """Strip the internals the Streamlit grid also hid (`_`-prefixed + partner_id is kept, because
-    the client needs a stable row identity that is not the display name)."""
-    return {k: v for k, v in row.items() if not str(k).startswith("_")}
-@router.get("/admin/statements")
-def statements(refresh: int = 0, session: Session = Depends(_gate)):
-    """The worklist + everything the sender UI needs to render itself honestly."""
-    cs = _cs()
-    try:
-        rows, loaded_at = _rows(force=bool(refresh))
-    except Exception as e:
-        raise err(502, "odoo_unavailable", f"could not load the collection list: {str(e)[:200]}")
-    return {
-        "rows": [_public(r) for r in rows],
-        "loadedAt": loaded_at,
-        # The guardrail is reported, never decided, here — the data layer owns it.
-        "safeMode": bool(cs.SAFE_MODE),
-        "safeRecipients": sorted(cs.SAFE_RECIPIENTS),
-        "sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL,
-                   "replyTo": cs.REPLY_TO, "company": cs.COMPANY},
-        "templates": {"subject": cs.DEFAULT_SUBJECT, "intro": cs.DEFAULT_INTRO,
-                      "footer": cs.DEFAULT_FOOTER},
-        # W35-T35: ONE literal, read from the engine, so the sender's worklist and a statements
-        # agent's tier filter cannot come to mean different things.
-        "tiers": list(engine.STATEMENT_TIERS),
-    }
-def _find(rows, customer):
-    return next((r for r in rows if r.get("Customer") == customer), None)
-@router.post("/admin/statements/preview")
-def preview(body: dict = Body(default=None), session: Session = Depends(_gate)):
-    """Render ONE customer's statement exactly as the send path would."""
-    cs = _cs()
-    body = body or {}
-    rows, _ = _rows()
-    row = _find(rows, body.get("customer"))
-    if row is None:
-        raise err(404, "not_found", "no such customer on the collection list")
-    t = body.get("templates") or {}
-    import datetime as dt
-    month = dt.date.today().strftime("%B %Y")
-    subject = (t.get("subject") or cs.DEFAULT_SUBJECT)
-    try:
-        subject = subject.format(customer=row["Customer"], company=cs.COMPANY, month=month)
-    except Exception:                                                     # noqa: BLE001
-        # An unknown placeholder is the user's typo, not a 500. Show the template verbatim so they
-        # can see what they typed rather than getting an opaque error.
-        # ⛔ W36-T42: THIS CAUGHT THREE OF THE WAYS `str.format` FAILS AND THERE ARE MORE.
-        # `{customer` is a ValueError, `{customer.x}` an AttributeError, `{customer:%Y}` a
-        # TypeError, and every one of them is the same user mistake this branch was written for.
-        # Naming a subset of the exception types turns a typo in the OTHER half into a 500 on the
-        # one screen somebody opens to avoid mailing 200 people the wrong thing.
-        pass
-    return {
-        "html": cs.render_statement_html(row, t.get("intro") or cs.DEFAULT_INTRO,
-                                         t.get("footer") or cs.DEFAULT_FOOTER),
-        "to": row.get("Email") or "",
-        "subject": subject,
-    }
-@router.post("/admin/statements/send")
-def send(body: dict = Body(default=None), session: Session = Depends(_gate)):
-    """Queue statements. Returns per-customer outcomes — NEVER a bare count.
-    `overrideTo` is the test-send path: one customer, one address. SAFE_MODE still applies (the
-    data layer refuses an address outside the allow-list), which is why the route does not check it.
-    """
-    cs = _cs()
-    body = body or {}
-    names = [str(n) for n in (body.get("customers") or []) if str(n).strip()]
-    if not names:
-        raise err(400, "bad_request", "name at least one customer")
-    # ⛔⛔ W36-T42 / D-299 — A DECLARED TEST SEND WITH NO ADDRESS REFUSES. IT DOES NOT BECOME A
-    # REAL ONE. This read `(body.get("overrideTo") or "").strip() or None`, so a caller who sent
-    # `overrideTo: ""` (the field left blank, the state not yet typed into, a trimmed-away space)
-    # got a REAL statement mailed to the debtor's own address, reported back as `test: false`. On
-    # the one route in this product that is allowed to write to Odoo, the difference between a
-    # rehearsal and mailing a live customer was one empty string.
-    #
-    # ⭐ THE DISCRIMINATOR IS THE CALLER'S DECLARATION, NOT THE VALUE. A body with no `overrideTo`
-    # key and no `test` flag is the PRODUCTION send, and refusing that would delete the feature
-    # D-299 exists to preserve. What can be refused is a caller who SAID this is a test: the key
-    # being present, or `test: true`, is that statement, and an empty address beside it is the
-    # mistake. So both spellings of "absent" are covered: the key present and blank, and `test`
-    # asserted with no key at all.
-    #
-    # ⚠ THIS IS THE SECOND OF THREE WALLS AND THE ONLY ONE A PAYLOAD CANNOT ROUTE AROUND.
-    # `automationApi.testSendStatement` refuses an empty address before the request is built, and
-    # SAFE_MODE refuses an address outside the allow-list inside `queue_statement`. The client
-    # wall is bypassable by construction (anything can POST); this one is not.
-    declared_test = ("overrideTo" in body) or bool(body.get("test"))
-    override = str(body.get("overrideTo") or "").strip()
-    if declared_test and not override:
-        raise err(400, "no_override_address",
-                  "a test send needs the address to send the test to. Without one this would "
-                  "mail the customer's own address, which is the opposite of a test")
-    override = override or None
-    if override and len(names) != 1:
-        raise err(400, "bad_request", "a test send takes exactly one customer")
-    t = body.get("templates") or {}
-    rows, _ = _rows()
-    sent, failed, skipped = [], [], []
-    for name in names:
-        row = _find(rows, name)
-        if row is None:
-            failed.append({"customer": name, "error": "not on the current collection list"})
-            continue
-        if not override and not row.get("Email"):
-            # The Streamlit page warned and skipped these. Reporting them SEPARATELY from failures
-            # keeps "we could not" distinct from "there was nowhere to send".
-            skipped.append({"customer": name, "reason": "no email address on the customer record"})
-            continue
-        try:
-            mid = cs.queue_statement(cs.Odoo(), row, t.get("subject") or cs.DEFAULT_SUBJECT,
-                                     t.get("intro") or cs.DEFAULT_INTRO,
-                                     t.get("footer") or cs.DEFAULT_FOOTER, override_to=override)
-            sent.append({"customer": name, "to": override or row.get("Email"), "mailId": mid})
-        except Exception as e:
-            # SafeModeBlocked lands here too, and that is correct: to the caller a guardrail refusal
-            # and an Odoo error are both "this one did not go", each with its own honest message.
-            failed.append({"customer": name, "error": str(e)[:200]})
-    return {"sent": sent, "failed": failed, "skipped": skipped,
-            "safeMode": bool(cs.SAFE_MODE), "test": bool(override)}
-# ---------------------------------------------------------------------------------------------
-# WAVE 35 · T36 / CONTRACT C8 / OWNER RULING R10 — THE AGENT'S PARKED BATCH.
-#
-# ⛔⛔ THE AGENT ASSEMBLES; A PERSON CLICKS SEND. `automation_engine.run_statements` renders a batch
-# and parks it on the automation definition, and it imports no mail path at all. THIS is the only
-# door that releases one, and it is deliberately built out of the parts already here:
-#   · `_gate` — `admin_gate` THEN `_royal_only`, byte-for-byte the dependency the other three
-#     endpoints use. Not a copy of the checks: the same object.
-#   · `cs.queue_statement` — the same call `send()` above makes, so SAFE_MODE's allow-list refusal
-#     happens in the DATA LAYER, where no route, payload or UI can reach around it.
-# ⇒ Nothing about the guardrails is re-expressed here, which is what makes "unchanged" checkable.
-#
-# ⚠ WHY THE BATCH IS RE-RENDERED FROM THE LIVE WORKLIST RATHER THAN SENT AS STORED. The parked
-# `html` is what a person APPROVED and is what the review screen shows; but a balance can move
-# between the parking and the click, and mailing a figure we know to be stale is worse than mailing
-# a fresh one. So the parked batch decides WHO and WITH WHAT WORDS, and the live row decides the
-# NUMBERS — the same split `preview` already makes. A customer who has left the worklist entirely
-# (they paid) is reported as skipped rather than invoiced.
-@router.get("/admin/statements/agent/{auto_id}")
-def agent_batch(auto_id: str, session: Session = Depends(_gate)):
-    """What is parked and waiting for a click, for ONE agent. `null` when nothing is."""
-    defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
-    pending = defn.get("pendingStatements")
-    if not isinstance(pending, dict):
-        return {"pending": None}
-    # ⚠ The rendered `html` is NOT returned in the list — a 200-statement batch of rendered mail is
-    # megabytes, and the review screen needs the count and the names to decide. `preview` already
-    # renders ONE on demand.
-    return {"pending": {
-        "ts": pending.get("ts"), "count": int(pending.get("count") or 0),
-        "notes": list(pending.get("notes") or []),
-        "items": [{k: v for k, v in it.items() if k != "html"}
-                  for it in (pending.get("items") or [])],
-        "safeMode": bool(_cs().SAFE_MODE)}}
-@router.post("/admin/statements/agent/{auto_id}/send")
-def agent_send(auto_id: str, body: dict = Body(default=None),
-               session: Session = Depends(_gate)):
-    """Release a parked batch. THE CLICK R10 REQUIRES — nothing else in the system calls this.
-    ⛔ IT REFUSES AN EMPTY OR MISSING BATCH rather than answering 200 with nothing sent: a send
-    that reports success and mails nobody is the `view_upsert` failure mode (200 OK, zero writes)
-    arriving on the one route in this system that talks to a mail server.
-    """
-    cs = _cs()
-    defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
-    pending = defn.get("pendingStatements")
-    items = list((pending or {}).get("items") or []) if isinstance(pending, dict) else []
-    if not items:
-        raise err(404, "no_batch", "there is nothing parked for this agent to send")
-    # ⚠ An explicit subset is allowed (a person unticking a customer on the review screen) but it
-    # may only NARROW the parked batch. A name that was never parked cannot be introduced by the
-    # payload, or the review stops being what authorised the send.
-    want = {str(n) for n in (body or {}).get("customers") or []}
-    if want:
-        items = [it for it in items if str(it.get("customer")) in want]
-        if not items:
-            raise err(400, "bad_request", "none of those customers are in the parked batch")
-    rows, _ = _rows()
-    sent, failed, skipped = [], [], []
-    for it in items:
-        name = str(it.get("customer") or "")
-        row = _find(rows, name)
-        if row is None:
-            skipped.append({"customer": name,
-                            "reason": "no longer on the collection list, so nothing is owed"})
-            continue
-        try:
-            # ⛔ THE SAME DATA-LAYER CALL `send()` MAKES. SafeModeBlocked is raised INSIDE
-            # `queue_statement`, so the guardrail cannot be argued with from here.
-            mid = cs.queue_statement(cs.Odoo(), row,
-                                     str(it.get("subject") or "") or cs.DEFAULT_SUBJECT,
-                                     cs.DEFAULT_INTRO, cs.DEFAULT_FOOTER)
-            sent.append({"customer": name, "to": row.get("Email"), "mailId": mid})
-        except Exception as e:                                        # noqa: BLE001
-            failed.append({"customer": name, "error": str(e)[:200]})
-    # ⚠ CLEARED ONLY WHEN NOTHING IS LEFT TO RETRY. A batch dropped while some of it failed would
-    # lose the list of who still needs a statement, and nobody would know to look.
-    if sent and not failed:
-        engine.clear_statements(session.runtime, auto_id)
-    return {"sent": sent, "failed": failed, "skipped": skipped,
-            "safeMode": bool(cs.SAFE_MODE), "cleared": bool(sent and not failed)}

+"""routes_statements.py — the statement-of-account sender, ported off Streamlit (EXIT-6).
+⛔ THIS IS THE ONE SANCTIONED ODOO WRITER IN THE ENTIRE SYSTEM. Everything else in AIOS is
+read-only on Odoo by hard block. `modules/collections_send.py` owns a narrow client that whitelists
+exactly `mail.mail create` (queueing an outbound email) and nothing else; these routes call it and
+add no write of their own.
+WHY IT EXISTS SEPARATELY FROM THE COLLECTIONS PAGE. Owner ruling wave-17 item 15 retired the
+Collections *dashboard* — the worklist is the shared "Collections" view on the Customer grid, from
+the same reconciled blocks. What that ruling explicitly left "untouched" is this send workflow, so
+when `app.py` is deleted it is the ONLY live Streamlit-only feature, and it moves here rather than
+dying with the host. Ported faithfully: same tiers, same filters, same template placeholders, same
+preview, same test-send, same two-step confirm.
+THE THREE GUARDRAILS, and where each is enforced:
+  1. SAFE_MODE (default ON) — in the DATA LAYER (`collections_send.queue_statement`), so no route,
+     payload or UI can bypass it. These routes only REPORT it; they never re-implement the check.
+  2. Admin only — `admin_gate` (role, fail-closed), mirroring the Streamlit `if not is_admin()`.
+  3. ⭐ TENANT — NEW HERE, and it did not exist in Streamlit because it could not. `cs_mod.Odoo()`
+     reads Odoo credentials from the ENVIRONMENT, which after the keychain cutover belongs to
+     TENANT #0 ALONE. On the multi-tenant API an unguarded route would let a nurilab or gtmlab
+     admin queue mail from Royal Imports' Odoo, as Royal Imports. `_royal_only` closes that; the
+     single-tenant Streamlit host never had the exposure, so this is a port that must ADD a wall
+     rather than copy one.
+NOTHING SENDS ON A GET. The send route requires an explicit customer list in the body; there is no
+"send all" parameter, deliberately — the confirm step is a product requirement, not a formality.
+"""
+from fastapi import APIRouter, Body, Depends
+from deps import Session, err
+from routes_admin import admin_gate
+# W35-T35 (C8): the tenant predicate, held once. See `_royal_only` for why the import runs this
+# way round. `main.py` already imports both modules, so this adds no load.
+import automation_engine as engine
+router = APIRouter(prefix="/api/v1")
+#: Cache the Odoo follow-up pull briefly. The Streamlit page used `@st.cache_data(ttl=1800)`; the
+#: list moves slowly (it is a dunning worklist, not a live feed) and the pull is a multi-model read.
+_TTL = 1800
+_cache = {"at": 0.0, "rows": None}
+def _cs():
+    import modules.collections_send as cs
+    return cs
+def _royal_only(session: Session) -> Session:
+    """⛔ See the module docstring, guardrail 3. The send client is env-credentialed, so it is
+    tenant #0's and only tenant #0's. Refuse for anyone else rather than send as the wrong company.
+    Keyed on the runtime, never on a request field: a tenant is a property of the SESSION.
+    ⭐⭐ WAVE 35 · T35 / CONTRACT C8 — THE TEST ITSELF NOW LIVES IN ONE PLACE. Statements became an
+    agent step this wave, so the automation engine has to answer the same question at two more
+    doors (which tenants see the action, which tenants may store it). C8's words are "the predicate
+    is imported, never re-expressed", and this is the direction that import can run: the engine
+    imports no route module and no FastAPI, so reaching `_royal_only` FROM it would drag `deps` and
+    `routes_admin` into a route-free module. The engine holds the boolean; this holds the refusal.
+    ⚠ WHAT STAYS HERE IS THE HTTP SHAPE, and that is deliberate — a 404 rather than a 403, so the
+    surface is invisible rather than forbidden. The engine must not know about status codes."""
+    if not engine.is_statement_tenant(session.runtime):
+        raise err(404, "not_found", "statements are not configured for this workspace")
+    return session
+def _gate(session: Session = Depends(admin_gate)) -> Session:
+    return _royal_only(session)
+def _rows(force=False):
+    import time
+    cs = _cs()
+    if force or _cache["rows"] is None or (time.time() - _cache["at"]) > _TTL:
+        _cache["rows"] = cs.load_collection_list(cs.Odoo())
+        _cache["at"] = time.time()
+    return _cache["rows"], time.strftime("%Y-%m-%d %H:%M", time.localtime(_cache["at"]))
+def _public(row):
+    """Strip the internals the Streamlit grid also hid (`_`-prefixed + partner_id is kept, because
+    the client needs a stable row identity that is not the display name)."""
+    return {k: v for k, v in row.items() if not str(k).startswith("_")}
+@router.get("/admin/statements")
+def statements(refresh: int = 0, session: Session = Depends(_gate)):
+    """The worklist + everything the sender UI needs to render itself honestly."""
+    cs = _cs()
+    try:
+        rows, loaded_at = _rows(force=bool(refresh))
+    except Exception as e:
+        raise err(502, "odoo_unavailable", f"could not load the collection list: {str(e)[:200]}")
+    return {
+        "rows": [_public(r) for r in rows],
+        "loadedAt": loaded_at,
+        # The guardrail is reported, never decided, here — the data layer owns it.
+        "safeMode": bool(cs.SAFE_MODE),
+        "safeRecipients": sorted(cs.SAFE_RECIPIENTS),
+        "sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL,
+                   "replyTo": cs.REPLY_TO, "company": cs.COMPANY},
+        "templates": {"subject": cs.DEFAULT_SUBJECT, "intro": cs.DEFAULT_INTRO,
+                      "footer": cs.DEFAULT_FOOTER},
+        # W35-T35: ONE literal, read from the engine, so the sender's worklist and a statements
+        # agent's tier filter cannot come to mean different things.
+        "tiers": list(engine.STATEMENT_TIERS),
+    }
+def _find(rows, customer):
+    return next((r for r in rows if r.get("Customer") == customer), None)
+@router.post("/admin/statements/preview")
+def preview(body: dict = Body(default=None), session: Session = Depends(_gate)):
+    """Render ONE customer's statement exactly as the send path would."""
+    cs = _cs()
+    body = body or {}
+    rows, _ = _rows()
+    row = _find(rows, body.get("customer"))
+    if row is None:
+        raise err(404, "not_found", "no such customer on the collection list")
+    t = body.get("templates") or {}
+    import datetime as dt
+    month = dt.date.today().strftime("%B %Y")
+    subject = (t.get("subject") or cs.DEFAULT_SUBJECT)
+    try:
+        subject = subject.format(customer=row["Customer"], company=cs.COMPANY, month=month)
+    except Exception:                                                     # noqa: BLE001
+        # An unknown placeholder is the user's typo, not a 500. Show the template verbatim so they
+        # can see what they typed rather than getting an opaque error.
+        # ⛔ W36-T42: THIS CAUGHT THREE OF THE WAYS `str.format` FAILS AND THERE ARE MORE.
+        # `{customer` is a ValueError, `{customer.x}` an AttributeError, `{customer:%Y}` a
+        # TypeError, and every one of them is the same user mistake this branch was written for.
+        # Naming a subset of the exception types turns a typo in the OTHER half into a 500 on the
+        # one screen somebody opens to avoid mailing 200 people the wrong thing.
+        pass
+    return {
+        "html": cs.render_statement_html(row, t.get("intro") or cs.DEFAULT_INTRO,
+                                         t.get("footer") or cs.DEFAULT_FOOTER),
+        "to": row.get("Email") or "",
+        "subject": subject,
+    }
+@router.post("/admin/statements/send")
+def send(body: dict = Body(default=None), session: Session = Depends(_gate)):
+    """Queue statements. Returns per-customer outcomes — NEVER a bare count.
+    `overrideTo` is the test-send path: one customer, one address. SAFE_MODE still applies (the
+    data layer refuses an address outside the allow-list), which is why the route does not check it.
+    """
+    cs = _cs()
+    body = body or {}
+    names = [str(n) for n in (body.get("customers") or []) if str(n).strip()]
+    if not names:
+        raise err(400, "bad_request", "name at least one customer")
+    # ⛔⛔ W36-T42 / D-299 — A DECLARED TEST SEND WITH NO ADDRESS REFUSES. IT DOES NOT BECOME A
+    # REAL ONE. This read `(body.get("overrideTo") or "").strip() or None`, so a caller who sent
+    # `overrideTo: ""` (the field left blank, the state not yet typed into, a trimmed-away space)
+    # got a REAL statement mailed to the debtor's own address, reported back as `test: false`. On
+    # the one route in this product that is allowed to write to Odoo, the difference between a
+    # rehearsal and mailing a live customer was one empty string.
+    #
+    # ⭐ THE DISCRIMINATOR IS THE CALLER'S DECLARATION, NOT THE VALUE. A body with no `overrideTo`
+    # key and no `test` flag is the PRODUCTION send, and refusing that would delete the feature
+    # D-299 exists to preserve. What can be refused is a caller who SAID this is a test: the key
+    # being present, or `test: true`, is that statement, and an empty address beside it is the
+    # mistake. So both spellings of "absent" are covered: the key present and blank, and `test`
+    # asserted with no key at all.
+    #
+    # ⚠ THIS IS THE SECOND OF THREE WALLS AND THE ONLY ONE A PAYLOAD CANNOT ROUTE AROUND.
+    # `automationApi.testSendStatement` refuses an empty address before the request is built, and
+    # SAFE_MODE refuses an address outside the allow-list inside `queue_statement`. The client
+    # wall is bypassable by construction (anything can POST); this one is not.
+    declared_test = ("overrideTo" in body) or bool(body.get("test"))
+    override = str(body.get("overrideTo") or "").strip()
+    if declared_test and not override:
+        raise err(400, "no_override_address",
+                  "a test send needs the address to send the test to. Without one this would "
+                  "mail the customer's own address, which is the opposite of a test")
+    override = override or None
+    if override and len(names) != 1:
+        raise err(400, "bad_request", "a test send takes exactly one customer")
+    t = body.get("templates") or {}
+    rows, _ = _rows()
+    sent, failed, skipped = [], [], []
+    for name in names:
+        row = _find(rows, name)
+        if row is None:
+            failed.append({"customer": name, "error": "not on the current collection list"})
+            continue
+        if not override and not row.get("Email"):
+            # The Streamlit page warned and skipped these. Reporting them SEPARATELY from failures
+            # keeps "we could not" distinct from "there was nowhere to send".
+            skipped.append({"customer": name, "reason": "no email address on the customer record"})
+            continue
+        try:
+            mid = cs.queue_statement(cs.Odoo(), row, t.get("subject") or cs.DEFAULT_SUBJECT,
+                                     t.get("intro") or cs.DEFAULT_INTRO,
+                                     t.get("footer") or cs.DEFAULT_FOOTER, override_to=override)
+            sent.append({"customer": name, "to": override or row.get("Email"), "mailId": mid})
+        except Exception as e:
+            # SafeModeBlocked lands here too, and that is correct: to the caller a guardrail refusal
+            # and an Odoo error are both "this one did not go", each with its own honest message.
+            failed.append({"customer": name, "error": str(e)[:200]})
+    return {"sent": sent, "failed": failed, "skipped": skipped,
+            "safeMode": bool(cs.SAFE_MODE), "test": bool(override)}
+# ---------------------------------------------------------------------------------------------
+# WAVE 35 · T36 / CONTRACT C8 / OWNER RULING R10 — THE AGENT'S PARKED BATCH.
+#
+# ⛔⛔ THE AGENT ASSEMBLES; A PERSON CLICKS SEND. `automation_engine.run_statements` renders a batch
+# and parks it on the automation definition, and it imports no mail path at all. THIS is the only
+# door that releases one, and it is deliberately built out of the parts already here:
+#   · `_gate` — `admin_gate` THEN `_royal_only`, byte-for-byte the dependency the other three
+#     endpoints use. Not a copy of the checks: the same object.
+#   · `cs.queue_statement` — the same call `send()` above makes, so SAFE_MODE's allow-list refusal
+#     happens in the DATA LAYER, where no route, payload or UI can reach around it.
+# ⇒ Nothing about the guardrails is re-expressed here, which is what makes "unchanged" checkable.
+#
+# ⚠ WHY THE BATCH IS RE-RENDERED FROM THE LIVE WORKLIST RATHER THAN SENT AS STORED. The parked
+# `html` is what a person APPROVED and is what the review screen shows; but a balance can move
+# between the parking and the click, and mailing a figure we know to be stale is worse than mailing
+# a fresh one. So the parked batch decides WHO and WITH WHAT WORDS, and the live row decides the
+# NUMBERS — the same split `preview` already makes. A customer who has left the worklist entirely
+# (they paid) is reported as skipped rather than invoiced.
+@router.get("/admin/statements/agent/{auto_id}")
+def agent_batch(auto_id: str, session: Session = Depends(_gate)):
+    """What is parked and waiting for a click, for ONE agent. `null` when nothing is."""
+    defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
+    pending = defn.get("pendingStatements")
+    if not isinstance(pending, dict):
+        return {"pending": None}
+    # ⚠ The rendered `html` is NOT returned in the list — a 200-statement batch of rendered mail is
+    # megabytes, and the review screen needs the count and the names to decide. `preview` already
+    # renders ONE on demand.
+    return {"pending": {
+        "ts": pending.get("ts"), "count": int(pending.get("count") or 0),
+        "notes": list(pending.get("notes") or []),
+        "items": [{k: v for k, v in it.items() if k != "html"}
+                  for it in (pending.get("items") or [])],
+        "safeMode": bool(_cs().SAFE_MODE)}}
+@router.post("/admin/statements/agent/{auto_id}/send")
+def agent_send(auto_id: str, body: dict = Body(default=None),
+               session: Session = Depends(_gate)):
+    """Release a parked batch. THE CLICK R10 REQUIRES — nothing else in the system calls this.
+    ⛔ IT REFUSES AN EMPTY OR MISSING BATCH rather than answering 200 with nothing sent: a send
+    that reports success and mails nobody is the `view_upsert` failure mode (200 OK, zero writes)
+    arriving on the one route in this system that talks to a mail server.
+    """
+    cs = _cs()
+    defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
+    pending = defn.get("pendingStatements")
+    items = list((pending or {}).get("items") or []) if isinstance(pending, dict) else []
+    if not items:
+        raise err(404, "no_batch", "there is nothing parked for this agent to send")
+    # ⚠ An explicit subset is allowed (a person unticking a customer on the review screen) but it
+    # may only NARROW the parked batch. A name that was never parked cannot be introduced by the
+    # payload, or the review stops being what authorised the send.
+    want = {str(n) for n in (body or {}).get("customers") or []}
+    if want:
+        items = [it for it in items if str(it.get("customer")) in want]
+        if not items:
+            raise err(400, "bad_request", "none of those customers are in the parked batch")
+    rows, _ = _rows()
+    sent, failed, skipped = [], [], []
+    for it in items:
+        name = str(it.get("customer") or "")
+        row = _find(rows, name)
+        if row is None:
+            skipped.append({"customer": name,
+                            "reason": "no longer on the collection list, so nothing is owed"})
+            continue
+        try:
+            # ⛔ THE SAME DATA-LAYER CALL `send()` MAKES. SafeModeBlocked is raised INSIDE
+            # `queue_statement`, so the guardrail cannot be argued with from here.
+            mid = cs.queue_statement(cs.Odoo(), row,
+                                     str(it.get("subject") or "") or cs.DEFAULT_SUBJECT,
+                                     cs.DEFAULT_INTRO, cs.DEFAULT_FOOTER)
+            sent.append({"customer": name, "to": row.get("Email"), "mailId": mid})
+        except Exception as e:                                        # noqa: BLE001
+            failed.append({"customer": name, "error": str(e)[:200]})
+    # ⚠ CLEARED ONLY WHEN NOTHING IS LEFT TO RETRY. A batch dropped while some of it failed would
+    # lose the list of who still needs a statement, and nobody would know to look.
+    if sent and not failed:
+        engine.clear_statements(session.runtime, auto_id)
+    return {"sent": sent, "failed": failed, "skipped": skipped,
+            "safeMode": bool(cs.SAFE_MODE), "cleared": bool(sent and not failed)}

api/routes_tables.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

api/routes_web_agent.py CHANGED Viewed

@@ -1,84 +1,84 @@
-"""routes_web_agent.py — the door that lets a person TEST the web agent (wave 31, R10 / D-51).
-The owner's words are the whole reason this file exists: *"we already laid the foundation of this
-but never test anything."* The capability is otherwise reachable only from inside an automation
-run, which means the first person to discover it is broken is a customer at 3am.
-    GET  /api/v1/web-agent/capability   any session   — can this deployment run a web step, and
-                                                        if not, the SENTENCE saying why
-    POST /api/v1/web-agent/test         ADMIN         — run one real `web_read` and show what
-                                                        came back, or the sentence
-⛔ NEITHER ROUTE IS THE SEAM. `automation_engine` calls `web_agent.run_step` directly (contract
-C5); these are an operator surface over the same function, so a green test here and a red run
-there cannot disagree about anything except the input.
-⚠ `POST /test` BLOCKS FOR ~10-30 s and COSTS A FRACTION OF A CENT. It is `def`, not `async def`,
-so FastAPI runs it in the threadpool and one test cannot stall the event loop for everybody.
-⚠ ON THE URL IT WILL FETCH: the fetch happens inside an ephemeral HF Job on Hugging Face's
-network, never from this server, so this is not a door into our own infrastructure. It is still
-admin-gated, because it spends money and because D-51 §5's authorisation posture ("only systems
-the tenant is authorised to use, at their instruction") is not something an ordinary member
-should be able to commit the tenant to.
-⭐ MOUNTED, and the gate is what says so rather than this sentence: `main.py:80` imports it and
-`main.py:316` includes it, and `verify_web_agent.py` asserts the route answers rather than trusting
-either line. This paragraph read "NOT MOUNTED YET" for a whole wave after the mount landed, which
-is the same class of stale claim as a green gate on a router nobody wired: three finished routers
-once shipped 404-dead behind entirely green gates, and prose is not the control that stops it.
-"""
-from fastapi import APIRouter, Body, Depends
-import web_agent
-from deps import Session, require_session, err
-from routes_admin import admin_gate
-router = APIRouter(prefix="/api/v1")
-MAX_URL = 2000
-MAX_SELECTOR = 400
-@router.get("/web-agent/capability")
-def web_agent_capability(session: Session = Depends(require_session)):
-    """Can a web step run here at all? Configuration, not liveness — see `web_agent.capability`.
-    Deliberately NARROW: it answers the question a UI needs ("may I offer this, and what do I say
-    if not") and withholds the deployment detail (namespace, which token key, the image) that
-    only an operator has any use for. Nothing here is ever a credential.
-    """
-    cap = web_agent.capability()
-    return {"ready": bool(cap["ready"]), "reason": cap["reason"],
-            "runnableKinds": cap["runnableKinds"], "profile": cap["profile"]}
-@router.post("/web-agent/test")
-def web_agent_test(session: Session = Depends(admin_gate), body: dict = Body(...)):
-    """Run ONE real `web_read` and report exactly what the seam returned.
-    The response mirrors the seam's own contract rather than flattening it: `ok` plus a `value`,
-    or `ok:false` plus the SENTENCE. A test surface that turns a named failure into "something
-    went wrong" would hide the one thing it exists to show.
-    """
-    url = str(body.get("url") or "").strip()
-    selector = str(body.get("selector") or "").strip()
-    if len(url) > MAX_URL or len(selector) > MAX_SELECTOR:
-        raise err(400, "too_long", "the URL or selector is longer than this door accepts")
-    step = {"kind": "web_read", "id": "test", "url": url, "selector": selector,
-            "attr": (body.get("attr") or "text"), "all": bool(body.get("all")),
-            "timeoutMs": int(body.get("timeoutMs") or 20000)}
-    if body.get("waitFor"):
-        step["waitFor"] = str(body["waitFor"])
-    notes = []
-    result, error = web_agent.run_step(
-        step, {"tenant": session.tenant, "runId": f"test-{session.tenant}-{session.uname}",
-               "log": notes.append})
-    if error:
-        # 200 with `ok:false`, not a 4xx: the request was well-formed and the ANSWER is that the
-        # web step did not succeed. A 500 here would make an ordinary "the selector matched
-        # nothing" look like a server fault.
-        return {"ok": False, "error": error, "log": notes[-6:]}
-    return {"ok": True, "result": result, "log": notes[-6:]}

+"""routes_web_agent.py — the door that lets a person TEST the web agent (wave 31, R10 / D-51).
+The owner's words are the whole reason this file exists: *"we already laid the foundation of this
+but never test anything."* The capability is otherwise reachable only from inside an automation
+run, which means the first person to discover it is broken is a customer at 3am.
+    GET  /api/v1/web-agent/capability   any session   — can this deployment run a web step, and
+                                                        if not, the SENTENCE saying why
+    POST /api/v1/web-agent/test         ADMIN         — run one real `web_read` and show what
+                                                        came back, or the sentence
+⛔ NEITHER ROUTE IS THE SEAM. `automation_engine` calls `web_agent.run_step` directly (contract
+C5); these are an operator surface over the same function, so a green test here and a red run
+there cannot disagree about anything except the input.
+⚠ `POST /test` BLOCKS FOR ~10-30 s and COSTS A FRACTION OF A CENT. It is `def`, not `async def`,
+so FastAPI runs it in the threadpool and one test cannot stall the event loop for everybody.
+⚠ ON THE URL IT WILL FETCH: the fetch happens inside an ephemeral HF Job on Hugging Face's
+network, never from this server, so this is not a door into our own infrastructure. It is still
+admin-gated, because it spends money and because D-51 §5's authorisation posture ("only systems
+the tenant is authorised to use, at their instruction") is not something an ordinary member
+should be able to commit the tenant to.
+⭐ MOUNTED, and the gate is what says so rather than this sentence: `main.py:80` imports it and
+`main.py:316` includes it, and `verify_web_agent.py` asserts the route answers rather than trusting
+either line. This paragraph read "NOT MOUNTED YET" for a whole wave after the mount landed, which
+is the same class of stale claim as a green gate on a router nobody wired: three finished routers
+once shipped 404-dead behind entirely green gates, and prose is not the control that stops it.
+"""
+from fastapi import APIRouter, Body, Depends
+import web_agent
+from deps import Session, require_session, err
+from routes_admin import admin_gate
+router = APIRouter(prefix="/api/v1")
+MAX_URL = 2000
+MAX_SELECTOR = 400
+@router.get("/web-agent/capability")
+def web_agent_capability(session: Session = Depends(require_session)):
+    """Can a web step run here at all? Configuration, not liveness — see `web_agent.capability`.
+    Deliberately NARROW: it answers the question a UI needs ("may I offer this, and what do I say
+    if not") and withholds the deployment detail (namespace, which token key, the image) that
+    only an operator has any use for. Nothing here is ever a credential.
+    """
+    cap = web_agent.capability()
+    return {"ready": bool(cap["ready"]), "reason": cap["reason"],
+            "runnableKinds": cap["runnableKinds"], "profile": cap["profile"]}
+@router.post("/web-agent/test")
+def web_agent_test(session: Session = Depends(admin_gate), body: dict = Body(...)):
+    """Run ONE real `web_read` and report exactly what the seam returned.
+    The response mirrors the seam's own contract rather than flattening it: `ok` plus a `value`,
+    or `ok:false` plus the SENTENCE. A test surface that turns a named failure into "something
+    went wrong" would hide the one thing it exists to show.
+    """
+    url = str(body.get("url") or "").strip()
+    selector = str(body.get("selector") or "").strip()
+    if len(url) > MAX_URL or len(selector) > MAX_SELECTOR:
+        raise err(400, "too_long", "the URL or selector is longer than this door accepts")
+    step = {"kind": "web_read", "id": "test", "url": url, "selector": selector,
+            "attr": (body.get("attr") or "text"), "all": bool(body.get("all")),
+            "timeoutMs": int(body.get("timeoutMs") or 20000)}
+    if body.get("waitFor"):
+        step["waitFor"] = str(body["waitFor"])
+    notes = []
+    result, error = web_agent.run_step(
+        step, {"tenant": session.tenant, "runId": f"test-{session.tenant}-{session.uname}",
+               "log": notes.append})
+    if error:
+        # 200 with `ok:false`, not a 4xx: the request was well-formed and the ANSWER is that the
+        # web step did not succeed. A 500 here would make an ordinary "the selector matched
+        # nothing" look like a server fault.
+        return {"ok": False, "error": error, "log": notes[-6:]}
+    return {"ok": True, "result": result, "log": notes[-6:]}

platform/aios_grid.py CHANGED Viewed

@@ -643,7 +643,18 @@ def clean_measure_field(raw, offered):
         "custom": True,
         "derived": True,
         "filterable": False,
-        "agg": "sum" if mtype in ("currency", "int") else None,
         "note": str(raw.get("note") or "")[:2000],
         "measure": {"key": str(spec.get("key"))[:80], "window": window},
     }
@@ -735,7 +746,14 @@ def fields_from_workspace(workspace=None, cohorts=False, scope_key=None, fields_
                 "custom": True,
                 "derived": True,
                 "filterable": False,
-                "agg": "sum" if mtype in ("currency", "int") else None,
                 "note": str(field.get("note") or "")[:2000],
                 "measure": {"key": mkey[:80], "window": window},
                 **_field_extras(field, mtype),
@@ -2016,6 +2034,30 @@ def clean_folders(raw):
             icon = clean_folder_icon(f.get("icon"))      # wave-9 I15 (C5); absent = default mark
             if icon:
                 row["icon"] = icon
             items.append(row)
         items.sort(key=lambda x: x["order"])
         for i, f in enumerate(items):

         "custom": True,
         "derived": True,
         "filterable": False,
+        # W41-T21 (owner instruction 16): every numeric measure column arrives with a column
+        # summary, `pct` included. A pct measure used to fall through to `agg: None`, so a
+        # percentage column could never total at the bottom or per group.
+        # It defaults to AVERAGE rather than sum ON PURPOSE: twenty rows of 20% would "total"
+        # 400%, a number nobody can use. Currency and int keep `sum`. `average` is a member
+        # of FIELD_AGGS, which is the vocabulary the saved-field passthrough at the bottom
+        # of `fields_from_workspace` filters against, so it is not nulled on the way out.
+        # Do not tidy the pct arm back to `sum`. The `else None` arm stays fail closed for
+        # any future member of MEASURE_FIELD_TYPES that is not summable; today the `mtype`
+        # fallback above makes it unreachable.
+        "agg": ("average" if mtype == "pct"
+                else "sum" if mtype in ("currency", "int") else None),
         "note": str(raw.get("note") or "")[:2000],
         "measure": {"key": str(spec.get("key"))[:80], "window": window},
     }
                 "custom": True,
                 "derived": True,
                 "filterable": False,
+                # W41-T21: the SAVED half of the same default, and it must stay identical to
+                # `clean_measure_field`. A measure column already sitting in somebody's
+                # workspace is rebuilt HERE, not there, so stamping only the create door would
+                # leave every existing pct column with no summary and ship the feature half
+                # dead. `pct` averages (a summed percentage is meaningless), currency and int
+                # sum. Do not tidy the pct arm back to `sum`.
+                "agg": ("average" if mtype == "pct"
+                        else "sum" if mtype in ("currency", "int") else None),
                 "note": str(field.get("note") or "")[:2000],
                 "measure": {"key": mkey[:80], "window": window},
                 **_field_extras(field, mtype),
             icon = clean_folder_icon(f.get("icon"))      # wave-9 I15 (C5); absent = default mark
             if icon:
                 row["icon"] = icon
+            # W41-T12 / T33 / OWNER INSTRUCTION 12 -- `parent` SURVIVES THIS FUNCTION NOW.
+            # THIS ONE LINE IS WHY NESTING WAS DEAD. Every other half shipped and worked:
+            # `ViewSidebar.tsx:316` takes a `parent`, `CustomerGrid.tsx:7432` puts it on the wire,
+            # `table_store.validate_folder_tree` refuses cycles and chains over `MAX_FOLDER_DEPTH`
+            # with a worded receipt, and `grid_events` already catches `FolderTreeError` into
+            # `_folder_refuse`. This row build STRIPPED the key on the way in, so the validator
+            # could never fire and a folder made inside a folder was gone on refresh -- a feature
+            # dead behind four correct halves and every gate green. `grid_events.py` stated the
+            # forward contract itself: "the day `clean_folders` learns `parent`, the refusal is
+            # already wired and worded". This is that day.
+            #
+            # ABSENT, NEVER `None`, and never invented. An absent `parent` IS the root, which is
+            # what every stored row has meant until now -- and `validate_folder_tree` promises that
+            # a payload carrying no `parent` anywhere comes back byte-identical with zero repairs,
+            # so writing a null key would break that promise for no gain.
+            # SELF-PARENTING IS DROPPED HERE as well as refused downstream: the validator raises
+            # `cycle` on it, and a row that cannot be legal should not reach the validator wearing
+            # a repair. A parent naming a folder that is GONE is deliberately NOT dropped here --
+            # deleting a folder creates exactly that, and `validate_folder_tree` repairs it to the
+            # root WITH a receipt the user can read. Dropping it silently here would destroy the
+            # receipt, and the user would never learn their folder had moved.
+            parent = str(f.get("parent") or "").strip()[:80]
+            if parent and parent != fid:
+                row["parent"] = parent
             items.append(row)
         items.sort(key=lambda x: x["order"])
         for i, f in enumerate(items):

platform/aios_grid_fields.json CHANGED Viewed

@@ -329,6 +329,14 @@
         "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."
       },
       {
         "key": "product",
         "label": "Product",
@@ -791,6 +799,140 @@
         "default": false,
         "shared": true,
         "description": "Team-maintained. The 2027 workbook's own non-Odoo columns (Product Description, Packing) folded into one field. Shared with everyone in the workspace."
       }
     ]
   }

         "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."
       },
+      {
+        "key": "product_id",
+        "label": "Odoo ID",
+        "type": "int",
+        "source": "odoo",
+        "default": false,
+        "description": "The Odoo product.product id, the key every Odoo document joins on. Carried on the row rather than derived, because a product's pid is a CRC32 of its SKU and the id cannot be recovered from it."
+      },
       {
         "key": "product",
         "label": "Product",
         "default": false,
         "shared": true,
         "description": "Team-maintained. The 2027 workbook's own non-Odoo columns (Product Description, Packing) folded into one field. Shared with everyone in the workspace."
+      },
+      {
+        "key": "sub_category",
+        "label": "Sub-Category",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "Fine grained product class from the Daily Mastersheet. Owned by the Administration account and shared with everyone in the workspace. Blank means the mastersheet carries no value for this SKU."
+      },
+      {
+        "key": "main_category",
+        "label": "Main Category",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "Top level product class from the Daily Mastersheet. Owned by the Administration account and shared with everyone in the workspace. Blank means the mastersheet carries no value for this SKU."
+      },
+      {
+        "key": "color",
+        "label": "Color",
+        "type": "multiselect",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "Colors this SKU is offered in, from the Daily Mastersheet. Multi-select, because the sheet stores several colors in one comma separated cell and each one becomes its own value. Owned by the Administration account and shared with everyone in the workspace."
+      },
+      {
+        "key": "shape_style",
+        "label": "Shape/Style",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "Shape or styling of the piece, from the Daily Mastersheet. Owned by the Administration account and shared with everyone in the workspace. Blank means the mastersheet carries no value for this SKU."
+      },
+      {
+        "key": "material",
+        "label": "Material",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "What the piece is made of, from the Daily Mastersheet. Owned by the Administration account and shared with everyone in the workspace. Blank means the mastersheet carries no value for this SKU."
+      },
+      {
+        "key": "finish",
+        "label": "Finish",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "Surface finish of the piece, from the Daily Mastersheet. Owned by the Administration account and shared with everyone in the workspace. Blank means the mastersheet carries no value for this SKU."
+      },
+      {
+        "key": "occassion",
+        "label": "Occassion",
+        "type": "multiselect",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "Occasions this SKU is bought for, from the Daily Mastersheet. Multi-select, because the sheet stores several occasions in one comma separated cell and each one becomes its own value. The label keeps the mastersheet's own spelling. Owned by the Administration account and shared with everyone in the workspace."
+      },
+      {
+        "key": "collection",
+        "label": "Collection",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "The merchandising collection this SKU belongs to, from the Daily Mastersheet. Owned by the Administration account and shared with everyone in the workspace. Blank means the mastersheet carries no value for this SKU."
+      },
+      {
+        "key": "size",
+        "label": "Size",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "preset": false,
+        "shared": true,
+        "createdBy": "admin",
+        "permissions": {
+          "edit": "collaborative"
+        },
+        "description": "Size band from the Daily Mastersheet. Owned by the Administration account and shared with everyone in the workspace. Blank means the mastersheet carries no value for this SKU."
+      },
+      {
+        "key": "upc",
+        "label": "UPC",
+        "type": "text",
+        "source": "odoo",
+        "default": false,
+        "description": "The SKU's barcode, read live from Odoo as product.product.barcode. Blank when Odoo carries no barcode for this product. The Daily Mastersheet has a UPC column of its own and it is deliberately not used: three quarters of it is a placeholder rather than a number."
       }
     ]
   }

platform/core/field_permissions.py CHANGED Viewed

@@ -6,6 +6,8 @@ that could never be true.  This module is the single normalization point for the
 personal, collaborative, or specific users.
 """
 import core.shared_overlay as shared_overlay
 import core.shares as shares
@@ -14,6 +16,28 @@ FIELD_EDIT_MODES = ("personal", "collaborative", "users")
 MAX_FIELD_USERS = 50
 _ALIASES = {"everyone": "collaborative", "creator": "personal", "admins": "personal"}
 def clean_permissions(raw, fallback="personal", known_users=None):
     """Return a small, canonical field permission bag or ``None`` for malformed input."""
@@ -115,6 +139,269 @@ def permissions_from_grants(entries):
     return clean_permissions({"edit": "users", "users": sorted(users)})
 def _same_classification(left, right):
     """Do two canonical bags say the same thing about WHO?
@@ -213,6 +500,149 @@ def reconcile_shared_permissions(shared_key, grant_topic, st=None):
     return rewritten
 def _field_is_migratable(field):
     return (isinstance(field, dict) and field.get("custom") is True
             and field.get("source") == "overlay")
@@ -229,7 +659,8 @@ def migrate_legacy_fields(table_key, st=None, known_users=None, grant_topic=None
     grant_key = str(grant_topic or key).strip()
     shared_key = str(shared_key or key).strip()
     if not key or st is None:
-        return {"promoted": 0, "normalized": 0, "reclassified": 0}
     # ⭐⭐ W40-T03 — RECONCILE THE SHARED STRATUM'S CLASSIFICATION FIRST, IN ITS OWN SWALLOWING
     # GUARD. This is the ONE seam that reaches every shared-field surface: all three readers
     # (`routes_customers.shared_fields`, `routes_tables._ut_shared_fields`,
@@ -254,15 +685,21 @@ def migrate_legacy_fields(table_key, st=None, known_users=None, grant_topic=None
     try:
         document = st.get(key) or {}
     except Exception:
-        return {"promoted": 0, "normalized": 0, "reclassified": reclassified}
     if not isinstance(document, dict):
-        return {"promoted": 0, "normalized": 0, "reclassified": reclassified}
     promoted = 0
     normalized = 0
     remove = {}
     for owner, workspace in document.items():
-        if owner == "__shared__" or not isinstance(workspace, dict):
             continue
         fields = workspace.get("fields") or {}
         if not isinstance(fields, dict):
@@ -270,6 +707,15 @@ def migrate_legacy_fields(table_key, st=None, known_users=None, grant_topic=None
         for field_key, original in list(fields.items()):
             if not _field_is_migratable(original):
                 continue
             permissions = stored_permissions(original, fallback="collaborative",
                                              known_users=known_users)
             if permissions["edit"] == "personal":
@@ -327,10 +773,42 @@ def migrate_legacy_fields(table_key, st=None, known_users=None, grant_topic=None
                                 values.pop(field_key, None)
                 return data
         st.update(key, _remove, flush="sync")
     # ⛔ `promoted` AND `normalized` KEEP THEIR NAMES AND THEIR MEANINGS.
     # `aios-web/api/verify_field_permissions.py` asserts `result["promoted"] == 1`; renaming or
     # folding either into the new count would turn a green gate red for a change it never made.
-    return {"promoted": promoted, "normalized": normalized, "reclassified": reclassified}
 def promote_field(workspace_key, shared_key, grant_topic, owner, field, st=None):
@@ -391,6 +869,13 @@ def promote_field(workspace_key, shared_key, grant_topic, owner, field, st=None)
         for values in (ws.get("overlays") or {}).values():
             if isinstance(values, dict):
                 values.pop(key, None)
         return data
     st.update(workspace_key, _remove, flush="sync")
     return shared
@@ -424,3 +909,93 @@ def demote_field(workspace_key, shared_key, grant_topic, field, st=None):
     shared_overlay.drop_field(shared_key, key, st=st)
     shares.drop_objects([("field", shares.field_oid(grant_topic, key))], st=st)
     return personal

 personal, collaborative, or specific users.
 """
+import time
 import core.shared_overlay as shared_overlay
 import core.shares as shares
 MAX_FIELD_USERS = 50
 _ALIASES = {"everyone": "collaborative", "creator": "personal", "admins": "personal"}
+#: ⭐⭐ W41-T01 / RULING R5 / CONTRACT C1 — THE THREE BADGES' VOCABULARIES, DECLARED ONCE.
+#: R5: *"A field is classified by THREE badges, and every right derives from them: Origin
+#: (`Pre-set` = the platform made it / blank = a person made it) x Audience (`Private` /
+#: `Shared by <name>` / `Everyone`) x Values (`Shared values` = one value everyone sees / blank =
+#: yours alone)."* A consumer greps ONE place for the spellings; nothing derives a badge
+#: independently.
+FIELD_ORIGINS = ("preset", "user")
+FIELD_AUDIENCES = ("private", "users", "everyone")
+FIELD_VALUE_STRATA = ("shared", "personal")
+#: `permissions_from_grants`' edit vocabulary -> C1's audience vocabulary. The two answer the SAME
+#: question in different words (who can reach this column), so this map is the whole of the
+#: translation and there is no second derivation to drift from it
+#: ([[one-evaluator-per-question]]). ⛔ It is a MAP rather than a branch on purpose: a mode this
+#: dict does not name falls to `private`, which is the fail-closed direction.
+_AUDIENCE_FROM_EDIT = {"collaborative": "everyone", "users": "users", "personal": "private"}
+def _uname(value):
+    """One spelling of a username, everywhere in this module."""
+    return str(value or "").strip().lower()
 def clean_permissions(raw, fallback="personal", known_users=None):
     """Return a small, canonical field permission bag or ``None`` for malformed input."""
     return clean_permissions({"edit": "users", "users": sorted(users)})
+# --------------------------------------------------------------- W41-T01 / R5 / C1: the badges
+def _governed(field):
+    """Does the per-field grant WALL apply to this column?
+    ⛔ ONE EVALUATOR, AND IT IS `perm_scope`'s. `granted_field_keys` is the cheap half of
+    `field_grant_hidden`; asking it here is what makes the BADGE and the WALL incapable of
+    disagreeing, which is this ticket's own acceptance. Re-spelling `f.get('granted') is True`
+    locally would be a second reader of the mark, and a second reader is how the two come apart.
+    ⛔ THE IMPORT IS LAZY, MATCHING `field_grant_hidden`'s OWN `import core.shares` AT ITS CALL
+    SITE. `perm_scope` pulls `core.perms` -> `context`/`registry`/`users`; this module is imported
+    lazily from `grid_events` precisely to stay cheap, and a top-level import here would widen its
+    graph for every importer to buy nothing.
+    """
+    try:
+        import core.perm_scope as perm_scope
+    except Exception:                                           # noqa: BLE001
+        # Unresolvable means "not governed": the badge then reports the column's OTHER, true
+        # properties instead of asserting a permission state it cannot verify. The wall itself
+        # does not degrade with it — it lives in `perm_scope` and is unreachable from here.
+        return False
+    return bool(perm_scope.granted_field_keys([field] if isinstance(field, dict) else []))
+def field_origin(field):
+    """R5's FIRST badge: `"preset"` (the platform made this column) or `"user"` (a person did).
+    ⛔ READ OFF MARKS THAT ALREADY EXIST, AND NO NEW ONE IS INVENTED. There are exactly two kinds
+    of positive evidence that a PERSON made a column, and both are already written by the create
+    doors: `custom: True` (`grid_events.field_upsert`) and `createdBy` (stamped at create and
+    preserved from `prior` on every later write). A contract-declared column carries neither —
+    `aios_grid_fields.json` names only `key/label/type/source/default/description/shared/...` — so
+    Supplier and every canonical Odoo column answer `"preset"` without a mark being added to the
+    contract file.
+    ⚠ `automation.preset` IS CHECKED FIRST AND IT WINS. It is the platform's own positive mark
+    (`automation_engine.ut_ensure(lock_fields=True)`), so a seeded column that somehow also carries
+    an author stays `"preset"`. ⛔ AND THE `type != 'rollup'` LEG OF THE CLIENT'S
+    `isSchemaLocked` IS DELIBERATELY NOT REPEATED HERE: that leg answers *"may this be edited"*
+    (`user_tables.preset_editable` returns True for exactly `rollup`), which is a RIGHT derived
+    from the badge, not the badge. A preset rollup was still made by the platform.
+    ⚠ ABSENCE FALLS TO `"preset"`, AND THE POLARITY IS THE CONSERVATIVE ONE. Rights derive from
+    this badge, so calling a platform column user-made is the direction that would offer somebody
+    a delete they must not have; calling a user column platform-made is cosmetic and visible.
+    ⛔ KNOWN GAP, OUT OF THIS TICKET'S FENCE: on a `ut_*` database `user_tables._clean_field` is a
+    strict allowlist that rebuilds `out` from scratch and keeps neither `custom` nor `createdBy`
+    (it does keep `automation`), so a user-created column there has no author mark left to read and
+    answers `"preset"`. That is a defect in the allowlist, not in this derivation, and it does not
+    reach `customer_data` or `product_data`, whose definitions keep both marks.
+    """
+    if not isinstance(field, dict):
+        return "preset"
+    automation = field.get("automation")
+    if isinstance(automation, dict) and automation.get("preset") is True:
+        return "preset"
+    if field.get("custom") is True or _uname(field.get("createdBy")):
+        return "user"
+    return "preset"
+def _shared_value_keys(table_key, st=None):
+    """The columns of `table_key` whose VALUES are one tenant-wide stratum."""
+    key = str(table_key or "").strip()
+    if not key:
+        return set()
+    try:
+        return {str(k) for k in shared_overlay.fields(key, st=st)}
+    except Exception:                                           # noqa: BLE001
+        return set()
+def _empty_record():
+    return {"owner": None, "entries": []}
+def _grant_record(field_key, table_key=None, grant_topic=None, st=None):
+    """ONE column's grant record, read straight from the registry."""
+    topic = str(grant_topic or table_key or "").strip()
+    key = str(field_key or "").strip()
+    if not topic or not key:
+        return _empty_record()
+    try:
+        return shares.grants("field", shares.field_oid(topic, key), st=st)
+    except Exception:                                           # noqa: BLE001
+        return _empty_record()
+def grant_records(grant_topic, st=None):
+    """`{field_key: {'owner', 'entries'}}` for one topic, on **ONE** read of `object_shares`.
+    ⭐⭐ THE BATCH EXISTS FOR A MEASURED REASON, NOT FOR TIDINESS. `shares.grants` opens the
+    registry per call and `store.get` hands back `json.loads(json.dumps(...))` — a fresh deep copy
+    every time. Badging a customer grid is 40-60 columns, so the per-field door is 40-60
+    serialise/deserialise round trips added to the hot read path. That is the exact shape
+    `grid_assembly`'s own W38-T20 note spent a ticket removing (*"three consumers want this dict on
+    one request, and letting each take its own copy is the shape D-214 spent a whole ticket
+    removing one document over"*).
+    ⛔ THE ENTRIES GO THROUGH `shares._clean_entries`, WHICH IS NOT OPTIONAL AND IS NOT TIDYING.
+    That normaliser DROPS an entry whose role is not in `shares.ROLES`, and `permissions_from_grants`
+    checks only the user. Reading the bucket raw would let a junk-role entry make this badge say
+    `users` while `shares.role_for` — which reads through `grants()`, i.e. through the normaliser —
+    walls that same person out. A badge that disagrees with the wall is precisely what R5's
+    *"every right derives from them"* forbids. Same normaliser, therefore same answer.
+    ⚠ THE TOPIC IS THE GRANT TOPIC, NOT THE BUCKET. `migrate_legacy_fields` already carries this
+    warning in full: `shared_key` names the store bucket (`customer_table_workspace__shared`) and
+    `grant_topic` names the registry namespace (`customer_data`). Handing this one the bucket finds
+    no record for any column and every badge silently reads as never-shared.
+    """
+    topic = str(grant_topic or "").strip()
+    if not topic:
+        return {}
+    try:
+        bucket = (shares._st(st).get(shares.SHARES_KEY) or {}).get("field") or {}
+    except Exception:                                           # noqa: BLE001
+        return {}
+    if not isinstance(bucket, dict):
+        return {}
+    out = {}
+    for oid, rec in bucket.items():
+        table, key = shares.split_field_oid(oid)
+        # `split_field_oid` FAILS CLOSED on junk (`(None, None)`), so an unparseable id is skipped
+        # rather than being attributed to whichever database is being read.
+        if table != topic or not key or not isinstance(rec, dict):
+            continue
+        out[key] = {"owner": (_uname(rec.get("owner")) or None),
+                    "entries": shares._clean_entries(rec.get("entries"))}
+    return out
+def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None,
+                values_shared=None, st=None):
+    """⭐⭐ W41-T01 / R5 / CONTRACT C1 — **THE ONE PRODUCER OF A FIELD'S THREE BADGES.**
+    Returns `{origin, audience, sharedBy, values, owner}` and nothing else derives a badge
+    independently. The five member spellings are C1's and they are the wire's: the payload key is
+    `class`, its members are `origin`, `audience`, `sharedBy`, `values`, `owner`.
+    `viewer` is a USERNAME STRING (`session.uname`), never a user dict — a dict compares unequal to
+    every stored name, which would make `sharedBy` silently never match and `owner` never equal the
+    reader.
+    **origin** — `field_origin`, above.
+    **audience** — `private` | `users` | `everyone`, and it MIRRORS THE WALL rather than paraphrasing
+    it, because a badge that says something the wall does not enforce is worse than no badge:
+      * a column carrying `perm_scope.FIELD_GRANT_MARK` is GOVERNED, so the registry answers,
+        through the existing `permissions_from_grants` (extended, never duplicated): a `*` grant is
+        `everyone`, named grants are `users`, no grant at all is `private`;
+      * an UNGOVERNED column is not walled by `field_grant_hidden` at all, so whoever holds the
+        database holds the column. It is therefore `everyone` when the column is tenant-wide — a
+        contract-declared one (Supplier, and every canonical Odoo column) or one living in the
+        shared stratum — and `private` when it is not, because a per-user definition exists only in
+        its creator's own stratum and no other account ever receives it.
+    ⭐ SUPPLIER IS THE CASE THE THIRD BADGE EXISTS FOR, AND IT IS WHY THE CONTRACT LEG IS NOT
+    OPTIONAL. It answers `everyone` while having NO `object_shares` row at all — its audience comes
+    from the contract that declared it, not from the registry, which is exactly why `ShareDialog`
+    prints "Not shared with anyone yet." about a column the whole workspace can already read.
+    ⛔ THE TRAP, AND IT IS THIS TICKET'S OWN: `shared_overlay`'s `"shared": True` IS WRITTEN AND
+    NEVER READ (D-414). It is not consulted anywhere here. `FIELD_GRANT_MARK` is the only flag the
+    wall reads, so it is the only flag this function reads, and tenant-wide-ness is answered by
+    MEMBERSHIP (`values_shared`) rather than by that stale boolean.
+    ⚠ A ROUTE COLUMN MINTED BEFORE THE MARK EXISTED THEREFORE READS `everyone`, AND THAT IS THE
+    TRUTH RATHER THAN A MISS. Such a column carries `shared: True` alone, is not `granted`, and
+    genuinely leaks to the whole tenant; the badge reports the leak instead of papering over it.
+    Closing it is W41-T05's work, and this badge is how it becomes visible.
+    **sharedBy** — who shared it TO this viewer, or `None`. `shares.grants` carries `by` per entry
+    (D-474) and the owner is the fallback when a pre-D-474 record has none. `None` when the viewer
+    IS the owner, when nobody shared it, or when the viewer shared it to themselves.
+    ⚠ IT IS EMITTED UNDER AN `everyone` AUDIENCE TOO, not only under `users`. R5 renders the three
+    as alternative states of one badge, so a consumer that only wants a name for `Shared by <name>`
+    reads it under `users` and ignores it otherwise — but the fact ("alice let you in") is true in
+    both, and withholding it would make the producer decide a rendering question that belongs to
+    the consumer.
+    **values** — `shared` when this column's VALUES are one stratum everyone sees (membership of
+    `shared_overlay.fields()` for an overlay topic, or a module's `SHARED_KEYS()` for a
+    contract-declared one), else `personal`. This is R5's new information and it is INDEPENDENT of
+    audience: a route column is `private` with `shared` values, Supplier is `everyone` with `shared`
+    values, and a column you made is `private` with `personal` ones.
+    ⚠ `values_shared` IS LENT BY THE CALLER because the key set is a MODULE-level fact
+    (`product_data.SHARED_KEYS()`), and `core` never imports up. Absent, it is derived from
+    `shared_overlay.fields(table_key)`, which is right for an overlay topic and blind to a
+    contract-declared one.
+    **owner** — the registry's owner, falling back to the definition's `createdBy` when the
+    registry has no record. ⚠ THE FALLBACK IS NOT BELT-AND-BRACES: the create door writes the
+    definition FIRST and claims the grant SECOND, on purpose, so the window where a column exists
+    unclaimed is real. `field_grant_hidden` already relies on exactly this fallback to stop a
+    creator being walled out of the column they just made.
+    """
+    field = field if isinstance(field, dict) else {}
+    key = str(field.get("key") or "").strip()
+    me = _uname(viewer)
+    origin = field_origin(field)
+    record = grants if isinstance(grants, dict) else _grant_record(
+        key, table_key=table_key, grant_topic=grant_topic, st=st)
+    owner = _uname(record.get("owner")) or None
+    entries = [e for e in (record.get("entries") or ()) if isinstance(e, dict)]
+    if values_shared is None:
+        values_shared = _shared_value_keys(table_key, st=st)
+    values = "shared" if key and key in {str(k) for k in values_shared} else "personal"
+    if _governed(field):
+        audience = _AUDIENCE_FROM_EDIT.get(
+            permissions_from_grants(entries).get("edit"), "private")
+    elif values == "shared" or origin == "preset":
+        # Ungoverned AND tenant-wide: the database's holders all hold this column. `origin` covers
+        # a contract-declared column whose VALUES are per-user (a canonical Odoo column); the
+        # `values` leg covers a shared-stratum column the contract never named.
+        audience = "everyone"
+    else:
+        audience = "private"
+    shared_by = None
+    if me and me != owner:
+        mine = next((e for e in entries if _uname(e.get("user")) == me), None)
+        room = next((e for e in entries if _uname(e.get("user")) == shares.EVERYONE), None)
+        entry = mine if mine is not None else room
+        if entry is not None:
+            shared_by = _uname(entry.get("by")) or owner
+    if shared_by == me:
+        shared_by = None
+    return {"origin": origin, "audience": audience, "sharedBy": shared_by,
+            "values": values, "owner": owner or _uname(field.get("createdBy")) or None}
+def field_classes(fields, viewer, *, table_key=None, grant_topic=None, values_shared=None,
+                  st=None):
+    """`{field_key: <C1 bag>}` for a whole field list, on ONE registry read. See `grant_records`.
+    ⚠ EVERY COLUMN GETS A BAG, INCLUDING ONE THE REGISTRY HAS NEVER HEARD OF: the missing record is
+    substituted explicitly rather than left to `field_class` to re-read, which is what keeps the
+    single read single.
+    """
+    topic = str(grant_topic or table_key or "").strip()
+    records = grant_records(topic, st=st)
+    if values_shared is None:
+        values_shared = _shared_value_keys(table_key, st=st)
+    shared_keys = {str(k) for k in (values_shared or ())}
+    out = {}
+    for field in (fields or ()):
+        if not isinstance(field, dict):
+            continue
+        key = str(field.get("key") or "").strip()
+        if not key:
+            continue
+        out[key] = field_class(field, viewer, grants=records.get(key) or _empty_record(),
+                               table_key=table_key, grant_topic=topic,
+                               values_shared=shared_keys, st=st)
+    return out
 def _same_classification(left, right):
     """Do two canonical bags say the same thing about WHO?
     return rewritten
+# ═════════ W41-T07 / OWNER INSTRUCTION 21 — A DELETED FIELD STAYS DELETED ═══════════════════
+#
+# Owner, verbatim: *"Deleting a field from Hide fields does not stick; 'August Campaign' on Odoo
+# customer has reappeared three times."*
+#
+# ⛔⛔ MEASURED IN-PROCESS BEFORE ANY OF THIS WAS WRITTEN, because the scout listed the cause as a
+# HYPOTHESIS and building on an unverified one is how a wave ships a correct fix for the wrong
+# defect. `promote_field` (and the promotion arm of `migrate_legacy_fields` below) POPS the
+# definition out of its creator's stratum, so on a PROMOTED column `table_store.delete_field` is a
+# **total no-op**: the creator's `fields` map no longer holds the key, the shared bucket is a
+# different document its `shared=` callback cannot reach, and every other account's fork is
+# untouched. Observed: `anna['fields'] changed? False`, `shared_overlay STILL holds it? True`.
+# The column the owner deleted three times was never deleted once.
+#
+# ⛔ AND `shared_overlay.drop_field` ALONE DOES NOT FIX IT, also measured: drop the shared
+# definition, run ONE read, and `migrate_legacy_fields` promotes it straight back out of a fork
+# sitting in another account's workspace. That is the fifth leg, and it is why the delete has to
+# be a SWEEP of every stratum rather than a call to any one door.
+#
+# ⚠ WHICH FORKS RE-PROMOTE, measured, because the guard is untestable without it: a fork carrying
+# NO permissions bag re-promotes (`stored_permissions` falls back to `collaborative`), one saying
+# `collaborative` re-promotes, and one saying `personal` does not. A negative control built on a
+# `personal` fork proves nothing at all: it would stay deleted with every guard disabled.
+#: The tenant-wide member of a `<key>_table_workspace` document — `core.table_store.SHARED_KEY`.
+#: ⚠ SPELLED, NOT IMPORTED, and deliberately: `table_store` imports nothing from this module and
+#: an import the other way would close a cycle in `core`. `migrate_legacy_fields` has skipped this
+#: member by the same literal since it was written, so the constant names what was already here.
+WORKSPACE_SHARED_MEMBER = "__shared__"
+#: Where a delete records itself: `__shared__.deletedFields = {field_key: <unix seconds>}`.
+#:
+#: ⭐⭐ THE RESIDENCY IS THE WHOLE COST ARGUMENT. `migrate_legacy_fields` ALREADY reads the
+#: workspace document (`document = st.get(key)`) and a delete ALREADY writes it (the fork sweep),
+#: so the tombstone is read for free on every read path and written in the SAME transaction as the
+#: sweep it belongs to. One update, one flush, one failure mode — `table_store._update`'s own
+#: argument for taking a `shared=` callback instead of making a second write.
+#:
+#: ⛔ IT IS A SIBLING OF `__shared__.fields`, NOT AN ENTRY IN IT, and that is what keeps it out of
+#: everyone's way. `table_store._shared_fields` reads `__shared__['fields']`; `shared_views` reads
+#: `__shared__['views']`; `assert_annotation_only` judges only the entries of `__shared__['fields']`
+#: — so nothing that reads this member can see this book, and the C3 annotation law has nothing to
+#: bite on. ⛔ AND IT IS NOT IN THE SHARED-OVERLAY BUCKET, which was the other candidate: that
+#: document carries every shared CELL in the tenant and `store.get_projection` drops keys from
+#: top-level VALUES rather than top-level keys, so reading it for a tombstone would buy a whole
+#: deep copy of the cells on every read — the D-214 shape, paid on the hot path, for a dozen bytes.
+DELETED_FIELDS_MEMBER = "deletedFields"
+#: How long a tombstone suppresses the IMPLICIT legacy promotion. See `delete_field_everywhere`
+#: for why a finite window is the anti-leak, not a weakness.
+TOMBSTONE_TTL_S = 900
+#: The book is compacted on every write, so this is a ceiling on a document nobody prunes.
+MAX_TOMBSTONES = 200
+def _live_tombstones(document, now=None):
+    """`{field_key: deleted_at}` for the deletes still inside their window, from a document the
+    caller ALREADY HOLDS. Costs no read, and never writes.
+    ⚠ EXPIRY IS READ-SIDE FILTERING, NOT A SWEEP. Retiring an expired entry would be a write on a
+    read path, on a tenant-wide document, triggered by opening a page — the exact shape
+    `reconcile_shared_permissions` had to argue its way past. An expired entry is INERT here and is
+    compacted by `_stamp_tombstone` on the next delete, which is a write somebody asked for.
+    """
+    member = (document or {}).get(WORKSPACE_SHARED_MEMBER)
+    book = member.get(DELETED_FIELDS_MEMBER) if isinstance(member, dict) else None
+    if not isinstance(book, dict):
+        return {}
+    now = int(time.time()) if now is None else int(now)
+    out = {}
+    for field_key, at in book.items():
+        # `bool` IS an `int` in Python, so it is excluded by name: `{'k': True}` would otherwise
+        # read as "deleted at epoch 1" and be permanently expired, i.e. a silently absent guard.
+        if isinstance(at, bool) or not isinstance(at, (int, float)):
+            continue
+        if now - int(at) < TOMBSTONE_TTL_S:
+            out[str(field_key)] = int(at)
+    return out
+def _stamp_tombstone(shared_member, field_key, now):
+    """Record one delete in the `__shared__` member being written. Compacts as it goes.
+    ⚠ A SEPARATE MODULE-LEVEL FUNCTION RATHER THAN A CLOSURE, so the fifth-leg guard can be
+    DISABLED for a negative control without editing the delete. A guard nothing can turn off is a
+    guard nobody can prove is doing the work.
+    """
+    book = shared_member.get(DELETED_FIELDS_MEMBER)
+    book = book if isinstance(book, dict) else {}
+    fresh = {str(k): int(v) for k, v in book.items()
+             if not isinstance(v, bool) and isinstance(v, (int, float))
+             and now - int(v) < TOMBSTONE_TTL_S}
+    fresh[str(field_key)] = int(now)
+    if len(fresh) > MAX_TOMBSTONES:
+        for stale in sorted(fresh, key=lambda k: fresh[k])[:len(fresh) - MAX_TOMBSTONES]:
+            fresh.pop(stale, None)
+    shared_member[DELETED_FIELDS_MEMBER] = fresh
+    return fresh
+def _retire_tombstone(document, field_key):
+    """Forget one delete, because somebody has explicitly said the column should exist again."""
+    member = (document or {}).get(WORKSPACE_SHARED_MEMBER)
+    book = member.get(DELETED_FIELDS_MEMBER) if isinstance(member, dict) else None
+    if isinstance(book, dict):
+        book.pop(str(field_key), None)
+    return document
+def _purge_forks(document, field_key):
+    """Drop one column's DEFINITION and VALUES from EVERY account's stratum. Returns the owners hit.
+    ⛔⛔ EVERY ACCOUNT, WHICH IS THE ONE THING A PER-USER DELETE CANNOT DO AND THE REASON THIS
+    EXISTS. `table_store.delete_field(username, key)` reaches exactly one member of this document.
+    A fork left in any other member is re-promoted into the shared stratum by
+    `migrate_legacy_fields` on the very next read, and the column is back — measured, not reasoned.
+    ⚠ Deleting a COLUMN is already a tenant-wide act (`table_store.delete_field`'s own note makes
+    that argument about the tenant-wide summary), so reaching across accounts here is the same
+    act, not a wider one. The RIGHT to do it was answered before this function was reached.
+    ⚠ MODULE-LEVEL AND NOT A CLOSURE, for `_stamp_tombstone`'s reason: the negative control has to
+    be able to switch this off and watch the column come back.
+    """
+    key = str(field_key or "")
+    owners = []
+    for owner, workspace in list((document or {}).items()):
+        if owner == WORKSPACE_SHARED_MEMBER or not isinstance(workspace, dict):
+            continue
+        touched = False
+        fields = workspace.get("fields")
+        if isinstance(fields, dict) and fields.pop(key, None) is not None:
+            touched = True
+        overlays = workspace.get("overlays")
+        if isinstance(overlays, dict):
+            for values in overlays.values():
+                if isinstance(values, dict) and values.pop(key, None) is not None:
+                    touched = True
+        if touched:
+            owners.append(str(owner))
+    return owners
 def _field_is_migratable(field):
     return (isinstance(field, dict) and field.get("custom") is True
             and field.get("source") == "overlay")
     grant_key = str(grant_topic or key).strip()
     shared_key = str(shared_key or key).strip()
     if not key or st is None:
+        return {"promoted": 0, "normalized": 0, "reclassified": 0,
+                "suppressed": 0, "purged": 0}
     # ⭐⭐ W40-T03 — RECONCILE THE SHARED STRATUM'S CLASSIFICATION FIRST, IN ITS OWN SWALLOWING
     # GUARD. This is the ONE seam that reaches every shared-field surface: all three readers
     # (`routes_customers.shared_fields`, `routes_tables._ut_shared_fields`,
     try:
         document = st.get(key) or {}
     except Exception:
+        return {"promoted": 0, "normalized": 0, "reclassified": reclassified,
+                "suppressed": 0, "purged": 0}
     if not isinstance(document, dict):
+        return {"promoted": 0, "normalized": 0, "reclassified": reclassified,
+                "suppressed": 0, "purged": 0}
     promoted = 0
     normalized = 0
+    suppressed = 0
     remove = {}
+    # ⭐⭐ W41-T07 — THE FIFTH LEG, READ FOR FREE OFF THE DOCUMENT ALREADY IN HAND. A key deleted
+    # inside the window is not promotable, no matter which account still holds a fork of it.
+    tombstoned = _live_tombstones(document)
     for owner, workspace in document.items():
+        if owner == WORKSPACE_SHARED_MEMBER or not isinstance(workspace, dict):
             continue
         fields = workspace.get("fields") or {}
         if not isinstance(fields, dict):
         for field_key, original in list(fields.items()):
             if not _field_is_migratable(original):
                 continue
+            if str(field_key) in tombstoned:
+                # ⛔ SKIP, NEVER SWEEP. The delete already took every fork it could see; anything
+                # here now either arrived after it or survived a partial failure, and destroying
+                # somebody's column to tidy up is the one mistake with no undo — this store keeps
+                # no history ([[a-cleanup-deletes-what-it-did-not-create]]). Suppressing the
+                # PROMOTION is enough: the fork stays private and visible to its holder, and the
+                # tenant-wide resurrection the owner reported three times does not happen.
+                suppressed += 1
+                continue
             permissions = stored_permissions(original, fallback="collaborative",
                                              known_users=known_users)
             if permissions["edit"] == "personal":
                                 values.pop(field_key, None)
                 return data
         st.update(key, _remove, flush="sync")
+    # ⭐⭐ W41-T07 — AND A SHARED DEFINITION THAT CAME BACK INSIDE THE WINDOW IS DROPPED AGAIN.
+    #
+    # ⛔ THIS IS THE LEG THAT MAKES A PARTIAL DELETE HEAL FORWARD, and it is why
+    # `delete_field_everywhere` sweeps the forks BEFORE it drops the shared definition. If the
+    # sweep and the tombstone land and the `shared_overlay.drop_field` after them does not, the
+    # definition would otherwise survive and be re-merged onto every grid forever. With this leg
+    # the next read finishes the delete instead. It also closes the concurrency window: a read
+    # that snapshotted the forks before the sweep can still write the promotion after it, and
+    # nothing else would ever take that resurrection away.
+    #
+    # ⚠ IT COSTS A READ OF THE SHARED BUCKET, AND ONLY WHEN A TOMBSTONE IS LIVE. Steady state is
+    # an empty book and this whole block is skipped, so the hot read path is unchanged; the cost
+    # is bounded to the `TOMBSTONE_TTL_S` window after somebody deletes a column.
+    purged = 0
+    if tombstoned:
+        try:
+            live = shared_overlay.fields(shared_key, st=st)
+        except Exception:                                       # noqa: BLE001
+            live = {}
+        for dead in tombstoned:
+            if dead not in live:
+                continue
+            try:
+                if shared_overlay.drop_field(shared_key, dead, st=st):
+                    purged += 1
+            except Exception:                                   # noqa: BLE001
+                continue
     # ⛔ `promoted` AND `normalized` KEEP THEIR NAMES AND THEIR MEANINGS.
     # `aios-web/api/verify_field_permissions.py` asserts `result["promoted"] == 1`; renaming or
     # folding either into the new count would turn a green gate red for a change it never made.
+    # ⚠ `suppressed` and `purged` are ADDED beside them for the same reason: a caller that reads
+    # the old two keeps reading exactly what it read before.
+    return {"promoted": promoted, "normalized": normalized, "reclassified": reclassified,
+            "suppressed": suppressed, "purged": purged}
 def promote_field(workspace_key, shared_key, grant_topic, owner, field, st=None):
         for values in (ws.get("overlays") or {}).values():
             if isinstance(values, dict):
                 values.pop(key, None)
+        # ⭐⭐ W41-T07 — AN EXPLICIT SHARE RETIRES THE TOMBSTONE, AND THIS LINE IS THE WHOLE
+        # ANTI-LEAK ARGUMENT FOR HAVING ONE. `delete_field_everywhere` suppresses the IMPLICIT
+        # legacy promotion of a deleted key; this function is the EXPLICIT one, reached from
+        # `routes_shares.put_share`, i.e. a person saying in as many words that this column is
+        # meant to exist and be shared. There is nothing left to be careful about after that, so
+        # the suppression ends immediately rather than waiting out `TOMBSTONE_TTL_S`.
+        _retire_tombstone(data, key)
         return data
     st.update(workspace_key, _remove, flush="sync")
     return shared
     shared_overlay.drop_field(shared_key, key, st=st)
     shares.drop_objects([("field", shares.field_oid(grant_topic, key))], st=st)
     return personal
+def delete_field_everywhere(workspace_key, shared_key, grant_topic, field_key, st=None):
+    """⭐⭐ W41-T07 / OWNER INSTRUCTION 21 — **DELETE ONE COLUMN FROM EVERY STRATUM THAT HOLDS IT.**
+    Owner: *"Deleting a field from Hide fields does not stick; 'August Campaign' on Odoo customer
+    has reappeared three times."* It reappeared because no door had ever deleted it. Returns a
+    per-leg report; it decides no rights and refuses nobody.
+    ⛔⛔ THE RIGHT IS ANSWERED BEFORE THIS IS REACHED, AND IT IS NOT ANSWERED AGAIN HERE.
+    `user_tables.may_delete_field` / `delete_field_refusal` are C2's one pair, and C2's last
+    sentence is *"No surface re-implements either test"* — a module that both decided and executed
+    would be the second implementation. This is the EXECUTION half, on purpose.
+    **THE FIVE LEGS, and which line closes each:**
+      1. the deleter's own per-user stratum   -> `_purge_forks` (their member of the document)
+      2. `shared_overlay`'s bucket            -> `shared_overlay.drop_field`, the RIGHT document
+      3. the re-merge onto the next fetch     -> leg 2; `_merge_shared_fields` and
+                                                 `_ut_shared_fields` project what is in the bucket,
+                                                 so a definition that is gone cannot be re-injected
+      4. the grant record                     -> `shares.drop_objects`
+      5. every OTHER account's fork           -> `_purge_forks` (all members) + `_stamp_tombstone`
+    ⛔ LEG 5 IS THE ONE THAT BITES, AND `drop_field` ALONE IS NOT ENOUGH — measured in-process
+    before this was written. `migrate_legacy_fields` runs on EVERY read and walks EVERY member of
+    the workspace document, so one fork left in one colleague's stratum re-promotes the column into
+    the shared bucket on the next page load. Deleting the shared definition without sweeping the
+    forks buys exactly one render.
+    ⛔ THE ORDER IS SWEEP-THEN-DROP AND IT IS LOAD-BEARING, not stylistic. The sweep and the
+    tombstone land in ONE transaction on the workspace document; only then is the shared definition
+    dropped. So a failure of the second half leaves a live tombstone, and the next read's
+    `migrate_legacy_fields` finishes the delete instead of re-merging the survivor forever. The
+    other order (drop first, sweep second) fails the opposite way: the definition is gone, the
+    forks are not, and the very next read puts it back with nothing recording that anyone objected.
+    ⚠ THE `__shared__.fields` COLUMN SUMMARY GOES TOO, for `table_store.delete_field`'s own stated
+    reason: *"an orphan `agg` under a deleted key is state nobody can see and nobody can clear, and
+    it would attach itself to the next column that happens to take the key back."*
+    """
+    key = str(field_key or "").strip()
+    ws_key = str(workspace_key or "").strip()
+    bucket = str(shared_key or "").strip()
+    topic = str(grant_topic or bucket or "").strip()
+    report = {"key": key, "personal": 0, "owners": [], "shared": False,
+              "grants": False, "tombstoned": False}
+    if not key or st is None:
+        return report
+    now = int(time.time())
+    if ws_key:
+        hit = {"owners": []}
+        def _purge(data):
+            data = data if isinstance(data, dict) else {}
+            hit["owners"] = _purge_forks(data, key)
+            member = data.setdefault(WORKSPACE_SHARED_MEMBER, {})
+            if isinstance(member, dict):
+                annotations = member.get("fields")
+                if isinstance(annotations, dict):
+                    annotations.pop(key, None)
+                _stamp_tombstone(member, key, now)
+            return data
+        # ⛔ `flush='sync'`, matching every other STRUCTURAL write in this module. A delete the
+        # user has confirmed must not be the thing that is still coalescing when the process dies;
+        # `shared_overlay._write`'s own note draws the same line ("a lost column definition is a
+        # worse failure than a lost keystroke") and a lost DELETION is worse again, because the
+        # column comes back and the person deletes it a fourth time.
+        st.update(ws_key, _purge, flush="sync")
+        report["owners"] = list(hit["owners"])
+        report["personal"] = len(hit["owners"])
+        report["tombstoned"] = True
+    if bucket:
+        report["shared"] = bool(shared_overlay.drop_field(bucket, key, st=st))
+    if topic:
+        # ⚠ GUARDED, AND THE TOLERANCE IS `routes_tables.delete_shared_field`'s ALREADY: the column
+        # and its values are gone by now, so a registry hiccup must not turn a completed delete
+        # into a 500 that invites the client to repeat it. A surviving grant record is inert
+        # (`shares.role_for` resolves against an object that no longer exists) and is overwritten
+        # by the next `set_grants` on the same id.
+        try:
+            shares.drop_objects([("field", shares.field_oid(topic, key))], st=st)
+            report["grants"] = True
+        except Exception:                                       # noqa: BLE001
+            report["grants"] = False
+    return report

platform/core/grid_events.py CHANGED Viewed

@@ -626,6 +626,122 @@ def table_workspace(ctx, allowed_pids=None, consume_corrections=True):
         uname, {'views': {}, 'fields': {}, 'overlays': {}})
 def _granted_views(ctx, uname):
     """{view_id: STAMPED view} for every view GRANTED to `uname` by name (wave 21, item 9, C1).
@@ -710,6 +826,14 @@ def _granted_views(ctx, uname):
             # renders in the same "Shared with me" group the view leg feeds. Stamps live on the
             # PROJECTION only and are never written back, exactly as above.
             v['sharedFolder'] = str(folder.get('name') or '')[:80]
             out[str(vid)] = v
     return out
@@ -852,14 +976,23 @@ def _known_usernames():
 #: `code` is a stable machine token (the client may branch on it); `message` is the sentence a
 #: person reads. ⚠ The message must name what the CALLER can change — a refusal a user cannot act
 #: on is only marginally better than silence.
-def _refuse(ctx, code, message, key=''):
     """Record a NAMED refusal on the result and demand a repaint. Always returns True."""
     try:
         out = getattr(ctx, 'out', None)
         if out is not None and hasattr(out, 'refusals'):
             if len(out.refusals) < 24:          # one per event in the window; never unbounded
                 out.refusals.append({
-                    'event': 'field_upsert',
                     'key': str(key or '')[:80],
                     'code': str(code)[:40],
                     'message': str(message)[:300],
@@ -872,6 +1005,142 @@ def _refuse(ctx, code, message, key=''):
     return True
 def handle_events(events, ctx):
     """The event LOG entry point → one EventResult. The `[-24:]` window lives here.
@@ -1146,6 +1415,8 @@ def handle_one(event, ctx):
             'widths': widths,
             'memberPids': [pid for pid in list(cfg.get('memberPids') or [])
                            if isinstance(pid, int) and pid in allowed_pids],
         }
         # Wave-6 item 10: a non-grid display mode rides the view config, validated
         # structurally (mode whitelist, refs must be this table's fields).
@@ -1885,11 +2156,22 @@ def handle_one(event, ctx):
         # events touch ONE home — the table workspace's `folders` + `itemFolders` — so a cohort
         # can be filed without the cohort STORE learning about folders at all.
         import aios_grid as _agf
         if not _store_of(ctx).available():
-            return False
         surface = str(event.get('surface') or '')
         if surface not in _agf.FOLDER_SURFACES:
-            return False
         # The ids this user may actually file: their own views, their own cohorts. Fail-closed —
         # an item_move naming somebody else's cohort is dropped by clean_item_folders anyway,
         # but refusing here means we never write it in the first place.
@@ -1898,6 +2180,18 @@ def handle_one(event, ctx):
                 return set((cur_ws.get('views') or {}))
             return set(_cohorts(ctx).all_for(uname))
         def _mutate(cur_ws):
             folders = _agf.clean_folders(cur_ws.get('folders'))
             placed = dict(cur_ws.get('itemFolders') or {})
@@ -1908,24 +2202,76 @@ def handle_one(event, ctx):
             fid = str(event.get('folderId') or '').strip()[:80]
             if kind == 'folder_create':
                 name = str(event.get('name') or '').strip()[:_agf.MAX_FOLDER_NAME]
-                if not fid or not name or len(lst) >= _agf.MAX_FOLDERS:
-                    return None
                 if any(f['id'] == fid for f in lst):
-                    return None
                 row = {'id': fid, 'name': name, 'order': len(lst)}
                 icon = _agf.clean_folder_icon(event.get('icon'))    # wave-9 I15 (C5)
                 if icon:
                     row['icon'] = icon
                 lst.append(row)
             elif kind == 'folder_rename':
                 name = str(event.get('name') or '').strip()[:_agf.MAX_FOLDER_NAME]
                 hit = next((f for f in lst if f['id'] == fid), None)
-                if not hit or not name:
-                    return None
-                hit['name'] = name
                 # wave-9 I15 (C5): the rename pane is also where the icon is changed. An event
                 # that carries NO icon key leaves the existing one alone (a rename must not
                 # silently strip a chosen icon); an explicit null clears it back to default.
                 if 'icon' in event:
                     icon = _agf.clean_folder_icon(event.get('icon'))
                     if icon:
@@ -1934,7 +2280,9 @@ def handle_one(event, ctx):
                         hit.pop('icon', None)
             elif kind == 'folder_delete':
                 if not any(f['id'] == fid for f in lst):
-                    return None
                 lst = [f for f in lst if f['id'] != fid]
                 # CONTENTS MOVE TO ROOT, never delete. Dropping the placements is exactly that:
                 # an item with no placement renders at the top level.
@@ -1958,7 +2306,9 @@ def handle_one(event, ctx):
                 # folder it merely failed to mention would be a data loss dressed as a sort.
                 order = [str(i).strip()[:80] for i in (event.get('order') or [])]
                 if not order:
-                    return None
                 known = {f['id']: f for f in lst}
                 seen, ranked = set(), []
                 for fid_ in order:
@@ -1967,17 +2317,34 @@ def handle_one(event, ctx):
                         ranked.append(known[fid_])
                 ranked.extend(f for f in lst if f['id'] not in seen)
                 if len(ranked) != len(lst):          # cannot happen; refuse rather than truncate
-                    return None
                 for i, f in enumerate(ranked):
                     f['order'] = i
                 lst = ranked
             elif kind == 'folder_duplicate':
                 new_id = str(event.get('newId') or '').strip()[:80]
                 src = next((f for f in lst if f['id'] == fid), None)
-                if not src or not new_id or len(lst) >= _agf.MAX_FOLDERS:
-                    return None
                 if any(f['id'] == new_id for f in lst):
-                    return None
                 lst.append({'id': new_id, 'name': f"{src['name']} copy"[:_agf.MAX_FOLDER_NAME],
                             'order': len(lst)})
                 # ⚠ The folder's CONTENTS are duplicated by the client emitting the ordinary
@@ -1988,8 +2355,19 @@ def handle_one(event, ctx):
             else:                                   # item_move
                 item_id = str(event.get('itemId') or '').strip()[:120]
                 target = event.get('folderId')
-                if not item_id or item_id not in _own_ids(surface, cur_ws):
-                    return None
                 cur = dict(placed.get(surface) or {})
                 if target is None:
                     # ⚠ "UNFILE" — the client says nothing about where it went. Popping is right
@@ -2015,7 +2393,10 @@ def handle_one(event, ctx):
                 else:
                     tid = str(target)[:80]
                     if not any(f['id'] == tid for f in lst):
-                        return None
                     cur[item_id] = tid
                 placed[surface] = cur
             folders[surface] = lst
@@ -2031,8 +2412,48 @@ def handle_one(event, ctx):
         # change inside a pure move.
         _res = _mutate(table_workspace(ctx, consume_corrections=False))
         if _res is None:
-            return False                      # refused: nothing is written
-        _tops(ctx).save_folders(uname, _res[0], _res[1])
         # True: the sidebars render from server state (which folder holds what), not from local
         # optimism — the same contract the cohort panel's membership edits ride.
         return True
@@ -2092,8 +2513,79 @@ def handle_one(event, ctx):
         import aios_grid as _ag3
         if not (key.startswith('custom_') or key.startswith(_ag3.MEASURE_FIELD_PREFIX)):
             return False
         if _store_of(ctx).available():
-            _tops(ctx).delete_field(uname, key)
         else:
             _session_ready()
             ws['fields'].pop(key, None)

         uname, {'views': {}, 'fields': {}, 'overlays': {}})
+#: ⭐⭐ W41-T14 · OWNER INSTRUCTION 11 · CONTRACT C9 — THE GRANTED FOLDER'S OWN RECORD.
+#:
+#: ⛔ THE ICON WAS NEVER LOST IN TRANSIT; IT WAS NEVER SENT. `_granted_views` stamped
+#: `v['sharedFolder'] = <name>` and nothing else, so `folders.ts::groupByFolder` RECONSTRUCTS
+#: `{id: sharedFolderGroupId(owner, name), name}` for the receiver's rail — a folder assembled out
+#: of two strings, with no icon on it — and `icons.tsx::FolderMark` then falls back to its default
+#: shape and tone. That fallback is exactly what the owner is reporting. The record was always in
+#: hand: `table_store.find_folder` returns `dict(hit)`, the whole stored row, icon included.
+#:
+#: ⚠ ADDITIVE, AND THAT IS THE CONTRACT DECISION. `sharedFolder` KEEPS its string type and its
+#: meaning: `aios-web/web/verify_folders.py` asserts `typeof v.sharedFolder === "string"` and
+#: `api/verify_api.py` reads the same key, so retyping it to a record would turn two gates red and
+#: blank the receiver's grouping until the client half (W41-T35) lands. C8's rule one bullet above
+#: C9 — *absent keys mean "not built yet", never "false"* — is what lets the two halves land in
+#: either order, and [[two-lanes-one-contract-dead-feature]] is the scar it exists to prevent.
+#:
+#: ⛔ THE CLIENT MUST NOT USE THIS `id` AS THE GROUP KEY. `folders.ts::SHARED_FOLDER_PREFIX` says
+#: it in its own words — *"NOTHING MAY EVER WRITE ONE… no `order`, no icon, no row in `folders`"* —
+#: and every rail affordance gates on `isSyntheticFolderId`. Swapping the synthetic group id for
+#: this real one would let the receiver emit `item_move` / `folder_rename` against a folder that
+#: lives in somebody ELSE's store. `id` is here to identify the share, never to key the group.
+#:
+#: ⛔ `parent` IS DELIBERATELY NOT FORWARDED, which is why C9 spells it `parent?`. A parent id
+#: names a folder in the OWNER's stratum that was NOT granted: the receiver cannot resolve it,
+#: must not store it, and would gain only a pointer into a tree they cannot see. One folder is
+#: shared, so one folder is delivered, flat.
+#:
+#: ⚠ BUILT MEMBER BY MEMBER, never `dict(folder)`. This row comes out of another account's
+#: workspace; forwarding it whole would carry whatever else happens to be sitting on it across a
+#: user boundary. The icon goes back out through `aios_grid.clean_folder_icon` — the ONE server
+#: whitelist (12 shapes, 5 tones, and the legacy `grey` tone canonicalised) — so a receiver can
+#: never be handed a shape no client knows how to draw.
+#: ⭐⭐ W41-T20's DONE-WHEN CLAUSE 5, LANDED BY THE INTEGRATOR. Lane B proved BOTH ways that a
+#: saved pivot round-trips to `None` without this, and correctly refused to write it: this file
+#: is lane A's fence. The clause named a file its own ticket did not own, so it was
+#: undischargeable by construction. [[two-lanes-one-contract-dead-feature]]
+#:
+#: ⛔ THE KEY IS WRITTEN UNCONDITIONALLY, like `important` above and unlike `cohortLock`. The
+#: client CLEARS a pivot by omitting the key (`CustomerGrid.tsx:7195`
+#: `const { secondaryView: _cleared, ...rest } = config`), so both spellings happen to clear
+#: correctly today -- but this dict is REBUILT FROM THE ALLOWLIST on every autosave, and a
+#: conditional key is one client change away from a pivot you can set and never clear. Lane A's
+#: own note at :1331-1334 argues this for `important`; every word of it applies here.
+#:
+#: ⛔ FAIL-CLOSED ON `database` AND `viaField`, matching `types.ts::cleanSecondaryView` exactly:
+#: a pivot missing either cannot be served by anything, so it stores as ABSENT (the ordinary view
+#: of this table) rather than as a pivot that renders an empty grid reading as
+#: "no related records" -- the distinction C10's `refusal` key exists to preserve.
+#:
+#: ⚠ THE NESTED `config` IS BOUNDED, NOT KEY-VALIDATED, AND THAT IS DELIBERATE. Its filters name
+#: columns of the TARGET database, whose field list is not resolvable from this door -- `cfg`'s
+#: `valid_keys` belong to the SOURCE. `routes_grid.py::pivot` already takes `filters` from the
+#: request body as a raw list (`:1201`) and owns their semantics, so validating here would either
+#: duplicate that or reject a legal tree. What this does own is SHAPE and SIZE, so nothing
+#: unbounded reaches the store.
+_SECONDARY_WINDOWS = ('all', 'last12m', 'ytd')          # routes_grid.PIVOT_WINDOWS' key set
+def _clean_secondary_view(raw):
+    """C6 -- the stored shape of a Relational pivot, or None. Mirrors `types.ts::cleanSecondaryView`."""
+    if not isinstance(raw, dict):
+        return None
+    database = str(raw.get('database') or '').strip()[:80]
+    via_field = str(raw.get('viaField') or '').strip()[:120]
+    if not database or not via_field:
+        return None                                     # fail-closed: see the note above
+    window = raw.get('window')
+    cfg = raw.get('config') if isinstance(raw.get('config'), dict) else {}
+    height = cfg.get('rowHeightMode')
+    def _keys(value, cap):
+        return [str(k)[:120] for k in list(value or [])[:cap] if isinstance(k, str)] \
+            if isinstance(value, list) else []
+    widths = {}
+    if isinstance(cfg.get('widths'), dict):
+        for k, v in list(cfg['widths'].items())[:400]:
+            try:
+                widths[str(k)[:120]] = int(v)
+            except (TypeError, ValueError):
+                continue
+    return {
+        'database': database,
+        'viaField': via_field,
+        'window': window if window in _SECONDARY_WINDOWS else 'all',
+        'config': {
+            'filters': list(cfg.get('filters') or [])[:200] if isinstance(cfg.get('filters'), list) else [],
+            'filterConj': 'or' if cfg.get('filterConj') == 'or' else 'and',
+            'sorts': list(cfg.get('sorts') or [])[:20] if isinstance(cfg.get('sorts'), list) else [],
+            'groupBy': str(cfg['groupBy'])[:120] if isinstance(cfg.get('groupBy'), str) and cfg['groupBy'] else None,
+            'colorBy': str(cfg['colorBy'])[:120] if isinstance(cfg.get('colorBy'), str) and cfg['colorBy'] else None,
+            'rowHeightMode': height if height in ('medium', 'tall') else 'short',
+            'order': _keys(cfg.get('order'), 400),
+            'visible': _keys(cfg.get('visible'), 400),
+            'widths': widths,
+        },
+    }
+def _shared_folder_record(fid, folder):
+    """C9's wire record for a folder granted to somebody else: `{id, name, order?, icon?}`.
+    Absent `icon` means the owner chose none and the client draws its default mark, which is the
+    same thing absence has always meant on a stored folder row (`aios_grid.clean_folders`).
+    """
+    import aios_grid as _agf
+    src = folder if isinstance(folder, dict) else {}
+    rec = {'id': str(fid or '')[:80], 'name': str(src.get('name') or '')[:80]}
+    try:
+        rec['order'] = int(src.get('order'))
+    except (TypeError, ValueError):
+        pass                       # the owner's rail position rides when it is one, never invented
+    icon = _agf.clean_folder_icon(src.get('icon'))
+    if icon:
+        rec['icon'] = icon
+    return rec
 def _granted_views(ctx, uname):
     """{view_id: STAMPED view} for every view GRANTED to `uname` by name (wave 21, item 9, C1).
             # renders in the same "Shared with me" group the view leg feeds. Stamps live on the
             # PROJECTION only and are never written back, exactly as above.
             v['sharedFolder'] = str(folder.get('name') or '')[:80]
+            # ⭐⭐ W41-T14 (C9) — AND NOW THE WHOLE RECORD BESIDE IT, which is the line that
+            # carries the icon. See `_shared_folder_record`: `sharedFolder` is untouched so the
+            # existing readers and their two gates keep working, and `sharedFolderRecord` is the
+            # key W41-T35 reads the shape and tone off. Same projection-only rule as every stamp
+            # above — `views_from_defs` copies a saved view with `dict(saved)` and `scope_view`
+            # with `dict(view)`, so an unknown key rides all the way to the wire untouched, and
+            # the `view_upsert` save path builds from a fixed whitelist so it can never be stored.
+            v['sharedFolderRecord'] = _shared_folder_record(fid, folder)
             out[str(vid)] = v
     return out
 #: `code` is a stable machine token (the client may branch on it); `message` is the sentence a
 #: person reads. ⚠ The message must name what the CALLER can change — a refusal a user cannot act
 #: on is only marginally better than silence.
+#:
+#: ⛔⛔ W41-T13 — `event` USED TO BE THE HARDCODED LITERAL `'field_upsert'`, and that was fine only
+#: while this seam had exactly one caller. It now has two, so a folder refusal filed through the
+#: old body would have recorded `{'event': 'field_upsert'}` on an `item_move` — a disclosure
+#: channel built to end unfalsifiable theories, telling the next reader the wrong thing about
+#: which door refused. KEYWORD-ONLY WITH THE OLD LITERAL AS THE DEFAULT, deliberately: every
+#: existing `field_upsert` call site is byte-unchanged, and W41-T02's own refusals keep reporting
+#: exactly what they reported before. The default is load-bearing, not decorative — it is what
+#: makes this a widening rather than a rewrite.
+def _refuse(ctx, code, message, key='', *, event='field_upsert'):
     """Record a NAMED refusal on the result and demand a repaint. Always returns True."""
     try:
         out = getattr(ctx, 'out', None)
         if out is not None and hasattr(out, 'refusals'):
             if len(out.refusals) < 24:          # one per event in the window; never unbounded
                 out.refusals.append({
+                    'event': str(event or 'field_upsert')[:40],
                     'key': str(key or '')[:80],
                     'code': str(code)[:40],
                     'message': str(message)[:300],
     return True
+#: ⭐⭐ W41-T13 — THE CHANNEL THAT ACTUALLY REACHES A SCREEN, and the two are not the same one.
+#: `EventResult.refusals` is assembled by `api/routes_grid.py` into `results[].refused` and a
+#: top-level `refusals` array — and MEASURED 2026-08-24, **nothing under `aios-web/web/src` reads
+#: either key**. `apiBridge.ts` (~1461) unpacks exactly `{results, doc, toast, rerender, derived}`
+#: from a 200, so `toast` is the only member of that envelope a person ever sees.
+#:
+#: So a refusal that is only recorded is still a silent 200 to the user, which is the defect this
+#: ticket names. Both are written: `refusals` is the machine record a caller branches on and the
+#: next investigation reads, `toast` is the sentence.
+#:
+#: ⚠ `toast` IS ONE SLOT, read once by `routes_grid` after its whole per-event loop, and it is
+#: SHARED with `add_to_list`'s confirmation. THE PRECEDENCE IMPLEMENTED HERE: a refusal always
+#: claims the slot, so within one window the last refusal is what is shown. THE LIMIT, stated
+#: rather than left to be discovered: an `add_to_list` that lands AFTER a refused folder event in
+#: the same 24-event window still overwrites it, because that branch assigns the slot directly.
+#: Widening `EventResult` to a message LIST is the real fix and it is not this ticket's file.
+def _folder_refuse(ctx, kind, code, message, key=''):
+    """Refuse ONE folder event out loud: the machine record AND the rendered sentence."""
+    try:
+        out = getattr(ctx, 'out', None)
+        if out is not None:
+            out.toast = str(message)[:300]
+    except Exception:                                                 # noqa: BLE001
+        pass
+    # ⛔ RETURNS True, LIKE EVERY OTHER REFUSAL. `handle_one`'s return value means "repaint from
+    # server state"; a folder refusal that answered False would leave the browser's OPTIMISTIC
+    # placement on screen with nothing stored behind it — which is the springback the owner is
+    # reporting, kept for another two minutes instead of corrected at once.
+    return _refuse(ctx, code, message, key=key, event=kind)
+#: ⭐ W41-T13 — WHICH `save_folders` REPAIRS ARE WORTH A SENTENCE. W41-T12's receipt lists every
+#: correction it made; most mean *"something you sent was wrong and we fixed it"*, which a person
+#: wants to know about because their folder tree now differs from what they dragged.
+#:
+#: ⛔ `parent_is_root_sentinel` IS DELIBERATELY ABSENT AND MUST STAY ABSENT. It means "you said
+#: root the other legal way" — both spellings are correct, nothing was lost, and rendering it as a
+#: warning would fire on ordinary use. A notice that cries wolf on the normal path trains the user
+#: to ignore the ones that matter.
+#:
+#: ⚠ THE WHOLE NOTICE MUST FIT IN 300 CHARACTERS, which is where `EventResult.toast` is sliced.
+#: All three phrases plus both joiners and the frame is the worst case, and the first draft came
+#: to 328 — a sentence cut off mid-word, in the one channel a person actually reads. The phrases
+#: below are short for that reason and not for style; the proof pins the bound so the next person
+#: to add one finds out here rather than on a screen.
+_FOLDER_REPAIR_COPY = {
+    'parent_missing': 'named a folder that is gone, so it moved to the top level',
+    'placement_missing_folder': 'named a folder that is gone, so it moved to the top level',
+    'item_in_two_folders': 'was in two folders at once, so the first one was kept',
+}
+#: Everything else actionable collapses to one sentence: the row could not be read at all.
+_FOLDER_REPAIR_UNREADABLE = frozenset({
+    'duplicate_folder_id', 'parent_not_an_id', 'row_not_a_folder', 'folder_without_id',
+    'surface_not_a_list', 'placements_not_a_map', 'placement_without_item',
+    'placement_not_an_id',
+})
+def _folder_repair_notice(repairs):
+    """The sentence for a `save_folders` receipt, or None when there is nothing worth saying."""
+    seen = []
+    for row in (repairs or ()):
+        reason = str((row or {}).get('reason') or '')
+        if reason == 'parent_is_root_sentinel':
+            continue                       # see the constant above: the normal path, not a repair
+        phrase = _FOLDER_REPAIR_COPY.get(reason)
+        if phrase is None and reason in _FOLDER_REPAIR_UNREADABLE:
+            phrase = 'could not be read, so it was left out'
+        if phrase and phrase not in seen:
+            seen.append(phrase)
+    if not seen:
+        return None
+    return ('Your folders were saved with a correction. Something in them '
+            + '; something else '.join(seen)
+            + '. Reload the page to see the result.')
+def _commit_folder_write(tops):
+    """⭐⭐ W41-T13 / OWNER INSTRUCTION 10 — MAKE THE FOLDER WRITE THAT JUST HAPPENED DURABLE, NOW.
+    ⛔ THE DEFECT, MEASURED WITH TWO REAL PROCESSES AGAINST A THROWAWAY STORE (2026-08-24):
+    `table_store.save_folders` commits through `TableStore._update`, which is hardcoded to
+    `flush='async'`. That applies the change to `Store._cache` and returns; the hub commit is
+    handed to a coalescing worker that sleeps `_FLUSH_DELAY` (2s) and then, if this key committed
+    inside the last `_FLUSH_MIN_GAP` (20s), sleeps the remainder of that too. **SIX accepted
+    folder writes in a row left the hub on its original commit** and a second process read an
+    empty `itemFolders` every single time. Read-your-writes held inside the process, which is
+    exactly why no gate in this repo could see it ([[a-guard-closed-on-one-backend-is-not-closed]]).
+    The user-visible half is the owner's report: `viewEcho.ts::ECHO_RECENT_MS` holds the
+    optimistic placement for 120s and then yields to the host copy, so a write that never reached
+    the hub before the container was replaced springs back at about two minutes.
+    ⛔ `st.flush(key)` IS THE WRONG PRIMITIVE HERE, THREE TIMES OVER: it waits out
+    `_FLUSH_MIN_GAP`, so it can block a drag for ~22 seconds; `harness.runtime.TenantRuntime` (the
+    handle the HTTP door actually passes) does not proxy it at all; and the gates' store doubles
+    do not all carry it. `update(key, identity, flush='sync')` is on EVERY handle — the module,
+    `Store`, `TenantRuntime`, `store_pg`, and both fakes — and `_update_locked`'s D-305 branch
+    makes it exactly the right one: with the key dirty and owned it takes the CACHE (never
+    re-downloading over the pending change), commits it through `_commit` with the parent
+    precondition and the replay journal intact, and clears the dirty mark so the worker does not
+    then spend a second commit on identical bytes.
+    ⛔ BYPASSING `_FLUSH_MIN_GAP` IS THE POINT, NOT AN OVERSIGHT — do not "fix" this back to
+    protect the 256-commits/hr budget. That floor exists to coalesce autosave chatter (a column
+    resize, a filter tweak, a typed cell). A folder event is not chatter: `CustomerGrid.tsx`
+    emits `item_move` and `folder_reorder` ON DROP, one per completed gesture, so the ceiling
+    this adds is a handful of commits per session against a budget of 256 per hour.
+    ⚠ IT IS THE HANDLE `save_folders` ITSELF USED, resolved through `_tops` and never `_store_of`.
+    Those two can be different objects (`_tops` can fall through to `cl_mod.TABLE_OPS`, built with
+    NO store handle, while `_store_of` returns the request's `TenantRuntime`), and committing the
+    wrong one would land nothing while looking exactly like success. `TableStore.st` and
+    `.table_key` are the public pair, so this addresses byte-for-byte what `_update` addressed.
+    ⚠ A FAILED COMMIT IS NOT A REFUSED WRITE. The change is already accepted into the cache and
+    the key is still marked dirty, so the coalescing worker keeps retrying with backoff. Logging
+    and carrying on is therefore right; raising here would turn a saved change into a 500.
+    ⚠ ON POSTGRES this is a redundant transaction: `store_pg.update` accepts `flush=` and ignores
+    it because every write is already committed when it returns. One extra RMW per user gesture,
+    correctness-neutral. Named for the record rather than special-cased, because a backend test
+    here would be a second definition of "which backend am I on".
+    """
+    try:
+        st = getattr(tops, 'st', None)
+        key = getattr(tops, 'table_key', None)
+        if st is None or not key or not hasattr(st, 'update'):
+            return False
+        st.update(key, lambda doc: doc, flush='sync')
+        return True
+    except Exception as exc:                                          # noqa: BLE001
+        _tel.error('grid_events:folder_commit', exc)
+        return False
 def handle_events(events, ctx):
     """The event LOG entry point → one EventResult. The `[-24:]` window lives here.
             'widths': widths,
             'memberPids': [pid for pid in list(cfg.get('memberPids') or [])
                            if isinstance(pid, int) and pid in allowed_pids],
+            # ⭐⭐ W41-T20 clause 5 / C6 -- see `_clean_secondary_view` above.
+            'secondaryView': _clean_secondary_view(cfg.get('secondaryView')),
         }
         # Wave-6 item 10: a non-grid display mode rides the view config, validated
         # structurally (mode whitelist, refs must be this table's fields).
         # events touch ONE home — the table workspace's `folders` + `itemFolders` — so a cohort
         # can be filed without the cohort STORE learning about folders at all.
         import aios_grid as _agf
+        # ⭐⭐ W41-T13 — NOT ONE BARE `False` LEAVES THIS BRANCH ANY MORE. Every exit below was a
+        # `return False`, which `routes_grid` renders as `{"results":[{"rerender":false}]}` — byte
+        # for byte a success. The user dragged a view, the rail sprang back, and the app said
+        # nothing at all. `refused` carries the cause a caller branches on; `_folder_refuse` also
+        # claims the one slot the client renders (see its note).
         if not _store_of(ctx).available():
+            return _folder_refuse(
+                ctx, kind, 'store_unavailable',
+                'Your folders could not be saved because the workspace store is not reachable '
+                'right now, so nothing was changed. Try again in a moment.')
         surface = str(event.get('surface') or '')
         if surface not in _agf.FOLDER_SURFACES:
+            return _folder_refuse(
+                ctx, kind, 'surface_unknown',
+                'That folder change did not name a sidebar this page has, so nothing was saved. '
+                'Reload the page and try again.', key=surface)
         # The ids this user may actually file: their own views, their own cohorts. Fail-closed —
         # an item_move naming somebody else's cohort is dropped by clean_item_folders anyway,
         # but refusing here means we never write it in the first place.
                 return set((cur_ws.get('views') or {}))
             return set(_cohorts(ctx).all_for(uname))
+        # ⚠ A CELL THE CLOSURE FILLS, because `_mutate` has ONE way to say no — `return None` —
+        # and eleven distinct reasons for saying it. Threading the cause out through the existing
+        # sentinel keeps every refusal at the line that decided it, rather than re-deriving the
+        # reason at the caller from state that has already moved on.
+        why = {}
+        def _no(code, message, key=''):
+            """Refuse from inside `_mutate`, naming the cause. Returns None, the sentinel."""
+            why.clear()
+            why.update({'code': code, 'message': message, 'key': str(key or '')})
+            return None
         def _mutate(cur_ws):
             folders = _agf.clean_folders(cur_ws.get('folders'))
             placed = dict(cur_ws.get('itemFolders') or {})
             fid = str(event.get('folderId') or '').strip()[:80]
             if kind == 'folder_create':
                 name = str(event.get('name') or '').strip()[:_agf.MAX_FOLDER_NAME]
+                if len(lst) >= _agf.MAX_FOLDERS:
+                    # ⚠ THE CAP IS SPLIT OUT FROM THE MALFORMED CASE, because it is the one a
+                    # person can actually do something about and the only one they will ever hit.
+                    return _no('folders_at_cap',
+                               f'This sidebar already holds {_agf.MAX_FOLDERS} folders, which is '
+                               f'all it can show, so the new one was not created. Delete a folder '
+                               f'you no longer need, then try again.', key=fid)
+                if not fid or not name:
+                    return _no('folder_needs_a_name',
+                               'A folder needs a name before it can be created, so nothing was '
+                               'saved. Type a name and try again.', key=fid)
                 if any(f['id'] == fid for f in lst):
+                    return _no('folder_already_exists',
+                               'A folder with that id is already on this sidebar, so nothing was '
+                               'created. Reload the page to see the folders you have.', key=fid)
                 row = {'id': fid, 'name': name, 'order': len(lst)}
                 icon = _agf.clean_folder_icon(event.get('icon'))    # wave-9 I15 (C5)
                 if icon:
                     row['icon'] = icon
+                # OWNER INSTRUCTION 12 -- the client's `parent` reaches the store. Paired with
+                # `aios_grid.clean_folders`, which carries it through the sanitiser; NEITHER EDIT
+                # DOES ANYTHING ALONE. `clean_folders` runs over the whole list on every folder
+                # event, so a rename or a reorder cannot un-nest a folder as a side effect either.
+                # Bounded to 80 like every other id on this door, absent rather than null for the
+                # root, and self-parenting dropped. A parent naming a folder that has since been
+                # deleted is passed THROUGH on purpose: `validate_folder_tree` repairs it to the
+                # root and returns a receipt, which `_folder_repair_notice` already turns into the
+                # sentence the user reads.
+                parent = str(event.get('parent') or '').strip()[:80]
+                if parent and parent != fid:
+                    row['parent'] = parent
                 lst.append(row)
             elif kind == 'folder_rename':
                 name = str(event.get('name') or '').strip()[:_agf.MAX_FOLDER_NAME]
                 hit = next((f for f in lst if f['id'] == fid), None)
+                if not hit:
+                    return _no('folder_gone',
+                               'That folder is not on this sidebar any more, so it could not be '
+                               'renamed. Reload the page to see the folders you have.', key=fid)
+                # ⭐⭐ W41-T14 · OWNER INSTRUCTION 11 — AN ICON-ONLY EVENT IS LEGAL ON THIS DOOR.
+                #
+                # ⛔ THE SECOND HALF OF THE INSTRUCTION IS *"allow changing the icon from the
+                # '...' menu"* — a Change icon item, NOT the rename pane wave-9 built this branch
+                # for. A dialog that changes only the icon has no name to send, and until this
+                # line `{folderId, icon}` fell straight into the refusal below: the receiver of a
+                # gesture that never mentioned a name was told *"A folder needs a name"*, the icon
+                # was not stored, and both lanes were individually correct
+                # ([[two-lanes-one-contract-dead-feature]], with a wrong sentence on top).
+                #
+                # ⚠ THE DISCRIMINATION IS THE `name` KEY, NOT ITS EMPTINESS, and that is what
+                # keeps W41-T13's refusal intact: an event that CARRIES `name` and means blank is
+                # still a rename to nothing and is still refused, in T13's exact words. Today's
+                # client always sends one (`CustomerGrid.tsx::onFolderRename`), so every event
+                # that has ever been emitted takes the byte-identical path. An event with neither
+                # a usable name nor an `icon` key is malformed and is refused as it always was.
+                if not name and ('name' in event or 'icon' not in event):
+                    return _no('folder_needs_a_name',
+                               'A folder needs a name, so the new one was not saved and the old '
+                               'name was kept. Type a name and try again.', key=fid)
+                if name:
+                    hit['name'] = name
                 # wave-9 I15 (C5): the rename pane is also where the icon is changed. An event
                 # that carries NO icon key leaves the existing one alone (a rename must not
                 # silently strip a chosen icon); an explicit null clears it back to default.
+                # ⚠ W41-T14 MEASURED THE LIMIT RATHER THAN WIDENING IT: `clean_folder_icon`
+                # answers None for an explicit null AND for a junk shape, so this branch cannot
+                # tell *"clear my icon"* from *"that shape does not exist"* and drops the stored
+                # icon either way. Nothing junk is ever STORED, which is what this ticket owes;
+                # the conflation is booked rather than fixed here, because a new refusal would
+                # claim the single `toast` slot on the path W41-T35 is about to exercise.
                 if 'icon' in event:
                     icon = _agf.clean_folder_icon(event.get('icon'))
                     if icon:
                         hit.pop('icon', None)
             elif kind == 'folder_delete':
                 if not any(f['id'] == fid for f in lst):
+                    return _no('folder_gone',
+                               'That folder is not on this sidebar any more, so there was nothing '
+                               'to delete. Reload the page to see the folders you have.', key=fid)
                 lst = [f for f in lst if f['id'] != fid]
                 # CONTENTS MOVE TO ROOT, never delete. Dropping the placements is exactly that:
                 # an item with no placement renders at the top level.
                 # folder it merely failed to mention would be a data loss dressed as a sort.
                 order = [str(i).strip()[:80] for i in (event.get('order') or [])]
                 if not order:
+                    return _no('order_named_no_folders',
+                               'That rail arrangement named no folders, so the order you had was '
+                               'kept. Drag the folder again.')
                 known = {f['id']: f for f in lst}
                 seen, ranked = set(), []
                 for fid_ in order:
                         ranked.append(known[fid_])
                 ranked.extend(f for f in lst if f['id'] not in seen)
                 if len(ranked) != len(lst):          # cannot happen; refuse rather than truncate
+                    return _no('order_incomplete',
+                               'That rail arrangement could not be applied without losing a '
+                               'folder, so the order you had was kept. Reload the page and try '
+                               'again.')
                 for i, f in enumerate(ranked):
                     f['order'] = i
                 lst = ranked
             elif kind == 'folder_duplicate':
                 new_id = str(event.get('newId') or '').strip()[:80]
                 src = next((f for f in lst if f['id'] == fid), None)
+                if len(lst) >= _agf.MAX_FOLDERS:
+                    return _no('folders_at_cap',
+                               f'This sidebar already holds {_agf.MAX_FOLDERS} folders, which is '
+                               f'all it can show, so the copy was not made. Delete a folder you '
+                               f'no longer need, then try again.', key=fid)
+                if not src:
+                    return _no('folder_gone',
+                               'That folder is not on this sidebar any more, so there was nothing '
+                               'to copy. Reload the page to see the folders you have.', key=fid)
+                if not new_id:
+                    return _no('duplicate_without_id',
+                               'The copy was not given an id, so nothing was created. Try '
+                               'duplicating the folder again.', key=fid)
                 if any(f['id'] == new_id for f in lst):
+                    return _no('folder_already_exists',
+                               'A folder with that id is already on this sidebar, so the copy was '
+                               'not made. Reload the page to see the folders you have.',
+                               key=new_id)
                 lst.append({'id': new_id, 'name': f"{src['name']} copy"[:_agf.MAX_FOLDER_NAME],
                             'order': len(lst)})
                 # ⚠ The folder's CONTENTS are duplicated by the client emitting the ordinary
             else:                                   # item_move
                 item_id = str(event.get('itemId') or '').strip()[:120]
                 target = event.get('folderId')
+                # ⭐⭐ W41-T13 / OWNER INSTRUCTION 10 — THE TWO CAUSES ARE SPLIT, and the split is
+                # the ticket's own argument: `not item_id` is a malformed event, `not in _own_ids`
+                # is a permission answer, and one `return None` for both told the user neither.
+                if not item_id:
+                    return _no('move_without_item',
+                               'That move did not say which item to file, so nothing was saved. '
+                               'Drag the item again.')
+                if item_id not in _own_ids(surface, cur_ws):
+                    # ⚠ Worded for the person, not the wall: a view shared WITH someone is in
+                    # their rail and is not theirs to file, which is the case they will meet.
+                    return _no('item_not_yours',
+                               'You can file only the items you own, and this one belongs to '
+                               'somebody else, so it stayed where it was.', key=item_id)
                 cur = dict(placed.get(surface) or {})
                 if target is None:
                     # ⚠ "UNFILE" — the client says nothing about where it went. Popping is right
                 else:
                     tid = str(target)[:80]
                     if not any(f['id'] == tid for f in lst):
+                        return _no('folder_gone',
+                                   'That folder is not on this sidebar any more, so the item '
+                                   'stayed where it was. Reload the page to see the folders you '
+                                   'have, then try again.', key=tid)
                     cur[item_id] = tid
                 placed[surface] = cur
             folders[surface] = lst
         # change inside a pure move.
         _res = _mutate(table_workspace(ctx, consume_corrections=False))
         if _res is None:
+            # Refused: nothing is written — and now the caller is TOLD, with the cause `_mutate`
+            # recorded at the line that decided it. The fallback exists so a future `return None`
+            # added without a `_no(...)` degrades to a generic sentence rather than to silence.
+            return _folder_refuse(
+                ctx, kind,
+                why.get('code') or 'folder_change_refused',
+                why.get('message') or ('That folder change could not be saved, so nothing was '
+                                       'altered. Reload the page and try again.'),
+                key=why.get('key') or '')
+        # ⭐⭐ W41-T12's HANDOVER, TAKEN. `save_folders` VALIDATES before it writes and RAISES
+        # `FolderTreeError` on a cycle or an over-deep chain, having written nothing. Letting that
+        # escape would 500 the whole event window; catching it and dropping the result would put
+        # it straight back into the silent-200 path this ticket exists to close. `str(exc)` is
+        # already the sentence a person reads and already C7-clean, and `folder_id` is an
+        # attribute, so nothing is parsed out of the message.
+        #
+        # ⚠ UNREACHABLE FROM THIS DOOR TODAY, AND SAYING SO IS PART OF THE HANDOVER.
+        # `_mutate` returns `_agf.clean_folders(...)`, whose row is `{id, name, order}` plus an
+        # optional `icon` — it STRIPS `parent` entirely, so no nesting can reach the validator
+        # through here and neither raise can fire. This is the forward contract with T12: the day
+        # `clean_folders` learns `parent`, the refusal is already wired and worded.
+        try:
+            _receipt = _tops(ctx).save_folders(uname, _res[0], _res[1])
+        except _tstore.FolderTreeError as _fte:
+            return _folder_refuse(ctx, kind,
+                                  str(getattr(_fte, 'reason', '') or 'folder_tree_illegal'),
+                                  str(_fte), key=str(getattr(_fte, 'folder_id', '') or ''))
+        # ⭐⭐ THE DURABILITY HALF — the owner's actual complaint. See `_commit_folder_write`: the
+        # write above lands in `Store._cache` and the hub commit is deferred by up to ~22s, so
+        # a second process (or the same one after a restart) cannot read it back. Forced here,
+        # for EVERY folder kind rather than `item_move` alone: they all write one key through one
+        # `save_folders`, they are all one discrete gesture, and a `folder_create` that evaporated
+        # would take the move filed into it with it.
+        _commit_folder_write(_tops(ctx))
+        # W41-T12's receipt, partitioned. A repair means the stored tree differs from what was
+        # dragged, which the user has to be told or their sidebar silently disagrees with them.
+        _notice = _folder_repair_notice((_receipt or {}).get('repairs'))
+        if _notice:
+            try:
+                ctx.out.toast = _notice[:300]
+            except Exception:                                         # noqa: BLE001
+                pass
         # True: the sidebars render from server state (which folder holds what), not from local
         # optimism — the same contract the cohort panel's membership edits ride.
         return True
         import aios_grid as _ag3
         if not (key.startswith('custom_') or key.startswith(_ag3.MEASURE_FIELD_PREFIX)):
             return False
+        # ⭐⭐ W41-T02 / RULING R6a+R6b / CONTRACT C2 — THE RIGHT, ASKED OF THE ONE PAIR THAT OWNS
+        # IT. Until now this door had NO rights test at all: the prefix above was the whole of
+        # the wall, so any holder of a grid could delete a column somebody else made and shared
+        # with them, and an administrator could delete a pre-set the rename door had always
+        # refused them. C2's last sentence is *"No surface re-implements either test"*, so the
+        # answer comes from `user_tables.may_delete_field`, which derives it from C1's badges.
+        #
+        # ⚠ THE PREFIX TEST STAYS, AND IT IS NOT THE SAME WALL. It is STRUCTURAL — it says which
+        # STRATUM a key could even be deleted from, which is what stops the browser claiming a
+        # base contract column is deletable. The predicate is the RIGHTS wall over the columns
+        # that survive it. Replacing one with the other would drop a check in either direction.
+        #
+        # ⛔ NO `_refuse` HERE, ON PURPOSE. That helper stamps `'event': 'field_upsert'` on every
+        # record it writes, so reporting from this branch would file a refusal that lies about
+        # which event it was. The refusal is real and silent for exactly one more ticket: W41-T07
+        # owns turning this door's `return False` into a truthy result with a message, and this
+        # line is what gives it a genuine refusal to carry. Until then the wall is proved from
+        # STORE STATE — the definition is still there after a refused delete — never from a
+        # refusal record this door cannot yet emit honestly.
+        # ⚠ THE DEFINITION IS RESOLVED IN TWO PLACES, AND THE SECOND IS NOT BELT-AND-BRACES.
+        # `field_by_key` is `ctx.fields`, bound ONCE per request, and it must be asked FIRST
+        # because it is the only one carrying the tenant-wide SHARED stratum (merged into the
+        # served contract by the assembly, never into this user's own bucket). But it is also
+        # STALE inside a batch: `handle_events` walks a window of events with one ctx, so a
+        # create and a delete arriving in the same burst would leave the delete looking at a
+        # field list assembled before the create landed — and the pair fails CLOSED, so the
+        # column would survive its own delete. `ws` is re-read per event a few lines up, so the
+        # per-user stratum it holds is current. Neither lookup DECIDES anything; both just hand
+        # the same one predicate the definition it is owed.
+        _defn = field_by_key.get(key)
+        if not isinstance(_defn, dict):
+            _defn = (ws.get('fields') or {}).get(key)
+        _share_key, _share_topic = _field_share_keys(ctx)
+        import core.user_tables as _ut2
+        if not _ut2.may_delete_field(
+                _share_key, key, uname, bool(admin),
+                ctx.st or getattr(ctx.table, 'st', None),
+                field=_defn, grant_topic=_share_topic):
+            return False
+        # W41-T07 / OWNER INSTRUCTION 21 -- DELETE FROM EVERY STRATUM, NOT JUST THIS USER'S.
+        # Owner: *"Deleting a field from Hide fields does not stick; 'August Campaign' on Odoo
+        # customer has reappeared three times."* It reappeared because THIS door never deleted
+        # it: `table_store.delete_field` reaches exactly one member of the workspace document --
+        # the deleter's own -- while the definition survives in `shared_overlay`'s bucket and in
+        # every other account's fork, and `migrate_legacy_fields` (which runs on EVERY read)
+        # promotes one straight back. Measured in-process by the ticket that built the executor:
+        # drop, one read, the column is back.
+        #
+        # W41-T07 BUILT `delete_field_everywhere` and wired it to `routes_tables.py::
+        # delete_shared_field`, the generic `ut_*` door. THIS door -- the one serving
+        # `customer_data` and `product_data`, which is the grid the owner named -- was left on the
+        # single-stratum call, so the fix existed and the defect shipped anyway. A correct
+        # mechanism on the wrong door is why every gate stayed green. [[two-lanes-one-contract-dead-feature]]
+        #
+        # THE RIGHT WAS ALREADY DECIDED ABOVE and is not decided again here: C2's last sentence is
+        # *"No surface re-implements either test"*, and `may_delete_field` is that test. This is
+        # the EXECUTION half only, which is exactly what the executor's own docstring says it is.
+        # The keys are the pair `_field_share_keys` already resolved: `customer_data`'s per-user
+        # and tenant-wide strata are named from ONE key (`routes_customers::_shared_key` --
+        # *"the store key this topic's per-user AND tenant-wide strata are both named from"*), so
+        # workspace and shared are the same argument here, and the grant topic is the second.
         if _store_of(ctx).available():
+            import core.field_permissions as _fp2
+            _removed = _fp2.delete_field_everywhere(
+                _share_key, _share_key, _share_topic, key,
+                st=ctx.st or getattr(ctx.table, 'st', None))
+            # The per-leg report is kept rather than reduced to a boolean: a delete that reached
+            # the shared bucket but no fork, or the reverse, is a different fact from a clean one.
+            try:
+                ctx.out.derived = dict(getattr(ctx.out, 'derived', None) or {},
+                                       fieldDeleteRemoved=_removed)
+            except Exception:                                          # noqa: BLE001
+                pass
         else:
             _session_ready()
             ws['fields'].pop(key, None)

platform/core/perm_scope.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

platform/core/script_sandbox.py CHANGED Viewed

@@ -1,519 +1,519 @@
-"""core/script_sandbox.py — WAVE 36 (R5 / R10, contract C1): running a tenant's OWN Python.
-Owner item 6: *"Add code script as an interface (database View) so a user can build whatever they
-want through the Agent chat interface."* Item 8: *"We need to really guardrail the reach of this
-script. So let's really grill this down."* R10 ruled it SERVER-SIDE PYTHON after the trade was
-stated, so this file is the guardrail, and one engine serves both items.
-════════════════════════════════════════════════════════════════════════════════════════════════
-⛔⛔ THE ONE PARAGRAPH TO READ BEFORE CHANGING ANYTHING HERE.
-In-process CPython cannot deliver two of this ticket's clauses. An AST allow-list plus a curated
-namespace stops import, file, network and environment access — but it **cannot cap memory and
-cannot interrupt a runaway loop**, because a `while True:` in the same interpreter is not a slow
-request, it is the tenant's ONE FastAPI process gone. So the script runs in a **SUBPROCESS**:
-`resource.setrlimit` for address space and CPU, a hard wall-clock kill from the parent, and the
-allow-list inside. Neither half is sufficient; both are load-bearing.
-⭐ AND THE SUBPROCESS RECEIVES **ROWS, NEVER A STORE**. The parent calls C1's `scoped_table` under
-the CALLING user's record and serialises the result; the child imports nothing from this repo and
-holds no credential, no runtime and no store handle. Wiring W1 ("the sandbox has no second store
-path") is then true by CONSTRUCTION rather than by discipline, and it is checkable: the child
-reports its own `sys.modules`, and no `core.*` name may appear in it.
-⛔ NEVER A BLACKLIST. Every rule below is an ALLOW-LIST — a set of node types, a set of attribute
-names, a dict of builtins. A blacklist of dangerous spellings is bypassable by construction, and
-the bypass is usually one string method away (`"{0.__class__}".format(x)` performs its attribute
-lookup inside `format`, so there is no `ast.Attribute` node to refuse).
-════════════════════════════════════════════════════════════════════════════════════════════════
-The two layers, and they refuse DIFFERENT things on purpose:
-  1. `check_source()` — a pure function over source text. Refuses a construct the language offers
-     and this sandbox does not: `import`, `class`, `with`, `async`, `yield`, `global`, and every
-     attribute name outside `ALLOWED_ATTRS`.
-  2. `SANDBOX_BUILTINS` — the names that resolve at all. `__import__`, `open`, `eval`, `exec`,
-     `compile`, `getattr`, `globals`, `vars` and `type` are simply absent, so a source that gets
-     past layer 1 still finds nothing to call.
-⚠ THAT DUPLICATION IS DELIBERATE AND IT CHANGES HOW THE GATE MUST BE WRITTEN. `import os` is
-refused twice, so a negative control that drops ONE layer sees the other refuse and reports
-green — the shape that already cost this wave one missed control in `routes_agent_harness`. So
-each layer is tested AT ITS OWN BOUNDARY: `check_source()` is called directly on source strings,
-and `run()` is driven end to end. An NC drops one entry from one frozenset and the matching
-boundary goes red.
-"""
-import ast
-import json
-import os
-import subprocess
-import sys
-import tempfile
-import time
-from pathlib import Path
-#: Wall clock, enforced by the PARENT with a kill. The one cap that works on every platform.
-DEFAULT_TIMEOUT_S = 10.0
-#: Address space for the child (`RLIMIT_AS`). POSIX only — see `run()`'s `caps` report.
-DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024
-#: CPU seconds for the child (`RLIMIT_CPU`). POSIX only. Deliberately above the wall clock: the
-#: wall-clock kill is the primary control and this is the backstop for a child that stops being
-#: reachable. A CPU limit BELOW the timeout would make every slow script look like a CPU refusal.
-DEFAULT_CPU_SECONDS = 15
-#: What the script may print, in bytes. `print` is a curated builtin writing to a capped buffer,
-#: and the child's real stdout goes to DEVNULL — so a script cannot fill a pipe, and anything
-#: that escaped far enough to write to fd 1 has nowhere for it to land.
-MAX_STDOUT_BYTES = 64 * 1024
-#: The serialised ROW payload handed to the child. ⛔ A REFUSAL, NEVER A TRUNCATION (standing rule
-#: 1): a short answer from a data tool is a wrong answer that looks right. Over this, `run()`
-#: returns a named limit carrying its cause and a recommendation.
-MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
-#: The emitted spec. A render spec is a description of a picture; one larger than this is data
-#: pretending to be a description.
-MAX_SPEC_BYTES = 2 * 1024 * 1024
-MAX_SOURCE_BYTES = 128 * 1024
-# ══════════════════════════════════════════════════════ LAYER 1 — the AST allow-list ═══════════
-#: Every `ast` node class a script may contain. ⛔ THE ABSENCES ARE THE POLICY: `Import` /
-#: `ImportFrom` (no module reaches the script), `ClassDef` (a class body is a namespace with its
-#: own scoping rules and buys a data script nothing), `With` (a context manager is `__enter__`
-#: by another spelling), `Global` / `Nonlocal` (rebinding the sandbox's own names), and every
-#: `Async*` / `Await` / `Yield` form (this engine is synchronous; a coroutine that is never
-#: awaited is a silent no-op that looks like a working script).
-ALLOWED_NODES = frozenset("""
-Module Expr Assign AugAssign AnnAssign NamedExpr Return Pass Break Continue Delete Assert Raise
-If For While Try TryStar ExceptHandler FunctionDef Lambda arguments arg keyword
-BoolOp BinOp UnaryOp IfExp Dict Set List Tuple Starred Subscript Slice Compare Call Attribute Name
-Constant JoinedStr FormattedValue ListComp SetComp DictComp GeneratorExp comprehension
-Load Store Del
-And Or Not Invert UAdd USub
-Add Sub Mult Div FloorDiv Mod Pow LShift RShift BitOr BitXor BitAnd MatMult
-Eq NotEq Lt LtE Gt GtE Is IsNot In NotIn
-""".split())
-#: Every attribute name a script may READ or CALL. ⛔⛔ THIS IS THE LOAD-BEARING SET, and it is
-#: an allow-list of NAMES rather than a refusal of dunders, because the interesting escapes are
-#: ordinary-looking: `f.__globals__` on any function reaches the runner's own module namespace,
-#: `e.__traceback__.tb_frame.f_globals` reaches it from an exception handler, and `().__class__`
-#: reaches `object.__subclasses__`. None of those names is here, and neither is any name this
-#: sandbox has not been asked for.
-#: ⚠ `format` IS ABSENT DELIBERATELY. `"{0.__class__}".format(x)` performs the attribute lookup
-#: INSIDE `str.format`, where no `ast.Attribute` node exists for layer 1 to see. f-strings are
-#: fine — `f"{x.__class__}"` compiles to a real `Attribute` node and is refused.
-ALLOWED_ATTRS = frozenset("""
-append extend insert pop remove clear sort reverse copy count index
-keys values items get setdefault update
-add discard union intersection difference issubset issuperset
-join split rsplit splitlines strip lstrip rstrip lower upper title capitalize casefold
-replace startswith endswith find rfind zfill ljust rjust center partition removeprefix removesuffix
-isdigit isalpha isalnum isspace isupper islower isnumeric
-real imag numerator denominator
-""".split())
-class Refused(Exception):
-    """A named refusal: `code` for a caller to branch on, `message` for a person to read."""
-    def __init__(self, code, message):
-        self.code, self.message = code, message
-        super().__init__(f"{code}: {message}")
-def _attr_ok(name):
-    """An attribute name passes only if it is on the list AND is not private.
-    ⚠ THE SECOND TEST IS NOT A BLACKLIST — it narrows an allow-list that already excludes every
-    private name. It is here so that adding a name to `ALLOWED_ATTRS` cannot open a dunder by
-    accident, which is the one edit a future reader is most likely to make in a hurry.
-    """
-    return name in ALLOWED_ATTRS and not name.startswith("_")
-def check_source(source):
-    """LAYER 1. Return a `Refused` for source this sandbox will not run, or `None`.
-    ⭐ PURE, AND THAT IS WHAT MAKES IT TESTABLE AT ITS OWN BOUNDARY. It reads no file, spawns no
-    process and touches no store, so a gate can hand it a hundred hostile strings for free and an
-    NC can drop one entry from one frozenset and watch exactly this function change its answer.
-    """
-    text = str(source or "")
-    if len(text.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
-        return Refused("source_too_long",
-                       f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of source")
-    try:
-        tree = ast.parse(text)
-    except SyntaxError as exc:
-        return Refused("syntax", f"line {exc.lineno or 0}: {exc.msg}")
-    for node in ast.walk(tree):
-        kind = type(node).__name__
-        if kind not in ALLOWED_NODES:
-            return Refused("refused_construct",
-                           f"line {getattr(node, 'lineno', 0)}: this sandbox does not run "
-                           f"{_english(kind)}")
-        if isinstance(node, ast.Attribute) and not _attr_ok(node.attr):
-            return Refused("refused_attribute",
-                           f"line {getattr(node, 'lineno', 0)}: the attribute "
-                           f"'{node.attr}' is not available inside a script view")
-        # ⛔ A NAME may not be private either. `_` prefixed names are the runner's own, and a
-        # script that could bind one could shadow the machinery it runs on top of.
-        if isinstance(node, ast.Name) and node.id.startswith("_"):
-            return Refused("reserved_name",
-                           f"line {getattr(node, 'lineno', 0)}: names starting with an "
-                           f"underscore are reserved by the sandbox")
-        if isinstance(node, (ast.FunctionDef, ast.arg, ast.ExceptHandler)) and str(
-                getattr(node, "name", None) or getattr(node, "arg", "") or "").startswith("_"):
-            return Refused("reserved_name",
-                           f"line {getattr(node, 'lineno', 0)}: names starting with an "
-                           f"underscore are reserved by the sandbox")
-        if isinstance(node, ast.keyword) and str(node.arg or "").startswith("_"):
-            return Refused("reserved_name",
-                           f"line {getattr(node, 'lineno', 0)}: keyword arguments starting with "
-                           f"an underscore are reserved by the sandbox")
-    return None
-_ENGLISH = {
-    "Import": "an import", "ImportFrom": "an import", "ClassDef": "a class definition",
-    "With": "a with block", "AsyncWith": "a with block", "AsyncFor": "an async loop",
-    "AsyncFunctionDef": "an async function", "Await": "await", "Yield": "yield",
-    "YieldFrom": "yield from", "Global": "a global statement", "Nonlocal": "a nonlocal statement",
-    "Match": "a match statement",
-}
-def _english(kind):
-    return _ENGLISH.get(kind, f"a {kind} expression")
-# ══════════════════════════════════════════ LAYER 2 — the namespace, and the child program ═════
-#: The builtins a script may reach, BY NAME. Everything else is a `NameError` in the child.
-#: ⛔ THE ABSENCES, again, are the policy: `__import__` `open` `eval` `exec` `compile` `input`
-#: `getattr` `setattr` `delattr` `globals` `locals` `vars` `dir` `type` `super` `object` `help`
-#: `exit` `breakpoint` `memoryview` `id`. Several are harmless on their own; each one is a step
-#: on a published escape, and none has ever been asked for by a script that shapes rows.
-#: ⚠ THE EXCEPTION CLASSES ARE HERE BECAUSE `try:` IS, and a `try` block whose `except` clause
-#: cannot name what it catches is a construct that reads as supported and is not. They are safe
-#: for the same reason everything else is: `Exception.__subclasses__` needs an attribute this
-#: sandbox does not allow, so a class object in the namespace is a leaf, not a doorway.
-SANDBOX_BUILTIN_NAMES = (
-    "abs all any bool bytes callable chr dict divmod enumerate filter float frozenset hash hex "
-    "int isinstance issubclass iter len list map max min next oct ord pow range repr reversed "
-    "round set slice sorted str sum tuple zip True False None "
-    "Exception ValueError TypeError KeyError IndexError ZeroDivisionError ArithmeticError "
-    "AttributeError StopIteration OverflowError"
-).split()
-#: The literal program the child runs. It is TEXT rather than a module because the child must
-#: import nothing from this repo: a module would be found on `sys.path` and would drag `core`
-#: with it, which is exactly the second store path W1 forbids.
-#: ⚠ Every name in here is underscore-prefixed and layer 1 refuses a script from binding one, so
-#: the runner's own machinery cannot be shadowed by the source it executes.
-_RUNNER = r'''
-import json as _json, os as _os, sys as _sys
-_pay = _json.loads(open(_sys.argv[1], "r", encoding="utf-8").read())
-_out = {"ok": False, "code": "not_run", "message": "the script did not run",
-        "stdout": "", "spec": None, "caps": {"wallClock": True, "memory": False, "cpu": False}}
-# ── the caps this platform can actually apply, reported either way (standing rule 1) ──────────
-try:
-    import resource as _res
-    _mem = int(_pay["memoryBytes"])
-    _res.setrlimit(_res.RLIMIT_AS, (_mem, _mem))
-    _out["caps"]["memory"] = True
-    _cpu = int(_pay["cpuSeconds"])
-    _res.setrlimit(_res.RLIMIT_CPU, (_cpu, _cpu))
-    _out["caps"]["cpu"] = True
-except Exception:
-    # `resource` is POSIX only. The wall-clock kill in the parent still applies, and `caps` says
-    # which of the three held, never a silent partial.
-    pass
-_printed = []
-_spent = [0]
-_LIMIT = int(_pay["maxStdout"])
-def _print(*_a, **_k):
-    _text = (_k.get("sep") or " ").join(str(_x) for _x in _a) + (_k.get("end") or "\n")
-    _room = _LIMIT - _spent[0]
-    if _room > 0:
-        _printed.append(_text[:_room])
-        _spent[0] += len(_text)
-class _Refusal(Exception):
-    """The SANDBOX refusing, as distinct from the SCRIPT failing.
-    Without its own class these arrive as `ValueError`, indistinguishable from a `ValueError` the
-    script raised itself, and the answer then says "refused" about an ordinary bug in the tenant's
-    own code. Two different facts, two different codes.
-    """
-_emitted = []
-def _emit(_spec):
-    if not isinstance(_spec, dict):
-        raise _Refusal("emit() takes a view spec, which is a dictionary")
-    if _emitted:
-        raise _Refusal("emit() was already called; a script view emits exactly one view")
-    _emitted.append(_spec)
-_rows = _pay["rows"]
-_fields = _pay["fields"]
-_bound = _pay["table"]
-def _scoped_table(_table=None):
-    if _table is not None and str(_table) != _bound:
-        raise _Refusal(
-            "this script view is bound to the database '" + _bound + "' and asked for '"
-            + str(_table) + "'. A script view reads its own database only")
-    return [dict(_r) for _r in _rows]
-def _scoped_fields():
-    return [dict(_f) for _f in _fields]
-_ns = {"__builtins__": {_n: __builtins__[_n] if isinstance(__builtins__, dict)
-                        else getattr(__builtins__, _n)
-                        for _n in _pay["builtins"]}}
-_ns["__builtins__"]["print"] = _print
-_ns["print"] = _print
-_ns["emit"] = _emit
-_ns["scoped_table"] = _scoped_table
-_ns["scoped_fields"] = _scoped_fields
-_ns["table"] = _bound
-try:
-    exec(compile(_pay["source"], "<script view>", "exec"), _ns)
-    if not _emitted:
-        _out.update(ok=False, code="no_view",
-                    message="the script finished without calling emit(spec)")
-    else:
-        _out.update(ok=True, code="", message="", spec=_emitted[0])
-except _Refusal as _e:
-    _out.update(ok=False, code="refused", message=str(_e)[:400])
-except MemoryError:
-    _out.update(ok=False, code="memory",
-                message="the script used more memory than a script view is allowed")
-except NameError as _e:
-    _out.update(ok=False, code="refused_name",
-                message=str(_e)[:200] + ". A script view may use only the names the sandbox "
-                                        "provides")
-except BaseException as _e:
-    _out.update(ok=False, code="error",
-                message=type(_e).__name__ + ": " + str(_e)[:400])
-_out["stdout"] = "".join(_printed)
-_out["truncated"] = _spent[0] > _LIMIT
-# ⭐ THE PROBE: what this child actually had. The PARENT strips it unless it was asked for, so a
-# production run never carries it and a gate can still prove that no `core.*` module and no
-# secret-shaped environment key was ever inside this process.
-# ⚠ SNAPSHOTTED AFTER `exec`, and `os` is imported at the TOP so this list does not depend on
-# dict-literal evaluation order. The first draft called `__import__("os")` inside this very
-# expression, so whether `os` appeared depended on which value Python built first: a probe whose
-# contents move with an unrelated edit is a probe a gate cannot assert against.
-_out["probe"] = {"modules": sorted(_sys.modules), "env": sorted(_os.environ)}
-open(_sys.argv[2], "w", encoding="utf-8").write(_json.dumps(_out, default=str))
-'''
-def _child_env():
-    """The child's WHOLE environment. An allow-list of two keys, and neither is a credential.
-    ⛔ NOT `os.environ.copy()` MINUS SOMETHING. A subtractive environment ships every key nobody
-    thought to name: `HF_TOKEN`, `ODOO_PASSWORD`, `ANTHROPIC_API_KEY` and whatever the next
-    connector adds. The three names below are here because Python will not start on Windows
-    without them; on Linux this returns `{}` and the child runs with no environment at all.
-    """
-    env = {}
-    for name in ("SystemRoot", "SYSTEMROOT", "WINDIR"):
-        if os.environ.get(name):
-            env[name] = os.environ[name]
-    return env
-def run(source, rows, fields, table_key, *, timeout_s=DEFAULT_TIMEOUT_S,
-        memory_bytes=DEFAULT_MEMORY_BYTES, cpu_seconds=DEFAULT_CPU_SECONDS, probe=False):
-    """Run ONE script over rows that are ALREADY scoped. Returns C3's envelope plus `caps`.
-        {ok, code, message, spec, stdout, truncated, ms, caps: {wallClock, memory, cpu}}
-    ⛔ THIS FUNCTION NEVER TOUCHES A STORE, AND THAT IS THE POINT: it takes rows. `run_view()`
-    below is the door that fetches them through C1; keeping the two apart is what lets a gate
-    drive the sandbox with no tenant, no runtime and no credential anywhere in the process.
-    ⚠ `caps` IS PART OF THE ANSWER, NOT DEBUG OUTPUT. On Windows `resource` does not exist, so
-    the memory and CPU limits are NOT applied and this says so. A caller that reports `ok:true`
-    without reading `caps` is claiming an enforcement that did not happen (standing rule 1).
-    """
-    started = time.monotonic()
-    refusal = check_source(source)
-    if refusal is not None:
-        return _refusal(refusal.code, refusal.message, started)
-    payload = {"source": str(source or ""), "rows": rows, "fields": fields,
-               "table": str(table_key or ""), "builtins": SANDBOX_BUILTIN_NAMES,
-               "maxStdout": MAX_STDOUT_BYTES, "memoryBytes": int(memory_bytes),
-               "cpuSeconds": int(cpu_seconds)}
-    try:
-        blob = json.dumps(payload, default=str)
-    except (TypeError, ValueError) as exc:
-        return _refusal("bad_rows", f"these rows cannot be handed to a script ({exc})", started)
-    if len(blob.encode("utf-8", "replace")) > MAX_PAYLOAD_BYTES:
-        # ⛔ REPORTED, NOT TRUNCATED (standing rule 1's second sentence): cause and recommendation,
-        # in the words the owner asked for, rather than a quietly short answer.
-        return _refusal(
-            "payload_too_large",
-            f"this database's rows are larger than the {MAX_PAYLOAD_BYTES // (1024 * 1024)} MB a "
-            f"script view can be handed at once. Narrow the view with a filter, or raise the "
-            f"sandbox payload limit for this deployment", started)
-    with tempfile.TemporaryDirectory(prefix="aios-script-") as work:
-        pay_path = Path(work) / "payload.json"
-        res_path = Path(work) / "result.json"
-        pay_path.write_text(blob, encoding="utf-8")
-        # `-I` isolates the interpreter (no PYTHON* env, no user site), `-S` skips site-packages,
-        # and the program arrives on STDIN so there is no file for anything to import it as.
-        # ⛔ `-X utf8` AND AN EXPLICIT `encoding` ARE NOT TIDINESS. Without them this pipe is
-        # encoded with the parent's locale codec, which on this Windows box is cp1252: the runner
-        # text below cannot be represented in it and `subprocess.run` died with
-        # `UnicodeEncodeError` before the child ever started. A sandbox whose behaviour depends on
-        # the operator's locale is a sandbox with two behaviours. `-I` implies `-E`, so
-        # `PYTHONUTF8` in the environment could not have carried this, it has to be a flag.
-        argv = [sys.executable, "-I", "-S", "-X", "utf8", "-", str(pay_path), str(res_path)]
-        try:
-            done = subprocess.run(
-                argv, input=_RUNNER, text=True, encoding="utf-8", errors="replace",
-                cwd=work, env=_child_env(),
-                stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout_s)
-        except subprocess.TimeoutExpired:
-            return _refusal("timeout",
-                            f"the script ran longer than {timeout_s:g} seconds and was stopped",
-                            started)
-        except OSError as exc:
-            return _refusal("no_sandbox",
-                            f"a script view could not be started on this deployment ({exc})",
-                            started)
-        if not res_path.is_file():
-            # The child died without writing an answer: an rlimit signal, an OOM kill, or a crash.
-            # ⚠ NAMED BY ITS RETURN CODE rather than reported as a generic failure — a memory kill
-            # and a bug in this file must not read identically to an operator.
-            return _refusal(*_died(done), started)
-        try:
-            out = json.loads(res_path.read_text(encoding="utf-8"))
-        except (OSError, ValueError) as exc:
-            return _refusal("unreadable", f"the script's answer could not be read ({exc})",
-                            started)
-    out["ms"] = int((time.monotonic() - started) * 1000)
-    if out.get("ok"):
-        spec_error = _check_spec(out.get("spec"))
-        if spec_error:
-            out.update(ok=False, code="bad_spec", message=spec_error, spec=None)
-    if not probe:
-        out.pop("probe", None)
-    return out
-def _died(done):
-    """`(code, message)` for a child that produced no answer."""
-    rc = done.returncode
-    tail = " ".join((done.stderr or "").split())[-300:]
-    if rc in (-9, 137):
-        return "memory", "the script was stopped for using too much memory"
-    if rc in (-24, 152):
-        return "timeout", "the script used more processor time than a script view is allowed"
-    return "crashed", f"the script view engine stopped without an answer{': ' + tail if tail else ''}"
-def _refusal(code, message, started):
-    return {"ok": False, "code": code, "message": message, "spec": None, "stdout": "",
-            "truncated": False, "ms": int((time.monotonic() - started) * 1000),
-            "caps": {"wallClock": True, "memory": False, "cpu": False}}
-def _check_spec(spec):
-    """C3: a spec is a DESCRIPTION the client draws. Never HTML, never a script, never a URL.
-    ⛔ THE CHECK IS ON THE KEYS, NOT ON THE STRING CONTENTS. Scanning values for `<script>` is a
-    blacklist and would pass `<SCR` + `IPT>`; refusing a spec that carries an `html`, `script`,
-    `src` or `onclick` key refuses the SHAPE that would let a renderer be talked into executing
-    something. The vocabulary of legal `kind`s is the ROUTE's business (W36-T37) — this is the
-    floor every caller gets whether or not the route above it remembers.
-    """
-    if not isinstance(spec, dict):
-        return "the script emitted something that is not a view spec"
-    try:
-        blob = json.dumps(spec)
-    except (TypeError, ValueError):
-        return "the emitted view spec is not something the client can be sent"
-    if len(blob.encode("utf-8", "replace")) > MAX_SPEC_BYTES:
-        return (f"the emitted view spec is over {MAX_SPEC_BYTES // (1024 * 1024)} MB. A view spec "
-                f"describes a picture; it is not where the rows go")
-    banned = {"html", "innerhtml", "script", "src", "srcdoc", "href", "style", "onclick", "onload"}
-    found = sorted(k for k in _keys_of(spec) if str(k).lower() in banned)
-    if found:
-        return (f"a view spec may not carry {', '.join(found)}. The client DRAWS a spec, so a "
-                f"markup or URL key would be a script by another name")
-    return None
-def _keys_of(value, depth=0):
-    """Every key anywhere in a nested spec. Bounded, so a deep structure cannot spin this."""
-    if depth > 12:
-        return
-    if isinstance(value, dict):
-        for key, sub in value.items():
-            yield key
-            yield from _keys_of(sub, depth + 1)
-    elif isinstance(value, (list, tuple)):
-        for sub in value:
-            yield from _keys_of(sub, depth + 1)
-# ══════════════════════════════════════════════ THE DOOR — C1 is the ONLY way to a row ═════════
-def run_view(user, table_key, source, st=None, **kw):
-    """Fetch through C1 under `user`'s scope, then run the script over what came back (R5).
-    ⭐⭐ THE FETCH HAPPENS IN THE PARENT AND ONLY ROWS CROSS INTO THE CHILD. That is wiring W1
-    made structural: the child has no runtime to ask, no store handle to open and no credential
-    to use, so "a script cannot read what its caller cannot read" is not a rule anybody has to
-    keep — there is no second path for it to be broken through.
-    ⛔ C1'S THREE EXCEPTIONS ARE ANSWERED, NEVER SWALLOWED. `UnknownTable`, `Denied` and
-    `Unresolvable` mean three different things to a person; collapsing them into "no rows" is the
-    silent-empty answer C1 was written to make impossible. `Unresolvable.as_limit()` is handed
-    through in the words it was raised with — standing rule 1's second sentence, verbatim.
-    """
-    import core.perm_scope as perm_scope
-    key = str(table_key or "")
-    try:
-        rows = perm_scope.scoped_table(user, key, st=st)
-        fields = perm_scope.scoped_fields(user, key, st=st)
-    except perm_scope.UnknownTable as exc:
-        return _refusal("unknown_table", str(exc) or f"there is no database '{key}'",
-                        time.monotonic())
-    except perm_scope.Denied as exc:
-        return _refusal("denied", str(exc) or "this account may not read that database",
-                        time.monotonic())
-    except perm_scope.Unresolvable as exc:
-        out = _refusal("unresolvable", str(exc), time.monotonic())
-        out["limit"] = exc.as_limit()
-        return out
-    return run(source, rows, fields, key, **kw)

+"""core/script_sandbox.py — WAVE 36 (R5 / R10, contract C1): running a tenant's OWN Python.
+Owner item 6: *"Add code script as an interface (database View) so a user can build whatever they
+want through the Agent chat interface."* Item 8: *"We need to really guardrail the reach of this
+script. So let's really grill this down."* R10 ruled it SERVER-SIDE PYTHON after the trade was
+stated, so this file is the guardrail, and one engine serves both items.
+════════════════════════════════════════════════════════════════════════════════════════════════
+⛔⛔ THE ONE PARAGRAPH TO READ BEFORE CHANGING ANYTHING HERE.
+In-process CPython cannot deliver two of this ticket's clauses. An AST allow-list plus a curated
+namespace stops import, file, network and environment access — but it **cannot cap memory and
+cannot interrupt a runaway loop**, because a `while True:` in the same interpreter is not a slow
+request, it is the tenant's ONE FastAPI process gone. So the script runs in a **SUBPROCESS**:
+`resource.setrlimit` for address space and CPU, a hard wall-clock kill from the parent, and the
+allow-list inside. Neither half is sufficient; both are load-bearing.
+⭐ AND THE SUBPROCESS RECEIVES **ROWS, NEVER A STORE**. The parent calls C1's `scoped_table` under
+the CALLING user's record and serialises the result; the child imports nothing from this repo and
+holds no credential, no runtime and no store handle. Wiring W1 ("the sandbox has no second store
+path") is then true by CONSTRUCTION rather than by discipline, and it is checkable: the child
+reports its own `sys.modules`, and no `core.*` name may appear in it.
+⛔ NEVER A BLACKLIST. Every rule below is an ALLOW-LIST — a set of node types, a set of attribute
+names, a dict of builtins. A blacklist of dangerous spellings is bypassable by construction, and
+the bypass is usually one string method away (`"{0.__class__}".format(x)` performs its attribute
+lookup inside `format`, so there is no `ast.Attribute` node to refuse).
+════════════════════════════════════════════════════════════════════════════════════════════════
+The two layers, and they refuse DIFFERENT things on purpose:
+  1. `check_source()` — a pure function over source text. Refuses a construct the language offers
+     and this sandbox does not: `import`, `class`, `with`, `async`, `yield`, `global`, and every
+     attribute name outside `ALLOWED_ATTRS`.
+  2. `SANDBOX_BUILTINS` — the names that resolve at all. `__import__`, `open`, `eval`, `exec`,
+     `compile`, `getattr`, `globals`, `vars` and `type` are simply absent, so a source that gets
+     past layer 1 still finds nothing to call.
+⚠ THAT DUPLICATION IS DELIBERATE AND IT CHANGES HOW THE GATE MUST BE WRITTEN. `import os` is
+refused twice, so a negative control that drops ONE layer sees the other refuse and reports
+green — the shape that already cost this wave one missed control in `routes_agent_harness`. So
+each layer is tested AT ITS OWN BOUNDARY: `check_source()` is called directly on source strings,
+and `run()` is driven end to end. An NC drops one entry from one frozenset and the matching
+boundary goes red.
+"""
+import ast
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+#: Wall clock, enforced by the PARENT with a kill. The one cap that works on every platform.
+DEFAULT_TIMEOUT_S = 10.0
+#: Address space for the child (`RLIMIT_AS`). POSIX only — see `run()`'s `caps` report.
+DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024
+#: CPU seconds for the child (`RLIMIT_CPU`). POSIX only. Deliberately above the wall clock: the
+#: wall-clock kill is the primary control and this is the backstop for a child that stops being
+#: reachable. A CPU limit BELOW the timeout would make every slow script look like a CPU refusal.
+DEFAULT_CPU_SECONDS = 15
+#: What the script may print, in bytes. `print` is a curated builtin writing to a capped buffer,
+#: and the child's real stdout goes to DEVNULL — so a script cannot fill a pipe, and anything
+#: that escaped far enough to write to fd 1 has nowhere for it to land.
+MAX_STDOUT_BYTES = 64 * 1024
+#: The serialised ROW payload handed to the child. ⛔ A REFUSAL, NEVER A TRUNCATION (standing rule
+#: 1): a short answer from a data tool is a wrong answer that looks right. Over this, `run()`
+#: returns a named limit carrying its cause and a recommendation.
+MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
+#: The emitted spec. A render spec is a description of a picture; one larger than this is data
+#: pretending to be a description.
+MAX_SPEC_BYTES = 2 * 1024 * 1024
+MAX_SOURCE_BYTES = 128 * 1024
+# ══════════════════════════════════════════════════════ LAYER 1 — the AST allow-list ═══════════
+#: Every `ast` node class a script may contain. ⛔ THE ABSENCES ARE THE POLICY: `Import` /
+#: `ImportFrom` (no module reaches the script), `ClassDef` (a class body is a namespace with its
+#: own scoping rules and buys a data script nothing), `With` (a context manager is `__enter__`
+#: by another spelling), `Global` / `Nonlocal` (rebinding the sandbox's own names), and every
+#: `Async*` / `Await` / `Yield` form (this engine is synchronous; a coroutine that is never
+#: awaited is a silent no-op that looks like a working script).
+ALLOWED_NODES = frozenset("""
+Module Expr Assign AugAssign AnnAssign NamedExpr Return Pass Break Continue Delete Assert Raise
+If For While Try TryStar ExceptHandler FunctionDef Lambda arguments arg keyword
+BoolOp BinOp UnaryOp IfExp Dict Set List Tuple Starred Subscript Slice Compare Call Attribute Name
+Constant JoinedStr FormattedValue ListComp SetComp DictComp GeneratorExp comprehension
+Load Store Del
+And Or Not Invert UAdd USub
+Add Sub Mult Div FloorDiv Mod Pow LShift RShift BitOr BitXor BitAnd MatMult
+Eq NotEq Lt LtE Gt GtE Is IsNot In NotIn
+""".split())
+#: Every attribute name a script may READ or CALL. ⛔⛔ THIS IS THE LOAD-BEARING SET, and it is
+#: an allow-list of NAMES rather than a refusal of dunders, because the interesting escapes are
+#: ordinary-looking: `f.__globals__` on any function reaches the runner's own module namespace,
+#: `e.__traceback__.tb_frame.f_globals` reaches it from an exception handler, and `().__class__`
+#: reaches `object.__subclasses__`. None of those names is here, and neither is any name this
+#: sandbox has not been asked for.
+#: ⚠ `format` IS ABSENT DELIBERATELY. `"{0.__class__}".format(x)` performs the attribute lookup
+#: INSIDE `str.format`, where no `ast.Attribute` node exists for layer 1 to see. f-strings are
+#: fine — `f"{x.__class__}"` compiles to a real `Attribute` node and is refused.
+ALLOWED_ATTRS = frozenset("""
+append extend insert pop remove clear sort reverse copy count index
+keys values items get setdefault update
+add discard union intersection difference issubset issuperset
+join split rsplit splitlines strip lstrip rstrip lower upper title capitalize casefold
+replace startswith endswith find rfind zfill ljust rjust center partition removeprefix removesuffix
+isdigit isalpha isalnum isspace isupper islower isnumeric
+real imag numerator denominator
+""".split())
+class Refused(Exception):
+    """A named refusal: `code` for a caller to branch on, `message` for a person to read."""
+    def __init__(self, code, message):
+        self.code, self.message = code, message
+        super().__init__(f"{code}: {message}")
+def _attr_ok(name):
+    """An attribute name passes only if it is on the list AND is not private.
+    ⚠ THE SECOND TEST IS NOT A BLACKLIST — it narrows an allow-list that already excludes every
+    private name. It is here so that adding a name to `ALLOWED_ATTRS` cannot open a dunder by
+    accident, which is the one edit a future reader is most likely to make in a hurry.
+    """
+    return name in ALLOWED_ATTRS and not name.startswith("_")
+def check_source(source):
+    """LAYER 1. Return a `Refused` for source this sandbox will not run, or `None`.
+    ⭐ PURE, AND THAT IS WHAT MAKES IT TESTABLE AT ITS OWN BOUNDARY. It reads no file, spawns no
+    process and touches no store, so a gate can hand it a hundred hostile strings for free and an
+    NC can drop one entry from one frozenset and watch exactly this function change its answer.
+    """
+    text = str(source or "")
+    if len(text.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
+        return Refused("source_too_long",
+                       f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of source")
+    try:
+        tree = ast.parse(text)
+    except SyntaxError as exc:
+        return Refused("syntax", f"line {exc.lineno or 0}: {exc.msg}")
+    for node in ast.walk(tree):
+        kind = type(node).__name__
+        if kind not in ALLOWED_NODES:
+            return Refused("refused_construct",
+                           f"line {getattr(node, 'lineno', 0)}: this sandbox does not run "
+                           f"{_english(kind)}")
+        if isinstance(node, ast.Attribute) and not _attr_ok(node.attr):
+            return Refused("refused_attribute",
+                           f"line {getattr(node, 'lineno', 0)}: the attribute "
+                           f"'{node.attr}' is not available inside a script view")
+        # ⛔ A NAME may not be private either. `_` prefixed names are the runner's own, and a
+        # script that could bind one could shadow the machinery it runs on top of.
+        if isinstance(node, ast.Name) and node.id.startswith("_"):
+            return Refused("reserved_name",
+                           f"line {getattr(node, 'lineno', 0)}: names starting with an "
+                           f"underscore are reserved by the sandbox")
+        if isinstance(node, (ast.FunctionDef, ast.arg, ast.ExceptHandler)) and str(
+                getattr(node, "name", None) or getattr(node, "arg", "") or "").startswith("_"):
+            return Refused("reserved_name",
+                           f"line {getattr(node, 'lineno', 0)}: names starting with an "
+                           f"underscore are reserved by the sandbox")
+        if isinstance(node, ast.keyword) and str(node.arg or "").startswith("_"):
+            return Refused("reserved_name",
+                           f"line {getattr(node, 'lineno', 0)}: keyword arguments starting with "
+                           f"an underscore are reserved by the sandbox")
+    return None
+_ENGLISH = {
+    "Import": "an import", "ImportFrom": "an import", "ClassDef": "a class definition",
+    "With": "a with block", "AsyncWith": "a with block", "AsyncFor": "an async loop",
+    "AsyncFunctionDef": "an async function", "Await": "await", "Yield": "yield",
+    "YieldFrom": "yield from", "Global": "a global statement", "Nonlocal": "a nonlocal statement",
+    "Match": "a match statement",
+}
+def _english(kind):
+    return _ENGLISH.get(kind, f"a {kind} expression")
+# ══════════════════════════════════════════ LAYER 2 — the namespace, and the child program ═════
+#: The builtins a script may reach, BY NAME. Everything else is a `NameError` in the child.
+#: ⛔ THE ABSENCES, again, are the policy: `__import__` `open` `eval` `exec` `compile` `input`
+#: `getattr` `setattr` `delattr` `globals` `locals` `vars` `dir` `type` `super` `object` `help`
+#: `exit` `breakpoint` `memoryview` `id`. Several are harmless on their own; each one is a step
+#: on a published escape, and none has ever been asked for by a script that shapes rows.
+#: ⚠ THE EXCEPTION CLASSES ARE HERE BECAUSE `try:` IS, and a `try` block whose `except` clause
+#: cannot name what it catches is a construct that reads as supported and is not. They are safe
+#: for the same reason everything else is: `Exception.__subclasses__` needs an attribute this
+#: sandbox does not allow, so a class object in the namespace is a leaf, not a doorway.
+SANDBOX_BUILTIN_NAMES = (
+    "abs all any bool bytes callable chr dict divmod enumerate filter float frozenset hash hex "
+    "int isinstance issubclass iter len list map max min next oct ord pow range repr reversed "
+    "round set slice sorted str sum tuple zip True False None "
+    "Exception ValueError TypeError KeyError IndexError ZeroDivisionError ArithmeticError "
+    "AttributeError StopIteration OverflowError"
+).split()
+#: The literal program the child runs. It is TEXT rather than a module because the child must
+#: import nothing from this repo: a module would be found on `sys.path` and would drag `core`
+#: with it, which is exactly the second store path W1 forbids.
+#: ⚠ Every name in here is underscore-prefixed and layer 1 refuses a script from binding one, so
+#: the runner's own machinery cannot be shadowed by the source it executes.
+_RUNNER = r'''
+import json as _json, os as _os, sys as _sys
+_pay = _json.loads(open(_sys.argv[1], "r", encoding="utf-8").read())
+_out = {"ok": False, "code": "not_run", "message": "the script did not run",
+        "stdout": "", "spec": None, "caps": {"wallClock": True, "memory": False, "cpu": False}}
+# ── the caps this platform can actually apply, reported either way (standing rule 1) ──────────
+try:
+    import resource as _res
+    _mem = int(_pay["memoryBytes"])
+    _res.setrlimit(_res.RLIMIT_AS, (_mem, _mem))
+    _out["caps"]["memory"] = True
+    _cpu = int(_pay["cpuSeconds"])
+    _res.setrlimit(_res.RLIMIT_CPU, (_cpu, _cpu))
+    _out["caps"]["cpu"] = True
+except Exception:
+    # `resource` is POSIX only. The wall-clock kill in the parent still applies, and `caps` says
+    # which of the three held, never a silent partial.
+    pass
+_printed = []
+_spent = [0]
+_LIMIT = int(_pay["maxStdout"])
+def _print(*_a, **_k):
+    _text = (_k.get("sep") or " ").join(str(_x) for _x in _a) + (_k.get("end") or "\n")
+    _room = _LIMIT - _spent[0]
+    if _room > 0:
+        _printed.append(_text[:_room])
+        _spent[0] += len(_text)
+class _Refusal(Exception):
+    """The SANDBOX refusing, as distinct from the SCRIPT failing.
+    Without its own class these arrive as `ValueError`, indistinguishable from a `ValueError` the
+    script raised itself, and the answer then says "refused" about an ordinary bug in the tenant's
+    own code. Two different facts, two different codes.
+    """
+_emitted = []
+def _emit(_spec):
+    if not isinstance(_spec, dict):
+        raise _Refusal("emit() takes a view spec, which is a dictionary")
+    if _emitted:
+        raise _Refusal("emit() was already called; a script view emits exactly one view")
+    _emitted.append(_spec)
+_rows = _pay["rows"]
+_fields = _pay["fields"]
+_bound = _pay["table"]
+def _scoped_table(_table=None):
+    if _table is not None and str(_table) != _bound:
+        raise _Refusal(
+            "this script view is bound to the database '" + _bound + "' and asked for '"
+            + str(_table) + "'. A script view reads its own database only")
+    return [dict(_r) for _r in _rows]
+def _scoped_fields():
+    return [dict(_f) for _f in _fields]
+_ns = {"__builtins__": {_n: __builtins__[_n] if isinstance(__builtins__, dict)
+                        else getattr(__builtins__, _n)
+                        for _n in _pay["builtins"]}}
+_ns["__builtins__"]["print"] = _print
+_ns["print"] = _print
+_ns["emit"] = _emit
+_ns["scoped_table"] = _scoped_table
+_ns["scoped_fields"] = _scoped_fields
+_ns["table"] = _bound
+try:
+    exec(compile(_pay["source"], "<script view>", "exec"), _ns)
+    if not _emitted:
+        _out.update(ok=False, code="no_view",
+                    message="the script finished without calling emit(spec)")
+    else:
+        _out.update(ok=True, code="", message="", spec=_emitted[0])
+except _Refusal as _e:
+    _out.update(ok=False, code="refused", message=str(_e)[:400])
+except MemoryError:
+    _out.update(ok=False, code="memory",
+                message="the script used more memory than a script view is allowed")
+except NameError as _e:
+    _out.update(ok=False, code="refused_name",
+                message=str(_e)[:200] + ". A script view may use only the names the sandbox "
+                                        "provides")
+except BaseException as _e:
+    _out.update(ok=False, code="error",
+                message=type(_e).__name__ + ": " + str(_e)[:400])
+_out["stdout"] = "".join(_printed)
+_out["truncated"] = _spent[0] > _LIMIT
+# ⭐ THE PROBE: what this child actually had. The PARENT strips it unless it was asked for, so a
+# production run never carries it and a gate can still prove that no `core.*` module and no
+# secret-shaped environment key was ever inside this process.
+# ⚠ SNAPSHOTTED AFTER `exec`, and `os` is imported at the TOP so this list does not depend on
+# dict-literal evaluation order. The first draft called `__import__("os")` inside this very
+# expression, so whether `os` appeared depended on which value Python built first: a probe whose
+# contents move with an unrelated edit is a probe a gate cannot assert against.
+_out["probe"] = {"modules": sorted(_sys.modules), "env": sorted(_os.environ)}
+open(_sys.argv[2], "w", encoding="utf-8").write(_json.dumps(_out, default=str))
+'''
+def _child_env():
+    """The child's WHOLE environment. An allow-list of two keys, and neither is a credential.
+    ⛔ NOT `os.environ.copy()` MINUS SOMETHING. A subtractive environment ships every key nobody
+    thought to name: `HF_TOKEN`, `ODOO_PASSWORD`, `ANTHROPIC_API_KEY` and whatever the next
+    connector adds. The three names below are here because Python will not start on Windows
+    without them; on Linux this returns `{}` and the child runs with no environment at all.
+    """
+    env = {}
+    for name in ("SystemRoot", "SYSTEMROOT", "WINDIR"):
+        if os.environ.get(name):
+            env[name] = os.environ[name]
+    return env
+def run(source, rows, fields, table_key, *, timeout_s=DEFAULT_TIMEOUT_S,
+        memory_bytes=DEFAULT_MEMORY_BYTES, cpu_seconds=DEFAULT_CPU_SECONDS, probe=False):
+    """Run ONE script over rows that are ALREADY scoped. Returns C3's envelope plus `caps`.
+        {ok, code, message, spec, stdout, truncated, ms, caps: {wallClock, memory, cpu}}
+    ⛔ THIS FUNCTION NEVER TOUCHES A STORE, AND THAT IS THE POINT: it takes rows. `run_view()`
+    below is the door that fetches them through C1; keeping the two apart is what lets a gate
+    drive the sandbox with no tenant, no runtime and no credential anywhere in the process.
+    ⚠ `caps` IS PART OF THE ANSWER, NOT DEBUG OUTPUT. On Windows `resource` does not exist, so
+    the memory and CPU limits are NOT applied and this says so. A caller that reports `ok:true`
+    without reading `caps` is claiming an enforcement that did not happen (standing rule 1).
+    """
+    started = time.monotonic()
+    refusal = check_source(source)
+    if refusal is not None:
+        return _refusal(refusal.code, refusal.message, started)
+    payload = {"source": str(source or ""), "rows": rows, "fields": fields,
+               "table": str(table_key or ""), "builtins": SANDBOX_BUILTIN_NAMES,
+               "maxStdout": MAX_STDOUT_BYTES, "memoryBytes": int(memory_bytes),
+               "cpuSeconds": int(cpu_seconds)}
+    try:
+        blob = json.dumps(payload, default=str)
+    except (TypeError, ValueError) as exc:
+        return _refusal("bad_rows", f"these rows cannot be handed to a script ({exc})", started)
+    if len(blob.encode("utf-8", "replace")) > MAX_PAYLOAD_BYTES:
+        # ⛔ REPORTED, NOT TRUNCATED (standing rule 1's second sentence): cause and recommendation,
+        # in the words the owner asked for, rather than a quietly short answer.
+        return _refusal(
+            "payload_too_large",
+            f"this database's rows are larger than the {MAX_PAYLOAD_BYTES // (1024 * 1024)} MB a "
+            f"script view can be handed at once. Narrow the view with a filter, or raise the "
+            f"sandbox payload limit for this deployment", started)
+    with tempfile.TemporaryDirectory(prefix="aios-script-") as work:
+        pay_path = Path(work) / "payload.json"
+        res_path = Path(work) / "result.json"
+        pay_path.write_text(blob, encoding="utf-8")
+        # `-I` isolates the interpreter (no PYTHON* env, no user site), `-S` skips site-packages,
+        # and the program arrives on STDIN so there is no file for anything to import it as.
+        # ⛔ `-X utf8` AND AN EXPLICIT `encoding` ARE NOT TIDINESS. Without them this pipe is
+        # encoded with the parent's locale codec, which on this Windows box is cp1252: the runner
+        # text below cannot be represented in it and `subprocess.run` died with
+        # `UnicodeEncodeError` before the child ever started. A sandbox whose behaviour depends on
+        # the operator's locale is a sandbox with two behaviours. `-I` implies `-E`, so
+        # `PYTHONUTF8` in the environment could not have carried this, it has to be a flag.
+        argv = [sys.executable, "-I", "-S", "-X", "utf8", "-", str(pay_path), str(res_path)]
+        try:
+            done = subprocess.run(
+                argv, input=_RUNNER, text=True, encoding="utf-8", errors="replace",
+                cwd=work, env=_child_env(),
+                stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout_s)
+        except subprocess.TimeoutExpired:
+            return _refusal("timeout",
+                            f"the script ran longer than {timeout_s:g} seconds and was stopped",
+                            started)
+        except OSError as exc:
+            return _refusal("no_sandbox",
+                            f"a script view could not be started on this deployment ({exc})",
+                            started)
+        if not res_path.is_file():
+            # The child died without writing an answer: an rlimit signal, an OOM kill, or a crash.
+            # ⚠ NAMED BY ITS RETURN CODE rather than reported as a generic failure — a memory kill
+            # and a bug in this file must not read identically to an operator.
+            return _refusal(*_died(done), started)
+        try:
+            out = json.loads(res_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            return _refusal("unreadable", f"the script's answer could not be read ({exc})",
+                            started)
+    out["ms"] = int((time.monotonic() - started) * 1000)
+    if out.get("ok"):
+        spec_error = _check_spec(out.get("spec"))
+        if spec_error:
+            out.update(ok=False, code="bad_spec", message=spec_error, spec=None)
+    if not probe:
+        out.pop("probe", None)
+    return out
+def _died(done):
+    """`(code, message)` for a child that produced no answer."""
+    rc = done.returncode
+    tail = " ".join((done.stderr or "").split())[-300:]
+    if rc in (-9, 137):
+        return "memory", "the script was stopped for using too much memory"
+    if rc in (-24, 152):
+        return "timeout", "the script used more processor time than a script view is allowed"
+    return "crashed", f"the script view engine stopped without an answer{': ' + tail if tail else ''}"
+def _refusal(code, message, started):
+    return {"ok": False, "code": code, "message": message, "spec": None, "stdout": "",
+            "truncated": False, "ms": int((time.monotonic() - started) * 1000),
+            "caps": {"wallClock": True, "memory": False, "cpu": False}}
+def _check_spec(spec):
+    """C3: a spec is a DESCRIPTION the client draws. Never HTML, never a script, never a URL.
+    ⛔ THE CHECK IS ON THE KEYS, NOT ON THE STRING CONTENTS. Scanning values for `<script>` is a
+    blacklist and would pass `<SCR` + `IPT>`; refusing a spec that carries an `html`, `script`,
+    `src` or `onclick` key refuses the SHAPE that would let a renderer be talked into executing
+    something. The vocabulary of legal `kind`s is the ROUTE's business (W36-T37) — this is the
+    floor every caller gets whether or not the route above it remembers.
+    """
+    if not isinstance(spec, dict):
+        return "the script emitted something that is not a view spec"
+    try:
+        blob = json.dumps(spec)
+    except (TypeError, ValueError):
+        return "the emitted view spec is not something the client can be sent"
+    if len(blob.encode("utf-8", "replace")) > MAX_SPEC_BYTES:
+        return (f"the emitted view spec is over {MAX_SPEC_BYTES // (1024 * 1024)} MB. A view spec "
+                f"describes a picture; it is not where the rows go")
+    banned = {"html", "innerhtml", "script", "src", "srcdoc", "href", "style", "onclick", "onload"}
+    found = sorted(k for k in _keys_of(spec) if str(k).lower() in banned)
+    if found:
+        return (f"a view spec may not carry {', '.join(found)}. The client DRAWS a spec, so a "
+                f"markup or URL key would be a script by another name")
+    return None
+def _keys_of(value, depth=0):
+    """Every key anywhere in a nested spec. Bounded, so a deep structure cannot spin this."""
+    if depth > 12:
+        return
+    if isinstance(value, dict):
+        for key, sub in value.items():
+            yield key
+            yield from _keys_of(sub, depth + 1)
+    elif isinstance(value, (list, tuple)):
+        for sub in value:
+            yield from _keys_of(sub, depth + 1)
+# ══════════════════════════════════════════════ THE DOOR — C1 is the ONLY way to a row ═════════
+def run_view(user, table_key, source, st=None, **kw):
+    """Fetch through C1 under `user`'s scope, then run the script over what came back (R5).
+    ⭐⭐ THE FETCH HAPPENS IN THE PARENT AND ONLY ROWS CROSS INTO THE CHILD. That is wiring W1
+    made structural: the child has no runtime to ask, no store handle to open and no credential
+    to use, so "a script cannot read what its caller cannot read" is not a rule anybody has to
+    keep — there is no second path for it to be broken through.
+    ⛔ C1'S THREE EXCEPTIONS ARE ANSWERED, NEVER SWALLOWED. `UnknownTable`, `Denied` and
+    `Unresolvable` mean three different things to a person; collapsing them into "no rows" is the
+    silent-empty answer C1 was written to make impossible. `Unresolvable.as_limit()` is handed
+    through in the words it was raised with — standing rule 1's second sentence, verbatim.
+    """
+    import core.perm_scope as perm_scope
+    key = str(table_key or "")
+    try:
+        rows = perm_scope.scoped_table(user, key, st=st)
+        fields = perm_scope.scoped_fields(user, key, st=st)
+    except perm_scope.UnknownTable as exc:
+        return _refusal("unknown_table", str(exc) or f"there is no database '{key}'",
+                        time.monotonic())
+    except perm_scope.Denied as exc:
+        return _refusal("denied", str(exc) or "this account may not read that database",
+                        time.monotonic())
+    except perm_scope.Unresolvable as exc:
+        out = _refusal("unresolvable", str(exc), time.monotonic())
+        out["limit"] = exc.as_limit()
+        return out
+    return run(source, rows, fields, key, **kw)

platform/core/shared_overlay.py CHANGED Viewed

@@ -1,327 +1,521 @@
-"""The TENANT-WIDE overlay stratum — one value per (row, column) for the whole workspace.
-Wave 29, item 20 / owner ruling R11, contract C5. The sibling of `core/table_store.py`, which
-holds the PER-USER strata (`store.get(key)[username]`) and always has.
-⛔ THE DEFECT THIS EXISTS FOR IS NOT "SHARING WOULD BE NICE" — IT IS THAT A SHARED VIEW SILENTLY
-WIDENS. `modules/product_data.py` already states it, in the comment above the supplier master:
-    "A user-created field and its values live in the PER-USER strata; only VIEWS are shared. So a
-     shared 'Buy list' view that filtered on a user-created column would, for every OTHER account,
-     name a column that does not exist — and an unknown column is an INACTIVE condition in the
-     tri-state engine, which IGNORES it and therefore WIDENS. The buy list would silently show the
-     whole catalogue to everyone but its author."
-That is why the four supplier columns were frozen as read-only CONTRACT columns rather than made
-editable, and why the owner's ask ("turn this Excel sheet into a User created Field that we can
-edit") has been parked for two waves. A column whose value is the same for every reader makes the
-shared view mean ONE thing, which is the precondition for editing it at all.
-────────────────────────────────────────────────────────────────────────────────────────────────
-⛔⛔ THIS MODULE IS NOT A PERMISSION WALL, AND MUST NEVER BECOME ONE BY ACCIDENT.
-It refuses no reader and no writer. The caller has already answered "may this session open this
-surface" (`user_tables.may_open`, `Session.require`, the BU pool) and this module answers only
-"what is stored". Two different questions; one of them belongs upstream, where the session is.
-What it DOES enforce is the one thing a caller can get wrong silently:
-    ⭐ `cells(table_key, pids)` — `pids` IS REQUIRED, POSITIONALLY, AND THERE IS NO "EVERYTHING"
-      CALL. A default of "all rows" is the widening hazard above wearing a friendly face: the
-      caller passes the row set it has ALREADY scoped, so a cell for a row this reader may not see
-      cannot come back to be merged. There is deliberately no `all_cells()` to reach for; a caller
-      that genuinely needs the lot passes the lot, in writing, where a reviewer can see it.
-The row wall then holds twice over, because `aios_grid.rows_from_pool` iterates the POOL and looks
-each pid UP in the overlay — never the reverse. A cell for a row outside the pool has nothing to
-attach to. This module is built to keep that true rather than to re-implement it.
-────────────────────────────────────────────────────────────────────────────────────────────────
-RESIDENCY. Its own bucket, `<table_key>__shared`, beside the per-user one — never a `__shared__`
-member inside it. Two reasons, and the first is `product_data.py`'s own argument for separate
-topic keys ("separate store keys make that structurally impossible, which is the whole reason the
-table-page factory exists"): a per-user reader iterating usernames cannot encounter shared data
-when there is no shared data in that bucket to encounter. The second is cost — the per-user bucket
-carries every user's views, and a cell edit should not read-modify-write all of it.
-SHAPE, chosen to be drop-in:
-    {"fields": {field_key: Field},              # the tenant-wide column DEFINITIONS
-     "cells":  {"<pid>": {field_key: value}}}   # exactly `rows_from_pool(overlays=...)`'s shape
-`cells()` returns STRING pid keys for that reason — `rows_from_pool` does `overlays.get(str(pid))`,
-so a caller merges the shared stratum over the per-user one with one `dict.update` and cannot get
-the key type wrong. (`table_store` stores `{str(pid): {...}}` too; one shape, three readers.)
-"""
-import core.store as store
-#: The suffix that turns a topic's per-user workspace key into its shared one. Callers pass the
-#: key they ALREADY hold (`product_data.TABLE_KEY`, `f'{ut_key}_table_workspace'`) — one
-#: identifier for both strata, so there is no second naming convention to get wrong.
-BUCKET_SUFFIX = '__shared'
-#: One cell value's ceiling, matching the `json` field kind's. A shared cell is read by every user
-#: in the tenant, so an unbounded one is an unbounded cost for all of them.
-MAX_VALUE_CHARS = 32_768
-def bucket(table_key):
-    """The store key this topic's shared stratum lives under."""
-    key = str(table_key or '').strip()
-    if not key:
-        raise ValueError('shared_overlay: a table_key is required — it names the bucket')
-    return f'{key}{BUCKET_SUFFIX}'
-def _st(st):
-    return st if st is not None else store
-def _read(table_key, st=None):
-    """The whole stratum, always in its full two-key shape. Lenient like every other display
-    read: an unreachable store degrades to "nothing shared yet", never to an exception on a page
-    that would otherwise render."""
-    try:
-        data = _st(st).get(bucket(table_key)) or {}
-    except Exception:
-        data = {}
-    return {'fields': dict(data.get('fields') or {}),
-            'cells': dict(data.get('cells') or {})}
-def _write(table_key, change, st=None, flush='async'):
-    """Read-modify-write one shared stratum.
-    `flush='async'` by default for the same reason `table_store._update` uses it: a typed cell
-    lands here inside the request round-trip, and the historical synchronous hub commit cost
-    seconds per keystroke. Structural writes (a field definition) pass `flush='sync'` — they are
-    rare, and a lost column definition is a worse failure than a lost keystroke.
-    """
-    def _up(data):
-        data = data if isinstance(data, dict) else {}
-        data.setdefault('fields', {})
-        data.setdefault('cells', {})
-        change(data)
-        return data
-    return _st(st).update(bucket(table_key), _up, flush=flush)
-def _pid(pid):
-    """Pids are ints everywhere in the grid and strings in JSON. ONE coercion, here, so a caller
-    passing either cannot write a row that a reader keyed the other way never finds."""
-    return str(int(pid))
-def _value(value):
-    """A cell holds a SCALAR. The Row contract is scalar on every surface — the grid, the filter
-    engine, formulas, export — and the `json` kind is a validated STRING rather than an object.
-    ⛔ A dict or a list RAISES rather than being dropped. This is called by our own code, so a
-    non-scalar is a programming error, and silently storing nothing would surface later as "the
-    shared column is blank for everyone" with no failure anywhere near the cause.
-    """
-    if isinstance(value, (dict, list, tuple, set)):
-        raise ValueError(f'shared_overlay: a cell holds a scalar, not {type(value).__name__}')
-    if value is None or isinstance(value, bool) or isinstance(value, (int, float)):
-        return value
-    text = str(value)
-    return text[:MAX_VALUE_CHARS]
-# ----------------------------------------------------------------- the column DEFINITIONS
-def fields(table_key, st=None):
-    """`{field_key: Field}` — the columns this topic shares tenant-wide.
-    Unscoped on purpose, and it is the one thing here that is: a shared column's EXISTENCE is
-    tenant-wide by definition — that is the whole feature, and it is what stops a shared view
-    naming a column half the workspace lacks. Its VALUES are scoped by `cells()`.
-    """
-    return _read(table_key, st)['fields']
-def is_shared(table_key, field_key, st=None):
-    """Is this column's value tenant-wide? The predicate a caller uses to decide WHICH stratum to
-    read and write — one evaluator, so the read path and the write path cannot disagree about
-    where a given column lives ([[one-evaluator-per-question]])."""
-    return str(field_key or '') in _read(table_key, st)['fields']
-def put_field(table_key, field_key, defn, st=None):
-    """Declare (or redefine) a shared column. Returns what was stored."""
-    key = str(field_key or '').strip()
-    if not key:
-        raise ValueError('shared_overlay: a field needs a key')
-    entry = dict(defn or {})
-    entry['key'] = key
-    def _add(data):
-        data['fields'][key] = entry
-    _write(table_key, _add, st, flush='sync')
-    return entry
-def drop_field(table_key, field_key, st=None):
-    """Remove a shared column AND every stored value for it.
-    ⛔ The cells go with the definition, exactly as `table_store.delete_field` scrubs its own:
-    orphaned values would silently resurface if the key were ever reused — and a resurrected
-    value in a TENANT-WIDE stratum reappears for everybody at once.
-    """
-    key = str(field_key or '').strip()
-    if not key:
-        return False
-    hit = [False]
-    def _drop(data):
-        hit[0] = data['fields'].pop(key, None) is not None
-        for row in data['cells'].values():
-            if isinstance(row, dict):
-                row.pop(key, None)
-        # ⚠ AND DROP THE ROWS THAT ARE NOW EMPTY. `cells()` already skips a blank row, so this
-        # changes nothing a reader sees — but this bucket is read by every user in the tenant,
-        # and a `{}` per pid that once held a since-deleted column is dead weight that only ever
-        # grows. Caught by `prune()` reporting rows nobody could see as dropped.
-        for pid in [p for p, row in data['cells'].items() if not row]:
-            data['cells'].pop(pid, None)
-    _write(table_key, _drop, st, flush='sync')
-    return hit[0]
-# ----------------------------------------------------------------------------- the VALUES
-def cells(table_key, pids, st=None):
-    """`{"<pid>": {field_key: value}}` for the rows named by `pids` — and ONLY those.
-    ⛔ `pids` IS REQUIRED. See the module header: this is the row wall expressed as a signature,
-    so a caller cannot get "every shared cell in the tenant" by forgetting an argument. Pass the
-    pool you have already scoped for this session.
-    An empty `pids` legitimately returns `{}` — a reader with no rows sees no cells, which is the
-    correct answer rather than a special case.
-    """
-    if pids is None:
-        raise TypeError('shared_overlay.cells: pids is required — pass the row set you have '
-                        'already scoped for this reader (there is deliberately no "all" call)')
-    wanted = {_pid(p) for p in pids}
-    if not wanted:
-        return {}
-    stored = _read(table_key, st)['cells']
-    return {pid: dict(row) for pid, row in stored.items()
-            if pid in wanted and isinstance(row, dict) and row}
-def snapshot(table_key, pids, st=None):
-    """`(fields, cells)` for `pids` — the shared stratum's SCHEMA and VALUES, from ONE read.
-    ⛔⛔ THIS EXISTS BECAUSE TWO READS OF THIS BUCKET CAN DISAGREE, AND THE DISAGREEMENT OPENS A
-    WALL. `perm_scope._enrich_for_wall` needs both halves: the schema decides WHICH user columns
-    the row wall may answer, and the cells are the values it answers with. Taking them as two
-    `st.get()` calls leaves a gap in which a concurrent write can land, and a wave-40 adversarial
-    probe drove exactly that: with the second read returning an emptied `cells`, a blank is merged
-    for a key the store cannot really serve and `custom_x is not West` flips from denying every row
-    to ADMITTING a row whose true value IS West. `is empty` does the same. The set and the values
-    must come from one snapshot or they are not talking about the same tenant state.
-    ⚠ `pids` IS REQUIRED, exactly as in `cells()` — the row wall expressed as a signature, so no
-    caller can get "every shared cell in the tenant" by forgetting an argument.
-    """
-    if pids is None:
-        raise TypeError('shared_overlay.snapshot: pids is required — pass the row set you have '
-                        'already scoped for this reader (there is deliberately no "all" call)')
-    stored = _read(table_key, st)
-    wanted = {_pid(p) for p in pids}
-    served = {pid: dict(row) for pid, row in stored['cells'].items()
-              if pid in wanted and isinstance(row, dict) and row} if wanted else {}
-    return dict(stored['fields']), served
-def put_cell(table_key, pid, field_key, value, st=None):
-    """Write ONE shared cell. Returns the value as stored (which may be truncated)."""
-    return put_cells(table_key, pid, {field_key: value}, st=st).get(str(field_key or ''))
-def put_cells(table_key, pid, values, st=None):
-    """Write several shared cells on one row, in one store update. Returns what was stored."""
-    row_id = _pid(pid)
-    clean = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
-    if not clean:
-        return {}
-    def _patch(data):
-        data['cells'].setdefault(row_id, {}).update(clean)
-    _write(table_key, _patch, st)
-    return clean
-def put_rows(table_key, rows, st=None):
-    """Write shared cells on MANY rows in ONE store update. Returns `{row_id: {key: value}}`.
-    ⭐⭐ THE WHOLE POINT IS THE *ONE*, AND IT IS NOT AN OPTIMISATION. `put_cells` is one row per
-    store write, so a 1,397-row catalog import is 1,397 download-modify-upload cycles against one
-    JSON document. This repo has a MEASURED scar for that shape: **18 writes against one document
-    under the store's coalescing single-flight landed ZERO while answering 200 eighteen times.**
-    Batching is what makes a bulk import land at all, not what makes it fast.
-    ⚠ It deliberately takes the WHOLE SET rather than accepting a stream: a caller that loops over
-    this function has simply rebuilt `put_cells` with extra steps, and the failure it reintroduces
-    is silent. If the set does not fit in memory it does not fit in this store either — that is a
-    signal to change substrate, not to chunk.
-    ⛔ NO CAP HERE, ON PURPOSE. The bound belongs at the DOOR, where a caller identity and a
-    reportable refusal exist (`routes_grid.bulk_cells`). A silent ceiling in a store primitive is
-    exactly the shape the standing no-cap rule forbids.
-    """
-    clean = {}
-    for pid, values in dict(rows or {}).items():
-        row_id = _pid(pid)
-        cells_for_row = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
-        if cells_for_row:
-            clean.setdefault(row_id, {}).update(cells_for_row)
-    if not clean:
-        return {}
-    def _patch(data):
-        for row_id, values in clean.items():
-            data['cells'].setdefault(row_id, {}).update(values)
-    # `flush='sync'` because a bulk import must be durable when the call returns: the caller is a
-    # script that will report "1,397 rows written" and exit, and an async flush would make that
-    # sentence a prediction rather than a fact.
-    _write(table_key, _patch, st, flush='sync')
-    return clean
-def clear_row(table_key, pid, st=None):
-    """Forget every shared cell on one row. True when there was something to forget."""
-    row_id = _pid(pid)
-    hit = [False]
-    def _clear(data):
-        hit[0] = data['cells'].pop(row_id, None) is not None
-    _write(table_key, _clear, st)
-    return hit[0]
-def prune(table_key, live_pids, st=None):
-    """Drop shared cells for rows that no longer exist. Returns how many rows were dropped.
-    ⛔ NOT a scoped read wearing another name, and the difference is the whole reason `cells()`
-    refuses to serve everything: `live_pids` here means *every row this TABLE has*, which is a
-    fact about the data, whereas `pids` in `cells()` means *every row this READER may see*, which
-    is a fact about the session. Calling this with one session's pool would delete the shared
-    values of every row that session cannot see. The name says which is which; so does this note.
-    """
-    keep = {_pid(p) for p in live_pids}
-    dropped = [0]
-    def _prune(data):
-        gone = [pid for pid in data['cells'] if pid not in keep]
-        for pid in gone:
-            data['cells'].pop(pid, None)
-        dropped[0] = len(gone)
-    _write(table_key, _prune, st, flush='sync')
-    return dropped[0]

+"""The TENANT-WIDE overlay stratum — one value per (row, column) for the whole workspace.
+Wave 29, item 20 / owner ruling R11, contract C5. The sibling of `core/table_store.py`, which
+holds the PER-USER strata (`store.get(key)[username]`) and always has.
+⛔ THE DEFECT THIS EXISTS FOR IS NOT "SHARING WOULD BE NICE" — IT IS THAT A SHARED VIEW SILENTLY
+WIDENS. `modules/product_data.py` already states it, in the comment above the supplier master:
+    "A user-created field and its values live in the PER-USER strata; only VIEWS are shared. So a
+     shared 'Buy list' view that filtered on a user-created column would, for every OTHER account,
+     name a column that does not exist — and an unknown column is an INACTIVE condition in the
+     tri-state engine, which IGNORES it and therefore WIDENS. The buy list would silently show the
+     whole catalogue to everyone but its author."
+That is why the four supplier columns were frozen as read-only CONTRACT columns rather than made
+editable, and why the owner's ask ("turn this Excel sheet into a User created Field that we can
+edit") has been parked for two waves. A column whose value is the same for every reader makes the
+shared view mean ONE thing, which is the precondition for editing it at all.
+────────────────────────────────────────────────────────────────────────────────────────────────
+⛔⛔ THIS MODULE IS NOT A PERMISSION WALL, AND MUST NEVER BECOME ONE BY ACCIDENT.
+It refuses no reader and no writer. The caller has already answered "may this session open this
+surface" (`user_tables.may_open`, `Session.require`, the BU pool) and this module answers only
+"what is stored". Two different questions; one of them belongs upstream, where the session is.
+What it DOES enforce is the one thing a caller can get wrong silently:
+    ⭐ `cells(table_key, pids)` — `pids` IS REQUIRED, POSITIONALLY, AND THERE IS NO "EVERYTHING"
+      CALL. A default of "all rows" is the widening hazard above wearing a friendly face: the
+      caller passes the row set it has ALREADY scoped, so a cell for a row this reader may not see
+      cannot come back to be merged. There is deliberately no `all_cells()` to reach for; a caller
+      that genuinely needs the lot passes the lot, in writing, where a reviewer can see it.
+The row wall then holds twice over, because `aios_grid.rows_from_pool` iterates the POOL and looks
+each pid UP in the overlay — never the reverse. A cell for a row outside the pool has nothing to
+attach to. This module is built to keep that true rather than to re-implement it.
+────────────────────────────────────────────────────────────────────────────────────────────────
+RESIDENCY. Its own bucket, `<table_key>__shared`, beside the per-user one — never a `__shared__`
+member inside it. Two reasons, and the first is `product_data.py`'s own argument for separate
+topic keys ("separate store keys make that structurally impossible, which is the whole reason the
+table-page factory exists"): a per-user reader iterating usernames cannot encounter shared data
+when there is no shared data in that bucket to encounter. The second is cost — the per-user bucket
+carries every user's views, and a cell edit should not read-modify-write all of it.
+SHAPE, chosen to be drop-in:
+    {"fields": {field_key: Field},              # the tenant-wide column DEFINITIONS
+     "cells":  {"<pid>": {field_key: value}}}   # exactly `rows_from_pool(overlays=...)`'s shape
+`cells()` returns STRING pid keys for that reason — `rows_from_pool` does `overlays.get(str(pid))`,
+so a caller merges the shared stratum over the per-user one with one `dict.update` and cannot get
+the key type wrong. (`table_store` stores `{str(pid): {...}}` too; one shape, three readers.)
+"""
+import core.store as store
+#: The suffix that turns a topic's per-user workspace key into its shared one. Callers pass the
+#: key they ALREADY hold (`product_data.TABLE_KEY`, `f'{ut_key}_table_workspace'`) — one
+#: identifier for both strata, so there is no second naming convention to get wrong.
+BUCKET_SUFFIX = '__shared'
+#: One cell value's ceiling, matching the `json` field kind's. A shared cell is read by every user
+#: in the tenant, so an unbounded one is an unbounded cost for all of them.
+MAX_VALUE_CHARS = 32_768
+# ══════════════════════════ W41-T04 / CONTRACT C3 — ONE COLUMN-CREATION DOOR ══════════════════
+#
+# ⭐⭐ WHAT THIS ALLOWLIST IS FOR, AND WHY IT IS *HERE* RATHER THAN AT EACH CALLER. Before it,
+# `put_field` stored whatever it was handed, verbatim. That is what let
+# `routes_customers::route_order_write` become a documented BYPASS: the column menu's own door
+# (`aios_grid._field_extras`) is a strict allowlist and WOULD HAVE STRIPPED the route bag, so the
+# route feature reached around it into this function instead. A second minting path with different
+# rules is the defect C3 exists to close, and the fix is not to police the caller: it is to widen
+# THIS allowlist so the bypass has nothing left to buy.
+#
+# ⛔ THE `route` BAG IS THE WIDENING. It is the one key `_field_extras` cannot carry and the only
+# reason the bypass was written. With `route` on the list, `route_order_write` is an ordinary
+# caller of an ordinary door.
+#
+# ⚠ MINT-STRICT, REDEFINE CARRY-FORWARD, and the asymmetry is deliberate. On a MINT the allowlist
+# is the whole story: an unrecognised key is a caller mistake, and storing it would be the wave-19
+# `image` failure in reverse (a definition carrying state nothing reads). On a REDEFINE, a key the
+# STORE already holds that this list does not know is carried through untouched, because most
+# callers here are read-modify-write pass-throughs (`field_permissions` reconcile,
+# `routes_shares.put_share`, the route rename) and an allowlist that deleted a stored key on the
+# way past would be silent data loss on a tenant-wide document.
+#
+# ⚠ IT MUST AGREE WITH `aios_grid._field_extras`, WHICH IS THE SIBLING ALLOWLIST ON THE PER-USER
+# DOOR. That one is narrower on purpose (it is a client passthrough and validates each value);
+# this one is the union of the client `Field` interface (`web/src/customer-grid/types.ts`), the
+# canonical contract (`aios_grid_fields.json`), the server-only grant mark
+# (`perm_scope.FIELD_GRANT_MARK`) and `route`. `verify_field_doors.py` derives the union of keys
+# every writer actually passes and reds if this set does not cover it, so the two cannot drift
+# into silent stripping without a gate saying so.
+ALLOWED_FIELD_KEYS = frozenset({
+    # identity and shape
+    'key', 'label', 'type', 'source', 'kind',
+    # the description, in both its spellings: `note` is the user-authored one and `description`
+    # the canonical contract default. The client renders `note || description`.
+    'note', 'description', '_note',
+    # display and behaviour
+    'format', 'agg', 'options', 'optionColors', 'colorCodeOptions', 'default', 'pinned',
+    'filterable', 'multi', 'max', 'derived', 'preset', 'custom', 'profile', 'link',
+    # the created strata's computation bags
+    'formula', 'measure', 'metric', 'rollup', 'geocode', 'code', 'automation', 'aiEnrich',
+    'scope',
+    # governance
+    'createdBy', 'permissions', 'shared', 'granted', 'sharedRole', 'editRole', 'editRequestId',
+    # label-collision bookkeeping written by `table_store.save_field`
+    'labelCorrectedFrom', 'labelCorrectionId',
+    # ⭐ W41-T04: the route-order fingerprint bag. THE WIDENING that retires the bypass.
+    'route',
+})
+#: What `mint_field` requires of a column being born, named so a refusal can quote them.
+#: `createdBy` because an ownerless governed column is unmanageable (`shares.may_administer`
+#: fails closed on one, so nobody can ever share it); a grant list because "shared with nobody"
+#: has to be STORED to be different from "never shared"; a description because a tenant-wide
+#: column is read by people who did not make it.
+MINT_REQUIRES = ('createdBy', 'grants', 'description')
+#: The route bag's own ceiling. Small on purpose: it is a solve fingerprint, not a payload.
+MAX_ROUTE_CHARS = 256
+def bucket(table_key):
+    """The store key this topic's shared stratum lives under."""
+    key = str(table_key or '').strip()
+    if not key:
+        raise ValueError('shared_overlay: a table_key is required — it names the bucket')
+    return f'{key}{BUCKET_SUFFIX}'
+def _st(st):
+    return st if st is not None else store
+def _read(table_key, st=None):
+    """The whole stratum, always in its full two-key shape. Lenient like every other display
+    read: an unreachable store degrades to "nothing shared yet", never to an exception on a page
+    that would otherwise render."""
+    try:
+        data = _st(st).get(bucket(table_key)) or {}
+    except Exception:
+        data = {}
+    return {'fields': dict(data.get('fields') or {}),
+            'cells': dict(data.get('cells') or {})}
+def _write(table_key, change, st=None, flush='async'):
+    """Read-modify-write one shared stratum.
+    `flush='async'` by default for the same reason `table_store._update` uses it: a typed cell
+    lands here inside the request round-trip, and the historical synchronous hub commit cost
+    seconds per keystroke. Structural writes (a field definition) pass `flush='sync'` — they are
+    rare, and a lost column definition is a worse failure than a lost keystroke.
+    """
+    def _up(data):
+        data = data if isinstance(data, dict) else {}
+        data.setdefault('fields', {})
+        data.setdefault('cells', {})
+        change(data)
+        return data
+    return _st(st).update(bucket(table_key), _up, flush=flush)
+def _pid(pid):
+    """Pids are ints everywhere in the grid and strings in JSON. ONE coercion, here, so a caller
+    passing either cannot write a row that a reader keyed the other way never finds."""
+    return str(int(pid))
+def _value(value):
+    """A cell holds a SCALAR. The Row contract is scalar on every surface — the grid, the filter
+    engine, formulas, export — and the `json` kind is a validated STRING rather than an object.
+    ⛔ A dict or a list RAISES rather than being dropped. This is called by our own code, so a
+    non-scalar is a programming error, and silently storing nothing would surface later as "the
+    shared column is blank for everyone" with no failure anywhere near the cause.
+    """
+    if isinstance(value, (dict, list, tuple, set)):
+        raise ValueError(f'shared_overlay: a cell holds a scalar, not {type(value).__name__}')
+    if value is None or isinstance(value, bool) or isinstance(value, (int, float)):
+        return value
+    text = str(value)
+    return text[:MAX_VALUE_CHARS]
+# ----------------------------------------------------------------- the column DEFINITIONS
+def fields(table_key, st=None):
+    """`{field_key: Field}` — the columns this topic shares tenant-wide.
+    Unscoped on purpose, and it is the one thing here that is: a shared column's EXISTENCE is
+    tenant-wide by definition — that is the whole feature, and it is what stops a shared view
+    naming a column half the workspace lacks. Its VALUES are scoped by `cells()`.
+    """
+    return _read(table_key, st)['fields']
+def is_shared(table_key, field_key, st=None):
+    """Is this column's value tenant-wide? The predicate a caller uses to decide WHICH stratum to
+    read and write — one evaluator, so the read path and the write path cannot disagree about
+    where a given column lives ([[one-evaluator-per-question]])."""
+    return str(field_key or '') in _read(table_key, st)['fields']
+def _clean_route(bag):
+    """The `route` fingerprint bag, reduced to what a column definition may carry.
+    ⭐ THIS IS THE WIDENING THE BYPASS EXISTED TO BUY. `routes_customers` writes
+    `{inputsHash, roundTrip, startPid, stops, depot, solvedAt}` onto the DEFINITION rather than the
+    rows, because one `planRoute` run fingerprints the whole cohort identically and `_value` raises
+    on a dict anyway. Everything here is a scalar except `depot`, which is one flat level
+    (`{address, lat, lon}` or None), so the shape is bounded without being guessed at.
+    Returns None for anything that is not a dict, so a caller cannot store a `route` marker that
+    carries nothing.
+    """
+    if not isinstance(bag, dict):
+        return None
+    def _scalar(value):
+        if value is None or isinstance(value, bool) or isinstance(value, (int, float)):
+            return value
+        return str(value)[:MAX_ROUTE_CHARS]
+    out = {}
+    for name, value in bag.items():
+        name = str(name)[:40]
+        if not name:
+            continue
+        if name == 'depot':
+            out['depot'] = ({str(k)[:40]: _scalar(v) for k, v in value.items()
+                             if not isinstance(v, (dict, list, tuple, set))}
+                            if isinstance(value, dict) else None)
+            continue
+        if isinstance(value, (dict, list, tuple, set)):
+            continue
+        out[name] = _scalar(value)
+    return out or None
+def put_field(table_key, field_key, defn, st=None):
+    """Declare (or redefine) a shared column, THROUGH THE ALLOWLIST. Returns what was stored.
+    ⭐⭐ W41-T04 / CONTRACT C3. This is the one function that writes a tenant-wide column
+    definition, and since this ticket it is a DOOR rather than a passthrough: see
+    `ALLOWED_FIELD_KEYS` for what it carries, why `route` is on the list, and why a MINT is strict
+    while a REDEFINE carries a stored stranger through.
+    ⚠ IT DOES NOT REQUIRE THE GOVERNANCE TRIPLE, AND THAT IS STATED HERE RATHER THAN LEFT TO BE
+    DISCOVERED. `mint_field` below is the entrance that requires `createdBy`, a grant list and a
+    description; this one cannot, because sixteen of the seventeen writers in the tree predate the
+    requirement and a raise here would refuse definitions that three ROSTER gates
+    (`platform_perm_scope`, `web_optimism`, `api_scopes`) mint in their fixtures today. Making the
+    triple a runtime refusal on this function is a real change and it needs those call sites moved
+    first; `verify_field_doors.py` reports the gap by name so it stays visible.
+    """
+    key = str(field_key or '').strip()
+    if not key:
+        raise ValueError('shared_overlay: a field needs a key')
+    incoming = dict(defn or {})
+    kept = {name: value for name, value in incoming.items() if name in ALLOWED_FIELD_KEYS}
+    route = _clean_route(incoming.get('route'))
+    if route:
+        kept['route'] = route
+    else:
+        kept.pop('route', None)
+    kept['key'] = key
+    # ⚠ SEEDED WITH THE ALLOWLISTED PAYLOAD, not left empty. `_write` only runs `_add` if the
+    # store actually invokes its callback, and the old body returned its `entry` either way.
+    # `grid_events.field_upsert` assigns this return straight back over `field` and then reads
+    # `createdBy` off it to claim the grant, so an empty answer on an unavailable store would
+    # hand ownership of the column to whoever happened to be saving.
+    stored = dict(kept)
+    def _add(data):
+        prior = data['fields'].get(key)
+        # ⚠ ONLY THE STRANGERS ARE CARRIED. A key this allowlist DOES know follows the caller's
+        # payload exactly, so clearing a formula or a note by omission keeps working the way it
+        # did before this door existed; a key it does not know is one the store already held and
+        # nothing here is entitled to delete.
+        entry = ({name: value for name, value in prior.items()
+                  if name not in ALLOWED_FIELD_KEYS} if isinstance(prior, dict) else {})
+        entry.update(kept)
+        entry['key'] = key
+        data['fields'][key] = entry
+        stored.clear()
+        stored.update(entry)
+    _write(table_key, _add, st, flush='sync')
+    return dict(stored)
+def mint_field(table_key, field_key, defn=None, *, created_by, grants, description,
+               grant_topic, st=None):
+    """⭐⭐ THE ONE COLUMN-CREATION DOOR (contract C3). Mint a governed tenant-wide column.
+    It requires the three things a column read by the whole tenant cannot be born without, and it
+    REFUSES BY NAME rather than storing a definition that is missing one:
+      `created_by`   who owns it. `shares.may_administer` fails closed on an ownerless record, so
+                     a governed column with no creator can never be shared by anybody, ever.
+      `grants`       the grant list, and an EMPTY LIST IS A VALID ANSWER: `set_grants` keeps a
+                     record with an owner and no entries, so "shared with nobody" is stored and is
+                     a different fact from "never shared". `None` is the refusal, not `[]`.
+      `description`  what the column means, for the people who did not make it.
+    ⛔ IT REFUSES TO OVERWRITE. A mint that finds the key already there is not a mint, and
+    answering 200 on one would let a second door quietly redefine a column somebody else owns.
+    Redefining is `put_field`.
+    ⭐ THE DEFINITION LANDS BEFORE THE CLAIM, AND THE ORDER IS THE SAFE ONE. If `set_grants`
+    fails, the column is already marked governed and nobody holds a grant, so only an admin sees
+    it: recoverable. The other order leaves a grant on a column that does not exist.
+    """
+    key = str(field_key or '').strip()
+    if not key:
+        raise ValueError('shared_overlay.mint_field: a field needs a key')
+    missing = []
+    if not str(created_by or '').strip():
+        missing.append('createdBy')
+    if grants is None or not isinstance(grants, (list, tuple)):
+        missing.append('grants')
+    if not str(description or '').strip():
+        missing.append('description')
+    if missing:
+        raise ValueError(
+            'shared_overlay.mint_field refuses to create the column ' + key + ': '
+            + ', '.join(missing) + ' is required. A tenant-wide column is read by people who did '
+            'not make it, so it is born with an owner, a grant list (an empty one means shared '
+            'with nobody, which is a stored fact) and a description.')
+    if is_shared(table_key, key, st=st):
+        raise ValueError(
+            'shared_overlay.mint_field refuses to create the column ' + key + ': this database '
+            'already has one under that key. Changing a column that exists is put_field.')
+    entry = dict(defn or {})
+    entry['key'] = key
+    entry['createdBy'] = str(created_by).strip()
+    entry['note'] = str(description).strip()
+    entry['shared'] = True
+    entry['granted'] = True
+    stored = put_field(table_key, key, entry, st=st)
+    try:
+        import core.shares as shares
+        shares.set_grants('field', shares.field_oid(str(grant_topic or table_key), key),
+                          list(grants), owner=entry['createdBy'], st=st)
+    except Exception:                                       # noqa: BLE001
+        # Fails CLOSED: the column is marked governed and nobody holds a grant, so it is
+        # admin-and-creator only until somebody shares it. Recoverable; the other order is not.
+        pass
+    return stored
+def drop_field(table_key, field_key, st=None):
+    """Remove a shared column AND every stored value for it.
+    ⛔ The cells go with the definition, exactly as `table_store.delete_field` scrubs its own:
+    orphaned values would silently resurface if the key were ever reused — and a resurrected
+    value in a TENANT-WIDE stratum reappears for everybody at once.
+    """
+    key = str(field_key or '').strip()
+    if not key:
+        return False
+    hit = [False]
+    def _drop(data):
+        hit[0] = data['fields'].pop(key, None) is not None
+        for row in data['cells'].values():
+            if isinstance(row, dict):
+                row.pop(key, None)
+        # ⚠ AND DROP THE ROWS THAT ARE NOW EMPTY. `cells()` already skips a blank row, so this
+        # changes nothing a reader sees — but this bucket is read by every user in the tenant,
+        # and a `{}` per pid that once held a since-deleted column is dead weight that only ever
+        # grows. Caught by `prune()` reporting rows nobody could see as dropped.
+        for pid in [p for p, row in data['cells'].items() if not row]:
+            data['cells'].pop(pid, None)
+    _write(table_key, _drop, st, flush='sync')
+    return hit[0]
+# ----------------------------------------------------------------------------- the VALUES
+def cells(table_key, pids, st=None):
+    """`{"<pid>": {field_key: value}}` for the rows named by `pids` — and ONLY those.
+    ⛔ `pids` IS REQUIRED. See the module header: this is the row wall expressed as a signature,
+    so a caller cannot get "every shared cell in the tenant" by forgetting an argument. Pass the
+    pool you have already scoped for this session.
+    An empty `pids` legitimately returns `{}` — a reader with no rows sees no cells, which is the
+    correct answer rather than a special case.
+    """
+    if pids is None:
+        raise TypeError('shared_overlay.cells: pids is required — pass the row set you have '
+                        'already scoped for this reader (there is deliberately no "all" call)')
+    wanted = {_pid(p) for p in pids}
+    if not wanted:
+        return {}
+    stored = _read(table_key, st)['cells']
+    return {pid: dict(row) for pid, row in stored.items()
+            if pid in wanted and isinstance(row, dict) and row}
+def snapshot(table_key, pids, st=None):
+    """`(fields, cells)` for `pids` — the shared stratum's SCHEMA and VALUES, from ONE read.
+    ⛔⛔ THIS EXISTS BECAUSE TWO READS OF THIS BUCKET CAN DISAGREE, AND THE DISAGREEMENT OPENS A
+    WALL. `perm_scope._enrich_for_wall` needs both halves: the schema decides WHICH user columns
+    the row wall may answer, and the cells are the values it answers with. Taking them as two
+    `st.get()` calls leaves a gap in which a concurrent write can land, and a wave-40 adversarial
+    probe drove exactly that: with the second read returning an emptied `cells`, a blank is merged
+    for a key the store cannot really serve and `custom_x is not West` flips from denying every row
+    to ADMITTING a row whose true value IS West. `is empty` does the same. The set and the values
+    must come from one snapshot or they are not talking about the same tenant state.
+    ⚠ `pids` IS REQUIRED, exactly as in `cells()` — the row wall expressed as a signature, so no
+    caller can get "every shared cell in the tenant" by forgetting an argument.
+    """
+    if pids is None:
+        raise TypeError('shared_overlay.snapshot: pids is required — pass the row set you have '
+                        'already scoped for this reader (there is deliberately no "all" call)')
+    stored = _read(table_key, st)
+    wanted = {_pid(p) for p in pids}
+    served = {pid: dict(row) for pid, row in stored['cells'].items()
+              if pid in wanted and isinstance(row, dict) and row} if wanted else {}
+    return dict(stored['fields']), served
+def put_cell(table_key, pid, field_key, value, st=None):
+    """Write ONE shared cell. Returns the value as stored (which may be truncated)."""
+    return put_cells(table_key, pid, {field_key: value}, st=st).get(str(field_key or ''))
+def put_cells(table_key, pid, values, st=None):
+    """Write several shared cells on one row, in one store update. Returns what was stored."""
+    row_id = _pid(pid)
+    clean = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
+    if not clean:
+        return {}
+    def _patch(data):
+        data['cells'].setdefault(row_id, {}).update(clean)
+    _write(table_key, _patch, st)
+    return clean
+def put_rows(table_key, rows, st=None):
+    """Write shared cells on MANY rows in ONE store update. Returns `{row_id: {key: value}}`.
+    ⭐⭐ THE WHOLE POINT IS THE *ONE*, AND IT IS NOT AN OPTIMISATION. `put_cells` is one row per
+    store write, so a 1,397-row catalog import is 1,397 download-modify-upload cycles against one
+    JSON document. This repo has a MEASURED scar for that shape: **18 writes against one document
+    under the store's coalescing single-flight landed ZERO while answering 200 eighteen times.**
+    Batching is what makes a bulk import land at all, not what makes it fast.
+    ⚠ It deliberately takes the WHOLE SET rather than accepting a stream: a caller that loops over
+    this function has simply rebuilt `put_cells` with extra steps, and the failure it reintroduces
+    is silent. If the set does not fit in memory it does not fit in this store either — that is a
+    signal to change substrate, not to chunk.
+    ⛔ NO CAP HERE, ON PURPOSE. The bound belongs at the DOOR, where a caller identity and a
+    reportable refusal exist (`routes_grid.bulk_cells`). A silent ceiling in a store primitive is
+    exactly the shape the standing no-cap rule forbids.
+    """
+    clean = {}
+    for pid, values in dict(rows or {}).items():
+        row_id = _pid(pid)
+        cells_for_row = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
+        if cells_for_row:
+            clean.setdefault(row_id, {}).update(cells_for_row)
+    if not clean:
+        return {}
+    def _patch(data):
+        for row_id, values in clean.items():
+            data['cells'].setdefault(row_id, {}).update(values)
+    # `flush='sync'` because a bulk import must be durable when the call returns: the caller is a
+    # script that will report "1,397 rows written" and exit, and an async flush would make that
+    # sentence a prediction rather than a fact.
+    _write(table_key, _patch, st, flush='sync')
+    return clean
+def clear_row(table_key, pid, st=None):
+    """Forget every shared cell on one row. True when there was something to forget."""
+    row_id = _pid(pid)
+    hit = [False]
+    def _clear(data):
+        hit[0] = data['cells'].pop(row_id, None) is not None
+    _write(table_key, _clear, st)
+    return hit[0]
+def prune(table_key, live_pids, st=None):
+    """Drop shared cells for rows that no longer exist. Returns how many rows were dropped.
+    ⛔ NOT a scoped read wearing another name, and the difference is the whole reason `cells()`
+    refuses to serve everything: `live_pids` here means *every row this TABLE has*, which is a
+    fact about the data, whereas `pids` in `cells()` means *every row this READER may see*, which
+    is a fact about the session. Calling this with one session's pool would delete the shared
+    values of every row that session cannot see. The name says which is which; so does this note.
+    """
+    keep = {_pid(p) for p in live_pids}
+    dropped = [0]
+    def _prune(data):
+        gone = [pid for pid in data['cells'] if pid not in keep]
+        for pid in gone:
+            data['cells'].pop(pid, None)
+        dropped[0] = len(gone)
+    _write(table_key, _prune, st, flush='sync')
+    return dropped[0]

platform/core/shares.py CHANGED Viewed

@@ -1,560 +1,584 @@
-"""core/shares.py — ONE grant registry for every shareable object (wave 20, owner ruling R10).
-WHAT R10 ASKED FOR: folders and databases share with the **same two-role vocabulary views
-already use** (specific users or everyone; role = view | edit), plus one manage-access editor
-that can add or revoke people later, on any of the three.
-WHY A REGISTRY RATHER THAN A FIELD ON EACH OBJECT. A view already carries its own `permissions`
-(`core/table_store.py`) and that stays — moving it would rewrite every stored view for no gain.
-But a FOLDER is a value inside one user's workspace blob and a DATABASE is a `user_tables`
-definition; giving each its own grant field would put the same three-line permission decision in
-three files owned by two sessions, which is how the three drift. One registry, one predicate,
-three callers.
-    shares.set_grants(kind, oid, entries, owner=…, granter=…, st=…)   # replaces the whole set
-    shares.grants(kind, oid, st=…)                         # -> {'owner': str, 'entries': [...]}
-    shares.role_for(kind, oid, user, is_admin=…, st=…)     # -> 'owner'|'edit'|'view'|None
-    shares.max_grantable_role(kind, oid, user, …)          # -> 'edit'|'view'|None (R4's ceiling)
-    shares.shared_with(user, kind=…, st=…)                 # -> [oid] this user was granted
-THE ROLE VOCABULARY IS TWO WORDS AND THE DEFAULT IS THE NARROW ONE. `view` = may open and read;
-`edit` = may also change the object's CONTENT.
-⭐⭐ AND ON A VIEW, `edit` NOW ALSO MEANS "MAY RE-SHARE" — OWNER RULING R4, instruction 4 (*"Edit
-View so a member can share a View as well, not just an admin"*), built as W40-T02. This REVERSES
-the flat owner-or-admin rule this paragraph used to state, and it reverses it for ONE kind:
-`RESHARE_KINDS` below is where the widening is spelled, once, and `folder` / `database` / `field`
-are untouched — still the owner's or an admin's, for the reason given at that constant.
-⛔ WHICH HALF OF THE OLD PROTECTION SURVIVES, BECAUSE THE FEAR IT NAMED WAS REAL AND ONLY HALF OF
-IT IS ANSWERED. The sentence here used to be *"a collaborator who could rewrite grants could grant
-themselves sole ownership of somebody else's object, or quietly widen a users-scoped share to
-everyone"*. Taking those one at a time:
-  * **SOLE OWNERSHIP IS BLOCKED — and now stated rather than incidental.** The owner is STICKY in
-    `set_grants` and `routes_shares.put_share` passes the EXISTING owner straight back through, so
-    a re-share cannot transfer ownership and no grantee can lock the creator out of their own view.
-    Ownership moves for nobody, by any path this registry offers.
-  * **WIDENING IS NOW BLOCKED TOO — OWNER RULING 2026-08-24, D-473.** ⛔ THE SENTENCE HERE USED
-    TO PRICE THIS AS A COST R4 ACCEPTED: *"an `edit` grantee may add somebody — `*` included — at
-    `view`"*. Measured and reported as such, and the owner's answer was *"no a re-sharer can only
-    share to specific people"*. So a re-sharer may name PEOPLE and may not reach `EVERYONE`, and
-    the second half of the old fear is closed rather than merely capped. The ROLE ceiling below
-    still stands beside it — they are two different questions and both are asked.
-  * **THE ROLE CEILING SURVIVES UNCHANGED.** A re-share may never exceed the role the re-sharer
-    holds, and the STRICTER reading of that ships: an `edit` grantee may add somebody at `view`,
-    and can never mint `edit` access for anyone. Handing out `edit` stays the owner's (or an
-    admin's) alone. A `view` grantee still cannot share at all. `max_grantable_role` is that
-    ceiling, and `routes_shares.put_share` is where it bites.
-  * **AND REVOCATION IS BOUNDED BY PROVENANCE — OWNER RULING 2026-08-24, D-474.** *"a re-sharer
-    can only unshare the people it shared to"*. R4 bounded the role a re-sharer may HAND OUT and
-    said nothing about what they may TAKE AWAY, so an `edit` grantee could `PUT []` and leave the
-    view shared with nobody. Answering that needs a fact the record did not carry, which is what
-    the `by` member on each entry is (`_clean_entries` / `set_grants`' `granter`). ⛔ An entry
-    with NO `by` — every grant written before this change — is the OWNER's to revoke and nobody
-    else's: a re-sharer must never revoke a grant they cannot prove they made.
-⛔ AN UNREADABLE GRANT IS NO GRANT. Every path here fails closed — junk in the bucket, a missing
-owner, an unknown role string all resolve to None rather than to a default that opens something.
-[[aios-permissioning]]: no fail-open defaults, ever.
-⚠ THE BUCKET IS TENANT-SCOPED THROUGH `st`, like every other product-data write. Passing the
-session's `TenantRuntime` is what keeps Nurilab's grants in Nurilab's store; the module default
-(`core.store`) is tenant #0 and exists for the same reason it does everywhere else — the ~28
-callers that predate multi-tenancy. (This is the D-5/D-16 residency shape, and this module does
-NOT repeat their mistake: `st` is threaded from the first line rather than retrofitted.)
-"""
-import core.store as store
-#: The store key. One bucket per tenant holds every kind's grants, because "what am I shared on"
-#: is a question across kinds — the "Shared with me" folder (R10) is exactly that query, and
-#: three separate buckets would make it three reads that can disagree about what a user can see.
-SHARES_KEY = 'object_shares'
-#: The shareable kinds. A CLOSED vocabulary: an unknown kind raises rather than creating a new
-#: namespace by typo, which would silently grant nothing to nobody and read as "sharing is broken".
-#:
-#: ⭐⭐ W38-T16 — `field` IS THE FOURTH, AND NOTHING IN THIS FILE BRANCHES ON IT. Every function
-#: below treats `kind` as an opaque bucket key (`_check_kind / grants / set_grants / role_for /
-#: may_see / may_edit / may_administer / shared_with / drop_objects`), so the kind's whole cost
-#: here is this tuple member. That is the point of one registry: the new object's WALL is written
-#: once in `core.perm_scope`, and its DOORS once in `routes_shares.py` — never a fourth
-#: permission decision in a fourth file ([[one-evaluator-per-question]]).
-KINDS = ('view', 'folder', 'database', 'field')
-#: `*` is "everyone who can already open the surface". It is NOT "every account on the platform".
-#: Spelled as a single character so it can never collide with a username (usernames are lower-case
-#: and non-empty by `core/users.py`, and are checked against this explicitly below).
-#:
-#: ⛔⛔ **AND WHAT THAT MEANS DEPENDS ON THE KIND — THE LINE THIS NOTE USED TO CARRY WAS FALSE FOR
-#: ONE OF THE THREE** (W33-T30, `waves/wave32/sharing-audit.md` S-8). It read *"the module/table
-#: wall runs FIRST and this never widens past it"*, flatly, and the audit's own words for that are
-#: *"the third docstring in this audit describing a check that is not on the path"*. Corrected
-#: here rather than deleted, because the sentence is TRUE of two kinds and the difference is the
-#: whole point:
-#:   * `kind='view'` / `kind='folder'` on a GOVERNED module (`customer_data`, `product_data`) —
-#:     the sentence holds. `require_session` plus the topic's own gate run first, and the
-#:     receiver's row scope and hidden-field closure are applied BEFORE any foreign view is
-#:     merged, so a grant can only narrow-or-equal what that account could already reach.
-#:   * `kind='database'` on a `ut_*` table — ⭐⭐ **THE SENTENCE HOLDS HERE TOO NOW, AND THAT IS
-#:     W36-T21 / OWNER RULING R6 (audit S-8, CLOSED).** It did not until wave 36, and the reason
-#:     is worth keeping: `routes_admin._clean_perms` 400'd any key outside
-#:     `("customer_data", "product_data")`, so no row filter and no hidden field could even be
-#:     DECLARED for a user table, `routes_tables.py` made zero `perm_scope` calls, and it passed
-#:     `hidden_keys=frozenset()`. A `database` grant was therefore ALL-OR-NOTHING — every row,
-#:     every column — and this registry was the only wall behind it.
-#:
-#: ⭐ WHAT CHANGED: `perm_scope.scoped_table` (contract C1) is the ONE door to any database's
-#: rows. `routes_tables` applies the permanent filter before `pids` is taken and the transitive
-#: hidden-field closure after `workspace_wire`, on EVERY `ut_*` read — the same code that walls
-#: `customer_data` — and a door that cannot apply them REFUSES rather than serving the lot. So a
-#: `database` grant is once again bounded by a second wall: it decides WHETHER an account reaches
-#: the database, and C1 decides WHICH rows and columns it then sees. An `*` grant still admits
-#: every account in the tenant, and each of them still only sees what their own wall allows.
-#:
-#: ⚠ `routes_shares.py`'s module docstring carries the OLD sentence at the other door and is in
-#: no wave-36 fence — the audit's own fix was "say so at both", so one of the two is now stale.
-#: Booked in `mailbox/C.md` (C-14) rather than edited across a fence
-#: [[two-gates-can-assert-opposite-things]].
-EVERYONE = '*'
-ROLES = ('view', 'edit')
-#: ⭐⭐ THE KINDS AN `edit` GRANTEE MAY RE-SHARE — R4 / W40-T02, and it is `view` ALONE.
-#:
-#: R4's words are "may re-share **A VIEW**", and the widening goes no further than the ruling
-#: names. That restraint is the whole reason this is a tuple rather than a bare `role == 'edit'`
-#: arm inside `may_administer`: every predicate in this file treats `kind` as an opaque bucket key
-#: (see the note on `KINDS`), so an UNGATED widening would reach `folder`, `database` and `field`
-#: in the same line — handing an `edit` grantee on a `ut_*` DATABASE the power to re-share the
-#: whole table. The asymmetry is one of blast radius: a view is one saved SELECTION, opened through
-#: the receiver's own module wall and row scope; a database grant admits an account to a database.
-#: `routes_shares.py`'s module docstring carries that argument at the door where it is enforced.
-#:
-#: ⚠ ONE SPELLING, DELIBERATELY. `may_administer` and `max_grantable_role` both consult this, so
-#: "who may open the editor" and "what may they hand out" cannot come apart about the same kind.
-RESHARE_KINDS = ('view',)
-class GrantsChanged(Exception):
-    """A grant write was decided against a record that is no longer the stored one.
-    Raised by `set_grants` when its `expect` does not match what is in the store at write time.
-    The door turns it into a 409 rather than a 500: it is not an error in the request, it is two
-    people editing the same sharing list at once, and the honest answer is to say so.
-    """
-#: ⛔⛔ A FIELD's OBJECT ID IS TOPIC-QUALIFIED, AND THE SEPARATOR IS DECLARED HERE SO THERE IS ONE
-#: SPELLING OF IT. A bare field key is NOT unique: `notes` exists on a dozen databases, and a
-#: grant stored under it would admit a grantee to every `notes` column in the tenant at once —
-#: the widening direction, silently, forever. `table_key` is the qualifier because it is the same
-#: identifier `shared_overlay.bucket()` already keys the values by, so the grant and the data it
-#: governs are named by the same string ([[one-question-two-normalizers]]).
-#:
-#: ⚠ A `ut_*` key and a registry topic key both match `[a-z0-9_]+` and neither can contain `:`,
-#: so the split below is unambiguous in both directions.
-FIELD_OID_SEP = ':'
-def field_oid(table_key, field_key):
-    """`"<table_key>:<field_key>"` — the share id of ONE column on ONE database."""
-    table = str(table_key or '').strip()
-    field = str(field_key or '').strip()
-    if not table or not field:
-        raise ValueError('shares.field_oid: a field share names BOTH a database and a column. '
-                         'A bare field key repeats across tables and would grant all of them')
-    return f'{table}{FIELD_OID_SEP}{field}'
-def split_field_oid(oid):
-    """`(table_key, field_key)` or `(None, None)` for anything that is not a field oid.
-    ⛔ FAIL-CLOSED ON JUNK, like every other read here: a caller that cannot learn WHICH database
-    an id names must not fall back to "the one I happen to be looking at", which is how a grant
-    on somebody else's column would be read as a grant on this one.
-    """
-    raw = str(oid or '')
-    table, sep, field = raw.partition(FIELD_OID_SEP)
-    if not sep or not table.strip() or not field.strip() or FIELD_OID_SEP in field:
-        return (None, None)
-    return (table.strip(), field.strip())
-def _st(st):
-    return st if st is not None else store
-def _check_kind(kind):
-    k = str(kind or '').strip().lower()
-    if k not in KINDS:
-        raise ValueError(f'{kind!r} is not a shareable kind. Use one of {", ".join(KINDS)}. '
-                         f'This door refuses to invent a namespace from a typo.')
-    return k
-def _clean_entries(entries):
-    """Normalise + REJECT junk, returning [{'user': str, 'role': 'view'|'edit'}] — plus an
-    OPTIONAL `'by'`, present only when the record already carried one.
-    Silently dropping a malformed entry is right here and wrong elsewhere: the caller is a UI
-    that just listed the people it is about to grant, so a rejected row must not abort the whole
-    save — but an entry with an unknown ROLE must not be stored as something else's default
-    either. Dropped, never coerced.
-    ⭐⭐ D-474 — `by` IS PROVENANCE: THE USERNAME OF WHOEVER PLACED THIS GRANT. Owner ruling
-    2026-08-24: *"a re-sharer can only unshare the people it shared to"*. That question has no
-    answer in a record that stores only WHO HOLDS the grant, so the record grew a third member and
-    this normaliser is where it survives the round trip (`grants` reads every stored entry back
-    through here, so a member this function drops is a member the door can never consult).
-    ⛔⛔ AND THIS FUNCTION STAYS A PURE NORMALISER: IT NEVER INVENTS A `by`, AND IT NEVER
-    VALIDATES ONE. That is not tidiness, it is the whole security property. `set_grants` is handed
-    a caller-supplied list, so a `by` arriving HERE may be forged — and the merge inside
-    `set_grants._apply` therefore OVERWRITES it in both directions from the PRIOR record and the
-    `granter`, never from the payload. Were this function to treat a submitted `by` as
-    authoritative, a re-sharer could PUT `{user: victim, role: view, by: <themselves>}` to
-    re-stamp somebody else's grant as their own, then PUT again omitting the victim, and the wall
-    at the door would be decoration. Normalise the SHAPE here; decide the VALUE there.
-    ⚠ KEY ORDER IS `user, role, by` AND `by` IS ABSENT RATHER THAN `None` WHEN THERE IS NONE.
-    Absence is what keeps every pre-existing record byte-identical after this change (an added
-    `by: None` would rewrite the whole bucket on the next save, for nothing), and it is what
-    `aios-web/api/verify_field_permissions.py` reads when it compares `tuple(entry.values())`
-    against a 2-tuple.
-    """
-    out, seen = [], set()
-    for e in entries or ():
-        if not isinstance(e, dict):
-            continue
-        user = str(e.get('user') or '').strip().lower()
-        role = str(e.get('role') or '').strip().lower()
-        if not user or role not in ROLES or user in seen:
-            continue
-        seen.add(user)
-        row = {'user': user, 'role': role}
-        by = str(e.get('by') or '').strip().lower()
-        if by:
-            row['by'] = by
-        out.append(row)
-    return out
-def grants(kind, oid, st=None):
-    """`{'owner': str|None, 'entries': [{'user','role','by'?}]}` — never raises on a junk bucket.
-    ⭐⭐ D-474 — `by` RIDES THE READ, because the DOOR is what has to consult it. The revocation
-    wall lives in `routes_shares.put_share` (it needs the session, which this layer does not
-    have), and a wall cannot read a member this function strips. `_clean_entries` carries it,
-    so every reader here sees it and no reader has to reach into the raw bucket.
-    ⚠ THE COST, STATED RATHER THAN DISCOVERED: `GET /api/v1/share/{kind}/{oid}` returns this
-    record verbatim, so anyone who may read a grant list now also learns WHO ADDED each person,
-    a `view` grantee included. That is a mild widening of *"who has this?"* into *"who let them
-    in?"*. It is accepted deliberately: the alternative is a second, provenance-stripped read
-    path, which is a second answer to one question and is how the two come apart
-    ([[one-evaluator-per-question]]).
-    """
-    kind = _check_kind(kind)
-    try:
-        bucket = (_st(st).get(SHARES_KEY) or {}).get(kind) or {}
-        rec = bucket.get(str(oid)) or {}
-    except Exception:
-        return {'owner': None, 'entries': []}
-    if not isinstance(rec, dict):
-        return {'owner': None, 'entries': []}
-    return {'owner': (str(rec.get('owner')).strip().lower() if rec.get('owner') else None),
-            'entries': _clean_entries(rec.get('entries'))}
-def set_grants(kind, oid, entries, owner=None, st=None, granter=None, expect=None):
-    """REPLACE the grant set for one object. Returns the stored record.
-    ⚠ REPLACE, NOT MERGE, and that is the contract the UI needs: revoking is expressed by an
-    entry's ABSENCE. A merge-only API cannot remove anybody without a second verb, and the
-    manage-access editor R10 asks for is exactly "here is the list now".
-    ⭐⭐ D-474 — `granter` IS WHO IS DOING THIS SAVE, AND IT IS THE ONLY SOURCE OF A NEW `by`.
-    Owner ruling 2026-08-24: *"a re-sharer can only unshare the people it shared to"*. The wall
-    is at the door (`routes_shares.put_share`), but the FACT it consults can only be recorded
-    here, at the write.
-    ⛔⛔ AND THE STAMP IS DECIDED INSIDE `_apply`, NOT ABOVE IT, BECAUSE `_apply` IS THE ONLY
-    PLACE THE PRIOR RECORD IS VISIBLE. Two rules, and the first is the one that matters:
-      * a user ALREADY in the prior record keeps their stored `by` VERBATIM. Never re-stamped —
-        a re-save would otherwise transfer provenance to whoever saved last, so every re-sharer
-        would silently inherit the right to revoke everybody the owner had ever added, simply by
-        pressing Save. That is the ruling inverted, arriving by accident.
-      * a user who is NEW to the record takes `by = granter`, or carries NO `by` at all when no
-        granter was named.
-    ⛔ IN BOTH ARMS THE VALUE IS OVERWRITTEN FROM (prior, granter) AND NEVER READ OFF THE
-    SUBMITTED ENTRY. `_clean_entries` preserves a submitted `by` because a STORED one has to
-    survive the read; a caller-supplied one is untrusted input. Filling in only a MISSING `by`
-    would leave the two-step forgery open: PUT `{user: victim, by: <me>}` to claim provenance,
-    then PUT again omitting the victim.
-    ⭐ `granter` DEFAULTS TO `None`, AND THAT IS WHAT MAKES THIS SHAPE CHANGE SAFE. Every
-    non-door caller — `core.field_permissions` (promote + reconcile), `modules.product_data`'s
-    Image field, `core.grid_events`' cleanup on delete, the gates — replaces a whole grant set
-    with no caller identity in hand, and each keeps producing EXACTLY the record it produced
-    before this change: no `by`, no new bytes, no behaviour moved. A grant with no `by` is one
-    nobody can prove they made, and the door treats it as the owner's alone to revoke
-    (fail-closed). ⚠ A future edit that defaults this to a session, or stamps it from the entry,
-    deletes that property without touching a line the compiler can complain about.
-    ⚠ `_apply` MAY RUN MORE THAN ONCE. `store._update_locked` re-applies the mutation on a
-    `parent_commit` rebase, so the merge builds FRESH dicts from `clean` on every invocation
-    rather than mutating it in place; a second pass must see the same untouched input, and it
-    must be free to reclassify a user who was "new" on the first pass and is "prior" on the
-    second (exactly what a rebase against another writer's save looks like).
-    """
-    kind = _check_kind(kind)
-    oid = str(oid)
-    clean = _clean_entries(entries)
-    owner_l = str(owner).strip().lower() if owner else None
-    granter_l = str(granter).strip().lower() if granter else None
-    def _apply(data):
-        by_kind = dict(data.get(kind) or {})
-        # ⛔⛔ COMPARE-AND-SET, AND IT IS A SECURITY BOUNDARY RATHER THAN A TIDINESS ONE.
-        # `routes_shares.put_share` reads the record ONCE, decides against it (may this caller
-        # remove that person, raise that role, add that audience), and only then calls this. The
-        # store re-reads `prior` fresh in here, so between the decision and the write another
-        # save can land and the decision is being applied to a record it never saw.
-        #
-        # Measured by a wave-40 adversarial probe, and it needs no attacker timing: the owner and
-        # a re-sharer both have Manage Access open and both press Save. The re-sharer's PUT was
-        # ACCEPTED with 200 and the grant the owner had just added was gone, with no error on
-        # either screen. That is D-474's wall failing open in the one window where two people are
-        # actually editing the same thing.
-        #
-        # ⚠ THE LOST UPDATE PREDATES THE WALL -- REPLACE semantics plus read-modify-write have
-        # always meant last-write-wins here. What is new is that a PERMISSION decision now rests
-        # on that read. So the caller states what it decided against, and a write that would land
-        # on anything else is refused rather than merged.
-        #
-        # `expect=None` keeps every existing caller byte-identical: the server-derived callers
-        # (`field_permissions`, `product_data`, the `[]` revokes) are not deciding anything about
-        # a person and have nothing to compare.
-        if expect is not None:
-            _now = [(e['user'], e['role']) for e in _clean_entries(
-                (by_kind.get(oid) or {}).get('entries') if isinstance(by_kind.get(oid), dict)
-                else [])]
-            if _now != [(e['user'], e['role']) for e in _clean_entries(expect)]:
-                raise GrantsChanged(
-                    'this item was shared with somebody else while you were editing, so nothing '
-                    'was saved. Reopen the sharing panel to see who has access now, then make '
-                    'your change again.')
-        prior = by_kind.get(oid) if isinstance(by_kind.get(oid), dict) else {}
-        # Read the prior entries through the SAME normaliser every other reader uses, so "was
-        # this user already here" cannot be answered one way by the store and another by the
-        # door ([[one-question-two-normalizers]]).
-        prior_by = {e['user']: e.get('by') for e in _clean_entries(prior.get('entries'))}
-        merged = []
-        for e in clean:
-            row = {'user': e['user'], 'role': e['role']}
-            stamp = prior_by[e['user']] if e['user'] in prior_by else granter_l
-            if stamp:
-                row['by'] = stamp
-            merged.append(row)
-        # The owner is STICKY: set once, and a later save that omits it must not orphan the
-        # object. An ownerless grant record cannot answer "who may re-share this", so every
-        # administer check would fail closed and the object would become unmanageable.
-        keep_owner = owner_l or (str(prior.get('owner')).strip().lower()
-                                 if prior.get('owner') else None)
-        if not merged and not keep_owner:
-            by_kind.pop(oid, None)          # fully un-shared and unowned: leave no empty husk
-        else:
-            by_kind[oid] = {'owner': keep_owner, 'entries': merged}
-        data[kind] = by_kind
-        return data
-    _st(st).update(SHARES_KEY, _apply, flush='async')
-    return grants(kind, oid, st=st)
-def role_for(kind, oid, user, is_admin=False, st=None):
-    """`'owner'` | `'edit'` | `'view'` | `None` — the caller's effective role, fail-closed.
-    An ADMIN reads as `'owner'`: an admin who could not administer an object could not
-    administer the tenant either, which is `table_store._may_administer`'s existing rule and is
-    kept identical here so the two cannot disagree about the same view.
-    """
-    user = str(user or '').strip().lower()
-    if not user:
-        return None
-    rec = grants(kind, oid, st=st)
-    if is_admin or (rec['owner'] and rec['owner'] == user):
-        return 'owner'
-    best = None
-    for e in rec['entries']:
-        if e['user'] == user or e['user'] == EVERYONE:
-            # The STRONGER of the two wins when both a personal and an everyone grant exist:
-            # naming somebody explicitly is how you RAISE them above the room, so an
-            # everyone-view + alice-edit pair must leave alice editing.
-            if e['role'] == 'edit':
-                return 'edit'
-            best = best or 'view'
-    return best
-def may_see(kind, oid, user, is_admin=False, st=None):
-    return role_for(kind, oid, user, is_admin=is_admin, st=st) is not None
-def may_edit(kind, oid, user, is_admin=False, st=None):
-    return role_for(kind, oid, user, is_admin=is_admin, st=st) in ('owner', 'edit')
-def may_administer(kind, oid, user, is_admin=False, st=None):
-    """May this caller change WHO ELSE reaches the object, and revoke them?
-    ⭐⭐ R4 / W40-T02 — AN `edit` GRANTEE ANSWERS TRUE, ON A `RESHARE_KINDS` KIND. Owner
-    instruction 4: *"Edit View so a member can share a View as well, not just an admin"*. That
-    reverses this function's old owner-or-admin rule for exactly one kind; the module note says
-    which half of the protection survives and `RESHARE_KINDS` says why it stops at `view`.
-    ⛔ ADMINISTERING IS NOT GRANTING, AND THE SECOND QUESTION HAS ITS OWN PREDICATE. True here
-    means "may open the editor and rewrite the list"; it does NOT mean every role is theirs to
-    hand out. `max_grantable_role` is the ceiling, and R4's two halves are only both honoured if
-    a caller consults both ([[one-evaluator-per-question]]).
-    ⛔ THE GATE IS THE KIND, NOT THE ROLE ALONE. `role_for` is deliberately kind-agnostic, so
-    testing `== 'edit'` without `RESHARE_KINDS` would widen all four kinds in one line.
-    """
-    role = role_for(kind, oid, user, is_admin=is_admin, st=st)
-    if role == 'owner':
-        return True
-    return role == 'edit' and _check_kind(kind) in RESHARE_KINDS
-def max_grantable_role(kind, oid, user, is_admin=False, st=None):
-    """The STRONGEST role this caller may hand SOMEBODY ELSE on this object, fail-closed.
-    `'edit'` for the owner or an admin · `'view'` for an `edit` grantee on a `RESHARE_KINDS` kind
-    · `None` for anybody who may not administer the object at all.
-    ⭐⭐ WHY A SECOND PREDICATE RATHER THAN A FLAG ON `may_administer` (R4 / W40-T02). R4 grants an
-    `edit` holder the right to re-share and caps it in the same breath: *"a re-share may never
-    exceed the role the re-sharer holds"*. Those are two different questions, and a single boolean
-    answering both is exactly how the cap gets dropped by the next caller that only needs the door.
-    ⛔ THE NARROWER OF R4's TWO READINGS SHIPS, AND ON PURPOSE. "Never exceed the role you hold"
-    reads either as *may grant up to and including `edit`* (an edit holder confers edit) or as *may
-    confer strictly less than the owner can*. This returns `'view'` — the second — because it is the
-    FAIL-CLOSED direction. A wrong `'view'` costs the owner one click to raise somebody; a wrong
-    `'edit'` lets a chain of collaborators propagate edit access the owner never approved, with
-    nothing in the store recording who widened it. W40-T02's `done-when` pins the same reading.
-    ⚠ THIS CAPS WHAT A CALLER GRANTS, NOT WHAT THE STORED SET ALREADY HOLDS, and the difference is
-    load-bearing. `routes_shares.put_share` enforces it against the DELTA — a name arriving at
-    `edit`, or an existing `view` grantee raised to it — never against every row of a body, because
-    the PUT REPLACES and the client therefore re-sends the whole list, the re-sharer's own `edit`
-    row included. The evidence for that is at the call site, where the body is.
-    ⛔⛔ AND IT IS ONE OF THREE BOUNDS ON A RE-SHARE, NOT THE BOUND. Owner ruling 2026-08-24 added
-    two more, and both live at the door because both need the SESSION: `_audience_added` (D-473,
-    a re-sharer may name people and may not reach `EVERYONE`) and `_unremovable` (D-474, a
-    re-sharer may revoke only what their own `by` stamp says they granted). ⚠ A reader who takes
-    this function for the whole ceiling will widen the other two by leaving them alone — which is
-    exactly how R4 shipped with an audience hole and a revocation hole under a docstring that
-    read like a complete account of the limits.
-    """
-    role = role_for(kind, oid, user, is_admin=is_admin, st=st)
-    if role == 'owner':
-        return 'edit'
-    if role == 'edit' and _check_kind(kind) in RESHARE_KINDS:
-        return 'view'
-    return None
-def shared_with(user, kind=None, st=None):
-    """Every object id this user has been granted (excluding what they own).
-    This is the "Shared with me" query (R10). It EXCLUDES owned objects deliberately: a folder
-    you made is not something shared *with* you, and listing it there would make the system
-    folder a duplicate of the rail above it.
-    """
-    user = str(user or '').strip().lower()
-    if not user:
-        return {}
-    try:
-        data = _st(st).get(SHARES_KEY) or {}
-    except Exception:
-        return {}
-    out = {}
-    for k in ([_check_kind(kind)] if kind else KINDS):
-        hits = []
-        for oid, rec in (data.get(k) or {}).items():
-            if not isinstance(rec, dict):
-                continue
-            owner = str(rec.get('owner') or '').strip().lower()
-            if owner == user:
-                continue
-            for e in _clean_entries(rec.get('entries')):
-                if e['user'] in (user, EVERYONE):
-                    hits.append(str(oid))
-                    break
-        out[k] = sorted(hits)
-    return out if kind is None else {_check_kind(kind): out[_check_kind(kind)]}
-def granted_oids(kind, st=None):
-    """Every object id of one `kind` that carries AT LEAST ONE grant entry — in ONE bucket read.
-    ⭐ W40-T01 / OWNER INSTRUCTION 2 ("a shared View must show the shared icon in EVERY account,
-    not only the recipient's"). `shared_with` answers *what was granted TO me* and deliberately
-    EXCLUDES what the caller owns — so it structurally cannot answer the other question a share
-    mark asks: *does this object have grants at all*. That question has no viewer in it, which is
-    why this is a separate function rather than a flag bolted onto `shared_with`.
-    ⚠ ONE READ, NOT N — and that is the whole reason this exists rather than a loop at the caller.
-    The obvious spelling is `grants(kind, oid)` per view, and `grants` re-reads the WHOLE bucket
-    on every call; a busy rail carries dozens of views, so painting one icon would cost dozens of
-    full reads of the tenant's entire grant registry. This reads the bucket once and hands back a
-    set the caller tests in O(1).
-    ⛔ AN ENTRY IS WHAT COUNTS, NOT A RECORD. `set_grants` keeps an owner-only HUSK after a full
-    revoke — the owner is sticky, deliberately, see its own note — so testing for the record's
-    mere EXISTENCE would leave the mark lit forever after the last person was removed. That is
-    exactly the revoke case, so it is the difference between this being right and being decorative
-    noise. `_clean_entries` is the same normaliser every other read here uses, so a junk entry
-    cannot mark an object either.
-    ⛔ FAIL-CLOSED like the rest of this module: an unreadable bucket answers the EMPTY set — no
-    marks — never a default that claims something is shared. An unknown KIND still RAISES, exactly
-    as `grants` / `shared_with` / `drop_objects` do: that is a typo in a caller, not junk in the
-    store, and swallowing it into "nothing is shared" would hide a caller that never works.
-    """
-    kind = _check_kind(kind)
-    try:
-        by_kind = (_st(st).get(SHARES_KEY) or {}).get(kind) or {}
-        rows = list(by_kind.items())
-    except Exception:
-        return set()
-    return {str(oid) for oid, rec in rows
-            if isinstance(rec, dict) and _clean_entries(rec.get('entries'))}
-def drop_objects(pairs, st=None):
-    """Remove whole grant RECORDS, owner husk included — wave 21, item 6a (C3).
-    A deleted object's grants must die with it: `shared_with` would otherwise serve ghost ids
-    into every receiver's "Shared with me" forever, and the ghost would 404 on open. One
-    transaction for the whole sweep — a table delete drops its database grant plus a view
-    grant per view that lived in its bucket."""
-    want = {}
-    for kind, oid in pairs or ():
-        want.setdefault(_check_kind(kind), set()).add(str(oid))
-    if not want:
-        return
-    def _apply(data):
-        for kind, oids in want.items():
-            by_kind = data.get(kind)
-            if isinstance(by_kind, dict):
-                for oid in oids:
-                    by_kind.pop(oid, None)
-        return data
-    _st(st).update(SHARES_KEY, _apply, flush='async')

+"""core/shares.py — ONE grant registry for every shareable object (wave 20, owner ruling R10).
+WHAT R10 ASKED FOR: folders and databases share with the **same two-role vocabulary views
+already use** (specific users or everyone; role = view | edit), plus one manage-access editor
+that can add or revoke people later, on any of the three.
+WHY A REGISTRY RATHER THAN A FIELD ON EACH OBJECT. A view already carries its own `permissions`
+(`core/table_store.py`) and that stays — moving it would rewrite every stored view for no gain.
+But a FOLDER is a value inside one user's workspace blob and a DATABASE is a `user_tables`
+definition; giving each its own grant field would put the same three-line permission decision in
+three files owned by two sessions, which is how the three drift. One registry, one predicate,
+three callers.
+    shares.set_grants(kind, oid, entries, owner=…, granter=…, st=…)   # replaces the whole set
+                                                       # ⚠ a NAMED owner REASSIGNS (R6d) — see it
+    shares.grants(kind, oid, st=…)                         # -> {'owner': str, 'entries': [...]}
+    shares.role_for(kind, oid, user, is_admin=…, st=…)     # -> 'owner'|'edit'|'view'|None
+    shares.max_grantable_role(kind, oid, user, …)          # -> 'edit'|'view'|None (R4's ceiling)
+    shares.shared_with(user, kind=…, st=…)                 # -> [oid] this user was granted
+THE ROLE VOCABULARY IS TWO WORDS AND THE DEFAULT IS THE NARROW ONE. `view` = may open and read;
+`edit` = may also change the object's CONTENT.
+⭐⭐ AND ON A VIEW, `edit` NOW ALSO MEANS "MAY RE-SHARE" — OWNER RULING R4, instruction 4 (*"Edit
+View so a member can share a View as well, not just an admin"*), built as W40-T02. This REVERSES
+the flat owner-or-admin rule this paragraph used to state, and it reverses it for ONE kind:
+`RESHARE_KINDS` below is where the widening is spelled, once, and `folder` / `database` / `field`
+are untouched — still the owner's or an admin's, for the reason given at that constant.
+⛔ WHICH HALF OF THE OLD PROTECTION SURVIVES, BECAUSE THE FEAR IT NAMED WAS REAL AND ONLY HALF OF
+IT IS ANSWERED. The sentence here used to be *"a collaborator who could rewrite grants could grant
+themselves sole ownership of somebody else's object, or quietly widen a users-scoped share to
+everyone"*. Taking those one at a time:
+  * **SOLE OWNERSHIP IS BLOCKED — and now stated rather than incidental.** The owner is STICKY in
+    `set_grants` and `routes_shares.put_share` passes the EXISTING owner straight back through, so
+    a re-share cannot transfer ownership and no grantee can lock the creator out of their own view.
+    Ownership moves for nobody, by any path this registry offers.
+  * **WIDENING IS NOW BLOCKED TOO — OWNER RULING 2026-08-24, D-473.** ⛔ THE SENTENCE HERE USED
+    TO PRICE THIS AS A COST R4 ACCEPTED: *"an `edit` grantee may add somebody — `*` included — at
+    `view`"*. Measured and reported as such, and the owner's answer was *"no a re-sharer can only
+    share to specific people"*. So a re-sharer may name PEOPLE and may not reach `EVERYONE`, and
+    the second half of the old fear is closed rather than merely capped. The ROLE ceiling below
+    still stands beside it — they are two different questions and both are asked.
+  * **THE ROLE CEILING SURVIVES UNCHANGED.** A re-share may never exceed the role the re-sharer
+    holds, and the STRICTER reading of that ships: an `edit` grantee may add somebody at `view`,
+    and can never mint `edit` access for anyone. Handing out `edit` stays the owner's (or an
+    admin's) alone. A `view` grantee still cannot share at all. `max_grantable_role` is that
+    ceiling, and `routes_shares.put_share` is where it bites.
+  * **AND REVOCATION IS BOUNDED BY PROVENANCE — OWNER RULING 2026-08-24, D-474.** *"a re-sharer
+    can only unshare the people it shared to"*. R4 bounded the role a re-sharer may HAND OUT and
+    said nothing about what they may TAKE AWAY, so an `edit` grantee could `PUT []` and leave the
+    view shared with nobody. Answering that needs a fact the record did not carry, which is what
+    the `by` member on each entry is (`_clean_entries` / `set_grants`' `granter`). ⛔ An entry
+    with NO `by` — every grant written before this change — is the OWNER's to revoke and nobody
+    else's: a re-sharer must never revoke a grant they cannot prove they made.
+⛔ AN UNREADABLE GRANT IS NO GRANT. Every path here fails closed — junk in the bucket, a missing
+owner, an unknown role string all resolve to None rather than to a default that opens something.
+[[aios-permissioning]]: no fail-open defaults, ever.
+⚠ THE BUCKET IS TENANT-SCOPED THROUGH `st`, like every other product-data write. Passing the
+session's `TenantRuntime` is what keeps Nurilab's grants in Nurilab's store; the module default
+(`core.store`) is tenant #0 and exists for the same reason it does everywhere else — the ~28
+callers that predate multi-tenancy. (This is the D-5/D-16 residency shape, and this module does
+NOT repeat their mistake: `st` is threaded from the first line rather than retrofitted.)
+"""
+import core.store as store
+#: The store key. One bucket per tenant holds every kind's grants, because "what am I shared on"
+#: is a question across kinds — the "Shared with me" folder (R10) is exactly that query, and
+#: three separate buckets would make it three reads that can disagree about what a user can see.
+SHARES_KEY = 'object_shares'
+#: The shareable kinds. A CLOSED vocabulary: an unknown kind raises rather than creating a new
+#: namespace by typo, which would silently grant nothing to nobody and read as "sharing is broken".
+#:
+#: ⭐⭐ W38-T16 — `field` IS THE FOURTH, AND NOTHING IN THIS FILE BRANCHES ON IT. Every function
+#: below treats `kind` as an opaque bucket key (`_check_kind / grants / set_grants / role_for /
+#: may_see / may_edit / may_administer / shared_with / drop_objects`), so the kind's whole cost
+#: here is this tuple member. That is the point of one registry: the new object's WALL is written
+#: once in `core.perm_scope`, and its DOORS once in `routes_shares.py` — never a fourth
+#: permission decision in a fourth file ([[one-evaluator-per-question]]).
+KINDS = ('view', 'folder', 'database', 'field')
+#: `*` is "everyone who can already open the surface". It is NOT "every account on the platform".
+#: Spelled as a single character so it can never collide with a username (usernames are lower-case
+#: and non-empty by `core/users.py`, and are checked against this explicitly below).
+#:
+#: ⛔⛔ **AND WHAT THAT MEANS DEPENDS ON THE KIND — THE LINE THIS NOTE USED TO CARRY WAS FALSE FOR
+#: ONE OF THE THREE** (W33-T30, `waves/wave32/sharing-audit.md` S-8). It read *"the module/table
+#: wall runs FIRST and this never widens past it"*, flatly, and the audit's own words for that are
+#: *"the third docstring in this audit describing a check that is not on the path"*. Corrected
+#: here rather than deleted, because the sentence is TRUE of two kinds and the difference is the
+#: whole point:
+#:   * `kind='view'` / `kind='folder'` on a GOVERNED module (`customer_data`, `product_data`) —
+#:     the sentence holds. `require_session` plus the topic's own gate run first, and the
+#:     receiver's row scope and hidden-field closure are applied BEFORE any foreign view is
+#:     merged, so a grant can only narrow-or-equal what that account could already reach.
+#:   * `kind='database'` on a `ut_*` table — ⭐⭐ **THE SENTENCE HOLDS HERE TOO NOW, AND THAT IS
+#:     W36-T21 / OWNER RULING R6 (audit S-8, CLOSED).** It did not until wave 36, and the reason
+#:     is worth keeping: `routes_admin._clean_perms` 400'd any key outside
+#:     `("customer_data", "product_data")`, so no row filter and no hidden field could even be
+#:     DECLARED for a user table, `routes_tables.py` made zero `perm_scope` calls, and it passed
+#:     `hidden_keys=frozenset()`. A `database` grant was therefore ALL-OR-NOTHING — every row,
+#:     every column — and this registry was the only wall behind it.
+#:
+#: ⭐ WHAT CHANGED: `perm_scope.scoped_table` (contract C1) is the ONE door to any database's
+#: rows. `routes_tables` applies the permanent filter before `pids` is taken and the transitive
+#: hidden-field closure after `workspace_wire`, on EVERY `ut_*` read — the same code that walls
+#: `customer_data` — and a door that cannot apply them REFUSES rather than serving the lot. So a
+#: `database` grant is once again bounded by a second wall: it decides WHETHER an account reaches
+#: the database, and C1 decides WHICH rows and columns it then sees. An `*` grant still admits
+#: every account in the tenant, and each of them still only sees what their own wall allows.
+#:
+#: ⚠ `routes_shares.py`'s module docstring carries the OLD sentence at the other door and is in
+#: no wave-36 fence — the audit's own fix was "say so at both", so one of the two is now stale.
+#: Booked in `mailbox/C.md` (C-14) rather than edited across a fence
+#: [[two-gates-can-assert-opposite-things]].
+EVERYONE = '*'
+ROLES = ('view', 'edit')
+#: ⭐⭐ THE KINDS AN `edit` GRANTEE MAY RE-SHARE — R4 / W40-T02, and it is `view` ALONE.
+#:
+#: R4's words are "may re-share **A VIEW**", and the widening goes no further than the ruling
+#: names. That restraint is the whole reason this is a tuple rather than a bare `role == 'edit'`
+#: arm inside `may_administer`: every predicate in this file treats `kind` as an opaque bucket key
+#: (see the note on `KINDS`), so an UNGATED widening would reach `folder`, `database` and `field`
+#: in the same line — handing an `edit` grantee on a `ut_*` DATABASE the power to re-share the
+#: whole table. The asymmetry is one of blast radius: a view is one saved SELECTION, opened through
+#: the receiver's own module wall and row scope; a database grant admits an account to a database.
+#: `routes_shares.py`'s module docstring carries that argument at the door where it is enforced.
+#:
+#: ⚠ ONE SPELLING, DELIBERATELY. `may_administer` and `max_grantable_role` both consult this, so
+#: "who may open the editor" and "what may they hand out" cannot come apart about the same kind.
+RESHARE_KINDS = ('view',)
+class GrantsChanged(Exception):
+    """A grant write was decided against a record that is no longer the stored one.
+    Raised by `set_grants` when its `expect` does not match what is in the store at write time.
+    The door turns it into a 409 rather than a 500: it is not an error in the request, it is two
+    people editing the same sharing list at once, and the honest answer is to say so.
+    """
+#: ⛔⛔ A FIELD's OBJECT ID IS TOPIC-QUALIFIED, AND THE SEPARATOR IS DECLARED HERE SO THERE IS ONE
+#: SPELLING OF IT. A bare field key is NOT unique: `notes` exists on a dozen databases, and a
+#: grant stored under it would admit a grantee to every `notes` column in the tenant at once —
+#: the widening direction, silently, forever. `table_key` is the qualifier because it is the same
+#: identifier `shared_overlay.bucket()` already keys the values by, so the grant and the data it
+#: governs are named by the same string ([[one-question-two-normalizers]]).
+#:
+#: ⚠ A `ut_*` key and a registry topic key both match `[a-z0-9_]+` and neither can contain `:`,
+#: so the split below is unambiguous in both directions.
+FIELD_OID_SEP = ':'
+def field_oid(table_key, field_key):
+    """`"<table_key>:<field_key>"` — the share id of ONE column on ONE database."""
+    table = str(table_key or '').strip()
+    field = str(field_key or '').strip()
+    if not table or not field:
+        raise ValueError('shares.field_oid: a field share names BOTH a database and a column. '
+                         'A bare field key repeats across tables and would grant all of them')
+    return f'{table}{FIELD_OID_SEP}{field}'
+def split_field_oid(oid):
+    """`(table_key, field_key)` or `(None, None)` for anything that is not a field oid.
+    ⛔ FAIL-CLOSED ON JUNK, like every other read here: a caller that cannot learn WHICH database
+    an id names must not fall back to "the one I happen to be looking at", which is how a grant
+    on somebody else's column would be read as a grant on this one.
+    """
+    raw = str(oid or '')
+    table, sep, field = raw.partition(FIELD_OID_SEP)
+    if not sep or not table.strip() or not field.strip() or FIELD_OID_SEP in field:
+        return (None, None)
+    return (table.strip(), field.strip())
+def _st(st):
+    return st if st is not None else store
+def _check_kind(kind):
+    k = str(kind or '').strip().lower()
+    if k not in KINDS:
+        raise ValueError(f'{kind!r} is not a shareable kind. Use one of {", ".join(KINDS)}. '
+                         f'This door refuses to invent a namespace from a typo.')
+    return k
+def _clean_entries(entries):
+    """Normalise + REJECT junk, returning [{'user': str, 'role': 'view'|'edit'}] — plus an
+    OPTIONAL `'by'`, present only when the record already carried one.
+    Silently dropping a malformed entry is right here and wrong elsewhere: the caller is a UI
+    that just listed the people it is about to grant, so a rejected row must not abort the whole
+    save — but an entry with an unknown ROLE must not be stored as something else's default
+    either. Dropped, never coerced.
+    ⭐⭐ D-474 — `by` IS PROVENANCE: THE USERNAME OF WHOEVER PLACED THIS GRANT. Owner ruling
+    2026-08-24: *"a re-sharer can only unshare the people it shared to"*. That question has no
+    answer in a record that stores only WHO HOLDS the grant, so the record grew a third member and
+    this normaliser is where it survives the round trip (`grants` reads every stored entry back
+    through here, so a member this function drops is a member the door can never consult).
+    ⛔⛔ AND THIS FUNCTION STAYS A PURE NORMALISER: IT NEVER INVENTS A `by`, AND IT NEVER
+    VALIDATES ONE. That is not tidiness, it is the whole security property. `set_grants` is handed
+    a caller-supplied list, so a `by` arriving HERE may be forged — and the merge inside
+    `set_grants._apply` therefore OVERWRITES it in both directions from the PRIOR record and the
+    `granter`, never from the payload. Were this function to treat a submitted `by` as
+    authoritative, a re-sharer could PUT `{user: victim, role: view, by: <themselves>}` to
+    re-stamp somebody else's grant as their own, then PUT again omitting the victim, and the wall
+    at the door would be decoration. Normalise the SHAPE here; decide the VALUE there.
+    ⚠ KEY ORDER IS `user, role, by` AND `by` IS ABSENT RATHER THAN `None` WHEN THERE IS NONE.
+    Absence is what keeps every pre-existing record byte-identical after this change (an added
+    `by: None` would rewrite the whole bucket on the next save, for nothing), and it is what
+    `aios-web/api/verify_field_permissions.py` reads when it compares `tuple(entry.values())`
+    against a 2-tuple.
+    """
+    out, seen = [], set()
+    for e in entries or ():
+        if not isinstance(e, dict):
+            continue
+        user = str(e.get('user') or '').strip().lower()
+        role = str(e.get('role') or '').strip().lower()
+        if not user or role not in ROLES or user in seen:
+            continue
+        seen.add(user)
+        row = {'user': user, 'role': role}
+        by = str(e.get('by') or '').strip().lower()
+        if by:
+            row['by'] = by
+        out.append(row)
+    return out
+def grants(kind, oid, st=None):
+    """`{'owner': str|None, 'entries': [{'user','role','by'?}]}` — never raises on a junk bucket.
+    ⭐⭐ D-474 — `by` RIDES THE READ, because the DOOR is what has to consult it. The revocation
+    wall lives in `routes_shares.put_share` (it needs the session, which this layer does not
+    have), and a wall cannot read a member this function strips. `_clean_entries` carries it,
+    so every reader here sees it and no reader has to reach into the raw bucket.
+    ⚠ THE COST, STATED RATHER THAN DISCOVERED: `GET /api/v1/share/{kind}/{oid}` returns this
+    record verbatim, so anyone who may read a grant list now also learns WHO ADDED each person,
+    a `view` grantee included. That is a mild widening of *"who has this?"* into *"who let them
+    in?"*. It is accepted deliberately: the alternative is a second, provenance-stripped read
+    path, which is a second answer to one question and is how the two come apart
+    ([[one-evaluator-per-question]]).
+    """
+    kind = _check_kind(kind)
+    try:
+        bucket = (_st(st).get(SHARES_KEY) or {}).get(kind) or {}
+        rec = bucket.get(str(oid)) or {}
+    except Exception:
+        return {'owner': None, 'entries': []}
+    if not isinstance(rec, dict):
+        return {'owner': None, 'entries': []}
+    return {'owner': (str(rec.get('owner')).strip().lower() if rec.get('owner') else None),
+            'entries': _clean_entries(rec.get('entries'))}
+def set_grants(kind, oid, entries, owner=None, st=None, granter=None, expect=None):
+    """REPLACE the grant set for one object. Returns the stored record.
+    ⚠ REPLACE, NOT MERGE, and that is the contract the UI needs: revoking is expressed by an
+    entry's ABSENCE. A merge-only API cannot remove anybody without a second verb, and the
+    manage-access editor R10 asks for is exactly "here is the list now".
+    ⭐⭐ D-474 — `granter` IS WHO IS DOING THIS SAVE, AND IT IS THE ONLY SOURCE OF A NEW `by`.
+    Owner ruling 2026-08-24: *"a re-sharer can only unshare the people it shared to"*. The wall
+    is at the door (`routes_shares.put_share`), but the FACT it consults can only be recorded
+    here, at the write.
+    ⛔⛔ AND THE STAMP IS DECIDED INSIDE `_apply`, NOT ABOVE IT, BECAUSE `_apply` IS THE ONLY
+    PLACE THE PRIOR RECORD IS VISIBLE. Two rules, and the first is the one that matters:
+      * a user ALREADY in the prior record keeps their stored `by` VERBATIM. Never re-stamped —
+        a re-save would otherwise transfer provenance to whoever saved last, so every re-sharer
+        would silently inherit the right to revoke everybody the owner had ever added, simply by
+        pressing Save. That is the ruling inverted, arriving by accident.
+      * a user who is NEW to the record takes `by = granter`, or carries NO `by` at all when no
+        granter was named.
+    ⛔ IN BOTH ARMS THE VALUE IS OVERWRITTEN FROM (prior, granter) AND NEVER READ OFF THE
+    SUBMITTED ENTRY. `_clean_entries` preserves a submitted `by` because a STORED one has to
+    survive the read; a caller-supplied one is untrusted input. Filling in only a MISSING `by`
+    would leave the two-step forgery open: PUT `{user: victim, by: <me>}` to claim provenance,
+    then PUT again omitting the victim.
+    ⭐ `granter` DEFAULTS TO `None`, AND THAT IS WHAT MAKES THIS SHAPE CHANGE SAFE. Every
+    non-door caller — `core.field_permissions` (promote + reconcile), `modules.product_data`'s
+    Image field, `core.grid_events`' cleanup on delete, the gates — replaces a whole grant set
+    with no caller identity in hand, and each keeps producing EXACTLY the record it produced
+    before this change: no `by`, no new bytes, no behaviour moved. A grant with no `by` is one
+    nobody can prove they made, and the door treats it as the owner's alone to revoke
+    (fail-closed). ⚠ A future edit that defaults this to a session, or stamps it from the entry,
+    deletes that property without touching a line the compiler can complain about.
+    ⚠ `_apply` MAY RUN MORE THAN ONCE. `store._update_locked` re-applies the mutation on a
+    `parent_commit` rebase, so the merge builds FRESH dicts from `clean` on every invocation
+    rather than mutating it in place; a second pass must see the same untouched input, and it
+    must be free to reclassify a user who was "new" on the first pass and is "prior" on the
+    second (exactly what a rebase against another writer's save looks like).
+    ⭐⭐ W41-T03 / RULING R6(d) — `owner=` IS THE REASSIGNMENT CHANNEL, AND IT IS THE ONLY ONE.
+    *"An admin can reassign a field's owner."* The door is `routes_shares.reassign_owner`
+    (`PUT /share/field/{oid}/owner`), which walls on `role_for(...) == 'owner'` and writes through
+    here; nothing else decides who owns an object. `field_permissions.field_class` (contract C1)
+    reads this `owner` and consumers derive the rights from that bag, so moving it here is what
+    moves the badge AND the delete right together.
+    ⛔⛔ AND THE HAZARD THAT COMES WITH A NAMED OWNER WINNING: A CALLER THAT PASSES AN `owner` IT
+    RE-DERIVED CLOBBERS A REASSIGNMENT, SILENTLY. Measured on this tree, wave 41, not argued:
+    `core/grid_events.py` (the grid's field-definition save, under `permission_sync or
+    promoted_this_save`) passes `owner=field.get('createdBy') or uname`, and `modules/product_data`
+    passes `owner=IMAGE_FIELD_CREATOR` on its Image-field repair. Both therefore RESET the owner to
+    the definition's creator on their next write — so a column handed to somebody else reverts the
+    next time its permissions are saved through the grid. ⚠ THE CORRECT SHAPE FOR SUCH A CALLER IS
+    TO PASS NO `owner` AT ALL once a record exists (stickiness then keeps whatever is stored), or
+    to guard on `grants(...)['owner']` first the way `product_data`'s SECOND call site already
+    does. Fixing those two files is out of W41-T03's fence and is booked, not done — this note is
+    here so the next reader of this parameter learns it from the function rather than from a bug.
+    """
+    kind = _check_kind(kind)
+    oid = str(oid)
+    clean = _clean_entries(entries)
+    owner_l = str(owner).strip().lower() if owner else None
+    granter_l = str(granter).strip().lower() if granter else None
+    def _apply(data):
+        by_kind = dict(data.get(kind) or {})
+        # ⛔⛔ COMPARE-AND-SET, AND IT IS A SECURITY BOUNDARY RATHER THAN A TIDINESS ONE.
+        # `routes_shares.put_share` reads the record ONCE, decides against it (may this caller
+        # remove that person, raise that role, add that audience), and only then calls this. The
+        # store re-reads `prior` fresh in here, so between the decision and the write another
+        # save can land and the decision is being applied to a record it never saw.
+        #
+        # Measured by a wave-40 adversarial probe, and it needs no attacker timing: the owner and
+        # a re-sharer both have Manage Access open and both press Save. The re-sharer's PUT was
+        # ACCEPTED with 200 and the grant the owner had just added was gone, with no error on
+        # either screen. That is D-474's wall failing open in the one window where two people are
+        # actually editing the same thing.
+        #
+        # ⚠ THE LOST UPDATE PREDATES THE WALL -- REPLACE semantics plus read-modify-write have
+        # always meant last-write-wins here. What is new is that a PERMISSION decision now rests
+        # on that read. So the caller states what it decided against, and a write that would land
+        # on anything else is refused rather than merged.
+        #
+        # `expect=None` keeps every existing caller byte-identical: the server-derived callers
+        # (`field_permissions`, `product_data`, the `[]` revokes) are not deciding anything about
+        # a person and have nothing to compare.
+        if expect is not None:
+            _now = [(e['user'], e['role']) for e in _clean_entries(
+                (by_kind.get(oid) or {}).get('entries') if isinstance(by_kind.get(oid), dict)
+                else [])]
+            if _now != [(e['user'], e['role']) for e in _clean_entries(expect)]:
+                raise GrantsChanged(
+                    'this item was shared with somebody else while you were editing, so nothing '
+                    'was saved. Reopen the sharing panel to see who has access now, then make '
+                    'your change again.')
+        prior = by_kind.get(oid) if isinstance(by_kind.get(oid), dict) else {}
+        # Read the prior entries through the SAME normaliser every other reader uses, so "was
+        # this user already here" cannot be answered one way by the store and another by the
+        # door ([[one-question-two-normalizers]]).
+        prior_by = {e['user']: e.get('by') for e in _clean_entries(prior.get('entries'))}
+        merged = []
+        for e in clean:
+            row = {'user': e['user'], 'role': e['role']}
+            stamp = prior_by[e['user']] if e['user'] in prior_by else granter_l
+            if stamp:
+                row['by'] = stamp
+            merged.append(row)
+        # The owner is STICKY: set once, and a later save that omits it must not orphan the
+        # object. An ownerless grant record cannot answer "who may re-share this", so every
+        # administer check would fail closed and the object would become unmanageable.
+        # ⛔⛔ STICKY IS ABOUT OMISSION, NOT IMMUTABILITY, AND THE DIFFERENCE IS NOW LOAD-BEARING:
+        # a NAMED `owner` still WINS over the stored one. That is what W41-T03 / R6(d) reassigns
+        # through, and it is also why a caller that means "leave the owner alone" must pass NOTHING
+        # rather than a value it derived for itself. See the hazard note on this function.
+        keep_owner = owner_l or (str(prior.get('owner')).strip().lower()
+                                 if prior.get('owner') else None)
+        if not merged and not keep_owner:
+            by_kind.pop(oid, None)          # fully un-shared and unowned: leave no empty husk
+        else:
+            by_kind[oid] = {'owner': keep_owner, 'entries': merged}
+        data[kind] = by_kind
+        return data
+    _st(st).update(SHARES_KEY, _apply, flush='async')
+    return grants(kind, oid, st=st)
+def role_for(kind, oid, user, is_admin=False, st=None):
+    """`'owner'` | `'edit'` | `'view'` | `None` — the caller's effective role, fail-closed.
+    An ADMIN reads as `'owner'`: an admin who could not administer an object could not
+    administer the tenant either, which is `table_store._may_administer`'s existing rule and is
+    kept identical here so the two cannot disagree about the same view.
+    """
+    user = str(user or '').strip().lower()
+    if not user:
+        return None
+    rec = grants(kind, oid, st=st)
+    if is_admin or (rec['owner'] and rec['owner'] == user):
+        return 'owner'
+    best = None
+    for e in rec['entries']:
+        if e['user'] == user or e['user'] == EVERYONE:
+            # The STRONGER of the two wins when both a personal and an everyone grant exist:
+            # naming somebody explicitly is how you RAISE them above the room, so an
+            # everyone-view + alice-edit pair must leave alice editing.
+            if e['role'] == 'edit':
+                return 'edit'
+            best = best or 'view'
+    return best
+def may_see(kind, oid, user, is_admin=False, st=None):
+    return role_for(kind, oid, user, is_admin=is_admin, st=st) is not None
+def may_edit(kind, oid, user, is_admin=False, st=None):
+    return role_for(kind, oid, user, is_admin=is_admin, st=st) in ('owner', 'edit')
+def may_administer(kind, oid, user, is_admin=False, st=None):
+    """May this caller change WHO ELSE reaches the object, and revoke them?
+    ⭐⭐ R4 / W40-T02 — AN `edit` GRANTEE ANSWERS TRUE, ON A `RESHARE_KINDS` KIND. Owner
+    instruction 4: *"Edit View so a member can share a View as well, not just an admin"*. That
+    reverses this function's old owner-or-admin rule for exactly one kind; the module note says
+    which half of the protection survives and `RESHARE_KINDS` says why it stops at `view`.
+    ⛔ ADMINISTERING IS NOT GRANTING, AND THE SECOND QUESTION HAS ITS OWN PREDICATE. True here
+    means "may open the editor and rewrite the list"; it does NOT mean every role is theirs to
+    hand out. `max_grantable_role` is the ceiling, and R4's two halves are only both honoured if
+    a caller consults both ([[one-evaluator-per-question]]).
+    ⛔ THE GATE IS THE KIND, NOT THE ROLE ALONE. `role_for` is deliberately kind-agnostic, so
+    testing `== 'edit'` without `RESHARE_KINDS` would widen all four kinds in one line.
+    """
+    role = role_for(kind, oid, user, is_admin=is_admin, st=st)
+    if role == 'owner':
+        return True
+    return role == 'edit' and _check_kind(kind) in RESHARE_KINDS
+def max_grantable_role(kind, oid, user, is_admin=False, st=None):
+    """The STRONGEST role this caller may hand SOMEBODY ELSE on this object, fail-closed.
+    `'edit'` for the owner or an admin · `'view'` for an `edit` grantee on a `RESHARE_KINDS` kind
+    · `None` for anybody who may not administer the object at all.
+    ⭐⭐ WHY A SECOND PREDICATE RATHER THAN A FLAG ON `may_administer` (R4 / W40-T02). R4 grants an
+    `edit` holder the right to re-share and caps it in the same breath: *"a re-share may never
+    exceed the role the re-sharer holds"*. Those are two different questions, and a single boolean
+    answering both is exactly how the cap gets dropped by the next caller that only needs the door.
+    ⛔ THE NARROWER OF R4's TWO READINGS SHIPS, AND ON PURPOSE. "Never exceed the role you hold"
+    reads either as *may grant up to and including `edit`* (an edit holder confers edit) or as *may
+    confer strictly less than the owner can*. This returns `'view'` — the second — because it is the
+    FAIL-CLOSED direction. A wrong `'view'` costs the owner one click to raise somebody; a wrong
+    `'edit'` lets a chain of collaborators propagate edit access the owner never approved, with
+    nothing in the store recording who widened it. W40-T02's `done-when` pins the same reading.
+    ⚠ THIS CAPS WHAT A CALLER GRANTS, NOT WHAT THE STORED SET ALREADY HOLDS, and the difference is
+    load-bearing. `routes_shares.put_share` enforces it against the DELTA — a name arriving at
+    `edit`, or an existing `view` grantee raised to it — never against every row of a body, because
+    the PUT REPLACES and the client therefore re-sends the whole list, the re-sharer's own `edit`
+    row included. The evidence for that is at the call site, where the body is.
+    ⛔⛔ AND IT IS ONE OF THREE BOUNDS ON A RE-SHARE, NOT THE BOUND. Owner ruling 2026-08-24 added
+    two more, and both live at the door because both need the SESSION: `_audience_added` (D-473,
+    a re-sharer may name people and may not reach `EVERYONE`) and `_unremovable` (D-474, a
+    re-sharer may revoke only what their own `by` stamp says they granted). ⚠ A reader who takes
+    this function for the whole ceiling will widen the other two by leaving them alone — which is
+    exactly how R4 shipped with an audience hole and a revocation hole under a docstring that
+    read like a complete account of the limits.
+    """
+    role = role_for(kind, oid, user, is_admin=is_admin, st=st)
+    if role == 'owner':
+        return 'edit'
+    if role == 'edit' and _check_kind(kind) in RESHARE_KINDS:
+        return 'view'
+    return None
+def shared_with(user, kind=None, st=None):
+    """Every object id this user has been granted (excluding what they own).
+    This is the "Shared with me" query (R10). It EXCLUDES owned objects deliberately: a folder
+    you made is not something shared *with* you, and listing it there would make the system
+    folder a duplicate of the rail above it.
+    """
+    user = str(user or '').strip().lower()
+    if not user:
+        return {}
+    try:
+        data = _st(st).get(SHARES_KEY) or {}
+    except Exception:
+        return {}
+    out = {}
+    for k in ([_check_kind(kind)] if kind else KINDS):
+        hits = []
+        for oid, rec in (data.get(k) or {}).items():
+            if not isinstance(rec, dict):
+                continue
+            owner = str(rec.get('owner') or '').strip().lower()
+            if owner == user:
+                continue
+            for e in _clean_entries(rec.get('entries')):
+                if e['user'] in (user, EVERYONE):
+                    hits.append(str(oid))
+                    break
+        out[k] = sorted(hits)
+    return out if kind is None else {_check_kind(kind): out[_check_kind(kind)]}
+def granted_oids(kind, st=None):
+    """Every object id of one `kind` that carries AT LEAST ONE grant entry — in ONE bucket read.
+    ⭐ W40-T01 / OWNER INSTRUCTION 2 ("a shared View must show the shared icon in EVERY account,
+    not only the recipient's"). `shared_with` answers *what was granted TO me* and deliberately
+    EXCLUDES what the caller owns — so it structurally cannot answer the other question a share
+    mark asks: *does this object have grants at all*. That question has no viewer in it, which is
+    why this is a separate function rather than a flag bolted onto `shared_with`.
+    ⚠ ONE READ, NOT N — and that is the whole reason this exists rather than a loop at the caller.
+    The obvious spelling is `grants(kind, oid)` per view, and `grants` re-reads the WHOLE bucket
+    on every call; a busy rail carries dozens of views, so painting one icon would cost dozens of
+    full reads of the tenant's entire grant registry. This reads the bucket once and hands back a
+    set the caller tests in O(1).
+    ⛔ AN ENTRY IS WHAT COUNTS, NOT A RECORD. `set_grants` keeps an owner-only HUSK after a full
+    revoke — the owner is sticky, deliberately, see its own note — so testing for the record's
+    mere EXISTENCE would leave the mark lit forever after the last person was removed. That is
+    exactly the revoke case, so it is the difference between this being right and being decorative
+    noise. `_clean_entries` is the same normaliser every other read here uses, so a junk entry
+    cannot mark an object either.
+    ⛔ FAIL-CLOSED like the rest of this module: an unreadable bucket answers the EMPTY set — no
+    marks — never a default that claims something is shared. An unknown KIND still RAISES, exactly
+    as `grants` / `shared_with` / `drop_objects` do: that is a typo in a caller, not junk in the
+    store, and swallowing it into "nothing is shared" would hide a caller that never works.
+    """
+    kind = _check_kind(kind)
+    try:
+        by_kind = (_st(st).get(SHARES_KEY) or {}).get(kind) or {}
+        rows = list(by_kind.items())
+    except Exception:
+        return set()
+    return {str(oid) for oid, rec in rows
+            if isinstance(rec, dict) and _clean_entries(rec.get('entries'))}
+def drop_objects(pairs, st=None):
+    """Remove whole grant RECORDS, owner husk included — wave 21, item 6a (C3).
+    A deleted object's grants must die with it: `shared_with` would otherwise serve ghost ids
+    into every receiver's "Shared with me" forever, and the ghost would 404 on open. One
+    transaction for the whole sweep — a table delete drops its database grant plus a view
+    grant per view that lived in its bucket."""
+    want = {}
+    for kind, oid in pairs or ():
+        want.setdefault(_check_kind(kind), set()).add(str(oid))
+    if not want:
+        return
+    def _apply(data):
+        for kind, oids in want.items():
+            by_kind = data.get(kind)
+            if isinstance(by_kind, dict):
+                for oid in oids:
+                    by_kind.pop(oid, None)
+        return data
+    _st(st).update(SHARES_KEY, _apply, flush='async')

platform/core/store.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

platform/core/table_store.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

platform/core/user_tables.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

platform/harness/connectors/odoo.py CHANGED Viewed

@@ -51,8 +51,24 @@ _MAP = {
         'f': {'product': 'product_id', 'qty': 'quantity', 'location': 'location_id'}},
     Entity.PRODUCT: {
         'model': 'product.product', 'date': None, 'dt': False,
         'f': {'id': 'id', 'code': 'default_code', 'name': 'name', 'category': 'categ_id',
-              'cost': 'standard_price', 'active': 'active'}},
     Entity.CUSTOMER: {
         'model': 'res.partner', 'date': None, 'dt': False,
         'f': {'id': 'id', 'name': 'name', 'city': 'city', 'state': 'state_id',

         'f': {'product': 'product_id', 'qty': 'quantity', 'location': 'location_id'}},
     Entity.PRODUCT: {
         'model': 'product.product', 'date': None, 'dt': False,
+        # ⭐⭐ W41-T26 (owner instruction 28, "pull UPC live from Odoo") — `barcode` is the
+        # canonical UPC. It is declared HERE so the vocabulary is complete for the next connector
+        # and the next tenant, but be clear about what this line does and does not do TODAY:
+        # ⚠ NOTHING in the repo calls `.records()` or `.aggregate()` on `Entity.PRODUCT` (grepped
+        # 2026-08-24: the only two references to the symbol are this map and `canonical.FIELDS`).
+        # The product grid's barcode comes from `modules/products.py::catalogue()`, which issues
+        # its own `search_read` and does not route through this connector at all. So this is a
+        # CONTRACT entry, not the live path, and moving it will not move a cell on screen.
+        # ⚠ PAYLOAD: `records()` falls back to `tuple(meta['f'])` when a Query names no measures
+        # (`:163`), so an unmeasured product read widens 6 fields -> 7. No caller exists to pay
+        # that today; a future one reads one extra char column per product (~13 bytes x 5,874).
+        # ⛔ `harness/canonical.py::FIELDS[Entity.PRODUCT]` still reads {'id','code','name',
+        # 'category','cost','active'} and does NOT list 'barcode'. That file is outside this
+        # ticket's fence, so the two drifted apart deliberately rather than by oversight. Nothing
+        # ENFORCES FIELDS in code (grepped: it has no consumer), so this is a documentation gap
+        # and not a live defect — but the next person to touch canonical.py should close it.
         'f': {'id': 'id', 'code': 'default_code', 'name': 'name', 'category': 'categ_id',
+              'cost': 'standard_price', 'active': 'active', 'barcode': 'barcode'}},
     Entity.CUSTOMER: {
         'model': 'res.partner', 'date': None, 'dt': False,
         'f': {'id': 'id', 'name': 'name', 'city': 'city', 'state': 'state_id',

platform/harness/datastore.py CHANGED Viewed

The diff for this file is too large to render. See raw diff

platform/harness/meta_store.py CHANGED Viewed

@@ -1,521 +1,521 @@
-"""meta_store.py — the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
-    python platform/harness/meta_store.py --sync                 pull into tenant #0's mirror
-    python platform/harness/meta_store.py --sync --tenant gtmlab
-    python platform/harness/meta_store.py --status               what is in the mirror now
-⛔ WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
-hardwired to XML-RPC — it does `import core.odoo as O` and speaks `search_read` — so no amount of
-spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
-per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
-delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
-store with two loaders, not two stores.**
-⭐ THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
-the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
-`XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
-`Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
-different first hop.
-⚠ EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
-carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
-  Ad Account 45 · Campaign 35 · Ad Set 54 · Ad 36 · Creative 58 · Insights 57
-⛔ AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
-came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
-nothing going red — which is exactly the "do not drop any column" instruction, broken silently.
-The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
-⚠ `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
-answers `403 (#200) Requires business_management permission`, which this token does not carry. One
-column of 285. R6's second sentence — a limit that cannot be removed gets stated with its cause.
-⛔ IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
-larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
-(W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
-"""
-import argparse
-import json
-import os
-import sys
-import time
-import urllib.error
-import urllib.parse
-import urllib.request
-from pathlib import Path
-_HERE = Path(__file__).resolve().parent
-if str(_HERE.parent) not in sys.path:
-    sys.path.insert(0, str(_HERE.parent))
-from harness import datastore                                    # noqa: E402
-GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
-GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
-#: Numeric columns, by name. Everything else is VARCHAR — including ids (see the header) and
-#: including anything Graph returns as a nested object, which is stored as compact JSON text.
-_INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
-        "inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
-        "account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
-        "min_daily_budget", "min_campaign_group_spend_cap"}
-_DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
-        "inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
-        "daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
-        "daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
-        "lifetime_spend_cap", "lifetime_imps"}
-#: ⭐ THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
-#: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
-#: the grid links in `meta_relational`.
-ACCOUNT_FIELDS = (
-    "account_id account_status age amount_spent balance business_city business_country_code "
-    "business_name business_state business_street business_street2 business_zip capabilities "
-    "created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
-    "has_migrated_permissions id io_number is_attribution_spec_system_default "
-    "is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
-    "is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
-    "name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
-    "timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
-).split()
-CAMPAIGN_FIELDS = (
-    "account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
-    "campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
-    "created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
-    "last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
-    "promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
-    "special_ad_category special_ad_category_country spend_cap start_time status stop_time "
-    "topline_id updated_time"
-).split()
-ADSET_FIELDS = (
-    "account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
-    "bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
-    "campaign_active_time campaign_attribution campaign_id configured_status created_time "
-    "creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
-    "effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
-    "issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
-    "lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
-    "optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
-    "rf_prediction_id source_adset source_adset_id start_time status targeting "
-    "targeting_optimization_types time_based_ad_rotation_id_blocks "
-    "time_based_ad_rotation_intervals updated_time use_new_app_click"
-).split()
-AD_FIELDS = (
-    "account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
-    "adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
-    "conversion_domain created_time creative demolink_hash display_sequence effective_status "
-    "engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
-    "preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
-    "tracking_and_conversion_with_defaults tracking_specs updated_time"
-).split()
-CREATIVE_FIELDS = (
-    "account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
-    "branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
-    "category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
-    "destination_set_id dynamic_ad_voice effective_authorization_category "
-    "effective_instagram_media_id effective_object_story_id enable_direct_install "
-    "enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
-    "instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
-    "link_deep_link_url link_destination_display_url link_og_id link_url "
-    "messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
-    "object_type object_url place_page_set_id platform_customizations playable_asset_id "
-    "portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
-    "template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
-    "use_page_actor_override video_id"
-).split()
-INSIGHT_FIELDS = (
-    "account_currency account_id account_name action_values actions ad_id ad_name adset_id "
-    "adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
-    "clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
-    "cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
-    "date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
-    "impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
-    "optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
-    "social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
-    "video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
-    "video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
-    "video_play_actions video_thruplay_watched_actions website_purchase_roas"
-).split()
-#: table -> (graph edge on the account | None, measured fields, parent column)
-SPECS = {
-    "meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
-    "meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
-    "meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
-    "meta_ads": ("ads", AD_FIELDS, "adset_id"),
-    "meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
-}
-#: The daily Insights grain (R2). One row per (ad, day) — the id is synthesised because Insights
-#: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
-INSIGHTS_TABLE = "meta_insights_daily"
-INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
-#: ⛔ INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
-#: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
-#: — Graph's way of saying the synchronous query is too heavy (the async report-run API is the
-#: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
-#: page 25 answer 200. So the window is walked in slices with every column intact:
-#:   57 fields · ad level · 7d · limit 25   -> 200, 25 rows
-#:   57 fields · account level · 7d          -> 200, 7 rows
-#: ⚠ Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over —
-#: it drops columns R2 requires, and it does so invisibly.
-INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
-INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
-INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
-def _slices(days, size):
-    """[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
-    from datetime import date, timedelta
-    end = date.today()
-    start = end - timedelta(days=max(1, days) - 1)
-    out, cur = [], start
-    while cur <= end:
-        stop = min(cur + timedelta(days=max(1, size) - 1), end)
-        out.append((cur.isoformat(), stop.isoformat()))
-        cur = stop + timedelta(days=1)
-    return out
-#: ⚠ A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
-#: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
-#: not a row cap on a connected source (R6 forbids that) — it is a runaway guard, and reaching it
-#: is reported as a problem, never absorbed.
-MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
-PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
-class MetaError(RuntimeError):
-    """A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
-def token():
-    """The Meta token from the environment or gitignored `platform/.env`; "" when absent.
-    ⚠ Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
-    `platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
-    (`core` never imports up). Fifteen lines is the price of that boundary.
-    """
-    tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
-    if tok:
-        return tok.strip()
-    env = _HERE.parent / ".env"
-    if env.exists():
-        for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
-            if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
-                _, _, v = line.partition("=")
-                return v.strip().strip('"').strip("'")
-    return ""
-def _get(path, tok, **params):
-    params["access_token"] = tok
-    url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
-    req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
-    try:
-        with urllib.request.urlopen(req, timeout=120) as r:
-            return json.loads(r.read().decode("utf-8", "replace"))
-    except urllib.error.HTTPError as e:
-        try:
-            msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
-                   ).get("message") or ""
-        except Exception:
-            msg = ""
-        raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
-    except Exception as e:
-        raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
-#: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
-#: why it cannot be treated as "the server is broken, give up".
-_TOO_MUCH = "reduce the amount of data"
-#: ⛔ THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
-#: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
-#: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" — the
-#: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
-#: ⚠ It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
-#: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
-#: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
-_RATE_LIMITED = "too many calls"
-_RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
-_RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
-def _walk(path, tok, log, **params):
-    """Every page of an edge, paged by CURSOR under our own parameters.
-    ⛔ IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
-    first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
-    you're asking for"**, the retry at limit=25 succeeds — and then `next` carries the ORIGINAL
-    limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
-    Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
-    ⭐ It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
-    silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
-    every column per row.
-    -> (rows, hit_page_cap)
-    """
-    out, pages = [], 0
-    limit = int(params.pop("limit", None) or PAGE)
-    after, waited = None, 0
-    while True:
-        call = dict(params, limit=limit)
-        if after:
-            call["after"] = after
-        try:
-            body = _get(path, tok, **call)
-        except MetaError as e:
-            if _TOO_MUCH in str(e) and limit > 5:
-                limit = max(5, limit // 4)
-                log(f"    page too heavy for /{path} - retrying at limit={limit} "
-                    f"(a payload ceiling, not a row cap; every column is still asked for)")
-                continue
-            if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
-                waited += 1
-                log(f"    rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
-                    f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
-                time.sleep(_RATE_WAIT)
-                continue
-            if _RATE_LIMITED in str(e).lower():
-                log(f"    !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
-                    f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
-                    f"limit is per ad account and persists for minutes. Fix: re-run "
-                    f"`--sync --only <table>` later; the upsert is idempotent.")
-                return out, True
-            raise
-        out.extend(body.get("data") or [])
-        pages += 1
-        after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
-        has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
-        if not has_next:
-            return out, False
-        if pages >= MAX_PAGES:
-            log(f"    !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
-                f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
-                f"window with META_INSIGHTS_DAYS.")
-            return out, True
-def _cell(value):
-    """One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
-    being dropped: R2 says every field the API returns, and `targeting` is a field."""
-    if value is None or isinstance(value, (str, int, float, bool)):
-        return value
-    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
-def _coltype(name, rows=None):
-    """The DuckDB type for one column — decided by the DATA when there is data, by the name only
-    as a fallback.
-    ⛔ THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
-    `cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
-    action-type objects** on the Insights edge:
-        [{"action_type":"outbound_click","value":"1.459854"}]
-    Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
-    '[{...}]' to DOUBLE` — after five entity tables had already been written, so the sync looked
-    like it worked and then blew up on the last table.
-    ⭐ Same principle the field CATALOG is built on, applied one layer down: **ask the response,
-    do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
-    that is what `_cell` stores; anything else falls back to the measured name hints.
-    """
-    if rows:
-        seen, kinds = 0, set()
-        for r in rows:
-            v = r.get(name)
-            if v is None or v == "":
-                continue
-            kinds.add("json" if isinstance(v, (list, dict)) else
-                      "bool" if isinstance(v, bool) else
-                      "int" if isinstance(v, int) else
-                      "float" if isinstance(v, float) else "str")
-            seen += 1
-            if seen >= 200:
-                break
-        if kinds:
-            if "json" in kinds or "str" in kinds:
-                return "VARCHAR"                              # a JSON blob, or a numeric STRING
-            if kinds <= {"int", "bool"}:
-                return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
-            return "DOUBLE"
-    if name in _INT:
-        return "BIGINT"
-    if name in _DBL:
-        return "DOUBLE"
-    return "VARCHAR"                                          # ids included — see the header
-def _ensure(con, table, fields, rows=None):
-    """Create or widen the table, with every column typed from `rows` when they are available.
-    ⚠ AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
-    column in place, and this table is DERIVED data that can be re-pulled in minutes — so a type
-    disagreement drops and recreates rather than limping on with a column that refuses every
-    insert. The alternative is a mirror that is permanently unwritable for one bad guess.
-    """
-    want = {f: _coltype(f, rows) for f in fields}
-    have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
-    if have:
-        clash = [f for f, ty in want.items() if f in have and have[f] != ty
-                 and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
-        if clash:
-            con.execute(f"DROP TABLE {table}")
-            have = {}
-    if not have:
-        cols = ", ".join(f"{f} {want[f]}" for f in fields)
-        con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
-                    if "id" not in fields else
-                    f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
-        return
-    for f in fields:
-        if f not in have:
-            con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
-def _upsert(con, table, fields, rows):
-    """Delete-then-insert by id — the same idempotence `datastore._upsert` gives the Odoo half, so
-    a re-sync updates in place and can never append a second copy of the same object."""
-    if not rows:
-        return 0
-    cols = list(fields)
-    ids = [str(r.get("id") or "") for r in rows]
-    q = ",".join("?" for _ in ids)
-    con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
-    con.executemany(
-        f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
-        [[_cell(r.get(c)) for c in cols] for r in rows])
-    return len(rows)
-def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
-    """Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
-    Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
-    exactly as `odoo_relational.refresh` is.
-    """
-    tok = tok or token()
-    # ⛔ THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME — and the difference cost a
-    # live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
-    # `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
-    # imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
-    # that trips the per-ad-account rate limit and never finishes. The comment beside that call
-    # claimed a short window the code could not deliver.
-    # ⭐ The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
-    # makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
-    days = int(insights_days or INSIGHTS_DAYS)
-    report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
-    if not tok:
-        report["problems"].append(
-            "META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
-            "was pulled. This is a missing CREDENTIAL, not a missing capability.")
-        return report
-    path = datastore.path_for(tenant_key)
-    if Path(datastore.DB_PATH) != Path(path):
-        datastore.use_path(path)
-    con = datastore.connect()
-    log(f"  mirror: {Path(path).name}")
-    accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
-    report["accounts"] = [a.get("id") for a in accts]
-    if not accts:
-        report["problems"].append("the token reaches no ad accounts")
-        return report
-    # ── the five entity levels ────────────────────────────────────────────────────────────────
-    for table, (edge, fields, _parent) in SPECS.items():
-        rows, capped = [], False
-        for acct in accts:
-            aid = acct["id"]
-            if edge is None:
-                rows.append(_get(aid, tok, fields=",".join(fields)))
-            else:
-                got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
-                rows.extend(got)
-                capped = capped or hit
-        _ensure(con, table, fields, rows)
-        n = _upsert(con, table, fields, rows)
-        total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
-        report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
-        log(f"  {table:<20} pulled {n:>6}   mirror total {total:>6}"
-            + ("   !! PAGE CAP HIT" if capped else ""))
-        if capped:
-            report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
-    # ── the daily Insights grain ──────────────────────────────────────────────────────────────
-    if insights:
-        rows, capped = [], False
-        for acct in accts:
-            for since, until in _slices(days, INSIGHTS_SLICE):
-                got, hit = _walk(f"{acct['id']}/insights", tok, log,
-                                 fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
-                                 time_increment="1", limit=INSIGHTS_PAGE,
-                                 time_range=json.dumps({"since": since, "until": until}))
-                rows.extend(got)
-                capped = capped or hit
-        # ⛔ Insights rows carry no id. The key must be STABLE across runs or every re-sync
-        # appends a second copy of the same day — so it is composed from the grain itself.
-        for r in rows:
-            r["id"] = ":".join(str(r.get(k) or "") for k in
-                               (f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
-        fields = ["id"] + INSIGHT_FIELDS
-        _ensure(con, INSIGHTS_TABLE, fields, rows)
-        n = _upsert(con, INSIGHTS_TABLE, fields, rows)
-        total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
-        report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
-        log(f"  {INSIGHTS_TABLE:<20} pulled {n:>6}   mirror total {total:>6}"
-            + ("   !! PAGE CAP HIT" if capped else ""))
-    con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
-                ["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
-                 sum(t["in_mirror"] for t in report["tables"].values()),
-                 time.strftime("%Y-%m-%d %H:%M:%S")])
-    return report
-def status(tenant_key="royal-imports"):
-    """What is in the mirror right now, per table. Never fetches."""
-    path = datastore.path_for(tenant_key)
-    if Path(datastore.DB_PATH) != Path(path):
-        datastore.use_path(path)
-    out = {}
-    con = datastore.connect()
-    for table in list(SPECS) + [INSIGHTS_TABLE]:
-        try:
-            out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
-        except Exception:
-            out[table] = None                                 # table absent = never synced
-    return out
-def main(argv=None):
-    ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
-    ap.add_argument("--sync", action="store_true")
-    ap.add_argument("--status", action="store_true")
-    ap.add_argument("--tenant", default="royal-imports")
-    ap.add_argument("--no-insights", action="store_true")
-    ap.add_argument("--insights-days", type=int, default=None,
-                    help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
-    a = ap.parse_args(argv)
-    if a.status:
-        for k, v in status(a.tenant).items():
-            print(f"  {k:<20} {'(never synced)' if v is None else v}")
-        return 0
-    if not a.sync:
-        ap.print_help()
-        return 2
-    rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
-    for p in rep["problems"]:
-        print("  PROBLEM:", p)
-    print(f"  accounts: {len(rep['accounts'])}   tables: {len(rep['tables'])}")
-    return 1 if rep["problems"] else 0
-if __name__ == "__main__":
-    sys.exit(main())

+"""meta_store.py — the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
+    python platform/harness/meta_store.py --sync                 pull into tenant #0's mirror
+    python platform/harness/meta_store.py --sync --tenant gtmlab
+    python platform/harness/meta_store.py --status               what is in the mirror now
+⛔ WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
+hardwired to XML-RPC — it does `import core.odoo as O` and speaks `search_read` — so no amount of
+spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
+per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
+delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
+store with two loaders, not two stores.**
+⭐ THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
+the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
+`XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
+`Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
+different first hop.
+⚠ EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
+carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
+  Ad Account 45 · Campaign 35 · Ad Set 54 · Ad 36 · Creative 58 · Insights 57
+⛔ AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
+came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
+nothing going red — which is exactly the "do not drop any column" instruction, broken silently.
+The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
+⚠ `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
+answers `403 (#200) Requires business_management permission`, which this token does not carry. One
+column of 285. R6's second sentence — a limit that cannot be removed gets stated with its cause.
+⛔ IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
+larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
+(W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
+"""
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+_HERE = Path(__file__).resolve().parent
+if str(_HERE.parent) not in sys.path:
+    sys.path.insert(0, str(_HERE.parent))
+from harness import datastore                                    # noqa: E402
+GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
+GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
+#: Numeric columns, by name. Everything else is VARCHAR — including ids (see the header) and
+#: including anything Graph returns as a nested object, which is stored as compact JSON text.
+_INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
+        "inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
+        "account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
+        "min_daily_budget", "min_campaign_group_spend_cap"}
+_DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
+        "inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
+        "daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
+        "daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
+        "lifetime_spend_cap", "lifetime_imps"}
+#: ⭐ THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
+#: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
+#: the grid links in `meta_relational`.
+ACCOUNT_FIELDS = (
+    "account_id account_status age amount_spent balance business_city business_country_code "
+    "business_name business_state business_street business_street2 business_zip capabilities "
+    "created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
+    "has_migrated_permissions id io_number is_attribution_spec_system_default "
+    "is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
+    "is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
+    "name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
+    "timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
+).split()
+CAMPAIGN_FIELDS = (
+    "account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
+    "campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
+    "created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
+    "last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
+    "promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
+    "special_ad_category special_ad_category_country spend_cap start_time status stop_time "
+    "topline_id updated_time"
+).split()
+ADSET_FIELDS = (
+    "account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
+    "bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
+    "campaign_active_time campaign_attribution campaign_id configured_status created_time "
+    "creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
+    "effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
+    "issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
+    "lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
+    "optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
+    "rf_prediction_id source_adset source_adset_id start_time status targeting "
+    "targeting_optimization_types time_based_ad_rotation_id_blocks "
+    "time_based_ad_rotation_intervals updated_time use_new_app_click"
+).split()
+AD_FIELDS = (
+    "account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
+    "adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
+    "conversion_domain created_time creative demolink_hash display_sequence effective_status "
+    "engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
+    "preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
+    "tracking_and_conversion_with_defaults tracking_specs updated_time"
+).split()
+CREATIVE_FIELDS = (
+    "account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
+    "branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
+    "category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
+    "destination_set_id dynamic_ad_voice effective_authorization_category "
+    "effective_instagram_media_id effective_object_story_id enable_direct_install "
+    "enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
+    "instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
+    "link_deep_link_url link_destination_display_url link_og_id link_url "
+    "messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
+    "object_type object_url place_page_set_id platform_customizations playable_asset_id "
+    "portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
+    "template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
+    "use_page_actor_override video_id"
+).split()
+INSIGHT_FIELDS = (
+    "account_currency account_id account_name action_values actions ad_id ad_name adset_id "
+    "adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
+    "clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
+    "cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
+    "date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
+    "impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
+    "optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
+    "social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
+    "video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
+    "video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
+    "video_play_actions video_thruplay_watched_actions website_purchase_roas"
+).split()
+#: table -> (graph edge on the account | None, measured fields, parent column)
+SPECS = {
+    "meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
+    "meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
+    "meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
+    "meta_ads": ("ads", AD_FIELDS, "adset_id"),
+    "meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
+}
+#: The daily Insights grain (R2). One row per (ad, day) — the id is synthesised because Insights
+#: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
+INSIGHTS_TABLE = "meta_insights_daily"
+INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
+#: ⛔ INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
+#: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
+#: — Graph's way of saying the synchronous query is too heavy (the async report-run API is the
+#: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
+#: page 25 answer 200. So the window is walked in slices with every column intact:
+#:   57 fields · ad level · 7d · limit 25   -> 200, 25 rows
+#:   57 fields · account level · 7d          -> 200, 7 rows
+#: ⚠ Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over —
+#: it drops columns R2 requires, and it does so invisibly.
+INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
+INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
+INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
+def _slices(days, size):
+    """[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
+    from datetime import date, timedelta
+    end = date.today()
+    start = end - timedelta(days=max(1, days) - 1)
+    out, cur = [], start
+    while cur <= end:
+        stop = min(cur + timedelta(days=max(1, size) - 1), end)
+        out.append((cur.isoformat(), stop.isoformat()))
+        cur = stop + timedelta(days=1)
+    return out
+#: ⚠ A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
+#: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
+#: not a row cap on a connected source (R6 forbids that) — it is a runaway guard, and reaching it
+#: is reported as a problem, never absorbed.
+MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
+PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
+class MetaError(RuntimeError):
+    """A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
+def token():
+    """The Meta token from the environment or gitignored `platform/.env`; "" when absent.
+    ⚠ Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
+    `platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
+    (`core` never imports up). Fifteen lines is the price of that boundary.
+    """
+    tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
+    if tok:
+        return tok.strip()
+    env = _HERE.parent / ".env"
+    if env.exists():
+        for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
+            if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
+                _, _, v = line.partition("=")
+                return v.strip().strip('"').strip("'")
+    return ""
+def _get(path, tok, **params):
+    params["access_token"] = tok
+    url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
+    req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
+    try:
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return json.loads(r.read().decode("utf-8", "replace"))
+    except urllib.error.HTTPError as e:
+        try:
+            msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
+                   ).get("message") or ""
+        except Exception:
+            msg = ""
+        raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
+    except Exception as e:
+        raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
+#: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
+#: why it cannot be treated as "the server is broken, give up".
+_TOO_MUCH = "reduce the amount of data"
+#: ⛔ THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
+#: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
+#: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" — the
+#: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
+#: ⚠ It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
+#: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
+#: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
+_RATE_LIMITED = "too many calls"
+_RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
+_RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
+def _walk(path, tok, log, **params):
+    """Every page of an edge, paged by CURSOR under our own parameters.
+    ⛔ IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
+    first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
+    you're asking for"**, the retry at limit=25 succeeds — and then `next` carries the ORIGINAL
+    limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
+    Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
+    ⭐ It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
+    silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
+    every column per row.
+    -> (rows, hit_page_cap)
+    """
+    out, pages = [], 0
+    limit = int(params.pop("limit", None) or PAGE)
+    after, waited = None, 0
+    while True:
+        call = dict(params, limit=limit)
+        if after:
+            call["after"] = after
+        try:
+            body = _get(path, tok, **call)
+        except MetaError as e:
+            if _TOO_MUCH in str(e) and limit > 5:
+                limit = max(5, limit // 4)
+                log(f"    page too heavy for /{path} - retrying at limit={limit} "
+                    f"(a payload ceiling, not a row cap; every column is still asked for)")
+                continue
+            if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
+                waited += 1
+                log(f"    rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
+                    f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
+                time.sleep(_RATE_WAIT)
+                continue
+            if _RATE_LIMITED in str(e).lower():
+                log(f"    !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
+                    f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
+                    f"limit is per ad account and persists for minutes. Fix: re-run "
+                    f"`--sync --only <table>` later; the upsert is idempotent.")
+                return out, True
+            raise
+        out.extend(body.get("data") or [])
+        pages += 1
+        after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
+        has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
+        if not has_next:
+            return out, False
+        if pages >= MAX_PAGES:
+            log(f"    !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
+                f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
+                f"window with META_INSIGHTS_DAYS.")
+            return out, True
+def _cell(value):
+    """One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
+    being dropped: R2 says every field the API returns, and `targeting` is a field."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+def _coltype(name, rows=None):
+    """The DuckDB type for one column — decided by the DATA when there is data, by the name only
+    as a fallback.
+    ⛔ THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
+    `cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
+    action-type objects** on the Insights edge:
+        [{"action_type":"outbound_click","value":"1.459854"}]
+    Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
+    '[{...}]' to DOUBLE` — after five entity tables had already been written, so the sync looked
+    like it worked and then blew up on the last table.
+    ⭐ Same principle the field CATALOG is built on, applied one layer down: **ask the response,
+    do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
+    that is what `_cell` stores; anything else falls back to the measured name hints.
+    """
+    if rows:
+        seen, kinds = 0, set()
+        for r in rows:
+            v = r.get(name)
+            if v is None or v == "":
+                continue
+            kinds.add("json" if isinstance(v, (list, dict)) else
+                      "bool" if isinstance(v, bool) else
+                      "int" if isinstance(v, int) else
+                      "float" if isinstance(v, float) else "str")
+            seen += 1
+            if seen >= 200:
+                break
+        if kinds:
+            if "json" in kinds or "str" in kinds:
+                return "VARCHAR"                              # a JSON blob, or a numeric STRING
+            if kinds <= {"int", "bool"}:
+                return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
+            return "DOUBLE"
+    if name in _INT:
+        return "BIGINT"
+    if name in _DBL:
+        return "DOUBLE"
+    return "VARCHAR"                                          # ids included — see the header
+def _ensure(con, table, fields, rows=None):
+    """Create or widen the table, with every column typed from `rows` when they are available.
+    ⚠ AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
+    column in place, and this table is DERIVED data that can be re-pulled in minutes — so a type
+    disagreement drops and recreates rather than limping on with a column that refuses every
+    insert. The alternative is a mirror that is permanently unwritable for one bad guess.
+    """
+    want = {f: _coltype(f, rows) for f in fields}
+    have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
+    if have:
+        clash = [f for f, ty in want.items() if f in have and have[f] != ty
+                 and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
+        if clash:
+            con.execute(f"DROP TABLE {table}")
+            have = {}
+    if not have:
+        cols = ", ".join(f"{f} {want[f]}" for f in fields)
+        con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
+                    if "id" not in fields else
+                    f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
+        return
+    for f in fields:
+        if f not in have:
+            con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
+def _upsert(con, table, fields, rows):
+    """Delete-then-insert by id — the same idempotence `datastore._upsert` gives the Odoo half, so
+    a re-sync updates in place and can never append a second copy of the same object."""
+    if not rows:
+        return 0
+    cols = list(fields)
+    ids = [str(r.get("id") or "") for r in rows]
+    q = ",".join("?" for _ in ids)
+    con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
+    con.executemany(
+        f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
+        [[_cell(r.get(c)) for c in cols] for r in rows])
+    return len(rows)
+def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
+    """Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
+    Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
+    exactly as `odoo_relational.refresh` is.
+    """
+    tok = tok or token()
+    # ⛔ THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME — and the difference cost a
+    # live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
+    # `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
+    # imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
+    # that trips the per-ad-account rate limit and never finishes. The comment beside that call
+    # claimed a short window the code could not deliver.
+    # ⭐ The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
+    # makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
+    days = int(insights_days or INSIGHTS_DAYS)
+    report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
+    if not tok:
+        report["problems"].append(
+            "META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
+            "was pulled. This is a missing CREDENTIAL, not a missing capability.")
+        return report
+    path = datastore.path_for(tenant_key)
+    if Path(datastore.DB_PATH) != Path(path):
+        datastore.use_path(path)
+    con = datastore.connect()
+    log(f"  mirror: {Path(path).name}")
+    accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
+    report["accounts"] = [a.get("id") for a in accts]
+    if not accts:
+        report["problems"].append("the token reaches no ad accounts")
+        return report
+    # ── the five entity levels ────────────────────────────────────────────────────────────────
+    for table, (edge, fields, _parent) in SPECS.items():
+        rows, capped = [], False
+        for acct in accts:
+            aid = acct["id"]
+            if edge is None:
+                rows.append(_get(aid, tok, fields=",".join(fields)))
+            else:
+                got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
+                rows.extend(got)
+                capped = capped or hit
+        _ensure(con, table, fields, rows)
+        n = _upsert(con, table, fields, rows)
+        total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
+        report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
+        log(f"  {table:<20} pulled {n:>6}   mirror total {total:>6}"
+            + ("   !! PAGE CAP HIT" if capped else ""))
+        if capped:
+            report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
+    # ── the daily Insights grain ──────────────────────────────────────────────────────────────
+    if insights:
+        rows, capped = [], False
+        for acct in accts:
+            for since, until in _slices(days, INSIGHTS_SLICE):
+                got, hit = _walk(f"{acct['id']}/insights", tok, log,
+                                 fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
+                                 time_increment="1", limit=INSIGHTS_PAGE,
+                                 time_range=json.dumps({"since": since, "until": until}))
+                rows.extend(got)
+                capped = capped or hit
+        # ⛔ Insights rows carry no id. The key must be STABLE across runs or every re-sync
+        # appends a second copy of the same day — so it is composed from the grain itself.
+        for r in rows:
+            r["id"] = ":".join(str(r.get(k) or "") for k in
+                               (f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
+        fields = ["id"] + INSIGHT_FIELDS
+        _ensure(con, INSIGHTS_TABLE, fields, rows)
+        n = _upsert(con, INSIGHTS_TABLE, fields, rows)
+        total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
+        report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
+        log(f"  {INSIGHTS_TABLE:<20} pulled {n:>6}   mirror total {total:>6}"
+            + ("   !! PAGE CAP HIT" if capped else ""))
+    con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
+                ["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
+                 sum(t["in_mirror"] for t in report["tables"].values()),
+                 time.strftime("%Y-%m-%d %H:%M:%S")])
+    return report
+def status(tenant_key="royal-imports"):
+    """What is in the mirror right now, per table. Never fetches."""
+    path = datastore.path_for(tenant_key)
+    if Path(datastore.DB_PATH) != Path(path):
+        datastore.use_path(path)
+    out = {}
+    con = datastore.connect()
+    for table in list(SPECS) + [INSIGHTS_TABLE]:
+        try:
+            out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
+        except Exception:
+            out[table] = None                                 # table absent = never synced
+    return out
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
+    ap.add_argument("--sync", action="store_true")
+    ap.add_argument("--status", action="store_true")
+    ap.add_argument("--tenant", default="royal-imports")
+    ap.add_argument("--no-insights", action="store_true")
+    ap.add_argument("--insights-days", type=int, default=None,
+                    help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
+    a = ap.parse_args(argv)
+    if a.status:
+        for k, v in status(a.tenant).items():
+            print(f"  {k:<20} {'(never synced)' if v is None else v}")
+        return 0
+    if not a.sync:
+        ap.print_help()
+        return 2
+    rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
+    for p in rep["problems"]:
+        print("  PROBLEM:", p)
+    print(f"  accounts: {len(rep['accounts'])}   tables: {len(rep['tables'])}")
+    return 1 if rep["problems"] else 0
+if __name__ == "__main__":
+    sys.exit(main())

platform/model/metrics/sales.yml CHANGED Viewed

@@ -1,149 +1,149 @@
-# Metrics: sales — the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
-# metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
-# Fields per metric:
-#   key/label/description — identity + the human definition (visibility = trust)
-#   agg + field           — sum | count_distinct over the topic's entity
-#   agg: ratio            — numerator/denominator are metric KEYS (resolved recursively)
-#   agg: derived + expr   — arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
-#   format                — usd | int | pct (rendering hint for surfaces)
-#   ai_context            — what a small model must know to use the metric correctly
-#   validate              — the INDEPENDENT Odoo cross-check contract (named method implemented in
-#                           harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
-#   empty                 — W37 C1's EMPTY-WINDOW FAMILY. See below; a metric an ENTITY topic
-#                           offers as a lookback column MUST declare one.
-#
-# ⛔⛔ `empty:` — WHAT A ROW WITH NO ACTIVITY IN THE WINDOW RENDERS AS (wave 37, contract C1).
-# Measured and load-bearing: only 1,646 of 5,836 active products sold in the last 90 days, so a
-# per-SKU lookback metric has NO GROUP for 72% of the catalogue. Get the default wrong and every
-# product grid reads as broken. Two values, and the difference is whether the blank cell would be
-# a TRUE STATEMENT:
-#   empty: zero    ADDITIVE — units, revenue, margin $, COGS. "It sold nothing" is a real
-#                  measurement, so 0 is the honest cell and a blank would hide a fact.
-#   empty: blank   RATIO / DERIVED-FROM-A-RATIO — GM %, ASP. A 0% margin on zero sales is a
-#                  FALSE statement, not a missing one. ⛔ AND THE GUARD IS THE DENOMINATOR, NOT
-#                  THE MISSING GROUP: `semantic._post_compute` returns 0.0 for `num/0`, so a SKU
-#                  that DID sell at $0 would print "0.0%" with a group behind it. The resolver
-#                  blanks on a zero denominator, which is the only reading that is never a lie.
-# ⚠ A metric with no `empty:` is REFUSED by `entity_measures()` rather than defaulted — a
-# defaulted family is a guess about truth, and C1 says a metric that cannot say which family it
-# is in does not ship.
-topic: sales_lines
-metrics:
-  - key: revenue
-    label: Revenue
-    agg: sum
-    field: price_subtotal
-    format: usd
-    empty: zero
-    description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
-    ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
-    validate:
-      method: order_level_revenue
-      note: "Σ line price_subtotal must equal Σ parent-order amount_untaxed under the same scope, to the cent (line vs order basis — the built-in cross-check)."
-  - key: units
-    label: Units sold
-    agg: sum
-    field: product_uom_qty
-    format: int
-    empty: zero
-    description: "Total quantity across confirmed wholesale order lines."
-    ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
-  - key: margin
-    label: Gross margin $
-    agg: sum
-    field: margin
-    format: usd
-    empty: zero
-    description: "Line revenue minus line cost (Odoo Margin module), summed."
-    ai_context: "margin is read_group-aggregatable (Margin module installed). COGS = revenue - margin. purchase_price is per-UNIT cost — never sum it as a total."
-  - key: cogs
-    label: COGS
-    agg: derived
-    expr: "revenue - margin"
-    format: usd
-    empty: zero
-    description: "Cost of goods sold, derived: revenue minus gross margin."
-    ai_context: "Derived, not pulled — Odoo carries cost on lines as margin; COGS is the difference."
-  - key: margin_pct
-    label: Gross margin %
-    agg: ratio
-    numerator: margin
-    denominator: revenue
-    format: pct
-    empty: blank
-    description: "Gross margin as a share of revenue."
-    ai_context: "Compare across BUs/categories at the same scope only. ⚠ TWO ZERO-REVENUE BEHAVIOURS, deliberately: the scalar/analyst path returns 0 (semantic._post_compute's guard), while an ENTITY LOOKBACK COLUMN renders BLANK (empty: blank) — on a grid, a printed 0.0% beside 5,836 products would assert a margin nobody measured."
-  # ⭐ W37-T10 — ASP, the fifth SHIP-FIRST per-SKU metric (proto/P3). Blended $18.76 over 1,646
-  # SKUs in the 90 days to 2026-08-19. A RATIO of two same-topic base measures, so it survives a
-  # GROUPED store_query (only a CROSS-TOPIC component is refused — that is what stops `aov`,
-  # whose denominator `orders` lives on sales_orders).
-  # ⚠ UNITS ARE AS-ORDERED, mixed UoM. `units` says so and this inherits it: a SKU sold in cases
-  # and in singles has an ASP blended across both, which is the true average selling price of a
-  # line unit and NOT a per-piece price.
-  - key: asp
-    label: Average selling price
-    agg: ratio
-    numerator: revenue
-    denominator: units
-    format: usd
-    empty: blank
-    description: "Revenue per unit sold — the blended average selling price."
-    ai_context: "revenue ÷ units at identical scope. Mixed units of measure are summed as ordered quantity, so this is per ordered unit, not per piece. Blank when nothing sold: an ASP of $0 on zero units is a false statement, not a missing one."
-  - key: orders
-    label: Orders
-    topic: sales_orders
-    agg: count
-    format: int
-    description: "Confirmed wholesale orders in the window (order-header count — what the scorecards show)."
-    ai_context: "Order-level count; slightly higher than distinct-orders-from-lines because a few confirmed orders carry zero lines (a data-health artifact the reconciliation contract counts exactly)."
-    validate:
-      method: order_count
-      note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
-  - key: customers
-    label: Active customers
-    agg: count_distinct
-    field: order_partner_id
-    format: int
-    empty: zero
-    description: "Distinct customers with at least one confirmed wholesale order line in the window."
-    ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
-  - key: aov
-    label: Average order value
-    agg: ratio
-    numerator: revenue
-    denominator: orders
-    format: usd
-    description: "Revenue per distinct order."
-    ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
-  # ⭐ Wave 21 R2 — the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
-  # not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
-  # invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
-  # `live_domain` filters the live path — BOTH or store_parity compares two different questions.
-  - key: revenue_invoiced
-    label: Sales — fully invoiced
-    agg: sum
-    field: price_subtotal
-    store_filter_sql: "o.invoice_status = 'invoiced'"
-    live_domain: [["order_id.invoice_status", "=", "invoiced"]]
-    format: usd
-    description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
-    ai_context: "Same scope as revenue, narrowed by the ORDER-level fully-invoiced flag. This is NOT posted-invoice-line revenue: a partially invoiced order is excluded entirely until Odoo flips the flag. Reconciled store-vs-live per BU by store_parity."
-  - key: orders_invoiced
-    label: Orders — fully invoiced
-    topic: sales_orders
-    agg: count
-    store_filter_sql: "o.invoice_status = 'invoiced'"
-    live_domain: [["invoice_status", "=", "invoiced"]]
-    format: int
-    description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
-    ai_context: "Order-header count under the orders scope plus the fully-invoiced flag; partially invoiced and not-yet-invoiced orders are excluded. Reconciled store-vs-live per BU by store_parity."

+# Metrics: sales — the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
+# metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
+# Fields per metric:
+#   key/label/description — identity + the human definition (visibility = trust)
+#   agg + field           — sum | count_distinct over the topic's entity
+#   agg: ratio            — numerator/denominator are metric KEYS (resolved recursively)
+#   agg: derived + expr   — arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
+#   format                — usd | int | pct (rendering hint for surfaces)
+#   ai_context            — what a small model must know to use the metric correctly
+#   validate              — the INDEPENDENT Odoo cross-check contract (named method implemented in
+#                           harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
+#   empty                 — W37 C1's EMPTY-WINDOW FAMILY. See below; a metric an ENTITY topic
+#                           offers as a lookback column MUST declare one.
+#
+# ⛔⛔ `empty:` — WHAT A ROW WITH NO ACTIVITY IN THE WINDOW RENDERS AS (wave 37, contract C1).
+# Measured and load-bearing: only 1,646 of 5,836 active products sold in the last 90 days, so a
+# per-SKU lookback metric has NO GROUP for 72% of the catalogue. Get the default wrong and every
+# product grid reads as broken. Two values, and the difference is whether the blank cell would be
+# a TRUE STATEMENT:
+#   empty: zero    ADDITIVE — units, revenue, margin $, COGS. "It sold nothing" is a real
+#                  measurement, so 0 is the honest cell and a blank would hide a fact.
+#   empty: blank   RATIO / DERIVED-FROM-A-RATIO — GM %, ASP. A 0% margin on zero sales is a
+#                  FALSE statement, not a missing one. ⛔ AND THE GUARD IS THE DENOMINATOR, NOT
+#                  THE MISSING GROUP: `semantic._post_compute` returns 0.0 for `num/0`, so a SKU
+#                  that DID sell at $0 would print "0.0%" with a group behind it. The resolver
+#                  blanks on a zero denominator, which is the only reading that is never a lie.
+# ⚠ A metric with no `empty:` is REFUSED by `entity_measures()` rather than defaulted — a
+# defaulted family is a guess about truth, and C1 says a metric that cannot say which family it
+# is in does not ship.
+topic: sales_lines
+metrics:
+  - key: revenue
+    label: Revenue
+    agg: sum
+    field: price_subtotal
+    format: usd
+    empty: zero
+    description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
+    ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
+    validate:
+      method: order_level_revenue
+      note: "Σ line price_subtotal must equal Σ parent-order amount_untaxed under the same scope, to the cent (line vs order basis — the built-in cross-check)."
+  - key: units
+    label: Units sold
+    agg: sum
+    field: product_uom_qty
+    format: int
+    empty: zero
+    description: "Total quantity across confirmed wholesale order lines."
+    ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
+  - key: margin
+    label: Gross margin $
+    agg: sum
+    field: margin
+    format: usd
+    empty: zero
+    description: "Line revenue minus line cost (Odoo Margin module), summed."
+    ai_context: "margin is read_group-aggregatable (Margin module installed). COGS = revenue - margin. purchase_price is per-UNIT cost — never sum it as a total."
+  - key: cogs
+    label: COGS
+    agg: derived
+    expr: "revenue - margin"
+    format: usd
+    empty: zero
+    description: "Cost of goods sold, derived: revenue minus gross margin."
+    ai_context: "Derived, not pulled — Odoo carries cost on lines as margin; COGS is the difference."
+  - key: margin_pct
+    label: Gross margin %
+    agg: ratio
+    numerator: margin
+    denominator: revenue
+    format: pct
+    empty: blank
+    description: "Gross margin as a share of revenue."
+    ai_context: "Compare across BUs/categories at the same scope only. ⚠ TWO ZERO-REVENUE BEHAVIOURS, deliberately: the scalar/analyst path returns 0 (semantic._post_compute's guard), while an ENTITY LOOKBACK COLUMN renders BLANK (empty: blank) — on a grid, a printed 0.0% beside 5,836 products would assert a margin nobody measured."
+  # ⭐ W37-T10 — ASP, the fifth SHIP-FIRST per-SKU metric (proto/P3). Blended $18.76 over 1,646
+  # SKUs in the 90 days to 2026-08-19. A RATIO of two same-topic base measures, so it survives a
+  # GROUPED store_query (only a CROSS-TOPIC component is refused — that is what stops `aov`,
+  # whose denominator `orders` lives on sales_orders).
+  # ⚠ UNITS ARE AS-ORDERED, mixed UoM. `units` says so and this inherits it: a SKU sold in cases
+  # and in singles has an ASP blended across both, which is the true average selling price of a
+  # line unit and NOT a per-piece price.
+  - key: asp
+    label: Average selling price
+    agg: ratio
+    numerator: revenue
+    denominator: units
+    format: usd
+    empty: blank
+    description: "Revenue per unit sold — the blended average selling price."
+    ai_context: "revenue ÷ units at identical scope. Mixed units of measure are summed as ordered quantity, so this is per ordered unit, not per piece. Blank when nothing sold: an ASP of $0 on zero units is a false statement, not a missing one."
+  - key: orders
+    label: Orders
+    topic: sales_orders
+    agg: count
+    format: int
+    description: "Confirmed wholesale orders in the window (order-header count — what the scorecards show)."
+    ai_context: "Order-level count; slightly higher than distinct-orders-from-lines because a few confirmed orders carry zero lines (a data-health artifact the reconciliation contract counts exactly)."
+    validate:
+      method: order_count
+      note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
+  - key: customers
+    label: Active customers
+    agg: count_distinct
+    field: order_partner_id
+    format: int
+    empty: zero
+    description: "Distinct customers with at least one confirmed wholesale order line in the window."
+    ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
+  - key: aov
+    label: Average order value
+    agg: ratio
+    numerator: revenue
+    denominator: orders
+    format: usd
+    description: "Revenue per distinct order."
+    ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
+  # ⭐ Wave 21 R2 — the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
+  # not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
+  # invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
+  # `live_domain` filters the live path — BOTH or store_parity compares two different questions.
+  - key: revenue_invoiced
+    label: Sales — fully invoiced
+    agg: sum
+    field: price_subtotal
+    store_filter_sql: "o.invoice_status = 'invoiced'"
+    live_domain: [["order_id.invoice_status", "=", "invoiced"]]
+    format: usd
+    description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
+    ai_context: "Same scope as revenue, narrowed by the ORDER-level fully-invoiced flag. This is NOT posted-invoice-line revenue: a partially invoiced order is excluded entirely until Odoo flips the flag. Reconciled store-vs-live per BU by store_parity."
+  - key: orders_invoiced
+    label: Orders — fully invoiced
+    topic: sales_orders
+    agg: count
+    store_filter_sql: "o.invoice_status = 'invoiced'"
+    live_domain: [["invoice_status", "=", "invoiced"]]
+    format: int
+    description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
+    ai_context: "Order-header count under the orders scope plus the fully-invoiced flag; partially invoiced and not-yet-invoiced orders are excluded. Reconciled store-vs-live per BU by store_parity."

platform/model/topics/odoo_accounts.yml CHANGED Viewed

@@ -1,60 +1,60 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_accounts
-label: "Odoo GL accounts"
-entity: account.account
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_accounts
-subject: "odoo:account.account"
-grain: "one row per GL account in the chart of accounts"
-scope:
-  population: "every account.account record (192 measured)"
-store:
-  table: account_account
-  alias: a
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-  dims:
-    account_type: {label: "Account type"}
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: account_code
-    label: "Code"
-    type: text
-    kind: data
-  - key: account_name
-    label: "Account"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `account.account` id. Also this row's id."
-  - key: account_type
-    label: "Type"
-    type: select
-    kind: data
-  - key: is_expense
-    label: "Expense account"
-    type: checkbox
-    kind: data
-    means: "Ticked for the expense family - the same predicate the semantic layer's gl_lines topic uses, so this column and that topic cannot disagree."
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-ai_context: >
-  The chart of accounts — the registry gl_lines posts against.
-  Use it to resolve an account code to a name or a type.
-  ⚠ `is_expense` is a DERIVED boolean standing in for Odoo's five-value `internal_group` (asset/liability/equity/income/expense), which the mirror does not yet carry.

+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_accounts
+label: "Odoo GL accounts"
+entity: account.account
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_accounts
+subject: "odoo:account.account"
+grain: "one row per GL account in the chart of accounts"
+scope:
+  population: "every account.account record (192 measured)"
+store:
+  table: account_account
+  alias: a
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+  dims:
+    account_type: {label: "Account type"}
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: account_code
+    label: "Code"
+    type: text
+    kind: data
+  - key: account_name
+    label: "Account"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `account.account` id. Also this row's id."
+  - key: account_type
+    label: "Type"
+    type: select
+    kind: data
+  - key: is_expense
+    label: "Expense account"
+    type: checkbox
+    kind: data
+    means: "Ticked for the expense family - the same predicate the semantic layer's gl_lines topic uses, so this column and that topic cannot disagree."
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+ai_context: >
+  The chart of accounts — the registry gl_lines posts against.
+  Use it to resolve an account code to a name or a type.
+  ⚠ `is_expense` is a DERIVED boolean standing in for Odoo's five-value `internal_group` (asset/liability/equity/income/expense), which the mirror does not yet carry.

platform/model/topics/odoo_agents.yml CHANGED Viewed

@@ -1,91 +1,91 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_agents
-label: "Odoo agents"
-entity: res.partner
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_agents
-subject: "odoo:res.partner.agent"
-grain: "one row per sales agent"
-scope:
-  population: "a UNION of two disagreeing sources — partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
-  why_union: "measured 2026-08-09: 16 carry commission lines, 17 carry the flag, and the union is 19 — either source alone silently drops real agents"
-store:
-  table: res_partner
-  alias: p
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-# ⭐⭐ W37-T12 / owner item 4 (R1) — THE LOOKBACK-MEASURE BINDING, the agent half of
-# *"It should apply to Odoo agents database as well."* Same contract as
-# `odoo_products.yml`: a FACT topic, and the dim of that topic which carries THIS
-# entity's identity.
-#
-# ⛔⛔ WHICH AGENT SOURCE, STATED — because there are THREE in this Odoo and they name
-# DIFFERENT PEOPLE (`proto/P3-metric-catalog.md`: 9 agents carry route-1 revenue, 12
-# carry commission lines, 17 carry the flag). This binds ROUTE 1, the CUSTOMER-MASTER
-# BOOK: `sales_lines.agent` is `rp.agent_id`, the customer's assigned agent, so every
-# order of that customer counts toward their agent. That is "whose book is this" and it
-# is the right question for a column on the AGENT REGISTRY.
-# ⚠ It is NOT commission. `account.invoice.line.agent` (topic `commission_lines`) is the
-# per-INVOICE-LINE credited agent and answers a different question; `sales_lines.yml`'s
-# own `agent` dim comment carries the full disagreement and says never to "fix" one by
-# reading the other.
-#
-# ⭐ THE JOIN NEEDS NO NEW DIM, unlike the product side. `sales_lines.agent` declares a
-# `name_col`, so `store_query` emits `agent_id` — which IS `res.partner.id`, which IS
-# this grid's `odoo_id` identity. Product needed `product_code` because its grid keys on
-# `default_code`; this one already keys on the same integer the fact topic groups by.
-measures:
-  source: sales_lines
-  dim: agent
-  keys: [revenue, units, margin, cogs, margin_pct, asp, customers]
-  not_yet:
-    - key: orders / aov
-      cause: "`orders` lives on topic `sales_orders`, so under a `group_by` it is a CROSS-TOPIC measure and `semantic.store_query` refuses it (scalar-only). `aov` inherits the refusal through its denominator"
-      fix: "add an ORDER-COUNT metric to `sales_lines` itself — `count_distinct` over `l.order_id` — which answers the same question at this grain in one pass"
-    - key: commission_amount
-      cause: "the commission basis lives on `account.invoice.line.agent` (topic `commission_lines`), a different topic AND a different grain; `invoice_lines` deduplicates to at most one agent per line"
-      fix: "bind a SECOND measures block per source once the contract allows more than one, and label the columns so the two routes can never be read as the same number"
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: agent
-    label: "Agent"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `res.partner` id. Also this row's id."
-  - key: agent_id
-    label: "Odoo agent id"
-    type: int
-    kind: data
-  - key: flagged
-    label: "Flagged in Odoo"
-    type: checkbox
-    kind: data
-    means: "Ticked = `res.partner.agent` is set. Unticked agents were found by their commission lines instead - both are real, which is why this table is the union of the two."
-  - key: commissioned
-    label: "Has commission lines"
-    type: checkbox
-    kind: data
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-ai_context: >
-  The sales-agent registry.
-  `flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
-  For an agent's BOOK use sales_lines/commission_lines with the agent dim.

+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_agents
+label: "Odoo agents"
+entity: res.partner
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_agents
+subject: "odoo:res.partner.agent"
+grain: "one row per sales agent"
+scope:
+  population: "a UNION of two disagreeing sources — partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
+  why_union: "measured 2026-08-09: 16 carry commission lines, 17 carry the flag, and the union is 19 — either source alone silently drops real agents"
+store:
+  table: res_partner
+  alias: p
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+# ⭐⭐ W37-T12 / owner item 4 (R1) — THE LOOKBACK-MEASURE BINDING, the agent half of
+# *"It should apply to Odoo agents database as well."* Same contract as
+# `odoo_products.yml`: a FACT topic, and the dim of that topic which carries THIS
+# entity's identity.
+#
+# ⛔⛔ WHICH AGENT SOURCE, STATED — because there are THREE in this Odoo and they name
+# DIFFERENT PEOPLE (`proto/P3-metric-catalog.md`: 9 agents carry route-1 revenue, 12
+# carry commission lines, 17 carry the flag). This binds ROUTE 1, the CUSTOMER-MASTER
+# BOOK: `sales_lines.agent` is `rp.agent_id`, the customer's assigned agent, so every
+# order of that customer counts toward their agent. That is "whose book is this" and it
+# is the right question for a column on the AGENT REGISTRY.
+# ⚠ It is NOT commission. `account.invoice.line.agent` (topic `commission_lines`) is the
+# per-INVOICE-LINE credited agent and answers a different question; `sales_lines.yml`'s
+# own `agent` dim comment carries the full disagreement and says never to "fix" one by
+# reading the other.
+#
+# ⭐ THE JOIN NEEDS NO NEW DIM, unlike the product side. `sales_lines.agent` declares a
+# `name_col`, so `store_query` emits `agent_id` — which IS `res.partner.id`, which IS
+# this grid's `odoo_id` identity. Product needed `product_code` because its grid keys on
+# `default_code`; this one already keys on the same integer the fact topic groups by.
+measures:
+  source: sales_lines
+  dim: agent
+  keys: [revenue, units, margin, cogs, margin_pct, asp, customers]
+  not_yet:
+    - key: orders / aov
+      cause: "`orders` lives on topic `sales_orders`, so under a `group_by` it is a CROSS-TOPIC measure and `semantic.store_query` refuses it (scalar-only). `aov` inherits the refusal through its denominator"
+      fix: "add an ORDER-COUNT metric to `sales_lines` itself — `count_distinct` over `l.order_id` — which answers the same question at this grain in one pass"
+    - key: commission_amount
+      cause: "the commission basis lives on `account.invoice.line.agent` (topic `commission_lines`), a different topic AND a different grain; `invoice_lines` deduplicates to at most one agent per line"
+      fix: "bind a SECOND measures block per source once the contract allows more than one, and label the columns so the two routes can never be read as the same number"
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: agent
+    label: "Agent"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `res.partner` id. Also this row's id."
+  - key: agent_id
+    label: "Odoo agent id"
+    type: int
+    kind: data
+  - key: flagged
+    label: "Flagged in Odoo"
+    type: checkbox
+    kind: data
+    means: "Ticked = `res.partner.agent` is set. Unticked agents were found by their commission lines instead - both are real, which is why this table is the union of the two."
+  - key: commissioned
+    label: "Has commission lines"
+    type: checkbox
+    kind: data
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+ai_context: >
+  The sales-agent registry.
+  `flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
+  For an agent's BOOK use sales_lines/commission_lines with the agent dim.

platform/model/topics/odoo_bills.yml CHANGED Viewed

@@ -1,86 +1,86 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_bills
-label: "Odoo vendor bills"
-entity: account.move
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_bills
-subject: "odoo:account.move.vendor"
-grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
-scope:
-  population: "move_type in (in_invoice, in_refund) AND state = posted"
-  signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
-store:
-  table: account_move
-  alias: m
-  date_col: "m.invoice_date"
-  dims:
-    vendor: {label: "Vendor"}
-    payment_state: {label: "Payment state"}
-    move_type: {label: "Document type"}
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: bill_no
-    label: "Bill"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `account.move` id. Also this row's id."
-  - key: vendor
-    label: "Vendor"
-    type: text
-    kind: data
-  - key: vendor_id
-    label: "Odoo vendor id"
-    type: int
-    kind: data
-  - key: invoice_date
-    label: "Bill date"
-    type: date
-    kind: data
-  - key: due_date
-    label: "Due date"
-    type: date
-    kind: data
-  - key: amount_untaxed
-    label: "Billed $"
-    type: currency
-    kind: data
-  - key: residual
-    label: "Outstanding $"
-    type: currency
-    kind: data
-  - key: payment_state
-    label: "Payment state"
-    type: select
-    kind: data
-  - key: move_type
-    label: "Document"
-    type: select
-    kind: data
-  - key: vendor_link
-    label: "Vendor record"
-    type: link
-    kind: link
-    to_grid: ut_odoo_vendors
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-ai_context: >
-  Vendor bills at DOCUMENT grain — the payables side of account_move.
-  Use it for AP questions.
-  ⚠ The census found `ref` (the VENDOR's own invoice number), `journal_id` and `currency_id` populated in Odoo and absent from the mirror, so they cannot be answered from here yet.

+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_bills
+label: "Odoo vendor bills"
+entity: account.move
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_bills
+subject: "odoo:account.move.vendor"
+grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
+scope:
+  population: "move_type in (in_invoice, in_refund) AND state = posted"
+  signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
+store:
+  table: account_move
+  alias: m
+  date_col: "m.invoice_date"
+  dims:
+    vendor: {label: "Vendor"}
+    payment_state: {label: "Payment state"}
+    move_type: {label: "Document type"}
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: bill_no
+    label: "Bill"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `account.move` id. Also this row's id."
+  - key: vendor
+    label: "Vendor"
+    type: text
+    kind: data
+  - key: vendor_id
+    label: "Odoo vendor id"
+    type: int
+    kind: data
+  - key: invoice_date
+    label: "Bill date"
+    type: date
+    kind: data
+  - key: due_date
+    label: "Due date"
+    type: date
+    kind: data
+  - key: amount_untaxed
+    label: "Billed $"
+    type: currency
+    kind: data
+  - key: residual
+    label: "Outstanding $"
+    type: currency
+    kind: data
+  - key: payment_state
+    label: "Payment state"
+    type: select
+    kind: data
+  - key: move_type
+    label: "Document"
+    type: select
+    kind: data
+  - key: vendor_link
+    label: "Vendor record"
+    type: link
+    kind: link
+    to_grid: ut_odoo_vendors
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+ai_context: >
+  Vendor bills at DOCUMENT grain — the payables side of account_move.
+  Use it for AP questions.
+  ⚠ The census found `ref` (the VENDOR's own invoice number), `journal_id` and `currency_id` populated in Odoo and absent from the mirror, so they cannot be answered from here yet.

platform/model/topics/odoo_invoices.yml CHANGED Viewed

@@ -1,98 +1,98 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_invoices
-label: "Odoo invoices"
-entity: account.move
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_invoices
-subject: "odoo:account.move.customer"
-grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
-scope:
-  population: "move_type in (out_invoice, out_refund) AND state = posted"
-  signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
-store:
-  table: account_move
-  alias: m
-  date_col: "m.invoice_date"
-  dims:
-    customer: {label: "Customer"}
-    payment_state: {label: "Payment state"}
-    move_type: {label: "Document type"}
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: invoice_no
-    label: "Invoice"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `account.move` id. Also this row's id."
-  - key: customer
-    label: "Customer"
-    type: text
-    kind: data
-  - key: partner_id
-    label: "Odoo partner id"
-    type: int
-    kind: data
-  - key: invoice_date
-    label: "Invoice date"
-    type: date
-    kind: data
-  - key: due_date
-    label: "Due date"
-    type: date
-    kind: data
-  - key: residual
-    label: "Outstanding $"
-    type: currency
-    kind: data
-    means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
-  - key: amount_untaxed
-    label: "Invoiced $"
-    type: currency
-    kind: data
-  - key: payment_state
-    label: "Payment state"
-    type: select
-    kind: data
-  - key: move_type
-    label: "Document"
-    type: select
-    kind: data
-  - key: wholesale_scope
-    label: "In wholesale scope"
-    type: checkbox
-    kind: data
-    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
-  - key: origin_order
-    label: "Source order"
-    type: text
-    kind: data
-    means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
-  - key: order_link
-    label: "Order record"
-    type: link
-    kind: link
-    to_grid: ut_odoo_orders
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-ai_context: >
-  Customer invoices at DOCUMENT grain — one row per invoice, not per line.
-  Use it for AR questions: what is open, what is overdue, what was invoiced.
-  For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
-  `origin_order` is the single stored key that joins an invoice back to the order it was raised from.

+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_invoices
+label: "Odoo invoices"
+entity: account.move
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_invoices
+subject: "odoo:account.move.customer"
+grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
+scope:
+  population: "move_type in (out_invoice, out_refund) AND state = posted"
+  signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
+store:
+  table: account_move
+  alias: m
+  date_col: "m.invoice_date"
+  dims:
+    customer: {label: "Customer"}
+    payment_state: {label: "Payment state"}
+    move_type: {label: "Document type"}
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: invoice_no
+    label: "Invoice"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `account.move` id. Also this row's id."
+  - key: customer
+    label: "Customer"
+    type: text
+    kind: data
+  - key: partner_id
+    label: "Odoo partner id"
+    type: int
+    kind: data
+  - key: invoice_date
+    label: "Invoice date"
+    type: date
+    kind: data
+  - key: due_date
+    label: "Due date"
+    type: date
+    kind: data
+  - key: residual
+    label: "Outstanding $"
+    type: currency
+    kind: data
+    means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
+  - key: amount_untaxed
+    label: "Invoiced $"
+    type: currency
+    kind: data
+  - key: payment_state
+    label: "Payment state"
+    type: select
+    kind: data
+  - key: move_type
+    label: "Document"
+    type: select
+    kind: data
+  - key: wholesale_scope
+    label: "In wholesale scope"
+    type: checkbox
+    kind: data
+    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
+  - key: origin_order
+    label: "Source order"
+    type: text
+    kind: data
+    means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
+  - key: order_link
+    label: "Order record"
+    type: link
+    kind: link
+    to_grid: ut_odoo_orders
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+ai_context: >
+  Customer invoices at DOCUMENT grain — one row per invoice, not per line.
+  Use it for AR questions: what is open, what is overdue, what was invoiced.
+  For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
+  `origin_order` is the single stored key that joins an invoice back to the order it was raised from.

platform/model/topics/odoo_orders.yml CHANGED Viewed

@@ -1,87 +1,87 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_orders
-label: "Odoo orders"
-entity: sale.order
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_orders
-subject: "odoo:sale.order"
-grain: "one row per confirmed sales order (document grain)"
-scope:
-  population: "state in (sale, done) — quotations and cancellations excluded"
-  vs_sales_orders: "⚠ DISTINCT from the `sales_orders` topic: that one is the wholesale-scoped analytical view (teams 5/6, house accounts excluded); THIS one is the registry a person opens as a grid, and carries the row set the app shows"
-store:
-  table: sale_order
-  alias: o
-  date_col: "o.date_order"
-  dims:
-    customer: {label: "Customer"}
-    team: {label: "Business unit"}
-    state: {label: "State"}
-    invoice_status: {label: "Invoice status"}
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: order_no
-    label: "Order"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `sale.order` id. Also this row's id."
-  - key: customer
-    label: "Customer"
-    type: text
-    kind: data
-  - key: partner_id
-    label: "Odoo partner id"
-    type: int
-    kind: data
-  - key: order_date
-    label: "Order date"
-    type: date
-    kind: data
-  - key: amount_untaxed
-    label: "Order $"
-    type: currency
-    kind: data
-  - key: team
-    label: "Business unit"
-    type: select
-    kind: data
-  - key: state
-    label: "State"
-    type: select
-    kind: data
-  - key: invoice_status
-    label: "Invoice status"
-    type: select
-    kind: data
-  - key: wholesale_scope
-    label: "In wholesale scope"
-    type: checkbox
-    kind: data
-    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
-  - key: invoices
-    label: "Invoices"
-    type: link
-    kind: link
-    to_grid: ut_odoo_invoices
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-ai_context: >
-  Sales orders at DOCUMENT grain, as the app's grid shows them.
-  ⛔ If you are asked for revenue, prefer `sales_lines` (line grain, wholesale scope) or `sales_orders` — this topic exists to describe the ORDER RECORD a person can open, and its scope is the grid's, not the analytical model's.

+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_orders
+label: "Odoo orders"
+entity: sale.order
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_orders
+subject: "odoo:sale.order"
+grain: "one row per confirmed sales order (document grain)"
+scope:
+  population: "state in (sale, done) — quotations and cancellations excluded"
+  vs_sales_orders: "⚠ DISTINCT from the `sales_orders` topic: that one is the wholesale-scoped analytical view (teams 5/6, house accounts excluded); THIS one is the registry a person opens as a grid, and carries the row set the app shows"
+store:
+  table: sale_order
+  alias: o
+  date_col: "o.date_order"
+  dims:
+    customer: {label: "Customer"}
+    team: {label: "Business unit"}
+    state: {label: "State"}
+    invoice_status: {label: "Invoice status"}
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: order_no
+    label: "Order"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `sale.order` id. Also this row's id."
+  - key: customer
+    label: "Customer"
+    type: text
+    kind: data
+  - key: partner_id
+    label: "Odoo partner id"
+    type: int
+    kind: data
+  - key: order_date
+    label: "Order date"
+    type: date
+    kind: data
+  - key: amount_untaxed
+    label: "Order $"
+    type: currency
+    kind: data
+  - key: team
+    label: "Business unit"
+    type: select
+    kind: data
+  - key: state
+    label: "State"
+    type: select
+    kind: data
+  - key: invoice_status
+    label: "Invoice status"
+    type: select
+    kind: data
+  - key: wholesale_scope
+    label: "In wholesale scope"
+    type: checkbox
+    kind: data
+    means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
+  - key: invoices
+    label: "Invoices"
+    type: link
+    kind: link
+    to_grid: ut_odoo_invoices
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+ai_context: >
+  Sales orders at DOCUMENT grain, as the app's grid shows them.
+  ⛔ If you are asked for revenue, prefer `sales_lines` (line grain, wholesale scope) or `sales_orders` — this topic exists to describe the ORDER RECORD a person can open, and its scope is the grid's, not the analytical model's.

platform/model/topics/odoo_products.yml CHANGED Viewed

@@ -25,7 +25,17 @@ subject: "odoo:product.product"
 grain: "one row per SKU in the active catalogue — a CATALOGUE, not a dated event stream"
 scope:
   population: "every ACTIVE product, sold or not (measured 5,862). Deliberately not the sales-window universe: that lands at 2,717 and hides ~2,550 SKUs that have never sold in wholesale scope"
-  identity: "the SKU code (`default_code`). ⚠ 33 active products carry NO code and are keyed `pid:<odoo product id>` instead, so every active product has exactly one row and none is dropped"
   merged: "W33-T44 retired `ut_odoo_products`, which presented this same subject on Odoo's product_id. This topic describes the SURVIVING database, `product_data`"
   no_date: "a catalogue has no date dimension; ask sales_lines for movement"
 store:
@@ -145,6 +155,11 @@ fields:
     type: text
     kind: data
     means: "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
     label: "Product"
     type: text

 grain: "one row per SKU in the active catalogue — a CATALOGUE, not a dated event stream"
 scope:
   population: "every ACTIVE product, sold or not (measured 5,862). Deliberately not the sales-window universe: that lands at 2,717 and hides ~2,550 SKUs that have never sold in wholesale scope"
+  # ⭐⭐ W41-T17 (owner instruction 25) rewrote this line. TWO IDS, and that is the honest
+  # difference from `odoo_customers`, whose own `scope.identity` can say "there is ONE id per row
+  # and no second one". Here the BUSINESS key and the ODOO key are genuinely different values, and
+  # `pid` is a CRC32 of the first, so it is neither of them and must never be offered as a join.
+  # ⛔ A CUSTOMERS->PRODUCTS EDGE JOINS ON `product_id`, never on this row's `pid` and never on the
+  # product NAME. Measured 2026-08-24 against the mirror: 5,873 active products, 33 codeless, ZERO
+  # with a null Odoo id, so the column resolves for every row the grid carries.
+  # ⚠ Which does NOT relax the `measures:` binding below. That block groups a FACT topic by its own
+  # `product_code` dim and stays code-keyed; `sales_lines` and `stock_moves` spell the identical
+  # COALESCE fallback, so the 33 codeless rows still match there on `pid:<id>` and are not lost.
+  identity: "the SKU code (`default_code`) is the BUSINESS key, and the `product_id` column (W41-T17) is the Odoo `product.product` id every Odoo document joins on. ⚠ 33 active products carry NO code and are keyed `pid:<odoo product id>` instead, so every active product has exactly one row and none is dropped; those 33 still carry a real `product_id`"
   merged: "W33-T44 retired `ut_odoo_products`, which presented this same subject on Odoo's product_id. This topic describes the SURVIVING database, `product_data`"
   no_date: "a catalogue has no date dimension; ask sales_lines for movement"
 store:
     type: text
     kind: data
     means: "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
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The Odoo product.product id, the key every Odoo document joins on. Carried on the row rather than derived, because a product's pid is a CRC32 of its SKU and the id cannot be recovered from it."
   - key: product
     label: "Product"
     type: text

platform/model/topics/odoo_vendors.yml CHANGED Viewed

@@ -1,103 +1,103 @@
-# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
-# the databases a person actually opens, not only the line and document grains.
-#
-# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
-# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
-# field row: add the column to the grid contract and re-emit, or the agent is being
-# trained on a schema the product does not have.
-key: odoo_vendors
-label: "Odoo vendors"
-entity: res.partner
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: ut_odoo_vendors
-subject: "odoo:res.partner.vendor"
-grain: "one row per partner we have posted a vendor bill to"
-scope:
-  population: "DERIVED FROM THE BILLS — a partner with no posted vendor bill has no payable history to show, so the bill is the population"
-  asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
-  overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
-store:
-  table: res_partner
-  alias: p
-  # NO date_col — a registry is not a dated event stream. Stated rather than
-  # omitted, so its absence reads as a fact and not as an unfinished file.
-  dims:
-    country: {label: "Country"}
-# key / label / type / kind, derived from the grid contract. `kind` says where the
-# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
-# from another topic; a `link` points at another database.
-fields:
-  - key: vendor
-    label: "Vendor"
-    type: text
-    kind: data
-  - key: odoo_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The `res.partner` id. Also this row's id."
-  - key: vendor_id
-    label: "Odoo vendor id"
-    type: int
-    kind: data
-  - key: country
-    label: "Country"
-    type: text
-    kind: data
-  - key: email
-    label: "Email"
-    type: text
-    kind: data
-  - key: phone
-    label: "Phone"
-    type: text
-    kind: data
-  - key: mobile
-    label: "Mobile"
-    type: text
-    kind: data
-  - key: vat
-    label: "Tax ID"
-    type: text
-    kind: data
-    means: "Odoo `vat` — the vendor's tax/VAT registration number."
-  - key: vendor_ref
-    label: "Vendor reference"
-    type: text
-    kind: data
-    means: "Odoo `res.partner.ref` — our internal reference for this vendor."
-  - key: website
-    label: "Website"
-    type: url
-    kind: data
-  - key: street
-    label: "Street"
-    type: text
-    kind: data
-  - key: street2
-    label: "Street 2"
-    type: text
-    kind: data
-  - key: city
-    label: "City"
-    type: text
-    kind: data
-  - key: zip
-    label: "ZIP"
-    type: text
-    kind: data
-  - key: bills
-    label: "Bills"
-    type: link
-    kind: link
-    to_grid: ut_odoo_bills
-  - key: refreshed
-    label: "Refreshed"
-    type: date
-    kind: data
-    means: "When this row was last reconciled against Odoo."
-ai_context: >
-  The vendor/supplier registry, with contact and tax identity (W33-T48 widened it from 5 columns to 15 after a census found 76 populated fields on the underlying partner)
-  ⚠ The contact columns are SPARSE by nature — measured 65/393 with an email, 13/393 with a tax id — so 'blank' means Odoo has no value, never that the sync failed.

+# ⭐⭐ W33-T49 (owner item 13) — an ENTITY topic: the semantic layer can finally see
+# the databases a person actually opens, not only the line and document grains.
+#
+# ⛔ THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
+# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
+# field row: add the column to the grid contract and re-emit, or the agent is being
+# trained on a schema the product does not have.
+key: odoo_vendors
+label: "Odoo vendors"
+entity: res.partner
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: ut_odoo_vendors
+subject: "odoo:res.partner.vendor"
+grain: "one row per partner we have posted a vendor bill to"
+scope:
+  population: "DERIVED FROM THE BILLS — a partner with no posted vendor bill has no payable history to show, so the bill is the population"
+  asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
+  overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
+store:
+  table: res_partner
+  alias: p
+  # NO date_col — a registry is not a dated event stream. Stated rather than
+  # omitted, so its absence reads as a fact and not as an unfinished file.
+  dims:
+    country: {label: "Country"}
+# key / label / type / kind, derived from the grid contract. `kind` says where the
+# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
+# from another topic; a `link` points at another database.
+fields:
+  - key: vendor
+    label: "Vendor"
+    type: text
+    kind: data
+  - key: odoo_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The `res.partner` id. Also this row's id."
+  - key: vendor_id
+    label: "Odoo vendor id"
+    type: int
+    kind: data
+  - key: country
+    label: "Country"
+    type: text
+    kind: data
+  - key: email
+    label: "Email"
+    type: text
+    kind: data
+  - key: phone
+    label: "Phone"
+    type: text
+    kind: data
+  - key: mobile
+    label: "Mobile"
+    type: text
+    kind: data
+  - key: vat
+    label: "Tax ID"
+    type: text
+    kind: data
+    means: "Odoo `vat` — the vendor's tax/VAT registration number."
+  - key: vendor_ref
+    label: "Vendor reference"
+    type: text
+    kind: data
+    means: "Odoo `res.partner.ref` — our internal reference for this vendor."
+  - key: website
+    label: "Website"
+    type: url
+    kind: data
+  - key: street
+    label: "Street"
+    type: text
+    kind: data
+  - key: street2
+    label: "Street 2"
+    type: text
+    kind: data
+  - key: city
+    label: "City"
+    type: text
+    kind: data
+  - key: zip
+    label: "ZIP"
+    type: text
+    kind: data
+  - key: bills
+    label: "Bills"
+    type: link
+    kind: link
+    to_grid: ut_odoo_bills
+  - key: refreshed
+    label: "Refreshed"
+    type: date
+    kind: data
+    means: "When this row was last reconciled against Odoo."
+ai_context: >
+  The vendor/supplier registry, with contact and tax identity (W33-T48 widened it from 5 columns to 15 after a census found 76 populated fields on the underlying partner)
+  ⚠ The contact columns are SPARSE by nature — measured 65/393 with an email, 13/393 with a tax id — so 'blank' means Odoo has no value, never that the sync failed.

platform/modules/agent.py CHANGED Viewed

@@ -1,385 +1,385 @@
-"""Agent module — per-agent (res.partner.agent_ids) analytics.
-An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
-module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
-with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
-trend, returns, top SKUs (with profit/order) and the FULL customer list — INCLUDING inactive
-accounts (no recent orders) so a rep sees who they've stopped selling to.
-Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
-so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
-everything else is BU-filterable via team_id.
-"""
-import sys
-import datetime as dt
-from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-import core.odoo as O
-import core.periods as P
-import modules.sales as sales_mod
-import modules.customers as cust_mod
-def options(t=None, team_id=None):
-    """Agent names with book activity — for the page/drawer picker."""
-    return cust_mod.agent_options(t, team_id)
-def _book(name):
-    """frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
-    return cust_mod.agent_partner_ids(name)
-def _rev(date_from, date_to, team_id, book):
-    return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
-                       'amount_untaxed')
-def _orders(date_from, date_to, team_id, book):
-    return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
-def _custs(date_from, date_to, team_id, book):
-    return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
-                            'partner_id')
-# ------------------------------------------------------------ period scorecard (custom dating)
-# Today / WTD / Last week / MTD / QTD / YTD — each carries its window so the UI can decompose it
-# and so "what did this agent sell this/last week" is a click, not a date-math exercise.
-_PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
-            ('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
-def _window(key, t):
-    if key == 'today':
-        return P._d(t), P._d(t)
-    if key == 'lwk':                       # the full prior Mon–Sun week
-        f, _tt = P.wtd(t)
-        start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
-        return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
-    return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
-def scorecard(name, t=None, team_id=None):
-    """Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
-    t = t or P.today()
-    book = _book(name)
-    out = []
-    for label, key in _PERIODS:
-        f, tt = _window(key, t)
-        wk = key in ('today', 'wtd', 'lwk')          # weekday-align the short windows' LY compare
-        cf, ct = P.shift_year(f, tt, weeks=wk)
-        rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
-        out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
-                    'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
-                    'orders': _orders(f, tt, team_id, book)})
-    return out
-def headline(name, date_from, date_to, team_id=None):
-    """Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
-    active customers, AOV and returns $ / return rate."""
-    book = _book(name)
-    cf, ct = P.shift_year(date_from, date_to, weeks=False)
-    rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
-    orders = _orders(date_from, date_to, team_id, book)
-    ret = sales_mod._returns_amt(date_from, date_to, book)
-    return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
-            'revenue': rev, 'revenue_ly': rev_ly,
-            'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
-            'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
-            'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
-# ------------------------------------------------------------ sales trend
-def _book_monthly_rev(book, date_from, date_to, team_id=None):
-    g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
-                     ['amount_untaxed:sum'], ['date_order:month'], lazy=False)
-    out = {}
-    for r in g:
-        ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
-        if ym:
-            out[ym] = r.get('amount_untaxed') or 0.0
-    return out
-def monthly(name, n=13, t=None, team_id=None):
-    """Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
-    t = t or P.today()
-    book = _book(name)
-    mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
-    rows = []
-    for ym, _s, _e in P.month_starts(n, t):
-        y, m = int(ym[:4]) - 1, int(ym[5:7])
-        this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
-        rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
-    return rows
-# ------------------------------------------------------------ full customer book (incl. inactive)
-def customers(name, t=None, team_id=None):
-    """EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) — those
-    show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
-    carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
-    t = t or P.today()
-    book = _book(name)
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    this = cust_mod._cust_rev(yf, yt, team_id, book)
-    last = cust_mod._cust_rev(lf, lt, team_id, book)
-    lastord = cust_mod._last_order_dates(None, None, team_id, book)   # all-time last order = recency
-    ids = list(book) if book is not None else list(set(this) | set(last))
-    attrs = cust_mod._partner_attrs(set(ids))
-    namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
-    rows = []
-    for p in ids:
-        tr = this.get(p, {}).get('rev', 0.0)
-        lr = last.get(p, {}).get('rev', 0.0)
-        a = attrs.get(p, {})
-        lo = lastord.get(p, '')
-        recency = (t - dt.date.fromisoformat(lo)).days if lo else None
-        status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
-        rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
-                     'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
-                     'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
-                     'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
-                     'agent': a.get('agent', name)})
-    rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
-    return rows
-# ------------------------------------------------------------ top SKUs (with profit/order)
-def top_skus(name, t=None, team_id=None, top=30):
-    """The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
-    t = t or P.today()
-    book = _book(name)
-    if book is not None and not book:
-        return []
-    yf, yt = P.ytd(t)
-    lex = [('order_partner_id', 'in', list(book))] if book is not None else None
-    return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
-# ------------------------------------------------------------ returns (book-scoped, consolidated)
-def returns_trend(name, n=13, t=None):
-    return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
-def returns_headline(name, t=None):
-    return sales_mod.returns_headline(t, partner_ids=_book(name))
-# ------------------------------------------------------------ all-agents rollup (the page table)
-def _returns_by_agent(t=None):
-    """{agent_name: returns$ YTD} — credit notes mapped to each customer's agent."""
-    by_p = sales_mod.returns_by_partner(t)
-    attrs = cust_mod._partner_attrs(list(by_p))
-    agg = {}
-    for pid, amt in by_p.items():
-        a = (attrs.get(pid) or {}).get('agent') or '(none)'
-        agg[a] = agg.get(a, 0.0) + amt
-    return agg
-def rollup(t=None, team_id=None):
-    """Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
-    rate. Reuses the Customers MECE agent rollup, so Σ(agents) == total YTD revenue."""
-    rows = cust_mod.by_dimension('agent', t, team_id=team_id)
-    ret = _returns_by_agent(t)
-    for r in rows:
-        r['agent'] = r['group']
-        r['returns'] = ret.get(r['group'], 0.0)
-        r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
-    return rows
-# ------------------------------------------------------------ VALIDATION
-def validate(t=None, team_id=None):
-    """Reconcile the agent rollup to Odoo. (1) Σ(agent book revenue) == total YTD revenue — the
-    rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    checks = []
-    rows = rollup(t, team_id=team_id)
-    agent_sum = sum(r['revenue'] for r in rows)
-    total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
-    checks.append({'check': 'YTD revenue: Σ(agent book) == total', 'a': round(agent_sum, 2),
-                   'b': round(total, 2), 'gap': round(agent_sum - total, 2),
-                   'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
-    # sampled agent: scorecard YTD == headline YTD for the same window
-    sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
-    if sample:
-        sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
-        hl = headline(sample, yf, yt, team_id)['revenue']
-        checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
-                       'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
-    checks.extend(validate_measures(t=t, team_id=team_id))
-    return checks
-def validate_measures(t=None, team_id=None, days=90):
-    """⭐⭐ W37-T12 — the minted PER-AGENT lookback columns, against a DIRECT Odoo aggregate.
-    ⛔ WHICH AGENT SOURCE, AND THE TICKET REQUIRES IT SAID OUT LOUD: this reconciles ROUTE 1, the
-    CUSTOMER-MASTER BOOK (`res.partner.agent_ids` -> the mirror's `res_partner.agent_id`, which is
-    `sales_lines`' `agent` dim). It is NOT the OCA commission route below — measured 2026-08-19,
-    9 agents carry route-1 revenue against 12 on commission lines and 17 carrying the flag, so the
-    two produce materially different rankings and a check that mixed them would be comparing two
-    different questions and calling the gap an error.
-    ⚠ THE ORACLE IS THE ORDER HEADER, not the mirror the columns are served from. `sale.order`
-    grouped by `partner_id`, mapped to each customer's agent CLIENT-SIDE — a different model, a
-    different grain and a different code path from `store_query`'s line-level sum, so agreement
-    between them is evidence rather than tautology.
-    ⚠ Windowed to the MIRROR'S newest order, like `product_data.validate_measures`, so the
-    residual is about EDITS to a shared period and not about orders the mirror has never seen.
-    """
-    from harness import datastore as DS
-    from harness import semantic as sem
-    t = t or P.today()
-    checks = []
-    try:
-        if not DS.ready():
-            return [{'check': 'agent lookback measures reconcile to Odoo', 'a': 'no mirror',
-                     'b': '-', 'ok': False,
-                     'detail': 'the tenant store is not readable, so this is UNPROVEN, which standing rule '
-                               '8 does not accept as green'}]
-    except Exception as e:                                             # noqa: BLE001
-        return [{'check': 'agent lookback measures reconcile to Odoo', 'a': type(e).__name__,
-                 'b': '-', 'ok': False, 'detail': str(e)[:200]}]
-    offer = sem.entity_measures('odoo_agents')
-    checks.append({'check': 'the agent measure OFFER is non-empty and every key resolves '
-                            '(owner item 4 / R1)',
-                   'a': len(offer), 'b': '>0', 'ok': bool(offer),
-                   'detail': {'keys': [m['key'] for m in offer],
-                              'refused': sem.entity_measure_refusals('odoo_agents')}})
-    if not offer:
-        return checks
-    con = DS.ro_cursor()
-    try:
-        newest = con.execute('SELECT max(date_order) FROM sale_order').fetchone()
-    finally:
-        con.close()
-    d_to = t - dt.timedelta(days=2)
-    if newest and newest[0]:
-        try:
-            d_to = min(d_to, dt.date.fromisoformat(str(newest[0])[:10]) - dt.timedelta(days=1))
-        except ValueError:
-            pass
-    d_from = d_to - dt.timedelta(days=days)
-    DF, DT = d_from.isoformat(), d_to.isoformat()
-    ours = sem.entity_measure_values('odoo_agents', ['revenue'], date_from=DF, date_to=DT,
-                                     team_id=team_id, offer=offer)
-    # THE ORACLE — order headers, grouped by customer, mapped to that customer's agent here.
-    o = O.get_odoo()
-    grp = o.read_group('sale.order', sales_mod.order_domain(DF, DT, team_id),
-                       ['partner_id', 'amount_untaxed:sum'], ['partner_id'], lazy=False)
-    pids = sorted({r['partner_id'][0] for r in grp if r.get('partner_id')})
-    agent_of = {}
-    for i in range(0, len(pids), 500):
-        for p in o.search_read('res.partner', [('id', 'in', pids[i:i + 500])],
-                               ['id', 'agent_ids']):
-            ag = (p.get('agent_ids') or [])
-            if ag:
-                agent_of[p['id']] = ag[0]          # the Customers-module convention: agent_ids[0]
-    theirs = {}
-    for r in grp:
-        if not r.get('partner_id'):
-            continue
-        a = agent_of.get(r['partner_id'][0])
-        if a is not None:
-            theirs[a] = theirs.get(a, 0.0) + r['amount_untaxed']
-    ours_tot = round(sum(c.get('revenue', 0) for c in ours.values()), 2)
-    theirs_tot = round(sum(theirs.values()), 2)
-    # ⚠ ORDER-HEADER vs LINE-SUM is a REAL basis difference (an order's untaxed total includes
-    # lines this topic's service filter drops), so the tolerance is a stated 3% rather than a
-    # cent — and the FIGURE is reported so a drift is readable instead of absorbed.
-    gap = ours_tot - theirs_tot
-    checks.append({
-        'check': 'per-agent revenue (BOOK route) vs an INDEPENDENT Odoo order-header aggregate '
-                 'mapped through res.partner.agent_ids',
-        'a': ours_tot, 'b': theirs_tot, 'gap': round(gap, 2),
-        'ok': bool(theirs_tot) and abs(gap) <= 0.03 * theirs_tot,
-        'detail': {'window': [DF, DT], 'agents_ours': len(ours), 'agents_theirs': len(theirs),
-                   'gap_pct': round(gap / theirs_tot * 100, 3) if theirs_tot else None,
-                   'route': 'customer-master book (res.partner.agent_ids), NOT the OCA '
-                            'commission table; the two name different people'}})
-    # ⛔ AND PER AGENT, because a total can agree while every row is keyed wrong — the join-key
-    # trap contract C1 names. Here the key is the `res.partner` id at both ends.
-    off_by = sorted(((abs(ours.get(a, {}).get('revenue', 0.0) - v), a)
-                     for a, v in theirs.items() if v), reverse=True)
-    bad = [(a, round(ours.get(a, {}).get('revenue', 0.0), 2), round(theirs[a], 2))
-           for d, a in off_by if d > 0.03 * theirs[a]]
-    checks.append({
-        'check': 'each agent\'s own figure ties (the C1 join-key test: a wrong key agrees in '
-                 'total and disagrees on every row)',
-        'a': len(bad), 'b': 0, 'ok': not bad,
-        'detail': {'worst': [(a, ours_v, th_v) for a, ours_v, th_v in bad[:5]],
-                   'agents_compared': len(theirs)}})
-    return checks
-# ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
-# A SECOND agent source. Everything above this line attributes by BOOK — the customer's assigned
-# agent (res.partner.agent_ids) — over confirmed SALES ORDERS. This section attributes per INVOICE
-# LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
-# commission_lines). The two disagree on purpose and answer different questions:
-#
-#   book     -> "whose customer is this / who owns the relationship"   (order basis)
-#   invoice  -> "what was actually credited to an agent on the billing" + the ONLY source that can
-#               say what is NOT allocated to an agent                   (invoice basis)
-#
-# ⚠ A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT — `res.partner.agent` is the flag.
-# "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
-# dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
-# See [[invoice-line-agent-commission]].
-_ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
-                'none': 'Not allocated'}
-def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
-    """Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
-    Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
-             'unallocated': float, 'basis': str} — or {'error': msg} when the tenant store is not
-    ready (this path is store-only; there is no live fallback that stays honest about the
-    unallocated bucket).
-    """
-    import harness.semantic as S
-    t = t or P.today()
-    yf, yt = P.ytd(t)
-    dim = 'commission_name' if include_salespeople else 'agent'
-    try:
-        by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
-                           date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
-        alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
-                              date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
-        tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
-                             team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
-    except Exception as e:                       # store not ready / model error — say so, don't fake
-        return {'error': str(e)}
-    # store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
-    # (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
-    # returns None for every row and silently renders the whole table as "no agent".
-    rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
-             'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
-    rows.sort(key=lambda r: -r['revenue'])
-    amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
-    allocated = amap.get('agent', 0.0)
-    return {
-        'by_agent': rows,
-        'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
-                       for k in ('agent', 'salesperson', 'none') if k in amap or True],
-        'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
-        'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
-        'window': (yf, yt),
-        'basis': ('invoice line · commission names incl. salespeople' if include_salespeople
-                  else 'invoice line · real agents only'),
-    }

+"""Agent module — per-agent (res.partner.agent_ids) analytics.
+An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
+module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
+with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
+trend, returns, top SKUs (with profit/order) and the FULL customer list — INCLUDING inactive
+accounts (no recent orders) so a rep sees who they've stopped selling to.
+Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
+so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
+everything else is BU-filterable via team_id.
+"""
+import sys
+import datetime as dt
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import core.odoo as O
+import core.periods as P
+import modules.sales as sales_mod
+import modules.customers as cust_mod
+def options(t=None, team_id=None):
+    """Agent names with book activity — for the page/drawer picker."""
+    return cust_mod.agent_options(t, team_id)
+def _book(name):
+    """frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
+    return cust_mod.agent_partner_ids(name)
+def _rev(date_from, date_to, team_id, book):
+    return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
+                       'amount_untaxed')
+def _orders(date_from, date_to, team_id, book):
+    return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
+def _custs(date_from, date_to, team_id, book):
+    return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
+                            'partner_id')
+# ------------------------------------------------------------ period scorecard (custom dating)
+# Today / WTD / Last week / MTD / QTD / YTD — each carries its window so the UI can decompose it
+# and so "what did this agent sell this/last week" is a click, not a date-math exercise.
+_PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
+            ('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
+def _window(key, t):
+    if key == 'today':
+        return P._d(t), P._d(t)
+    if key == 'lwk':                       # the full prior Mon–Sun week
+        f, _tt = P.wtd(t)
+        start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
+        return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
+    return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
+def scorecard(name, t=None, team_id=None):
+    """Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
+    t = t or P.today()
+    book = _book(name)
+    out = []
+    for label, key in _PERIODS:
+        f, tt = _window(key, t)
+        wk = key in ('today', 'wtd', 'lwk')          # weekday-align the short windows' LY compare
+        cf, ct = P.shift_year(f, tt, weeks=wk)
+        rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
+        out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
+                    'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
+                    'orders': _orders(f, tt, team_id, book)})
+    return out
+def headline(name, date_from, date_to, team_id=None):
+    """Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
+    active customers, AOV and returns $ / return rate."""
+    book = _book(name)
+    cf, ct = P.shift_year(date_from, date_to, weeks=False)
+    rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
+    orders = _orders(date_from, date_to, team_id, book)
+    ret = sales_mod._returns_amt(date_from, date_to, book)
+    return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
+            'revenue': rev, 'revenue_ly': rev_ly,
+            'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
+            'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
+            'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
+# ------------------------------------------------------------ sales trend
+def _book_monthly_rev(book, date_from, date_to, team_id=None):
+    g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
+                     ['amount_untaxed:sum'], ['date_order:month'], lazy=False)
+    out = {}
+    for r in g:
+        ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
+        if ym:
+            out[ym] = r.get('amount_untaxed') or 0.0
+    return out
+def monthly(name, n=13, t=None, team_id=None):
+    """Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
+    t = t or P.today()
+    book = _book(name)
+    mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
+    rows = []
+    for ym, _s, _e in P.month_starts(n, t):
+        y, m = int(ym[:4]) - 1, int(ym[5:7])
+        this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
+        rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
+    return rows
+# ------------------------------------------------------------ full customer book (incl. inactive)
+def customers(name, t=None, team_id=None):
+    """EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) — those
+    show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
+    carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
+    t = t or P.today()
+    book = _book(name)
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    this = cust_mod._cust_rev(yf, yt, team_id, book)
+    last = cust_mod._cust_rev(lf, lt, team_id, book)
+    lastord = cust_mod._last_order_dates(None, None, team_id, book)   # all-time last order = recency
+    ids = list(book) if book is not None else list(set(this) | set(last))
+    attrs = cust_mod._partner_attrs(set(ids))
+    namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
+    rows = []
+    for p in ids:
+        tr = this.get(p, {}).get('rev', 0.0)
+        lr = last.get(p, {}).get('rev', 0.0)
+        a = attrs.get(p, {})
+        lo = lastord.get(p, '')
+        recency = (t - dt.date.fromisoformat(lo)).days if lo else None
+        status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
+        rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
+                     'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
+                     'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
+                     'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
+                     'agent': a.get('agent', name)})
+    rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
+    return rows
+# ------------------------------------------------------------ top SKUs (with profit/order)
+def top_skus(name, t=None, team_id=None, top=30):
+    """The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
+    t = t or P.today()
+    book = _book(name)
+    if book is not None and not book:
+        return []
+    yf, yt = P.ytd(t)
+    lex = [('order_partner_id', 'in', list(book))] if book is not None else None
+    return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
+# ------------------------------------------------------------ returns (book-scoped, consolidated)
+def returns_trend(name, n=13, t=None):
+    return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
+def returns_headline(name, t=None):
+    return sales_mod.returns_headline(t, partner_ids=_book(name))
+# ------------------------------------------------------------ all-agents rollup (the page table)
+def _returns_by_agent(t=None):
+    """{agent_name: returns$ YTD} — credit notes mapped to each customer's agent."""
+    by_p = sales_mod.returns_by_partner(t)
+    attrs = cust_mod._partner_attrs(list(by_p))
+    agg = {}
+    for pid, amt in by_p.items():
+        a = (attrs.get(pid) or {}).get('agent') or '(none)'
+        agg[a] = agg.get(a, 0.0) + amt
+    return agg
+def rollup(t=None, team_id=None):
+    """Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
+    rate. Reuses the Customers MECE agent rollup, so Σ(agents) == total YTD revenue."""
+    rows = cust_mod.by_dimension('agent', t, team_id=team_id)
+    ret = _returns_by_agent(t)
+    for r in rows:
+        r['agent'] = r['group']
+        r['returns'] = ret.get(r['group'], 0.0)
+        r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
+    return rows
+# ------------------------------------------------------------ VALIDATION
+def validate(t=None, team_id=None):
+    """Reconcile the agent rollup to Odoo. (1) Σ(agent book revenue) == total YTD revenue — the
+    rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    checks = []
+    rows = rollup(t, team_id=team_id)
+    agent_sum = sum(r['revenue'] for r in rows)
+    total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
+    checks.append({'check': 'YTD revenue: Σ(agent book) == total', 'a': round(agent_sum, 2),
+                   'b': round(total, 2), 'gap': round(agent_sum - total, 2),
+                   'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
+    # sampled agent: scorecard YTD == headline YTD for the same window
+    sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
+    if sample:
+        sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
+        hl = headline(sample, yf, yt, team_id)['revenue']
+        checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
+                       'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
+    checks.extend(validate_measures(t=t, team_id=team_id))
+    return checks
+def validate_measures(t=None, team_id=None, days=90):
+    """⭐⭐ W37-T12 — the minted PER-AGENT lookback columns, against a DIRECT Odoo aggregate.
+    ⛔ WHICH AGENT SOURCE, AND THE TICKET REQUIRES IT SAID OUT LOUD: this reconciles ROUTE 1, the
+    CUSTOMER-MASTER BOOK (`res.partner.agent_ids` -> the mirror's `res_partner.agent_id`, which is
+    `sales_lines`' `agent` dim). It is NOT the OCA commission route below — measured 2026-08-19,
+    9 agents carry route-1 revenue against 12 on commission lines and 17 carrying the flag, so the
+    two produce materially different rankings and a check that mixed them would be comparing two
+    different questions and calling the gap an error.
+    ⚠ THE ORACLE IS THE ORDER HEADER, not the mirror the columns are served from. `sale.order`
+    grouped by `partner_id`, mapped to each customer's agent CLIENT-SIDE — a different model, a
+    different grain and a different code path from `store_query`'s line-level sum, so agreement
+    between them is evidence rather than tautology.
+    ⚠ Windowed to the MIRROR'S newest order, like `product_data.validate_measures`, so the
+    residual is about EDITS to a shared period and not about orders the mirror has never seen.
+    """
+    from harness import datastore as DS
+    from harness import semantic as sem
+    t = t or P.today()
+    checks = []
+    try:
+        if not DS.ready():
+            return [{'check': 'agent lookback measures reconcile to Odoo', 'a': 'no mirror',
+                     'b': '-', 'ok': False,
+                     'detail': 'the tenant store is not readable, so this is UNPROVEN, which standing rule '
+                               '8 does not accept as green'}]
+    except Exception as e:                                             # noqa: BLE001
+        return [{'check': 'agent lookback measures reconcile to Odoo', 'a': type(e).__name__,
+                 'b': '-', 'ok': False, 'detail': str(e)[:200]}]
+    offer = sem.entity_measures('odoo_agents')
+    checks.append({'check': 'the agent measure OFFER is non-empty and every key resolves '
+                            '(owner item 4 / R1)',
+                   'a': len(offer), 'b': '>0', 'ok': bool(offer),
+                   'detail': {'keys': [m['key'] for m in offer],
+                              'refused': sem.entity_measure_refusals('odoo_agents')}})
+    if not offer:
+        return checks
+    con = DS.ro_cursor()
+    try:
+        newest = con.execute('SELECT max(date_order) FROM sale_order').fetchone()
+    finally:
+        con.close()
+    d_to = t - dt.timedelta(days=2)
+    if newest and newest[0]:
+        try:
+            d_to = min(d_to, dt.date.fromisoformat(str(newest[0])[:10]) - dt.timedelta(days=1))
+        except ValueError:
+            pass
+    d_from = d_to - dt.timedelta(days=days)
+    DF, DT = d_from.isoformat(), d_to.isoformat()
+    ours = sem.entity_measure_values('odoo_agents', ['revenue'], date_from=DF, date_to=DT,
+                                     team_id=team_id, offer=offer)
+    # THE ORACLE — order headers, grouped by customer, mapped to that customer's agent here.
+    o = O.get_odoo()
+    grp = o.read_group('sale.order', sales_mod.order_domain(DF, DT, team_id),
+                       ['partner_id', 'amount_untaxed:sum'], ['partner_id'], lazy=False)
+    pids = sorted({r['partner_id'][0] for r in grp if r.get('partner_id')})
+    agent_of = {}
+    for i in range(0, len(pids), 500):
+        for p in o.search_read('res.partner', [('id', 'in', pids[i:i + 500])],
+                               ['id', 'agent_ids']):
+            ag = (p.get('agent_ids') or [])
+            if ag:
+                agent_of[p['id']] = ag[0]          # the Customers-module convention: agent_ids[0]
+    theirs = {}
+    for r in grp:
+        if not r.get('partner_id'):
+            continue
+        a = agent_of.get(r['partner_id'][0])
+        if a is not None:
+            theirs[a] = theirs.get(a, 0.0) + r['amount_untaxed']
+    ours_tot = round(sum(c.get('revenue', 0) for c in ours.values()), 2)
+    theirs_tot = round(sum(theirs.values()), 2)
+    # ⚠ ORDER-HEADER vs LINE-SUM is a REAL basis difference (an order's untaxed total includes
+    # lines this topic's service filter drops), so the tolerance is a stated 3% rather than a
+    # cent — and the FIGURE is reported so a drift is readable instead of absorbed.
+    gap = ours_tot - theirs_tot
+    checks.append({
+        'check': 'per-agent revenue (BOOK route) vs an INDEPENDENT Odoo order-header aggregate '
+                 'mapped through res.partner.agent_ids',
+        'a': ours_tot, 'b': theirs_tot, 'gap': round(gap, 2),
+        'ok': bool(theirs_tot) and abs(gap) <= 0.03 * theirs_tot,
+        'detail': {'window': [DF, DT], 'agents_ours': len(ours), 'agents_theirs': len(theirs),
+                   'gap_pct': round(gap / theirs_tot * 100, 3) if theirs_tot else None,
+                   'route': 'customer-master book (res.partner.agent_ids), NOT the OCA '
+                            'commission table; the two name different people'}})
+    # ⛔ AND PER AGENT, because a total can agree while every row is keyed wrong — the join-key
+    # trap contract C1 names. Here the key is the `res.partner` id at both ends.
+    off_by = sorted(((abs(ours.get(a, {}).get('revenue', 0.0) - v), a)
+                     for a, v in theirs.items() if v), reverse=True)
+    bad = [(a, round(ours.get(a, {}).get('revenue', 0.0), 2), round(theirs[a], 2))
+           for d, a in off_by if d > 0.03 * theirs[a]]
+    checks.append({
+        'check': 'each agent\'s own figure ties (the C1 join-key test: a wrong key agrees in '
+                 'total and disagrees on every row)',
+        'a': len(bad), 'b': 0, 'ok': not bad,
+        'detail': {'worst': [(a, ours_v, th_v) for a, ours_v, th_v in bad[:5]],
+                   'agents_compared': len(theirs)}})
+    return checks
+# ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
+# A SECOND agent source. Everything above this line attributes by BOOK — the customer's assigned
+# agent (res.partner.agent_ids) — over confirmed SALES ORDERS. This section attributes per INVOICE
+# LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
+# commission_lines). The two disagree on purpose and answer different questions:
+#
+#   book     -> "whose customer is this / who owns the relationship"   (order basis)
+#   invoice  -> "what was actually credited to an agent on the billing" + the ONLY source that can
+#               say what is NOT allocated to an agent                   (invoice basis)
+#
+# ⚠ A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT — `res.partner.agent` is the flag.
+# "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
+# dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
+# See [[invoice-line-agent-commission]].
+_ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
+                'none': 'Not allocated'}
+def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
+    """Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
+    Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
+             'unallocated': float, 'basis': str} — or {'error': msg} when the tenant store is not
+    ready (this path is store-only; there is no live fallback that stays honest about the
+    unallocated bucket).
+    """
+    import harness.semantic as S
+    t = t or P.today()
+    yf, yt = P.ytd(t)
+    dim = 'commission_name' if include_salespeople else 'agent'
+    try:
+        by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
+                           date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
+        alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
+                              date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
+        tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
+                             team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
+    except Exception as e:                       # store not ready / model error — say so, don't fake
+        return {'error': str(e)}
+    # store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
+    # (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
+    # returns None for every row and silently renders the whole table as "no agent".
+    rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
+             'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
+    rows.sort(key=lambda r: -r['revenue'])
+    amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
+    allocated = amap.get('agent', 0.0)
+    return {
+        'by_agent': rows,
+        'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
+                       for k in ('agent', 'salesperson', 'none') if k in amap or True],
+        'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
+        'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
+        'window': (yf, yt),
+        'basis': ('invoice line · commission names incl. salespeople' if include_salespeople
+                  else 'invoice line · real agents only'),
+    }

platform/modules/collections_send.py CHANGED Viewed

@@ -1,267 +1,267 @@
-"""Collections statements — the send layer behind the Collections page's Statements section.
-Folded in from the standalone collections_app (2026-07-05). THE one sanctioned exception to the
-app's read-only-on-Odoo rule, unchanged from the standalone tool: WRITE is whitelisted to exactly
-one operation —
-    create on mail.mail   (queueing an outbound statement email)
-A mail.mail record with state='outgoing' is picked up by Odoo's "Mail: Email Queue Manager" cron
-(every ~15 min) and delivered through the company's Office 365 relay. Because we set model/res_id,
-each sent statement also appears in the customer's chatter in Odoo — the audit log lives where AR
-already works. This module has its OWN narrow XML-RPC client; the app-wide odoo_client stays
-hard-blocking on all writes. The UI gates the section to admin users; SAFE_MODE is enforced HERE
-in the data layer so the UI cannot bypass it.
-Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
-Optional: SAFE_MODE (default ON), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
-COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
-"""
-import os
-import datetime as dt
-import xmlrpc.client
-from pathlib import Path
-try:  # self-contained: load credentials from the app root .env if present (HF uses Secrets)
-    from dotenv import load_dotenv
-    load_dotenv(Path(__file__).resolve().parents[1] / '.env')
-except Exception:
-    pass
-WRITE_WHITELIST = {('mail.mail', 'create')}
-EXCLUDE_NAMES = {'GIFTWARE DEALS'}  # the Amazon channel — not part of Fisch or Royal collections
-DOMAIN = [('followup_reminder_type', '=', 'automatic'), ('credit', '>', 1)]
-COMPANY = os.environ.get('COMPANY_NAME', 'Royal Imports')
-# --- Sender identity (statements go out AS Royal Imports) ---
-# Odoo routes outbound mail to the matching ir.mail_server by from_filter, and the Office 365
-# relay only accepts sends as its authenticated address. The "Office 365 - Royal" server (id 2)
-# authenticates as contact@royalimports.com with from_filter='contact@royalimports.com' — so the
-# From MUST be that address for delivery to succeed. Friendly display name; replies routed to AR.
-SENDER_NAME = os.environ.get('SENDER_NAME', 'Royal Imports Accounts Receivable')
-SENDER_EMAIL = os.environ.get('SENDER_EMAIL', 'contact@royalimports.com')
-REPLY_TO = os.environ.get('REPLY_TO', 'accounting@royalimports.com')
-ROYAL_MAIL_SERVER_ID = int(os.environ.get('ROYAL_MAIL_SERVER_ID', '2'))
-ROYAL_AUTHOR_ID = int(os.environ.get('ROYAL_AUTHOR_ID', '8978'))  # "Royal Imports" partner
-SENDER_DISPLAY = f'"{SENDER_NAME}" <{SENDER_EMAIL}>'
-class WriteBlocked(RuntimeError):
-    pass
-class SafeModeBlocked(RuntimeError):
-    pass
-# --- Testing guardrail -------------------------------------------------------
-# While SAFE_MODE is on, NO email can be queued to any address outside the allow-list — enforced
-# here in the data layer so the UI cannot bypass it. Default: ON. To go live for real customers,
-# set the Space secret SAFE_MODE=0.
-SAFE_MODE = os.environ.get('SAFE_MODE', '1').strip().lower() not in ('0', 'false', 'no', '')
-SAFE_RECIPIENTS = {a.strip().lower() for a in
-                   os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
-                   if a.strip()}
-def safe_recipient_ok(addr):
-    return (not SAFE_MODE) or (str(addr or '').strip().lower() in SAFE_RECIPIENTS)
-class Odoo:
-    """Narrow client: read anything, write ONLY the whitelisted mail.mail create."""
-    def __init__(self):
-        self.url = os.environ.get('ODOO_URL', '').rstrip('/')
-        self.db = os.environ.get('ODOO_DB', '')
-        self.user = os.environ.get('ODOO_USER', '')
-        self.key = os.environ.get('ODOO_API_KEY', '')
-        missing = [k for k, v in [('ODOO_URL', self.url), ('ODOO_DB', self.db),
-                                   ('ODOO_USER', self.user), ('ODOO_API_KEY', self.key)] if not v]
-        if missing:
-            raise RuntimeError(f"Missing secrets: {', '.join(missing)}")
-        common = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/common')
-        self.uid = common.authenticate(self.db, self.user, self.key, {})
-        if not self.uid:
-            raise RuntimeError('Odoo authentication failed')
-        self.models = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/object')
-    def _exec(self, model, method, args, kwargs=None):
-        mutating = method in ('write', 'create', 'unlink', 'copy') or \
-            any(method.startswith(p) for p in ('action_', 'button_', 'do_', 'send_',
-                                               'set_', 'update_', 'process_'))
-        if mutating and (model, method) not in WRITE_WHITELIST:
-            raise WriteBlocked(f'{method} on {model} is not allowed from this app')
-        return self.models.execute_kw(self.db, self.uid, self.key,
-                                      model, method, args, kwargs or {})
-    def search_read(self, model, domain=None, fields=None, limit=None, order=None):
-        kw = {'fields': fields or []}
-        if limit is not None:
-            kw['limit'] = limit
-        if order:
-            kw['order'] = order
-        return self._exec(model, 'search_read', [domain or []], kw)
-    def queue_mail(self, payload):
-        """The single allowed write: queue an outbound email."""
-        return self._exec('mail.mail', 'create', [payload])
-# --------------------------------------------------------------- data builders
-def load_collection_list(odoo):
-    """The saved follow-up filter (Reminders=Automatic, Receivable>$1), GIFTWARE excluded,
-    with priority tiers."""
-    partners = odoo.search_read('res.partner', DOMAIN,
-        ['name', 'credit', 'total_overdue', 'followup_status',
-         'followup_next_action_date', 'followup_responsible_id',
-         'email', 'phone', 'mobile'])
-    partners = [p for p in partners if (p['name'] or '').strip().upper() not in EXCLUDE_NAMES]
-    pids = [p['id'] for p in partners]
-    docs = odoo.search_read('account.move',
-        [('move_type', 'in', ['out_invoice', 'out_refund']), ('state', '=', 'posted'),
-         ('payment_state', 'in', ['not_paid', 'partial']), ('partner_id', 'in', pids)],
-        ['name', 'partner_id', 'move_type', 'invoice_date', 'invoice_date_due',
-         'amount_total', 'amount_residual_signed'])
-    today = dt.date.today()
-    by_partner = {}
-    for d in docs:
-        pid = d['partner_id'][0]
-        due = d.get('invoice_date_due')
-        try:
-            days = (today - dt.date.fromisoformat(due)).days if due else 0
-        except Exception:
-            days = 0
-        d['days_overdue'] = max(days, 0)
-        d['open_signed'] = d['amount_residual_signed']
-        by_partner.setdefault(pid, []).append(d)
-    rows = []
-    for p in partners:
-        pid = p['id']
-        odoo_overdue = float(p.get('total_overdue') or 0)
-        docs_p = sorted(by_partner.get(pid, []), key=lambda x: x.get('invoice_date_due') or '')
-        inv_overdue = sum(d['open_signed'] for d in docs_p if d['days_overdue'] > 0)
-        oldest = max((d['days_overdue'] for d in docs_p), default=0)
-        gap = inv_overdue - odoo_overdue
-        reconcile = abs(gap) > 50
-        if odoo_overdue >= 5000 or (odoo_overdue > 0 and oldest > 90):
-            tier = 'A-Urgent'
-        elif odoo_overdue >= 1000 or (odoo_overdue > 0 and oldest > 30):
-            tier = 'B-Active'
-        elif odoo_overdue > 0:
-            tier = 'C-Light'
-        else:
-            tier = 'Monitor'
-        rows.append({
-            'partner_id': pid,
-            'Customer': p['name'],
-            'Tier': tier,
-            'Overdue': odoo_overdue,
-            'Receivable': float(p.get('credit') or 0),
-            'Oldest (days)': oldest,
-            'Open Docs': len(docs_p),
-            'Email': p.get('email') or '',
-            'Phone': p.get('phone') or p.get('mobile') or '',
-            'Status': (p.get('followup_status') or '').replace('_', ' '),
-            'Reconcile?': 'YES' if reconcile else '',
-            '_docs': docs_p,
-        })
-    tier_rank = {'A-Urgent': 0, 'B-Active': 1, 'C-Light': 2, 'Monitor': 3}
-    rows.sort(key=lambda r: (tier_rank[r['Tier']], -r['Overdue']))
-    return rows
-# --------------------------------------------------------------- statement email
-# ⛔ STANDING RULE 2, AND THIS IS THE ONE STRING IN THE PRODUCT THAT LEAVES THE BUILDING.
-# Every other finding `web_prose` reports is copy on a screen somebody here opens; this is the
-# SUBJECT LINE of mail queued to a real debtor, over the single sanctioned Odoo write. It read
-# 'Statement of Account (em dash) {company} (em dash) {month}' until W36-T42.
-DEFAULT_SUBJECT = 'Statement of Account from {company}, {month}'
-DEFAULT_INTRO = (
-    'Dear {customer},<br><br>'
-    'Please find below your current statement of account with {company}. '
-    'According to our records, the following invoices remain open:'
-)
-DEFAULT_FOOTER = (
-    'If you have already sent payment, please disregard this notice, and thank you. '
-    'For any questions about an invoice, simply reply to this email.<br><br>'
-    'Thank you for your business,<br>{company}<br>Accounts Receivable'
-)
-def render_statement_html(row, intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER):
-    month = dt.date.today().strftime('%B %Y')
-    intro = intro_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
-    footer = footer_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
-    lines = []
-    total_open = 0.0
-    for d in row['_docs']:
-        kind = 'Credit Note' if d['move_type'] == 'out_refund' else 'Invoice'
-        amt = d['open_signed']
-        total_open += amt
-        overdue_txt = f"{d['days_overdue']}d overdue" if d['days_overdue'] > 0 else 'current'
-        color = '#C0392B' if d['days_overdue'] > 0 else '#1F4E78'
-        lines.append(
-            f"<tr><td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d['name']} <span style='color:#888'>({kind})</span></td>"
-            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date') or ''}</td>"
-            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date_due') or ''}</td>"
-            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;color:{color}'>{overdue_txt}</td>"
-            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;text-align:right'>${amt:,.2f}</td></tr>")
-    table = (
-        "<table style='border-collapse:collapse;font-size:14px;margin:14px 0'>"
-        "<tr style='background:#1F4E78;color:#fff'>"
-        "<th style='padding:7px 10px;text-align:left'>Document</th>"
-        "<th style='padding:7px 10px;text-align:left'>Date</th>"
-        "<th style='padding:7px 10px;text-align:left'>Due</th>"
-        "<th style='padding:7px 10px;text-align:left'>Status</th>"
-        "<th style='padding:7px 10px;text-align:right'>Open Balance</th></tr>"
-        + ''.join(lines) +
-        f"<tr><td colspan='4' style='padding:8px 10px;font-weight:bold;text-align:right'>Total open</td>"
-        f"<td style='padding:8px 10px;font-weight:bold;text-align:right'>${total_open:,.2f}</td></tr>"
-        f"<tr><td colspan='4' style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>Of which overdue</td>"
-        f"<td style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>${row['Overdue']:,.2f}</td></tr>"
-        "</table>")
-    return (f"<div style='font-family:Calibri,Arial,sans-serif;color:#1a1a1a;font-size:14px'>"
-            f"{intro}{table}{footer}</div>")
-def queue_statement(odoo, row, subject_tpl=DEFAULT_SUBJECT,
-                    intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER,
-                    override_to=None):
-    """Queue one statement email in Odoo. Returns mail.mail id.
-    override_to: send to a different address (used by the test-send button)."""
-    to = override_to or row['Email']
-    if not to:
-        raise ValueError(f"{row['Customer']} has no email address")
-    # Hard guardrail — refuse any recipient outside the allow-list while SAFE_MODE is on.
-    if not safe_recipient_ok(to):
-        raise SafeModeBlocked(
-            f"Guardrail ON: refusing to email {to}. Only {', '.join(sorted(SAFE_RECIPIENTS))} "
-            f"is allowed right now. (Set SAFE_MODE=0 to send to real customers.)")
-    month = dt.date.today().strftime('%B %Y')
-    subject = subject_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
-    payload = {
-        'subject': subject,
-        'body_html': render_statement_html(row, intro_tpl, footer_tpl),
-        'email_to': to,
-        'email_from': SENDER_DISPLAY,            # From: Royal Imports
-        'reply_to': REPLY_TO,                    # replies -> AR
-        'mail_server_id': ROYAL_MAIL_SERVER_ID,  # force Royal O365 relay
-        'author_id': ROYAL_AUTHOR_ID,            # clean attribution in chatter
-        'state': 'outgoing',
-        'auto_delete': False,
-        'model': 'res.partner',
-        'res_id': row['partner_id'],
-    }
-    return odoo.queue_mail(payload)

+"""Collections statements — the send layer behind the Collections page's Statements section.
+Folded in from the standalone collections_app (2026-07-05). THE one sanctioned exception to the
+app's read-only-on-Odoo rule, unchanged from the standalone tool: WRITE is whitelisted to exactly
+one operation —
+    create on mail.mail   (queueing an outbound statement email)
+A mail.mail record with state='outgoing' is picked up by Odoo's "Mail: Email Queue Manager" cron
+(every ~15 min) and delivered through the company's Office 365 relay. Because we set model/res_id,
+each sent statement also appears in the customer's chatter in Odoo — the audit log lives where AR
+already works. This module has its OWN narrow XML-RPC client; the app-wide odoo_client stays
+hard-blocking on all writes. The UI gates the section to admin users; SAFE_MODE is enforced HERE
+in the data layer so the UI cannot bypass it.
+Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
+Optional: SAFE_MODE (default ON), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
+COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
+"""
+import os
+import datetime as dt
+import xmlrpc.client
+from pathlib import Path
+try:  # self-contained: load credentials from the app root .env if present (HF uses Secrets)
+    from dotenv import load_dotenv
+    load_dotenv(Path(__file__).resolve().parents[1] / '.env')
+except Exception:
+    pass
+WRITE_WHITELIST = {('mail.mail', 'create')}
+EXCLUDE_NAMES = {'GIFTWARE DEALS'}  # the Amazon channel — not part of Fisch or Royal collections
+DOMAIN = [('followup_reminder_type', '=', 'automatic'), ('credit', '>', 1)]
+COMPANY = os.environ.get('COMPANY_NAME', 'Royal Imports')
+# --- Sender identity (statements go out AS Royal Imports) ---
+# Odoo routes outbound mail to the matching ir.mail_server by from_filter, and the Office 365
+# relay only accepts sends as its authenticated address. The "Office 365 - Royal" server (id 2)
+# authenticates as contact@royalimports.com with from_filter='contact@royalimports.com' — so the
+# From MUST be that address for delivery to succeed. Friendly display name; replies routed to AR.
+SENDER_NAME = os.environ.get('SENDER_NAME', 'Royal Imports Accounts Receivable')
+SENDER_EMAIL = os.environ.get('SENDER_EMAIL', 'contact@royalimports.com')
+REPLY_TO = os.environ.get('REPLY_TO', 'accounting@royalimports.com')
+ROYAL_MAIL_SERVER_ID = int(os.environ.get('ROYAL_MAIL_SERVER_ID', '2'))
+ROYAL_AUTHOR_ID = int(os.environ.get('ROYAL_AUTHOR_ID', '8978'))  # "Royal Imports" partner
+SENDER_DISPLAY = f'"{SENDER_NAME}" <{SENDER_EMAIL}>'
+class WriteBlocked(RuntimeError):
+    pass
+class SafeModeBlocked(RuntimeError):
+    pass
+# --- Testing guardrail -------------------------------------------------------
+# While SAFE_MODE is on, NO email can be queued to any address outside the allow-list — enforced
+# here in the data layer so the UI cannot bypass it. Default: ON. To go live for real customers,
+# set the Space secret SAFE_MODE=0.
+SAFE_MODE = os.environ.get('SAFE_MODE', '1').strip().lower() not in ('0', 'false', 'no', '')
+SAFE_RECIPIENTS = {a.strip().lower() for a in
+                   os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
+                   if a.strip()}
+def safe_recipient_ok(addr):
+    return (not SAFE_MODE) or (str(addr or '').strip().lower() in SAFE_RECIPIENTS)
+class Odoo:
+    """Narrow client: read anything, write ONLY the whitelisted mail.mail create."""
+    def __init__(self):
+        self.url = os.environ.get('ODOO_URL', '').rstrip('/')
+        self.db = os.environ.get('ODOO_DB', '')
+        self.user = os.environ.get('ODOO_USER', '')
+        self.key = os.environ.get('ODOO_API_KEY', '')
+        missing = [k for k, v in [('ODOO_URL', self.url), ('ODOO_DB', self.db),
+                                   ('ODOO_USER', self.user), ('ODOO_API_KEY', self.key)] if not v]
+        if missing:
+            raise RuntimeError(f"Missing secrets: {', '.join(missing)}")
+        common = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/common')
+        self.uid = common.authenticate(self.db, self.user, self.key, {})
+        if not self.uid:
+            raise RuntimeError('Odoo authentication failed')
+        self.models = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/object')
+    def _exec(self, model, method, args, kwargs=None):
+        mutating = method in ('write', 'create', 'unlink', 'copy') or \
+            any(method.startswith(p) for p in ('action_', 'button_', 'do_', 'send_',
+                                               'set_', 'update_', 'process_'))
+        if mutating and (model, method) not in WRITE_WHITELIST:
+            raise WriteBlocked(f'{method} on {model} is not allowed from this app')
+        return self.models.execute_kw(self.db, self.uid, self.key,
+                                      model, method, args, kwargs or {})
+    def search_read(self, model, domain=None, fields=None, limit=None, order=None):
+        kw = {'fields': fields or []}
+        if limit is not None:
+            kw['limit'] = limit
+        if order:
+            kw['order'] = order
+        return self._exec(model, 'search_read', [domain or []], kw)
+    def queue_mail(self, payload):
+        """The single allowed write: queue an outbound email."""
+        return self._exec('mail.mail', 'create', [payload])
+# --------------------------------------------------------------- data builders
+def load_collection_list(odoo):
+    """The saved follow-up filter (Reminders=Automatic, Receivable>$1), GIFTWARE excluded,
+    with priority tiers."""
+    partners = odoo.search_read('res.partner', DOMAIN,
+        ['name', 'credit', 'total_overdue', 'followup_status',
+         'followup_next_action_date', 'followup_responsible_id',
+         'email', 'phone', 'mobile'])
+    partners = [p for p in partners if (p['name'] or '').strip().upper() not in EXCLUDE_NAMES]
+    pids = [p['id'] for p in partners]
+    docs = odoo.search_read('account.move',
+        [('move_type', 'in', ['out_invoice', 'out_refund']), ('state', '=', 'posted'),
+         ('payment_state', 'in', ['not_paid', 'partial']), ('partner_id', 'in', pids)],
+        ['name', 'partner_id', 'move_type', 'invoice_date', 'invoice_date_due',
+         'amount_total', 'amount_residual_signed'])
+    today = dt.date.today()
+    by_partner = {}
+    for d in docs:
+        pid = d['partner_id'][0]
+        due = d.get('invoice_date_due')
+        try:
+            days = (today - dt.date.fromisoformat(due)).days if due else 0
+        except Exception:
+            days = 0
+        d['days_overdue'] = max(days, 0)
+        d['open_signed'] = d['amount_residual_signed']
+        by_partner.setdefault(pid, []).append(d)
+    rows = []
+    for p in partners:
+        pid = p['id']
+        odoo_overdue = float(p.get('total_overdue') or 0)
+        docs_p = sorted(by_partner.get(pid, []), key=lambda x: x.get('invoice_date_due') or '')
+        inv_overdue = sum(d['open_signed'] for d in docs_p if d['days_overdue'] > 0)
+        oldest = max((d['days_overdue'] for d in docs_p), default=0)
+        gap = inv_overdue - odoo_overdue
+        reconcile = abs(gap) > 50
+        if odoo_overdue >= 5000 or (odoo_overdue > 0 and oldest > 90):
+            tier = 'A-Urgent'
+        elif odoo_overdue >= 1000 or (odoo_overdue > 0 and oldest > 30):
+            tier = 'B-Active'
+        elif odoo_overdue > 0:
+            tier = 'C-Light'
+        else:
+            tier = 'Monitor'
+        rows.append({
+            'partner_id': pid,
+            'Customer': p['name'],
+            'Tier': tier,
+            'Overdue': odoo_overdue,
+            'Receivable': float(p.get('credit') or 0),
+            'Oldest (days)': oldest,
+            'Open Docs': len(docs_p),
+            'Email': p.get('email') or '',
+            'Phone': p.get('phone') or p.get('mobile') or '',
+            'Status': (p.get('followup_status') or '').replace('_', ' '),
+            'Reconcile?': 'YES' if reconcile else '',
+            '_docs': docs_p,
+        })
+    tier_rank = {'A-Urgent': 0, 'B-Active': 1, 'C-Light': 2, 'Monitor': 3}
+    rows.sort(key=lambda r: (tier_rank[r['Tier']], -r['Overdue']))
+    return rows
+# --------------------------------------------------------------- statement email
+# ⛔ STANDING RULE 2, AND THIS IS THE ONE STRING IN THE PRODUCT THAT LEAVES THE BUILDING.
+# Every other finding `web_prose` reports is copy on a screen somebody here opens; this is the
+# SUBJECT LINE of mail queued to a real debtor, over the single sanctioned Odoo write. It read
+# 'Statement of Account (em dash) {company} (em dash) {month}' until W36-T42.
+DEFAULT_SUBJECT = 'Statement of Account from {company}, {month}'
+DEFAULT_INTRO = (
+    'Dear {customer},<br><br>'
+    'Please find below your current statement of account with {company}. '
+    'According to our records, the following invoices remain open:'
+)
+DEFAULT_FOOTER = (
+    'If you have already sent payment, please disregard this notice, and thank you. '
+    'For any questions about an invoice, simply reply to this email.<br><br>'
+    'Thank you for your business,<br>{company}<br>Accounts Receivable'
+)
+def render_statement_html(row, intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER):
+    month = dt.date.today().strftime('%B %Y')
+    intro = intro_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
+    footer = footer_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
+    lines = []
+    total_open = 0.0
+    for d in row['_docs']:
+        kind = 'Credit Note' if d['move_type'] == 'out_refund' else 'Invoice'
+        amt = d['open_signed']
+        total_open += amt
+        overdue_txt = f"{d['days_overdue']}d overdue" if d['days_overdue'] > 0 else 'current'
+        color = '#C0392B' if d['days_overdue'] > 0 else '#1F4E78'
+        lines.append(
+            f"<tr><td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d['name']} <span style='color:#888'>({kind})</span></td>"
+            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date') or ''}</td>"
+            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date_due') or ''}</td>"
+            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;color:{color}'>{overdue_txt}</td>"
+            f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;text-align:right'>${amt:,.2f}</td></tr>")
+    table = (
+        "<table style='border-collapse:collapse;font-size:14px;margin:14px 0'>"
+        "<tr style='background:#1F4E78;color:#fff'>"
+        "<th style='padding:7px 10px;text-align:left'>Document</th>"
+        "<th style='padding:7px 10px;text-align:left'>Date</th>"
+        "<th style='padding:7px 10px;text-align:left'>Due</th>"
+        "<th style='padding:7px 10px;text-align:left'>Status</th>"
+        "<th style='padding:7px 10px;text-align:right'>Open Balance</th></tr>"
+        + ''.join(lines) +
+        f"<tr><td colspan='4' style='padding:8px 10px;font-weight:bold;text-align:right'>Total open</td>"
+        f"<td style='padding:8px 10px;font-weight:bold;text-align:right'>${total_open:,.2f}</td></tr>"
+        f"<tr><td colspan='4' style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>Of which overdue</td>"
+        f"<td style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>${row['Overdue']:,.2f}</td></tr>"
+        "</table>")
+    return (f"<div style='font-family:Calibri,Arial,sans-serif;color:#1a1a1a;font-size:14px'>"
+            f"{intro}{table}{footer}</div>")
+def queue_statement(odoo, row, subject_tpl=DEFAULT_SUBJECT,
+                    intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER,
+                    override_to=None):
+    """Queue one statement email in Odoo. Returns mail.mail id.
+    override_to: send to a different address (used by the test-send button)."""
+    to = override_to or row['Email']
+    if not to:
+        raise ValueError(f"{row['Customer']} has no email address")
+    # Hard guardrail — refuse any recipient outside the allow-list while SAFE_MODE is on.
+    if not safe_recipient_ok(to):
+        raise SafeModeBlocked(
+            f"Guardrail ON: refusing to email {to}. Only {', '.join(sorted(SAFE_RECIPIENTS))} "
+            f"is allowed right now. (Set SAFE_MODE=0 to send to real customers.)")
+    month = dt.date.today().strftime('%B %Y')
+    subject = subject_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
+    payload = {
+        'subject': subject,
+        'body_html': render_statement_html(row, intro_tpl, footer_tpl),
+        'email_to': to,
+        'email_from': SENDER_DISPLAY,            # From: Royal Imports
+        'reply_to': REPLY_TO,                    # replies -> AR
+        'mail_server_id': ROYAL_MAIL_SERVER_ID,  # force Royal O365 relay
+        'author_id': ROYAL_AUTHOR_ID,            # clean attribution in chatter
+        'state': 'outgoing',
+        'auto_delete': False,
+        'model': 'res.partner',
+        'res_id': row['partner_id'],
+    }
+    return odoo.queue_mail(payload)

platform/modules/product_data.py CHANGED Viewed

@@ -636,6 +636,13 @@ def pool(team_id=None, t=None):
             # leaf and WIDENS to the whole catalogue. That is the exact failure `_seed_wave17`'s
             # buy-list comment was written about, and a blank here would reintroduce it.
             "discontinued": meta.get("discontinued") or "No",
             # ⭐⭐ W33-T43 (R2 / amendment A2) — ODOO'S OWN PRODUCT ID, beside the hashed `pid`.
             # R2 retires `ut_odoo_products` onto this key and keeps every data column it had; this
             # is that column. ⛔ NOT DERIVABLE DOWNSTREAM: `pid` is `crc32(default_code)` here,
@@ -844,6 +851,81 @@ def pool(team_id=None, t=None):
     return rows
 #: ⭐ THE BUY SIGNAL, AS THE FORMULA FIELD EVALUATES IT (owner, 2026-08-03).
 #:
 #: The owner's ruling was that "Buy signal" is not a preset field — it is a formula over two

             # leaf and WIDENS to the whole catalogue. That is the exact failure `_seed_wave17`'s
             # buy-list comment was written about, and a blank here would reintroduce it.
             "discontinued": meta.get("discontinued") or "No",
+            # W41-T26 (owner I28, "pull UPC live from Odoo") - the barcode, carried from
+            # `products.catalogue()` for the same reason `product_id` is: `pool()` assembles
+            # this row key by key and never spreads `meta`, so a key the catalogue gains
+            # reaches nothing until it is named here.
+            # BLANK, never a placeholder: Odoo carries zero "-" and zero "0" barcodes, so the
+            # mastersheet's 75-percent-"-" column cannot leak in through the source.
+            "upc": meta.get("upc") or "",
             # ⭐⭐ W33-T43 (R2 / amendment A2) — ODOO'S OWN PRODUCT ID, beside the hashed `pid`.
             # R2 retires `ut_odoo_products` onto this key and keeps every data column it had; this
             # is that column. ⛔ NOT DERIVABLE DOWNSTREAM: `pid` is `crc32(default_code)` here,
     return rows
+#: ⭐⭐ W41-T17 (owner instruction 25) — THE SYNTHETIC BUSINESS KEY'S PREFIX.
+#:
+#: `products.catalogue()` keys a product with no `default_code` as `f"pid:{p['id']}"`, and three
+#: other functions in `modules/products.py` plus `modules/backorders.py` spell that same literal.
+#: This constant exists so the REPORT below reads the convention by name instead of adding a sixth
+#: copy of the spelling; it deliberately does not try to make the producers use it, because those
+#: files are the ones that would have to change and a constant nobody writes through is a second
+#: source for one fact ([[gate-pins-a-spelling-not-a-claim]]).
+#: ⚠ IT IS A FALLBACK KEY, NOT AN ODOO ID. The digits after the colon happen to BE the
+#: `product.product` id, which is exactly why reading them back out would look reasonable and be
+#: wrong: `product_id` is a declared column carrying that value as an int, and parsing it out of a
+#: text cell would be a second derivation of a number already on the row.
+CODELESS_KEY_PREFIX = "pid:"
+def identity_report(rows):
+    """R6's second sentence as data, for the PRODUCT grid's two identity columns:
+    `{subject, cause, recommendation, effect}` plus the counts it is asserting.
+    ⭐⭐ W41-T17 / owner instruction 25 ("check whether Odoo customer's unique ID should have been
+    the Odoo ID"). The answer for CUSTOMERS was yes and already shipped: a customer row's `pid` IS
+    the `res.partner` id, so `odoo_customers.yml` can say "there is ONE id per row and no second
+    one". PRODUCTS are the gap this reports on: `pid` is a CRC32 of the SKU, the Odoo id is a
+    separate value, and 33 active products carry no SKU at all and wear a `pid:<id>` business key.
+    ⛔ THIS IS THE "REPORTED, NEVER SILENTLY ENFORCED" HALF OF STANDING RULE 1, AND IT IS THE
+    REASON THE FUNCTION EXISTS RATHER THAN A COMMENT. Those 33 rows are not dropped, not capped
+    and not blank; what they lack is a REAL business key, and before this ticket nothing on the
+    wire said so. A reader who filtered `code` for a SKU pattern silently lost them, and a reader
+    who saw `pid:40170` had no way to learn whether that was a code or a placeholder.
+    ⚠ `effect` IS `reported`, WHICH IS A THIRD VALUE, AND THAT IS DELIBERATE.
+    `core/user_tables.limit_report` ships exactly two (`read_through` and `refused`) and its
+    docstring makes a point of `truncated` never being one of them, because every site it speaks
+    for REFUSES. Nothing is refused here and nothing is read through: all 5,872 grid rows ship
+    with a resolved `product_id`. Forcing this into `refused` would make that invariant read as
+    broken; inventing a quiet fourth meaning for `read_through` would be worse. So the shape is
+    borrowed and the vocabulary is extended, in writing.
+    ⭐ TAKES ROWS, DOES NOT BUILD THEM. The caller passes the rows it is actually about to serve,
+    AFTER the row wall has run, so a BU-scoped reader is told about the products in THEIR grid.
+    Counting `catalogue()` here instead would print 33 beside a narrower grid, which is the class
+    of number that disagrees with the screen and is believed anyway.
+    """
+    rows = list(rows or [])
+    total = len(rows)
+    codeless = [r for r in rows
+                if str(r.get("code") or "").startswith(CODELESS_KEY_PREFIX)]
+    # ⚠ `is None`, NOT falsy: 0 is a real Odoo id (the same distinction `pool` makes on this key
+    # one screen up), so `not r.get("product_id")` would count a legitimate id as a missing one.
+    missing_id = [r for r in rows if r.get("product_id") is None]
+    return {
+        "subject": "product identity",
+        "effect": "reported",
+        "rows": total,
+        "resolved": total - len(missing_id),
+        "unresolved": len(missing_id),
+        "codeless": len(codeless),
+        "codeless_sample": sorted(str(r.get("code") or "") for r in codeless)[:5],
+        "cause": (
+            "a product's row id is a CRC32 of its SKU, so it is not the Odoo id and the two "
+            "cannot be recovered from each other. `product_id` carries the real "
+            "`product.product` id, and `code` stays the business key. "
+            f"{len(codeless)} of these {total} products carry no SKU in Odoo, so their `code` is "
+            "the fallback `pid:<odoo id>` rather than a code anyone quotes"
+        ),
+        "recommendation": (
+            "join and group on `product_id`, which resolves for every product carrying an Odoo "
+            "id. Treat a `code` beginning `pid:` as absent rather than as a SKU: filter on "
+            "`product_id` when the question is about the record, and on `code` only when the "
+            "question is genuinely about the catalogue number"
+        ),
+    }
 #: ⭐ THE BUY SIGNAL, AS THE FORMULA FIELD EVALUATES IT (owner, 2026-08-03).
 #:
 #: The owner's ruling was that "Buy signal" is not a preset field — it is a formula over two