Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,6 +1,12 @@
 {
- "current": "624b9af",
+ "current": "v30 (71776ca)",
  "releases": [
+  {
+   "version": "v30",
+   "sha": "71776ca",
+   "date": "2026-08-20",
+   "subject": "v30: W39-T29 Member-owned View first-share hotfix"
+  },
   {
    "version": "v29",
    "sha": "55ced50",

VERSION

@@ -1 +1 @@
-624b9af
+v30 (71776ca)

api/ai_review.py

@@ -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/connectors_tt.py

@@ -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/routes_agent_harness.py

@@ -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

@@ -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_geo.py

@@ -1,369 +1,369 @@
-"""routes_geo.py — the MAP PROVIDER SEAM (wave 37, R3/R14, tickets T35/T36/T37).
-
-⭐ WHY THIS FILE EXISTS AT ALL, and why the map does not simply call a vendor.
-
-R14 (owner, 2026-08-19): no Google Maps API key this wave. The map work is not dropped, it is
-retargeted to providers that need no key: OpenStreetMap tiles, OSRM routing, Nominatim geocoding.
-The deferral only holds if swapping a paid vendor back in is a CONFIG change rather than a rewrite,
-so every provider is a (base URL + attribution) pair read from the environment and served from ONE
-door. The renderer receives a URL template and a credit line; it knows nothing about who is behind
-them. That is the seam.
-
-    tiles     AIOS_MAP_TILE_URL           default  https://tile.openstreetmap.org/{z}/{x}/{y}.png
-    geocode   AIOS_GEOCODE_URL            default  https://nominatim.openstreetmap.org/search
-    routing   AIOS_ROUTE_URL              default  https://router.project-osrm.org/route/v1/driving/
-
-⛔ R3'S ON-DEMAND RULE, AND WHY IT IS STRUCTURAL HERE RATHER THAN A COMMENT.
-R3 forbids geocoding a whole table automatically. Under R14 the reason moves from money to manners
-and gets sharper: Nominatim's usage policy allows roughly one request per second and explicitly
-forbids bulk harvesting, so a loop over 3,636 customers does not produce a bill, it produces a
-BLOCKED tenant. Three mechanisms enforce it, none of them advisory:
-
-  1. `/geo/geocode` takes an explicit LIST OF ADDRESSES from the caller. It cannot read a table, so
-     there is no code path from "a database exists" to "its rows were geocoded". Somebody had to
-     choose the records.
-  2. `MAX_BATCH` refuses an oversized list with a named error rather than truncating it. The client
-     drives the loop and can therefore SHOW the wait, which is the half of the ticket a comment
-     cannot satisfy.
-  3. `_throttle()` blocks in-process until the minimum interval has elapsed, so even a caller that
-     ignores everything above cannot exceed the published rate.
-
-⭐ AND A CACHE, because the policy asks for one: an address geocoded once is answered from memory
-for the rest of the container's life. It is the cheapest way to be a good citizen and it makes a
-re-run of the same records free rather than merely legal.
-
-⚠ NOTHING HERE PROXIES TILES. Tiles are fetched by the BROWSER, straight from the provider, which
-is what every OSM client does and what the tile policy expects. Proxying them through this app
-would put a free tier in the path of every pan and would breach the same policy it looks like it is
-respecting. This door serves the tile URL, never the tile.
-"""
-import os
-import re
-import threading
-import time
-from collections import OrderedDict
-
-import requests
-from fastapi import APIRouter, Body, Depends
-
-from deps import Session, err, require_session
-
-router = APIRouter(prefix="/api/v1")
-
-# --------------------------------------------------------------------- the seam
-#
-# Every value below is an environment override with a keyless default. Pointing the map at a paid
-# vendor is three variables on the Space and no code change, which is what makes R14 a deferral.
-
-_TILE_URL_DEFAULT = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
-_TILE_CREDIT_DEFAULT = "© OpenStreetMap contributors"
-_TILE_CREDIT_HREF_DEFAULT = "https://www.openstreetmap.org/copyright"
-_GEOCODE_URL_DEFAULT = "https://nominatim.openstreetmap.org/search"
-_ROUTE_URL_DEFAULT = "https://router.project-osrm.org/route/v1/driving/"
-
-#: Both policies require a real, identifying User-Agent. A generic one is how a shared service
-#: decides an application is a scraper, so this carries the product name and a contact URL.
-_UA_DEFAULT = "AIOS-Loopable/1.0 (+https://runloopable.com)"
-
-#: Nominatim publishes one request per second. 1100 ms leaves room for clock jitter rather than
-#: sitting exactly on the published edge.
-_MIN_INTERVAL_MS_DEFAULT = 1100
-
-#: The most addresses one call may carry. Small on purpose: the client loops and shows progress,
-#: and no single request can sit on the connection for a minute waiting out the throttle.
-MAX_BATCH = 25
-
-#: Tile zoom the provider actually serves. OSM stops at 19.
-_TILE_MAX_Z_DEFAULT = 19
-
-_CACHE_MAX = 4096
-
-
-def _env(name, default):
-    return (os.environ.get(name) or "").strip() or default
-
-
-def _env_int(name, default):
-    try:
-        n = int((os.environ.get(name) or "").strip())
-        return n if n > 0 else default
-    except (TypeError, ValueError):
-        return default
-
-
-def provider_config():
-    """The whole seam as one dict. `GET /geo/providers` serves it and the gate reads it."""
-    return {
-        "tiles": {
-            "url": _env("AIOS_MAP_TILE_URL", _TILE_URL_DEFAULT),
-            "attribution": _env("AIOS_MAP_TILE_ATTRIBUTION", _TILE_CREDIT_DEFAULT),
-            "attributionUrl": _env("AIOS_MAP_TILE_ATTRIBUTION_URL", _TILE_CREDIT_HREF_DEFAULT),
-            "maxZoom": _env_int("AIOS_MAP_TILE_MAX_Z", _TILE_MAX_Z_DEFAULT),
-        },
-        "geocode": {
-            "available": True,
-            "maxBatch": MAX_BATCH,
-            "minIntervalMs": _env_int("AIOS_GEOCODE_MIN_INTERVAL_MS", _MIN_INTERVAL_MS_DEFAULT),
-            # ⭐⭐ THE NUMBER THE SURFACE MUST QUOTE, AND IT IS NOT THE RATE LIMIT.
-            # T37 asks for the estimated wait to be shown BEFORE a run. The obvious source is
-            # `minIntervalMs`, and it is wrong: 1.1 s is a floor on POLITENESS, not a prediction of
-            # LATENCY. One real lookup was MEASURED at 3.28 s end to end on 2026-08-19. Quoting the
-            # limit would promise a minute and take three, and a progress estimate that runs out
-            # before the work does reads as a hang rather than as a wait.
-            "secondsPerAddress": float(_env("AIOS_GEOCODE_SECONDS_EACH", "3.3")),
-            "attribution": _env("AIOS_GEOCODE_ATTRIBUTION", _TILE_CREDIT_DEFAULT),
-        },
-        "route": {
-            "available": True,
-            "attribution": _env("AIOS_ROUTE_ATTRIBUTION", "Routing by OSRM"),
-        },
-    }
-
-
-# ------------------------------------------------------------------ the throttle
-#
-# ⚠ ONE lock and ONE timestamp for the whole process, shared by geocoding and routing, because the
-# rate limit belongs to the SERVICE and not to the endpoint. Two independent throttles would each
-# stay honest and together double the published rate.
-
-_gate = threading.Lock()
-_last_call = [0.0]
-
-
-def _throttle(min_interval_ms):
-    """Block until the minimum interval since the last outbound call has elapsed.
-
-    Returns the seconds actually waited, so a caller can report the wait rather than hide it."""
-    wait = 0.0
-    with _gate:
-        gap = min_interval_ms / 1000.0
-        now = time.monotonic()
-        due = _last_call[0] + gap
-        if now < due:
-            wait = due - now
-            time.sleep(wait)
-        _last_call[0] = time.monotonic()
-    return wait
-
-
-# --------------------------------------------------------------------- the cache
-
-_cache = OrderedDict()
-_cache_lock = threading.Lock()
-
-
-def _cache_key(q, country):
-    return (re.sub(r"\s+", " ", str(q or "")).strip().lower(), str(country or "").strip().lower())
-
-
-def _cache_get(key):
-    with _cache_lock:
-        if key not in _cache:
-            return None
-        _cache.move_to_end(key)
-        return _cache[key]
-
-
-def _cache_put(key, value):
-    with _cache_lock:
-        _cache[key] = value
-        _cache.move_to_end(key)
-        while len(_cache) > _CACHE_MAX:
-            _cache.popitem(last=False)
-
-
-def geocode_one(address, country=None, timeout=12):
-    """One address to {lat, lon, label} or None.
-
-    ⛔ THE ONLY PLACE AN OUTBOUND GEOCODE HAPPENS. `ai_enrich.py`'s geocode field calls this rather
-    than reaching for `requests` itself, so the throttle and the cache cannot be walked around by a
-    second caller. A cache hit costs no request and no wait."""
-    q = re.sub(r"\s+", " ", str(address or "")).strip()
-    if not q:
-        return None
-    key = _cache_key(q, country)
-    hit = _cache_get(key)
-    if hit is not None:
-        return dict(hit) if hit else None
-
-    cfg = provider_config()["geocode"]
-    _throttle(cfg["minIntervalMs"])
-    params = {"q": q, "format": "jsonv2", "limit": 1}
-    if country:
-        params["countrycodes"] = str(country).strip().lower()
-    try:
-        r = requests.get(
-            _env("AIOS_GEOCODE_URL", _GEOCODE_URL_DEFAULT),
-            params=params,
-            headers={"User-Agent": _env("AIOS_GEO_USER_AGENT", _UA_DEFAULT),
-                     "Accept": "application/json"},
-            timeout=timeout,
-        )
-        r.raise_for_status()
-        rows = r.json()
-    except Exception:
-        # ⚠ A transport failure is NOT cached. Caching it would turn one bad minute into a
-        # permanently empty column that no re-run could ever repair.
-        return None
-    if not isinstance(rows, list) or not rows:
-        # A genuine "no such place" IS cached, as a negative: asking again gets the same answer and
-        # spends another second of a shared service's budget to hear it.
-        _cache_put(key, {})
-        return None
-    top = rows[0] or {}
-    try:
-        lat = float(top.get("lat"))
-        lon = float(top.get("lon"))
-    except (TypeError, ValueError):
-        _cache_put(key, {})
-        return None
-    if not (-90 <= lat <= 90) or not (-180 <= lon <= 180):
-        _cache_put(key, {})
-        return None
-    out = {"lat": lat, "lon": lon, "label": str(top.get("display_name") or q)}
-    _cache_put(key, out)
-    return dict(out)
-
-
-# ---------------------------------------------------------------------- the doors
-
-
-@router.get("/geo/providers")
-def geo_providers(session: Session = Depends(require_session)):
-    """What the map should draw with, and who to credit for it.
-
-    Session gated like every other door here. The values are not secret, but an unauthenticated
-    endpoint on this app is a door somebody eventually hangs something else on."""
-    return provider_config()
-
-
-@router.post("/geo/geocode")
-def geo_geocode(body: dict = Body(...), session: Session = Depends(require_session)):
-    """Turn a bounded list of addresses into coordinates.
-
-    ⛔ Takes ADDRESSES, never a table key, a view id or a filter. There is deliberately no shape of
-    request that means "geocode everything", which is R3 expressed as an API rather than as a
-    warning."""
-    items = body.get("addresses")
-    # ⭐ THE SECOND SHAPE, AND IT EXISTS TO KEEP ONE COMPOSER. A caller may send whole RECORDS plus
-    # the geocode field's config instead of finished address strings, and the server builds the
-    # query with `ai_enrich.geocode_query`. The alternative was a TypeScript twin of that function
-    # on the client, and an address composer that exists twice will disagree the first time either
-    # copy learns about a new column ([[one-question-two-normalizers]]) -- which is exactly the trap
-    # B's measured `New York (US)` suffix would spring, silently, in whichever copy forgot.
-    if items is None:
-        records = body.get("records")
-        cfg = body.get("config") or {}
-        if isinstance(records, list) and records:
-            import ai_enrich
-            items = []
-            for rec in records:
-                if not isinstance(rec, dict):
-                    continue
-                q = ai_enrich.geocode_query(rec.get("row") or {}, cfg)
-                # ⛔ A record with no usable address is REPORTED, not dropped: it comes back
-                # `found: false` with an empty address, so the caller can name it on screen instead
-                # of quietly returning fewer answers than it asked questions.
-                items.append({"key": rec.get("key"), "address": q})
-            if not body.get("country") and cfg.get("country"):
-                body = {**body, "country": cfg.get("country")}
-    if not isinstance(items, list) or not items:
-        raise err(400, "no_addresses", "Send at least one address to look up.")
-    if len(items) > MAX_BATCH:
-        raise err(
-            400,
-            "batch_too_large",
-            f"Look up at most {MAX_BATCH} addresses per request. "
-            f"The map sends them in batches of {MAX_BATCH} so the wait stays visible.",
-        )
-    country = body.get("country")
-    out = []
-    started = time.monotonic()
-    for raw in items:
-        if isinstance(raw, dict):
-            key, addr = raw.get("key"), raw.get("address")
-        else:
-            key, addr = None, raw
-        # ⛔ AN EMPTY QUERY COSTS NO REQUEST AND CARRIES ITS OWN REASON. Nominatim's policy is a
-        # budget shared with everyone else using it, and asking it to place "" would spend a second
-        # of that budget to be told nothing. `reason` is what lets the surface say "no address on
-        # file" rather than "not found", which are different facts and want different actions.
-        if not str(addr or "").strip():
-            out.append({"key": key, "address": "", "found": False, "lat": None, "lon": None,
-                        "label": None, "reason": "no_address"})
-            continue
-        hit = geocode_one(addr, country=country)
-        out.append({"key": key, "address": str(addr or ""), "found": bool(hit),
-                    "reason": None if hit else "not_found",
-                    "lat": hit["lat"] if hit else None,
-                    "lon": hit["lon"] if hit else None,
-                    "label": hit["label"] if hit else None})
-    elapsed = time.monotonic() - started
-    return {"results": out,
-            "found": sum(1 for r in out if r["found"]),
-            "asked": len(out),
-            "secondsElapsed": round(elapsed, 2),
-            "attribution": provider_config()["geocode"]["attribution"]}
-
-
-@router.post("/geo/route")
-def geo_route(body: dict = Body(...), session: Session = Depends(require_session)):
-    """Road distance, duration and the drawn line, for stops ALREADY put in order.
-
-    ⭐ THE ORDERING IS NOT DONE HERE. `mapProjection.planRoute` sequences the stops on the client,
-    for free, and keeps working when this service does not answer. This door adds the half that
-    arithmetic cannot produce: what the ROADS actually cost. Splitting it that way is why the Start
-    picker and the round-trip toggle keep working with no network at all."""
-    stops = body.get("stops")
-    if not isinstance(stops, list) or len(stops) < 2:
-        raise err(400, "too_few_stops", "A route needs at least two stops with a location.")
-    if len(stops) > 25:
-        raise err(400, "too_many_stops",
-                   "Route at most 25 stops at once. Narrow the selection and try again.")
-    pairs = []
-    for s in stops:
-        try:
-            lat, lon = float(s["lat"]), float(s["lon"])
-        except (TypeError, ValueError, KeyError, IndexError):
-            raise err(400, "bad_stop", "Every stop needs a numeric latitude and longitude.")
-        if not (-90 <= lat <= 90) or not (-180 <= lon <= 180):
-            raise err(400, "bad_stop", "Every stop needs a latitude and longitude on the globe.")
-        pairs.append(f"{lon:.6f},{lat:.6f}")
-
-    base = _env("AIOS_ROUTE_URL", _ROUTE_URL_DEFAULT)
-    _throttle(_env_int("AIOS_GEOCODE_MIN_INTERVAL_MS", _MIN_INTERVAL_MS_DEFAULT))
-    try:
-        r = requests.get(
-            base.rstrip("/") + "/" + ";".join(pairs),
-            params={"overview": "simplified", "geometries": "geojson", "steps": "false"},
-            headers={"User-Agent": _env("AIOS_GEO_USER_AGENT", _UA_DEFAULT)},
-            timeout=20,
-        )
-        r.raise_for_status()
-        data = r.json()
-    except Exception:
-        raise err(502, "route_service_unavailable",
-                   "The routing service did not answer. The stop order and the straight line "
-                   "distance are still on the map.")
-    routes = (data or {}).get("routes") or []
-    if not routes:
-        raise err(
-            502,
-            "no_route",
-            "No road route connects these stops. They may be on different land masses, or one of "
-            "them may be far from any road.",
-        )
-    top = routes[0]
-    geom = ((top.get("geometry") or {}).get("coordinates")) or []
-    line = []
-    for c in geom:
-        try:
-            line.append([float(c[0]), float(c[1])])
-        except (TypeError, ValueError, IndexError):
-            continue
-    return {
-        "km": round(float(top.get("distance") or 0.0) / 1000.0, 1),
-        "minutes": int(round(float(top.get("duration") or 0.0) / 60.0)),
-        "line": line,
-        "attribution": provider_config()["route"]["attribution"],
-    }
+"""routes_geo.py — the MAP PROVIDER SEAM (wave 37, R3/R14, tickets T35/T36/T37).
+
+⭐ WHY THIS FILE EXISTS AT ALL, and why the map does not simply call a vendor.
+
+R14 (owner, 2026-08-19): no Google Maps API key this wave. The map work is not dropped, it is
+retargeted to providers that need no key: OpenStreetMap tiles, OSRM routing, Nominatim geocoding.
+The deferral only holds if swapping a paid vendor back in is a CONFIG change rather than a rewrite,
+so every provider is a (base URL + attribution) pair read from the environment and served from ONE
+door. The renderer receives a URL template and a credit line; it knows nothing about who is behind
+them. That is the seam.
+
+    tiles     AIOS_MAP_TILE_URL           default  https://tile.openstreetmap.org/{z}/{x}/{y}.png
+    geocode   AIOS_GEOCODE_URL            default  https://nominatim.openstreetmap.org/search
+    routing   AIOS_ROUTE_URL              default  https://router.project-osrm.org/route/v1/driving/
+
+⛔ R3'S ON-DEMAND RULE, AND WHY IT IS STRUCTURAL HERE RATHER THAN A COMMENT.
+R3 forbids geocoding a whole table automatically. Under R14 the reason moves from money to manners
+and gets sharper: Nominatim's usage policy allows roughly one request per second and explicitly
+forbids bulk harvesting, so a loop over 3,636 customers does not produce a bill, it produces a
+BLOCKED tenant. Three mechanisms enforce it, none of them advisory:
+
+  1. `/geo/geocode` takes an explicit LIST OF ADDRESSES from the caller. It cannot read a table, so
+     there is no code path from "a database exists" to "its rows were geocoded". Somebody had to
+     choose the records.
+  2. `MAX_BATCH` refuses an oversized list with a named error rather than truncating it. The client
+     drives the loop and can therefore SHOW the wait, which is the half of the ticket a comment
+     cannot satisfy.
+  3. `_throttle()` blocks in-process until the minimum interval has elapsed, so even a caller that
+     ignores everything above cannot exceed the published rate.
+
+⭐ AND A CACHE, because the policy asks for one: an address geocoded once is answered from memory
+for the rest of the container's life. It is the cheapest way to be a good citizen and it makes a
+re-run of the same records free rather than merely legal.
+
+⚠ NOTHING HERE PROXIES TILES. Tiles are fetched by the BROWSER, straight from the provider, which
+is what every OSM client does and what the tile policy expects. Proxying them through this app
+would put a free tier in the path of every pan and would breach the same policy it looks like it is
+respecting. This door serves the tile URL, never the tile.
+"""
+import os
+import re
+import threading
+import time
+from collections import OrderedDict
+
+import requests
+from fastapi import APIRouter, Body, Depends
+
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+# --------------------------------------------------------------------- the seam
+#
+# Every value below is an environment override with a keyless default. Pointing the map at a paid
+# vendor is three variables on the Space and no code change, which is what makes R14 a deferral.
+
+_TILE_URL_DEFAULT = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+_TILE_CREDIT_DEFAULT = "© OpenStreetMap contributors"
+_TILE_CREDIT_HREF_DEFAULT = "https://www.openstreetmap.org/copyright"
+_GEOCODE_URL_DEFAULT = "https://nominatim.openstreetmap.org/search"
+_ROUTE_URL_DEFAULT = "https://router.project-osrm.org/route/v1/driving/"
+
+#: Both policies require a real, identifying User-Agent. A generic one is how a shared service
+#: decides an application is a scraper, so this carries the product name and a contact URL.
+_UA_DEFAULT = "AIOS-Loopable/1.0 (+https://runloopable.com)"
+
+#: Nominatim publishes one request per second. 1100 ms leaves room for clock jitter rather than
+#: sitting exactly on the published edge.
+_MIN_INTERVAL_MS_DEFAULT = 1100
+
+#: The most addresses one call may carry. Small on purpose: the client loops and shows progress,
+#: and no single request can sit on the connection for a minute waiting out the throttle.
+MAX_BATCH = 25
+
+#: Tile zoom the provider actually serves. OSM stops at 19.
+_TILE_MAX_Z_DEFAULT = 19
+
+_CACHE_MAX = 4096
+
+
+def _env(name, default):
+    return (os.environ.get(name) or "").strip() or default
+
+
+def _env_int(name, default):
+    try:
+        n = int((os.environ.get(name) or "").strip())
+        return n if n > 0 else default
+    except (TypeError, ValueError):
+        return default
+
+
+def provider_config():
+    """The whole seam as one dict. `GET /geo/providers` serves it and the gate reads it."""
+    return {
+        "tiles": {
+            "url": _env("AIOS_MAP_TILE_URL", _TILE_URL_DEFAULT),
+            "attribution": _env("AIOS_MAP_TILE_ATTRIBUTION", _TILE_CREDIT_DEFAULT),
+            "attributionUrl": _env("AIOS_MAP_TILE_ATTRIBUTION_URL", _TILE_CREDIT_HREF_DEFAULT),
+            "maxZoom": _env_int("AIOS_MAP_TILE_MAX_Z", _TILE_MAX_Z_DEFAULT),
+        },
+        "geocode": {
+            "available": True,
+            "maxBatch": MAX_BATCH,
+            "minIntervalMs": _env_int("AIOS_GEOCODE_MIN_INTERVAL_MS", _MIN_INTERVAL_MS_DEFAULT),
+            # ⭐⭐ THE NUMBER THE SURFACE MUST QUOTE, AND IT IS NOT THE RATE LIMIT.
+            # T37 asks for the estimated wait to be shown BEFORE a run. The obvious source is
+            # `minIntervalMs`, and it is wrong: 1.1 s is a floor on POLITENESS, not a prediction of
+            # LATENCY. One real lookup was MEASURED at 3.28 s end to end on 2026-08-19. Quoting the
+            # limit would promise a minute and take three, and a progress estimate that runs out
+            # before the work does reads as a hang rather than as a wait.
+            "secondsPerAddress": float(_env("AIOS_GEOCODE_SECONDS_EACH", "3.3")),
+            "attribution": _env("AIOS_GEOCODE_ATTRIBUTION", _TILE_CREDIT_DEFAULT),
+        },
+        "route": {
+            "available": True,
+            "attribution": _env("AIOS_ROUTE_ATTRIBUTION", "Routing by OSRM"),
+        },
+    }
+
+
+# ------------------------------------------------------------------ the throttle
+#
+# ⚠ ONE lock and ONE timestamp for the whole process, shared by geocoding and routing, because the
+# rate limit belongs to the SERVICE and not to the endpoint. Two independent throttles would each
+# stay honest and together double the published rate.
+
+_gate = threading.Lock()
+_last_call = [0.0]
+
+
+def _throttle(min_interval_ms):
+    """Block until the minimum interval since the last outbound call has elapsed.
+
+    Returns the seconds actually waited, so a caller can report the wait rather than hide it."""
+    wait = 0.0
+    with _gate:
+        gap = min_interval_ms / 1000.0
+        now = time.monotonic()
+        due = _last_call[0] + gap
+        if now < due:
+            wait = due - now
+            time.sleep(wait)
+        _last_call[0] = time.monotonic()
+    return wait
+
+
+# --------------------------------------------------------------------- the cache
+
+_cache = OrderedDict()
+_cache_lock = threading.Lock()
+
+
+def _cache_key(q, country):
+    return (re.sub(r"\s+", " ", str(q or "")).strip().lower(), str(country or "").strip().lower())
+
+
+def _cache_get(key):
+    with _cache_lock:
+        if key not in _cache:
+            return None
+        _cache.move_to_end(key)
+        return _cache[key]
+
+
+def _cache_put(key, value):
+    with _cache_lock:
+        _cache[key] = value
+        _cache.move_to_end(key)
+        while len(_cache) > _CACHE_MAX:
+            _cache.popitem(last=False)
+
+
+def geocode_one(address, country=None, timeout=12):
+    """One address to {lat, lon, label} or None.
+
+    ⛔ THE ONLY PLACE AN OUTBOUND GEOCODE HAPPENS. `ai_enrich.py`'s geocode field calls this rather
+    than reaching for `requests` itself, so the throttle and the cache cannot be walked around by a
+    second caller. A cache hit costs no request and no wait."""
+    q = re.sub(r"\s+", " ", str(address or "")).strip()
+    if not q:
+        return None
+    key = _cache_key(q, country)
+    hit = _cache_get(key)
+    if hit is not None:
+        return dict(hit) if hit else None
+
+    cfg = provider_config()["geocode"]
+    _throttle(cfg["minIntervalMs"])
+    params = {"q": q, "format": "jsonv2", "limit": 1}
+    if country:
+        params["countrycodes"] = str(country).strip().lower()
+    try:
+        r = requests.get(
+            _env("AIOS_GEOCODE_URL", _GEOCODE_URL_DEFAULT),
+            params=params,
+            headers={"User-Agent": _env("AIOS_GEO_USER_AGENT", _UA_DEFAULT),
+                     "Accept": "application/json"},
+            timeout=timeout,
+        )
+        r.raise_for_status()
+        rows = r.json()
+    except Exception:
+        # ⚠ A transport failure is NOT cached. Caching it would turn one bad minute into a
+        # permanently empty column that no re-run could ever repair.
+        return None
+    if not isinstance(rows, list) or not rows:
+        # A genuine "no such place" IS cached, as a negative: asking again gets the same answer and
+        # spends another second of a shared service's budget to hear it.
+        _cache_put(key, {})
+        return None
+    top = rows[0] or {}
+    try:
+        lat = float(top.get("lat"))
+        lon = float(top.get("lon"))
+    except (TypeError, ValueError):
+        _cache_put(key, {})
+        return None
+    if not (-90 <= lat <= 90) or not (-180 <= lon <= 180):
+        _cache_put(key, {})
+        return None
+    out = {"lat": lat, "lon": lon, "label": str(top.get("display_name") or q)}
+    _cache_put(key, out)
+    return dict(out)
+
+
+# ---------------------------------------------------------------------- the doors
+
+
+@router.get("/geo/providers")
+def geo_providers(session: Session = Depends(require_session)):
+    """What the map should draw with, and who to credit for it.
+
+    Session gated like every other door here. The values are not secret, but an unauthenticated
+    endpoint on this app is a door somebody eventually hangs something else on."""
+    return provider_config()
+
+
+@router.post("/geo/geocode")
+def geo_geocode(body: dict = Body(...), session: Session = Depends(require_session)):
+    """Turn a bounded list of addresses into coordinates.
+
+    ⛔ Takes ADDRESSES, never a table key, a view id or a filter. There is deliberately no shape of
+    request that means "geocode everything", which is R3 expressed as an API rather than as a
+    warning."""
+    items = body.get("addresses")
+    # ⭐ THE SECOND SHAPE, AND IT EXISTS TO KEEP ONE COMPOSER. A caller may send whole RECORDS plus
+    # the geocode field's config instead of finished address strings, and the server builds the
+    # query with `ai_enrich.geocode_query`. The alternative was a TypeScript twin of that function
+    # on the client, and an address composer that exists twice will disagree the first time either
+    # copy learns about a new column ([[one-question-two-normalizers]]) -- which is exactly the trap
+    # B's measured `New York (US)` suffix would spring, silently, in whichever copy forgot.
+    if items is None:
+        records = body.get("records")
+        cfg = body.get("config") or {}
+        if isinstance(records, list) and records:
+            import ai_enrich
+            items = []
+            for rec in records:
+                if not isinstance(rec, dict):
+                    continue
+                q = ai_enrich.geocode_query(rec.get("row") or {}, cfg)
+                # ⛔ A record with no usable address is REPORTED, not dropped: it comes back
+                # `found: false` with an empty address, so the caller can name it on screen instead
+                # of quietly returning fewer answers than it asked questions.
+                items.append({"key": rec.get("key"), "address": q})
+            if not body.get("country") and cfg.get("country"):
+                body = {**body, "country": cfg.get("country")}
+    if not isinstance(items, list) or not items:
+        raise err(400, "no_addresses", "Send at least one address to look up.")
+    if len(items) > MAX_BATCH:
+        raise err(
+            400,
+            "batch_too_large",
+            f"Look up at most {MAX_BATCH} addresses per request. "
+            f"The map sends them in batches of {MAX_BATCH} so the wait stays visible.",
+        )
+    country = body.get("country")
+    out = []
+    started = time.monotonic()
+    for raw in items:
+        if isinstance(raw, dict):
+            key, addr = raw.get("key"), raw.get("address")
+        else:
+            key, addr = None, raw
+        # ⛔ AN EMPTY QUERY COSTS NO REQUEST AND CARRIES ITS OWN REASON. Nominatim's policy is a
+        # budget shared with everyone else using it, and asking it to place "" would spend a second
+        # of that budget to be told nothing. `reason` is what lets the surface say "no address on
+        # file" rather than "not found", which are different facts and want different actions.
+        if not str(addr or "").strip():
+            out.append({"key": key, "address": "", "found": False, "lat": None, "lon": None,
+                        "label": None, "reason": "no_address"})
+            continue
+        hit = geocode_one(addr, country=country)
+        out.append({"key": key, "address": str(addr or ""), "found": bool(hit),
+                    "reason": None if hit else "not_found",
+                    "lat": hit["lat"] if hit else None,
+                    "lon": hit["lon"] if hit else None,
+                    "label": hit["label"] if hit else None})
+    elapsed = time.monotonic() - started
+    return {"results": out,
+            "found": sum(1 for r in out if r["found"]),
+            "asked": len(out),
+            "secondsElapsed": round(elapsed, 2),
+            "attribution": provider_config()["geocode"]["attribution"]}
+
+
+@router.post("/geo/route")
+def geo_route(body: dict = Body(...), session: Session = Depends(require_session)):
+    """Road distance, duration and the drawn line, for stops ALREADY put in order.
+
+    ⭐ THE ORDERING IS NOT DONE HERE. `mapProjection.planRoute` sequences the stops on the client,
+    for free, and keeps working when this service does not answer. This door adds the half that
+    arithmetic cannot produce: what the ROADS actually cost. Splitting it that way is why the Start
+    picker and the round-trip toggle keep working with no network at all."""
+    stops = body.get("stops")
+    if not isinstance(stops, list) or len(stops) < 2:
+        raise err(400, "too_few_stops", "A route needs at least two stops with a location.")
+    if len(stops) > 25:
+        raise err(400, "too_many_stops",
+                   "Route at most 25 stops at once. Narrow the selection and try again.")
+    pairs = []
+    for s in stops:
+        try:
+            lat, lon = float(s["lat"]), float(s["lon"])
+        except (TypeError, ValueError, KeyError, IndexError):
+            raise err(400, "bad_stop", "Every stop needs a numeric latitude and longitude.")
+        if not (-90 <= lat <= 90) or not (-180 <= lon <= 180):
+            raise err(400, "bad_stop", "Every stop needs a latitude and longitude on the globe.")
+        pairs.append(f"{lon:.6f},{lat:.6f}")
+
+    base = _env("AIOS_ROUTE_URL", _ROUTE_URL_DEFAULT)
+    _throttle(_env_int("AIOS_GEOCODE_MIN_INTERVAL_MS", _MIN_INTERVAL_MS_DEFAULT))
+    try:
+        r = requests.get(
+            base.rstrip("/") + "/" + ";".join(pairs),
+            params={"overview": "simplified", "geometries": "geojson", "steps": "false"},
+            headers={"User-Agent": _env("AIOS_GEO_USER_AGENT", _UA_DEFAULT)},
+            timeout=20,
+        )
+        r.raise_for_status()
+        data = r.json()
+    except Exception:
+        raise err(502, "route_service_unavailable",
+                   "The routing service did not answer. The stop order and the straight line "
+                   "distance are still on the map.")
+    routes = (data or {}).get("routes") or []
+    if not routes:
+        raise err(
+            502,
+            "no_route",
+            "No road route connects these stops. They may be on different land masses, or one of "
+            "them may be far from any road.",
+        )
+    top = routes[0]
+    geom = ((top.get("geometry") or {}).get("coordinates")) or []
+    line = []
+    for c in geom:
+        try:
+            line.append([float(c[0]), float(c[1])])
+        except (TypeError, ValueError, IndexError):
+            continue
+    return {
+        "km": round(float(top.get("distance") or 0.0) / 1000.0, 1),
+        "minutes": int(round(float(top.get("duration") or 0.0) / 60.0)),
+        "line": line,
+        "attribution": provider_config()["route"]["attribution"],
+    }

api/routes_oauth.py

@@ -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_records.py

@@ -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

@@ -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

@@ -1,452 +1,458 @@
-"""routes_shares.py — the manage-access surface (wave 20, owner ruling R10, contract C-SHARE).
-
-    GET  /api/v1/share/{kind}/{oid}      -> {owner, entries:[{user,role}], mayAdminister, people}
-    PUT  /api/v1/share/{kind}/{oid}      <- {entries:[{user,role}]}   (REPLACES the set)
-    GET  /api/v1/share/mine              -> {view:[id], folder:[id], database:[id]}
-
-`kind` ∈ view | folder | database | field. Roles are `view` | `edit` — the same two words the
-view rail already speaks, now extended to folders, databases and COLUMNS so there is ONE
-vocabulary in the UI (R10: "the same picker views use").
-
-⭐⭐ **W38-T16 — `field` IS THE FOURTH KIND, AND ITS `oid` IS TOPIC-QUALIFIED: `"<table_key>:<field_key>"`**
-(`shares.field_oid`). A bare column key repeats across databases — `notes` exists on a dozen —
-so a grant stored under one would admit the grantee to every `notes` column in the tenant at
-once. ⛔ THREE functions in this file branch on kind and ALL THREE need the new one, which is not
-obvious because only two of them fail loudly: `_owns_object` (without it a column's own creator
-is 404'd trying to share the thing they just made) and `_object_ref` (without it `route` is None,
-`_notify_new_grantees` returns early, and the grantee is **granted and never told** — owner item
-18's silent half, reopened one kind over). `_can_see_object` stays deliberately CLOSED for
-anything that is not a view.
-
-⛔ **RE-SHARING IS THE OWNER'S, AND THAT IS ENFORCED HERE, NOT IN THE CLIENT.** `PUT` requires
-`shares.may_administer` (owner or admin). A collaborator with `edit` may change an object's
-CONTENT and may not change who else can reach it — otherwise anyone you shared a view with could
-widen it to everyone, or grant themselves ownership and lock you out. The client greys the editor
-for non-administrators; that is a courtesy, and this check is the wall.
-
-⚠ **THE GRANT NEVER WIDENS PAST THE MODULE WALL — ON A GOVERNED MODULE.** `*` ("everyone") means
-every account that can already open the surface: `require_session` plus the topic's own gate run
-first, and for `customer_data` / `product_data` the receiver's own row scope and hidden-field
-closure run BEFORE any foreign view is merged. Sharing there can only narrow-or-equal the set that
-could already reach the data ([[aios-permissioning]]).
-
-⛔⛔ **AND THAT SENTENCE IS FALSE FOR `kind='database'`, WHICH IS WHY IT NOW SAYS "ON A GOVERNED
-MODULE" (W32-T26, audit S-8).** `routes_admin._PERM_MODULES` is `("customer_data","product_data")`
-and `_clean_perms` **400s** on anything else, so **no row filter and no hidden field can even be
-DECLARED for a `ut_*` database** — `routes_tables.py` makes zero `perm_scope` calls and passes
-`hidden_keys=frozenset()`. There is no module wall behind a user table for a grant to be bounded
-by: **this registry IS the wall.** So a `database` grant is ALL-OR-NOTHING — every row, every
-column — and an `*` database grant admits every account in the tenant to all of it.
-That is a real capability, deliberately kept; what was wrong was a docstring promising a second
-wall that does not exist for this kind. Scoping user tables is booked, not done
-(`waves/wave32/sharing-audit.md` S-8).
-
-⚠ **TWO SYSTEMS ANSWER "IS THIS SHARED", AND THEY ARE NOT THE SAME ONE (audit S-4).** THIS
-registry decides who appears in *"Shared with me"* and who may re-share. **`table_store.is_shared`
-— the view's own `permissions` — is what actually decides who may OPEN a view.** A grant here
-whose object is invisible under that one is a row in a list that opens a refusal, which is what
-made item 18 worth auditing. `_entries_or_400` closes the common cause (a name nobody has), but
-the two vocabularies are still two.
-"""
-from fastapi import APIRouter, Body, Depends
-
-import core.shares as shares
-import core.users as users
-from deps import Session, err, require_session
-# ⭐ W32-T28 (C3) — the SHARE notification's topic word, imported from the module that CLASSIFIES
-# it (`routes_alerts.notification_view`) rather than typed again here. The producer and the
-# reader agreeing about one string is the whole difference between an Inbox row that opens the
-# shared database and one that is quietly unclickable.
-from routes_alerts import SHARE_TOPIC as _SHARE_TOPIC
-
-router = APIRouter(prefix="/api/v1")
-
-
-def _kind_or_400(raw):
-    try:
-        return shares._check_kind(raw)
-    except ValueError as e:
-        raise err(400, "bad_kind", str(e))
-
-
-# ── ⭐⭐ WAVE 32 · T26 (owner item 18, ruling R12) — THE WALL THIS FILE SAID IT HAD ─────────────
-#
-# `put_share`'s comment used to justify the first-claim rule with *"reaching this route at all
-# means passing the surface's own wall"*. **There was no such wall.** `kind` and `oid` are free
-# strings off the URL and the only dependency was `require_session`, so any signed-in account
-# could `PUT` a grant on an id it had never seen. Because the 403 sat behind `if rec["owner"]`,
-# an object with no grant record skipped the check entirely and the caller was stamped OWNER —
-# sticky, so **the real creator was then refused on their own view, permanently.** Driven, not
-# argued: `waves/wave32/sharing-audit.md` S-1 carries the four-step transcript.
-#
-# ⚠ AND IT WAS SILENT ON BOTH SIDES. The claimant does not even see the object in their own
-# "Shared with me" (`shared_with` excludes what you own), so nothing appears anywhere until the
-# victim next opens the dialog.
-
-#: The built-in grid topics. A view or folder lives in `{topic}_table_workspace`, and the share
-#: route is not told which topic — so resolving one means asking each.
-_BUILTIN_TOPICS = ("customer", "product")
-
-
-def _topics(session):
-    """Every topic whose workspace could hold a view or folder for this tenant.
-
-    ⚠ `all_defs`, never `all_tables` — the latter is the whole 28.6 MB row payload (~703 ms on
-    tenant #0) to answer a question about KEYS (D-185).
-    """
-    try:
-        import core.user_tables as ut
-        return (*_BUILTIN_TOPICS, *(ut.all_defs(st=session.runtime) or {}))
-    except Exception:                                       # noqa: BLE001
-        return _BUILTIN_TOPICS
-
-
-def _owns_object(session, kind, oid):
-    """May this caller CLAIM an object that has no grant record yet — i.e. do they own it?
-
-    ⛔ THIS GUARDS THE CLAIM, NOT THE READ, AND THAT IS DELIBERATE. Resolving a view means asking
-    each topic's workspace in turn, which is N store reads; making every share call pay that
-    would put a loop on a route the manage-access dialog opens. The dangerous path is the one
-    where a caller is about to be stamped OWNER of something nobody owns — so the resolution runs
-    exactly there, and the common path (a record exists, `may_administer` decides) is untouched.
-    """
-    if session.admin:
-        return True
-    if kind == "field":
-        # ⭐⭐ W38-T16 — A COLUMN'S OWNER IS ITS `createdBy`, WHICH THE CREATE DOOR ALREADY STAMPS
-        # (`routes_tables.patch_shared_cell`) and the DELETE door already reads as its wall (R8 /
-        # D-172: creator-or-admin). Read from the same place by all three, so a column cannot be
-        # deletable by one person and shareable by another.
-        # ⚠ THIS BRANCH IS NOT OPTIONAL AND ITS ABSENCE FAILS SILENTLY IN THE WORST DIRECTION:
-        # a brand-new column has no grant record, so `put_share` falls to this predicate — and
-        # without it the column's own creator is answered `404 no_object` on the first attempt to
-        # share the thing they just made.
-        table_key, field_key = shares.split_field_oid(oid)
-        if not table_key:
-            return False
-        try:
-            import core.shared_overlay as shared_overlay
-            defn = (shared_overlay.fields(table_key, st=session.runtime) or {}).get(field_key)
-        except Exception:                                   # noqa: BLE001
-            return False
-        return bool(defn) and str(defn.get("createdBy") or "") == str(session.uname)
-    if kind == "database":
-        # ⚠ `may_open` is THE resolver for a user table (its own docstring says so) and already
-        # admits creator, admin, or a `database` grantee. Re-implementing "who owns a table"
-        # here would be the second definition this wave keeps finding.
-        try:
-            import core.user_tables as ut
-            return bool(ut.may_open(oid, session.uname, is_admin=session.admin,
-                                    st=session.runtime))
-        except Exception:                                   # noqa: BLE001
-            return False
-    try:
-        import core.table_store as table_store
-    except Exception:                                       # noqa: BLE001
-        return False
-    for topic in _topics(session):
-        try:
-            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
-            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
-        except Exception:                                   # noqa: BLE001
-            continue
-        if hit:
-            # `find_view`/`find_folder` answer `(owner_username, …)`. The claim belongs to the
-            # person whose personal stratum holds it — anybody else reaching this line is
-            # exactly the case S-1 describes.
-            return str(hit[0]) == str(session.uname)
-    return False
-
-
-def _can_see_object(session, kind, oid):
-    """May this caller READ an object's grant list — i.e. can they reach the object at all?
-
-    ⛔⛔ THIS IS DELIBERATELY WIDER THAN {@link _owns_object}, AND CONFLATING THE TWO IS A
-    REGRESSION I SHIPPED AND CAUGHT. The first version of T26 guarded BOTH doors with the
-    ownership test, which reads sensibly and is wrong for the read, because **`find_view` searches
-    PERSONAL STRATA ONLY** (its own docstring says so). So a view living in alice's stratum with
-    `permissions.edit = "collaborative"` and no grant record yet — a view bob **can open and edit
-    in the grid** — answered `404` when bob opened its manage-access dialog. Measured before
-    fixing: `table_store._may_see(view, "bob") is True` while `GET /share/view/vc` said
-    `404 no_object`.
-    ⚠ THAT IS THE AUDIT'S OWN S-4 BITING THE AUDIT'S OWN FIX: two systems answer "is this shared",
-    and the wall consulted the grant registry (system A) plus stratum ownership, never the view's
-    `permissions` (system B) — which is the one that actually decides who may OPEN it.
-    ⚠ And it hides the ANSWER, not just the editor. `ViewSidebar`'s Share row is deliberately not
-    gated on edit rights because *"hiding the row from everyone else would hide the ANSWER too —
-    'who has this?' is a fair question for anyone the view was shared with"*. A 404 there tells a
-    legitimate collaborator their view does not exist.
-
-    ⛔ THE CLAIM KEEPS THE NARROW TEST. Being able to SEE an object must not let you become its
-    owner — that is S-1, and widening this predicate onto `put_share` would re-open it.
-    """
-    if _owns_object(session, kind, oid):
-        return True
-    if kind != "view":
-        # A folder carries no per-object visibility flag of its own, and a database's `may_open`
-        # (inside `_owns_object`) already admits grantees. Nothing wider to ask.
-        # ⭐ W38-T16 — AND `field` KEEPS THIS CLOSED, DELIBERATELY. A grantee never reaches here:
-        # `get_share` tests `role is None` first and a grant answers a role, so the only caller
-        # left is an account with no relationship to the column at all. Widening it would let any
-        # signed-in session enumerate who holds which column on a database they cannot open.
-        return False
-    try:
-        import core.table_store as table_store
-        for topic in _topics(session):
-            hit = table_store.make(f"{topic}_table_workspace", st=session.runtime).find_view(oid)
-            if hit:
-                return bool(table_store._may_see(hit[1] if len(hit) > 1 else {},
-                                                 session.uname, is_admin=session.admin))
-    except Exception:                                       # noqa: BLE001
-        return False
-    return False
-
-
-def _entries_or_400(session, entries):
-    """Validate a grant list against the tenant's REAL, ACTIVE accounts — and refuse BY NAME.
-
-    ⛔ `core.shares._clean_entries` silently drops junk, and its docstring argues that correctly:
-    a UI mid-save must not lose the whole list to one malformed row. **But it validates the SHAPE
-    of a string and the role word — never that the user EXISTS, is ACTIVE, or is in this tenant**,
-    so a typo'd name is stored, reported as a successful save, and never reaches anybody. The
-    sharer believes the person has access. That is item 18's plain reading.
-    ⚠ The correct population is computed THREE FUNCTIONS BELOW and served to the picker
-    (`_people`). One route, two populations, and the write door was the permissive one.
-    ⚠ `*` (everyone) is not a user and is admitted deliberately — it is R10's vocabulary for
-    "every account that can already open the surface".
-    """
-    known = {p["username"].strip().lower() for p in _people(session.tenant)}
-    unknown = []
-    for e in entries or ():
-        if not isinstance(e, dict):
-            continue
-        user = str(e.get("user") or "").strip().lower()
-        if user and user != shares.EVERYONE and user not in known:
-            unknown.append(user)
-    if unknown:
-        raise err(400, "unknown_people",
-                  "no active account in this workspace is named "
-                  + ", ".join(sorted(set(unknown)))
-                  + ". Nothing was shared. Pick people from the list rather than typing a name.")
-
-
-@router.get("/share/mine")
-def my_shares(session: Session = Depends(require_session)):
-    """Everything shared WITH me, by kind — the "Shared with me" rail section (R10).
-
-    Registered before `/share/{kind}/{oid}` so the literal path wins the match; FastAPI resolves
-    in declaration order and `mine` would otherwise be read as a `kind`, answering 400 for a URL
-    that is not malformed at all.
-    """
-    return shares.shared_with(session.uname, st=session.runtime)
-
-
-@router.get("/share/{kind}/{oid}")
-def get_share(kind: str, oid: str, session: Session = Depends(require_session)):
-    kind = _kind_or_400(kind)
-    rec = shares.grants(kind, oid, st=session.runtime)
-    role = shares.role_for(kind, oid, session.uname, is_admin=session.admin, st=session.runtime)
-    may_admin = shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
-                                      st=session.runtime)
-    # ⭐ W32-T26 (audit S-3) — A STRANGER LEARNS NOTHING. This route used to answer for ANY id:
-    # who owns it, everyone it is granted to, and the tenant's whole username↔name directory —
-    # to any signed-in session, about objects it cannot open. Now a caller with no role on an
-    # object must prove they can reach it, and gets a 404 otherwise: the same answer a
-    # non-existent id gives, so the route cannot be used to probe which ids are real.
-    # ⚠ `role is None` is the cheap pre-test, so the N-topic resolution below runs only for a
-    # caller who has no relationship with the object at all.
-    if role is None and not _can_see_object(session, kind, oid):
-        raise err(404, "no_object", "no such item, or it is not shared with this account")
-    return {
-        **rec,
-        "role": role,
-        "mayAdminister": may_admin,
-        # ⚠ WAVE 21 (C1 identity fix): grant entries BIND on USERNAMES, so the picker must carry
-        # them. `assignable_people` serves bare display names because `user`-kind CELLS store
-        # display names — that list's shape cannot change without migrating cell values — so
-        # this route serves objects of its own. Existing grants that were written as lowercased
-        # display names are normalised by the wave-21 cleanup script.
-        # ⭐ W32-T26 (audit S-3) — the roster is the EDITOR's data, so it rides only for a caller
-        # who may open the editor. A read-only grantee gets the grant list (their fair question is
-        # "who else has this?") and not a directory of every account in the workspace.
-        "people": _people(session.tenant) if may_admin else [],
-    }
-
-
-def _people(tenant):
-    """[{username, name}] for this tenant — same population as `assignable_people`, with the
-    BINDING identity alongside the display one."""
-    try:
-        reg = users.registry() or {}
-    except Exception:
-        return []
-    want = str(tenant or '').strip().lower()
-    out = []
-    for uname, u in reg.items():
-        if not isinstance(u, dict) or u.get('active') is False:
-            continue
-        if want and str(u.get('tenant') or 'royal-imports').strip().lower() != want:
-            continue
-        out.append({"username": str(uname), "name": str(u.get('name') or uname)})
-    return sorted(out, key=lambda p: p["name"].lower())
-
-
-@router.put("/share/{kind}/{oid}")
-def put_share(kind: str, oid: str, body: dict = Body(default=None),
-              session: Session = Depends(require_session)):
-    kind = _kind_or_400(kind)
-    body = body or {}
-    rec = shares.grants(kind, oid, st=session.runtime)
-    # An object with NO grant record yet has no owner — the first person to share it claims it.
-    # That is safe because reaching this route at all means passing the surface's own wall, and
-    # the alternative (refusing until somebody seeds an owner) would make a brand-new folder
-    # unshareable by the person who just made it.
-    if rec["owner"]:
-        if not shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
-                                     st=session.runtime):
-            raise err(403, "not_owner",
-                      "only the owner of this item (or an administrator) can change who it is "
-                      "shared with")
-    # ⛔⛔ W32-T26 (audit S-1) — THE CLAIM NOW HAS A PRECONDITION. An object with no grant record
-    # is still claimed by the first person to share it — that rule is right, and refusing until
-    # somebody seeds an owner would make a brand-new folder unshareable by the person who just
-    # made it. What was missing is the half the old comment ASSERTED and the code never did: the
-    # claimant has to be able to reach the object. Without this, any signed-in account could
-    # stamp itself owner of an id it had never seen and lock the real creator out for good.
-    elif not _owns_object(session, kind, oid):
-        raise err(404, "no_object", "no such item, or it is not shared with this account")
-    entries = body.get("entries")
-    if not isinstance(entries, list):
-        raise err(400, "bad_entries",
-                  "entries must be a list of {user, role}. Send [] to un-share, which is how "
-                  "revoking is expressed")
-    _entries_or_400(session, entries)
-    out = shares.set_grants(kind, oid, entries, owner=rec["owner"] or session.uname,
-                            st=session.runtime)
-    _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
-    return out
-
-
-def _notify_new_grantees(session, kind, oid, before, after):
-    """⭐⭐ W32-T28 (owner item 18's last clause, contract C3) — tell the RECEIVER, in their Inbox.
-
-    Owner item 18 ends *"being shared a database notifies the receiver"*. Until now sharing was
-    silent: the grant landed in a rail section the receiver had to notice on their own, which is
-    why "I shared it with you" and "I never saw it" were both true.
-
-    ⛔ WRITTEN ON THE SHARE, NEVER POLLED. `/notifications` re-evaluates view-ALERTS on read
-    because an alert is a live question about rows; a share is an EVENT that happened once, and
-    polling for it would mean re-deriving "was this new?" on every inbox open — the diff below
-    only exists here, at the moment the set changes.
-
-    ⚠ ONLY THE NEWLY ADDED. `PUT` REPLACES the whole entry set (revoking is expressed by absence),
-    so every save re-sends everyone who was already there. Diffing against `before` is what stops
-    a rename or a role change from ringing the bell for people whose access did not change.
-    ⚠ `*` IS NOT NOTIFIED: there is no user to name, and minting one notification per account in
-    the tenant on a single click is a broadcast nobody asked for. The rail still shows it.
-    ⚠ IT NEVER RAISES. A notification that fails must not fail the share that triggered it — the
-    grant is the user's actual intent, and `core.alerts.notify` writes with `flush='async'`.
-    """
-    try:
-        was = {e.get("user") for e in (before or ()) if isinstance(e, dict)}
-        fresh = [str(e.get("user")) for e in (after or ())
-                 if isinstance(e, dict) and e.get("user") not in was
-                 and e.get("user") != shares.EVERYONE]
-        if not fresh:
-            return
-        import core.alerts as alerts
-
-        label, route, view_id = _object_ref(session, kind, oid)
-        if not route:
-            # ⛔ NO ROUTE, NO NOTIFICATION — the receiver would get a row that opens nothing, and
-            # `notification_view` would have to invent a target. Silence is the honest answer
-            # here; the rail still shows the grant under "Shared with me".
-            return
-        sharer = str(session.user.get("name") or session.uname)
-        for user in fresh:
-            # ⚠ THE SHAPE IS `routes_alerts.notification_view`'s SHARE BRANCH, and the two must
-            # agree or the Inbox row is unclickable: `topic` selects the branch and `key` becomes
-            # `alertId`, which that branch reads as the id to open. Both constants are IMPORTED
-            # from there rather than typed again — one vocabulary, one owner.
-            # ⭐⭐ W33-T28 (`ASK C-14`, answered) — `actor` IS THE SENDER, AND IT IS THE ONLY WAY
-            # THE INBOX CAN NAME ONE. An alert and an automation have no person behind them and
-            # are honestly named by their machine; a SHARE has a real person, and only this call
-            # site knows who. ⛔ It is passed as its OWN field rather than recovered from the
-            # `detail` prose below: a sender parsed out of "<name> shared this with you" breaks
-            # the first time the sentence is reworded, silently, in the header
-            # [[grep-output-is-not-source]]. The prose stays as the body; this is the From.
-            alerts.notify(user, label, topic=_SHARE_TOPIC, key=route, row_id=view_id,
-                          detail=f"{sharer} shared this with you", actor=sharer,
-                          st=session.runtime)
-    except Exception:                                       # noqa: BLE001
-        return
-
-
-def _object_ref(session, kind, oid):
-    """`(label, route, view_id)` — what to CALL the shared thing, and where it OPENS.
-
-    ⛔ THE ROUTE IS RESOLVED HERE, NOT SHAPED IN THE CONSUMER, AND THE FIRST VERSION GOT IT
-    WRONG: it put the raw `oid` in the notification's key, so a shared VIEW produced
-    `target: {module: "database", id: "view_42"}` — an instruction to open a database named
-    `view_42`. It read perfectly in the payload and would have opened nothing. **A view is not
-    addressable on its own; it is a SELECTION inside a topic's grid**, so the pair is what has to
-    travel. Caught by looking at the notification the driver actually produced, not by reading
-    the code back.
-
-    ⚠ `label` never falls back to a raw id. A notification headed `ut_leads_3f2a` tells the
-    receiver nothing they can act on, and the id is already in the target.
-    ⚠ An unresolvable object answers `route=None`, and the caller then sends NOTHING rather than
-    a row that opens nowhere.
-    """
-    try:
-        if kind == "field":
-            # ⭐⭐ W38-T16 — A COLUMN IS NOT ADDRESSABLE ON ITS OWN, exactly as a view is not: it
-            # is a column INSIDE a database, so the target that travels is the DATABASE. Without
-            # this branch the function falls through to the view/folder loop, finds nothing,
-            # answers `route=None` — and `_notify_new_grantees` returns EARLY. The grant lands and
-            # the receiver is never told, which is the silent half of owner item 18 reopened one
-            # kind over.
-            from routes_alerts import route_for_topic
-            table_key, field_key = shares.split_field_oid(oid)
-            if not table_key:
-                return ("A column", None, "")
-            try:
-                import core.shared_overlay as shared_overlay
-                defn = (shared_overlay.fields(table_key, st=session.runtime) or {}).get(field_key)
-            except Exception:                               # noqa: BLE001
-                defn = None
-            label = str((defn or {}).get("label") or "").strip() or field_key
-            # ⚠ TWO SPELLINGS REACH THIS LINE AND ONE MAP ANSWERS BOTH. `shared_overlay` is keyed
-            # by whatever the calling door already held: a `ut_*` database uses its bare key,
-            # while a registry topic uses `<topic>_table_workspace` (`product_data.TABLE_KEY`).
-            # `route_for_topic` speaks the GRID SCOPE vocabulary (`customer`, not
-            # `customer_data`), so the suffix comes off before it is asked — rather than a second
-            # route table being written here, which is how the two come apart.
-            _WS = "_table_workspace"
-            scope = table_key[:-len(_WS)] if table_key.endswith(_WS) else table_key
-            return (label, route_for_topic(scope) or None, "")
-        if kind == "database":
-            import core.user_tables as ut
-            defn = (ut.all_defs(st=session.runtime) or {}).get(str(oid)) or {}
-            # A user table IS its own route key in both vocabularies (`route_for_topic`).
-            return (str(defn.get("label") or "").strip() or "A database", str(oid), "")
-        import core.table_store as table_store
-        from routes_alerts import route_for_topic
-        for topic in _topics(session):
-            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
-            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
-            if not hit:
-                continue
-            route = route_for_topic(topic)
-            if not route:
-                break
-            row = hit[1] if len(hit) > 1 else {}
-            name = str((row or {}).get("name") or "").strip()
-            # ⚠ Only a VIEW carries a selection. A folder is a rail grouping, so the target opens
-            # the grid and stops there rather than naming a view the receiver did not get.
-            return (name or ("A view" if kind == "view" else "A folder"),
-                    route, str(oid) if kind == "view" else "")
-    except Exception:                                       # noqa: BLE001
-        pass
-    return ({"view": "A view", "folder": "A folder",
-             "field": "A column"}.get(kind, "An item"), None, "")
+"""routes_shares.py — the manage-access surface (wave 20, owner ruling R10, contract C-SHARE).
+
+    GET  /api/v1/share/{kind}/{oid}      -> {owner, entries:[{user,role}], mayAdminister, people}
+    PUT  /api/v1/share/{kind}/{oid}      <- {entries:[{user,role}]}   (REPLACES the set)
+    GET  /api/v1/share/mine              -> {view:[id], folder:[id], database:[id]}
+
+`kind` ∈ view | folder | database | field. Roles are `view` | `edit` — the same two words the
+view rail already speaks, now extended to folders, databases and COLUMNS so there is ONE
+vocabulary in the UI (R10: "the same picker views use").
+
+⭐⭐ **W38-T16 — `field` IS THE FOURTH KIND, AND ITS `oid` IS TOPIC-QUALIFIED: `"<table_key>:<field_key>"`**
+(`shares.field_oid`). A bare column key repeats across databases — `notes` exists on a dozen —
+so a grant stored under one would admit the grantee to every `notes` column in the tenant at
+once. ⛔ THREE functions in this file branch on kind and ALL THREE need the new one, which is not
+obvious because only two of them fail loudly: `_owns_object` (without it a column's own creator
+is 404'd trying to share the thing they just made) and `_object_ref` (without it `route` is None,
+`_notify_new_grantees` returns early, and the grantee is **granted and never told** — owner item
+18's silent half, reopened one kind over). `_can_see_object` stays deliberately CLOSED for
+anything that is not a view.
+
+⛔ **RE-SHARING IS THE OWNER'S, AND THAT IS ENFORCED HERE, NOT IN THE CLIENT.** `PUT` requires
+`shares.may_administer` (owner or admin). A collaborator with `edit` may change an object's
+CONTENT and may not change who else can reach it — otherwise anyone you shared a view with could
+widen it to everyone, or grant themselves ownership and lock you out. The client greys the editor
+for non-administrators; that is a courtesy, and this check is the wall.
+
+⚠ **THE GRANT NEVER WIDENS PAST THE MODULE WALL — ON A GOVERNED MODULE.** `*` ("everyone") means
+every account that can already open the surface: `require_session` plus the topic's own gate run
+first, and for `customer_data` / `product_data` the receiver's own row scope and hidden-field
+closure run BEFORE any foreign view is merged. Sharing there can only narrow-or-equal the set that
+could already reach the data ([[aios-permissioning]]).
+
+⛔⛔ **AND THAT SENTENCE IS FALSE FOR `kind='database'`, WHICH IS WHY IT NOW SAYS "ON A GOVERNED
+MODULE" (W32-T26, audit S-8).** `routes_admin._PERM_MODULES` is `("customer_data","product_data")`
+and `_clean_perms` **400s** on anything else, so **no row filter and no hidden field can even be
+DECLARED for a `ut_*` database** — `routes_tables.py` makes zero `perm_scope` calls and passes
+`hidden_keys=frozenset()`. There is no module wall behind a user table for a grant to be bounded
+by: **this registry IS the wall.** So a `database` grant is ALL-OR-NOTHING — every row, every
+column — and an `*` database grant admits every account in the tenant to all of it.
+That is a real capability, deliberately kept; what was wrong was a docstring promising a second
+wall that does not exist for this kind. Scoping user tables is booked, not done
+(`waves/wave32/sharing-audit.md` S-8).
+
+⚠ **TWO SYSTEMS ANSWER "IS THIS SHARED", AND THEY ARE NOT THE SAME ONE (audit S-4).** THIS
+registry decides who appears in *"Shared with me"* and who may re-share. **`table_store.is_shared`
+— the view's own `permissions` — is what actually decides who may OPEN a view.** A grant here
+whose object is invisible under that one is a row in a list that opens a refusal, which is what
+made item 18 worth auditing. `_entries_or_400` closes the common cause (a name nobody has), but
+the two vocabularies are still two.
+"""
+from fastapi import APIRouter, Body, Depends
+
+import core.shares as shares
+import core.users as users
+from deps import Session, err, require_session
+# ⭐ W32-T28 (C3) — the SHARE notification's topic word, imported from the module that CLASSIFIES
+# it (`routes_alerts.notification_view`) rather than typed again here. The producer and the
+# reader agreeing about one string is the whole difference between an Inbox row that opens the
+# shared database and one that is quietly unclickable.
+from routes_alerts import SHARE_TOPIC as _SHARE_TOPIC
+
+router = APIRouter(prefix="/api/v1")
+
+
+def _kind_or_400(raw):
+    try:
+        return shares._check_kind(raw)
+    except ValueError as e:
+        raise err(400, "bad_kind", str(e))
+
+
+# ── ⭐⭐ WAVE 32 · T26 (owner item 18, ruling R12) — THE WALL THIS FILE SAID IT HAD ─────────────
+#
+# `put_share`'s comment used to justify the first-claim rule with *"reaching this route at all
+# means passing the surface's own wall"*. **There was no such wall.** `kind` and `oid` are free
+# strings off the URL and the only dependency was `require_session`, so any signed-in account
+# could `PUT` a grant on an id it had never seen. Because the 403 sat behind `if rec["owner"]`,
+# an object with no grant record skipped the check entirely and the caller was stamped OWNER —
+# sticky, so **the real creator was then refused on their own view, permanently.** Driven, not
+# argued: `waves/wave32/sharing-audit.md` S-1 carries the four-step transcript.
+#
+# ⚠ AND IT WAS SILENT ON BOTH SIDES. The claimant does not even see the object in their own
+# "Shared with me" (`shared_with` excludes what you own), so nothing appears anywhere until the
+# victim next opens the dialog.
+
+#: The built-in grid topics. A view or folder lives in `{topic}_table_workspace`, and the share
+#: route is not told which topic — so resolving one means asking each.
+_BUILTIN_TOPICS = ("customer", "product")
+
+
+def _topics(session):
+    """Every topic whose workspace could hold a view or folder for this tenant.
+
+    ⚠ `all_defs`, never `all_tables` — the latter is the whole 28.6 MB row payload (~703 ms on
+    tenant #0) to answer a question about KEYS (D-185).
+    """
+    try:
+        import core.user_tables as ut
+        return (*_BUILTIN_TOPICS, *(ut.all_defs(st=session.runtime) or {}))
+    except Exception:                                       # noqa: BLE001
+        return _BUILTIN_TOPICS
+
+
+def _owns_object(session, kind, oid):
+    """May this caller CLAIM an object that has no grant record yet — i.e. do they own it?
+
+    ⛔ THIS GUARDS THE CLAIM, NOT THE READ, AND THAT IS DELIBERATE. Resolving a view means asking
+    each topic's workspace in turn, which is N store reads; making every share call pay that
+    would put a loop on a route the manage-access dialog opens. The dangerous path is the one
+    where a caller is about to be stamped OWNER of something nobody owns — so the resolution runs
+    exactly there, and the common path (a record exists, `may_administer` decides) is untouched.
+    """
+    if session.admin:
+        return True
+    if kind == "field":
+        # ⭐⭐ W38-T16 — A COLUMN'S OWNER IS ITS `createdBy`, WHICH THE CREATE DOOR ALREADY STAMPS
+        # (`routes_tables.patch_shared_cell`) and the DELETE door already reads as its wall (R8 /
+        # D-172: creator-or-admin). Read from the same place by all three, so a column cannot be
+        # deletable by one person and shareable by another.
+        # ⚠ THIS BRANCH IS NOT OPTIONAL AND ITS ABSENCE FAILS SILENTLY IN THE WORST DIRECTION:
+        # a brand-new column has no grant record, so `put_share` falls to this predicate — and
+        # without it the column's own creator is answered `404 no_object` on the first attempt to
+        # share the thing they just made.
+        table_key, field_key = shares.split_field_oid(oid)
+        if not table_key:
+            return False
+        try:
+            import core.shared_overlay as shared_overlay
+            defn = (shared_overlay.fields(table_key, st=session.runtime) or {}).get(field_key)
+        except Exception:                                   # noqa: BLE001
+            return False
+        return bool(defn) and str(defn.get("createdBy") or "") == str(session.uname)
+    if kind == "database":
+        # ⚠ `may_open` is THE resolver for a user table (its own docstring says so) and already
+        # admits creator, admin, or a `database` grantee. Re-implementing "who owns a table"
+        # here would be the second definition this wave keeps finding.
+        try:
+            import core.user_tables as ut
+            return bool(ut.may_open(oid, session.uname, is_admin=session.admin,
+                                    st=session.runtime))
+        except Exception:                                   # noqa: BLE001
+            return False
+    try:
+        import core.table_store as table_store
+    except Exception:                                       # noqa: BLE001
+        return False
+    for topic in _topics(session):
+        try:
+            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
+            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
+        except Exception:                                   # noqa: BLE001
+            continue
+        if hit:
+            # `find_view`/`find_folder` answer `(owner_username, …)`. The claim belongs to the
+            # person whose personal stratum holds it — anybody else reaching this line is
+            # exactly the case S-1 describes.
+            return str(hit[0]) == str(session.uname)
+    return False
+
+
+def _can_see_object(session, kind, oid):
+    """May this caller READ an object's grant list — i.e. can they reach the object at all?
+
+    ⛔⛔ THIS IS DELIBERATELY WIDER THAN {@link _owns_object}, AND CONFLATING THE TWO IS A
+    REGRESSION I SHIPPED AND CAUGHT. The first version of T26 guarded BOTH doors with the
+    ownership test, which reads sensibly and is wrong for the read, because **`find_view` searches
+    PERSONAL STRATA ONLY** (its own docstring says so). So a view living in alice's stratum with
+    `permissions.edit = "collaborative"` and no grant record yet — a view bob **can open and edit
+    in the grid** — answered `404` when bob opened its manage-access dialog. Measured before
+    fixing: `table_store._may_see(view, "bob") is True` while `GET /share/view/vc` said
+    `404 no_object`.
+    ⚠ THAT IS THE AUDIT'S OWN S-4 BITING THE AUDIT'S OWN FIX: two systems answer "is this shared",
+    and the wall consulted the grant registry (system A) plus stratum ownership, never the view's
+    `permissions` (system B) — which is the one that actually decides who may OPEN it.
+    ⚠ And it hides the ANSWER, not just the editor. `ViewSidebar`'s Share row is deliberately not
+    gated on edit rights because *"hiding the row from everyone else would hide the ANSWER too —
+    'who has this?' is a fair question for anyone the view was shared with"*. A 404 there tells a
+    legitimate collaborator their view does not exist.
+
+    ⛔ THE CLAIM KEEPS THE NARROW TEST. Being able to SEE an object must not let you become its
+    owner — that is S-1, and widening this predicate onto `put_share` would re-open it.
+    """
+    if _owns_object(session, kind, oid):
+        return True
+    if kind != "view":
+        # A folder carries no per-object visibility flag of its own, and a database's `may_open`
+        # (inside `_owns_object`) already admits grantees. Nothing wider to ask.
+        # ⭐ W38-T16 — AND `field` KEEPS THIS CLOSED, DELIBERATELY. A grantee never reaches here:
+        # `get_share` tests `role is None` first and a grant answers a role, so the only caller
+        # left is an account with no relationship to the column at all. Widening it would let any
+        # signed-in session enumerate who holds which column on a database they cannot open.
+        return False
+    try:
+        import core.table_store as table_store
+        for topic in _topics(session):
+            hit = table_store.make(f"{topic}_table_workspace", st=session.runtime).find_view(oid)
+            if hit:
+                return bool(table_store._may_see(hit[1] if len(hit) > 1 else {},
+                                                 session.uname, is_admin=session.admin))
+    except Exception:                                       # noqa: BLE001
+        return False
+    return False
+
+
+def _entries_or_400(session, entries):
+    """Validate a grant list against the tenant's REAL, ACTIVE accounts — and refuse BY NAME.
+
+    ⛔ `core.shares._clean_entries` silently drops junk, and its docstring argues that correctly:
+    a UI mid-save must not lose the whole list to one malformed row. **But it validates the SHAPE
+    of a string and the role word — never that the user EXISTS, is ACTIVE, or is in this tenant**,
+    so a typo'd name is stored, reported as a successful save, and never reaches anybody. The
+    sharer believes the person has access. That is item 18's plain reading.
+    ⚠ The correct population is computed THREE FUNCTIONS BELOW and served to the picker
+    (`_people`). One route, two populations, and the write door was the permissive one.
+    ⚠ `*` (everyone) is not a user and is admitted deliberately — it is R10's vocabulary for
+    "every account that can already open the surface".
+    """
+    known = {p["username"].strip().lower() for p in _people(session.tenant)}
+    unknown = []
+    for e in entries or ():
+        if not isinstance(e, dict):
+            continue
+        user = str(e.get("user") or "").strip().lower()
+        if user and user != shares.EVERYONE and user not in known:
+            unknown.append(user)
+    if unknown:
+        raise err(400, "unknown_people",
+                  "no active account in this workspace is named "
+                  + ", ".join(sorted(set(unknown)))
+                  + ". Nothing was shared. Pick people from the list rather than typing a name.")
+
+
+@router.get("/share/mine")
+def my_shares(session: Session = Depends(require_session)):
+    """Everything shared WITH me, by kind — the "Shared with me" rail section (R10).
+
+    Registered before `/share/{kind}/{oid}` so the literal path wins the match; FastAPI resolves
+    in declaration order and `mine` would otherwise be read as a `kind`, answering 400 for a URL
+    that is not malformed at all.
+    """
+    return shares.shared_with(session.uname, st=session.runtime)
+
+
+@router.get("/share/{kind}/{oid}")
+def get_share(kind: str, oid: str, session: Session = Depends(require_session)):
+    kind = _kind_or_400(kind)
+    rec = shares.grants(kind, oid, st=session.runtime)
+    role = shares.role_for(kind, oid, session.uname, is_admin=session.admin, st=session.runtime)
+    may_admin = shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
+                                      st=session.runtime)
+    # W39-T29 — the dialog opens with GET before its first PUT.  Until that PUT exists the grant
+    # registry has no owner to return from `may_administer`, even though the same caller may safely
+    # claim their own object through the PUT path below.  Reflect that exact claim predicate here:
+    # a Member who owns an unshared View receives the people picker; a collaborator still does not.
+    if not rec["owner"] and not may_admin and _owns_object(session, kind, oid):
+        may_admin = True
+    # ⭐ W32-T26 (audit S-3) — A STRANGER LEARNS NOTHING. This route used to answer for ANY id:
+    # who owns it, everyone it is granted to, and the tenant's whole username↔name directory —
+    # to any signed-in session, about objects it cannot open. Now a caller with no role on an
+    # object must prove they can reach it, and gets a 404 otherwise: the same answer a
+    # non-existent id gives, so the route cannot be used to probe which ids are real.
+    # ⚠ `role is None` is the cheap pre-test, so the N-topic resolution below runs only for a
+    # caller who has no relationship with the object at all.
+    if role is None and not _can_see_object(session, kind, oid):
+        raise err(404, "no_object", "no such item, or it is not shared with this account")
+    return {
+        **rec,
+        "role": role,
+        "mayAdminister": may_admin,
+        # ⚠ WAVE 21 (C1 identity fix): grant entries BIND on USERNAMES, so the picker must carry
+        # them. `assignable_people` serves bare display names because `user`-kind CELLS store
+        # display names — that list's shape cannot change without migrating cell values — so
+        # this route serves objects of its own. Existing grants that were written as lowercased
+        # display names are normalised by the wave-21 cleanup script.
+        # ⭐ W32-T26 (audit S-3) — the roster is the EDITOR's data, so it rides only for a caller
+        # who may open the editor. A read-only grantee gets the grant list (their fair question is
+        # "who else has this?") and not a directory of every account in the workspace.
+        "people": _people(session.tenant) if may_admin else [],
+    }
+
+
+def _people(tenant):
+    """[{username, name}] for this tenant — same population as `assignable_people`, with the
+    BINDING identity alongside the display one."""
+    try:
+        reg = users.registry() or {}
+    except Exception:
+        return []
+    want = str(tenant or '').strip().lower()
+    out = []
+    for uname, u in reg.items():
+        if not isinstance(u, dict) or u.get('active') is False:
+            continue
+        if want and str(u.get('tenant') or 'royal-imports').strip().lower() != want:
+            continue
+        out.append({"username": str(uname), "name": str(u.get('name') or uname)})
+    return sorted(out, key=lambda p: p["name"].lower())
+
+
+@router.put("/share/{kind}/{oid}")
+def put_share(kind: str, oid: str, body: dict = Body(default=None),
+              session: Session = Depends(require_session)):
+    kind = _kind_or_400(kind)
+    body = body or {}
+    rec = shares.grants(kind, oid, st=session.runtime)
+    # An object with NO grant record yet has no owner — the first person to share it claims it.
+    # That is safe because reaching this route at all means passing the surface's own wall, and
+    # the alternative (refusing until somebody seeds an owner) would make a brand-new folder
+    # unshareable by the person who just made it.
+    if rec["owner"]:
+        if not shares.may_administer(kind, oid, session.uname, is_admin=session.admin,
+                                     st=session.runtime):
+            raise err(403, "not_owner",
+                      "only the owner of this item (or an administrator) can change who it is "
+                      "shared with")
+    # ⛔⛔ W32-T26 (audit S-1) — THE CLAIM NOW HAS A PRECONDITION. An object with no grant record
+    # is still claimed by the first person to share it — that rule is right, and refusing until
+    # somebody seeds an owner would make a brand-new folder unshareable by the person who just
+    # made it. What was missing is the half the old comment ASSERTED and the code never did: the
+    # claimant has to be able to reach the object. Without this, any signed-in account could
+    # stamp itself owner of an id it had never seen and lock the real creator out for good.
+    elif not _owns_object(session, kind, oid):
+        raise err(404, "no_object", "no such item, or it is not shared with this account")
+    entries = body.get("entries")
+    if not isinstance(entries, list):
+        raise err(400, "bad_entries",
+                  "entries must be a list of {user, role}. Send [] to un-share, which is how "
+                  "revoking is expressed")
+    _entries_or_400(session, entries)
+    out = shares.set_grants(kind, oid, entries, owner=rec["owner"] or session.uname,
+                            st=session.runtime)
+    _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
+    return out
+
+
+def _notify_new_grantees(session, kind, oid, before, after):
+    """⭐⭐ W32-T28 (owner item 18's last clause, contract C3) — tell the RECEIVER, in their Inbox.
+
+    Owner item 18 ends *"being shared a database notifies the receiver"*. Until now sharing was
+    silent: the grant landed in a rail section the receiver had to notice on their own, which is
+    why "I shared it with you" and "I never saw it" were both true.
+
+    ⛔ WRITTEN ON THE SHARE, NEVER POLLED. `/notifications` re-evaluates view-ALERTS on read
+    because an alert is a live question about rows; a share is an EVENT that happened once, and
+    polling for it would mean re-deriving "was this new?" on every inbox open — the diff below
+    only exists here, at the moment the set changes.
+
+    ⚠ ONLY THE NEWLY ADDED. `PUT` REPLACES the whole entry set (revoking is expressed by absence),
+    so every save re-sends everyone who was already there. Diffing against `before` is what stops
+    a rename or a role change from ringing the bell for people whose access did not change.
+    ⚠ `*` IS NOT NOTIFIED: there is no user to name, and minting one notification per account in
+    the tenant on a single click is a broadcast nobody asked for. The rail still shows it.
+    ⚠ IT NEVER RAISES. A notification that fails must not fail the share that triggered it — the
+    grant is the user's actual intent, and `core.alerts.notify` writes with `flush='async'`.
+    """
+    try:
+        was = {e.get("user") for e in (before or ()) if isinstance(e, dict)}
+        fresh = [str(e.get("user")) for e in (after or ())
+                 if isinstance(e, dict) and e.get("user") not in was
+                 and e.get("user") != shares.EVERYONE]
+        if not fresh:
+            return
+        import core.alerts as alerts
+
+        label, route, view_id = _object_ref(session, kind, oid)
+        if not route:
+            # ⛔ NO ROUTE, NO NOTIFICATION — the receiver would get a row that opens nothing, and
+            # `notification_view` would have to invent a target. Silence is the honest answer
+            # here; the rail still shows the grant under "Shared with me".
+            return
+        sharer = str(session.user.get("name") or session.uname)
+        for user in fresh:
+            # ⚠ THE SHAPE IS `routes_alerts.notification_view`'s SHARE BRANCH, and the two must
+            # agree or the Inbox row is unclickable: `topic` selects the branch and `key` becomes
+            # `alertId`, which that branch reads as the id to open. Both constants are IMPORTED
+            # from there rather than typed again — one vocabulary, one owner.
+            # ⭐⭐ W33-T28 (`ASK C-14`, answered) — `actor` IS THE SENDER, AND IT IS THE ONLY WAY
+            # THE INBOX CAN NAME ONE. An alert and an automation have no person behind them and
+            # are honestly named by their machine; a SHARE has a real person, and only this call
+            # site knows who. ⛔ It is passed as its OWN field rather than recovered from the
+            # `detail` prose below: a sender parsed out of "<name> shared this with you" breaks
+            # the first time the sentence is reworded, silently, in the header
+            # [[grep-output-is-not-source]]. The prose stays as the body; this is the From.
+            alerts.notify(user, label, topic=_SHARE_TOPIC, key=route, row_id=view_id,
+                          detail=f"{sharer} shared this with you", actor=sharer,
+                          st=session.runtime)
+    except Exception:                                       # noqa: BLE001
+        return
+
+
+def _object_ref(session, kind, oid):
+    """`(label, route, view_id)` — what to CALL the shared thing, and where it OPENS.
+
+    ⛔ THE ROUTE IS RESOLVED HERE, NOT SHAPED IN THE CONSUMER, AND THE FIRST VERSION GOT IT
+    WRONG: it put the raw `oid` in the notification's key, so a shared VIEW produced
+    `target: {module: "database", id: "view_42"}` — an instruction to open a database named
+    `view_42`. It read perfectly in the payload and would have opened nothing. **A view is not
+    addressable on its own; it is a SELECTION inside a topic's grid**, so the pair is what has to
+    travel. Caught by looking at the notification the driver actually produced, not by reading
+    the code back.
+
+    ⚠ `label` never falls back to a raw id. A notification headed `ut_leads_3f2a` tells the
+    receiver nothing they can act on, and the id is already in the target.
+    ⚠ An unresolvable object answers `route=None`, and the caller then sends NOTHING rather than
+    a row that opens nowhere.
+    """
+    try:
+        if kind == "field":
+            # ⭐⭐ W38-T16 — A COLUMN IS NOT ADDRESSABLE ON ITS OWN, exactly as a view is not: it
+            # is a column INSIDE a database, so the target that travels is the DATABASE. Without
+            # this branch the function falls through to the view/folder loop, finds nothing,
+            # answers `route=None` — and `_notify_new_grantees` returns EARLY. The grant lands and
+            # the receiver is never told, which is the silent half of owner item 18 reopened one
+            # kind over.
+            from routes_alerts import route_for_topic
+            table_key, field_key = shares.split_field_oid(oid)
+            if not table_key:
+                return ("A column", None, "")
+            try:
+                import core.shared_overlay as shared_overlay
+                defn = (shared_overlay.fields(table_key, st=session.runtime) or {}).get(field_key)
+            except Exception:                               # noqa: BLE001
+                defn = None
+            label = str((defn or {}).get("label") or "").strip() or field_key
+            # ⚠ TWO SPELLINGS REACH THIS LINE AND ONE MAP ANSWERS BOTH. `shared_overlay` is keyed
+            # by whatever the calling door already held: a `ut_*` database uses its bare key,
+            # while a registry topic uses `<topic>_table_workspace` (`product_data.TABLE_KEY`).
+            # `route_for_topic` speaks the GRID SCOPE vocabulary (`customer`, not
+            # `customer_data`), so the suffix comes off before it is asked — rather than a second
+            # route table being written here, which is how the two come apart.
+            _WS = "_table_workspace"
+            scope = table_key[:-len(_WS)] if table_key.endswith(_WS) else table_key
+            return (label, route_for_topic(scope) or None, "")
+        if kind == "database":
+            import core.user_tables as ut
+            defn = (ut.all_defs(st=session.runtime) or {}).get(str(oid)) or {}
+            # A user table IS its own route key in both vocabularies (`route_for_topic`).
+            return (str(defn.get("label") or "").strip() or "A database", str(oid), "")
+        import core.table_store as table_store
+        from routes_alerts import route_for_topic
+        for topic in _topics(session):
+            ops = table_store.make(f"{topic}_table_workspace", st=session.runtime)
+            hit = ops.find_view(oid) if kind == "view" else ops.find_folder(oid)
+            if not hit:
+                continue
+            route = route_for_topic(topic)
+            if not route:
+                break
+            row = hit[1] if len(hit) > 1 else {}
+            name = str((row or {}).get("name") or "").strip()
+            # ⚠ Only a VIEW carries a selection. A folder is a rail grouping, so the target opens
+            # the grid and stops there rather than naming a view the receiver did not get.
+            return (name or ("A view" if kind == "view" else "A folder"),
+                    route, str(oid) if kind == "view" else "")
+    except Exception:                                       # noqa: BLE001
+        pass
+    return ({"view": "A view", "folder": "A folder",
+             "field": "A column"}.get(kind, "An item"), None, "")

api/routes_slack.py

@@ -1,772 +1,772 @@
-"""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):
-    """The rows this channel may receive — `permits()`, so an unanswerable permanent filter DENIES
-    rather than being ignored."""
-    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)
-    # 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):
+    """The rows this channel may receive — `permits()`, so an unanswerable permanent filter DENIES
+    rather than being ignored."""
+    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)
+    # 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

@@ -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_web_agent.py

@@ -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_fields.json

@@ -1,581 +1,581 @@
-{
-  "_comment": "CANONICAL field contract for the AIOS Airtable-style grid — the SINGLE source of truth. Consumed by platform/aios_grid.py (embed/Space host) and aios-web/api/main.py (standalone API), and regenerated into aios-web/web/public/sample_customers.json. Edit HERE only, then run aios-web/verify_fields_contract.py. source=odoo is READ-ONLY; source=overlay is the editable stratum (notes/tags) outside Odoo. type in {text,status,select,currency,int,date,pct} (select = a fixed-choice READ-ONLY brand attribute; dba is the first, wave 2026-08-02). `description` (wave 5) is the CANONICAL per-field description — every field must carry one, and since wave 7 (owner W8, 2026-07-28) every description is ONE SHORT PLAIN sentence (two only when a fact would otherwise mislead): what the field IS, nothing else — no filter tips, no '(none)' coaching, no rationale; the user's workspace NOTE overrides it in the (i) hover, never in this file. BUILDER FACT (documented here, deliberately NOT in user-facing text): blank text attributes display as '(none)', so `is '(none)'` — not `is empty` — finds the blanks on agent/city/state/country/zip/payment_terms/pricelist/tags. filterable:false = the CONDITION BUILDER does not offer it (still displayed, still sortable); every such field must have a replacement declared in aios-web/verify_fields_contract.py. 2026-07-27 partner attributes: country/zip/payment_terms/pricelist/tags/customer_since all ship default:false. zip is TEXT because a postal code has leading zeros. Odoo's credit_limit (1% populated) and user_id salesperson (2%) are deliberately ABSENT; agent_ids is the salesperson field and AR is where credit exposure comes from. Wave-5 item 8 (2026-07-27): ltm_rev and at_risk are DELETED — LTM's replacement is a creatable Sales measure column (the demo column IS Sales · the last 12 months), at_risk's replacement is a formula field, e.g. MAX(0, {revenue_ly} - {revenue_ytd}). Wave-6 item 8 (2026-07-27, the no-buildable-presets rule): revenue_ytd, revenue_ly, orders_24m, aov and yoy_pct are DELETED — every one is self-buildable, so a frozen pre-set beside the builder was two ways to ask one question. Replacements (recorded in verify_fields_contract.py): creatable measure columns for Sales / Orders / Avg order $ over any period (harness/measure_filter.py ADMITTED carries revenue, orders and the composite aov), and a formula over two measure columns for YoY, e.g. ({sales_ytd} - {sales_ly}) / {sales_ly}. Stale view colIds naming the five self-heal on the next autosave (the established rule).",
-  "fields": [
-    {
-      "key": "customer",
-      "label": "Customer",
-      "type": "text",
-      "source": "odoo",
-      "pinned": true,
-      "default": true,
-      "description": "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
-    },
-    {
-      "key": "partner_id",
-      "label": "Odoo ID",
-      "type": "int",
-      "source": "odoo",
-      "derived": true,
-      "default": false,
-      "description": "The Odoo res.partner id — the key every Odoo document joins on. DERIVED: this row's pid IS the partner id, so a stored copy would be a second source."
-    },
-    {
-      "key": "odoo_status",
-      "label": "Odoo record",
-      "type": "status",
-      "source": "odoo",
-      "default": false,
-      "options": [
-        "Active",
-        "Archived"
-      ],
-      "description": "Whether this customer still exists in Odoo. Archived means deleted there."
-    },
-    {
-      "key": "agent",
-      "label": "Agent",
-      "type": "text",
-      "source": "odoo",
-      "default": true,
-      "description": "The sales agent who owns this account."
-    },
-    {
-      "key": "dba",
-      "label": "DBA",
-      "type": "select",
-      "source": "odoo",
-      "default": false,
-      "options": [
-        "Fisch",
-        "Royal",
-        "Both"
-      ],
-      "description": "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
-    },
-    {
-      "key": "salesperson",
-      "label": "Salesperson",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Who keyed in most of this customer's orders — not the Agent, who owns the account."
-    },
-    {
-      "key": "street",
-      "label": "Street",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "First address line, from res.partner directly - not the geocoder, so a customer the map cannot place still shows its address."
-    },
-    {
-      "key": "street2",
-      "label": "Street 2",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Second address line (suite, unit, floor) on the customer's Odoo address."
-    },
-    {
-      "key": "city",
-      "label": "City",
-      "type": "text",
-      "source": "odoo",
-      "default": true,
-      "description": "City on the customer's Odoo address."
-    },
-    {
-      "key": "state",
-      "label": "State",
-      "type": "text",
-      "source": "odoo",
-      "default": true,
-      "description": "State or province on the customer's Odoo address."
-    },
-    {
-      "key": "country",
-      "label": "Country",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Country on the customer's Odoo address."
-    },
-    {
-      "key": "zip",
-      "label": "ZIP",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Postal code on the customer's Odoo address."
-    },
-    {
-      "key": "customer_since",
-      "label": "Customer since",
-      "type": "date",
-      "source": "odoo",
-      "default": false,
-      "description": "When this customer was first set up in Odoo."
-    },
-    {
-      "key": "tags",
-      "label": "Tags",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Odoo labels on this customer, comma-separated."
-    },
-    {
-      "key": "pricelist",
-      "label": "Price list",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "The price list this customer buys on."
-    },
-    {
-      "key": "payment_terms",
-      "label": "Payment terms",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Payment terms on this customer's account — Net 30, for example."
-    },
-    {
-      "key": "last_order",
-      "label": "Last order",
-      "type": "date",
-      "source": "odoo",
-      "default": true,
-      "description": "Date of the most recent confirmed order."
-    },
-    {
-      "key": "overdue_days",
-      "label": "Overdue days",
-      "type": "int",
-      "source": "odoo",
-      "default": true,
-      "description": "How many days late this customer is running against their own usual ordering rhythm."
-    },
-    {
-      "_note": "filterable:false — DERIVED ANALYTIC: est_missed is min(cycles missed, 3) x AOV, a score we compute rather than an object the business has, so a condition on it would read as a fact about the customer when it is a fact about our arithmetic. It still displays and still sorts. Until wave 6 this flag also covered the frozen-window presets (revenue_ytd / revenue_ly / orders_24m / aov / yoy_pct); those are now DELETED outright under the owner's no-buildable-presets rule — see _comment. est_missed itself STAYS: no creatable measure or formula reproduces the cadence model behind it.",
-      "key": "est_missed",
-      "label": "Est. missed $",
-      "type": "currency",
-      "source": "odoo",
-      "default": true,
-      "agg": "sum",
-      "filterable": false,
-      "description": "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
-    },
-    {
-      "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
-      "key": "ar_open",
-      "label": "AR current $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Invoiced money owed but not yet due (a 5-day grace applies before it counts as overdue)."
-    },
-    {
-      "key": "ar_overdue",
-      "label": "AR overdue $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Invoiced money past due — same basis as the Collections page."
-    },
-    {
-      "_note": "wave 21 R1 — the TOTAL, added beside the rename above. AR current $ + AR overdue $, i.e. what most people mean by 'open AR'. Composed from the same ar.credit_exposure rows the siblings use, so it is transitively reconciled by ar.validate()'s residual read_group tie — no second oracle.",
-      "key": "ar_outstanding",
-      "label": "AR outstanding $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Total invoiced money owed right now: AR current $ plus AR overdue $."
-    },
-    {
-      "key": "ar_exposure",
-      "label": "Credit exposure $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "The most you could be out if they stopped paying today: open, overdue, draft and not-yet-invoiced."
-    },
-    {
-      "key": "ar_aged_1_30",
-      "label": "1-30 days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue between 1 and 30 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "ar_aged_31_60",
-      "label": "31-60 days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue between 31 and 60 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "ar_aged_61_90",
-      "label": "61-90 days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "ar_aged_90_plus",
-      "label": "90+ days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "days_to_pay",
-      "label": "Days to pay",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
-    },
-    {
-      "key": "top_category",
-      "label": "Top category",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "The category this customer spent the most on in the last 12 months."
-    },
-    {
-      "key": "top_category_pct",
-      "label": "Top category %",
-      "type": "pct",
-      "source": "odoo",
-      "default": false,
-      "description": "Share of last-12-months spend that went to the top category."
-    },
-    {
-      "key": "sku_count",
-      "label": "SKUs bought",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Distinct products bought in the last 12 months."
-    },
-    {
-      "key": "top_sku",
-      "label": "Top SKU",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "The product this customer spent the most on in the last 12 months."
-    },
-    {
-      "key": "days_since",
-      "label": "Days since order",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Days since the last confirmed order."
-    },
-    {
-      "key": "typical_gap_days",
-      "label": "Typical gap days",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Days this customer usually goes between orders, from their own history."
-    },
-    {
-      "key": "notes",
-      "label": "Notes",
-      "type": "text",
-      "source": "overlay",
-      "default": false,
-      "description": "Your notes on this customer. Saved in this app only, visible only to you."
-    }
-  ],
-  "_product_comment": "ADDITIVE, wave 15 C-TOPIC. The PRODUCT table's field contract. Kept as a SEPARATE top-level key rather than restructuring `fields` into {customer_data, product_data}: both existing readers (aios_grid._load_fields, aios-web/api/main.py) index doc['fields'] directly, and reshaping that mid-wave would break the embed for a cosmetic gain. The keyed shape can arrive when both readers move in ONE commit; until then this is the product half and `fields` is the customer half.",
-  "_product_removed_buy_now": "OWNER, 2026-08-03: 'Buy signal' (key buy_now, a select of Buy now / OK) is NO LONGER A PRESET FIELD. It never earned one: it is a formula over two columns that are both still right here, and the platform has a formula field type for exactly that. THE FORMULA, which reproduces the retired column row for row (modules/product_data.validate proves the equivalence, and goes red if it ever stops holding): IF({lead_days} > 0, IF({dos} < {lead_days}, \"Buy now\", \"OK\"), \"\") . Every branch matches the old server rule, including the blanks - the formula engine refuses a comparison against a blank rather than coercing it to 0, so a SKU with no days-of-supply or no lead time comes out empty, which is 'we do not know' and not 'you are fine'. NOTE the column is still COMPUTED in product_data.pool(): it ships nowhere (rows_from_pool projects strictly through this contract, so no Field means no cell on the wire) and exists only as validate()'s oracle. A formula field is PER-USER, so nothing shared may filter on it - the Buy list view filters on dos/lead_days directly (_seed_wave17).",
-  "product_data": {
-    "identity": "pid",
-    "business_key": "code",
-    "fields": [
-      {
-        "key": "code",
-        "label": "SKU",
-        "type": "text",
-        "source": "odoo",
-        "pinned": true,
-        "default": true,
-        "description": "The SKU code — the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer."
-      },
-      {
-        "key": "product",
-        "label": "Product",
-        "type": "text",
-        "source": "odoo",
-        "default": true,
-        "description": "Product name as it appears in Odoo."
-      },
-      {
-        "key": "category",
-        "label": "Category",
-        "type": "select",
-        "source": "odoo",
-        "default": true,
-        "description": "Product category; '(uncategorized)' when Odoo carries none."
-      },
-      {
-        "key": "supplier",
-        "label": "Supplier",
-        "type": "text",
-        "source": "overlay",
-        "default": true,
-        "description": "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet.",
-        "shared": true
-      },
-      {
-        "key": "origin_country",
-        "label": "Country",
-        "type": "text",
-        "source": "overlay",
-        "default": false,
-        "description": "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet.",
-        "shared": true
-      },
-      {
-        "key": "lead_days",
-        "label": "Lead time (days)",
-        "type": "int",
-        "source": "overlay",
-        "default": true,
-        "description": "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone.",
-        "shared": true
-      },
-      {
-        "key": "first_cost",
-        "label": "First cost",
-        "type": "currency",
-        "source": "overlay",
-        "default": false,
-        "description": "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone.",
-        "shared": true
-      },
-      {
-        "key": "price_fisch",
-        "label": "Fisch price",
-        "type": "currency",
-        "source": "odoo",
-        "description": "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
-      },
-      {
-        "key": "price_royal_1",
-        "label": "Royal 1 price",
-        "type": "currency",
-        "source": "odoo",
-        "description": "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
-      },
-      {
-        "key": "price_royal_2",
-        "label": "Royal 2 price",
-        "type": "currency",
-        "source": "odoo",
-        "description": "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
-      },
-      {
-        "key": "tier_prices",
-        "label": "Tier prices",
-        "type": "json",
-        "source": "odoo",
-        "description": "Every live pricelist that prices this SKU today, as [{pricelist, unit_price}] at qty 1. Blank when no list prices it. This is the honest SET; the three Fisch/Royal columns beside it are the DECLARED subset and cannot show a price on a list the contract does not name."
-      },
-      {
-        "key": "units",
-        "label": "Units",
-        "type": "json",
-        "source": "odoo",
-        "description": "The units of measure this SKU is really sold in, as [{name, qty}] where qty is in the product's own unit. Blank means it is sold in ONE unit, not that data is missing - only 1,150 of 5,873 active SKUs (19.6%) carry a unit tier."
-      },
-      {
-        "key": "rev_ytd",
-        "label": "Revenue YTD",
-        "type": "currency",
-        "source": "odoo",
-        "default": true,
-        "description": "Year-to-date revenue for this SKU, BU-scoped when the caller is."
-      },
-      {
-        "key": "rev_ly",
-        "label": "Revenue LY",
-        "type": "currency",
-        "source": "odoo",
-        "description": "Same period last year — seasonal wholesale compares like for like."
-      },
-      {
-        "key": "yoy_pct",
-        "label": "YoY %",
-        "type": "pct",
-        "source": "odoo",
-        "description": "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
-      },
-      {
-        "key": "qty_ytd",
-        "label": "Units YTD",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units sold year to date."
-      },
-      {
-        "key": "orders_ytd",
-        "label": "Orders YTD",
-        "type": "int",
-        "source": "odoo",
-        "description": "Distinct orders containing this SKU, year to date."
-      },
-      {
-        "key": "on_hand",
-        "label": "On hand",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
-      },
-      {
-        "key": "unit_cost",
-        "label": "Unit cost",
-        "type": "currency",
-        "source": "odoo",
-        "description": "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "inv_value",
-        "label": "Stock value",
-        "type": "currency",
-        "source": "odoo",
-        "description": "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "qty_ltm",
-        "label": "Units LTM",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "incoming",
-        "label": "Inbound units",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units already on order and not yet received, from Odoo's own incoming quantity on the product. In the product's STOCK unit of measure, the same unit as On hand, so the two can be added. Days of supply and both cover gap columns all count this as stock (owner, 2026-08-19)."
-      },
-      {
-        "key": "dos",
-        "label": "Days of supply",
-        "type": "int",
-        "source": "odoo",
-        "description": "Days of supply at the trailing twelve month rate, counting ON HAND PLUS INBOUND units as stock; null means it never sells through. Same stock figure as the cover gap columns, so the two cannot disagree about how much you have. They still divide by different rates: this one is the trailing average, the cover gap uses the forward 8 month forecast, so a seasonal SKU reads differently in each. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "cover_gap_d",
-        "label": "Cover gap (days)",
-        "type": "int",
-        "source": "odoo",
-        "default": false,
-        "description": "Days of cover minus supplier lead time. Negative means it runs out before a reorder lands. It counts INBOUND units as stock, exactly as Days of supply now does. The one thing it does differently: the burn rate is the FORWARD 8 month forecast rather than the trailing twelve month average, so a seasonal SKU reads differently here."
-      },
-      {
-        "key": "cover_gap_units",
-        "label": "Cover gap (units)",
-        "type": "int",
-        "source": "odoo",
-        "default": false,
-        "description": "The recommended reorder quantity: units of forecast demand over the lead time that on-hand plus inbound does not cover. POSITIVE means buy this many; negative is surplus units; blank means we cannot say, because the SKU has no lead time on file or no forecast demand. Rounded AWAY from zero, so a real shortfall never rounds down to nothing."
-      },
-      {
-        "key": "demand_fwd",
-        "label": "Forecast units (8 mo)",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units this SKU is expected to sell over the next 8 months, read as the units it actually sold in the same 8 calendar months one year ago. Seasonal on purpose: a flat annual average spreads Valentine's, Mother's Day and Christmas evenly across the year and understates the months buyers actually order for. A SKU too new to appear in that window falls back to its trailing twelve month rate scaled to 8 months. This is the burn rate both cover gap columns divide by, shown so the reorder quantity can be checked."
-      },
-      {
-        "key": "stock_bucket",
-        "label": "Stock status",
-        "type": "select",
-        "source": "odoo",
-        "description": "Dead / excess / healthy bucket, from the same days of supply figure beside it, so it counts inbound units too. One exception on purpose: 'Out of stock' still keys on the REAL shelf, because that is a present tense fact somebody can walk into the warehouse and check. A row can honestly read 'Out of stock' with a days of supply beside it when the replenishment is on the water; Inbound units is why. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "discontinued",
-        "label": "Discontinued",
-        "type": "select",
-        "source": "odoo",
-        "options": [
-          "Yes",
-          "No"
-        ],
-        "description": "Whether Odoo carries the Discontinued product tag on this SKU. Every row gets an explicit Yes or No rather than a blank, because a blank reads as an inactive condition in the filter engine and would silently WIDEN any view that filtered on it."
-      },
-      {
-        "key": "needs_pricing",
-        "label": "Needs pricing",
-        "type": "select",
-        "source": "overlay",
-        "default": false,
-        "options": [
-          "Yes"
-        ],
-        "shared": true,
-        "description": "Team-maintained. A SKU carries “Yes” when it appears on the NEEDS PRICING tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
-      },
-      {
-        "key": "march_pricelist",
-        "label": "March pricelist",
-        "type": "select",
-        "source": "overlay",
-        "default": false,
-        "options": [
-          "Yes"
-        ],
-        "shared": true,
-        "description": "Team-maintained. A SKU carries “Yes” when it appears on the March Pricelist tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
-      },
-      {
-        "key": "price_changes",
-        "label": "Price changes",
-        "type": "select",
-        "source": "overlay",
-        "default": false,
-        "options": [
-          "Yes"
-        ],
-        "shared": true,
-        "description": "Team-maintained. A SKU carries “Yes” when it appears on the Price Changes tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
-      },
-      {
-        "key": "closeouts",
-        "label": "Closeouts",
-        "type": "select",
-        "source": "overlay",
-        "default": false,
-        "options": [
-          "Yes"
-        ],
-        "shared": true,
-        "description": "Team-maintained. A SKU carries “Yes” when it appears on the Closeouts tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
-      },
-      {
-        "key": "notes",
-        "label": "Notes",
-        "type": "text",
-        "source": "overlay",
-        "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."
-      }
-    ]
-  }
-}
+{
+  "_comment": "CANONICAL field contract for the AIOS Airtable-style grid — the SINGLE source of truth. Consumed by platform/aios_grid.py (embed/Space host) and aios-web/api/main.py (standalone API), and regenerated into aios-web/web/public/sample_customers.json. Edit HERE only, then run aios-web/verify_fields_contract.py. source=odoo is READ-ONLY; source=overlay is the editable stratum (notes/tags) outside Odoo. type in {text,status,select,currency,int,date,pct} (select = a fixed-choice READ-ONLY brand attribute; dba is the first, wave 2026-08-02). `description` (wave 5) is the CANONICAL per-field description — every field must carry one, and since wave 7 (owner W8, 2026-07-28) every description is ONE SHORT PLAIN sentence (two only when a fact would otherwise mislead): what the field IS, nothing else — no filter tips, no '(none)' coaching, no rationale; the user's workspace NOTE overrides it in the (i) hover, never in this file. BUILDER FACT (documented here, deliberately NOT in user-facing text): blank text attributes display as '(none)', so `is '(none)'` — not `is empty` — finds the blanks on agent/city/state/country/zip/payment_terms/pricelist/tags. filterable:false = the CONDITION BUILDER does not offer it (still displayed, still sortable); every such field must have a replacement declared in aios-web/verify_fields_contract.py. 2026-07-27 partner attributes: country/zip/payment_terms/pricelist/tags/customer_since all ship default:false. zip is TEXT because a postal code has leading zeros. Odoo's credit_limit (1% populated) and user_id salesperson (2%) are deliberately ABSENT; agent_ids is the salesperson field and AR is where credit exposure comes from. Wave-5 item 8 (2026-07-27): ltm_rev and at_risk are DELETED — LTM's replacement is a creatable Sales measure column (the demo column IS Sales · the last 12 months), at_risk's replacement is a formula field, e.g. MAX(0, {revenue_ly} - {revenue_ytd}). Wave-6 item 8 (2026-07-27, the no-buildable-presets rule): revenue_ytd, revenue_ly, orders_24m, aov and yoy_pct are DELETED — every one is self-buildable, so a frozen pre-set beside the builder was two ways to ask one question. Replacements (recorded in verify_fields_contract.py): creatable measure columns for Sales / Orders / Avg order $ over any period (harness/measure_filter.py ADMITTED carries revenue, orders and the composite aov), and a formula over two measure columns for YoY, e.g. ({sales_ytd} - {sales_ly}) / {sales_ly}. Stale view colIds naming the five self-heal on the next autosave (the established rule).",
+  "fields": [
+    {
+      "key": "customer",
+      "label": "Customer",
+      "type": "text",
+      "source": "odoo",
+      "pinned": true,
+      "default": true,
+      "description": "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
+    },
+    {
+      "key": "partner_id",
+      "label": "Odoo ID",
+      "type": "int",
+      "source": "odoo",
+      "derived": true,
+      "default": false,
+      "description": "The Odoo res.partner id — the key every Odoo document joins on. DERIVED: this row's pid IS the partner id, so a stored copy would be a second source."
+    },
+    {
+      "key": "odoo_status",
+      "label": "Odoo record",
+      "type": "status",
+      "source": "odoo",
+      "default": false,
+      "options": [
+        "Active",
+        "Archived"
+      ],
+      "description": "Whether this customer still exists in Odoo. Archived means deleted there."
+    },
+    {
+      "key": "agent",
+      "label": "Agent",
+      "type": "text",
+      "source": "odoo",
+      "default": true,
+      "description": "The sales agent who owns this account."
+    },
+    {
+      "key": "dba",
+      "label": "DBA",
+      "type": "select",
+      "source": "odoo",
+      "default": false,
+      "options": [
+        "Fisch",
+        "Royal",
+        "Both"
+      ],
+      "description": "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
+    },
+    {
+      "key": "salesperson",
+      "label": "Salesperson",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Who keyed in most of this customer's orders — not the Agent, who owns the account."
+    },
+    {
+      "key": "street",
+      "label": "Street",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "First address line, from res.partner directly - not the geocoder, so a customer the map cannot place still shows its address."
+    },
+    {
+      "key": "street2",
+      "label": "Street 2",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Second address line (suite, unit, floor) on the customer's Odoo address."
+    },
+    {
+      "key": "city",
+      "label": "City",
+      "type": "text",
+      "source": "odoo",
+      "default": true,
+      "description": "City on the customer's Odoo address."
+    },
+    {
+      "key": "state",
+      "label": "State",
+      "type": "text",
+      "source": "odoo",
+      "default": true,
+      "description": "State or province on the customer's Odoo address."
+    },
+    {
+      "key": "country",
+      "label": "Country",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Country on the customer's Odoo address."
+    },
+    {
+      "key": "zip",
+      "label": "ZIP",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Postal code on the customer's Odoo address."
+    },
+    {
+      "key": "customer_since",
+      "label": "Customer since",
+      "type": "date",
+      "source": "odoo",
+      "default": false,
+      "description": "When this customer was first set up in Odoo."
+    },
+    {
+      "key": "tags",
+      "label": "Tags",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Odoo labels on this customer, comma-separated."
+    },
+    {
+      "key": "pricelist",
+      "label": "Price list",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "The price list this customer buys on."
+    },
+    {
+      "key": "payment_terms",
+      "label": "Payment terms",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Payment terms on this customer's account — Net 30, for example."
+    },
+    {
+      "key": "last_order",
+      "label": "Last order",
+      "type": "date",
+      "source": "odoo",
+      "default": true,
+      "description": "Date of the most recent confirmed order."
+    },
+    {
+      "key": "overdue_days",
+      "label": "Overdue days",
+      "type": "int",
+      "source": "odoo",
+      "default": true,
+      "description": "How many days late this customer is running against their own usual ordering rhythm."
+    },
+    {
+      "_note": "filterable:false — DERIVED ANALYTIC: est_missed is min(cycles missed, 3) x AOV, a score we compute rather than an object the business has, so a condition on it would read as a fact about the customer when it is a fact about our arithmetic. It still displays and still sorts. Until wave 6 this flag also covered the frozen-window presets (revenue_ytd / revenue_ly / orders_24m / aov / yoy_pct); those are now DELETED outright under the owner's no-buildable-presets rule — see _comment. est_missed itself STAYS: no creatable measure or formula reproduces the cadence model behind it.",
+      "key": "est_missed",
+      "label": "Est. missed $",
+      "type": "currency",
+      "source": "odoo",
+      "default": true,
+      "agg": "sum",
+      "filterable": false,
+      "description": "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
+    },
+    {
+      "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
+      "key": "ar_open",
+      "label": "AR current $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Invoiced money owed but not yet due (a 5-day grace applies before it counts as overdue)."
+    },
+    {
+      "key": "ar_overdue",
+      "label": "AR overdue $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Invoiced money past due — same basis as the Collections page."
+    },
+    {
+      "_note": "wave 21 R1 — the TOTAL, added beside the rename above. AR current $ + AR overdue $, i.e. what most people mean by 'open AR'. Composed from the same ar.credit_exposure rows the siblings use, so it is transitively reconciled by ar.validate()'s residual read_group tie — no second oracle.",
+      "key": "ar_outstanding",
+      "label": "AR outstanding $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Total invoiced money owed right now: AR current $ plus AR overdue $."
+    },
+    {
+      "key": "ar_exposure",
+      "label": "Credit exposure $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "The most you could be out if they stopped paying today: open, overdue, draft and not-yet-invoiced."
+    },
+    {
+      "key": "ar_aged_1_30",
+      "label": "1-30 days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue between 1 and 30 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "ar_aged_31_60",
+      "label": "31-60 days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue between 31 and 60 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "ar_aged_61_90",
+      "label": "61-90 days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "ar_aged_90_plus",
+      "label": "90+ days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "days_to_pay",
+      "label": "Days to pay",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
+    },
+    {
+      "key": "top_category",
+      "label": "Top category",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "The category this customer spent the most on in the last 12 months."
+    },
+    {
+      "key": "top_category_pct",
+      "label": "Top category %",
+      "type": "pct",
+      "source": "odoo",
+      "default": false,
+      "description": "Share of last-12-months spend that went to the top category."
+    },
+    {
+      "key": "sku_count",
+      "label": "SKUs bought",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Distinct products bought in the last 12 months."
+    },
+    {
+      "key": "top_sku",
+      "label": "Top SKU",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "The product this customer spent the most on in the last 12 months."
+    },
+    {
+      "key": "days_since",
+      "label": "Days since order",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Days since the last confirmed order."
+    },
+    {
+      "key": "typical_gap_days",
+      "label": "Typical gap days",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Days this customer usually goes between orders, from their own history."
+    },
+    {
+      "key": "notes",
+      "label": "Notes",
+      "type": "text",
+      "source": "overlay",
+      "default": false,
+      "description": "Your notes on this customer. Saved in this app only, visible only to you."
+    }
+  ],
+  "_product_comment": "ADDITIVE, wave 15 C-TOPIC. The PRODUCT table's field contract. Kept as a SEPARATE top-level key rather than restructuring `fields` into {customer_data, product_data}: both existing readers (aios_grid._load_fields, aios-web/api/main.py) index doc['fields'] directly, and reshaping that mid-wave would break the embed for a cosmetic gain. The keyed shape can arrive when both readers move in ONE commit; until then this is the product half and `fields` is the customer half.",
+  "_product_removed_buy_now": "OWNER, 2026-08-03: 'Buy signal' (key buy_now, a select of Buy now / OK) is NO LONGER A PRESET FIELD. It never earned one: it is a formula over two columns that are both still right here, and the platform has a formula field type for exactly that. THE FORMULA, which reproduces the retired column row for row (modules/product_data.validate proves the equivalence, and goes red if it ever stops holding): IF({lead_days} > 0, IF({dos} < {lead_days}, \"Buy now\", \"OK\"), \"\") . Every branch matches the old server rule, including the blanks - the formula engine refuses a comparison against a blank rather than coercing it to 0, so a SKU with no days-of-supply or no lead time comes out empty, which is 'we do not know' and not 'you are fine'. NOTE the column is still COMPUTED in product_data.pool(): it ships nowhere (rows_from_pool projects strictly through this contract, so no Field means no cell on the wire) and exists only as validate()'s oracle. A formula field is PER-USER, so nothing shared may filter on it - the Buy list view filters on dos/lead_days directly (_seed_wave17).",
+  "product_data": {
+    "identity": "pid",
+    "business_key": "code",
+    "fields": [
+      {
+        "key": "code",
+        "label": "SKU",
+        "type": "text",
+        "source": "odoo",
+        "pinned": true,
+        "default": true,
+        "description": "The SKU code — the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer."
+      },
+      {
+        "key": "product",
+        "label": "Product",
+        "type": "text",
+        "source": "odoo",
+        "default": true,
+        "description": "Product name as it appears in Odoo."
+      },
+      {
+        "key": "category",
+        "label": "Category",
+        "type": "select",
+        "source": "odoo",
+        "default": true,
+        "description": "Product category; '(uncategorized)' when Odoo carries none."
+      },
+      {
+        "key": "supplier",
+        "label": "Supplier",
+        "type": "text",
+        "source": "overlay",
+        "default": true,
+        "description": "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet.",
+        "shared": true
+      },
+      {
+        "key": "origin_country",
+        "label": "Country",
+        "type": "text",
+        "source": "overlay",
+        "default": false,
+        "description": "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet.",
+        "shared": true
+      },
+      {
+        "key": "lead_days",
+        "label": "Lead time (days)",
+        "type": "int",
+        "source": "overlay",
+        "default": true,
+        "description": "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone.",
+        "shared": true
+      },
+      {
+        "key": "first_cost",
+        "label": "First cost",
+        "type": "currency",
+        "source": "overlay",
+        "default": false,
+        "description": "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone.",
+        "shared": true
+      },
+      {
+        "key": "price_fisch",
+        "label": "Fisch price",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
+      },
+      {
+        "key": "price_royal_1",
+        "label": "Royal 1 price",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
+      },
+      {
+        "key": "price_royal_2",
+        "label": "Royal 2 price",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
+      },
+      {
+        "key": "tier_prices",
+        "label": "Tier prices",
+        "type": "json",
+        "source": "odoo",
+        "description": "Every live pricelist that prices this SKU today, as [{pricelist, unit_price}] at qty 1. Blank when no list prices it. This is the honest SET; the three Fisch/Royal columns beside it are the DECLARED subset and cannot show a price on a list the contract does not name."
+      },
+      {
+        "key": "units",
+        "label": "Units",
+        "type": "json",
+        "source": "odoo",
+        "description": "The units of measure this SKU is really sold in, as [{name, qty}] where qty is in the product's own unit. Blank means it is sold in ONE unit, not that data is missing - only 1,150 of 5,873 active SKUs (19.6%) carry a unit tier."
+      },
+      {
+        "key": "rev_ytd",
+        "label": "Revenue YTD",
+        "type": "currency",
+        "source": "odoo",
+        "default": true,
+        "description": "Year-to-date revenue for this SKU, BU-scoped when the caller is."
+      },
+      {
+        "key": "rev_ly",
+        "label": "Revenue LY",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Same period last year — seasonal wholesale compares like for like."
+      },
+      {
+        "key": "yoy_pct",
+        "label": "YoY %",
+        "type": "pct",
+        "source": "odoo",
+        "description": "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
+      },
+      {
+        "key": "qty_ytd",
+        "label": "Units YTD",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units sold year to date."
+      },
+      {
+        "key": "orders_ytd",
+        "label": "Orders YTD",
+        "type": "int",
+        "source": "odoo",
+        "description": "Distinct orders containing this SKU, year to date."
+      },
+      {
+        "key": "on_hand",
+        "label": "On hand",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
+      },
+      {
+        "key": "unit_cost",
+        "label": "Unit cost",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "inv_value",
+        "label": "Stock value",
+        "type": "currency",
+        "source": "odoo",
+        "description": "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "qty_ltm",
+        "label": "Units LTM",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "incoming",
+        "label": "Inbound units",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units already on order and not yet received, from Odoo's own incoming quantity on the product. In the product's STOCK unit of measure, the same unit as On hand, so the two can be added. Days of supply and both cover gap columns all count this as stock (owner, 2026-08-19)."
+      },
+      {
+        "key": "dos",
+        "label": "Days of supply",
+        "type": "int",
+        "source": "odoo",
+        "description": "Days of supply at the trailing twelve month rate, counting ON HAND PLUS INBOUND units as stock; null means it never sells through. Same stock figure as the cover gap columns, so the two cannot disagree about how much you have. They still divide by different rates: this one is the trailing average, the cover gap uses the forward 8 month forecast, so a seasonal SKU reads differently in each. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "cover_gap_d",
+        "label": "Cover gap (days)",
+        "type": "int",
+        "source": "odoo",
+        "default": false,
+        "description": "Days of cover minus supplier lead time. Negative means it runs out before a reorder lands. It counts INBOUND units as stock, exactly as Days of supply now does. The one thing it does differently: the burn rate is the FORWARD 8 month forecast rather than the trailing twelve month average, so a seasonal SKU reads differently here."
+      },
+      {
+        "key": "cover_gap_units",
+        "label": "Cover gap (units)",
+        "type": "int",
+        "source": "odoo",
+        "default": false,
+        "description": "The recommended reorder quantity: units of forecast demand over the lead time that on-hand plus inbound does not cover. POSITIVE means buy this many; negative is surplus units; blank means we cannot say, because the SKU has no lead time on file or no forecast demand. Rounded AWAY from zero, so a real shortfall never rounds down to nothing."
+      },
+      {
+        "key": "demand_fwd",
+        "label": "Forecast units (8 mo)",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units this SKU is expected to sell over the next 8 months, read as the units it actually sold in the same 8 calendar months one year ago. Seasonal on purpose: a flat annual average spreads Valentine's, Mother's Day and Christmas evenly across the year and understates the months buyers actually order for. A SKU too new to appear in that window falls back to its trailing twelve month rate scaled to 8 months. This is the burn rate both cover gap columns divide by, shown so the reorder quantity can be checked."
+      },
+      {
+        "key": "stock_bucket",
+        "label": "Stock status",
+        "type": "select",
+        "source": "odoo",
+        "description": "Dead / excess / healthy bucket, from the same days of supply figure beside it, so it counts inbound units too. One exception on purpose: 'Out of stock' still keys on the REAL shelf, because that is a present tense fact somebody can walk into the warehouse and check. A row can honestly read 'Out of stock' with a days of supply beside it when the replenishment is on the water; Inbound units is why. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "discontinued",
+        "label": "Discontinued",
+        "type": "select",
+        "source": "odoo",
+        "options": [
+          "Yes",
+          "No"
+        ],
+        "description": "Whether Odoo carries the Discontinued product tag on this SKU. Every row gets an explicit Yes or No rather than a blank, because a blank reads as an inactive condition in the filter engine and would silently WIDEN any view that filtered on it."
+      },
+      {
+        "key": "needs_pricing",
+        "label": "Needs pricing",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "options": [
+          "Yes"
+        ],
+        "shared": true,
+        "description": "Team-maintained. A SKU carries “Yes” when it appears on the NEEDS PRICING tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
+      },
+      {
+        "key": "march_pricelist",
+        "label": "March pricelist",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "options": [
+          "Yes"
+        ],
+        "shared": true,
+        "description": "Team-maintained. A SKU carries “Yes” when it appears on the March Pricelist tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
+      },
+      {
+        "key": "price_changes",
+        "label": "Price changes",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "options": [
+          "Yes"
+        ],
+        "shared": true,
+        "description": "Team-maintained. A SKU carries “Yes” when it appears on the Price Changes tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
+      },
+      {
+        "key": "closeouts",
+        "label": "Closeouts",
+        "type": "select",
+        "source": "overlay",
+        "default": false,
+        "options": [
+          "Yes"
+        ],
+        "shared": true,
+        "description": "Team-maintained. A SKU carries “Yes” when it appears on the Closeouts tab of the 2027 catalog workbook; no value means it is not on that list. Shared with everyone in the workspace — the whole point of R8 is that the TEAM's work lands in the system, not one importer's private column."
+      },
+      {
+        "key": "notes",
+        "label": "Notes",
+        "type": "text",
+        "source": "overlay",
+        "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."
+      }
+    ]
+  }
+}

platform/core/script_sandbox.py

@@ -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/shares.py

@@ -1,296 +1,296 @@
-"""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=…, st=…)   # replaces the whole grant set
-    shares.grants(kind, oid, st=…)                         # -> {'owner': str, 'entries': [...]}
-    shares.role_for(kind, oid, user, is_admin=…, st=…)     # -> 'owner'|'edit'|'view'|None
-    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. Neither ever means "may re-share": changing grants
-is the OWNER's (or an admin's), which is `table_store._may_administer`'s existing rule promoted to
-every kind. 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.
-
-⛔ 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')
-
-#: ⛔⛔ 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'}].
-
-    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.
-    """
-    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)
-        out.append({'user': user, 'role': role})
-    return out
-
-
-def grants(kind, oid, st=None):
-    """`{'owner': str|None, 'entries': [{'user','role'}]}` — never raises on a junk bucket."""
-    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):
-    """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".
-    """
-    kind = _check_kind(kind)
-    oid = str(oid)
-    clean = _clean_entries(entries)
-    owner_l = str(owner).strip().lower() if owner else None
-
-    def _apply(data):
-        by_kind = dict(data.get(kind) or {})
-        prior = by_kind.get(oid) if isinstance(by_kind.get(oid), dict) else {}
-        # 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 clean 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': clean}
-        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):
-    """Only the owner or an admin may change grants or delete. See the module note on why this
-    is deliberately narrower than `may_edit`."""
-    return role_for(kind, oid, user, is_admin=is_admin, st=st) == 'owner'
-
-
-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 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=…, st=…)   # replaces the whole grant set
+    shares.grants(kind, oid, st=…)                         # -> {'owner': str, 'entries': [...]}
+    shares.role_for(kind, oid, user, is_admin=…, st=…)     # -> 'owner'|'edit'|'view'|None
+    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. Neither ever means "may re-share": changing grants
+is the OWNER's (or an admin's), which is `table_store._may_administer`'s existing rule promoted to
+every kind. 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.
+
+⛔ 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')
+
+#: ⛔⛔ 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'}].
+
+    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.
+    """
+    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)
+        out.append({'user': user, 'role': role})
+    return out
+
+
+def grants(kind, oid, st=None):
+    """`{'owner': str|None, 'entries': [{'user','role'}]}` — never raises on a junk bucket."""
+    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):
+    """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".
+    """
+    kind = _check_kind(kind)
+    oid = str(oid)
+    clean = _clean_entries(entries)
+    owner_l = str(owner).strip().lower() if owner else None
+
+    def _apply(data):
+        by_kind = dict(data.get(kind) or {})
+        prior = by_kind.get(oid) if isinstance(by_kind.get(oid), dict) else {}
+        # 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 clean 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': clean}
+        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):
+    """Only the owner or an admin may change grants or delete. See the module note on why this
+    is deliberately narrower than `may_edit`."""
+    return role_for(kind, oid, user, is_admin=is_admin, st=st) == 'owner'
+
+
+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 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/table_store.py

@@ -1,797 +1,797 @@
-"""The generic per-user TABLE WORKSPACE store — the persistence half of the table-page factory.
-
-One durable store key holds one table OBJECT's per-user Airtable-style state:
-
-    {username: {'views':    {view_id: SavedView},
-                'fields':   {field_key: Field},        # notes + custom_ + measure_ strata
-                'overlays': {str(pid): {field_key: value}}}}
-
-`make(table_key)` returns the six operations a table page's host loop needs, closed over that
-key. The Customer table's ops (`modules/customer_data.py`, key 'customer_table_workspace') are
-these exact functions — the logic MOVED here 2026-07-27 so that duplicating the Customer table
-pattern to a new object is a registry row + a config, not a copy of the store plumbing
-(owner directive: the table-page factory).
-
-A LIST (membership/formula semantics) is deliberately a different store from a VIEW
-(presentation/query state) — see modules/customer_data.py's customer_lists key.
-"""
-import core.store as store
-
-#: Wave-9 I17 — the SHARED bucket. Views whose permissions make them visible to anyone but
-#: their creator live here instead of in a personal workspace, under a key that cannot collide
-#: with a username (usernames come from core/users.py and are never dunder-wrapped; `is_shared`
-#: guards it anyway). ONE HOME PER VIEW, never both: a view moved to personal is REMOVED from
-#: here, and a view shared is removed from its creator's workspace. Two homes would mean two
-#: divergent copies the moment either was edited.
-SHARED_KEY = '__shared__'
-
-#: ⭐⭐ W36-T25 — THE COLUMN SUMMARY IS THE DATABASE'S, NOT ONE ACCOUNT'S.
-#:
-#: Owner item 1, second half, verbatim: *"When i filter Avi on my computer sum works for the Sales
-#: last 365 days column but not when my colleague filter it — The sum of the field is not showing
-#: at the bottom even when i zoom out. It only works on my screen??"* Measured while scouting it:
-#: `save_field` writes the WHOLE field payload into `data[username]`, so a column summary — which
-#: is a statement about the COLUMN, identical for every reader by construction — was stored once
-#: per account. Set it, and the totals row exists for you and for nobody else. `computeAggs` then
-#: paints no totals row at all for the colleague (`showTotals` is false when no field carries an
-#: `agg`), which is exactly "not showing at the bottom".
-#:
-#: ⛔ ONLY `agg` MOVES, AND THE LINE IS NOT ARBITRARY. Width, column order, the note, the display
-#: format and every `custom_`/`measure_` definition stay per user, because each of those is a
-#: statement about how ONE PERSON reads the column. "Sum this column" is a statement about what
-#: the column MEANS, and two accounts disagreeing about it is the defect, not a preference.
-#:
-#: ⚠ IT LIVES IN THE `__shared__` MEMBER OF THIS SAME BUCKET rather than in
-#: `core/shared_overlay.py`'s `<key>__shared` document, and the reason is transactional: a summary
-#: is written by the same `save_field` call that writes the note beside it, and the two must land
-#: or fail together. `__shared__` is already this store's tenant-wide member (shared VIEWS live
-#: there) and is guarded against colliding with a username by `is_shared` and by `core/users.py`'s
-#: never-dunder rule, so there is no second bucket, no second flush and no second failure mode.
-SHARED_FIELD_KEYS = ('agg',)
-
-
-def _may_see(view, viewer, is_admin=False):
-    """Visibility for ONE shared view, fail-closed.
-
-    'collaborative' = everyone who can already open the module (the caller has gated that).
-    'users'         = the named users, plus the creator, plus admins — an admin who could not
-                      see a view could not administer it either.
-    Anything unrecognised returns False rather than defaulting open: an unreadable permission
-    must never widen access ([[aios-permissioning]] — no fail-open defaults).
-    """
-    if not isinstance(view, dict):
-        return False
-    if view.get('createdBy') == viewer or is_admin:
-        return True
-    perms = view.get('permissions') or {}
-    edit = perms.get('edit')
-    if edit == 'collaborative':
-        return True
-    if edit == 'users':
-        return viewer in set(perms.get('users') or ())
-    return False                      # 'personal', absent, or junk
-
-
-def _may_edit(view, viewer, is_admin=False):
-    """Who may WRITE a shared view. Same set as visibility today — the owner's item asks 'who
-    can edit' and lists who 'can have access', i.e. seeing and editing are one grant. Kept as a
-    separate function so they can diverge (a future read-only share) without hunting callers."""
-    return _may_see(view, viewer, is_admin)
-
-
-def _may_administer(view, viewer, is_admin=False):
-    """Who may change a view's PERMISSIONS, or delete it: the creator or an admin ONLY.
-
-    Deliberately narrower than _may_edit. If a collaborator could rewrite `permissions` they
-    could grant themselves sole ownership of somebody else's view, or quietly widen a
-    users-scoped view to everyone — the classic privilege-escalation-by-edit hole.
-    """
-    if not isinstance(view, dict):
-        return False
-    return bool(is_admin) or view.get('createdBy') == viewer
-
-
-def is_shared(view):
-    """A view belongs in the shared bucket when its permissions reach beyond its creator."""
-    return ((view or {}).get('permissions') or {}).get('edit') in ('collaborative', 'users')
-
-
-def _shared_fields(data):
-    """The tenant-wide field stratum of one workspace document — `{field_key: {'agg': …}}`.
-
-    ⚠ TOTAL AND FAIL-SOFT: a document written before W36-T25 has no `__shared__` member at all,
-    and one written by a future version may have something else in it. Either way this answers an
-    empty mapping rather than raising, because the caller is a READ that must still serve the
-    workspace — a column with no summary is the state every column was in yesterday.
-    """
-    shared = (data or {}).get(SHARED_KEY)
-    fields = (shared or {}).get('fields') if isinstance(shared, dict) else None
-    return fields if isinstance(fields, dict) else {}
-
-
-def split_shared(payload):
-    """`(per_user, shared)` — one field payload divided at the strata boundary.
-
-    ⭐ W36-T25. `shared` carries only `SHARED_FIELD_KEYS` that are actually SET; `per_user` is the
-    payload without them. Split HERE rather than at each write door so the three doors that store
-    a field (`save_field`, `duplicate_field`, and the delete that must clear it) cannot come apart
-    about where a summary lives — which is the whole reason this module exists rather than being
-    copied per topic.
-    """
-    payload = dict(payload or {})
-    shared = {}
-    for key in SHARED_FIELD_KEYS:
-        value = str(payload.pop(key, '') or '').strip()
-        if value:
-            shared[key] = value
-    return payload, shared
-
-
-def source_override_is_empty(payload):
-    """Does this stored definition of a SOURCE (non-custom) column carry any user state?
-
-    A cleared note on an immutable source field returns to the canonical schema instead of
-    leaving a meaningless override row. Custom fields remain even with an empty note — and so
-    does a PRESET field carrying a measure-window override (wave-2 item 8), a DISPLAY-format
-    override (wave-5 item 10), and, since W29-T83, a COLUMN SUMMARY.
-
-    ⛔ EVERY CLAUSE IS A SETTING A USER MADE, and each one omitted is a setting that silently
-    stops surviving a session. `agg` was missing: choosing Average on Customer's `Overdue days`
-    built an override whose only content was that summary, so this rule threw the whole row away
-    on write while the menu went on reading "Summary: Average" from the client's own optimistic
-    copy until the next login — a discarded WRITE wearing the face of a failed read
-    ([[lost-write-looks-like-failed-read]]). Measured on `bac40c2`; a `ut_*` table, which stores
-    its definitions through another door entirely, kept it.
-
-    ⚠ ONE RULE, TWO CALLERS — here and `grid_events`' store-less fallback. Two copies of a
-    discard rule is how one of them keeps a write the other bins ([[one-evaluator-per-question]]).
-    ⚠ A CLEARED summary still drops the row, which is the intent: with nothing else set, the
-    column goes back to whatever the contract declares for it.
-    """
-    payload = payload or {}
-    if payload.get('custom'):
-        return False
-    return (not str(payload.get('note') or '').strip()
-            and not isinstance(payload.get('measure'), dict)
-            and not isinstance(payload.get('format'), dict)
-            and not str(payload.get('agg') or '').strip())
-
-
-def _unique_name(wanted, existing, *, fallback='Untitled', max_len=120):
-    """Allocate one human-facing name inside a store.update transaction.
-
-    Keys/ids remain structural identity.  Names compare case-insensitively after collapsing
-    whitespace, because those variants are indistinguishable in the UI.  This helper belongs
-    in the store layer: allocating from a pre-write snapshot lets two concurrent requests both
-    choose the same free name before either write lands.
-    """
-    limit = max(1, int(max_len))
-
-    def _clean(value):
-        return ' '.join(str(value or '').split())
-
-    base = (_clean(wanted) or _clean(fallback) or 'Untitled')[:limit].rstrip()
-    taken = {_clean(value).casefold() for value in existing if _clean(value)}
-    if base.casefold() not in taken:
-        return base
-    index = 2
-    while True:
-        suffix = f' {index}'
-        stem = base[:max(0, limit - len(suffix))].rstrip()
-        candidate = f'{stem}{suffix}' if stem else str(index)[-limit:]
-        if candidate.casefold() not in taken:
-            return candidate
-        index += 1
-
-
-class TableStore:
-    """The six store operations for one table object's workspace, closed over its store key.
-
-    `st` (wave 18, C3-UT) is the STORE HANDLE — anything exposing `get(name)` /
-    `update(name, fn, flush=)`. Default = `core.store` (tenant #0, every existing caller,
-    zero behaviour change). The API passes the session's `TenantRuntime`, whose accessors
-    apply the tenant prefix / repo binding — which is what makes a user table created by a
-    Nurilab admin land in Nurilab's store instead of Royal's.
-    """
-
-    def __init__(self, table_key, st=None):
-        self.table_key = table_key
-        self._st = st if st is not None else store
-
-    @property
-    def st(self):
-        """The bound store handle — for SIBLING registries (core/shares) that must read the
-        same tenant's buckets this workspace lives in (wave 21, C1)."""
-        return self._st
-
-    def find_view(self, view_id):
-        """`(owner_username, view)` for a view living in ANY personal stratum, else None.
-
-        ⭐ Wave 21 (item 9, C1): the R10 grant registry names bare ids, so projecting a granted
-        view means locating the OWNER's record inside this topic's bucket. Personal strata
-        only — the `__shared__` bucket has its own read path (`shared_views`), and serving one
-        view from two finders is how two copies drift."""
-        vid = str(view_id or '').strip()
-        if not vid:
-            return None
-        try:
-            data = self._st.get(self.table_key) or {}
-        except Exception:
-            return None
-        for username, ws in data.items():
-            if username == SHARED_KEY or not isinstance(ws, dict):
-                continue
-            v = (ws.get('views') or {}).get(vid)
-            if isinstance(v, dict):
-                return str(username), dict(v)
-        return None
-
-    def find_folder(self, folder_id):
-        """`(owner_username, folder_row, {view_id: view})` for a VIEWS folder living in any
-        personal stratum, else None. `find_view`'s sibling, and here for the same reason.
-
-        ⭐ D-37 (wave 20's R10 remainder, closed 2026-08-05): the grant registry accepts kind
-        `folder` and has since wave 20, but only the VIEW kind was ever projected — so "share
-        this folder with Karen" recorded a row, listed under Shared with me, and put nothing on
-        Karen's screen. Projecting a folder means two lookups the view path does not need: WHO
-        owns it, and WHICH views are filed in it. Folder membership lives in the owner's
-        `itemFolders` map (item id -> folder id), never on the view record, so the views are
-        found by asking that map rather than by reading a list off the folder.
-
-        Views only (`folders['views']`): the cohort surface has its own store and its own
-        sharing question, and answering both here would make one function mean two things.
-        """
-        fid = str(folder_id or '').strip()
-        if not fid:
-            return None
-        try:
-            data = self._st.get(self.table_key) or {}
-        except Exception:
-            return None
-        for username, ws in data.items():
-            if username == SHARED_KEY or not isinstance(ws, dict):
-                continue
-            rows = (ws.get('folders') or {}).get('views') or []
-            hit = next((f for f in rows
-                        if isinstance(f, dict) and str(f.get('id') or '') == fid), None)
-            if not hit:
-                continue
-            # ⚠ `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, …}`) —
-            # reading item ids off the top level finds the surface names instead and matches
-            # nothing, so the projection silently returns an EMPTY folder and the feature looks
-            # exactly as broken as it was before the fix. Caught by this change's own gate,
-            # which is the entire argument for writing one.
-            placed = (ws.get('itemFolders') or {}).get('views') or {}
-            views = ws.get('views') or {}
-            inside = {str(vid): dict(v) for vid, v in views.items()
-                      if isinstance(v, dict) and str(placed.get(str(vid)) or '') == fid}
-            return str(username), dict(hit), inside
-        return None
-
-    # ---------------------------------------------------------------- read
-    def workspace(self, username, consume_corrections=True):
-        """One user's durable workspace: always the full three-strata shape."""
-        try:
-            data = self._st.get(self.table_key) or {}
-            ws = data.get(username, {}) or {}
-            # A collision acknowledgement is protocol state, not part of a field definition.
-            # Consume it with the first fresh workspace payload after the correcting write,
-            # then splice a bounded copy into that payload only.  Keeping it out of `fields`
-            # prevents an old request id surviving forever and overriding a later rename.
-            corrections = {}
-            if consume_corrections and ws.get('fieldCorrections'):
-                def _take(current):
-                    current_ws = current.get(username) or {}
-                    pending = current_ws.get('fieldCorrections') or {}
-                    corrections.update({
-                        str(key)[:80]: dict(value)
-                        for key, value in pending.items()
-                        if isinstance(value, dict)
-                    })
-                    current_ws.pop('fieldCorrections', None)
-                    return current
-
-                data = self._st.update(self.table_key, _take, flush='async')
-                ws = (data or {}).get(username, {}) or {}
-        except Exception:
-            data = {}
-            ws = {}
-            corrections = {}
-        fields = {
-            key: dict(value) if isinstance(value, dict) else value
-            for key, value in (ws.get('fields') or {}).items()
-        }
-        # ⭐⭐ W36-T25 — THE TENANT-WIDE COLUMN SUMMARY, MERGED OVER THIS USER'S STRATUM.
-        # ⛔ IT MUST BE ABLE TO CREATE AN ENTRY, not only decorate one, and that is the whole
-        # reason this is a merge rather than a lookup: the colleague who never touched the column
-        # has NO per-user record for it, so a decorate-only pass would have left them with exactly
-        # the blank totals row the owner reported. `aios_grid.workspace_wire` reads `meta['agg']`
-        # off whatever is here, base column or custom one alike.
-        for key, shared in _shared_fields(data).items():
-            agg = str((shared or {}).get('agg') or '').strip()
-            if not agg:
-                continue
-            entry = fields.get(key)
-            fields[key] = {**entry, 'agg': agg} if isinstance(entry, dict) else {'agg': agg}
-        for key, ack in corrections.items():
-            field = fields.get(key)
-            accepted_label = str(ack.get('label') or '')[:120]
-            requested_label = str(ack.get('labelCorrectedFrom') or '')[:120]
-            correction_id = str(ack.get('labelCorrectionId') or '')[:180]
-            # A newer field write clears/replaces the pending ack in the SAME transaction.
-            # The label check is an extra belt against ever attaching a stale ack to a newer
-            # definition if a future store implementation weakens that ordering.
-            if (isinstance(field, dict) and accepted_label
-                    and str(field.get('label') or '') == accepted_label
-                    and requested_label and correction_id):
-                field['labelCorrectedFrom'] = requested_label
-                field['labelCorrectionId'] = correction_id
-        out = {
-            'views': dict(ws.get('views') or {}),
-            'fields': fields,
-            'overlays': dict(ws.get('overlays') or {}),
-            # wave-8 I11 (C4): folders over the saved views / cohorts sidebars. A FOURTH
-            # stratum rather than a key on each item — see aios_grid.clean_folders for why
-            # (a cohort lives in another store, and filing is an organising act, not part of
-            # what a view is). Absent for every workspace saved before this wave, which is
-            # exactly "no folders yet".
-            'folders': dict(ws.get('folders') or {}),
-            'itemFolders': dict(ws.get('itemFolders') or {}),
-        }
-        # 2026-07-31 (owner item 3): WHERE THE USER LEFT OFF survives a new browser. The
-        # client's localStorage copy wins when present; this is the server's answer for a
-        # fresh profile, which used to fall all the way to the system default view.
-        if ws.get('activeViewId'):
-            out['activeViewId'] = str(ws['activeViewId'])
-        # Wave 2026-08-02 (C-LAYOUT): the per-user record-detail field order. A fifth
-        # stratum, absent until the user first reorders — exactly "default order".
-        if isinstance(ws.get('recordLayout'), dict):
-            out['recordLayout'] = dict(ws['recordLayout'])
-        return out
-
-    # ---------------------------------------------------------------- write
-    def _update(self, username, change, shared=None):
-        """Apply `change(ws)` to this user's stratum, and `shared(shared_fields)` to the
-        tenant-wide one, in ONE transaction.
-
-        ⭐ W36-T25 — `shared` IS A SECOND CALLBACK RATHER THAN A SECOND `update`, and that is the
-        whole reason it exists here instead of at the caller. `save_field` writes a note (per
-        user) and a column summary (tenant-wide) from ONE payload; two transactions would let the
-        summary land while the note did not, and the store's own commit is asynchronous, so the
-        window is real rather than theoretical. One `update`, one flush, one failure mode.
-        """
-        def _up(data):
-            ws = data.setdefault(username, {})
-            ws.setdefault('views', {})
-            ws.setdefault('fields', {})
-            ws.setdefault('overlays', {})
-            ws.setdefault('folders', {})
-            ws.setdefault('itemFolders', {})
-            change(ws)
-            if shared is not None:
-                shared(data.setdefault(SHARED_KEY, {}).setdefault('fields', {}))
-            return data
-        # flush='async' (wave-7 W3): this is THE hot path — every autosaved filter tweak,
-        # column note and typed overlay cell lands here inside the component round-trip, and
-        # the historical synchronous hub commit cost seconds per edit. The mutation applies to
-        # the in-process cache (read-your-writes for every subsequent render); the hub write
-        # coalesces in the background. Registry/auth writes elsewhere stay flush='sync'.
-        return self._st.update(self.table_key, _up, flush='async')
-
-    def rename_choice_values(self, username, change):
-        """Apply an arbitrary workspace rewrite (wave 20, item 15 / C-RENAME).
-
-        ⚠ NAMED FOR ITS ONE CALLER RATHER THAN EXPOSED AS A GENERIC `mutate`, deliberately. A
-        public "do anything to the workspace" method is an invitation to put write logic in
-        callers instead of here, and every OTHER method on this class exists precisely because
-        that logic belongs in one place. Renaming a choice is the one operation that must touch
-        three strata AT ONCE — the field's `choices`, the cells in `overlays`, and the views that
-        filter or colour by the old value — inside a SINGLE transaction, because a rename that
-        updated the cells and not the filters would leave a saved view matching nothing.
-
-        `change(ws)` receives the whole workspace with every stratum pre-created (see `_update`).
-        """
-        return self._update(username, change)
-
-    def save_active_view(self, username, view_id):
-        """Remember which view this user last opened (owner item 3, 2026-07-31).
-
-        Presentation state, not authorisation: the READ side re-validates the id against what
-        the caller may actually see, so a stale or foreign id degrades to the default view
-        rather than granting anything. Stored per user like every other stratum.
-        """
-        vid = str(view_id or '').strip()[:120]
-        if not vid or username == SHARED_KEY:
-            return
-
-        def _set(ws):
-            ws['activeViewId'] = vid
-        self._update(username, _set)
-
-    def save_record_layout(self, username, order):
-        """The per-user RECORD-DETAIL field order (wave 2026-08-02, C-LAYOUT).
-
-        Presentation state for ONE surface — the record modal. Deliberately not view config:
-        the owner's ask is per-user, not per-view, and it must never reorder grid columns.
-        The event handler validated keys against the live field set; the wire re-validates at
-        serve time (aios_grid.workspace_wire), so a deleted field cannot outlive itself here.
-        An empty order clears the stratum back to "default order".
-        """
-        if username == SHARED_KEY:
-            return
-        clean, seen = [], set()
-        for key in (order or [])[:200]:
-            key = str(key or '').strip()[:80]
-            if key and key not in seen:
-                seen.add(key)
-                clean.append(key)
-
-        def _set(ws):
-            if clean:
-                ws['recordLayout'] = {'order': clean}
-            else:
-                ws.pop('recordLayout', None)
-
-        self._update(username, _set)
-
-    def save_folders(self, username, folders, item_folders):
-        """Replace the folder stratum wholesale (wave-8 I11).
-
-        Wholesale rather than per-folder because the caller has ALREADY validated the complete
-        picture through aios_grid.clean_folders / clean_item_folders, and those two are
-        interdependent: a placement is only legal while its folder exists, so committing them
-        separately would leave a window where a reader sees an item filed into a folder that is
-        not there yet. One write, one consistent state.
-        """
-        def _set(ws):
-            ws['folders'] = dict(folders or {})
-            ws['itemFolders'] = dict(item_folders or {})
-        self._update(username, _set)
-
-    def save_view_order(self, username, order):
-        """⭐ WAVE-27 item 5 (contract C7) — this user's own ORDER for the views rail.
-
-        Wholesale, like `save_folders` above and for the same reason: the client sends the full
-        list it is looking at, not a delta, because a partial order cannot say where an UNNAMED
-        view went.
-
-        ⛔ PER USER, and it belongs in this stratum rather than on the view records themselves.
-        `aios_grid`'s own folder note argues it out for placements and every word applies: an
-        arrangement is a per-user ORGANISING act, not part of what a view IS — so keeping it out
-        of the view config means duplicating, sharing or exporting a view does not drag one
-        person's rail position along with it. It also means a SHARED view can sit in a different
-        place for each person who can see it, which is the only coherent answer once two people
-        share one view.
-
-        An empty list CLEARS the arrangement (back to server order) rather than storing `[]`.
-        """
-        def _set(ws):
-            clean = []
-            seen = set()
-            for vid in (order or []):
-                vid = str(vid).strip()[:120]
-                if vid and vid not in seen:
-                    seen.add(vid)
-                    clean.append(vid)
-            if clean:
-                ws['viewOrder'] = clean
-            else:
-                ws.pop('viewOrder', None)
-        self._update(username, _set)
-
-    def shared_views(self, viewer, is_admin=False):
-        """Every SHARED view this viewer may see, by id (wave-9 I17).
-
-        Read-only and independent of the viewer's own workspace: the caller merges. Returns
-        only what `_may_see` allows, so a caller cannot accidentally render somebody else's
-        personal view by forgetting to filter.
-        """
-        try:
-            bucket = ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}).get('views') or {}
-        except Exception:
-            return {}
-        return {vid: dict(v) for vid, v in bucket.items()
-                if _may_see(v, viewer, is_admin)}
-
-    def shared_view(self, view_id):
-        """One shared view RAW — no visibility filter. For authorisation decisions only: a
-        caller must know a view exists and who owns it before it can decide whether the actor
-        may touch it. Never hand the result to a renderer without checking `_may_see`."""
-        try:
-            return ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}
-                    ).get('views', {}).get(str(view_id))
-        except Exception:
-            return None
-
-    def save_view(self, username, view, shared=None, reserved_names=(), is_admin=False):
-        """Upsert a SavedView into its ONE home — personal workspace or the shared bucket.
-
-        `shared` defaults to reading the view's own permissions (`is_shared`). Whichever home
-        it lands in, the view is REMOVED from the other, so a view can never exist as two
-        copies that diverge on the next edit.
-
-        ⚠ AUTHORISATION IS THE CALLER'S JOB and must happen BEFORE this is called — this layer
-        moves data and does not know who is asking. `_cl_handle_one` is the wall.
-        """
-        view_id = str((view or {}).get('id') or '').strip()
-        if not view_id:
-            raise ValueError('view id is required')
-        if username == SHARED_KEY:
-            raise ValueError('reserved username')
-        to_shared = is_shared(view) if shared is None else bool(shared)
-        requested = dict(view)
-        accepted = {}
-
-        def _up(data):
-            # View names are tenant-global: every personal workspace plus the shared bucket.
-            # This deliberately includes views the actor cannot see.  The only disclosed fact
-            # is that a display name is already taken, while the categorical "no duplicate
-            # view names" contract remains true when a personal view is later shared.
-            names = list(reserved_names or ())
-            for workspace in data.values():
-                if not isinstance(workspace, dict):
-                    continue
-                names.extend(
-                    value.get('name')
-                    for candidate_id, value in (workspace.get('views') or {}).items()
-                    if candidate_id != view_id and isinstance(value, dict)
-                )
-            payload = dict(requested)
-            payload['name'] = _unique_name(payload.get('name'), names)
-            accepted.clear()
-            accepted.update(payload)
-            if to_shared:
-                bucket = data.setdefault(SHARED_KEY, {})
-                bucket.setdefault('views', {})[view_id] = payload
-                # it may have lived in the creator's workspace before being shared
-                owner = data.get(payload.get('createdBy') or username) or {}
-                (owner.get('views') or {}).pop(view_id, None)
-            else:
-                ws = data.setdefault(username, {})
-                ws.setdefault('views', {})[view_id] = payload
-                (data.get(SHARED_KEY, {}).get('views') or {}).pop(view_id, None)
-            return data
-
-        self._st.update(self.table_key, _up, flush='async')
-        return dict(accepted)
-
-    def delete_view(self, username, view_id):
-        """Delete a custom/list view override. The system all-rows view is guarded by caller.
-
-        Removes from BOTH homes: the caller has already authorised the delete, and leaving a
-        stale copy in the other bucket would resurrect the view on the next read.
-        """
-        vid = str(view_id)
-
-        def _up(data):
-            (data.get(username, {}).get('views') or {}).pop(vid, None)
-            (data.get(SHARED_KEY, {}).get('views') or {}).pop(vid, None)
-            return data
-
-        self._st.update(self.table_key, _up, flush='async')
-
-    def save_field(self, username, field, reserved_names=(), correction_id=None):
-        """Persist a column note or a user-created (custom_/measure_) field definition.
-
-        ⭐⭐ W36-T25 — THE COLUMN SUMMARY GOES TO THE TENANT-WIDE STRATUM, EVERYTHING ELSE STAYS
-        PER USER, in ONE transaction. See `SHARED_FIELD_KEYS` above for the owner's report and for
-        why the line falls where it does. The returned `accepted` still carries the summary: the
-        caller is echoing back the field it just stored, and dropping a key from that echo would
-        tell the client its write was refused ([[read-path-cannot-witness-write-path]]).
-        """
-        key = str((field or {}).get('key') or '').strip()
-        if not key:
-            raise ValueError('field key is required')
-        requested = dict(field)
-        accepted = {}
-
-        def _save(ws):
-            names = list(reserved_names or ())
-            names.extend(
-                value.get('label')
-                for candidate_key, value in (ws.get('fields') or {}).items()
-                if candidate_key != key and isinstance(value, dict)
-            )
-            payload = dict(requested)
-            payload.pop('labelCorrectedFrom', None)
-            payload.pop('labelCorrectionId', None)
-            requested_label = ' '.join(
-                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
-            payload['label'] = _unique_name(requested_label, names)
-            corrections = ws.setdefault('fieldCorrections', {})
-            corrections.pop(key, None)
-            if payload['label'] != requested_label and correction_id:
-                corrections[key] = {
-                    'label': payload['label'],
-                    'labelCorrectedFrom': requested_label,
-                    'labelCorrectionId': str(correction_id)[:180],
-                }
-            if not corrections:
-                ws.pop('fieldCorrections', None)
-            accepted.clear()
-            accepted.update(payload)
-            # ⭐⭐ W36-T25 — SPLIT AFTER the label allocation and the correction bookkeeping, so
-            # both still see the whole payload, and BEFORE the per-user write.
-            mine, shared_now = split_shared(payload)
-            shared_write.clear()
-            shared_write.update(shared_now)
-            # ⚠ EMPTINESS IS JUDGED ON THE PER-USER HALF. A source column whose ONLY state was a
-            # summary now has no per-user state at all, and leaving an `{}` override behind is the
-            # meaningless row `source_override_is_empty` exists to prevent.
-            if source_override_is_empty(mine):
-                ws['fields'].pop(key, None)
-            else:
-                ws['fields'][key] = mine
-
-        shared_write = {}
-
-        def _share(shared_fields):
-            # ⛔ A CLEARED SUMMARY MUST REMOVE THE ROW, not leave an empty one: `workspace` treats
-            # any entry it finds as a live tenant-wide summary, so an `{'agg': ''}` husk would be
-            # skipped today and become a resurrection hazard the moment the read grows a second
-            # shared key. Absence is the only honest spelling of "nobody set one".
-            if shared_write:
-                shared_fields[key] = {**(shared_fields.get(key) or {}), **shared_write}
-            else:
-                shared_fields.pop(key, None)
-
-        self._update(username, _save, shared=_share)
-        return dict(accepted)
-
-    def duplicate_field(self, username, source_key, new_key, field,
-                        reserved_names=(), correction_id=None):
-        """Clone a user-created field in ONE store transaction (wave-5 item 1): the new
-        definition plus — for `custom_` overlay sources only — every stored cell value under
-        the source key. One transaction, because a def without its values (or values without a
-        def) is exactly the orphan state delete_field exists to prevent, in reverse.
-        The caller validated both keys (same created stratum) and stamped the clone's
-        createdBy; this layer only moves data."""
-        source_key = str(source_key or '').strip()
-        new_key = str(new_key or '').strip()
-        if not source_key or not new_key or source_key == new_key:
-            raise ValueError('duplicate_field needs two distinct keys')
-        requested = dict(field)
-        accepted = {}
-
-        def _dup(ws):
-            names = list(reserved_names or ())
-            names.extend(
-                value.get('label')
-                for candidate_key, value in (ws.get('fields') or {}).items()
-                if candidate_key != new_key and isinstance(value, dict)
-            )
-            payload = dict(requested)
-            payload.pop('labelCorrectedFrom', None)
-            payload.pop('labelCorrectionId', None)
-            requested_label = ' '.join(
-                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
-            payload['label'] = _unique_name(requested_label, names)
-            corrections = ws.setdefault('fieldCorrections', {})
-            corrections.pop(new_key, None)
-            if payload['label'] != requested_label and correction_id:
-                corrections[new_key] = {
-                    'label': payload['label'],
-                    'labelCorrectedFrom': requested_label,
-                    'labelCorrectionId': str(correction_id)[:180],
-                }
-            if not corrections:
-                ws.pop('fieldCorrections', None)
-            accepted.clear()
-            accepted.update(payload)
-            # ⭐ W36-T25: a CLONE carries the original's summary, and a summary is the database's
-            # (see `SHARED_FIELD_KEYS`). Storing it per user here would give the clone a different
-            # residency from every other column — one door out of three disagreeing about where a
-            # thing lives is how `save_field` and this function drift.
-            mine, shared_now = split_shared(payload)
-            shared_write.clear()
-            shared_write.update(shared_now)
-            ws['fields'][new_key] = mine
-            if source_key.startswith('custom_'):
-                for row in ws['overlays'].values():
-                    if isinstance(row, dict) and source_key in row:
-                        row[new_key] = row[source_key]
-
-        shared_write = {}
-
-        def _share(shared_fields):
-            if shared_write:
-                shared_fields[new_key] = {**(shared_fields.get(new_key) or {}), **shared_write}
-            else:
-                shared_fields.pop(new_key, None)
-
-        self._update(username, _dup, shared=_share)
-        return dict(accepted)
-
-    def delete_field(self, username, key):
-        """Delete a USER-CREATED field definition outright (owner gap closed 2026-07-27).
-
-        Only the created strata ever reach here (`custom_` overlay fields, `measure_` formula
-        columns — the caller enforces the prefix). The stored overlay VALUES for the key are
-        scrubbed with it: a deleted column's cells must not linger as orphan data that would
-        silently resurface if the key were ever reused. Views referencing the key self-heal on
-        their next autosave (an unknown colId is dropped) — the rule every stale key rides.
-
-        ⭐⭐ W36-T25 — AND THE TENANT-WIDE SUMMARY GOES WITH IT, for exactly the reason the
-        paragraph above gives about cells: 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. ⚠ This is the ONE stratum a per-user delete may reach across accounts,
-        and it is safe because the summary was never this user's to begin with — deleting the
-        COLUMN is a tenant-wide act already.
-        """
-        key = str(key or '').strip()
-        if not key:
-            return
-
-        def _drop(ws):
-            ws['fields'].pop(key, None)
-            for row in ws['overlays'].values():
-                if isinstance(row, dict):
-                    row.pop(key, None)
-
-        self._update(username, _drop, shared=lambda shared_fields: shared_fields.pop(key, None))
-
-    def _tenant_wide_keys(self):
-        """The columns of THIS table whose values live in the tenant-wide stratum.
-
-        ⭐ THE CHEAP HALF. A table that shares nothing reads one small per-key file (cache-first
-        per process) and answers the empty set, so `patch_overlay` behaves exactly as it did
-        before W38-T20 for every database that has no shared column. It is deliberately not
-        memoised on the instance: `modules/customer_data.py` and `modules/product_data.py` both
-        hold a MODULE-LEVEL `TABLE_OPS`, so a per-instance cache would serve one request's answer
-        to the next, and this one decides WHERE a value is written.
-        ⚠ LENIENT LIKE EVERY OTHER STRATUM READ, and the failure direction is the safe one: an
-        unreachable shared bucket routes the write to the PER-USER stratum, which is the
-        pre-ticket behaviour, rather than dropping it.
-        """
-        try:
-            import core.shared_overlay as shared_overlay
-            return set(shared_overlay.fields(self.table_key, st=self._st) or ())
-        except Exception:                                    # noqa: BLE001
-            return set()
-
-    def patch_overlay(self, username, pid, updates):
-        """Patch only the external editable stratum; never writes to the source system.
-
-        ⭐⭐ W38-T20 / D-423 — A CELL IN A TENANT-WIDE COLUMN GOES TO THE TENANT-WIDE STRATUM,
-        AND WITHOUT THIS SPLIT THE EDIT SILENTLY DISAPPEARS. The read path layers the shared
-        stratum OVER the per-user one (it has to: that is what makes every reader see the same
-        number). This method wrote PER USER. So the sequence was: type a new value, see it accept,
-        come back, and read the shared value again — the owner's *"I went back and it all got
-        reseted"*, with a successful 200 at every step and nothing in any log.
-
-        ⛔ IT IS DECIDED BY WHERE THE COLUMN LIVES, NOT BY WHO IS WRITING OR THROUGH WHICH ROUTE.
-        `modules/product_data._ProductTableStore` has done exactly this since W30-T36 against its
-        CANONICAL list; the only reason it needed a subclass is that its shared columns are
-        declared in a contract file. Columns created at runtime cannot be, so the general form
-        asks the stratum itself. Both doors (`PATCH /customers/{pid}` and `POST /grid/events`)
-        arrive here through `grid_events._tops(ctx)`, which is why the split belongs at the STORE
-        and not at either route: intercepting at one leaves the other writing into the shadow.
-
-        ⛔ NO PERMISSION IS ANSWERED HERE. `shared_overlay`'s header is explicit that it is not a
-        wall, and neither is this: whether this session may write this key is settled upstream by
-        `EventCtx.hidden_keys`, which `routes_customers._hidden_for` now computes over the MERGED
-        contract precisely so a grant-governed column is refused before it reaches this line.
-        """
-        clean = dict(updates or {})
-        if not clean:
-            return
-        wide = self._tenant_wide_keys()
-        shared = {k: v for k, v in clean.items() if k in wide}
-        personal = {k: v for k, v in clean.items() if k not in wide}
-        if shared:
-            import core.shared_overlay as shared_overlay
-            # ⚠ `st=self._st`, NEVER the module default. The two strata must resolve to the SAME
-            # tenant handle, or a value written by one is invisible to the other and the user's
-            # edit vanishes the moment they save it (`_ProductTableStore` records the same rule).
-            shared_overlay.put_cells(self.table_key, pid, shared, st=self._st)
-        if not personal:
-            return
-
-        def _patch(ws):
-            ws['overlays'].setdefault(str(int(pid)), {}).update(personal)
-
-        self._update(username, _patch)
-
-
-def make(table_key, st=None):
-    return TableStore(table_key, st=st)
+"""The generic per-user TABLE WORKSPACE store — the persistence half of the table-page factory.
+
+One durable store key holds one table OBJECT's per-user Airtable-style state:
+
+    {username: {'views':    {view_id: SavedView},
+                'fields':   {field_key: Field},        # notes + custom_ + measure_ strata
+                'overlays': {str(pid): {field_key: value}}}}
+
+`make(table_key)` returns the six operations a table page's host loop needs, closed over that
+key. The Customer table's ops (`modules/customer_data.py`, key 'customer_table_workspace') are
+these exact functions — the logic MOVED here 2026-07-27 so that duplicating the Customer table
+pattern to a new object is a registry row + a config, not a copy of the store plumbing
+(owner directive: the table-page factory).
+
+A LIST (membership/formula semantics) is deliberately a different store from a VIEW
+(presentation/query state) — see modules/customer_data.py's customer_lists key.
+"""
+import core.store as store
+
+#: Wave-9 I17 — the SHARED bucket. Views whose permissions make them visible to anyone but
+#: their creator live here instead of in a personal workspace, under a key that cannot collide
+#: with a username (usernames come from core/users.py and are never dunder-wrapped; `is_shared`
+#: guards it anyway). ONE HOME PER VIEW, never both: a view moved to personal is REMOVED from
+#: here, and a view shared is removed from its creator's workspace. Two homes would mean two
+#: divergent copies the moment either was edited.
+SHARED_KEY = '__shared__'
+
+#: ⭐⭐ W36-T25 — THE COLUMN SUMMARY IS THE DATABASE'S, NOT ONE ACCOUNT'S.
+#:
+#: Owner item 1, second half, verbatim: *"When i filter Avi on my computer sum works for the Sales
+#: last 365 days column but not when my colleague filter it — The sum of the field is not showing
+#: at the bottom even when i zoom out. It only works on my screen??"* Measured while scouting it:
+#: `save_field` writes the WHOLE field payload into `data[username]`, so a column summary — which
+#: is a statement about the COLUMN, identical for every reader by construction — was stored once
+#: per account. Set it, and the totals row exists for you and for nobody else. `computeAggs` then
+#: paints no totals row at all for the colleague (`showTotals` is false when no field carries an
+#: `agg`), which is exactly "not showing at the bottom".
+#:
+#: ⛔ ONLY `agg` MOVES, AND THE LINE IS NOT ARBITRARY. Width, column order, the note, the display
+#: format and every `custom_`/`measure_` definition stay per user, because each of those is a
+#: statement about how ONE PERSON reads the column. "Sum this column" is a statement about what
+#: the column MEANS, and two accounts disagreeing about it is the defect, not a preference.
+#:
+#: ⚠ IT LIVES IN THE `__shared__` MEMBER OF THIS SAME BUCKET rather than in
+#: `core/shared_overlay.py`'s `<key>__shared` document, and the reason is transactional: a summary
+#: is written by the same `save_field` call that writes the note beside it, and the two must land
+#: or fail together. `__shared__` is already this store's tenant-wide member (shared VIEWS live
+#: there) and is guarded against colliding with a username by `is_shared` and by `core/users.py`'s
+#: never-dunder rule, so there is no second bucket, no second flush and no second failure mode.
+SHARED_FIELD_KEYS = ('agg',)
+
+
+def _may_see(view, viewer, is_admin=False):
+    """Visibility for ONE shared view, fail-closed.
+
+    'collaborative' = everyone who can already open the module (the caller has gated that).
+    'users'         = the named users, plus the creator, plus admins — an admin who could not
+                      see a view could not administer it either.
+    Anything unrecognised returns False rather than defaulting open: an unreadable permission
+    must never widen access ([[aios-permissioning]] — no fail-open defaults).
+    """
+    if not isinstance(view, dict):
+        return False
+    if view.get('createdBy') == viewer or is_admin:
+        return True
+    perms = view.get('permissions') or {}
+    edit = perms.get('edit')
+    if edit == 'collaborative':
+        return True
+    if edit == 'users':
+        return viewer in set(perms.get('users') or ())
+    return False                      # 'personal', absent, or junk
+
+
+def _may_edit(view, viewer, is_admin=False):
+    """Who may WRITE a shared view. Same set as visibility today — the owner's item asks 'who
+    can edit' and lists who 'can have access', i.e. seeing and editing are one grant. Kept as a
+    separate function so they can diverge (a future read-only share) without hunting callers."""
+    return _may_see(view, viewer, is_admin)
+
+
+def _may_administer(view, viewer, is_admin=False):
+    """Who may change a view's PERMISSIONS, or delete it: the creator or an admin ONLY.
+
+    Deliberately narrower than _may_edit. If a collaborator could rewrite `permissions` they
+    could grant themselves sole ownership of somebody else's view, or quietly widen a
+    users-scoped view to everyone — the classic privilege-escalation-by-edit hole.
+    """
+    if not isinstance(view, dict):
+        return False
+    return bool(is_admin) or view.get('createdBy') == viewer
+
+
+def is_shared(view):
+    """A view belongs in the shared bucket when its permissions reach beyond its creator."""
+    return ((view or {}).get('permissions') or {}).get('edit') in ('collaborative', 'users')
+
+
+def _shared_fields(data):
+    """The tenant-wide field stratum of one workspace document — `{field_key: {'agg': …}}`.
+
+    ⚠ TOTAL AND FAIL-SOFT: a document written before W36-T25 has no `__shared__` member at all,
+    and one written by a future version may have something else in it. Either way this answers an
+    empty mapping rather than raising, because the caller is a READ that must still serve the
+    workspace — a column with no summary is the state every column was in yesterday.
+    """
+    shared = (data or {}).get(SHARED_KEY)
+    fields = (shared or {}).get('fields') if isinstance(shared, dict) else None
+    return fields if isinstance(fields, dict) else {}
+
+
+def split_shared(payload):
+    """`(per_user, shared)` — one field payload divided at the strata boundary.
+
+    ⭐ W36-T25. `shared` carries only `SHARED_FIELD_KEYS` that are actually SET; `per_user` is the
+    payload without them. Split HERE rather than at each write door so the three doors that store
+    a field (`save_field`, `duplicate_field`, and the delete that must clear it) cannot come apart
+    about where a summary lives — which is the whole reason this module exists rather than being
+    copied per topic.
+    """
+    payload = dict(payload or {})
+    shared = {}
+    for key in SHARED_FIELD_KEYS:
+        value = str(payload.pop(key, '') or '').strip()
+        if value:
+            shared[key] = value
+    return payload, shared
+
+
+def source_override_is_empty(payload):
+    """Does this stored definition of a SOURCE (non-custom) column carry any user state?
+
+    A cleared note on an immutable source field returns to the canonical schema instead of
+    leaving a meaningless override row. Custom fields remain even with an empty note — and so
+    does a PRESET field carrying a measure-window override (wave-2 item 8), a DISPLAY-format
+    override (wave-5 item 10), and, since W29-T83, a COLUMN SUMMARY.
+
+    ⛔ EVERY CLAUSE IS A SETTING A USER MADE, and each one omitted is a setting that silently
+    stops surviving a session. `agg` was missing: choosing Average on Customer's `Overdue days`
+    built an override whose only content was that summary, so this rule threw the whole row away
+    on write while the menu went on reading "Summary: Average" from the client's own optimistic
+    copy until the next login — a discarded WRITE wearing the face of a failed read
+    ([[lost-write-looks-like-failed-read]]). Measured on `bac40c2`; a `ut_*` table, which stores
+    its definitions through another door entirely, kept it.
+
+    ⚠ ONE RULE, TWO CALLERS — here and `grid_events`' store-less fallback. Two copies of a
+    discard rule is how one of them keeps a write the other bins ([[one-evaluator-per-question]]).
+    ⚠ A CLEARED summary still drops the row, which is the intent: with nothing else set, the
+    column goes back to whatever the contract declares for it.
+    """
+    payload = payload or {}
+    if payload.get('custom'):
+        return False
+    return (not str(payload.get('note') or '').strip()
+            and not isinstance(payload.get('measure'), dict)
+            and not isinstance(payload.get('format'), dict)
+            and not str(payload.get('agg') or '').strip())
+
+
+def _unique_name(wanted, existing, *, fallback='Untitled', max_len=120):
+    """Allocate one human-facing name inside a store.update transaction.
+
+    Keys/ids remain structural identity.  Names compare case-insensitively after collapsing
+    whitespace, because those variants are indistinguishable in the UI.  This helper belongs
+    in the store layer: allocating from a pre-write snapshot lets two concurrent requests both
+    choose the same free name before either write lands.
+    """
+    limit = max(1, int(max_len))
+
+    def _clean(value):
+        return ' '.join(str(value or '').split())
+
+    base = (_clean(wanted) or _clean(fallback) or 'Untitled')[:limit].rstrip()
+    taken = {_clean(value).casefold() for value in existing if _clean(value)}
+    if base.casefold() not in taken:
+        return base
+    index = 2
+    while True:
+        suffix = f' {index}'
+        stem = base[:max(0, limit - len(suffix))].rstrip()
+        candidate = f'{stem}{suffix}' if stem else str(index)[-limit:]
+        if candidate.casefold() not in taken:
+            return candidate
+        index += 1
+
+
+class TableStore:
+    """The six store operations for one table object's workspace, closed over its store key.
+
+    `st` (wave 18, C3-UT) is the STORE HANDLE — anything exposing `get(name)` /
+    `update(name, fn, flush=)`. Default = `core.store` (tenant #0, every existing caller,
+    zero behaviour change). The API passes the session's `TenantRuntime`, whose accessors
+    apply the tenant prefix / repo binding — which is what makes a user table created by a
+    Nurilab admin land in Nurilab's store instead of Royal's.
+    """
+
+    def __init__(self, table_key, st=None):
+        self.table_key = table_key
+        self._st = st if st is not None else store
+
+    @property
+    def st(self):
+        """The bound store handle — for SIBLING registries (core/shares) that must read the
+        same tenant's buckets this workspace lives in (wave 21, C1)."""
+        return self._st
+
+    def find_view(self, view_id):
+        """`(owner_username, view)` for a view living in ANY personal stratum, else None.
+
+        ⭐ Wave 21 (item 9, C1): the R10 grant registry names bare ids, so projecting a granted
+        view means locating the OWNER's record inside this topic's bucket. Personal strata
+        only — the `__shared__` bucket has its own read path (`shared_views`), and serving one
+        view from two finders is how two copies drift."""
+        vid = str(view_id or '').strip()
+        if not vid:
+            return None
+        try:
+            data = self._st.get(self.table_key) or {}
+        except Exception:
+            return None
+        for username, ws in data.items():
+            if username == SHARED_KEY or not isinstance(ws, dict):
+                continue
+            v = (ws.get('views') or {}).get(vid)
+            if isinstance(v, dict):
+                return str(username), dict(v)
+        return None
+
+    def find_folder(self, folder_id):
+        """`(owner_username, folder_row, {view_id: view})` for a VIEWS folder living in any
+        personal stratum, else None. `find_view`'s sibling, and here for the same reason.
+
+        ⭐ D-37 (wave 20's R10 remainder, closed 2026-08-05): the grant registry accepts kind
+        `folder` and has since wave 20, but only the VIEW kind was ever projected — so "share
+        this folder with Karen" recorded a row, listed under Shared with me, and put nothing on
+        Karen's screen. Projecting a folder means two lookups the view path does not need: WHO
+        owns it, and WHICH views are filed in it. Folder membership lives in the owner's
+        `itemFolders` map (item id -> folder id), never on the view record, so the views are
+        found by asking that map rather than by reading a list off the folder.
+
+        Views only (`folders['views']`): the cohort surface has its own store and its own
+        sharing question, and answering both here would make one function mean two things.
+        """
+        fid = str(folder_id or '').strip()
+        if not fid:
+            return None
+        try:
+            data = self._st.get(self.table_key) or {}
+        except Exception:
+            return None
+        for username, ws in data.items():
+            if username == SHARED_KEY or not isinstance(ws, dict):
+                continue
+            rows = (ws.get('folders') or {}).get('views') or []
+            hit = next((f for f in rows
+                        if isinstance(f, dict) and str(f.get('id') or '') == fid), None)
+            if not hit:
+                continue
+            # ⚠ `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, …}`) —
+            # reading item ids off the top level finds the surface names instead and matches
+            # nothing, so the projection silently returns an EMPTY folder and the feature looks
+            # exactly as broken as it was before the fix. Caught by this change's own gate,
+            # which is the entire argument for writing one.
+            placed = (ws.get('itemFolders') or {}).get('views') or {}
+            views = ws.get('views') or {}
+            inside = {str(vid): dict(v) for vid, v in views.items()
+                      if isinstance(v, dict) and str(placed.get(str(vid)) or '') == fid}
+            return str(username), dict(hit), inside
+        return None
+
+    # ---------------------------------------------------------------- read
+    def workspace(self, username, consume_corrections=True):
+        """One user's durable workspace: always the full three-strata shape."""
+        try:
+            data = self._st.get(self.table_key) or {}
+            ws = data.get(username, {}) or {}
+            # A collision acknowledgement is protocol state, not part of a field definition.
+            # Consume it with the first fresh workspace payload after the correcting write,
+            # then splice a bounded copy into that payload only.  Keeping it out of `fields`
+            # prevents an old request id surviving forever and overriding a later rename.
+            corrections = {}
+            if consume_corrections and ws.get('fieldCorrections'):
+                def _take(current):
+                    current_ws = current.get(username) or {}
+                    pending = current_ws.get('fieldCorrections') or {}
+                    corrections.update({
+                        str(key)[:80]: dict(value)
+                        for key, value in pending.items()
+                        if isinstance(value, dict)
+                    })
+                    current_ws.pop('fieldCorrections', None)
+                    return current
+
+                data = self._st.update(self.table_key, _take, flush='async')
+                ws = (data or {}).get(username, {}) or {}
+        except Exception:
+            data = {}
+            ws = {}
+            corrections = {}
+        fields = {
+            key: dict(value) if isinstance(value, dict) else value
+            for key, value in (ws.get('fields') or {}).items()
+        }
+        # ⭐⭐ W36-T25 — THE TENANT-WIDE COLUMN SUMMARY, MERGED OVER THIS USER'S STRATUM.
+        # ⛔ IT MUST BE ABLE TO CREATE AN ENTRY, not only decorate one, and that is the whole
+        # reason this is a merge rather than a lookup: the colleague who never touched the column
+        # has NO per-user record for it, so a decorate-only pass would have left them with exactly
+        # the blank totals row the owner reported. `aios_grid.workspace_wire` reads `meta['agg']`
+        # off whatever is here, base column or custom one alike.
+        for key, shared in _shared_fields(data).items():
+            agg = str((shared or {}).get('agg') or '').strip()
+            if not agg:
+                continue
+            entry = fields.get(key)
+            fields[key] = {**entry, 'agg': agg} if isinstance(entry, dict) else {'agg': agg}
+        for key, ack in corrections.items():
+            field = fields.get(key)
+            accepted_label = str(ack.get('label') or '')[:120]
+            requested_label = str(ack.get('labelCorrectedFrom') or '')[:120]
+            correction_id = str(ack.get('labelCorrectionId') or '')[:180]
+            # A newer field write clears/replaces the pending ack in the SAME transaction.
+            # The label check is an extra belt against ever attaching a stale ack to a newer
+            # definition if a future store implementation weakens that ordering.
+            if (isinstance(field, dict) and accepted_label
+                    and str(field.get('label') or '') == accepted_label
+                    and requested_label and correction_id):
+                field['labelCorrectedFrom'] = requested_label
+                field['labelCorrectionId'] = correction_id
+        out = {
+            'views': dict(ws.get('views') or {}),
+            'fields': fields,
+            'overlays': dict(ws.get('overlays') or {}),
+            # wave-8 I11 (C4): folders over the saved views / cohorts sidebars. A FOURTH
+            # stratum rather than a key on each item — see aios_grid.clean_folders for why
+            # (a cohort lives in another store, and filing is an organising act, not part of
+            # what a view is). Absent for every workspace saved before this wave, which is
+            # exactly "no folders yet".
+            'folders': dict(ws.get('folders') or {}),
+            'itemFolders': dict(ws.get('itemFolders') or {}),
+        }
+        # 2026-07-31 (owner item 3): WHERE THE USER LEFT OFF survives a new browser. The
+        # client's localStorage copy wins when present; this is the server's answer for a
+        # fresh profile, which used to fall all the way to the system default view.
+        if ws.get('activeViewId'):
+            out['activeViewId'] = str(ws['activeViewId'])
+        # Wave 2026-08-02 (C-LAYOUT): the per-user record-detail field order. A fifth
+        # stratum, absent until the user first reorders — exactly "default order".
+        if isinstance(ws.get('recordLayout'), dict):
+            out['recordLayout'] = dict(ws['recordLayout'])
+        return out
+
+    # ---------------------------------------------------------------- write
+    def _update(self, username, change, shared=None):
+        """Apply `change(ws)` to this user's stratum, and `shared(shared_fields)` to the
+        tenant-wide one, in ONE transaction.
+
+        ⭐ W36-T25 — `shared` IS A SECOND CALLBACK RATHER THAN A SECOND `update`, and that is the
+        whole reason it exists here instead of at the caller. `save_field` writes a note (per
+        user) and a column summary (tenant-wide) from ONE payload; two transactions would let the
+        summary land while the note did not, and the store's own commit is asynchronous, so the
+        window is real rather than theoretical. One `update`, one flush, one failure mode.
+        """
+        def _up(data):
+            ws = data.setdefault(username, {})
+            ws.setdefault('views', {})
+            ws.setdefault('fields', {})
+            ws.setdefault('overlays', {})
+            ws.setdefault('folders', {})
+            ws.setdefault('itemFolders', {})
+            change(ws)
+            if shared is not None:
+                shared(data.setdefault(SHARED_KEY, {}).setdefault('fields', {}))
+            return data
+        # flush='async' (wave-7 W3): this is THE hot path — every autosaved filter tweak,
+        # column note and typed overlay cell lands here inside the component round-trip, and
+        # the historical synchronous hub commit cost seconds per edit. The mutation applies to
+        # the in-process cache (read-your-writes for every subsequent render); the hub write
+        # coalesces in the background. Registry/auth writes elsewhere stay flush='sync'.
+        return self._st.update(self.table_key, _up, flush='async')
+
+    def rename_choice_values(self, username, change):
+        """Apply an arbitrary workspace rewrite (wave 20, item 15 / C-RENAME).
+
+        ⚠ NAMED FOR ITS ONE CALLER RATHER THAN EXPOSED AS A GENERIC `mutate`, deliberately. A
+        public "do anything to the workspace" method is an invitation to put write logic in
+        callers instead of here, and every OTHER method on this class exists precisely because
+        that logic belongs in one place. Renaming a choice is the one operation that must touch
+        three strata AT ONCE — the field's `choices`, the cells in `overlays`, and the views that
+        filter or colour by the old value — inside a SINGLE transaction, because a rename that
+        updated the cells and not the filters would leave a saved view matching nothing.
+
+        `change(ws)` receives the whole workspace with every stratum pre-created (see `_update`).
+        """
+        return self._update(username, change)
+
+    def save_active_view(self, username, view_id):
+        """Remember which view this user last opened (owner item 3, 2026-07-31).
+
+        Presentation state, not authorisation: the READ side re-validates the id against what
+        the caller may actually see, so a stale or foreign id degrades to the default view
+        rather than granting anything. Stored per user like every other stratum.
+        """
+        vid = str(view_id or '').strip()[:120]
+        if not vid or username == SHARED_KEY:
+            return
+
+        def _set(ws):
+            ws['activeViewId'] = vid
+        self._update(username, _set)
+
+    def save_record_layout(self, username, order):
+        """The per-user RECORD-DETAIL field order (wave 2026-08-02, C-LAYOUT).
+
+        Presentation state for ONE surface — the record modal. Deliberately not view config:
+        the owner's ask is per-user, not per-view, and it must never reorder grid columns.
+        The event handler validated keys against the live field set; the wire re-validates at
+        serve time (aios_grid.workspace_wire), so a deleted field cannot outlive itself here.
+        An empty order clears the stratum back to "default order".
+        """
+        if username == SHARED_KEY:
+            return
+        clean, seen = [], set()
+        for key in (order or [])[:200]:
+            key = str(key or '').strip()[:80]
+            if key and key not in seen:
+                seen.add(key)
+                clean.append(key)
+
+        def _set(ws):
+            if clean:
+                ws['recordLayout'] = {'order': clean}
+            else:
+                ws.pop('recordLayout', None)
+
+        self._update(username, _set)
+
+    def save_folders(self, username, folders, item_folders):
+        """Replace the folder stratum wholesale (wave-8 I11).
+
+        Wholesale rather than per-folder because the caller has ALREADY validated the complete
+        picture through aios_grid.clean_folders / clean_item_folders, and those two are
+        interdependent: a placement is only legal while its folder exists, so committing them
+        separately would leave a window where a reader sees an item filed into a folder that is
+        not there yet. One write, one consistent state.
+        """
+        def _set(ws):
+            ws['folders'] = dict(folders or {})
+            ws['itemFolders'] = dict(item_folders or {})
+        self._update(username, _set)
+
+    def save_view_order(self, username, order):
+        """⭐ WAVE-27 item 5 (contract C7) — this user's own ORDER for the views rail.
+
+        Wholesale, like `save_folders` above and for the same reason: the client sends the full
+        list it is looking at, not a delta, because a partial order cannot say where an UNNAMED
+        view went.
+
+        ⛔ PER USER, and it belongs in this stratum rather than on the view records themselves.
+        `aios_grid`'s own folder note argues it out for placements and every word applies: an
+        arrangement is a per-user ORGANISING act, not part of what a view IS — so keeping it out
+        of the view config means duplicating, sharing or exporting a view does not drag one
+        person's rail position along with it. It also means a SHARED view can sit in a different
+        place for each person who can see it, which is the only coherent answer once two people
+        share one view.
+
+        An empty list CLEARS the arrangement (back to server order) rather than storing `[]`.
+        """
+        def _set(ws):
+            clean = []
+            seen = set()
+            for vid in (order or []):
+                vid = str(vid).strip()[:120]
+                if vid and vid not in seen:
+                    seen.add(vid)
+                    clean.append(vid)
+            if clean:
+                ws['viewOrder'] = clean
+            else:
+                ws.pop('viewOrder', None)
+        self._update(username, _set)
+
+    def shared_views(self, viewer, is_admin=False):
+        """Every SHARED view this viewer may see, by id (wave-9 I17).
+
+        Read-only and independent of the viewer's own workspace: the caller merges. Returns
+        only what `_may_see` allows, so a caller cannot accidentally render somebody else's
+        personal view by forgetting to filter.
+        """
+        try:
+            bucket = ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}).get('views') or {}
+        except Exception:
+            return {}
+        return {vid: dict(v) for vid, v in bucket.items()
+                if _may_see(v, viewer, is_admin)}
+
+    def shared_view(self, view_id):
+        """One shared view RAW — no visibility filter. For authorisation decisions only: a
+        caller must know a view exists and who owns it before it can decide whether the actor
+        may touch it. Never hand the result to a renderer without checking `_may_see`."""
+        try:
+            return ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}
+                    ).get('views', {}).get(str(view_id))
+        except Exception:
+            return None
+
+    def save_view(self, username, view, shared=None, reserved_names=(), is_admin=False):
+        """Upsert a SavedView into its ONE home — personal workspace or the shared bucket.
+
+        `shared` defaults to reading the view's own permissions (`is_shared`). Whichever home
+        it lands in, the view is REMOVED from the other, so a view can never exist as two
+        copies that diverge on the next edit.
+
+        ⚠ AUTHORISATION IS THE CALLER'S JOB and must happen BEFORE this is called — this layer
+        moves data and does not know who is asking. `_cl_handle_one` is the wall.
+        """
+        view_id = str((view or {}).get('id') or '').strip()
+        if not view_id:
+            raise ValueError('view id is required')
+        if username == SHARED_KEY:
+            raise ValueError('reserved username')
+        to_shared = is_shared(view) if shared is None else bool(shared)
+        requested = dict(view)
+        accepted = {}
+
+        def _up(data):
+            # View names are tenant-global: every personal workspace plus the shared bucket.
+            # This deliberately includes views the actor cannot see.  The only disclosed fact
+            # is that a display name is already taken, while the categorical "no duplicate
+            # view names" contract remains true when a personal view is later shared.
+            names = list(reserved_names or ())
+            for workspace in data.values():
+                if not isinstance(workspace, dict):
+                    continue
+                names.extend(
+                    value.get('name')
+                    for candidate_id, value in (workspace.get('views') or {}).items()
+                    if candidate_id != view_id and isinstance(value, dict)
+                )
+            payload = dict(requested)
+            payload['name'] = _unique_name(payload.get('name'), names)
+            accepted.clear()
+            accepted.update(payload)
+            if to_shared:
+                bucket = data.setdefault(SHARED_KEY, {})
+                bucket.setdefault('views', {})[view_id] = payload
+                # it may have lived in the creator's workspace before being shared
+                owner = data.get(payload.get('createdBy') or username) or {}
+                (owner.get('views') or {}).pop(view_id, None)
+            else:
+                ws = data.setdefault(username, {})
+                ws.setdefault('views', {})[view_id] = payload
+                (data.get(SHARED_KEY, {}).get('views') or {}).pop(view_id, None)
+            return data
+
+        self._st.update(self.table_key, _up, flush='async')
+        return dict(accepted)
+
+    def delete_view(self, username, view_id):
+        """Delete a custom/list view override. The system all-rows view is guarded by caller.
+
+        Removes from BOTH homes: the caller has already authorised the delete, and leaving a
+        stale copy in the other bucket would resurrect the view on the next read.
+        """
+        vid = str(view_id)
+
+        def _up(data):
+            (data.get(username, {}).get('views') or {}).pop(vid, None)
+            (data.get(SHARED_KEY, {}).get('views') or {}).pop(vid, None)
+            return data
+
+        self._st.update(self.table_key, _up, flush='async')
+
+    def save_field(self, username, field, reserved_names=(), correction_id=None):
+        """Persist a column note or a user-created (custom_/measure_) field definition.
+
+        ⭐⭐ W36-T25 — THE COLUMN SUMMARY GOES TO THE TENANT-WIDE STRATUM, EVERYTHING ELSE STAYS
+        PER USER, in ONE transaction. See `SHARED_FIELD_KEYS` above for the owner's report and for
+        why the line falls where it does. The returned `accepted` still carries the summary: the
+        caller is echoing back the field it just stored, and dropping a key from that echo would
+        tell the client its write was refused ([[read-path-cannot-witness-write-path]]).
+        """
+        key = str((field or {}).get('key') or '').strip()
+        if not key:
+            raise ValueError('field key is required')
+        requested = dict(field)
+        accepted = {}
+
+        def _save(ws):
+            names = list(reserved_names or ())
+            names.extend(
+                value.get('label')
+                for candidate_key, value in (ws.get('fields') or {}).items()
+                if candidate_key != key and isinstance(value, dict)
+            )
+            payload = dict(requested)
+            payload.pop('labelCorrectedFrom', None)
+            payload.pop('labelCorrectionId', None)
+            requested_label = ' '.join(
+                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
+            payload['label'] = _unique_name(requested_label, names)
+            corrections = ws.setdefault('fieldCorrections', {})
+            corrections.pop(key, None)
+            if payload['label'] != requested_label and correction_id:
+                corrections[key] = {
+                    'label': payload['label'],
+                    'labelCorrectedFrom': requested_label,
+                    'labelCorrectionId': str(correction_id)[:180],
+                }
+            if not corrections:
+                ws.pop('fieldCorrections', None)
+            accepted.clear()
+            accepted.update(payload)
+            # ⭐⭐ W36-T25 — SPLIT AFTER the label allocation and the correction bookkeeping, so
+            # both still see the whole payload, and BEFORE the per-user write.
+            mine, shared_now = split_shared(payload)
+            shared_write.clear()
+            shared_write.update(shared_now)
+            # ⚠ EMPTINESS IS JUDGED ON THE PER-USER HALF. A source column whose ONLY state was a
+            # summary now has no per-user state at all, and leaving an `{}` override behind is the
+            # meaningless row `source_override_is_empty` exists to prevent.
+            if source_override_is_empty(mine):
+                ws['fields'].pop(key, None)
+            else:
+                ws['fields'][key] = mine
+
+        shared_write = {}
+
+        def _share(shared_fields):
+            # ⛔ A CLEARED SUMMARY MUST REMOVE THE ROW, not leave an empty one: `workspace` treats
+            # any entry it finds as a live tenant-wide summary, so an `{'agg': ''}` husk would be
+            # skipped today and become a resurrection hazard the moment the read grows a second
+            # shared key. Absence is the only honest spelling of "nobody set one".
+            if shared_write:
+                shared_fields[key] = {**(shared_fields.get(key) or {}), **shared_write}
+            else:
+                shared_fields.pop(key, None)
+
+        self._update(username, _save, shared=_share)
+        return dict(accepted)
+
+    def duplicate_field(self, username, source_key, new_key, field,
+                        reserved_names=(), correction_id=None):
+        """Clone a user-created field in ONE store transaction (wave-5 item 1): the new
+        definition plus — for `custom_` overlay sources only — every stored cell value under
+        the source key. One transaction, because a def without its values (or values without a
+        def) is exactly the orphan state delete_field exists to prevent, in reverse.
+        The caller validated both keys (same created stratum) and stamped the clone's
+        createdBy; this layer only moves data."""
+        source_key = str(source_key or '').strip()
+        new_key = str(new_key or '').strip()
+        if not source_key or not new_key or source_key == new_key:
+            raise ValueError('duplicate_field needs two distinct keys')
+        requested = dict(field)
+        accepted = {}
+
+        def _dup(ws):
+            names = list(reserved_names or ())
+            names.extend(
+                value.get('label')
+                for candidate_key, value in (ws.get('fields') or {}).items()
+                if candidate_key != new_key and isinstance(value, dict)
+            )
+            payload = dict(requested)
+            payload.pop('labelCorrectedFrom', None)
+            payload.pop('labelCorrectionId', None)
+            requested_label = ' '.join(
+                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
+            payload['label'] = _unique_name(requested_label, names)
+            corrections = ws.setdefault('fieldCorrections', {})
+            corrections.pop(new_key, None)
+            if payload['label'] != requested_label and correction_id:
+                corrections[new_key] = {
+                    'label': payload['label'],
+                    'labelCorrectedFrom': requested_label,
+                    'labelCorrectionId': str(correction_id)[:180],
+                }
+            if not corrections:
+                ws.pop('fieldCorrections', None)
+            accepted.clear()
+            accepted.update(payload)
+            # ⭐ W36-T25: a CLONE carries the original's summary, and a summary is the database's
+            # (see `SHARED_FIELD_KEYS`). Storing it per user here would give the clone a different
+            # residency from every other column — one door out of three disagreeing about where a
+            # thing lives is how `save_field` and this function drift.
+            mine, shared_now = split_shared(payload)
+            shared_write.clear()
+            shared_write.update(shared_now)
+            ws['fields'][new_key] = mine
+            if source_key.startswith('custom_'):
+                for row in ws['overlays'].values():
+                    if isinstance(row, dict) and source_key in row:
+                        row[new_key] = row[source_key]
+
+        shared_write = {}
+
+        def _share(shared_fields):
+            if shared_write:
+                shared_fields[new_key] = {**(shared_fields.get(new_key) or {}), **shared_write}
+            else:
+                shared_fields.pop(new_key, None)
+
+        self._update(username, _dup, shared=_share)
+        return dict(accepted)
+
+    def delete_field(self, username, key):
+        """Delete a USER-CREATED field definition outright (owner gap closed 2026-07-27).
+
+        Only the created strata ever reach here (`custom_` overlay fields, `measure_` formula
+        columns — the caller enforces the prefix). The stored overlay VALUES for the key are
+        scrubbed with it: a deleted column's cells must not linger as orphan data that would
+        silently resurface if the key were ever reused. Views referencing the key self-heal on
+        their next autosave (an unknown colId is dropped) — the rule every stale key rides.
+
+        ⭐⭐ W36-T25 — AND THE TENANT-WIDE SUMMARY GOES WITH IT, for exactly the reason the
+        paragraph above gives about cells: 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. ⚠ This is the ONE stratum a per-user delete may reach across accounts,
+        and it is safe because the summary was never this user's to begin with — deleting the
+        COLUMN is a tenant-wide act already.
+        """
+        key = str(key or '').strip()
+        if not key:
+            return
+
+        def _drop(ws):
+            ws['fields'].pop(key, None)
+            for row in ws['overlays'].values():
+                if isinstance(row, dict):
+                    row.pop(key, None)
+
+        self._update(username, _drop, shared=lambda shared_fields: shared_fields.pop(key, None))
+
+    def _tenant_wide_keys(self):
+        """The columns of THIS table whose values live in the tenant-wide stratum.
+
+        ⭐ THE CHEAP HALF. A table that shares nothing reads one small per-key file (cache-first
+        per process) and answers the empty set, so `patch_overlay` behaves exactly as it did
+        before W38-T20 for every database that has no shared column. It is deliberately not
+        memoised on the instance: `modules/customer_data.py` and `modules/product_data.py` both
+        hold a MODULE-LEVEL `TABLE_OPS`, so a per-instance cache would serve one request's answer
+        to the next, and this one decides WHERE a value is written.
+        ⚠ LENIENT LIKE EVERY OTHER STRATUM READ, and the failure direction is the safe one: an
+        unreachable shared bucket routes the write to the PER-USER stratum, which is the
+        pre-ticket behaviour, rather than dropping it.
+        """
+        try:
+            import core.shared_overlay as shared_overlay
+            return set(shared_overlay.fields(self.table_key, st=self._st) or ())
+        except Exception:                                    # noqa: BLE001
+            return set()
+
+    def patch_overlay(self, username, pid, updates):
+        """Patch only the external editable stratum; never writes to the source system.
+
+        ⭐⭐ W38-T20 / D-423 — A CELL IN A TENANT-WIDE COLUMN GOES TO THE TENANT-WIDE STRATUM,
+        AND WITHOUT THIS SPLIT THE EDIT SILENTLY DISAPPEARS. The read path layers the shared
+        stratum OVER the per-user one (it has to: that is what makes every reader see the same
+        number). This method wrote PER USER. So the sequence was: type a new value, see it accept,
+        come back, and read the shared value again — the owner's *"I went back and it all got
+        reseted"*, with a successful 200 at every step and nothing in any log.
+
+        ⛔ IT IS DECIDED BY WHERE THE COLUMN LIVES, NOT BY WHO IS WRITING OR THROUGH WHICH ROUTE.
+        `modules/product_data._ProductTableStore` has done exactly this since W30-T36 against its
+        CANONICAL list; the only reason it needed a subclass is that its shared columns are
+        declared in a contract file. Columns created at runtime cannot be, so the general form
+        asks the stratum itself. Both doors (`PATCH /customers/{pid}` and `POST /grid/events`)
+        arrive here through `grid_events._tops(ctx)`, which is why the split belongs at the STORE
+        and not at either route: intercepting at one leaves the other writing into the shadow.
+
+        ⛔ NO PERMISSION IS ANSWERED HERE. `shared_overlay`'s header is explicit that it is not a
+        wall, and neither is this: whether this session may write this key is settled upstream by
+        `EventCtx.hidden_keys`, which `routes_customers._hidden_for` now computes over the MERGED
+        contract precisely so a grant-governed column is refused before it reaches this line.
+        """
+        clean = dict(updates or {})
+        if not clean:
+            return
+        wide = self._tenant_wide_keys()
+        shared = {k: v for k, v in clean.items() if k in wide}
+        personal = {k: v for k, v in clean.items() if k not in wide}
+        if shared:
+            import core.shared_overlay as shared_overlay
+            # ⚠ `st=self._st`, NEVER the module default. The two strata must resolve to the SAME
+            # tenant handle, or a value written by one is invisible to the other and the user's
+            # edit vanishes the moment they save it (`_ProductTableStore` records the same rule).
+            shared_overlay.put_cells(self.table_key, pid, shared, st=self._st)
+        if not personal:
+            return
+
+        def _patch(ws):
+            ws['overlays'].setdefault(str(int(pid)), {}).update(personal)
+
+        self._update(username, _patch)
+
+
+def make(table_key, st=None):
+    return TableStore(table_key, st=st)

platform/core/users.py

@@ -1,532 +1,532 @@
-"""Per-user accounts for the platform, persisted in the HF Dataset store (users.json).
-
-Passwords are salted + PBKDF2-HMAC-SHA256 (200k iterations) — never stored or logged in plaintext.
-A bootstrap 'admin' account is seeded from APP_PASSWORD so the owner can always log in and create
-users; APP_PASSWORD also works as an emergency master for 'admin' if the registry is unreachable.
-
-Each account carries BU access ('all' or a list of team-ids [5=Fisch, 6=Royal]) which drives
-allowed_bus() — the basis for per-Business-Unit permissioning (a Royal-only user never sees Fisch).
-"""
-import os
-import hmac
-import hashlib
-import secrets
-
-import core.store as store
-
-BU_LABELS = {5: 'Fisch', 6: 'Royal'}
-_ITER = 200_000
-
-#: Wave 15 C-PERM — the explicit-resolution marker. Mirrors `core.perm_scope.PERMS_VERSION`;
-#: kept as a literal here so `users` does not import the permission layer it is read by.
-PERMS_VERSION = 1
-
-
-def _hash(pw, salt):
-    return hashlib.pbkdf2_hmac('sha256', str(pw).encode('utf-8'), bytes.fromhex(salt), _ITER).hex()
-
-
-def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
-            perms=None, tenant='royal-imports', platform_admin=False):
-    salt = secrets.token_hex(16)
-    rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
-           'bus': bus, 'active': active, 'modules': modules,
-           'agent': agent or None, 'email': email or None,
-           # Wave 18 (C1-TENANT, R1): the account's COMPANY. Absent == 'royal-imports' on every
-           # pre-wave record — no migration. Login binds the session to THIS value; the posted
-           # tenant field can hint but never override it.
-           'tenant': str(tenant or 'royal-imports').strip().lower()}
-    if platform_admin is True:
-        # Wave 19 (R3): the PLATFORM-operator flag — half of `core.platform_admin`'s double lock
-        # (the other half is `tenant == 'loopable'`). Written ONLY for True, so every record that
-        # is not deliberately promoted keeps its pre-wave shape and answers False by absence.
-        # There is no UI writer and there never should be: it is set by provisioning, on purpose.
-        rec['platform_admin'] = True
-    if perms is not None:
-        # Wave 15 C-PERM. A record written WITH perms is migrated by construction — the marker
-        # and the block are set together, here, so no writer can create one without the other.
-        # (`core.perm_scope` reads an unmarked record as legacy, so a block without its marker
-        # would be silently ignored; a marker without a block would deny everything.)
-        rec['perms'] = perms
-        rec['perms_v'] = PERMS_VERSION
-    return rec
-
-
-def registry():
-    return store.get('users')
-
-
-def ensure_bootstrap():
-    """Seed an 'admin' account from APP_PASSWORD ONLY on a truly fresh store (no users file yet).
-    Idempotent; no-op if the store is unavailable (the app then falls back to the master-password
-    path in verify()).
-
-    Critically, this NEVER overwrites an existing registry: it seeds only when store.exists('users')
-    is definitively False. A transient read failure at startup used to return {} and make this
-    re-seed just {admin} over the real accounts — that is the bug that wiped users on restart."""
-    if not store.available():
-        return
-    if store.exists('users'):          # present, or uncertain -> never clobber
-        return
-    try:
-        reg = store.get('users', fresh=True)
-    except Exception:
-        return
-    if reg:
-        return
-    master = os.environ.get('APP_PASSWORD', '')
-    if not master:
-        return
-    try:
-        store.put('users', {'admin': _record(master, 'Administrator', 'admin', 'all')})
-    except Exception:
-        pass
-
-
-def _public(username, u):
-    return {'username': username, 'name': u.get('name', username),
-            'role': u.get('role', 'user'), 'bus': u.get('bus', 'all'),
-            'modules': u.get('modules', 'all'),
-            'agent': u.get('agent'), 'email': u.get('email'),
-            # Wave 18 (C1-TENANT): the session's tenant binding travels on the projection or it
-            # does not travel — the same rule the perms block states below.
-            'tenant': str(u.get('tenant') or 'royal-imports').strip().lower(),
-            # Wave 14 C-AVATAR: the profile photo is public-safe by definition (it is served
-            # to every grid session via the workspace map); without it here the API session's
-            # user record silently drops it and /me can never show your own photo.
-            'avatar': u.get('avatar') or None,
-            # ⛔ WAVE 15 C-PERM — THE WALL TRAVELS ON THIS PROJECTION OR IT DOES NOT TRAVEL.
-            # `deps._user_for` builds every API session from `_public()`, so a `perms` block
-            # dropped here is a restricted account served as an unrestricted one — silently, on
-            # every route, with nothing to notice. `perms_v` must ride ALONG WITH it and for the
-            # same reason inverted: the marker without the block denies everything, the block
-            # without the marker is ignored. Two keys, one fact, never separated.
-            # `verify_api` asserts a restricted user's SESSION OBJECT carries both, at the mount
-            # rather than by grep — a projection is exactly the kind of wiring that looks
-            # present in three files and is absent in the one that runs.
-            **({'perms': u['perms']} if isinstance(u.get('perms'), dict) else {}),
-            **({'perms_v': int(u['perms_v'] or 0)} if u.get('perms_v') else {}),
-            # ⛔ WAVE 19 R3 — THE SAME RULE, ON A NEW FIELD. `deps._user_for` builds every API
-            # session from this projection, so the platform-admin flag travels here or
-            # `core.platform_admin.is_platform_admin(session.user)` is blind and the Loopable
-            # admin plane 403s its own operator. Carried ONLY when the record says True, so a
-            # session dict for any other account is byte-identical to its pre-wave shape.
-            # Not a client leak: `routes_auth._public_user` is a whitelist projection and does
-            # not name this key, so it reaches no browser via /login or /me — the client's copy
-            # is the separate `platformAdmin` bool on GET /settings, which is derived from this.
-            **({'platform_admin': True} if u.get('platform_admin') is True else {}),
-            'epoch': int(u.get('epoch') or 0)}
-
-
-# ------------------------------------------------------------------ session revocation (X3)
-# The API's session cookie is SIGNED AND STATELESS: there is no server-side session table to
-# delete from, so "log this user out everywhere" needs a number that lives with the account. The
-# cookie carries the epoch it was minted under; bumping the account's epoch makes every
-# outstanding cookie for that user fail verification on its next use. Absent == 0, so every
-# record written before this wave is valid without a migration.
-def epoch(username):
-    """The current session epoch for `username`. None when there is no such account.
-
-    None is NOT 0. 0 is "this account exists and has never been revoked"; None is "no record" —
-    which the session verifier must treat as a reason to refuse, not as a default to compare
-    against. (The APP_PASSWORD emergency-master admin has no record at all; the verifier handles
-    that case explicitly rather than inventing an epoch for it here.)
-    """
-    username = (username or '').strip().lower()
-    try:
-        u = (store.get('users') or {}).get(username)
-    except Exception:
-        return None
-    return int((u or {}).get('epoch') or 0) if u else None
-
-
-def bump_epoch(username):
-    """Revoke every outstanding API session for this account."""
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            u['epoch'] = int(u.get('epoch') or 0) + 1
-        return reg
-    store.update('users', _set)
-
-
-def verify(username, pw):
-    """Return a public user dict on success, else None. APP_PASSWORD is an emergency master for the
-    'admin' login even if the store is unreachable, so the owner is never locked out."""
-    username = (username or '').strip().lower()
-    if not username or not pw:
-        return None
-    master = os.environ.get('APP_PASSWORD', '')
-    try:
-        # read fresh so accounts created moments ago (UI or out-of-band) are recognised at once
-        reg = store.get('users', fresh=True)
-    except Exception:
-        reg = {}
-    u = reg.get(username)
-    # ⛔ KEY FIRST, EMAIL SECOND, AND SINCE WAVE 37 THAT ORDER IS A DECISION RATHER THAN AN ACCIDENT.
-    # R8 lets a username BE an email address, so a typed string can now match a registry KEY and a
-    # different account's `email` field at the same time. The key wins, here, by construction: this
-    # branch is only reached when `reg.get(username)` missed. `routes_admin.py::create_user` refuses
-    # to CREATE either collision (`username_shadows_email` / `email_shadows_username`) so the
-    # ambiguity cannot be introduced through the product; this line is what decides it for any
-    # record that arrived some other way.
-    if u is None and '@' in username:
-        # Wave 18 (R1): the login box takes a username OR an email — admin@nurilab.id signs in
-        # without knowing the slug an admin chose. First case-insensitive email match wins;
-        # ambiguity is an admin data problem, not a login feature.
-        for k, r in reg.items():
-            if isinstance(r, dict) and str(r.get('email') or '').strip().lower() == username:
-                username, u = k, r
-                break
-    if u and u.get('active', True) and hmac.compare_digest(_hash(pw, u['salt']), u['hash']):
-        return _public(username, u)
-    # emergency master: admin + APP_PASSWORD always works (covers first run / store outage)
-    if username == 'admin' and master and hmac.compare_digest(str(pw), master):
-        # ⚠ CARRY THE RECORD'S CURRENT EPOCH when there is a record to read, so the session cookie
-        # the API mints from this dict AGREES with the stored account.
-        #
-        # This is not what stops the emergency lockout — `deps._user_for`'s master fallback does
-        # that, and a negative control confirmed the lockout is gone with or without this line.
-        # What it fixes is subtler and is a SCOPE question: a cookie whose epoch disagrees with the
-        # record falls through to that master fallback, which hands back a SYNTHETIC identity
-        # (`bus: 'all'`, `modules: 'all'`). An admin whose record narrows either field would
-        # therefore be silently WIDENED to consolidated, all-module access for the life of that
-        # session. Matching the epoch means the record branch wins and the account's real scope
-        # applies, leaving the master fallback as the true last resort it is meant to be.
-        # 0 when the store is unreachable, which is the case this branch was written for.
-        return {'username': 'admin', 'name': 'Administrator', 'role': 'admin', 'bus': 'all',
-                'modules': 'all', 'epoch': int((reg.get('admin') or {}).get('epoch') or 0)}
-    return None
-
-
-def create_user(username, pw, name, role='user', bus='all', modules='all',
-                agent=None, email=None, tenant=None, platform_admin=None):
-    """Create — or, from app.py's dialog, OVERWRITE — an account.
-
-    ⛔ X3: OVERWRITING AN ACCOUNT MUST NOT RESURRECT ITS OLD SESSIONS. `_record()` builds a fresh
-    record with no `epoch` key, i.e. absent == 0. So re-saving an existing username used to reset
-    the epoch to 0, and every cookie minted before that account's last password rotation started
-    verifying again — a silent un-revocation. `app.py`'s "Add / update a user" calls this function
-    for BOTH add and update, so the hole was reachable from the shipped UI.
-
-    Epoch revocation is only ever as strong as the NARROWEST write path that touches the record, so
-    the carry-and-bump lives here rather than in each caller: an overwrite is at least as
-    session-invalidating as a password change, and it usually IS one.
-    """
-    username = (username or '').strip().lower()
-    if not username or not pw:
-        raise ValueError('username and password are required')
-
-    def _add(reg):
-        prior = reg.get(username) or {}
-        rec = _record(pw, name or username, role, bus, modules=modules,
-                      agent=agent, email=email,
-                      # An overwrite that names no tenant KEEPS the account's company — a
-                      # rename must never quietly move a user between tenants.
-                      tenant=(tenant or prior.get('tenant') or 'royal-imports'),
-                      # Wave 19 (R3): CARRIED, for the same reason `epoch` is carried below —
-                      # `_record` builds a FRESH record, so re-running the provisioner (it is
-                      # documented as idempotent) or saving an account through this function
-                      # would silently DEMOTE a platform admin and lock the operator out of
-                      # their own plane. None = leave as it was; True/False = set it deliberately.
-                      platform_admin=(prior.get('platform_admin') is True
-                                      if platform_admin is None else platform_admin is True))
-        if prior:
-            rec['epoch'] = int(prior.get('epoch') or 0) + 1
-        reg[username] = rec
-        return reg
-    store.update('users', _add)
-
-
-def set_password(username, pw):
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            u['salt'] = secrets.token_hex(16)
-            u['hash'] = _hash(pw, u['salt'])
-            # X3: a password change revokes every outstanding API session for the account. Bumped
-            # INSIDE the same read-modify-write as the hash so the two can never disagree — a
-            # separate update() could rotate the password and leave old cookies live if the second
-            # write failed.
-            u['epoch'] = int(u.get('epoch') or 0) + 1
-        return reg
-    store.update('users', _set)
-
-
-def set_active(username, active):
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        if username in reg:
-            reg[username]['active'] = bool(active)
-            # X3: DEACTIVATION must kill live sessions, not just future logins — otherwise a
-            # disabled account keeps working until its cookie expires. Bumped on reactivation too:
-            # cheap, and it means a re-enabled account never resurrects a stale cookie.
-            reg[username]['epoch'] = int(reg[username].get('epoch') or 0) + 1
-        return reg
-    store.update('users', _set)
-
-
-def set_platform_admin(username, on):
-    """Promote/demote a PLATFORM administrator (wave 19, R3) without touching the password.
-
-    The narrow write, deliberately: `create_user` is the destructive path (fresh salt, fresh
-    hash, bumped epoch) and promoting somebody should not sign them out or rotate a credential.
-    Cleared by REMOVING the key, so a demoted record goes back to its pre-wave shape rather than
-    carrying a `False` that reads as "somebody considered this".
-
-    ⚠ This is the flag only. It grants nothing on its own — `core.platform_admin` also demands
-    the `loopable` tenant, and there is no code path anywhere that moves an account between
-    tenants, which is what makes the second lock hold.
-    """
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            if on is True:
-                u['platform_admin'] = True
-            else:
-                u.pop('platform_admin', None)
-        return reg
-    store.update('users', _set)
-
-
-# ------------------------------------------------------------------ activity stamps (wave 19 R4)
-# "When did this account last sign in, and is anyone actually using it?" — the two questions the
-# Loopable admin plane exists to answer and that NOTHING in the product could answer before this
-# wave (there is no login history, no audit log, no request log anywhere).
-#
-# ⛔ THIS IS THE FIRST HIGH-FREQUENCY WRITER `users.json` HAS EVER HAD, and that bucket also holds
-# every password hash, `active`, `epoch` and the permission blocks. Three rules follow, and the
-# second one is a correctness rule, not a performance one:
-#
-#   1. **In-place mutation of ONE key.** Never `_record()`, never a whole-record replace: a stamp
-#      that rebuilt the record would reset the salt/hash (locking the user out) or the epoch
-#      (silently un-revoking every cookie ever minted for them). `set_password`'s docstring
-#      explains why that class of bug is worth naming out loud.
-#
-#   2. **SYNCHRONOUS FLUSH — deliberately NOT the async path, and this reverses my first draft.**
-#      `store.update(flush='async')` rebases on the PROCESS CACHE once a key is `_owned`
-#      (`core/store.py:284`) and its worker uploads that whole cached blob. For a
-#      table-workspace key, written by one process, that is exactly right. For `users` it is a
-#      silent-revert machine: tenant #0's Streamlit host writes the SAME file, so an API process
-#      holding a cache from an hour ago would, on its next stamp, upload a blob in which a
-#      password rotation or a deactivation performed in the other host simply never happened.
-#      A telemetry stamp must not be able to resurrect a disabled account. `flush='sync'` does a
-#      FRESH strict read inside the store's lock and then uploads, which is the same discipline
-#      every other `users` writer already uses.
-#
-#   3. **OFF THE REQUEST THREAD, so rule 2 costs nothing.** A sync commit is a hub round-trip, and
-#      neither a sign-in nor a random request an hour later should wait for it. Each stamp runs on
-#      a short-lived daemon thread; `flush_stamps()` is how a test or a shutdown waits for them.
-#      Everything is fail-silent: a stamp is telemetry and may never turn a good login into a
-#      failed one — the plane shows an honest "never" instead.
-def _now_iso():
-    import datetime as _dt
-    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec='seconds')
-
-
-#: Live stamp threads, so `flush_stamps()` can join them. Bounded by construction — one thread per
-#: stamp, and a stamp is at most one per login plus one per account per hour per process.
-_STAMPS = []
-_STAMPS_LOCK = __import__('threading').Lock()
-
-
-def _stamp(username, fields):
-    """Merge `fields` into ONE account record, on a background thread, with a fresh read."""
-    username = (username or '').strip().lower()
-    if not username or not fields:
-        return None
-
-    def _set(reg):
-        u = reg.get(username)
-        if isinstance(u, dict):
-            u.update(fields)
-        return reg
-
-    def _work():
-        try:
-            store.update('users', _set)          # sync: fresh strict read + blocking upload
-        except Exception:
-            pass                                  # a lost stamp is a lost stamp, never an error
-    import threading
-    t = threading.Thread(target=_work, daemon=True, name=f'user-stamp:{username}')
-    with _STAMPS_LOCK:
-        _STAMPS[:] = [x for x in _STAMPS if x.is_alive()]
-        _STAMPS.append(t)
-    t.start()
-    return t
-
-
-def flush_stamps(timeout=10.0):
-    """Block until outstanding stamp writes have been applied. For gates and shutdown hooks —
-    the app never needs it, exactly like `core.store.flush`."""
-    with _STAMPS_LOCK:
-        pending = list(_STAMPS)
-    for t in pending:
-        t.join(timeout=timeout)
-    return all(not t.is_alive() for t in pending)
-
-
-def touch_login(username, when=None):
-    """Stamp `last_login` (ISO-8601, UTC, OFFSET-BEARING) on a SUCCESSFUL login.
-
-    `username` must be the RESOLVED account key, not what the person typed: `verify()` accepts an
-    email address and resolves it to the registry key, so stamping the typed identifier would
-    write a stamp onto a key that does not exist and create a phantom account in the registry.
-
-    `last_active` rides along — signing in IS activity, and setting both here means the plane's
-    two columns agree the moment somebody logs in rather than an hour later.
-    """
-    stamp = when or _now_iso()
-    return _stamp(username, {'last_login': stamp, 'last_active': stamp})
-
-
-def touch_active(username, when=None):
-    """Stamp `last_active` — "this session did something". Throttled BY THE CALLER (`deps.py`
-    holds a process-local last-seen map), so this is not a store round-trip per request."""
-    return _stamp(username, {'last_active': when or _now_iso()})
-
-
-def set_access(username, role=None, bus=None, modules=None, agent=None, email=None,
-               name=None, perms=None):
-    """Update access fields. agent/email: pass '' to clear, None to leave unchanged —
-    the user↔agent link scopes the Customer List page / digests to that agent's book.
-
-    `name` follows the same None-means-unchanged idiom. It is here because it had no setter at all:
-    a display name could previously only be changed by re-creating the record through
-    `create_user`, i.e. by also resetting the password (and, before the fix above, the session
-    epoch). Y4's `PATCH {name?}` needs the narrow write, not the destructive one."""
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            if name is not None:
-                u['name'] = name
-            if role is not None:
-                u['role'] = role
-            if bus is not None:
-                u['bus'] = bus
-            if modules is not None:
-                u['modules'] = modules
-            if agent is not None:
-                u['agent'] = agent or None
-            if email is not None:
-                u['email'] = email or None
-            if perms is not None:
-                # Wave 15 C-PERM. Writing perms MIGRATES the record: the marker goes on in the
-                # same read-modify-write, so a record can never end up with one and not the
-                # other (see `_record`). Whole-block replace, matching the PUT route's shape —
-                # a merge would make "remove this restriction" unexpressible.
-                u['perms'] = perms
-                u['perms_v'] = PERMS_VERSION
-        return reg
-    store.update('users', _set)
-
-
-def allowed_bus_labels(user):
-    """BU labels this user may select. 'all' -> All+Fisch+Royal; a single BU -> just that BU (no
-    'All', so the other BU is never reachable); multiple -> All + each."""
-    bus = (user or {}).get('bus', 'all')
-    if bus == 'all':
-        return ['All', 'Fisch', 'Royal']
-    labels = [BU_LABELS[b] for b in bus if b in BU_LABELS]
-    if not labels:
-        return ['All', 'Fisch', 'Royal']
-    return (['All'] + labels) if len(labels) > 1 else labels
-
-
-def assignable_people(tenant=None):
-    """Display names for `user`-typed overlay columns — the tenant's ACTIVE accounts.
-
-    Moved from app.py (2026-07-31) so both hosts serve the same choices. Resolved on every
-    call rather than persisted with the column: a snapshot would keep offering people who
-    have left and never offer people who joined. Deactivated accounts are excluded; a value
-    already stored on a row is untouched — history should still say who owned something.
-
-    Wave 18 (C1-TENANT): pass `tenant` to scope the choices to ONE company — the user registry
-    is a global control-plane bucket, and a Nurilab picker offering Royal's staff is a
-    cross-tenant name leak.
-
-    ⛔⛔ WAVE 33 (W33-T37) — A BLANK `tenant` NOW RETURNS NOTHING. It used to skip the filter and
-    return EVERY tenant's staff: `if want and …` is structurally fail-OPEN, and the exemption was
-    written for "None = unscoped (the Streamlit host, tenant #0's process)" — a host DELETED at
-    EXIT-6. So the sanctioned caller no longer exists, and what was left is a whole-platform
-    roster one forgotten kwarg away, with no error to notice
-    ([[gate-must-go-red-not-crash]]'s sibling: a wall that answers instead of refusing).
-    ⚠ The direction is the safety: this can only ever NARROW. All six live call sites pass
-    `session.tenant`, which `aios_session.read` refuses to admit blank, so nothing legitimate
-    changes — and a future caller that forgets gets an empty picker somebody notices instead of a
-    leak nobody does.
-    """
-    return sorted({str(u.get('name') or n) for n, u in _tenant_accounts(tenant)})
-
-
-def set_avatar(username, data_url):
-    """Set (or clear, with None/'') the user's profile photo — a data URL (wave 14 C-AVATAR,
-    [[loopable-wave14-split]] item 11). Stored VERBATIM; the API route owns validation (mime +
-    decoded size) because this value is served back to every grid session. Cleared by removing
-    the key, so records without a photo keep their pre-wave shape."""
-    username = (username or '').strip().lower()
-
-    def _set(reg):
-        u = reg.get(username)
-        if u:
-            if data_url:
-                u['avatar'] = str(data_url)
-            else:
-                u.pop('avatar', None)
-        return reg
-    store.update('users', _set)
-
-
-def avatar_map(tenant=None):
-    """{display name -> avatar data URL} for ACTIVE accounts with a photo — the companion of
-    `assignable_people()`, keyed by the SAME vocabulary: a `user` cell stores the display
-    name, so the display name is the only join a renderer has. Two active accounts sharing a
-    display name share one option; the first WITH a photo wins the key rather than a coin
-    flip deciding whether the option has a face. `tenant` scopes it exactly as
-    `assignable_people(tenant)` does, and for the same leak — including wave 33's fail-closed
-    blank, which both take from the ONE resolver below rather than each writing `if want and …`.
-    """
-    out = {}
-    for username, u in sorted(_tenant_accounts(tenant), key=lambda kv: kv[0]):
-        av = u.get('avatar')
-        nm = str(u.get('name') or username)
-        if av and nm not in out:
-            out[nm] = str(av)
-    return out
-
-
-def _tenant_accounts(tenant):
-    """`[(username, record), …]` — the ACTIVE accounts of exactly ONE tenant. FAIL-CLOSED.
-
-    ⛔ THE ONE PLACE THE TENANT FILTER FOR THE USER REGISTRY IS WRITTEN. It was written twice,
-    identically, in `assignable_people` and `avatar_map`, and both copies were fail-OPEN on a
-    blank slug in the same way (`if want and …`). Two copies of a wall is two places for one of
-    them to be fixed [[one-question-two-normalizers]]; `routes_shares._people` is a THIRD copy of
-    the same predicate and is lane C's to fold in.
-
-    ⚠ `str(u.get('tenant') or 'royal-imports')` is kept on the RECORD side deliberately: a
-    pre-wave-18 account genuinely has no `tenant` key and IS tenant #0's, and `users._public`
-    normalises it the same way. What changed is the WANT side — a blank want is now a refusal
-    rather than a wildcard.
-    """
-    want = str(tenant or '').strip().lower()
-    if not want:
-        # Not an error and not everything: nobody. See `assignable_people`'s note — the one
-        # caller this exemption was written for (the Streamlit host) was deleted at EXIT-6.
-        return []
-    try:
-        reg = registry() or {}
-    except Exception:
-        return []
-    return [(n, u) for n, u in reg.items()
-            if isinstance(u, dict) and u.get('active') is not False
-            and str(u.get('tenant') or 'royal-imports').strip().lower() == want]
+"""Per-user accounts for the platform, persisted in the HF Dataset store (users.json).
+
+Passwords are salted + PBKDF2-HMAC-SHA256 (200k iterations) — never stored or logged in plaintext.
+A bootstrap 'admin' account is seeded from APP_PASSWORD so the owner can always log in and create
+users; APP_PASSWORD also works as an emergency master for 'admin' if the registry is unreachable.
+
+Each account carries BU access ('all' or a list of team-ids [5=Fisch, 6=Royal]) which drives
+allowed_bus() — the basis for per-Business-Unit permissioning (a Royal-only user never sees Fisch).
+"""
+import os
+import hmac
+import hashlib
+import secrets
+
+import core.store as store
+
+BU_LABELS = {5: 'Fisch', 6: 'Royal'}
+_ITER = 200_000
+
+#: Wave 15 C-PERM — the explicit-resolution marker. Mirrors `core.perm_scope.PERMS_VERSION`;
+#: kept as a literal here so `users` does not import the permission layer it is read by.
+PERMS_VERSION = 1
+
+
+def _hash(pw, salt):
+    return hashlib.pbkdf2_hmac('sha256', str(pw).encode('utf-8'), bytes.fromhex(salt), _ITER).hex()
+
+
+def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
+            perms=None, tenant='royal-imports', platform_admin=False):
+    salt = secrets.token_hex(16)
+    rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
+           'bus': bus, 'active': active, 'modules': modules,
+           'agent': agent or None, 'email': email or None,
+           # Wave 18 (C1-TENANT, R1): the account's COMPANY. Absent == 'royal-imports' on every
+           # pre-wave record — no migration. Login binds the session to THIS value; the posted
+           # tenant field can hint but never override it.
+           'tenant': str(tenant or 'royal-imports').strip().lower()}
+    if platform_admin is True:
+        # Wave 19 (R3): the PLATFORM-operator flag — half of `core.platform_admin`'s double lock
+        # (the other half is `tenant == 'loopable'`). Written ONLY for True, so every record that
+        # is not deliberately promoted keeps its pre-wave shape and answers False by absence.
+        # There is no UI writer and there never should be: it is set by provisioning, on purpose.
+        rec['platform_admin'] = True
+    if perms is not None:
+        # Wave 15 C-PERM. A record written WITH perms is migrated by construction — the marker
+        # and the block are set together, here, so no writer can create one without the other.
+        # (`core.perm_scope` reads an unmarked record as legacy, so a block without its marker
+        # would be silently ignored; a marker without a block would deny everything.)
+        rec['perms'] = perms
+        rec['perms_v'] = PERMS_VERSION
+    return rec
+
+
+def registry():
+    return store.get('users')
+
+
+def ensure_bootstrap():
+    """Seed an 'admin' account from APP_PASSWORD ONLY on a truly fresh store (no users file yet).
+    Idempotent; no-op if the store is unavailable (the app then falls back to the master-password
+    path in verify()).
+
+    Critically, this NEVER overwrites an existing registry: it seeds only when store.exists('users')
+    is definitively False. A transient read failure at startup used to return {} and make this
+    re-seed just {admin} over the real accounts — that is the bug that wiped users on restart."""
+    if not store.available():
+        return
+    if store.exists('users'):          # present, or uncertain -> never clobber
+        return
+    try:
+        reg = store.get('users', fresh=True)
+    except Exception:
+        return
+    if reg:
+        return
+    master = os.environ.get('APP_PASSWORD', '')
+    if not master:
+        return
+    try:
+        store.put('users', {'admin': _record(master, 'Administrator', 'admin', 'all')})
+    except Exception:
+        pass
+
+
+def _public(username, u):
+    return {'username': username, 'name': u.get('name', username),
+            'role': u.get('role', 'user'), 'bus': u.get('bus', 'all'),
+            'modules': u.get('modules', 'all'),
+            'agent': u.get('agent'), 'email': u.get('email'),
+            # Wave 18 (C1-TENANT): the session's tenant binding travels on the projection or it
+            # does not travel — the same rule the perms block states below.
+            'tenant': str(u.get('tenant') or 'royal-imports').strip().lower(),
+            # Wave 14 C-AVATAR: the profile photo is public-safe by definition (it is served
+            # to every grid session via the workspace map); without it here the API session's
+            # user record silently drops it and /me can never show your own photo.
+            'avatar': u.get('avatar') or None,
+            # ⛔ WAVE 15 C-PERM — THE WALL TRAVELS ON THIS PROJECTION OR IT DOES NOT TRAVEL.
+            # `deps._user_for` builds every API session from `_public()`, so a `perms` block
+            # dropped here is a restricted account served as an unrestricted one — silently, on
+            # every route, with nothing to notice. `perms_v` must ride ALONG WITH it and for the
+            # same reason inverted: the marker without the block denies everything, the block
+            # without the marker is ignored. Two keys, one fact, never separated.
+            # `verify_api` asserts a restricted user's SESSION OBJECT carries both, at the mount
+            # rather than by grep — a projection is exactly the kind of wiring that looks
+            # present in three files and is absent in the one that runs.
+            **({'perms': u['perms']} if isinstance(u.get('perms'), dict) else {}),
+            **({'perms_v': int(u['perms_v'] or 0)} if u.get('perms_v') else {}),
+            # ⛔ WAVE 19 R3 — THE SAME RULE, ON A NEW FIELD. `deps._user_for` builds every API
+            # session from this projection, so the platform-admin flag travels here or
+            # `core.platform_admin.is_platform_admin(session.user)` is blind and the Loopable
+            # admin plane 403s its own operator. Carried ONLY when the record says True, so a
+            # session dict for any other account is byte-identical to its pre-wave shape.
+            # Not a client leak: `routes_auth._public_user` is a whitelist projection and does
+            # not name this key, so it reaches no browser via /login or /me — the client's copy
+            # is the separate `platformAdmin` bool on GET /settings, which is derived from this.
+            **({'platform_admin': True} if u.get('platform_admin') is True else {}),
+            'epoch': int(u.get('epoch') or 0)}
+
+
+# ------------------------------------------------------------------ session revocation (X3)
+# The API's session cookie is SIGNED AND STATELESS: there is no server-side session table to
+# delete from, so "log this user out everywhere" needs a number that lives with the account. The
+# cookie carries the epoch it was minted under; bumping the account's epoch makes every
+# outstanding cookie for that user fail verification on its next use. Absent == 0, so every
+# record written before this wave is valid without a migration.
+def epoch(username):
+    """The current session epoch for `username`. None when there is no such account.
+
+    None is NOT 0. 0 is "this account exists and has never been revoked"; None is "no record" —
+    which the session verifier must treat as a reason to refuse, not as a default to compare
+    against. (The APP_PASSWORD emergency-master admin has no record at all; the verifier handles
+    that case explicitly rather than inventing an epoch for it here.)
+    """
+    username = (username or '').strip().lower()
+    try:
+        u = (store.get('users') or {}).get(username)
+    except Exception:
+        return None
+    return int((u or {}).get('epoch') or 0) if u else None
+
+
+def bump_epoch(username):
+    """Revoke every outstanding API session for this account."""
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            u['epoch'] = int(u.get('epoch') or 0) + 1
+        return reg
+    store.update('users', _set)
+
+
+def verify(username, pw):
+    """Return a public user dict on success, else None. APP_PASSWORD is an emergency master for the
+    'admin' login even if the store is unreachable, so the owner is never locked out."""
+    username = (username or '').strip().lower()
+    if not username or not pw:
+        return None
+    master = os.environ.get('APP_PASSWORD', '')
+    try:
+        # read fresh so accounts created moments ago (UI or out-of-band) are recognised at once
+        reg = store.get('users', fresh=True)
+    except Exception:
+        reg = {}
+    u = reg.get(username)
+    # ⛔ KEY FIRST, EMAIL SECOND, AND SINCE WAVE 37 THAT ORDER IS A DECISION RATHER THAN AN ACCIDENT.
+    # R8 lets a username BE an email address, so a typed string can now match a registry KEY and a
+    # different account's `email` field at the same time. The key wins, here, by construction: this
+    # branch is only reached when `reg.get(username)` missed. `routes_admin.py::create_user` refuses
+    # to CREATE either collision (`username_shadows_email` / `email_shadows_username`) so the
+    # ambiguity cannot be introduced through the product; this line is what decides it for any
+    # record that arrived some other way.
+    if u is None and '@' in username:
+        # Wave 18 (R1): the login box takes a username OR an email — admin@nurilab.id signs in
+        # without knowing the slug an admin chose. First case-insensitive email match wins;
+        # ambiguity is an admin data problem, not a login feature.
+        for k, r in reg.items():
+            if isinstance(r, dict) and str(r.get('email') or '').strip().lower() == username:
+                username, u = k, r
+                break
+    if u and u.get('active', True) and hmac.compare_digest(_hash(pw, u['salt']), u['hash']):
+        return _public(username, u)
+    # emergency master: admin + APP_PASSWORD always works (covers first run / store outage)
+    if username == 'admin' and master and hmac.compare_digest(str(pw), master):
+        # ⚠ CARRY THE RECORD'S CURRENT EPOCH when there is a record to read, so the session cookie
+        # the API mints from this dict AGREES with the stored account.
+        #
+        # This is not what stops the emergency lockout — `deps._user_for`'s master fallback does
+        # that, and a negative control confirmed the lockout is gone with or without this line.
+        # What it fixes is subtler and is a SCOPE question: a cookie whose epoch disagrees with the
+        # record falls through to that master fallback, which hands back a SYNTHETIC identity
+        # (`bus: 'all'`, `modules: 'all'`). An admin whose record narrows either field would
+        # therefore be silently WIDENED to consolidated, all-module access for the life of that
+        # session. Matching the epoch means the record branch wins and the account's real scope
+        # applies, leaving the master fallback as the true last resort it is meant to be.
+        # 0 when the store is unreachable, which is the case this branch was written for.
+        return {'username': 'admin', 'name': 'Administrator', 'role': 'admin', 'bus': 'all',
+                'modules': 'all', 'epoch': int((reg.get('admin') or {}).get('epoch') or 0)}
+    return None
+
+
+def create_user(username, pw, name, role='user', bus='all', modules='all',
+                agent=None, email=None, tenant=None, platform_admin=None):
+    """Create — or, from app.py's dialog, OVERWRITE — an account.
+
+    ⛔ X3: OVERWRITING AN ACCOUNT MUST NOT RESURRECT ITS OLD SESSIONS. `_record()` builds a fresh
+    record with no `epoch` key, i.e. absent == 0. So re-saving an existing username used to reset
+    the epoch to 0, and every cookie minted before that account's last password rotation started
+    verifying again — a silent un-revocation. `app.py`'s "Add / update a user" calls this function
+    for BOTH add and update, so the hole was reachable from the shipped UI.
+
+    Epoch revocation is only ever as strong as the NARROWEST write path that touches the record, so
+    the carry-and-bump lives here rather than in each caller: an overwrite is at least as
+    session-invalidating as a password change, and it usually IS one.
+    """
+    username = (username or '').strip().lower()
+    if not username or not pw:
+        raise ValueError('username and password are required')
+
+    def _add(reg):
+        prior = reg.get(username) or {}
+        rec = _record(pw, name or username, role, bus, modules=modules,
+                      agent=agent, email=email,
+                      # An overwrite that names no tenant KEEPS the account's company — a
+                      # rename must never quietly move a user between tenants.
+                      tenant=(tenant or prior.get('tenant') or 'royal-imports'),
+                      # Wave 19 (R3): CARRIED, for the same reason `epoch` is carried below —
+                      # `_record` builds a FRESH record, so re-running the provisioner (it is
+                      # documented as idempotent) or saving an account through this function
+                      # would silently DEMOTE a platform admin and lock the operator out of
+                      # their own plane. None = leave as it was; True/False = set it deliberately.
+                      platform_admin=(prior.get('platform_admin') is True
+                                      if platform_admin is None else platform_admin is True))
+        if prior:
+            rec['epoch'] = int(prior.get('epoch') or 0) + 1
+        reg[username] = rec
+        return reg
+    store.update('users', _add)
+
+
+def set_password(username, pw):
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            u['salt'] = secrets.token_hex(16)
+            u['hash'] = _hash(pw, u['salt'])
+            # X3: a password change revokes every outstanding API session for the account. Bumped
+            # INSIDE the same read-modify-write as the hash so the two can never disagree — a
+            # separate update() could rotate the password and leave old cookies live if the second
+            # write failed.
+            u['epoch'] = int(u.get('epoch') or 0) + 1
+        return reg
+    store.update('users', _set)
+
+
+def set_active(username, active):
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        if username in reg:
+            reg[username]['active'] = bool(active)
+            # X3: DEACTIVATION must kill live sessions, not just future logins — otherwise a
+            # disabled account keeps working until its cookie expires. Bumped on reactivation too:
+            # cheap, and it means a re-enabled account never resurrects a stale cookie.
+            reg[username]['epoch'] = int(reg[username].get('epoch') or 0) + 1
+        return reg
+    store.update('users', _set)
+
+
+def set_platform_admin(username, on):
+    """Promote/demote a PLATFORM administrator (wave 19, R3) without touching the password.
+
+    The narrow write, deliberately: `create_user` is the destructive path (fresh salt, fresh
+    hash, bumped epoch) and promoting somebody should not sign them out or rotate a credential.
+    Cleared by REMOVING the key, so a demoted record goes back to its pre-wave shape rather than
+    carrying a `False` that reads as "somebody considered this".
+
+    ⚠ This is the flag only. It grants nothing on its own — `core.platform_admin` also demands
+    the `loopable` tenant, and there is no code path anywhere that moves an account between
+    tenants, which is what makes the second lock hold.
+    """
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            if on is True:
+                u['platform_admin'] = True
+            else:
+                u.pop('platform_admin', None)
+        return reg
+    store.update('users', _set)
+
+
+# ------------------------------------------------------------------ activity stamps (wave 19 R4)
+# "When did this account last sign in, and is anyone actually using it?" — the two questions the
+# Loopable admin plane exists to answer and that NOTHING in the product could answer before this
+# wave (there is no login history, no audit log, no request log anywhere).
+#
+# ⛔ THIS IS THE FIRST HIGH-FREQUENCY WRITER `users.json` HAS EVER HAD, and that bucket also holds
+# every password hash, `active`, `epoch` and the permission blocks. Three rules follow, and the
+# second one is a correctness rule, not a performance one:
+#
+#   1. **In-place mutation of ONE key.** Never `_record()`, never a whole-record replace: a stamp
+#      that rebuilt the record would reset the salt/hash (locking the user out) or the epoch
+#      (silently un-revoking every cookie ever minted for them). `set_password`'s docstring
+#      explains why that class of bug is worth naming out loud.
+#
+#   2. **SYNCHRONOUS FLUSH — deliberately NOT the async path, and this reverses my first draft.**
+#      `store.update(flush='async')` rebases on the PROCESS CACHE once a key is `_owned`
+#      (`core/store.py:284`) and its worker uploads that whole cached blob. For a
+#      table-workspace key, written by one process, that is exactly right. For `users` it is a
+#      silent-revert machine: tenant #0's Streamlit host writes the SAME file, so an API process
+#      holding a cache from an hour ago would, on its next stamp, upload a blob in which a
+#      password rotation or a deactivation performed in the other host simply never happened.
+#      A telemetry stamp must not be able to resurrect a disabled account. `flush='sync'` does a
+#      FRESH strict read inside the store's lock and then uploads, which is the same discipline
+#      every other `users` writer already uses.
+#
+#   3. **OFF THE REQUEST THREAD, so rule 2 costs nothing.** A sync commit is a hub round-trip, and
+#      neither a sign-in nor a random request an hour later should wait for it. Each stamp runs on
+#      a short-lived daemon thread; `flush_stamps()` is how a test or a shutdown waits for them.
+#      Everything is fail-silent: a stamp is telemetry and may never turn a good login into a
+#      failed one — the plane shows an honest "never" instead.
+def _now_iso():
+    import datetime as _dt
+    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec='seconds')
+
+
+#: Live stamp threads, so `flush_stamps()` can join them. Bounded by construction — one thread per
+#: stamp, and a stamp is at most one per login plus one per account per hour per process.
+_STAMPS = []
+_STAMPS_LOCK = __import__('threading').Lock()
+
+
+def _stamp(username, fields):
+    """Merge `fields` into ONE account record, on a background thread, with a fresh read."""
+    username = (username or '').strip().lower()
+    if not username or not fields:
+        return None
+
+    def _set(reg):
+        u = reg.get(username)
+        if isinstance(u, dict):
+            u.update(fields)
+        return reg
+
+    def _work():
+        try:
+            store.update('users', _set)          # sync: fresh strict read + blocking upload
+        except Exception:
+            pass                                  # a lost stamp is a lost stamp, never an error
+    import threading
+    t = threading.Thread(target=_work, daemon=True, name=f'user-stamp:{username}')
+    with _STAMPS_LOCK:
+        _STAMPS[:] = [x for x in _STAMPS if x.is_alive()]
+        _STAMPS.append(t)
+    t.start()
+    return t
+
+
+def flush_stamps(timeout=10.0):
+    """Block until outstanding stamp writes have been applied. For gates and shutdown hooks —
+    the app never needs it, exactly like `core.store.flush`."""
+    with _STAMPS_LOCK:
+        pending = list(_STAMPS)
+    for t in pending:
+        t.join(timeout=timeout)
+    return all(not t.is_alive() for t in pending)
+
+
+def touch_login(username, when=None):
+    """Stamp `last_login` (ISO-8601, UTC, OFFSET-BEARING) on a SUCCESSFUL login.
+
+    `username` must be the RESOLVED account key, not what the person typed: `verify()` accepts an
+    email address and resolves it to the registry key, so stamping the typed identifier would
+    write a stamp onto a key that does not exist and create a phantom account in the registry.
+
+    `last_active` rides along — signing in IS activity, and setting both here means the plane's
+    two columns agree the moment somebody logs in rather than an hour later.
+    """
+    stamp = when or _now_iso()
+    return _stamp(username, {'last_login': stamp, 'last_active': stamp})
+
+
+def touch_active(username, when=None):
+    """Stamp `last_active` — "this session did something". Throttled BY THE CALLER (`deps.py`
+    holds a process-local last-seen map), so this is not a store round-trip per request."""
+    return _stamp(username, {'last_active': when or _now_iso()})
+
+
+def set_access(username, role=None, bus=None, modules=None, agent=None, email=None,
+               name=None, perms=None):
+    """Update access fields. agent/email: pass '' to clear, None to leave unchanged —
+    the user↔agent link scopes the Customer List page / digests to that agent's book.
+
+    `name` follows the same None-means-unchanged idiom. It is here because it had no setter at all:
+    a display name could previously only be changed by re-creating the record through
+    `create_user`, i.e. by also resetting the password (and, before the fix above, the session
+    epoch). Y4's `PATCH {name?}` needs the narrow write, not the destructive one."""
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            if name is not None:
+                u['name'] = name
+            if role is not None:
+                u['role'] = role
+            if bus is not None:
+                u['bus'] = bus
+            if modules is not None:
+                u['modules'] = modules
+            if agent is not None:
+                u['agent'] = agent or None
+            if email is not None:
+                u['email'] = email or None
+            if perms is not None:
+                # Wave 15 C-PERM. Writing perms MIGRATES the record: the marker goes on in the
+                # same read-modify-write, so a record can never end up with one and not the
+                # other (see `_record`). Whole-block replace, matching the PUT route's shape —
+                # a merge would make "remove this restriction" unexpressible.
+                u['perms'] = perms
+                u['perms_v'] = PERMS_VERSION
+        return reg
+    store.update('users', _set)
+
+
+def allowed_bus_labels(user):
+    """BU labels this user may select. 'all' -> All+Fisch+Royal; a single BU -> just that BU (no
+    'All', so the other BU is never reachable); multiple -> All + each."""
+    bus = (user or {}).get('bus', 'all')
+    if bus == 'all':
+        return ['All', 'Fisch', 'Royal']
+    labels = [BU_LABELS[b] for b in bus if b in BU_LABELS]
+    if not labels:
+        return ['All', 'Fisch', 'Royal']
+    return (['All'] + labels) if len(labels) > 1 else labels
+
+
+def assignable_people(tenant=None):
+    """Display names for `user`-typed overlay columns — the tenant's ACTIVE accounts.
+
+    Moved from app.py (2026-07-31) so both hosts serve the same choices. Resolved on every
+    call rather than persisted with the column: a snapshot would keep offering people who
+    have left and never offer people who joined. Deactivated accounts are excluded; a value
+    already stored on a row is untouched — history should still say who owned something.
+
+    Wave 18 (C1-TENANT): pass `tenant` to scope the choices to ONE company — the user registry
+    is a global control-plane bucket, and a Nurilab picker offering Royal's staff is a
+    cross-tenant name leak.
+
+    ⛔⛔ WAVE 33 (W33-T37) — A BLANK `tenant` NOW RETURNS NOTHING. It used to skip the filter and
+    return EVERY tenant's staff: `if want and …` is structurally fail-OPEN, and the exemption was
+    written for "None = unscoped (the Streamlit host, tenant #0's process)" — a host DELETED at
+    EXIT-6. So the sanctioned caller no longer exists, and what was left is a whole-platform
+    roster one forgotten kwarg away, with no error to notice
+    ([[gate-must-go-red-not-crash]]'s sibling: a wall that answers instead of refusing).
+    ⚠ The direction is the safety: this can only ever NARROW. All six live call sites pass
+    `session.tenant`, which `aios_session.read` refuses to admit blank, so nothing legitimate
+    changes — and a future caller that forgets gets an empty picker somebody notices instead of a
+    leak nobody does.
+    """
+    return sorted({str(u.get('name') or n) for n, u in _tenant_accounts(tenant)})
+
+
+def set_avatar(username, data_url):
+    """Set (or clear, with None/'') the user's profile photo — a data URL (wave 14 C-AVATAR,
+    [[loopable-wave14-split]] item 11). Stored VERBATIM; the API route owns validation (mime +
+    decoded size) because this value is served back to every grid session. Cleared by removing
+    the key, so records without a photo keep their pre-wave shape."""
+    username = (username or '').strip().lower()
+
+    def _set(reg):
+        u = reg.get(username)
+        if u:
+            if data_url:
+                u['avatar'] = str(data_url)
+            else:
+                u.pop('avatar', None)
+        return reg
+    store.update('users', _set)
+
+
+def avatar_map(tenant=None):
+    """{display name -> avatar data URL} for ACTIVE accounts with a photo — the companion of
+    `assignable_people()`, keyed by the SAME vocabulary: a `user` cell stores the display
+    name, so the display name is the only join a renderer has. Two active accounts sharing a
+    display name share one option; the first WITH a photo wins the key rather than a coin
+    flip deciding whether the option has a face. `tenant` scopes it exactly as
+    `assignable_people(tenant)` does, and for the same leak — including wave 33's fail-closed
+    blank, which both take from the ONE resolver below rather than each writing `if want and …`.
+    """
+    out = {}
+    for username, u in sorted(_tenant_accounts(tenant), key=lambda kv: kv[0]):
+        av = u.get('avatar')
+        nm = str(u.get('name') or username)
+        if av and nm not in out:
+            out[nm] = str(av)
+    return out
+
+
+def _tenant_accounts(tenant):
+    """`[(username, record), …]` — the ACTIVE accounts of exactly ONE tenant. FAIL-CLOSED.
+
+    ⛔ THE ONE PLACE THE TENANT FILTER FOR THE USER REGISTRY IS WRITTEN. It was written twice,
+    identically, in `assignable_people` and `avatar_map`, and both copies were fail-OPEN on a
+    blank slug in the same way (`if want and …`). Two copies of a wall is two places for one of
+    them to be fixed [[one-question-two-normalizers]]; `routes_shares._people` is a THIRD copy of
+    the same predicate and is lane C's to fold in.
+
+    ⚠ `str(u.get('tenant') or 'royal-imports')` is kept on the RECORD side deliberately: a
+    pre-wave-18 account genuinely has no `tenant` key and IS tenant #0's, and `users._public`
+    normalises it the same way. What changed is the WANT side — a blank want is now a refusal
+    rather than a wildcard.
+    """
+    want = str(tenant or '').strip().lower()
+    if not want:
+        # Not an error and not everything: nobody. See `assignable_people`'s note — the one
+        # caller this exemption was written for (the Streamlit host) was deleted at EXIT-6.
+        return []
+    try:
+        reg = registry() or {}
+    except Exception:
+        return []
+    return [(n, u) for n, u in reg.items()
+            if isinstance(u, dict) and u.get('active') is not False
+            and str(u.get('tenant') or 'royal-imports').strip().lower() == want]

platform/harness/meta_store.py

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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_customers.yml

@@ -1,213 +1,213 @@
-# ⭐⭐ 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_customers
-label: "Odoo customers"
-entity: res.partner
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: customer_data
-subject: "odoo:res.partner"
-grain: "one row per customer in tenant #0's scoped book — a REGISTRY, not a dated event stream. Identity is the Odoo `res.partner` id (the row's `pid` IS that id)."
-scope:
-  population: "the customer book `modules/customer_data.pool()` builds; the grid's own contract states it as one row per customer who ordered in the last 24 months"
-  identity: "the Odoo res.partner id — exposed as the `partner_id` column (W33-T43) and used as the row pid, so there is ONE id per row and no second one"
-  merged: "W33-T44 retired `ut_odoo_customers`, which presented this same subject. This topic describes the SURVIVING database, `customer_data`, which keeps its store bucket so no saved view, grant, cohort or formula moved"
-  no_date: "a registry has no date dimension; ask sales_lines or customer_invoices for anything time-windowed about a customer"
-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:
-    agent: {label: "Sales agent"}
-    state: {label: "State"}
-    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: customer
-    label: "Customer"
-    type: text
-    kind: data
-    means: "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
-  - key: partner_id
-    label: "Odoo ID"
-    type: int
-    kind: data
-    means: "The Odoo res.partner id — this row's identity, and the key every Odoo document joins on. W33-T43 / owner item 12: 'One unique ID per database always.' It is DERIVED rather than read off the pool row because a customer row's pid IS the partner id, so the value is already on every row and a second copy in the pool would be a second source for one fact."
-  - key: odoo_status
-    label: "Odoo record"
-    type: status
-    kind: data
-    means: "Whether this customer still exists in Odoo. Archived means deleted there."
-  - key: agent
-    label: "Agent"
-    type: text
-    kind: data
-    means: "The sales agent who owns this account."
-  - key: dba
-    label: "DBA"
-    type: select
-    kind: data
-    means: "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
-  - key: salesperson
-    label: "Salesperson"
-    type: text
-    kind: data
-    means: "Who keyed in most of this customer's orders — not the Agent, who owns the account."
-  - key: street
-    label: "Street"
-    type: text
-    kind: data
-    means: "First address line, from res.partner directly - not the geocoder, so a customer the map cannot place still shows its address."
-  - key: street2
-    label: "Street 2"
-    type: text
-    kind: data
-    means: "Second address line (suite, unit, floor) on the customer's Odoo address."
-  - key: city
-    label: "City"
-    type: text
-    kind: data
-    means: "City on the customer's Odoo address."
-  - key: state
-    label: "State"
-    type: text
-    kind: data
-    means: "State or province on the customer's Odoo address."
-  - key: country
-    label: "Country"
-    type: text
-    kind: data
-    means: "Country on the customer's Odoo address."
-  - key: zip
-    label: "ZIP"
-    type: text
-    kind: data
-    means: "Postal code on the customer's Odoo address."
-  - key: customer_since
-    label: "Customer since"
-    type: date
-    kind: data
-    means: "When this customer was first set up in Odoo."
-  - key: tags
-    label: "Tags"
-    type: text
-    kind: data
-    means: "Odoo labels on this customer, comma-separated."
-  - key: pricelist
-    label: "Price list"
-    type: text
-    kind: data
-    means: "The price list this customer buys on."
-  - key: payment_terms
-    label: "Payment terms"
-    type: text
-    kind: data
-    means: "Payment terms on this customer's account — Net 30, for example."
-  - key: last_order
-    label: "Last order"
-    type: date
-    kind: data
-    means: "Date of the most recent confirmed order."
-  - key: overdue_days
-    label: "Overdue days"
-    type: int
-    kind: data
-    means: "How many days late this customer is running against their own usual ordering rhythm."
-  - key: est_missed
-    label: "Est. missed $"
-    type: currency
-    kind: data
-    means: "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
-  - key: ar_open
-    label: "AR current $"
-    type: currency
-    kind: data
-    means: "Invoiced money owed but not yet due (a 5-day grace applies before it counts as overdue)."
-  - key: ar_overdue
-    label: "AR overdue $"
-    type: currency
-    kind: data
-    means: "Invoiced money past due — same basis as the Collections page."
-  - key: ar_outstanding
-    label: "AR outstanding $"
-    type: currency
-    kind: data
-    means: "Total invoiced money owed right now: AR current $ plus AR overdue $."
-  - key: ar_exposure
-    label: "Credit exposure $"
-    type: currency
-    kind: data
-    means: "The most you could be out if they stopped paying today: open, overdue, draft and not-yet-invoiced."
-  - key: ar_aged_1_30
-    label: "1-30 days $"
-    type: currency
-    kind: data
-    means: "Overdue between 1 and 30 days. The four aging buckets sum to AR overdue $."
-  - key: ar_aged_31_60
-    label: "31-60 days $"
-    type: currency
-    kind: data
-    means: "Overdue between 31 and 60 days. The four aging buckets sum to AR overdue $."
-  - key: ar_aged_61_90
-    label: "61-90 days $"
-    type: currency
-    kind: data
-    means: "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
-  - key: ar_aged_90_plus
-    label: "90+ days $"
-    type: currency
-    kind: data
-    means: "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
-  - key: days_to_pay
-    label: "Days to pay"
-    type: int
-    kind: data
-    means: "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
-  - key: top_category
-    label: "Top category"
-    type: text
-    kind: data
-    means: "The category this customer spent the most on in the last 12 months."
-  - key: top_category_pct
-    label: "Top category %"
-    type: pct
-    kind: data
-    means: "Share of last-12-months spend that went to the top category."
-  - key: sku_count
-    label: "SKUs bought"
-    type: int
-    kind: data
-    means: "Distinct products bought in the last 12 months."
-  - key: top_sku
-    label: "Top SKU"
-    type: text
-    kind: data
-    means: "The product this customer spent the most on in the last 12 months."
-  - key: days_since
-    label: "Days since order"
-    type: int
-    kind: data
-    means: "Days since the last confirmed order."
-  - key: typical_gap_days
-    label: "Typical gap days"
-    type: int
-    kind: data
-    means: "Days this customer usually goes between orders, from their own history."
-  - key: notes
-    label: "Notes"
-    type: text
-    kind: data
-    means: "Your notes on this customer. Saved in this app only, visible only to you."
-
-ai_context: >
-  The customer REGISTRY as a person sees it in the app — the database labelled 'Odoo customers'.
-  Use it to answer 'who is this customer', 'which customers exist', 'which agent owns them', 'where are they', and for the AR columns it carries (ar_open, ar_overdue, days_to_pay), which are reconciled by modules/ar.py.
-  ⛔ For anything WINDOWED or at line grain go to sales_lines / customer_invoices / receivables — those topics own the time dimension and this one has none.
+# ⭐⭐ 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_customers
+label: "Odoo customers"
+entity: res.partner
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: customer_data
+subject: "odoo:res.partner"
+grain: "one row per customer in tenant #0's scoped book — a REGISTRY, not a dated event stream. Identity is the Odoo `res.partner` id (the row's `pid` IS that id)."
+scope:
+  population: "the customer book `modules/customer_data.pool()` builds; the grid's own contract states it as one row per customer who ordered in the last 24 months"
+  identity: "the Odoo res.partner id — exposed as the `partner_id` column (W33-T43) and used as the row pid, so there is ONE id per row and no second one"
+  merged: "W33-T44 retired `ut_odoo_customers`, which presented this same subject. This topic describes the SURVIVING database, `customer_data`, which keeps its store bucket so no saved view, grant, cohort or formula moved"
+  no_date: "a registry has no date dimension; ask sales_lines or customer_invoices for anything time-windowed about a customer"
+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:
+    agent: {label: "Sales agent"}
+    state: {label: "State"}
+    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: customer
+    label: "Customer"
+    type: text
+    kind: data
+    means: "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
+  - key: partner_id
+    label: "Odoo ID"
+    type: int
+    kind: data
+    means: "The Odoo res.partner id — this row's identity, and the key every Odoo document joins on. W33-T43 / owner item 12: 'One unique ID per database always.' It is DERIVED rather than read off the pool row because a customer row's pid IS the partner id, so the value is already on every row and a second copy in the pool would be a second source for one fact."
+  - key: odoo_status
+    label: "Odoo record"
+    type: status
+    kind: data
+    means: "Whether this customer still exists in Odoo. Archived means deleted there."
+  - key: agent
+    label: "Agent"
+    type: text
+    kind: data
+    means: "The sales agent who owns this account."
+  - key: dba
+    label: "DBA"
+    type: select
+    kind: data
+    means: "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
+  - key: salesperson
+    label: "Salesperson"
+    type: text
+    kind: data
+    means: "Who keyed in most of this customer's orders — not the Agent, who owns the account."
+  - key: street
+    label: "Street"
+    type: text
+    kind: data
+    means: "First address line, from res.partner directly - not the geocoder, so a customer the map cannot place still shows its address."
+  - key: street2
+    label: "Street 2"
+    type: text
+    kind: data
+    means: "Second address line (suite, unit, floor) on the customer's Odoo address."
+  - key: city
+    label: "City"
+    type: text
+    kind: data
+    means: "City on the customer's Odoo address."
+  - key: state
+    label: "State"
+    type: text
+    kind: data
+    means: "State or province on the customer's Odoo address."
+  - key: country
+    label: "Country"
+    type: text
+    kind: data
+    means: "Country on the customer's Odoo address."
+  - key: zip
+    label: "ZIP"
+    type: text
+    kind: data
+    means: "Postal code on the customer's Odoo address."
+  - key: customer_since
+    label: "Customer since"
+    type: date
+    kind: data
+    means: "When this customer was first set up in Odoo."
+  - key: tags
+    label: "Tags"
+    type: text
+    kind: data
+    means: "Odoo labels on this customer, comma-separated."
+  - key: pricelist
+    label: "Price list"
+    type: text
+    kind: data
+    means: "The price list this customer buys on."
+  - key: payment_terms
+    label: "Payment terms"
+    type: text
+    kind: data
+    means: "Payment terms on this customer's account — Net 30, for example."
+  - key: last_order
+    label: "Last order"
+    type: date
+    kind: data
+    means: "Date of the most recent confirmed order."
+  - key: overdue_days
+    label: "Overdue days"
+    type: int
+    kind: data
+    means: "How many days late this customer is running against their own usual ordering rhythm."
+  - key: est_missed
+    label: "Est. missed $"
+    type: currency
+    kind: data
+    means: "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
+  - key: ar_open
+    label: "AR current $"
+    type: currency
+    kind: data
+    means: "Invoiced money owed but not yet due (a 5-day grace applies before it counts as overdue)."
+  - key: ar_overdue
+    label: "AR overdue $"
+    type: currency
+    kind: data
+    means: "Invoiced money past due — same basis as the Collections page."
+  - key: ar_outstanding
+    label: "AR outstanding $"
+    type: currency
+    kind: data
+    means: "Total invoiced money owed right now: AR current $ plus AR overdue $."
+  - key: ar_exposure
+    label: "Credit exposure $"
+    type: currency
+    kind: data
+    means: "The most you could be out if they stopped paying today: open, overdue, draft and not-yet-invoiced."
+  - key: ar_aged_1_30
+    label: "1-30 days $"
+    type: currency
+    kind: data
+    means: "Overdue between 1 and 30 days. The four aging buckets sum to AR overdue $."
+  - key: ar_aged_31_60
+    label: "31-60 days $"
+    type: currency
+    kind: data
+    means: "Overdue between 31 and 60 days. The four aging buckets sum to AR overdue $."
+  - key: ar_aged_61_90
+    label: "61-90 days $"
+    type: currency
+    kind: data
+    means: "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
+  - key: ar_aged_90_plus
+    label: "90+ days $"
+    type: currency
+    kind: data
+    means: "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
+  - key: days_to_pay
+    label: "Days to pay"
+    type: int
+    kind: data
+    means: "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
+  - key: top_category
+    label: "Top category"
+    type: text
+    kind: data
+    means: "The category this customer spent the most on in the last 12 months."
+  - key: top_category_pct
+    label: "Top category %"
+    type: pct
+    kind: data
+    means: "Share of last-12-months spend that went to the top category."
+  - key: sku_count
+    label: "SKUs bought"
+    type: int
+    kind: data
+    means: "Distinct products bought in the last 12 months."
+  - key: top_sku
+    label: "Top SKU"
+    type: text
+    kind: data
+    means: "The product this customer spent the most on in the last 12 months."
+  - key: days_since
+    label: "Days since order"
+    type: int
+    kind: data
+    means: "Days since the last confirmed order."
+  - key: typical_gap_days
+    label: "Typical gap days"
+    type: int
+    kind: data
+    means: "Days this customer usually goes between orders, from their own history."
+  - key: notes
+    label: "Notes"
+    type: text
+    kind: data
+    means: "Your notes on this customer. Saved in this app only, visible only to you."
+
+ai_context: >
+  The customer REGISTRY as a person sees it in the app — the database labelled 'Odoo customers'.
+  Use it to answer 'who is this customer', 'which customers exist', 'which agent owns them', 'where are they', and for the AR columns it carries (ar_open, ar_overdue, days_to_pay), which are reconciled by modules/ar.py.
+  ⛔ For anything WINDOWED or at line grain go to sales_lines / customer_invoices / receivables — those topics own the time dimension and this one has none.

platform/model/topics/odoo_invoices.yml

@@ -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

@@ -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

@@ -1,198 +1,198 @@
-# ⭐⭐ 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_products
-label: "Odoo products"
-entity: product.product
-# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
-grid: product_data
-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:
-  table: product_product
-  alias: pp
-  # 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:
-    category: {label: "Category"}
-    supplier: {label: "Supplier"}
-
-# ⭐⭐ W37-T10 / owner item 4 (ruling R1) — THE LOOKBACK-MEASURE BINDING. Owner: *"Odoo products
-# should have a lookbsck metrics like sales etc."* This block is what turns `measures: []` on the
-# product workspace into a real catalogue, and it is DECLARED HERE rather than hand-written in a
-# route for the reason `_rollup_source_offer` gives about itself: a second list is a second
-# definition of the same fact, and the two drift the day somebody adds a metric.
-#
-# ⛔ THE JOIN KEY IS THE TRAP CONTRACT C1 NAMES, and this is where it is answered. `source` is a
-# FACT topic; `dim` is the dim of THAT topic which carries THIS entity's identity. `sales_lines`
-# has two candidates and only one is right: `product` groups by Odoo's `product_id`, while this
-# database's identity (see `scope.identity` above) is `default_code`. Binding to `product` would
-# key every cell on a number no grid row carries — a column of nulls that reads as "never sold".
-#
-# ⚠ A SINGLE-TOPIC GROUPED QUERY, which is why `semantic.store_query`'s cross-topic refusal does
-# not bite: `revenue` lives ON `sales_lines` and we group `sales_lines` by its OWN dim. The same
-# refusal is real and DOES bite `aov`/`orders` (denominator `orders` lives on `sales_orders`), so
-# those two are absent from `keys` below and `entity_measures()` re-proves that rather than
-# trusting this list.
-# ⭐ A LIST SINCE W37-T13: an entity's columns legitimately come from more than ONE fact topic.
-# Sales movement is `sales_lines`; physical movement is `stock_moves`. Same grid, same join key
-# (`product_code`), different tables — forcing stock into the sales topic would have defined a
-# metric against rows it does not have.
-measures:
-- source: sales_lines
-  dim: product_code
-  # ⭐ The SHIP-FIRST six of `proto/P3-metric-catalog.md`, and they cost ONE grouped query
-  # together (measured 0.22 s over 1,670 groups against the mirror; 2.55 s live).
-  keys: [units, revenue, margin, cogs, margin_pct, asp]
-  # ⛔ REPORTED, NOT SILENTLY DROPPED (standing rule 1's second sentence, applied to a catalogue).
-  # Each of these is a real metric `proto/P3-metric-catalog.md` measured and this wave does not
-  # ship, with the CAUSE and the fix — so the next session extends the list instead of
-  # re-measuring, and nobody reads the six as "all Odoo can answer".
-  not_yet:
-    - key: days_since_last_sale
-      cause: "needs `agg: max` over a DATE, which `semantic._measure_sql` does not implement (sum | count | count_distinct only), and a date-typed measure could not render anyway: `aios_grid.MEASURE_FIELD_TYPES` is {currency, int, pct}"
-      fix: "add `agg: max` to `_measure_sql` and express the metric as an INT — `date_diff('day', max(date), today)` — so it renders as a number of days rather than a date. Measured live at 4.61 s over 3,348 SKUs"
-    - key: distinct_orders
-      cause: "`__count` on the live path is LINE count, not ORDER count (12,707 lines vs 12,645 distinct SKU-order pairs); the honest figure needs a 2-level groupby measured at 10.87 s live"
-      fix: "on the STORE path this is `count(DISTINCT l.order_id)` in one pass — add it as a `count_distinct` metric on `sales_lines` with field `order_id`"
-
-# ⭐⭐ W37-T13 — PHYSICAL MOVEMENT. `stock.move` and `stock_location` are mirrored now (the
-# `not_yet` entry that used to sit here said "not mirrored, so there is no store binding to
-# group"; that is what changed). The direction rule is TWO-SIDED and lives in the metrics'
-# `store_filter_sql` — see `model/metrics/stock.yml`, which carries the 58% trap in full.
-- source: stock_moves
-  dim: product_code
-  keys: [stock_in, stock_out, stock_net]
-  not_yet:
-    - key: stock_in_excl_adjustments
-      cause: "adjustments and scrap are ~30% of IN / ~20% of OUT and the two obvious exclusions are NOT equivalent - the 5,320-unit gap between them is entirely `Virtual Locations/Scrap`, so the choice is a business ruling rather than a filter"
-      fix: "ask the owner which exclusion they mean, then add it as a SEPARATE metric with `store_filter_sql` narrowed on `sl.usage`/`sd.usage` - never by changing what `stock_in` means"
-
-# 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: code
-    label: "SKU"
-    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
-    kind: data
-    means: "Product name as it appears in Odoo."
-  - key: category
-    label: "Category"
-    type: select
-    kind: data
-    means: "Product category; '(uncategorized)' when Odoo carries none."
-  - key: supplier
-    label: "Supplier"
-    type: text
-    kind: data
-    means: "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet."
-  - key: origin_country
-    label: "Country"
-    type: text
-    kind: data
-    means: "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet."
-  - key: lead_days
-    label: "Lead time (days)"
-    type: int
-    kind: data
-    means: "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone."
-  - key: first_cost
-    label: "First cost"
-    type: currency
-    kind: data
-    means: "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone."
-  - key: price_fisch
-    label: "Fisch price"
-    type: currency
-    kind: data
-    means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
-  - key: price_royal_1
-    label: "Royal 1 price"
-    type: currency
-    kind: data
-    means: "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
-  - key: price_royal_2
-    label: "Royal 2 price"
-    type: currency
-    kind: data
-    means: "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
-  - key: rev_ytd
-    label: "Revenue YTD"
-    type: currency
-    kind: data
-    means: "Year-to-date revenue for this SKU, BU-scoped when the caller is."
-  - key: rev_ly
-    label: "Revenue LY"
-    type: currency
-    kind: data
-    means: "Same period last year — seasonal wholesale compares like for like."
-  - key: yoy_pct
-    label: "YoY %"
-    type: pct
-    kind: data
-    means: "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
-  - key: qty_ytd
-    label: "Units YTD"
-    type: int
-    kind: data
-    means: "Units sold year to date."
-  - key: orders_ytd
-    label: "Orders YTD"
-    type: int
-    kind: data
-    means: "Distinct orders containing this SKU, year to date."
-  - key: on_hand
-    label: "On hand"
-    type: int
-    kind: data
-    means: "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
-  - key: unit_cost
-    label: "Unit cost"
-    type: currency
-    kind: data
-    means: "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
-  - key: inv_value
-    label: "Stock value"
-    type: currency
-    kind: data
-    means: "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
-  - key: qty_ltm
-    label: "Units LTM"
-    type: int
-    kind: data
-    means: "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
-  - key: dos
-    label: "Days of supply"
-    type: int
-    kind: data
-    means: "Days of supply at the LTM rate; null means it never sells through. Consolidated; absent for a BU-scoped caller."
-  - key: cover_gap_d
-    label: "Cover gap (days)"
-    type: int
-    kind: data
-    means: "Days of supply minus lead time. Negative means it runs out before a reorder lands."
-  - key: stock_bucket
-    label: "Stock status"
-    type: select
-    kind: data
-    means: "Dead / excess / healthy bucket from the inventory module. Consolidated; absent for a BU-scoped caller."
-
-ai_context: >
-  The product CATALOGUE — the database labelled 'Odoo products'.
-  Use it for 'what do we sell', 'what does it cost' (first_cost/unit_cost), 'who supplies it', 'what is on hand' and the stock-coverage columns.
-  ⛔ Revenue and unit columns here are WINDOWED SNAPSHOTS (rev_ytd, qty_ltm); for any other window, or for line grain, go to sales_lines.
+# ⭐⭐ 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_products
+label: "Odoo products"
+entity: product.product
+# The database this topic DESCRIBES — the same store key the nav opens (W33-T46).
+grid: product_data
+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:
+  table: product_product
+  alias: pp
+  # 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:
+    category: {label: "Category"}
+    supplier: {label: "Supplier"}
+
+# ⭐⭐ W37-T10 / owner item 4 (ruling R1) — THE LOOKBACK-MEASURE BINDING. Owner: *"Odoo products
+# should have a lookbsck metrics like sales etc."* This block is what turns `measures: []` on the
+# product workspace into a real catalogue, and it is DECLARED HERE rather than hand-written in a
+# route for the reason `_rollup_source_offer` gives about itself: a second list is a second
+# definition of the same fact, and the two drift the day somebody adds a metric.
+#
+# ⛔ THE JOIN KEY IS THE TRAP CONTRACT C1 NAMES, and this is where it is answered. `source` is a
+# FACT topic; `dim` is the dim of THAT topic which carries THIS entity's identity. `sales_lines`
+# has two candidates and only one is right: `product` groups by Odoo's `product_id`, while this
+# database's identity (see `scope.identity` above) is `default_code`. Binding to `product` would
+# key every cell on a number no grid row carries — a column of nulls that reads as "never sold".
+#
+# ⚠ A SINGLE-TOPIC GROUPED QUERY, which is why `semantic.store_query`'s cross-topic refusal does
+# not bite: `revenue` lives ON `sales_lines` and we group `sales_lines` by its OWN dim. The same
+# refusal is real and DOES bite `aov`/`orders` (denominator `orders` lives on `sales_orders`), so
+# those two are absent from `keys` below and `entity_measures()` re-proves that rather than
+# trusting this list.
+# ⭐ A LIST SINCE W37-T13: an entity's columns legitimately come from more than ONE fact topic.
+# Sales movement is `sales_lines`; physical movement is `stock_moves`. Same grid, same join key
+# (`product_code`), different tables — forcing stock into the sales topic would have defined a
+# metric against rows it does not have.
+measures:
+- source: sales_lines
+  dim: product_code
+  # ⭐ The SHIP-FIRST six of `proto/P3-metric-catalog.md`, and they cost ONE grouped query
+  # together (measured 0.22 s over 1,670 groups against the mirror; 2.55 s live).
+  keys: [units, revenue, margin, cogs, margin_pct, asp]
+  # ⛔ REPORTED, NOT SILENTLY DROPPED (standing rule 1's second sentence, applied to a catalogue).
+  # Each of these is a real metric `proto/P3-metric-catalog.md` measured and this wave does not
+  # ship, with the CAUSE and the fix — so the next session extends the list instead of
+  # re-measuring, and nobody reads the six as "all Odoo can answer".
+  not_yet:
+    - key: days_since_last_sale
+      cause: "needs `agg: max` over a DATE, which `semantic._measure_sql` does not implement (sum | count | count_distinct only), and a date-typed measure could not render anyway: `aios_grid.MEASURE_FIELD_TYPES` is {currency, int, pct}"
+      fix: "add `agg: max` to `_measure_sql` and express the metric as an INT — `date_diff('day', max(date), today)` — so it renders as a number of days rather than a date. Measured live at 4.61 s over 3,348 SKUs"
+    - key: distinct_orders
+      cause: "`__count` on the live path is LINE count, not ORDER count (12,707 lines vs 12,645 distinct SKU-order pairs); the honest figure needs a 2-level groupby measured at 10.87 s live"
+      fix: "on the STORE path this is `count(DISTINCT l.order_id)` in one pass — add it as a `count_distinct` metric on `sales_lines` with field `order_id`"
+
+# ⭐⭐ W37-T13 — PHYSICAL MOVEMENT. `stock.move` and `stock_location` are mirrored now (the
+# `not_yet` entry that used to sit here said "not mirrored, so there is no store binding to
+# group"; that is what changed). The direction rule is TWO-SIDED and lives in the metrics'
+# `store_filter_sql` — see `model/metrics/stock.yml`, which carries the 58% trap in full.
+- source: stock_moves
+  dim: product_code
+  keys: [stock_in, stock_out, stock_net]
+  not_yet:
+    - key: stock_in_excl_adjustments
+      cause: "adjustments and scrap are ~30% of IN / ~20% of OUT and the two obvious exclusions are NOT equivalent - the 5,320-unit gap between them is entirely `Virtual Locations/Scrap`, so the choice is a business ruling rather than a filter"
+      fix: "ask the owner which exclusion they mean, then add it as a SEPARATE metric with `store_filter_sql` narrowed on `sl.usage`/`sd.usage` - never by changing what `stock_in` means"
+
+# 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: code
+    label: "SKU"
+    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
+    kind: data
+    means: "Product name as it appears in Odoo."
+  - key: category
+    label: "Category"
+    type: select
+    kind: data
+    means: "Product category; '(uncategorized)' when Odoo carries none."
+  - key: supplier
+    label: "Supplier"
+    type: text
+    kind: data
+    means: "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet."
+  - key: origin_country
+    label: "Country"
+    type: text
+    kind: data
+    means: "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet."
+  - key: lead_days
+    label: "Lead time (days)"
+    type: int
+    kind: data
+    means: "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone."
+  - key: first_cost
+    label: "First cost"
+    type: currency
+    kind: data
+    means: "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone."
+  - key: price_fisch
+    label: "Fisch price"
+    type: currency
+    kind: data
+    means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
+  - key: price_royal_1
+    label: "Royal 1 price"
+    type: currency
+    kind: data
+    means: "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
+  - key: price_royal_2
+    label: "Royal 2 price"
+    type: currency
+    kind: data
+    means: "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
+  - key: rev_ytd
+    label: "Revenue YTD"
+    type: currency
+    kind: data
+    means: "Year-to-date revenue for this SKU, BU-scoped when the caller is."
+  - key: rev_ly
+    label: "Revenue LY"
+    type: currency
+    kind: data
+    means: "Same period last year — seasonal wholesale compares like for like."
+  - key: yoy_pct
+    label: "YoY %"
+    type: pct
+    kind: data
+    means: "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
+  - key: qty_ytd
+    label: "Units YTD"
+    type: int
+    kind: data
+    means: "Units sold year to date."
+  - key: orders_ytd
+    label: "Orders YTD"
+    type: int
+    kind: data
+    means: "Distinct orders containing this SKU, year to date."
+  - key: on_hand
+    label: "On hand"
+    type: int
+    kind: data
+    means: "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
+  - key: unit_cost
+    label: "Unit cost"
+    type: currency
+    kind: data
+    means: "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
+  - key: inv_value
+    label: "Stock value"
+    type: currency
+    kind: data
+    means: "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
+  - key: qty_ltm
+    label: "Units LTM"
+    type: int
+    kind: data
+    means: "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
+  - key: dos
+    label: "Days of supply"
+    type: int
+    kind: data
+    means: "Days of supply at the LTM rate; null means it never sells through. Consolidated; absent for a BU-scoped caller."
+  - key: cover_gap_d
+    label: "Cover gap (days)"
+    type: int
+    kind: data
+    means: "Days of supply minus lead time. Negative means it runs out before a reorder lands."
+  - key: stock_bucket
+    label: "Stock status"
+    type: select
+    kind: data
+    means: "Dead / excess / healthy bucket from the inventory module. Consolidated; absent for a BU-scoped caller."
+
+ai_context: >
+  The product CATALOGUE — the database labelled 'Odoo products'.
+  Use it for 'what do we sell', 'what does it cost' (first_cost/unit_cost), 'who supplies it', 'what is on hand' and the stock-coverage columns.
+  ⛔ Revenue and unit columns here are WINDOWED SNAPSHOTS (rev_ytd, qty_ltm); for any other window, or for line grain, go to sales_lines.

platform/model/topics/odoo_vendors.yml

@@ -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

@@ -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

@@ -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)