fsanyoto commited on
Commit
b58ff54
Β·
verified Β·
1 Parent(s): 309fe95

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
This view is limited to 50 files because it contains too many changes. Β  See raw diff
Files changed (50) hide show
  1. RELEASES.json +1 -1
  2. VERSION +1 -1
  3. api/ai_review.py +591 -591
  4. api/connectors_tt.py +568 -568
  5. api/providers.py +0 -0
  6. api/routes_agent_harness.py +455 -455
  7. api/routes_geo.py +8 -5
  8. api/routes_keychain.py +0 -0
  9. api/routes_oauth.py +114 -114
  10. api/routes_records.py +211 -211
  11. api/routes_script_views.py +439 -439
  12. api/routes_slack.py +789 -789
  13. api/routes_statements.py +298 -298
  14. api/routes_tables.py +10 -13
  15. api/routes_web_agent.py +84 -84
  16. platform/core/grid_events.py +23 -5
  17. platform/core/route_system.py +56 -9
  18. platform/core/script_sandbox.py +519 -519
  19. platform/core/store.py +0 -0
  20. platform/core/user_tables.py +32 -47
  21. platform/core/view_templates.py +16 -17
  22. platform/harness/meta_store.py +521 -521
  23. platform/model/metrics/sales.yml +149 -149
  24. platform/model/topics/odoo_accounts.yml +60 -60
  25. platform/model/topics/odoo_agents.yml +91 -91
  26. platform/model/topics/odoo_bills.yml +86 -86
  27. platform/model/topics/odoo_invoices.yml +98 -98
  28. platform/model/topics/odoo_orders.yml +87 -87
  29. platform/model/topics/odoo_vendors.yml +103 -103
  30. platform/modules/agent.py +385 -385
  31. platform/modules/collections_send.py +267 -267
  32. requirements.txt +55 -55
  33. web/index.html +46 -46
  34. web/src/App.tsx +41 -41
  35. web/src/account/SubscriptionPage.tsx +49 -49
  36. web/src/account/UsagePage.tsx +297 -297
  37. web/src/account/account.css +372 -372
  38. web/src/account/accountApi.ts +188 -188
  39. web/src/alerts/alertsModel.ts +418 -418
  40. web/src/automation/AutomationFind.tsx +893 -893
  41. web/src/automation/HarnessPanel.tsx +413 -413
  42. web/src/automation/PresetPlan.tsx +122 -122
  43. web/src/automation/automation.css +556 -556
  44. web/src/connectors/brandMarks.tsx +413 -413
  45. web/src/customer-grid/CustomerGrid.tsx +143 -58
  46. web/src/customer-grid/GridChat.tsx +512 -512
  47. web/src/customer-grid/ImportDialog.css +154 -154
  48. web/src/customer-grid/ImportDialog.tsx +299 -299
  49. web/src/customer-grid/SwipeView.tsx +586 -586
  50. web/src/customer-grid/chatDock.css +48 -48
RELEASES.json CHANGED
@@ -1,5 +1,5 @@
1
  {
2
- "current": "fbb56dd",
3
  "releases": [
4
  {
5
  "version": "v56",
 
1
  {
2
+ "current": "4859c03",
3
  "releases": [
4
  {
5
  "version": "v56",
VERSION CHANGED
@@ -1 +1 @@
1
- fbb56dd
 
1
+ 4859c03
api/ai_review.py CHANGED
@@ -1,591 +1,591 @@
1
- """AI REVIEW β€” let a model decide which stage a card moves to (wave 23, owner ruling R4/R14).
2
-
3
- ⭐ WHAT THIS IS. A review stage holds a record until somebody decides where it goes next. R4 made
4
- that somebody optionally a MODEL: the engine hands over the record's own values, the review's
5
- prompt, and the list of stages the review is allowed to send a card to, and gets back ONE of
6
- those stage labels plus a one-line reason. Every decision is written to the same `reviews` audit
7
- log a human click writes to, tagged `by: "ai"` with the provider and model that made it.
8
-
9
- β›” FAIL-CLOSED IN EVERY DIRECTION, and this is the whole safety story. No key configured, a
10
- network failure, a slow answer, a malformed answer, or an answer naming a stage the review does
11
- not offer β€” all return `("", {...})`, and the caller leaves the card exactly where a human would
12
- have found it. The feature can be absent, broken or wrong and the worst outcome is a person doing
13
- the work. Nothing here can move a card somewhere the review does not already permit.
14
-
15
- ⭐ CHEAP FIRST (owner R14, verbatim: *"Claude is a bit too expensive"*). The ladder is
16
- `groq β†’ cerebras β†’ openrouter β†’ anthropic`; the first CONFIGURED provider wins, and Anthropic is
17
- last rather than absent β€” it is the quality backstop, not the default. `AIOS_AI_REVIEW_PROVIDER`
18
- pins one; `AIOS_AI_MODEL` overrides the model.
19
-
20
- ⭐⭐ THE ANTHROPIC LEG IS ON THE OFFICIAL SDK NOW (D-346, W37-T39, 2026-08-19). β›” THIS PARAGRAPH
21
- USED TO ARGUE THE OPPOSITE and is rewritten rather than deleted, because a comment left asserting
22
- the reverse of its own code is [[two-gates-can-assert-opposite-things]] with no gate to catch it.
23
- The retired text said raw HTTP was *"a deliberate deviation … booked as a DEBT line so the
24
- integrator can overturn it deliberately rather than by drift"*. This is that overturn.
25
-
26
- Its two reasons were real and are both answered rather than waved away:
27
- 1. *"one SDK leg beside three hand-rolled ones is two implementations of the same call."* It is
28
- not, because the leg does not live here: `providers.anthropic_send` owns the wire, prefers
29
- the SDK, and normalises BOTH transports to one `(status, body)` pair. This file gained no
30
- Anthropic knowledge β€” it lost some.
31
- 2. *"adding a pinned dependency rebuilds the container, a real deploy risk."* Still true, so the
32
- import is LAZY and its absence is a FALLBACK, not a crash: with no `anthropic` package the
33
- same raw POST runs and `LAST_ANTHROPIC_TRANSPORT` reports `'http'`. The pin is owed in BOTH
34
- manifests ([[pin-deps-space-rebuilds]]) and is outside every worker fence this wave.
35
- ⚠ The other three legs stay OpenAI-chat-shaped over `requests` β€” they have no shared SDK, and that
36
- half of the original reasoning never expired.
37
-
38
- The Messages shape below is the current one: `x-api-key` + `anthropic-version: 2023-06-01`, and
39
- `stop_reason: "refusal"` is checked BEFORE reading `content` β€” a refusal answers HTTP 200 with an
40
- empty content list, so code that indexes `content[0]` unconditionally breaks on it.
41
- """
42
- from __future__ import annotations
43
-
44
- import json
45
- import os
46
- import re
47
-
48
- import requests
49
-
50
- #: The ladder. Order IS the policy (R14) β€” cheapest capable first, Anthropic last.
51
- PROVIDERS = [
52
- # β›”β›” D-345, FIXED W37-T39 (2026-08-19). This read `llama-3.3-70b-versatile` and Groq RETIRED
53
- # it: a real POST with the live key answers HTTP 404 `model_not_found`, and the id is absent
54
- # from `GET /openai/v1/models`. ⚠ THE `openai/` PREFIX IS PART OF GROQ'S ID and is NOT a typo
55
- # for the cerebras rung below, which serves the same family bare as `gpt-oss-120b`.
56
- {"name": "groq", "env": "GROQ_API_KEY", "shape": "openai",
57
- "url": "https://api.groq.com/openai/v1/chat/completions",
58
- "model": "openai/gpt-oss-120b"},
59
- {"name": "cerebras", "env": "CEREBRAS_API_KEY", "shape": "openai",
60
- "url": "https://api.cerebras.ai/v1/chat/completions",
61
- "model": "gpt-oss-120b"},
62
- {"name": "openrouter", "env": "OPENROUTER_API_KEY", "shape": "openai",
63
- "url": "https://openrouter.ai/api/v1/chat/completions",
64
- "model": "openai/gpt-4o-mini"},
65
- # ⚠ haiku-class DELIBERATELY, not the default Opus tier: R14 put Anthropic on this ladder as
66
- # the backstop for a one-line classification, and this is the cheapest current Claude that
67
- # does it well. A bigger model here would be spending the owner's money to pick between two
68
- # labels it already has in front of it.
69
- {"name": "anthropic", "env": "ANTHROPIC_API_KEY", "shape": "anthropic",
70
- "url": "https://api.anthropic.com/v1/messages",
71
- # ⚠ AN ENV LEVER, NOT A NEW DEFAULT (W36-T35): haiku stays the choice for the reasons above,
72
- # and a deployment whose side rungs are out of credit can raise the tier without a release.
73
- "model": os.environ.get("AIOS_AI_REVIEW_ANTHROPIC_MODEL") or "claude-haiku-4-5"},
74
- ]
75
- ANTHROPIC_VERSION = "2023-06-01"
76
- TIMEOUT_SECONDS = float(os.environ.get("AIOS_AI_REVIEW_TIMEOUT") or 20)
77
- MAX_FIELD_CHARS = 200 # per value handed to the model
78
- MAX_FIELDS = 30 # columns handed to the model
79
- MAX_REASON = 200
80
-
81
-
82
- def ladder():
83
- """The providers that are actually usable here, in order. Empty = the feature is off."""
84
- pin = (os.environ.get("AIOS_AI_REVIEW_PROVIDER") or "").strip().lower()
85
- live = [p for p in PROVIDERS if (os.environ.get(p["env"]) or "").strip()]
86
- if pin:
87
- live = [p for p in live if p["name"] == pin]
88
- return live
89
-
90
-
91
- def configured():
92
- return bool(ladder())
93
-
94
-
95
- def _record_text(row, fields):
96
- """The record, as the model sees it. Values are truncated and the column set is bounded β€”
97
- an automation table can carry a 32 KB JSON blob per row (C7) and a review decision does not
98
- need it. Machine bookkeeping columns are dropped: a stage cell naming the stage the card is
99
- sitting at would be the model reading its own question back."""
100
- keys = [k for k in (fields or list((row or {}).keys()))
101
- if not str(k).startswith("stage_")][:MAX_FIELDS]
102
- lines = []
103
- for k in keys:
104
- v = (row or {}).get(k)
105
- if v is None or str(v).strip() == "":
106
- continue
107
- lines.append(f"{k}: {str(v)[:MAX_FIELD_CHARS]}")
108
- return "\n".join(lines) or "(this record has no filled-in values)"
109
-
110
-
111
- def _instruction(prompt, options, label):
112
- return (
113
- f"You are deciding what happens to one record waiting at a review step called "
114
- f"{label!r} in a workflow.\n\n"
115
- f"The person who built this workflow told you: {prompt}\n\n"
116
- f"Choose EXACTLY ONE of these next steps, by its exact name:\n"
117
- + "\n".join(f"- {o}" for o in options)
118
- + "\n\nAnswer with one line of JSON and nothing else:\n"
119
- '{"choice": "<one name from the list above>", "reason": "<one short sentence>"}\n'
120
- "If the record does not give you enough to decide, answer "
121
- '{"choice": "", "reason": "why not"} and a person will decide instead.'
122
- )
123
-
124
-
125
- def _parse(text, options):
126
- """The model's line β†’ `(choice, reason)`. A choice that is not one of the offered stages is
127
- DISCARDED, not fuzzy-matched: the offered list is a permission boundary, and a near-miss
128
- resolved by string distance is how a card ends up somewhere nobody authorised."""
129
- raw = str(text or "").strip()
130
- obj = None
131
- m = re.search(r"\{.*\}", raw, re.S)
132
- if m:
133
- try:
134
- obj = json.loads(m.group(0))
135
- except (ValueError, TypeError):
136
- obj = None
137
- if not isinstance(obj, dict):
138
- return "", ""
139
- choice = str(obj.get("choice") or "").strip()
140
- reason = str(obj.get("reason") or "").strip()[:MAX_REASON]
141
- for opt in options:
142
- if choice.lower() == str(opt).lower():
143
- return str(opt), reason # the OFFERED spelling wins, never the model's
144
- return "", reason
145
-
146
-
147
- # ⭐⭐ WAVE 35 Β· W35-T41 / C7 β€” THE TWO TRANSPORTS RETURN THE RESPONSE BODY'S `usage`.
148
- #
149
- # β›” THIS FILE'S OWN HEADER USED TO BE THE PRODUCT'S CONFESSION THAT NOTHING COUNTED: `ai_enrich`'s
150
- # docstring says *"`ai_review.decide` -- the product's only other LLM entry -- has no token
151
- # accounting of ANY kind"*. R9 asks for ONE meter for every AI surface, so the counting has to reach
152
- # this transport rather than be bolted onto its caller β€” the caller never sees the body.
153
- #
154
- # ⚠ A THIRD RETURN VALUE, NOT A MUTATED ARGUMENT, and both call sites are in `decide` below. The
155
- # tuple grew from `(text, err)` to `(text, err, usage)`; `usage` is the raw `usage` OBJECT (or None),
156
- # because reading it is `usage_ledger`'s job and a second reader here would be the two-normalizers
157
- # shape this repo keeps paying for.
158
- def _call_openai(p, model, system, user, timeout):
159
- r = requests.post(p["url"], timeout=timeout,
160
- headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
161
- "Content-Type": "application/json"},
162
- json={"model": model, "max_tokens": 300, "temperature": 0,
163
- "messages": [{"role": "system", "content": system},
164
- {"role": "user", "content": user}]})
165
- if r.status_code >= 400:
166
- # ⚠ NO BODY ON A 4xx/5xx: an error envelope carries no usage, and a provider that refused
167
- # before running the model has nothing to bill. The call is still COUNTED by `decide`.
168
- return "", f"{p['name']} answered {r.status_code}", None
169
- body = r.json()
170
- choices = body.get("choices") or []
171
- if not choices:
172
- return "", f"{p['name']} returned no choices", body
173
- return str(((choices[0] or {}).get("message") or {}).get("content") or ""), "", body
174
-
175
-
176
- #: What transport the last Anthropic call actually used: `'sdk'`, `'http'`, or `''` before any.
177
- #: ⚠ PROCESS-LOCAL AND FOR REPORTING ONLY. It exists so `GET /meta` and `verify_web_agent` can say
178
- #: WHICH path ran rather than inferring it from a requirements file nobody in this lane can edit.
179
- LAST_ANTHROPIC_TRANSPORT = ""
180
-
181
-
182
- def _call_anthropic(p, model, system, user, timeout):
183
- """One classification turn on the Messages API, through `providers.anthropic_send`.
184
-
185
- ⭐ D-346 (W37-T39): this used to hand-roll the POST. It now goes through the shared wire, which
186
- prefers the OFFICIAL `anthropic` SDK and falls back to the same raw POST when the package is
187
- absent. The shape of what comes back is unchanged, deliberately: `anthropic_send` normalises
188
- both transports to `(status, body)`, so every line below this call is untouched.
189
- """
190
- global LAST_ANTHROPIC_TRANSPORT
191
- import providers as _prov # noqa: PLC0415
192
- # ⚠ NO TOOLS ON THIS PATH. The builder omits `tool_choice` for exactly that case, so there is
193
- # nothing to strip here β€” the rule lives in `anthropic_request`, beside the thing it constrains.
194
- req = _prov.anthropic_request(
195
- model=model, key=os.environ[p["env"]].strip(), system=system,
196
- messages=[{"role": "user", "content": user}], tools=[], max_tokens=300)
197
- status, body, transport = _prov.anthropic_send(req, timeout=timeout)
198
- LAST_ANTHROPIC_TRANSPORT = transport
199
- if status >= 400 or status == 0:
200
- # ⭐ THE SENTENCE COMES FROM THE LADDER, NOT FROM HERE. `refusal_sentence` already names the
201
- # vendor and the action for every status R4 enumerated, so a bare "anthropic answered 402"
202
- # (which is what this line used to say, and what the owner quoted back at us) cannot recur.
203
- return "", _prov.refusal_sentence("anthropic", status, json.dumps(body)[:400]), None
204
- body = body or {}
205
- # β›” stop_reason FIRST. A safety refusal is a successful 200 with an EMPTY content list, so
206
- # reading content[0] before this check turns a refusal into an IndexError inside a run.
207
- # ⚠ A refusal IS billed and its body carries `usage`, so the body rides back on this branch too.
208
- if body.get("stop_reason") == "refusal":
209
- return "", "anthropic declined to answer this record", body
210
- parts = [b.get("text") or "" for b in (body.get("content") or [])
211
- if isinstance(b, dict) and b.get("type") == "text"]
212
- if not parts:
213
- return "", "anthropic returned no text", body
214
- return "".join(parts), "", body
215
-
216
-
217
- def decide(*, prompt, options, row, fields=(), label="Review", timeout=None, st=None, user=""):
218
- """Pick this record's next stage. Returns `(choice, meta)`.
219
-
220
- `choice` is "" whenever a person should decide β€” which is every failure mode there is.
221
- `meta` carries `provider`, `model`, `reason` on success, and `problem` on refusal to answer.
222
-
223
- ⭐ W35-T41 / C7 β€” `st` and `user` are the USAGE LEDGER's target. Both default to absent because
224
- this function's caller is `automation_engine.ai_decide(rt, ...)`, in another lane's fence: it
225
- HAS the runtime and does not pass it yet, so until it does, a review's tokens are counted as
226
- unattributed and REPORTED by `GET /usage` rather than dropped. See `usage_ledger`'s header for
227
- why they cannot be resolved implicitly (measured: a contextvar does not survive a FastAPI
228
- dependency).
229
- """
230
- import usage_ledger # noqa: PLC0415
231
- opts = [str(o) for o in (options or []) if str(o).strip()]
232
- if not opts:
233
- return "", {"problem": "the review offers no next stages"}
234
- if not str(prompt or "").strip():
235
- return "", {"problem": "the review has no prompt for the model to follow"}
236
- live = ladder()
237
- if not live:
238
- return "", {"problem": "no AI provider is configured on this deployment"}
239
- system = _instruction(prompt, opts, label)
240
- user = "Here is the record:\n\n" + _record_text(row, fields)
241
- tmo = float(timeout or TIMEOUT_SECONDS)
242
- override = (os.environ.get("AIOS_AI_MODEL") or "").strip()
243
- problems = []
244
- for p in live:
245
- model = override or p["model"]
246
- body = None
247
- try:
248
- text, err, body = (_call_anthropic if p["shape"] == "anthropic" else _call_openai)(
249
- p, model, system, user, tmo)
250
- except Exception as e: # noqa: BLE001
251
- text, err = "", f"{p['name']} failed: {type(e).__name__}"
252
- # ⭐⭐ C7 β€” THE LEDGER LINE, BEFORE ANY BRANCH BELOW READS THE ANSWER.
253
- # β›” IT IS WRITTEN ON EVERY OUTCOME THAT REACHED A PROVIDER, including a refusal and an
254
- # unusable answer. A meter that books only successes reports a cheap week for a run that
255
- # spent its budget being declined β€” and a declined call is billed. The only path that does
256
- # NOT record is a transport that never reached the vendor (`body is None`), which spent
257
- # nothing.
258
- if body is not None:
259
- ins, outs = usage_ledger.tokens_from(body)
260
- usage_ledger.record("ai_review", p["name"], model, ins, outs,
261
- total=usage_ledger.total_from(body), st=st, user=user)
262
- if err:
263
- problems.append(err)
264
- continue # ladder: a dead provider degrades to the next one
265
- choice, reason = _parse(text, opts)
266
- if not choice:
267
- # The provider ANSWERED and declined (or answered unusably). That is a decision about
268
- # this record, not a fault in the provider, so it does NOT fall through to a more
269
- # expensive one β€” the card goes to a human, which is what the model just asked for.
270
- return "", {"provider": p["name"], "model": model,
271
- "problem": reason or "the model did not choose one of the stages"}
272
- return choice, {"provider": p["name"], "model": model, "reason": reason}
273
- return "", {"problem": "; ".join(problems)[:300] or "no provider answered"}
274
-
275
-
276
- # ══════════════════════════════════════════════════════════════════ the FLOW WRITER
277
- # ⭐⭐ WAVE 33 Β· W33-T54/T55 (owner item 7, ruling R3) β€” A PROMPT BECOMES A DRAFT AUTOMATION.
278
- #
279
- # Owner, verbatim: *"lay out the foundation with custom tools we provide"* β€” and the tools are the
280
- # action catalog, which has been machine-readable since wave 23. So this writes no new vocabulary:
281
- # it hands the model the SAME `ACTION_CATALOG` the menu paints, the SAME `ACTION_REQUIRED` the
282
- # runner blocks on, and the SAME trigger keys `clean_trigger` accepts, and asks for one JSON object
283
- # in that vocabulary.
284
- #
285
- # β›” WHY IT LIVES IN `ai_review.py` RATHER THAN A NEW FILE. Two reasons, both about ownership. This
286
- # is the one module in the API package that already holds an LLM ladder and its credentials, so a
287
- # second one would be a second place a rotated key has to be noticed; and a new `routes_*.py` needs
288
- # a `main.py` line from another lane (contract C2) to be reachable at all, which is how wave 23
289
- # shipped three finished routers 404-dead behind green gates. The DOOR is a route on
290
- # `routes_automation.py`, which is already mounted.
291
- #
292
- # β›”β›” CONTRACT C7 IS THE DESIGN, NOT A CHECK AT THE END: *"the flow writer may emit only kinds
293
- # present in `ACTION_CATALOG`, and its output must pass `clean_actions` unchanged."* Both halves are
294
- # enforced mechanically rather than asked for politely β€” the kind list is an `enum` in the schema
295
- # the model fills, and the caller runs `clean_actions` and DIFFS the result. That diff matters
296
- # because `clean_actions` has no disclosure channel (D-75): it drops a key it does not recognise
297
- # and answers 200, so a draft accepted without the diff would show a person a flow that is not the
298
- # flow the model described, with nothing anywhere saying so.
299
- #
300
- # ⚠ `chat` IS INJECTABLE, exactly as `routes_query._call_model`'s is, and it is the reason this door
301
- # can be proven end to end with no API key and no spend. A gate that can only run where a
302
- # credential exists is a gate that never runs.
303
-
304
- #: Cerebras first, NOT the cheap-first order `ladder()` uses. Same reason `routes_query` inverts it:
305
- #: this contract includes a REFUSAL, and refusing honestly ("I cannot build that from the steps you
306
- #: have") is a model property. A cheaper rung answers an impossible request with a plausible flow,
307
- #: which is worse than no flow. Override with `AIOS_FLOW_PROVIDER`.
308
- FLOW_PROVIDER_ORDER = ("cerebras", "groq", "openrouter", "anthropic")
309
- MAX_DRAFT_ACTIONS = 12 # a draft a person reads in one screen; the engine's own cap is 25
310
- MAX_PROMPT_CHARS = 2000
311
-
312
-
313
- def flow_providers(pin=None):
314
- """The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off.
315
-
316
- ⭐ `pin` IS ASK D-18 (2026-08-18): the Agent chat's model toggle must configure something, and
317
- the draft door used to read `prompt` off the body and nothing else β€” so the key the client sent
318
- was accepted and dropped, and the picker was a control over nothing.
319
- ⚠ AN UNKNOWN OR UNCONFIGURED PIN FALLS BACK TO THE LADDER rather than refusing. A model the
320
- ladder stopped offering must not turn every later draft into an error; the caller is told which
321
- rung actually answered, which is the honest half.
322
- """
323
- by_name = {p["name"]: p for p in PROVIDERS}
324
- live = [n for n in FLOW_PROVIDER_ORDER
325
- if n in by_name and (os.environ.get(by_name[n]["env"]) or "").strip()]
326
- wanted = str(pin or os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
327
- if wanted and wanted in live:
328
- return [by_name[wanted]]
329
- return [by_name[n] for n in live]
330
-
331
-
332
- def flow_schema(kinds, trigger_keys, table_keys):
333
- """The tool schema the model fills β€” the catalog's OWN key lists as enums.
334
-
335
- β›” `kind` AND `trigger` ARE ENUMS, not free strings, and that is C7's first half enforced by the
336
- transport rather than by a check afterwards. A model asked for "any action name" invents
337
- `send_slack_message` on a deployment that has no such kind, and the failure then surfaces as a
338
- 400 from `clean_actions` carrying a sentence about a word the person never typed.
339
- ⚠ `required` IS `["kind"]` ALONE, deliberately: a REFUSAL carries no name and no actions, and a
340
- schema demanding them turns an honest refusal into a provider-side 400 that reads exactly like a
341
- transport failure (`routes_query._spec_schema` carries the same note, for the same measured
342
- reason).
343
- """
344
- return {
345
- "type": "object",
346
- "properties": {
347
- "kind": {"type": "string", "enum": ["flow", "refused"],
348
- "description": "refused = this cannot be built from the steps available"},
349
- "refusal": {"type": "string",
350
- "description": "when kind=refused: ONE plain sentence naming what is "
351
- "missing, in the words a non-technical person would use"},
352
- "name": {"type": "string", "description": "a short title for the automation"},
353
- "trigger": {"type": "string", "enum": sorted(trigger_keys),
354
- "description": "what starts this automation"},
355
- "table": {"type": "string", "enum": sorted(table_keys),
356
- "description": "the database whose records this flow walks, if any"},
357
- "actions": {
358
- "type": "array",
359
- "maxItems": MAX_DRAFT_ACTIONS,
360
- "items": {
361
- "type": "object",
362
- "properties": {
363
- "kind": {"type": "string", "enum": sorted(kinds)},
364
- "why": {"type": "string",
365
- "description": "one short sentence: why this step is here"},
366
- "config": {"type": "object", "additionalProperties": True,
367
- "description": "the step's settings, using ONLY the keys named "
368
- "for that kind in the system message"},
369
- },
370
- "required": ["kind"],
371
- },
372
- },
373
- },
374
- "required": ["kind"],
375
- }
376
-
377
-
378
- def flow_system_prompt(catalog, required, triggers, tables):
379
- """What the model is told it may build with β€” DERIVED, never written down twice.
380
-
381
- Every list here is the server's own: the catalog rows the menu paints, the required-key table
382
- the runner blocks on, the trigger keys `clean_trigger` accepts, and this tenant's real databases
383
- with their real columns. Nothing about the vocabulary is restated by hand, so a kind added to
384
- the catalog is offered here on the same deploy and a kind removed stops being offered.
385
- """
386
- lines = ["You build small automations for a business tool. You are given the EXACT set of "
387
- "steps this tool can perform. You may use nothing else.",
388
- "", "THE STEPS YOU MAY USE:"]
389
- # ⚠ BOTH HALVES, `key (phrase)`. The KEY is what the model must write into `config` and the
390
- # PHRASE is the only human wording of that requirement anywhere β€” the one the runner's own
391
- # refusal sentence is built from. Keys alone leave the model guessing what `field` means on a
392
- # `web_read` (it is a column to write into, not a form field); phrases alone leave it guessing
393
- # what to call the setting. Handing it one and hoping is how a draft comes back configured
394
- # against a key the validator drops.
395
- req = {str(k): [f"{key} ({phrase})" for phrase, key in v] for k, v in (required or {}).items()}
396
- for row in catalog or []:
397
- if not row.get("ready"):
398
- continue
399
- kind = str(row.get("kind") or "")
400
- need = req.get(kind) or []
401
- lines.append(f"- {kind}: {row.get('label')} - {row.get('detail') or ''}"
402
- + (f" REQUIRED settings: {', '.join(need)}" if need else ""))
403
- lines += ["", "WHAT CAN START AN AUTOMATION:"]
404
- for t in triggers or []:
405
- if t.get("planned") or not t.get("ready", True):
406
- continue
407
- lines.append(f"- {t.get('key')}: {t.get('label')}")
408
- lines += ["", "THE DATABASES THIS PERSON HAS:"]
409
- for t in (tables or [])[:40]:
410
- cols = ", ".join(str(f.get("key")) for f in (t.get("fields") or [])[:25])
411
- lines.append(f"- {t.get('key')} ({t.get('label')}): {cols or 'no columns yet'}")
412
- if not tables:
413
- lines.append("- (none - do not name a database)")
414
- lines += [
415
- "",
416
- "RULES:",
417
- "1. Use ONLY the step kinds listed above. If what is asked needs a step that is not there, "
418
- "answer kind=refused and say plainly which capability is missing.",
419
- "2. Fill in every REQUIRED setting you can from what the person told you. Leave one blank "
420
- "rather than inventing a web address, a CSS selector or a column name.",
421
- "3. A web address must start with http:// or https://.",
422
- "4. To use a value from the record the flow is walking, write it as {{Column name}}.",
423
- "5. Name a database only from the list above, by its key.",
424
- "6. Keep it short. Fewer steps that work beat more steps that guess.",
425
- ]
426
- return "\n".join(lines)
427
-
428
-
429
- def _flow_from_tool_call(obj):
430
- """The model's tool arguments -> `(draft, refusal)`. A shape error is a refusal, never a crash."""
431
- if not isinstance(obj, dict):
432
- return None, "the assistant's answer could not be read"
433
- if str(obj.get("kind") or "") == "refused":
434
- return None, (str(obj.get("refusal") or "").strip()
435
- or "the assistant could not build this from the steps available")
436
- acts = obj.get("actions")
437
- if not isinstance(acts, list) or not acts:
438
- return None, ("the assistant did not produce any steps - try describing what should "
439
- "happen, one action at a time")
440
- out = []
441
- for a in acts[:MAX_DRAFT_ACTIONS]:
442
- if not isinstance(a, dict) or not str(a.get("kind") or "").strip():
443
- continue
444
- cfg = a.get("config")
445
- out.append({"kind": str(a["kind"]).strip(),
446
- "config": cfg if isinstance(cfg, dict) else {},
447
- "why": str(a.get("why") or "").strip()[:200]})
448
- if not out:
449
- return None, "the assistant's steps could not be read"
450
- return {"name": str(obj.get("name") or "").strip()[:80] or "New automation",
451
- "trigger": str(obj.get("trigger") or "").strip(),
452
- "table": str(obj.get("table") or "").strip(),
453
- # β›”β›” THE TRUNCATION IS REPORTED, and it is a STANDING RULE that it must be (owner,
454
- # 2026-08-12, W30/R6 second sentence): *"if there is lag or it can't be done, you need
455
- # to explicitly tell me why and recommend a fix"* β€” **a silent truncation IS the
456
- # violation, not the limit.** `acts[:MAX_DRAFT_ACTIONS]` above dropped everything past
457
- # the twelfth and said nothing, so a model that answered with a twenty-step journey had
458
- # eight steps deleted between the answer and the screen, with no key anywhere in the
459
- # response naming them. `MAX_ACTIONS` is 20, so those steps were STORABLE β€” this
460
- # ceiling is the draft door's own, which makes reporting it the whole obligation.
461
- # ⚠ Found by the verifier that checked this ticket, not by a gate.
462
- "asked": len([a for a in acts if isinstance(a, dict)]),
463
- "actions": out}, ""
464
-
465
-
466
- def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeout=None,
467
- st=None, user="", model=None):
468
- """A sentence -> `(draft, refusal_sentence, provider)`. β›” NOTHING IS SAVED HERE.
469
-
470
- Exactly one of `draft` and `refusal_sentence` is truthy β€” the same contract
471
- `web_agent.run_step` keeps, so a caller has no third case to get wrong.
472
-
473
- ⭐ W35-T41 / C7 β€” `st`/`user` are the usage ledger's target, exactly as on `decide` above and for
474
- the same reason: both of this function's callers (`automation_engine._ai_agent_plan` and
475
- `routes_automation`'s draft door) are in lane D's fence. C7 says E adds the ledger line here and
476
- D asserts it; the two keywords are what D has to pass for the line to be attributable.
477
- """
478
- # ⚠ DECLARED AT THE TOP OF THE FUNCTION, not beside the assignment inside the provider loop.
479
- # It parses either way; a reader scanning for the declaration does not look inside a `for`.
480
- global LAST_ANTHROPIC_TRANSPORT
481
- import usage_ledger # noqa: PLC0415
482
- text = str(prompt or "").strip()[:MAX_PROMPT_CHARS]
483
- if not text:
484
- return None, "type what you want the automation to do", None
485
- kinds = sorted({str(r.get("kind")) for r in (catalog or []) if r.get("ready")})
486
- if not kinds:
487
- return None, "this deployment offers no automation steps to build with", None
488
- trigger_keys = sorted({str(t.get("key")) for t in (triggers or [])
489
- if t.get("key") and not t.get("planned")}) or ["manual"]
490
- table_keys = sorted({str(t.get("key")) for t in (tables or []) if t.get("key")}) or [""]
491
- tools = [{"type": "function", "function": {
492
- "name": "build_automation",
493
- "description": "Emit the automation, or refuse.",
494
- "parameters": flow_schema(kinds, trigger_keys, table_keys)}}]
495
- messages = [{"role": "system",
496
- "content": flow_system_prompt(catalog, required, triggers, tables)},
497
- {"role": "user", "content": text}]
498
-
499
- if chat is not None:
500
- # ⚠ THE INJECTED PATH IS THE PROVEN PATH. It runs the SAME parse and the SAME refusal
501
- # branches as a live call; only the transport is replaced.
502
- draft, refusal = _flow_from_tool_call(chat(messages, tools))
503
- return draft, refusal, "injected"
504
-
505
- provs = flow_providers(model)
506
- if not provs:
507
- # β›” SAY SO. An AI feature that silently does nothing is indistinguishable from one that was
508
- # never built [[flag-shipped-without-its-writer]].
509
- return None, ("the assistant is not configured on this deployment, so an automation cannot "
510
- "be drafted from a description yet"), None
511
- tmo = float(timeout or TIMEOUT_SECONDS)
512
- problems = []
513
- import providers as _prov
514
- for p in provs:
515
- # ⭐⭐ W36-T35 / R4 β€” THE OWNER QUOTED THIS LINE BACK AT US. It used to read
516
- # `problems.append(f"{p['name']}: tool calls are not wired for this shape")` and `continue`,
517
- # so the sentence *"anthropic: tool calls are not wired for this shape"* appeared under the
518
- # Agent module verbatim. R4: *"Anthropic becomes the tool-calling path that always works."*
519
- # It is wired now, through the ONE wire in `providers`, and it matters more than it looks:
520
- # every side rung on this account is refusing today (cerebras 402, groq 404, openrouter
521
- # 402), so without this branch the drafter cannot answer at all.
522
- # ⚠ NO `effort` ON THIS DOOR β€” `output_config.effort` errors on Haiku 4.5, the tier this
523
- # ladder runs. The parameter is the caller's to send, which is why the wire takes it.
524
- # ⭐ D-346 (W37-T39): BOTH shapes now yield the SAME `(status, body)` pair, so every branch
525
- # below reads one thing. The anthropic side gets there through `anthropic_send` (official
526
- # SDK when installed, the identical raw POST when not); the openai side still posts here
527
- # because there is no shared SDK across three different vendors on that wire.
528
- global LAST_ANTHROPIC_TRANSPORT
529
- try:
530
- if p["shape"] == "anthropic":
531
- req = _prov.anthropic_request(
532
- model=p["model"], key=os.environ[p["env"]].strip(), system=None,
533
- messages=messages, tools=tools, max_tokens=1500, tool_choice="required")
534
- status, body, transport = _prov.anthropic_send(req, timeout=tmo)
535
- LAST_ANTHROPIC_TRANSPORT = transport
536
- else:
537
- r = requests.post(p["url"], timeout=tmo,
538
- headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
539
- "Content-Type": "application/json"},
540
- json={"model": p["model"], "messages": messages, "tools": tools,
541
- "tool_choice": "required", "temperature": 0.1,
542
- "max_tokens": 1500})
543
- status = r.status_code
544
- body = r.json() if (r.content and r.status_code == 200) else {"_text": r.text}
545
- except Exception as e: # noqa: BLE001
546
- problems.append(f"{p['name']}: {type(e).__name__}")
547
- continue
548
- if status != 200:
549
- # β›” A SENTENCE, NOT `HTTP 402` (R4's third clause). The owner read the status codes off
550
- # this very door. `refusal_sentence` also decides whether this was a CREDIT failure, and
551
- # the memo makes the next turn SKIP the empty account instead of paying for it again.
552
- # ⚠ The body is re-serialised for the substring test because the SDK path never had a
553
- # `.text` β€” that is the one thing this normalisation costs, and it costs nothing else.
554
- detail = json.dumps(body)[:600] if isinstance(body, dict) else str(body)[:600]
555
- if _prov.is_credit_failure(status, detail):
556
- _prov.mark_no_credit(p["name"])
557
- problems.append(_prov.refusal_sentence(p["name"], status, detail))
558
- continue
559
- try:
560
- body = body or {}
561
- if p["shape"] == "anthropic":
562
- _text, args, _refused = _prov.anthropic_read(body)
563
- if _refused:
564
- problems.append(f"{p['name']}: {_refused}")
565
- continue
566
- else:
567
- calls = (((body.get("choices") or [{}])[0].get("message") or {})
568
- .get("tool_calls") or [])
569
- args = json.loads(calls[0]["function"]["arguments"]) if calls else None
570
- except Exception as e: # noqa: BLE001
571
- problems.append(f"{p['name']}: unreadable answer ({type(e).__name__})")
572
- continue
573
- # ⭐⭐ C7 β€” THE LEDGER LINE. Placed after the parse rather than before it so an UNREADABLE
574
- # answer is not double-counted by the `continue` above... ⚠ which means an unreadable answer
575
- # is NOT counted at all, and that is a deliberate, disclosed loss: a body this code cannot
576
- # parse is a body whose `usage` it also cannot trust, and `body` is out of scope in that
577
- # branch by construction. The 200-with-junk case is rare and named here rather than
578
- # silently rounded to zero.
579
- ins, outs = usage_ledger.tokens_from(body)
580
- usage_ledger.record("automation_draft", p["name"], p["model"], ins, outs,
581
- total=usage_ledger.total_from(body), st=st, user=user)
582
- draft, refusal = _flow_from_tool_call(args)
583
- if draft is None and isinstance(args, dict) and str(args.get("kind")) == "refused":
584
- # β›” A REFUSAL IS AN ANSWER, NOT A FAULT, so it does NOT fall through to a more
585
- # expensive rung β€” the model has just said this cannot be built. `decide()` takes the
586
- # same posture for the same reason.
587
- return None, refusal, p["name"]
588
- if draft is not None:
589
- return draft, "", p["name"]
590
- problems.append(f"{p['name']}: {refusal}")
591
- return None, ("; ".join(problems)[:300] or "no provider answered"), None
 
1
+ """AI REVIEW β€” let a model decide which stage a card moves to (wave 23, owner ruling R4/R14).
2
+
3
+ ⭐ WHAT THIS IS. A review stage holds a record until somebody decides where it goes next. R4 made
4
+ that somebody optionally a MODEL: the engine hands over the record's own values, the review's
5
+ prompt, and the list of stages the review is allowed to send a card to, and gets back ONE of
6
+ those stage labels plus a one-line reason. Every decision is written to the same `reviews` audit
7
+ log a human click writes to, tagged `by: "ai"` with the provider and model that made it.
8
+
9
+ β›” FAIL-CLOSED IN EVERY DIRECTION, and this is the whole safety story. No key configured, a
10
+ network failure, a slow answer, a malformed answer, or an answer naming a stage the review does
11
+ not offer β€” all return `("", {...})`, and the caller leaves the card exactly where a human would
12
+ have found it. The feature can be absent, broken or wrong and the worst outcome is a person doing
13
+ the work. Nothing here can move a card somewhere the review does not already permit.
14
+
15
+ ⭐ CHEAP FIRST (owner R14, verbatim: *"Claude is a bit too expensive"*). The ladder is
16
+ `groq β†’ cerebras β†’ openrouter β†’ anthropic`; the first CONFIGURED provider wins, and Anthropic is
17
+ last rather than absent β€” it is the quality backstop, not the default. `AIOS_AI_REVIEW_PROVIDER`
18
+ pins one; `AIOS_AI_MODEL` overrides the model.
19
+
20
+ ⭐⭐ THE ANTHROPIC LEG IS ON THE OFFICIAL SDK NOW (D-346, W37-T39, 2026-08-19). β›” THIS PARAGRAPH
21
+ USED TO ARGUE THE OPPOSITE and is rewritten rather than deleted, because a comment left asserting
22
+ the reverse of its own code is [[two-gates-can-assert-opposite-things]] with no gate to catch it.
23
+ The retired text said raw HTTP was *"a deliberate deviation … booked as a DEBT line so the
24
+ integrator can overturn it deliberately rather than by drift"*. This is that overturn.
25
+
26
+ Its two reasons were real and are both answered rather than waved away:
27
+ 1. *"one SDK leg beside three hand-rolled ones is two implementations of the same call."* It is
28
+ not, because the leg does not live here: `providers.anthropic_send` owns the wire, prefers
29
+ the SDK, and normalises BOTH transports to one `(status, body)` pair. This file gained no
30
+ Anthropic knowledge β€” it lost some.
31
+ 2. *"adding a pinned dependency rebuilds the container, a real deploy risk."* Still true, so the
32
+ import is LAZY and its absence is a FALLBACK, not a crash: with no `anthropic` package the
33
+ same raw POST runs and `LAST_ANTHROPIC_TRANSPORT` reports `'http'`. The pin is owed in BOTH
34
+ manifests ([[pin-deps-space-rebuilds]]) and is outside every worker fence this wave.
35
+ ⚠ The other three legs stay OpenAI-chat-shaped over `requests` β€” they have no shared SDK, and that
36
+ half of the original reasoning never expired.
37
+
38
+ The Messages shape below is the current one: `x-api-key` + `anthropic-version: 2023-06-01`, and
39
+ `stop_reason: "refusal"` is checked BEFORE reading `content` β€” a refusal answers HTTP 200 with an
40
+ empty content list, so code that indexes `content[0]` unconditionally breaks on it.
41
+ """
42
+ from __future__ import annotations
43
+
44
+ import json
45
+ import os
46
+ import re
47
+
48
+ import requests
49
+
50
+ #: The ladder. Order IS the policy (R14) β€” cheapest capable first, Anthropic last.
51
+ PROVIDERS = [
52
+ # β›”β›” D-345, FIXED W37-T39 (2026-08-19). This read `llama-3.3-70b-versatile` and Groq RETIRED
53
+ # it: a real POST with the live key answers HTTP 404 `model_not_found`, and the id is absent
54
+ # from `GET /openai/v1/models`. ⚠ THE `openai/` PREFIX IS PART OF GROQ'S ID and is NOT a typo
55
+ # for the cerebras rung below, which serves the same family bare as `gpt-oss-120b`.
56
+ {"name": "groq", "env": "GROQ_API_KEY", "shape": "openai",
57
+ "url": "https://api.groq.com/openai/v1/chat/completions",
58
+ "model": "openai/gpt-oss-120b"},
59
+ {"name": "cerebras", "env": "CEREBRAS_API_KEY", "shape": "openai",
60
+ "url": "https://api.cerebras.ai/v1/chat/completions",
61
+ "model": "gpt-oss-120b"},
62
+ {"name": "openrouter", "env": "OPENROUTER_API_KEY", "shape": "openai",
63
+ "url": "https://openrouter.ai/api/v1/chat/completions",
64
+ "model": "openai/gpt-4o-mini"},
65
+ # ⚠ haiku-class DELIBERATELY, not the default Opus tier: R14 put Anthropic on this ladder as
66
+ # the backstop for a one-line classification, and this is the cheapest current Claude that
67
+ # does it well. A bigger model here would be spending the owner's money to pick between two
68
+ # labels it already has in front of it.
69
+ {"name": "anthropic", "env": "ANTHROPIC_API_KEY", "shape": "anthropic",
70
+ "url": "https://api.anthropic.com/v1/messages",
71
+ # ⚠ AN ENV LEVER, NOT A NEW DEFAULT (W36-T35): haiku stays the choice for the reasons above,
72
+ # and a deployment whose side rungs are out of credit can raise the tier without a release.
73
+ "model": os.environ.get("AIOS_AI_REVIEW_ANTHROPIC_MODEL") or "claude-haiku-4-5"},
74
+ ]
75
+ ANTHROPIC_VERSION = "2023-06-01"
76
+ TIMEOUT_SECONDS = float(os.environ.get("AIOS_AI_REVIEW_TIMEOUT") or 20)
77
+ MAX_FIELD_CHARS = 200 # per value handed to the model
78
+ MAX_FIELDS = 30 # columns handed to the model
79
+ MAX_REASON = 200
80
+
81
+
82
+ def ladder():
83
+ """The providers that are actually usable here, in order. Empty = the feature is off."""
84
+ pin = (os.environ.get("AIOS_AI_REVIEW_PROVIDER") or "").strip().lower()
85
+ live = [p for p in PROVIDERS if (os.environ.get(p["env"]) or "").strip()]
86
+ if pin:
87
+ live = [p for p in live if p["name"] == pin]
88
+ return live
89
+
90
+
91
+ def configured():
92
+ return bool(ladder())
93
+
94
+
95
+ def _record_text(row, fields):
96
+ """The record, as the model sees it. Values are truncated and the column set is bounded β€”
97
+ an automation table can carry a 32 KB JSON blob per row (C7) and a review decision does not
98
+ need it. Machine bookkeeping columns are dropped: a stage cell naming the stage the card is
99
+ sitting at would be the model reading its own question back."""
100
+ keys = [k for k in (fields or list((row or {}).keys()))
101
+ if not str(k).startswith("stage_")][:MAX_FIELDS]
102
+ lines = []
103
+ for k in keys:
104
+ v = (row or {}).get(k)
105
+ if v is None or str(v).strip() == "":
106
+ continue
107
+ lines.append(f"{k}: {str(v)[:MAX_FIELD_CHARS]}")
108
+ return "\n".join(lines) or "(this record has no filled-in values)"
109
+
110
+
111
+ def _instruction(prompt, options, label):
112
+ return (
113
+ f"You are deciding what happens to one record waiting at a review step called "
114
+ f"{label!r} in a workflow.\n\n"
115
+ f"The person who built this workflow told you: {prompt}\n\n"
116
+ f"Choose EXACTLY ONE of these next steps, by its exact name:\n"
117
+ + "\n".join(f"- {o}" for o in options)
118
+ + "\n\nAnswer with one line of JSON and nothing else:\n"
119
+ '{"choice": "<one name from the list above>", "reason": "<one short sentence>"}\n'
120
+ "If the record does not give you enough to decide, answer "
121
+ '{"choice": "", "reason": "why not"} and a person will decide instead.'
122
+ )
123
+
124
+
125
+ def _parse(text, options):
126
+ """The model's line β†’ `(choice, reason)`. A choice that is not one of the offered stages is
127
+ DISCARDED, not fuzzy-matched: the offered list is a permission boundary, and a near-miss
128
+ resolved by string distance is how a card ends up somewhere nobody authorised."""
129
+ raw = str(text or "").strip()
130
+ obj = None
131
+ m = re.search(r"\{.*\}", raw, re.S)
132
+ if m:
133
+ try:
134
+ obj = json.loads(m.group(0))
135
+ except (ValueError, TypeError):
136
+ obj = None
137
+ if not isinstance(obj, dict):
138
+ return "", ""
139
+ choice = str(obj.get("choice") or "").strip()
140
+ reason = str(obj.get("reason") or "").strip()[:MAX_REASON]
141
+ for opt in options:
142
+ if choice.lower() == str(opt).lower():
143
+ return str(opt), reason # the OFFERED spelling wins, never the model's
144
+ return "", reason
145
+
146
+
147
+ # ⭐⭐ WAVE 35 Β· W35-T41 / C7 β€” THE TWO TRANSPORTS RETURN THE RESPONSE BODY'S `usage`.
148
+ #
149
+ # β›” THIS FILE'S OWN HEADER USED TO BE THE PRODUCT'S CONFESSION THAT NOTHING COUNTED: `ai_enrich`'s
150
+ # docstring says *"`ai_review.decide` -- the product's only other LLM entry -- has no token
151
+ # accounting of ANY kind"*. R9 asks for ONE meter for every AI surface, so the counting has to reach
152
+ # this transport rather than be bolted onto its caller β€” the caller never sees the body.
153
+ #
154
+ # ⚠ A THIRD RETURN VALUE, NOT A MUTATED ARGUMENT, and both call sites are in `decide` below. The
155
+ # tuple grew from `(text, err)` to `(text, err, usage)`; `usage` is the raw `usage` OBJECT (or None),
156
+ # because reading it is `usage_ledger`'s job and a second reader here would be the two-normalizers
157
+ # shape this repo keeps paying for.
158
+ def _call_openai(p, model, system, user, timeout):
159
+ r = requests.post(p["url"], timeout=timeout,
160
+ headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
161
+ "Content-Type": "application/json"},
162
+ json={"model": model, "max_tokens": 300, "temperature": 0,
163
+ "messages": [{"role": "system", "content": system},
164
+ {"role": "user", "content": user}]})
165
+ if r.status_code >= 400:
166
+ # ⚠ NO BODY ON A 4xx/5xx: an error envelope carries no usage, and a provider that refused
167
+ # before running the model has nothing to bill. The call is still COUNTED by `decide`.
168
+ return "", f"{p['name']} answered {r.status_code}", None
169
+ body = r.json()
170
+ choices = body.get("choices") or []
171
+ if not choices:
172
+ return "", f"{p['name']} returned no choices", body
173
+ return str(((choices[0] or {}).get("message") or {}).get("content") or ""), "", body
174
+
175
+
176
+ #: What transport the last Anthropic call actually used: `'sdk'`, `'http'`, or `''` before any.
177
+ #: ⚠ PROCESS-LOCAL AND FOR REPORTING ONLY. It exists so `GET /meta` and `verify_web_agent` can say
178
+ #: WHICH path ran rather than inferring it from a requirements file nobody in this lane can edit.
179
+ LAST_ANTHROPIC_TRANSPORT = ""
180
+
181
+
182
+ def _call_anthropic(p, model, system, user, timeout):
183
+ """One classification turn on the Messages API, through `providers.anthropic_send`.
184
+
185
+ ⭐ D-346 (W37-T39): this used to hand-roll the POST. It now goes through the shared wire, which
186
+ prefers the OFFICIAL `anthropic` SDK and falls back to the same raw POST when the package is
187
+ absent. The shape of what comes back is unchanged, deliberately: `anthropic_send` normalises
188
+ both transports to `(status, body)`, so every line below this call is untouched.
189
+ """
190
+ global LAST_ANTHROPIC_TRANSPORT
191
+ import providers as _prov # noqa: PLC0415
192
+ # ⚠ NO TOOLS ON THIS PATH. The builder omits `tool_choice` for exactly that case, so there is
193
+ # nothing to strip here β€” the rule lives in `anthropic_request`, beside the thing it constrains.
194
+ req = _prov.anthropic_request(
195
+ model=model, key=os.environ[p["env"]].strip(), system=system,
196
+ messages=[{"role": "user", "content": user}], tools=[], max_tokens=300)
197
+ status, body, transport = _prov.anthropic_send(req, timeout=timeout)
198
+ LAST_ANTHROPIC_TRANSPORT = transport
199
+ if status >= 400 or status == 0:
200
+ # ⭐ THE SENTENCE COMES FROM THE LADDER, NOT FROM HERE. `refusal_sentence` already names the
201
+ # vendor and the action for every status R4 enumerated, so a bare "anthropic answered 402"
202
+ # (which is what this line used to say, and what the owner quoted back at us) cannot recur.
203
+ return "", _prov.refusal_sentence("anthropic", status, json.dumps(body)[:400]), None
204
+ body = body or {}
205
+ # β›” stop_reason FIRST. A safety refusal is a successful 200 with an EMPTY content list, so
206
+ # reading content[0] before this check turns a refusal into an IndexError inside a run.
207
+ # ⚠ A refusal IS billed and its body carries `usage`, so the body rides back on this branch too.
208
+ if body.get("stop_reason") == "refusal":
209
+ return "", "anthropic declined to answer this record", body
210
+ parts = [b.get("text") or "" for b in (body.get("content") or [])
211
+ if isinstance(b, dict) and b.get("type") == "text"]
212
+ if not parts:
213
+ return "", "anthropic returned no text", body
214
+ return "".join(parts), "", body
215
+
216
+
217
+ def decide(*, prompt, options, row, fields=(), label="Review", timeout=None, st=None, user=""):
218
+ """Pick this record's next stage. Returns `(choice, meta)`.
219
+
220
+ `choice` is "" whenever a person should decide β€” which is every failure mode there is.
221
+ `meta` carries `provider`, `model`, `reason` on success, and `problem` on refusal to answer.
222
+
223
+ ⭐ W35-T41 / C7 β€” `st` and `user` are the USAGE LEDGER's target. Both default to absent because
224
+ this function's caller is `automation_engine.ai_decide(rt, ...)`, in another lane's fence: it
225
+ HAS the runtime and does not pass it yet, so until it does, a review's tokens are counted as
226
+ unattributed and REPORTED by `GET /usage` rather than dropped. See `usage_ledger`'s header for
227
+ why they cannot be resolved implicitly (measured: a contextvar does not survive a FastAPI
228
+ dependency).
229
+ """
230
+ import usage_ledger # noqa: PLC0415
231
+ opts = [str(o) for o in (options or []) if str(o).strip()]
232
+ if not opts:
233
+ return "", {"problem": "the review offers no next stages"}
234
+ if not str(prompt or "").strip():
235
+ return "", {"problem": "the review has no prompt for the model to follow"}
236
+ live = ladder()
237
+ if not live:
238
+ return "", {"problem": "no AI provider is configured on this deployment"}
239
+ system = _instruction(prompt, opts, label)
240
+ user = "Here is the record:\n\n" + _record_text(row, fields)
241
+ tmo = float(timeout or TIMEOUT_SECONDS)
242
+ override = (os.environ.get("AIOS_AI_MODEL") or "").strip()
243
+ problems = []
244
+ for p in live:
245
+ model = override or p["model"]
246
+ body = None
247
+ try:
248
+ text, err, body = (_call_anthropic if p["shape"] == "anthropic" else _call_openai)(
249
+ p, model, system, user, tmo)
250
+ except Exception as e: # noqa: BLE001
251
+ text, err = "", f"{p['name']} failed: {type(e).__name__}"
252
+ # ⭐⭐ C7 β€” THE LEDGER LINE, BEFORE ANY BRANCH BELOW READS THE ANSWER.
253
+ # β›” IT IS WRITTEN ON EVERY OUTCOME THAT REACHED A PROVIDER, including a refusal and an
254
+ # unusable answer. A meter that books only successes reports a cheap week for a run that
255
+ # spent its budget being declined β€” and a declined call is billed. The only path that does
256
+ # NOT record is a transport that never reached the vendor (`body is None`), which spent
257
+ # nothing.
258
+ if body is not None:
259
+ ins, outs = usage_ledger.tokens_from(body)
260
+ usage_ledger.record("ai_review", p["name"], model, ins, outs,
261
+ total=usage_ledger.total_from(body), st=st, user=user)
262
+ if err:
263
+ problems.append(err)
264
+ continue # ladder: a dead provider degrades to the next one
265
+ choice, reason = _parse(text, opts)
266
+ if not choice:
267
+ # The provider ANSWERED and declined (or answered unusably). That is a decision about
268
+ # this record, not a fault in the provider, so it does NOT fall through to a more
269
+ # expensive one β€” the card goes to a human, which is what the model just asked for.
270
+ return "", {"provider": p["name"], "model": model,
271
+ "problem": reason or "the model did not choose one of the stages"}
272
+ return choice, {"provider": p["name"], "model": model, "reason": reason}
273
+ return "", {"problem": "; ".join(problems)[:300] or "no provider answered"}
274
+
275
+
276
+ # ══════════════════════════════════════════════════════════════════ the FLOW WRITER
277
+ # ⭐⭐ WAVE 33 Β· W33-T54/T55 (owner item 7, ruling R3) β€” A PROMPT BECOMES A DRAFT AUTOMATION.
278
+ #
279
+ # Owner, verbatim: *"lay out the foundation with custom tools we provide"* β€” and the tools are the
280
+ # action catalog, which has been machine-readable since wave 23. So this writes no new vocabulary:
281
+ # it hands the model the SAME `ACTION_CATALOG` the menu paints, the SAME `ACTION_REQUIRED` the
282
+ # runner blocks on, and the SAME trigger keys `clean_trigger` accepts, and asks for one JSON object
283
+ # in that vocabulary.
284
+ #
285
+ # β›” WHY IT LIVES IN `ai_review.py` RATHER THAN A NEW FILE. Two reasons, both about ownership. This
286
+ # is the one module in the API package that already holds an LLM ladder and its credentials, so a
287
+ # second one would be a second place a rotated key has to be noticed; and a new `routes_*.py` needs
288
+ # a `main.py` line from another lane (contract C2) to be reachable at all, which is how wave 23
289
+ # shipped three finished routers 404-dead behind green gates. The DOOR is a route on
290
+ # `routes_automation.py`, which is already mounted.
291
+ #
292
+ # β›”β›” CONTRACT C7 IS THE DESIGN, NOT A CHECK AT THE END: *"the flow writer may emit only kinds
293
+ # present in `ACTION_CATALOG`, and its output must pass `clean_actions` unchanged."* Both halves are
294
+ # enforced mechanically rather than asked for politely β€” the kind list is an `enum` in the schema
295
+ # the model fills, and the caller runs `clean_actions` and DIFFS the result. That diff matters
296
+ # because `clean_actions` has no disclosure channel (D-75): it drops a key it does not recognise
297
+ # and answers 200, so a draft accepted without the diff would show a person a flow that is not the
298
+ # flow the model described, with nothing anywhere saying so.
299
+ #
300
+ # ⚠ `chat` IS INJECTABLE, exactly as `routes_query._call_model`'s is, and it is the reason this door
301
+ # can be proven end to end with no API key and no spend. A gate that can only run where a
302
+ # credential exists is a gate that never runs.
303
+
304
+ #: Cerebras first, NOT the cheap-first order `ladder()` uses. Same reason `routes_query` inverts it:
305
+ #: this contract includes a REFUSAL, and refusing honestly ("I cannot build that from the steps you
306
+ #: have") is a model property. A cheaper rung answers an impossible request with a plausible flow,
307
+ #: which is worse than no flow. Override with `AIOS_FLOW_PROVIDER`.
308
+ FLOW_PROVIDER_ORDER = ("cerebras", "groq", "openrouter", "anthropic")
309
+ MAX_DRAFT_ACTIONS = 12 # a draft a person reads in one screen; the engine's own cap is 25
310
+ MAX_PROMPT_CHARS = 2000
311
+
312
+
313
+ def flow_providers(pin=None):
314
+ """The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off.
315
+
316
+ ⭐ `pin` IS ASK D-18 (2026-08-18): the Agent chat's model toggle must configure something, and
317
+ the draft door used to read `prompt` off the body and nothing else β€” so the key the client sent
318
+ was accepted and dropped, and the picker was a control over nothing.
319
+ ⚠ AN UNKNOWN OR UNCONFIGURED PIN FALLS BACK TO THE LADDER rather than refusing. A model the
320
+ ladder stopped offering must not turn every later draft into an error; the caller is told which
321
+ rung actually answered, which is the honest half.
322
+ """
323
+ by_name = {p["name"]: p for p in PROVIDERS}
324
+ live = [n for n in FLOW_PROVIDER_ORDER
325
+ if n in by_name and (os.environ.get(by_name[n]["env"]) or "").strip()]
326
+ wanted = str(pin or os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
327
+ if wanted and wanted in live:
328
+ return [by_name[wanted]]
329
+ return [by_name[n] for n in live]
330
+
331
+
332
+ def flow_schema(kinds, trigger_keys, table_keys):
333
+ """The tool schema the model fills β€” the catalog's OWN key lists as enums.
334
+
335
+ β›” `kind` AND `trigger` ARE ENUMS, not free strings, and that is C7's first half enforced by the
336
+ transport rather than by a check afterwards. A model asked for "any action name" invents
337
+ `send_slack_message` on a deployment that has no such kind, and the failure then surfaces as a
338
+ 400 from `clean_actions` carrying a sentence about a word the person never typed.
339
+ ⚠ `required` IS `["kind"]` ALONE, deliberately: a REFUSAL carries no name and no actions, and a
340
+ schema demanding them turns an honest refusal into a provider-side 400 that reads exactly like a
341
+ transport failure (`routes_query._spec_schema` carries the same note, for the same measured
342
+ reason).
343
+ """
344
+ return {
345
+ "type": "object",
346
+ "properties": {
347
+ "kind": {"type": "string", "enum": ["flow", "refused"],
348
+ "description": "refused = this cannot be built from the steps available"},
349
+ "refusal": {"type": "string",
350
+ "description": "when kind=refused: ONE plain sentence naming what is "
351
+ "missing, in the words a non-technical person would use"},
352
+ "name": {"type": "string", "description": "a short title for the automation"},
353
+ "trigger": {"type": "string", "enum": sorted(trigger_keys),
354
+ "description": "what starts this automation"},
355
+ "table": {"type": "string", "enum": sorted(table_keys),
356
+ "description": "the database whose records this flow walks, if any"},
357
+ "actions": {
358
+ "type": "array",
359
+ "maxItems": MAX_DRAFT_ACTIONS,
360
+ "items": {
361
+ "type": "object",
362
+ "properties": {
363
+ "kind": {"type": "string", "enum": sorted(kinds)},
364
+ "why": {"type": "string",
365
+ "description": "one short sentence: why this step is here"},
366
+ "config": {"type": "object", "additionalProperties": True,
367
+ "description": "the step's settings, using ONLY the keys named "
368
+ "for that kind in the system message"},
369
+ },
370
+ "required": ["kind"],
371
+ },
372
+ },
373
+ },
374
+ "required": ["kind"],
375
+ }
376
+
377
+
378
+ def flow_system_prompt(catalog, required, triggers, tables):
379
+ """What the model is told it may build with β€” DERIVED, never written down twice.
380
+
381
+ Every list here is the server's own: the catalog rows the menu paints, the required-key table
382
+ the runner blocks on, the trigger keys `clean_trigger` accepts, and this tenant's real databases
383
+ with their real columns. Nothing about the vocabulary is restated by hand, so a kind added to
384
+ the catalog is offered here on the same deploy and a kind removed stops being offered.
385
+ """
386
+ lines = ["You build small automations for a business tool. You are given the EXACT set of "
387
+ "steps this tool can perform. You may use nothing else.",
388
+ "", "THE STEPS YOU MAY USE:"]
389
+ # ⚠ BOTH HALVES, `key (phrase)`. The KEY is what the model must write into `config` and the
390
+ # PHRASE is the only human wording of that requirement anywhere β€” the one the runner's own
391
+ # refusal sentence is built from. Keys alone leave the model guessing what `field` means on a
392
+ # `web_read` (it is a column to write into, not a form field); phrases alone leave it guessing
393
+ # what to call the setting. Handing it one and hoping is how a draft comes back configured
394
+ # against a key the validator drops.
395
+ req = {str(k): [f"{key} ({phrase})" for phrase, key in v] for k, v in (required or {}).items()}
396
+ for row in catalog or []:
397
+ if not row.get("ready"):
398
+ continue
399
+ kind = str(row.get("kind") or "")
400
+ need = req.get(kind) or []
401
+ lines.append(f"- {kind}: {row.get('label')} - {row.get('detail') or ''}"
402
+ + (f" REQUIRED settings: {', '.join(need)}" if need else ""))
403
+ lines += ["", "WHAT CAN START AN AUTOMATION:"]
404
+ for t in triggers or []:
405
+ if t.get("planned") or not t.get("ready", True):
406
+ continue
407
+ lines.append(f"- {t.get('key')}: {t.get('label')}")
408
+ lines += ["", "THE DATABASES THIS PERSON HAS:"]
409
+ for t in (tables or [])[:40]:
410
+ cols = ", ".join(str(f.get("key")) for f in (t.get("fields") or [])[:25])
411
+ lines.append(f"- {t.get('key')} ({t.get('label')}): {cols or 'no columns yet'}")
412
+ if not tables:
413
+ lines.append("- (none - do not name a database)")
414
+ lines += [
415
+ "",
416
+ "RULES:",
417
+ "1. Use ONLY the step kinds listed above. If what is asked needs a step that is not there, "
418
+ "answer kind=refused and say plainly which capability is missing.",
419
+ "2. Fill in every REQUIRED setting you can from what the person told you. Leave one blank "
420
+ "rather than inventing a web address, a CSS selector or a column name.",
421
+ "3. A web address must start with http:// or https://.",
422
+ "4. To use a value from the record the flow is walking, write it as {{Column name}}.",
423
+ "5. Name a database only from the list above, by its key.",
424
+ "6. Keep it short. Fewer steps that work beat more steps that guess.",
425
+ ]
426
+ return "\n".join(lines)
427
+
428
+
429
+ def _flow_from_tool_call(obj):
430
+ """The model's tool arguments -> `(draft, refusal)`. A shape error is a refusal, never a crash."""
431
+ if not isinstance(obj, dict):
432
+ return None, "the assistant's answer could not be read"
433
+ if str(obj.get("kind") or "") == "refused":
434
+ return None, (str(obj.get("refusal") or "").strip()
435
+ or "the assistant could not build this from the steps available")
436
+ acts = obj.get("actions")
437
+ if not isinstance(acts, list) or not acts:
438
+ return None, ("the assistant did not produce any steps - try describing what should "
439
+ "happen, one action at a time")
440
+ out = []
441
+ for a in acts[:MAX_DRAFT_ACTIONS]:
442
+ if not isinstance(a, dict) or not str(a.get("kind") or "").strip():
443
+ continue
444
+ cfg = a.get("config")
445
+ out.append({"kind": str(a["kind"]).strip(),
446
+ "config": cfg if isinstance(cfg, dict) else {},
447
+ "why": str(a.get("why") or "").strip()[:200]})
448
+ if not out:
449
+ return None, "the assistant's steps could not be read"
450
+ return {"name": str(obj.get("name") or "").strip()[:80] or "New automation",
451
+ "trigger": str(obj.get("trigger") or "").strip(),
452
+ "table": str(obj.get("table") or "").strip(),
453
+ # β›”β›” THE TRUNCATION IS REPORTED, and it is a STANDING RULE that it must be (owner,
454
+ # 2026-08-12, W30/R6 second sentence): *"if there is lag or it can't be done, you need
455
+ # to explicitly tell me why and recommend a fix"* β€” **a silent truncation IS the
456
+ # violation, not the limit.** `acts[:MAX_DRAFT_ACTIONS]` above dropped everything past
457
+ # the twelfth and said nothing, so a model that answered with a twenty-step journey had
458
+ # eight steps deleted between the answer and the screen, with no key anywhere in the
459
+ # response naming them. `MAX_ACTIONS` is 20, so those steps were STORABLE β€” this
460
+ # ceiling is the draft door's own, which makes reporting it the whole obligation.
461
+ # ⚠ Found by the verifier that checked this ticket, not by a gate.
462
+ "asked": len([a for a in acts if isinstance(a, dict)]),
463
+ "actions": out}, ""
464
+
465
+
466
+ def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeout=None,
467
+ st=None, user="", model=None):
468
+ """A sentence -> `(draft, refusal_sentence, provider)`. β›” NOTHING IS SAVED HERE.
469
+
470
+ Exactly one of `draft` and `refusal_sentence` is truthy β€” the same contract
471
+ `web_agent.run_step` keeps, so a caller has no third case to get wrong.
472
+
473
+ ⭐ W35-T41 / C7 β€” `st`/`user` are the usage ledger's target, exactly as on `decide` above and for
474
+ the same reason: both of this function's callers (`automation_engine._ai_agent_plan` and
475
+ `routes_automation`'s draft door) are in lane D's fence. C7 says E adds the ledger line here and
476
+ D asserts it; the two keywords are what D has to pass for the line to be attributable.
477
+ """
478
+ # ⚠ DECLARED AT THE TOP OF THE FUNCTION, not beside the assignment inside the provider loop.
479
+ # It parses either way; a reader scanning for the declaration does not look inside a `for`.
480
+ global LAST_ANTHROPIC_TRANSPORT
481
+ import usage_ledger # noqa: PLC0415
482
+ text = str(prompt or "").strip()[:MAX_PROMPT_CHARS]
483
+ if not text:
484
+ return None, "type what you want the automation to do", None
485
+ kinds = sorted({str(r.get("kind")) for r in (catalog or []) if r.get("ready")})
486
+ if not kinds:
487
+ return None, "this deployment offers no automation steps to build with", None
488
+ trigger_keys = sorted({str(t.get("key")) for t in (triggers or [])
489
+ if t.get("key") and not t.get("planned")}) or ["manual"]
490
+ table_keys = sorted({str(t.get("key")) for t in (tables or []) if t.get("key")}) or [""]
491
+ tools = [{"type": "function", "function": {
492
+ "name": "build_automation",
493
+ "description": "Emit the automation, or refuse.",
494
+ "parameters": flow_schema(kinds, trigger_keys, table_keys)}}]
495
+ messages = [{"role": "system",
496
+ "content": flow_system_prompt(catalog, required, triggers, tables)},
497
+ {"role": "user", "content": text}]
498
+
499
+ if chat is not None:
500
+ # ⚠ THE INJECTED PATH IS THE PROVEN PATH. It runs the SAME parse and the SAME refusal
501
+ # branches as a live call; only the transport is replaced.
502
+ draft, refusal = _flow_from_tool_call(chat(messages, tools))
503
+ return draft, refusal, "injected"
504
+
505
+ provs = flow_providers(model)
506
+ if not provs:
507
+ # β›” SAY SO. An AI feature that silently does nothing is indistinguishable from one that was
508
+ # never built [[flag-shipped-without-its-writer]].
509
+ return None, ("the assistant is not configured on this deployment, so an automation cannot "
510
+ "be drafted from a description yet"), None
511
+ tmo = float(timeout or TIMEOUT_SECONDS)
512
+ problems = []
513
+ import providers as _prov
514
+ for p in provs:
515
+ # ⭐⭐ W36-T35 / R4 β€” THE OWNER QUOTED THIS LINE BACK AT US. It used to read
516
+ # `problems.append(f"{p['name']}: tool calls are not wired for this shape")` and `continue`,
517
+ # so the sentence *"anthropic: tool calls are not wired for this shape"* appeared under the
518
+ # Agent module verbatim. R4: *"Anthropic becomes the tool-calling path that always works."*
519
+ # It is wired now, through the ONE wire in `providers`, and it matters more than it looks:
520
+ # every side rung on this account is refusing today (cerebras 402, groq 404, openrouter
521
+ # 402), so without this branch the drafter cannot answer at all.
522
+ # ⚠ NO `effort` ON THIS DOOR β€” `output_config.effort` errors on Haiku 4.5, the tier this
523
+ # ladder runs. The parameter is the caller's to send, which is why the wire takes it.
524
+ # ⭐ D-346 (W37-T39): BOTH shapes now yield the SAME `(status, body)` pair, so every branch
525
+ # below reads one thing. The anthropic side gets there through `anthropic_send` (official
526
+ # SDK when installed, the identical raw POST when not); the openai side still posts here
527
+ # because there is no shared SDK across three different vendors on that wire.
528
+ global LAST_ANTHROPIC_TRANSPORT
529
+ try:
530
+ if p["shape"] == "anthropic":
531
+ req = _prov.anthropic_request(
532
+ model=p["model"], key=os.environ[p["env"]].strip(), system=None,
533
+ messages=messages, tools=tools, max_tokens=1500, tool_choice="required")
534
+ status, body, transport = _prov.anthropic_send(req, timeout=tmo)
535
+ LAST_ANTHROPIC_TRANSPORT = transport
536
+ else:
537
+ r = requests.post(p["url"], timeout=tmo,
538
+ headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
539
+ "Content-Type": "application/json"},
540
+ json={"model": p["model"], "messages": messages, "tools": tools,
541
+ "tool_choice": "required", "temperature": 0.1,
542
+ "max_tokens": 1500})
543
+ status = r.status_code
544
+ body = r.json() if (r.content and r.status_code == 200) else {"_text": r.text}
545
+ except Exception as e: # noqa: BLE001
546
+ problems.append(f"{p['name']}: {type(e).__name__}")
547
+ continue
548
+ if status != 200:
549
+ # β›” A SENTENCE, NOT `HTTP 402` (R4's third clause). The owner read the status codes off
550
+ # this very door. `refusal_sentence` also decides whether this was a CREDIT failure, and
551
+ # the memo makes the next turn SKIP the empty account instead of paying for it again.
552
+ # ⚠ The body is re-serialised for the substring test because the SDK path never had a
553
+ # `.text` β€” that is the one thing this normalisation costs, and it costs nothing else.
554
+ detail = json.dumps(body)[:600] if isinstance(body, dict) else str(body)[:600]
555
+ if _prov.is_credit_failure(status, detail):
556
+ _prov.mark_no_credit(p["name"])
557
+ problems.append(_prov.refusal_sentence(p["name"], status, detail))
558
+ continue
559
+ try:
560
+ body = body or {}
561
+ if p["shape"] == "anthropic":
562
+ _text, args, _refused = _prov.anthropic_read(body)
563
+ if _refused:
564
+ problems.append(f"{p['name']}: {_refused}")
565
+ continue
566
+ else:
567
+ calls = (((body.get("choices") or [{}])[0].get("message") or {})
568
+ .get("tool_calls") or [])
569
+ args = json.loads(calls[0]["function"]["arguments"]) if calls else None
570
+ except Exception as e: # noqa: BLE001
571
+ problems.append(f"{p['name']}: unreadable answer ({type(e).__name__})")
572
+ continue
573
+ # ⭐⭐ C7 β€” THE LEDGER LINE. Placed after the parse rather than before it so an UNREADABLE
574
+ # answer is not double-counted by the `continue` above... ⚠ which means an unreadable answer
575
+ # is NOT counted at all, and that is a deliberate, disclosed loss: a body this code cannot
576
+ # parse is a body whose `usage` it also cannot trust, and `body` is out of scope in that
577
+ # branch by construction. The 200-with-junk case is rare and named here rather than
578
+ # silently rounded to zero.
579
+ ins, outs = usage_ledger.tokens_from(body)
580
+ usage_ledger.record("automation_draft", p["name"], p["model"], ins, outs,
581
+ total=usage_ledger.total_from(body), st=st, user=user)
582
+ draft, refusal = _flow_from_tool_call(args)
583
+ if draft is None and isinstance(args, dict) and str(args.get("kind")) == "refused":
584
+ # β›” A REFUSAL IS AN ANSWER, NOT A FAULT, so it does NOT fall through to a more
585
+ # expensive rung β€” the model has just said this cannot be built. `decide()` takes the
586
+ # same posture for the same reason.
587
+ return None, refusal, p["name"]
588
+ if draft is not None:
589
+ return draft, "", p["name"]
590
+ problems.append(f"{p['name']}: {refusal}")
591
+ return None, ("; ".join(problems)[:300] or "no provider answered"), None
api/connectors_tt.py CHANGED
@@ -1,568 +1,568 @@
1
- """connectors_tt.py β€” the TIKTOK connector (wave 29 Β· item 7 Β· DEBT D-9 Β· rulings R1 + R2).
2
-
3
- Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
4
- automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
5
- exists at all rather than another thousand lines inside the engine.
6
-
7
- β›” **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema β€” 40 profile / 43
8
- post / 17 comment fields, each with the vendor's own type, description and `pii` flag β€” was read
9
- live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
10
- `.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
11
- close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
12
- name below reads through a candidate list it is because the vendor has two names for one fact
13
- (`biography`/`signature`, `region`/`country`), never because the name is uncertain.
14
-
15
- β›” **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned β€”
16
- public data through a supplier, exactly the rail `connectors_ig.py` states for Instagram. The
17
- vendor key is a key to a SUPPLIER.
18
-
19
- ⭐ **THE TRANSPORT IS `connectors_bd.py` β€” SHARED, VENDOR-NAMED, AND NO LONGER BORROWED FROM THE
20
- OTHER PLATFORM'S CONNECTOR** (WAVE 30 Β· T09, DEBT D-128). `bd_call`, `bd_scrape` and
21
- `bd_filter_start` take the dataset id as a PARAMETER β€” they are Bright Data's wire, not
22
- Instagram's β€” and re-implementing them here would be a second copy of the deferral handling, the
23
- truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
24
- Until wave 30 the code was right and the NAME was wrong: this file imported thirteen symbols from
25
- `connectors_ig`, which read as a dependency on Instagram and was really a dependency on a supplier.
26
- ⚠ **This file now imports ZERO names from `connectors_ig`, and a gate check asserts that**, because
27
- the sentence above is the kind that quietly stops being true.
28
-
29
- ⚠ **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
30
- 1. the real ROW shape β€” `/metadata` describes a DATASET, and Instagram's rows carry undeclared
31
- envelope keys (`timestamp`, `input`) that no metadata call mentions;
32
- 2. that a declared field POPULATES β€” Bright Data's Instagram Reels *declares* `views: number`
33
- and delivers an account-grain wrong number (Β§4e). **Declared is not delivered**, and the one
34
- TikTok claim that matters most (`play_count`) is exactly a declaration.
35
- """
36
- from __future__ import annotations
37
-
38
- import automation_engine as engine
39
- # ⚠ T09 β€” FOUR NAMES CAME OFF THIS LIST AND NOTHING BROKE, which is the point of deriving an
40
- # import block from the AST both ways. `bd_call`, `bd_filter_start`, `bd_key` and `bd_ready` were
41
- # imported here under a comment claiming they were *"re-exported for the runners"*; no runner ever
42
- # read them off this module (the engine imports them from the transport itself), so they were four
43
- # lines of dependency nobody was paying for. `[[artifact-with-no-importer]]` in its smallest form.
44
- from connectors_bd import (
45
- _bd_first_url,
46
- _bd_flag,
47
- _bd_list,
48
- _bd_source_payload,
49
- _first,
50
- _ig_int,
51
- bd_scrape,
52
- )
53
-
54
- # ---------------------------------------------------------------------------------------------
55
- # THE DATASETS
56
- # ---------------------------------------------------------------------------------------------
57
- # ⚠ CATALOGUE PRESENCE IS NOT ENTITLEMENT β€” the same finding Instagram produced. `GET
58
- # /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
59
- # full field list, and the two DISCOVERY halves answer **404 for our key**:
60
- # `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
61
- # β‡’ TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
62
- # does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
63
- TT_DS_PROFILES = "gd_l1villgoiiidt09ci" # TikTok - Profiles. 40 fields, 152,000,000 records
64
- TT_DS_POSTS = "gd_lu702nij2f790tmv9h" # TikTok - Posts. 43 fields
65
- TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k" # TikTok - Comments. 17 fields
66
-
67
- #: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
68
- #: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
69
- TT_POST_TYPE_VIDEO = "video"
70
- TT_POST_TYPE_CONTENT = "content"
71
-
72
- #: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
73
- #: beside the dataset ids because it is the same class of vendor fact.
74
- #: ⚠ ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
75
- #: string from `_PROFILE_RULES` (contract C2, E's half) β€” this exists for the connector's own
76
- #: batch calls, and the gate asserts the two agree rather than trusting that they do.
77
- TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
78
-
79
-
80
- def tt_profile_url(handle):
81
- """`nurilab` β†’ `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
82
- h = str(handle or "").strip().lstrip("@")
83
- return TT_PROFILE_URL.format(handle=h) if h else ""
84
-
85
-
86
- # ---------------------------------------------------------------------------------------------
87
- # THE FIELD MAPS
88
- # ---------------------------------------------------------------------------------------------
89
- # Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
90
- # in `automation_engine`. The rules they all obey, stated once:
91
- #
92
- # * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
93
- # so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
94
- # returns `None` (never 0) when nothing matches, which is what makes that possible.
95
- # * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
96
- # rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
97
- # * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
98
- # vendor's side is preserved rather than silently discarded while our column model catches up.
99
- # * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
100
- # (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
101
- # ride in `source_payload` where they make no claim.
102
-
103
-
104
- def _tt_str(node, *names):
105
- """The first non-empty string among `names`, or None when the vendor sent nothing.
106
-
107
- β›” `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest β€”
108
- an empty string written into a cell claims "we looked and it is empty".
109
- """
110
- v = _first(node, *names)
111
- if v is None:
112
- return None
113
- s = str(v).strip()
114
- return s or None
115
-
116
-
117
- def _tt_pct(node, *names):
118
- """A vendor 0–1 engagement fraction β†’ our stored 0–100 percentage, or None.
119
-
120
- β›” THE Γ—100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
121
- the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` β€”
122
- measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
123
- """
124
- v = _first(node, *names)
125
- if v is None:
126
- return None
127
- out = engine._pct100(v)
128
- return out or None
129
-
130
-
131
- def _tt_day(node, *names):
132
- """A vendor stamp β†’ `YYYY-MM-DD`, or None. Our `date` columns store a day."""
133
- v = _first(node, *names)
134
- if v is None:
135
- return None
136
- return engine._day(v) or None
137
-
138
-
139
- def _drop_blanks(row):
140
- """The one place a mapped row loses its `None`s β€” see the BLANK MEANS NOT READ rule above."""
141
- return {k: v for k, v in row.items() if v is not None and v != ""}
142
-
143
-
144
- def normalize_profile(node, handle=""):
145
- """A TikTok Profiles row β†’ the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
146
-
147
- ⚠ TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
148
- * `biography` is PRIMARY and `signature` the FALLBACK β€” the probe measured `signature`
149
- populated on 85% of rows and they carry the same text;
150
- * `region` is PRIMARY and `country` the FALLBACK β€” `region` is the one with a documented
151
- two-letter-ISO description, `country` has no description at all.
152
- ⚠ `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
153
- `ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
154
- only count of its kind the dataset offers.
155
- """
156
- node = node if isinstance(node, dict) else {}
157
- account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
158
- return _drop_blanks({
159
- "platform": engine.PLATFORM_TIKTOK,
160
- "handle": account,
161
- "full_name": _tt_str(node, "nickname"),
162
- "tt_id": _tt_str(node, "id"),
163
- "profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
164
- "bio": _tt_str(node, "biography", "signature"),
165
- "external_url": _bd_first_url(_first(node, "bio_link")),
166
- "verified": _bd_flag(node, "is_verified"),
167
- "is_private": _bd_flag(node, "is_private"),
168
- # ⚠ APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
169
- # on their own description. It is the closest thing TikTok has to Instagram's
170
- # `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent β€” so
171
- # the approximation only ever fills a cell the vendor actually answered.
172
- "is_business": _bd_flag(node, "is_commerce_user"),
173
- "followers": _ig_int(_first(node, "followers")),
174
- "following": _ig_int(_first(node, "following")),
175
- "posts_count": _ig_int(_first(node, "videos_count")),
176
- # ⚠ `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
177
- # nulls). It is not a post-level number and it is not our `likes` column, which is why it
178
- # is stored under a different name.
179
- "likes_received": _ig_int(_first(node, "likes")),
180
- "avg_engagement": _tt_pct(node, "awg_engagement_rate"),
181
- "like_engagement": _tt_pct(node, "like_engagement_rate"),
182
- "comment_engagement": _tt_pct(node, "comment_engagement_rate"),
183
- "country_code": _tt_str(node, "region", "country"),
184
- "region": _tt_str(node, "region"),
185
- "predicted_lang": _tt_str(node, "predicted_lang"),
186
- # ⚠ ACCOUNT AGE, NOT A MEASUREMENT STAMP β€” `create_time` on a profile is when the ACCOUNT
187
- # was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
188
- # which is why the append law dates a snapshot by when WE read it.
189
- "account_created_at": _tt_day(node, "create_time"),
190
- "source_payload": _bd_source_payload(node),
191
- })
192
-
193
-
194
- def tt_post_type(node):
195
- """A TikTok post row β†’ one of OUR three type options, or None.
196
-
197
- β›” THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
198
- `"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
199
- vendor's token would fail `_clean_field`'s option check on the way in and would put an
200
- untranslated API word in front of a user on the way out.
201
-
202
- So: `video` is `video`, and `content` β€” TikTok's photo-mode post β€” is `image`, EXCEPT when the
203
- row carries more than one `carousel_images` entry, which is what a carousel IS on either
204
- network. ⚠ The multi-image branch is decided from the IMAGES, never from the type token: the
205
- token cannot express it, so inferring `carousel` from the word would be inventing a fact.
206
- ⚠ An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
207
- that is exactly what would make the wrong default invisible).
208
- """
209
- raw = str((node or {}).get("post_type") or "").strip().lower()
210
- if raw == TT_POST_TYPE_VIDEO:
211
- return "video"
212
- if raw != TT_POST_TYPE_CONTENT:
213
- return None
214
- images = (node or {}).get("carousel_images")
215
- return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
216
-
217
-
218
- def normalize_post(node):
219
- """A TikTok Posts row β†’ the `ut_tt_posts` cell shape. None when it carries no identity.
220
-
221
- β›” THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
222
- Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
223
- fact β€” `play_count` IS the count TikTok displays under a video β€” so it maps to `views` and
224
- `ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
225
- manufacture a second measurement that a rollup could average or double-count, which is a worse
226
- outcome than the missing column it would paper over.
227
-
228
- ⚠ `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
229
- the probe measured them as the same shape. That equality is what lets the comments→posts link
230
- join with NO normaliser, which the Instagram side never had.
231
- ⚠ `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
232
- ⚠ `commerce_info` is a business/commerce LOCATION per its own description β€” cities and
233
- countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
234
- no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
235
- """
236
- node = node if isinstance(node, dict) else {}
237
- shortcode = _tt_str(node, "shortcode", "post_id")
238
- if not shortcode:
239
- return None
240
- return _drop_blanks({
241
- "platform": engine.PLATFORM_TIKTOK,
242
- "shortcode": shortcode,
243
- # β›”β›” `account_id`, NOT `profile_username` β€” MEASURED on a real Posts row 2026-08-12.
244
- # The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
245
- # @handle (`"d1na_th"`) β€” the same field `normalize_profile` already reads for `handle`, so
246
- # one name means one thing across both corpora. Reading the display name silently broke the
247
- # only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
248
- # NOTHING, so a person could not filter posts by creator and a rollup would count zero.
249
- # ⚠ NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
250
- # different fact, and filling a join key with it is worse than leaving it blank β€” a blank
251
- # is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
252
- # The URL is the honest second source: it carries the handle by construction.
253
- "influencer_key": (_tt_str(node, "account_id")
254
- or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
255
- "posted_at": _tt_day(node, "create_time"),
256
- "type": tt_post_type(node),
257
- "caption": _tt_str(node, "description"),
258
- "url": _tt_str(node, "url"),
259
- "hashtags": _bd_list(node, "hashtags"),
260
- "tagged_location": _tt_str(node, "commerce_info"),
261
- "views": _ig_int(_first(node, "play_count")),
262
- "likes": _ig_int(_first(node, "digg_count")),
263
- "comments": _ig_int(_first(node, "comment_count")),
264
- "shares": _ig_int(_first(node, "num_share_count")),
265
- "saves": _ig_int(_first(node, "collect_count")),
266
- "video_duration": _ig_int(_first(node, "video_duration")),
267
- "source_payload": _bd_source_payload(node),
268
- })
269
-
270
-
271
- def normalize_comment(node):
272
- """A TikTok Comments row β†’ the `ut_tt_comments` cell shape. None without a comment id.
273
-
274
- ⚠ THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
275
- `replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
276
- `source_payload`. Reading the array's length instead would be a second, disagreeing answer to
277
- a question the vendor already answers β€” and it would disagree, because a page of replies is not
278
- all of them.
279
- ⚠ `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
280
- text and needs defensive parsing. It still goes through `_tt_day` β€” one date path, so a vendor
281
- that changes its mind cannot change ours.
282
- ⚠ The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
283
- PII) stay in `source_payload` and are promoted to no column, which is the same posture the
284
- Instagram comment schema takes for the same D-24 reason.
285
- """
286
- node = node if isinstance(node, dict) else {}
287
- comment_key = _tt_str(node, "comment_id")
288
- if not comment_key:
289
- return None
290
- return _drop_blanks({
291
- "platform": engine.PLATFORM_TIKTOK,
292
- "comment_key": comment_key,
293
- "shortcode": _tt_str(node, "post_id"),
294
- # ⭐⭐ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
295
- # vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
296
- # primary first, so a row carrying the rich form is not silently served the plain one.
297
- # β›” The commenter's identity is deliberately NOT promoted β€” see `TT_COMMENT_FIELDS`.
298
- "text": _tt_str(node, "comment_text", "comment_text_only"),
299
- "commented_at": _tt_day(node, "date_created"),
300
- "likes": _ig_int(_first(node, "num_likes")),
301
- "replies": _ig_int(_first(node, "num_replies")),
302
- "source_payload": _bd_source_payload(node),
303
- })
304
-
305
-
306
- #: ⭐ The three maps, addressable by name β€” so a gate (and the runners in T04-T06) can walk them
307
- #: rather than naming three functions, and so adding a fourth dataset is one entry.
308
- TT_NORMALIZERS = {
309
- "tt_profile": normalize_profile,
310
- "tt_post_metrics": normalize_post,
311
- "tt_comments": normalize_comment,
312
- }
313
-
314
-
315
- # ---------------------------------------------------------------------------------------------
316
- # THE FETCH β€” wave 30 Β· W30-T08 (carrying wave-29's dropped T05)
317
- # ---------------------------------------------------------------------------------------------
318
-
319
- def tt_handle(url):
320
- """A TikTok profile URL **or** a bare handle β†’ the handle. `''` when it is neither.
321
-
322
- Deliberately permissive about the input and strict about the output, because the two callers
323
- hand it different things: an automation stores whatever a person typed in the profile column
324
- (`@nurilab`, `nurilab`, or the full URL), while the discovery runner already holds a clean
325
- `account_id`. One normaliser, so a row found by discovery and a row typed by hand cannot
326
- resolve to two different handles.
327
- """
328
- s = str(url or "").strip()
329
- if not s:
330
- return ""
331
- if "tiktok.com" in s.lower():
332
- # Everything after the first `@`, up to the next path segment or query.
333
- tail = s.split("@", 1)[1] if "@" in s else ""
334
- s = tail.split("/")[0].split("?")[0].split("#")[0]
335
- s = s.strip().lstrip("@").strip()
336
- # A handle is the vendor's `account_id` shape: alphanumerics, dots and underscores.
337
- return s if s and all(c.isalnum() or c in "._" for c in s) else ""
338
-
339
-
340
- def tt_post_urls(node, limit=0):
341
- """⭐ WAVE 30 Β· T10 β€” the profile row's own post permalinks, newest-first as the vendor sends.
342
-
343
- β›” THIS IS WHY TIKTOK POST CAPTURE COSTS NO EXTRA DISCOVERY. `top_videos` rides the PROFILE row
344
- we have already bought, so the posts read is a scrape of links we hold, never a search for them.
345
- The two TikTok DISCOVERY datasets (posts-by-profile, posts-by-keyword) are **404 for our key**,
346
- so a design that reached for either would not merely be dearer, it would not work.
347
-
348
- β›”β›” CORRECTED 2026-08-12 β€” THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
349
- array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
350
- read `/datasets/{id}/metadata` β€” a DATASET description β€” and the phrase quoted was the field's
351
- `ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
352
- (measured below), so the reader built against the quoted sentence found nothing, forever, in
353
- silence. ⭐ The transferable half: *"the probe measured X"* and *"the probe read a declaration
354
- of X"* are different claims, and prose cannot be told apart by a reader downstream β€” which is
355
- why the correction names the method, not just the value.
356
-
357
- ⚠ `top_posts_data` is deliberately NOT read: the probe calls it *"a thin dup of `top_videos`"*,
358
- and preferring whichever happened to be longer is how one creator's window silently differs
359
- from another's.
360
- ⚠ `limit <= 0` means "everything the row carried". The CAP IS THE CALLER'S β€” `config.maxPosts`,
361
- validated 1..12 β€” and it is applied here rather than after the scrape so an unwanted post is
362
- never bought. [[a-constant-two-features-share]]: the 12 is the vendor's measured profile window,
363
- not a number this function may invent.
364
- """
365
- raw = (node or {}).get("top_videos")
366
- out = []
367
- for item in raw if isinstance(raw, list) else []:
368
- # β›”β›” MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
369
- # `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
370
- # live handle returns **19 DICTS**, keyed
371
- # `video_url Β· video_id Β· playcount Β· diggcount Β· commentcount Β· share_count Β·
372
- # favorites_count Β· create_date Β· cover_image`.
373
- # The docstring above cites the $0 probe as having "measured" permalinks β€” it had not, and
374
- # could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
375
- # so in terms (*"what $0 cannot buy … the real ROW shape … that a declared field
376
- # POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
377
- # declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
378
- # the first. [[reachable-is-not-the-same-as-built]]
379
- # β‡’ The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
380
- # list on every real profile β€” post capture could not have worked for anybody, and the
381
- # T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
382
- # written from a schema tests the schema.
383
- # ⚠ `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
384
- # because it costs nothing and is what a future corpus revision would most likely use. The
385
- # bare-string branch stays for the same reason β€” this widens what is ACCEPTED and invents
386
- # nothing: a shape that yields no `http…` value still degrades to "no posts", exactly as
387
- # before, rather than to a URL built out of a guess.
388
- # ⚠ `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
389
- # whichever array happened to be longer is how one creator's window silently differs from
390
- # another's, and that reasoning is unchanged by this correction.
391
- if isinstance(item, dict):
392
- u = str(item.get("video_url") or item.get("url") or "").strip()
393
- else:
394
- u = str(item or "").strip()
395
- if u.lower().startswith("http") and u not in out:
396
- out.append(u)
397
- return out[:limit] if limit and limit > 0 else out
398
-
399
-
400
- def pull_posts_tt(post_urls, log=print, deferred=None):
401
- """The TikTok Posts dataset for a list of permalinks β†’ `(rows, note)`, already normalised.
402
-
403
- ⚠ ONE CALL FOR THE WHOLE WINDOW. `bd_scrape` has always taken a list, and the Instagram side
404
- measured what happens when a caller forgets: 25 records, one billed snapshot each, a walk still
405
- running at 67 minutes. Nothing here loops per URL.
406
- """
407
- urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
408
- if not urls:
409
- return [], ""
410
- rows, note = bd_scrape(TT_DS_POSTS, urls, deferred=deferred)
411
- if note:
412
- log(f"[aios-tt] posts: {note}")
413
- return [], note
414
- out = [r for r in (normalize_post(n) for n in rows) if r]
415
- return out, ""
416
-
417
-
418
- def pull_comments_tt(post_urls, log=print, deferred=None):
419
- """The TikTok Comments dataset for a list of POST permalinks β†’ `(rows, note)`, normalised.
420
-
421
- β›” THE MOST EXPENSIVE THING THIS PRODUCT BUYS, and the reason `commentMetrics` defaults OFF on
422
- both networks: a comments scrape ingests identifiable third parties who never entered anybody's
423
- list (D-24). The mapper already keeps every commenter field in `source_payload` and promotes
424
- none of them to a column; this function adds no new exposure, it just has to be asked for.
425
- """
426
- urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
427
- if not urls:
428
- return [], ""
429
- rows, note = bd_scrape(TT_DS_COMMENTS, urls, deferred=deferred)
430
- if note:
431
- log(f"[aios-tt] comments: {note}")
432
- return [], note
433
- out = [r for r in (normalize_comment(n) for n in rows) if r]
434
- return out, ""
435
-
436
-
437
- #: ⭐⭐ WAVE 30 Β· D-156 β€” THE MEDIA DATASETS, AS A SET, SO THE HAND-OFF CAN FILTER ON IDENTITY.
438
- #: `_media_deferrals` uses this to lift ONLY posts/comments snapshots out of the local deferral
439
- #: list. That is what makes it structurally impossible to file a PROFILE snapshot in the engine's
440
- #: metric queue β€” the defect a draft of T10 shipped and A-39 booked as "the wrong fix is worse
441
- #: than the gap". A membership test cannot be got wrong by a later edit the way `if` order can.
442
- TT_MEDIA_DATASETS = (TT_DS_POSTS, TT_DS_COMMENTS)
443
-
444
-
445
- def _media_deferrals(deferred):
446
- """The POSTS/COMMENTS entries of a `bd_scrape` deferral list β€” never the profile's.
447
-
448
- ⚠ The engine, not this module, decides what a deferral MEANS: it stamps `kind` and the
449
- handle and files it. TikTok needs no `_tag_metric_deferrals` twin because one dataset is one
450
- kind here, so the id already carries everything a mapper choice depends on β€” and importing
451
- Instagram's tagger is not available anyway (W30-T09 gates ZERO `from connectors_ig` lines).
452
- """
453
- out = []
454
- for d in deferred or []:
455
- if isinstance(d, dict) and str(d.get("datasetId") or "") in TT_MEDIA_DATASETS:
456
- out.append(dict(d))
457
- return out
458
-
459
-
460
- def pull_profile_tt(url, log=print, pending_profile=None, prefetch=None,
461
- max_posts=0, post_metrics=False, comment_metrics=False):
462
- """ONE TikTok profile from the vendor. Same return contract as `pull_profile`.
463
-
464
- `{state, profile, posts, comments, via, note}` with `state ∈ ok | partial | blocked | error`,
465
- so the engine's enrich branch treats every network identically and no caller learns a new
466
- shape.
467
-
468
- ⭐ WAVE 30 Β· T10 β€” POSTS AND COMMENTS ARE REAL NOW, AND BOTH DEFAULT OFF, exactly as Instagram's
469
- do. `post_metrics` scrapes the profile row's own `top_videos` permalinks (see `tt_post_urls` β€”
470
- no discovery call, because both TikTok discovery datasets 404 for our key); `comment_metrics`
471
- then scrapes the comments of the posts that came back. ⚠ COMMENTS REQUIRE POSTS by construction
472
- rather than by a rule: their input IS a post permalink, so asking for comments with post capture
473
- off is a request with no subject, and it returns none instead of quietly buying posts nobody
474
- asked for.
475
-
476
- β›” `partial` IS THE SUCCESS STATE WHENEVER NO MEDIA WAS READ, and that is deliberate rather than
477
- pessimistic. The Instagram contract reads `ok` only when identity AND media both landed
478
- (`pull_profile_bd`: *"identity without media is still partial ... a run that wrote a follower
479
- count and no posts must not paint green over a posts table that did not grow"*). So: posts not
480
- ASKED for β†’ `partial`, saying so; posts asked for and landed β†’ `ok`; asked for and none came β†’
481
- `partial` with the vendor's reason. The state answers "did this pull deliver what it went for",
482
- never "did the function finish".
483
-
484
- ⚠ **NO FREE RUNG, AND NO FALLBACK CHAIN.** Instagram's `pull_profile` drops to Apify when the
485
- paid rung refuses; `providers.DEFAULT_CHAINS["tt_profile"]` is deliberately single-provider,
486
- with its own note explaining that a multi-provider chain is a promise something walks it and
487
- that nothing walks Instagram's second name today either. So a refusal here is final, and it
488
- says so instead of implying a retry somewhere.
489
- """
490
- handle = tt_handle(url)
491
- if not handle:
492
- return {"state": "error", "profile": {}, "posts": [], "comments": [], "via": "",
493
- "note": f"{url!r} is not a TikTok profile URL or handle"}
494
-
495
- # ⭐ THE BATCH FAST PATH, same shape as the Instagram side: `prefetch` is `{handle: node}` from
496
- # one multi-URL scrape covering a whole selection. A hit is a vendor round trip that does not
497
- # happen; a miss falls through to the single-URL call below.
498
- cached = prefetch.get(handle) if isinstance(prefetch, dict) else None
499
- _deferred = []
500
- if isinstance(cached, dict) and cached:
501
- rows, note = [cached], ""
502
- else:
503
- rows, note = bd_scrape(TT_DS_PROFILES, [tt_profile_url(handle)], deferred=_deferred)
504
-
505
- node = rows[0] if rows else {}
506
- profile = normalize_profile(node, handle) if node else {}
507
- # β›” THE READABILITY TEST IS `followers`/`following`, NOT "did we get a dict". `normalize_profile`
508
- # drops blanks, so an unreadable row still returns `{"platform": …, "handle": …}` β€” truthy, and
509
- # carrying nothing anybody asked for. The Instagram rung tests exactly this pair for exactly
510
- # this reason, and answering "0 followers" instead is the failure it exists to prevent.
511
- unreadable = profile.get("followers") is None and profile.get("following") is None
512
- if note or unreadable:
513
- # ⭐ THE DEFERRAL IS HANDED OVER RATHER THAN DISCARDED. A snapshot the vendor is still
514
- # building HAS ALREADY BEEN PAID FOR; dropping its id bills again on the next run for the
515
- # same record. That was live on the Instagram profile path until 2026-08-09 β€” measured on
516
- # nurilab as two runs, two fresh snapshots, both abandoned β€” and it is not being
517
- # reintroduced here by omission.
518
- if isinstance(pending_profile, list):
519
- for d in _deferred:
520
- pending_profile.append({**d, "kind": "profile", "influencer": handle})
521
- why = note or ("the scrape answered, but no follower/following counts were readable in it "
522
- "(the field names may have moved - see tiktok-capture.md)")
523
- return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
524
- "deferredProfile": [d.get("snapshotId") for d in _deferred],
525
- "note": why}
526
-
527
- # --- W30-T10: THE MEDIA, ONLY WHEN IT WAS ASKED FOR. ------------------------------------
528
- if not post_metrics:
529
- return {"state": "partial", "profile": profile, "posts": [], "comments": [],
530
- "via": "brightdata",
531
- "note": note or "profile read; post capture is off for this step"}
532
- urls = tt_post_urls(node, limit=max_posts)
533
- if not urls:
534
- # ⚠ NOT AN ERROR AND NOT A RETRY. A creator with no `top_videos` has nothing to buy, and
535
- # saying so is what stops the next run paying to be told the same thing.
536
- return {"state": "partial", "profile": profile, "posts": [], "comments": [],
537
- "via": "brightdata",
538
- "note": note or "profile read; this account's row carried no post links"}
539
- posts, p_note = pull_posts_tt(urls, log=log, deferred=_deferred)
540
- comments, c_note = ([], "")
541
- if comment_metrics and posts:
542
- # The comments dataset is keyed on a POST permalink, so it reads the posts we just bought β€”
543
- # `url` from the mapper, never the profile's raw array, so a post the posts scrape refused
544
- # is not silently asked about again one rung later.
545
- comments, c_note = pull_comments_tt([p.get("url") for p in posts if p.get("url")],
546
- log=log, deferred=_deferred)
547
- # ⭐⭐ WAVE 30 Β· D-156 β€” THE MEDIA DEFERRALS ARE HANDED BACK, and the shape of the hand-off is
548
- # the whole lesson. An earlier draft of T10 appended every `_deferred` entry to
549
- # `pending_profile` tagged `kind: "profile"`. By the time control reaches here a PROFILE
550
- # deferral is impossible β€” the profile branch above returns `blocked` on any note β€” so **every
551
- # id fanned out that way was a POSTS or COMMENTS snapshot in the PROFILE queue**, whose
552
- # collector writes preset profile cells onto somebody's record from post rows. The engine keeps
553
- # the two queues apart deliberately (`_pending_profile_tasks` vs `_pending_metric_tasks`).
554
- # β‡’ So this returns them under their OWN key, filtered by dataset identity
555
- # (`_media_deferrals`), and the engine files them in the metric queue with the handle it
556
- # already holds. Returning rather than appending also keeps the queue's vocabulary out of a
557
- # connector: this module knows which CORPUS deferred, never what the engine calls it.
558
- # ⚠ `deferredMedia` rides BOTH returns on purpose. The empty-posts case is the one that
559
- # matters most β€” that is exactly the run where the vendor took too long, so a caller reading
560
- # the ids only from the success path would lose every batch it actually paid for.
561
- deferred_media = _media_deferrals(_deferred)
562
- if not posts:
563
- return {"state": "partial", "profile": profile, "posts": [], "comments": [],
564
- "via": "brightdata", "deferredMedia": deferred_media,
565
- "note": p_note or note or "profile read; the post source returned nothing"}
566
- return {"state": "ok", "profile": profile, "posts": posts, "comments": comments,
567
- "via": "brightdata", "deferredMedia": deferred_media,
568
- "note": c_note or note or ""}
 
1
+ """connectors_tt.py β€” the TIKTOK connector (wave 29 Β· item 7 Β· DEBT D-9 Β· rulings R1 + R2).
2
+
3
+ Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
4
+ automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
5
+ exists at all rather than another thousand lines inside the engine.
6
+
7
+ β›” **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema β€” 40 profile / 43
8
+ post / 17 comment fields, each with the vendor's own type, description and `pii` flag β€” was read
9
+ live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
10
+ `.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
11
+ close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
12
+ name below reads through a candidate list it is because the vendor has two names for one fact
13
+ (`biography`/`signature`, `region`/`country`), never because the name is uncertain.
14
+
15
+ β›” **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned β€”
16
+ public data through a supplier, exactly the rail `connectors_ig.py` states for Instagram. The
17
+ vendor key is a key to a SUPPLIER.
18
+
19
+ ⭐ **THE TRANSPORT IS `connectors_bd.py` β€” SHARED, VENDOR-NAMED, AND NO LONGER BORROWED FROM THE
20
+ OTHER PLATFORM'S CONNECTOR** (WAVE 30 Β· T09, DEBT D-128). `bd_call`, `bd_scrape` and
21
+ `bd_filter_start` take the dataset id as a PARAMETER β€” they are Bright Data's wire, not
22
+ Instagram's β€” and re-implementing them here would be a second copy of the deferral handling, the
23
+ truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
24
+ Until wave 30 the code was right and the NAME was wrong: this file imported thirteen symbols from
25
+ `connectors_ig`, which read as a dependency on Instagram and was really a dependency on a supplier.
26
+ ⚠ **This file now imports ZERO names from `connectors_ig`, and a gate check asserts that**, because
27
+ the sentence above is the kind that quietly stops being true.
28
+
29
+ ⚠ **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
30
+ 1. the real ROW shape β€” `/metadata` describes a DATASET, and Instagram's rows carry undeclared
31
+ envelope keys (`timestamp`, `input`) that no metadata call mentions;
32
+ 2. that a declared field POPULATES β€” Bright Data's Instagram Reels *declares* `views: number`
33
+ and delivers an account-grain wrong number (Β§4e). **Declared is not delivered**, and the one
34
+ TikTok claim that matters most (`play_count`) is exactly a declaration.
35
+ """
36
+ from __future__ import annotations
37
+
38
+ import automation_engine as engine
39
+ # ⚠ T09 β€” FOUR NAMES CAME OFF THIS LIST AND NOTHING BROKE, which is the point of deriving an
40
+ # import block from the AST both ways. `bd_call`, `bd_filter_start`, `bd_key` and `bd_ready` were
41
+ # imported here under a comment claiming they were *"re-exported for the runners"*; no runner ever
42
+ # read them off this module (the engine imports them from the transport itself), so they were four
43
+ # lines of dependency nobody was paying for. `[[artifact-with-no-importer]]` in its smallest form.
44
+ from connectors_bd import (
45
+ _bd_first_url,
46
+ _bd_flag,
47
+ _bd_list,
48
+ _bd_source_payload,
49
+ _first,
50
+ _ig_int,
51
+ bd_scrape,
52
+ )
53
+
54
+ # ---------------------------------------------------------------------------------------------
55
+ # THE DATASETS
56
+ # ---------------------------------------------------------------------------------------------
57
+ # ⚠ CATALOGUE PRESENCE IS NOT ENTITLEMENT β€” the same finding Instagram produced. `GET
58
+ # /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
59
+ # full field list, and the two DISCOVERY halves answer **404 for our key**:
60
+ # `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
61
+ # β‡’ TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
62
+ # does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
63
+ TT_DS_PROFILES = "gd_l1villgoiiidt09ci" # TikTok - Profiles. 40 fields, 152,000,000 records
64
+ TT_DS_POSTS = "gd_lu702nij2f790tmv9h" # TikTok - Posts. 43 fields
65
+ TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k" # TikTok - Comments. 17 fields
66
+
67
+ #: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
68
+ #: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
69
+ TT_POST_TYPE_VIDEO = "video"
70
+ TT_POST_TYPE_CONTENT = "content"
71
+
72
+ #: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
73
+ #: beside the dataset ids because it is the same class of vendor fact.
74
+ #: ⚠ ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
75
+ #: string from `_PROFILE_RULES` (contract C2, E's half) β€” this exists for the connector's own
76
+ #: batch calls, and the gate asserts the two agree rather than trusting that they do.
77
+ TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
78
+
79
+
80
+ def tt_profile_url(handle):
81
+ """`nurilab` β†’ `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
82
+ h = str(handle or "").strip().lstrip("@")
83
+ return TT_PROFILE_URL.format(handle=h) if h else ""
84
+
85
+
86
+ # ---------------------------------------------------------------------------------------------
87
+ # THE FIELD MAPS
88
+ # ---------------------------------------------------------------------------------------------
89
+ # Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
90
+ # in `automation_engine`. The rules they all obey, stated once:
91
+ #
92
+ # * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
93
+ # so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
94
+ # returns `None` (never 0) when nothing matches, which is what makes that possible.
95
+ # * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
96
+ # rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
97
+ # * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
98
+ # vendor's side is preserved rather than silently discarded while our column model catches up.
99
+ # * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
100
+ # (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
101
+ # ride in `source_payload` where they make no claim.
102
+
103
+
104
+ def _tt_str(node, *names):
105
+ """The first non-empty string among `names`, or None when the vendor sent nothing.
106
+
107
+ β›” `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest β€”
108
+ an empty string written into a cell claims "we looked and it is empty".
109
+ """
110
+ v = _first(node, *names)
111
+ if v is None:
112
+ return None
113
+ s = str(v).strip()
114
+ return s or None
115
+
116
+
117
+ def _tt_pct(node, *names):
118
+ """A vendor 0–1 engagement fraction β†’ our stored 0–100 percentage, or None.
119
+
120
+ β›” THE Γ—100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
121
+ the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` β€”
122
+ measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
123
+ """
124
+ v = _first(node, *names)
125
+ if v is None:
126
+ return None
127
+ out = engine._pct100(v)
128
+ return out or None
129
+
130
+
131
+ def _tt_day(node, *names):
132
+ """A vendor stamp β†’ `YYYY-MM-DD`, or None. Our `date` columns store a day."""
133
+ v = _first(node, *names)
134
+ if v is None:
135
+ return None
136
+ return engine._day(v) or None
137
+
138
+
139
+ def _drop_blanks(row):
140
+ """The one place a mapped row loses its `None`s β€” see the BLANK MEANS NOT READ rule above."""
141
+ return {k: v for k, v in row.items() if v is not None and v != ""}
142
+
143
+
144
+ def normalize_profile(node, handle=""):
145
+ """A TikTok Profiles row β†’ the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
146
+
147
+ ⚠ TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
148
+ * `biography` is PRIMARY and `signature` the FALLBACK β€” the probe measured `signature`
149
+ populated on 85% of rows and they carry the same text;
150
+ * `region` is PRIMARY and `country` the FALLBACK β€” `region` is the one with a documented
151
+ two-letter-ISO description, `country` has no description at all.
152
+ ⚠ `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
153
+ `ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
154
+ only count of its kind the dataset offers.
155
+ """
156
+ node = node if isinstance(node, dict) else {}
157
+ account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
158
+ return _drop_blanks({
159
+ "platform": engine.PLATFORM_TIKTOK,
160
+ "handle": account,
161
+ "full_name": _tt_str(node, "nickname"),
162
+ "tt_id": _tt_str(node, "id"),
163
+ "profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
164
+ "bio": _tt_str(node, "biography", "signature"),
165
+ "external_url": _bd_first_url(_first(node, "bio_link")),
166
+ "verified": _bd_flag(node, "is_verified"),
167
+ "is_private": _bd_flag(node, "is_private"),
168
+ # ⚠ APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
169
+ # on their own description. It is the closest thing TikTok has to Instagram's
170
+ # `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent β€” so
171
+ # the approximation only ever fills a cell the vendor actually answered.
172
+ "is_business": _bd_flag(node, "is_commerce_user"),
173
+ "followers": _ig_int(_first(node, "followers")),
174
+ "following": _ig_int(_first(node, "following")),
175
+ "posts_count": _ig_int(_first(node, "videos_count")),
176
+ # ⚠ `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
177
+ # nulls). It is not a post-level number and it is not our `likes` column, which is why it
178
+ # is stored under a different name.
179
+ "likes_received": _ig_int(_first(node, "likes")),
180
+ "avg_engagement": _tt_pct(node, "awg_engagement_rate"),
181
+ "like_engagement": _tt_pct(node, "like_engagement_rate"),
182
+ "comment_engagement": _tt_pct(node, "comment_engagement_rate"),
183
+ "country_code": _tt_str(node, "region", "country"),
184
+ "region": _tt_str(node, "region"),
185
+ "predicted_lang": _tt_str(node, "predicted_lang"),
186
+ # ⚠ ACCOUNT AGE, NOT A MEASUREMENT STAMP β€” `create_time` on a profile is when the ACCOUNT
187
+ # was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
188
+ # which is why the append law dates a snapshot by when WE read it.
189
+ "account_created_at": _tt_day(node, "create_time"),
190
+ "source_payload": _bd_source_payload(node),
191
+ })
192
+
193
+
194
+ def tt_post_type(node):
195
+ """A TikTok post row β†’ one of OUR three type options, or None.
196
+
197
+ β›” THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
198
+ `"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
199
+ vendor's token would fail `_clean_field`'s option check on the way in and would put an
200
+ untranslated API word in front of a user on the way out.
201
+
202
+ So: `video` is `video`, and `content` β€” TikTok's photo-mode post β€” is `image`, EXCEPT when the
203
+ row carries more than one `carousel_images` entry, which is what a carousel IS on either
204
+ network. ⚠ The multi-image branch is decided from the IMAGES, never from the type token: the
205
+ token cannot express it, so inferring `carousel` from the word would be inventing a fact.
206
+ ⚠ An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
207
+ that is exactly what would make the wrong default invisible).
208
+ """
209
+ raw = str((node or {}).get("post_type") or "").strip().lower()
210
+ if raw == TT_POST_TYPE_VIDEO:
211
+ return "video"
212
+ if raw != TT_POST_TYPE_CONTENT:
213
+ return None
214
+ images = (node or {}).get("carousel_images")
215
+ return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
216
+
217
+
218
+ def normalize_post(node):
219
+ """A TikTok Posts row β†’ the `ut_tt_posts` cell shape. None when it carries no identity.
220
+
221
+ β›” THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
222
+ Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
223
+ fact β€” `play_count` IS the count TikTok displays under a video β€” so it maps to `views` and
224
+ `ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
225
+ manufacture a second measurement that a rollup could average or double-count, which is a worse
226
+ outcome than the missing column it would paper over.
227
+
228
+ ⚠ `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
229
+ the probe measured them as the same shape. That equality is what lets the comments→posts link
230
+ join with NO normaliser, which the Instagram side never had.
231
+ ⚠ `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
232
+ ⚠ `commerce_info` is a business/commerce LOCATION per its own description β€” cities and
233
+ countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
234
+ no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
235
+ """
236
+ node = node if isinstance(node, dict) else {}
237
+ shortcode = _tt_str(node, "shortcode", "post_id")
238
+ if not shortcode:
239
+ return None
240
+ return _drop_blanks({
241
+ "platform": engine.PLATFORM_TIKTOK,
242
+ "shortcode": shortcode,
243
+ # β›”β›” `account_id`, NOT `profile_username` β€” MEASURED on a real Posts row 2026-08-12.
244
+ # The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
245
+ # @handle (`"d1na_th"`) β€” the same field `normalize_profile` already reads for `handle`, so
246
+ # one name means one thing across both corpora. Reading the display name silently broke the
247
+ # only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
248
+ # NOTHING, so a person could not filter posts by creator and a rollup would count zero.
249
+ # ⚠ NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
250
+ # different fact, and filling a join key with it is worse than leaving it blank β€” a blank
251
+ # is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
252
+ # The URL is the honest second source: it carries the handle by construction.
253
+ "influencer_key": (_tt_str(node, "account_id")
254
+ or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
255
+ "posted_at": _tt_day(node, "create_time"),
256
+ "type": tt_post_type(node),
257
+ "caption": _tt_str(node, "description"),
258
+ "url": _tt_str(node, "url"),
259
+ "hashtags": _bd_list(node, "hashtags"),
260
+ "tagged_location": _tt_str(node, "commerce_info"),
261
+ "views": _ig_int(_first(node, "play_count")),
262
+ "likes": _ig_int(_first(node, "digg_count")),
263
+ "comments": _ig_int(_first(node, "comment_count")),
264
+ "shares": _ig_int(_first(node, "num_share_count")),
265
+ "saves": _ig_int(_first(node, "collect_count")),
266
+ "video_duration": _ig_int(_first(node, "video_duration")),
267
+ "source_payload": _bd_source_payload(node),
268
+ })
269
+
270
+
271
+ def normalize_comment(node):
272
+ """A TikTok Comments row β†’ the `ut_tt_comments` cell shape. None without a comment id.
273
+
274
+ ⚠ THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
275
+ `replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
276
+ `source_payload`. Reading the array's length instead would be a second, disagreeing answer to
277
+ a question the vendor already answers β€” and it would disagree, because a page of replies is not
278
+ all of them.
279
+ ⚠ `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
280
+ text and needs defensive parsing. It still goes through `_tt_day` β€” one date path, so a vendor
281
+ that changes its mind cannot change ours.
282
+ ⚠ The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
283
+ PII) stay in `source_payload` and are promoted to no column, which is the same posture the
284
+ Instagram comment schema takes for the same D-24 reason.
285
+ """
286
+ node = node if isinstance(node, dict) else {}
287
+ comment_key = _tt_str(node, "comment_id")
288
+ if not comment_key:
289
+ return None
290
+ return _drop_blanks({
291
+ "platform": engine.PLATFORM_TIKTOK,
292
+ "comment_key": comment_key,
293
+ "shortcode": _tt_str(node, "post_id"),
294
+ # ⭐⭐ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
295
+ # vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
296
+ # primary first, so a row carrying the rich form is not silently served the plain one.
297
+ # β›” The commenter's identity is deliberately NOT promoted β€” see `TT_COMMENT_FIELDS`.
298
+ "text": _tt_str(node, "comment_text", "comment_text_only"),
299
+ "commented_at": _tt_day(node, "date_created"),
300
+ "likes": _ig_int(_first(node, "num_likes")),
301
+ "replies": _ig_int(_first(node, "num_replies")),
302
+ "source_payload": _bd_source_payload(node),
303
+ })
304
+
305
+
306
+ #: ⭐ The three maps, addressable by name β€” so a gate (and the runners in T04-T06) can walk them
307
+ #: rather than naming three functions, and so adding a fourth dataset is one entry.
308
+ TT_NORMALIZERS = {
309
+ "tt_profile": normalize_profile,
310
+ "tt_post_metrics": normalize_post,
311
+ "tt_comments": normalize_comment,
312
+ }
313
+
314
+
315
+ # ---------------------------------------------------------------------------------------------
316
+ # THE FETCH β€” wave 30 Β· W30-T08 (carrying wave-29's dropped T05)
317
+ # ---------------------------------------------------------------------------------------------
318
+
319
+ def tt_handle(url):
320
+ """A TikTok profile URL **or** a bare handle β†’ the handle. `''` when it is neither.
321
+
322
+ Deliberately permissive about the input and strict about the output, because the two callers
323
+ hand it different things: an automation stores whatever a person typed in the profile column
324
+ (`@nurilab`, `nurilab`, or the full URL), while the discovery runner already holds a clean
325
+ `account_id`. One normaliser, so a row found by discovery and a row typed by hand cannot
326
+ resolve to two different handles.
327
+ """
328
+ s = str(url or "").strip()
329
+ if not s:
330
+ return ""
331
+ if "tiktok.com" in s.lower():
332
+ # Everything after the first `@`, up to the next path segment or query.
333
+ tail = s.split("@", 1)[1] if "@" in s else ""
334
+ s = tail.split("/")[0].split("?")[0].split("#")[0]
335
+ s = s.strip().lstrip("@").strip()
336
+ # A handle is the vendor's `account_id` shape: alphanumerics, dots and underscores.
337
+ return s if s and all(c.isalnum() or c in "._" for c in s) else ""
338
+
339
+
340
+ def tt_post_urls(node, limit=0):
341
+ """⭐ WAVE 30 Β· T10 β€” the profile row's own post permalinks, newest-first as the vendor sends.
342
+
343
+ β›” THIS IS WHY TIKTOK POST CAPTURE COSTS NO EXTRA DISCOVERY. `top_videos` rides the PROFILE row
344
+ we have already bought, so the posts read is a scrape of links we hold, never a search for them.
345
+ The two TikTok DISCOVERY datasets (posts-by-profile, posts-by-keyword) are **404 for our key**,
346
+ so a design that reached for either would not merely be dearer, it would not work.
347
+
348
+ β›”β›” CORRECTED 2026-08-12 β€” THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
349
+ array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
350
+ read `/datasets/{id}/metadata` β€” a DATASET description β€” and the phrase quoted was the field's
351
+ `ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
352
+ (measured below), so the reader built against the quoted sentence found nothing, forever, in
353
+ silence. ⭐ The transferable half: *"the probe measured X"* and *"the probe read a declaration
354
+ of X"* are different claims, and prose cannot be told apart by a reader downstream β€” which is
355
+ why the correction names the method, not just the value.
356
+
357
+ ⚠ `top_posts_data` is deliberately NOT read: the probe calls it *"a thin dup of `top_videos`"*,
358
+ and preferring whichever happened to be longer is how one creator's window silently differs
359
+ from another's.
360
+ ⚠ `limit <= 0` means "everything the row carried". The CAP IS THE CALLER'S β€” `config.maxPosts`,
361
+ validated 1..12 β€” and it is applied here rather than after the scrape so an unwanted post is
362
+ never bought. [[a-constant-two-features-share]]: the 12 is the vendor's measured profile window,
363
+ not a number this function may invent.
364
+ """
365
+ raw = (node or {}).get("top_videos")
366
+ out = []
367
+ for item in raw if isinstance(raw, list) else []:
368
+ # β›”β›” MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
369
+ # `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
370
+ # live handle returns **19 DICTS**, keyed
371
+ # `video_url Β· video_id Β· playcount Β· diggcount Β· commentcount Β· share_count Β·
372
+ # favorites_count Β· create_date Β· cover_image`.
373
+ # The docstring above cites the $0 probe as having "measured" permalinks β€” it had not, and
374
+ # could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
375
+ # so in terms (*"what $0 cannot buy … the real ROW shape … that a declared field
376
+ # POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
377
+ # declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
378
+ # the first. [[reachable-is-not-the-same-as-built]]
379
+ # β‡’ The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
380
+ # list on every real profile β€” post capture could not have worked for anybody, and the
381
+ # T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
382
+ # written from a schema tests the schema.
383
+ # ⚠ `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
384
+ # because it costs nothing and is what a future corpus revision would most likely use. The
385
+ # bare-string branch stays for the same reason β€” this widens what is ACCEPTED and invents
386
+ # nothing: a shape that yields no `http…` value still degrades to "no posts", exactly as
387
+ # before, rather than to a URL built out of a guess.
388
+ # ⚠ `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
389
+ # whichever array happened to be longer is how one creator's window silently differs from
390
+ # another's, and that reasoning is unchanged by this correction.
391
+ if isinstance(item, dict):
392
+ u = str(item.get("video_url") or item.get("url") or "").strip()
393
+ else:
394
+ u = str(item or "").strip()
395
+ if u.lower().startswith("http") and u not in out:
396
+ out.append(u)
397
+ return out[:limit] if limit and limit > 0 else out
398
+
399
+
400
+ def pull_posts_tt(post_urls, log=print, deferred=None):
401
+ """The TikTok Posts dataset for a list of permalinks β†’ `(rows, note)`, already normalised.
402
+
403
+ ⚠ ONE CALL FOR THE WHOLE WINDOW. `bd_scrape` has always taken a list, and the Instagram side
404
+ measured what happens when a caller forgets: 25 records, one billed snapshot each, a walk still
405
+ running at 67 minutes. Nothing here loops per URL.
406
+ """
407
+ urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
408
+ if not urls:
409
+ return [], ""
410
+ rows, note = bd_scrape(TT_DS_POSTS, urls, deferred=deferred)
411
+ if note:
412
+ log(f"[aios-tt] posts: {note}")
413
+ return [], note
414
+ out = [r for r in (normalize_post(n) for n in rows) if r]
415
+ return out, ""
416
+
417
+
418
+ def pull_comments_tt(post_urls, log=print, deferred=None):
419
+ """The TikTok Comments dataset for a list of POST permalinks β†’ `(rows, note)`, normalised.
420
+
421
+ β›” THE MOST EXPENSIVE THING THIS PRODUCT BUYS, and the reason `commentMetrics` defaults OFF on
422
+ both networks: a comments scrape ingests identifiable third parties who never entered anybody's
423
+ list (D-24). The mapper already keeps every commenter field in `source_payload` and promotes
424
+ none of them to a column; this function adds no new exposure, it just has to be asked for.
425
+ """
426
+ urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
427
+ if not urls:
428
+ return [], ""
429
+ rows, note = bd_scrape(TT_DS_COMMENTS, urls, deferred=deferred)
430
+ if note:
431
+ log(f"[aios-tt] comments: {note}")
432
+ return [], note
433
+ out = [r for r in (normalize_comment(n) for n in rows) if r]
434
+ return out, ""
435
+
436
+
437
+ #: ⭐⭐ WAVE 30 Β· D-156 β€” THE MEDIA DATASETS, AS A SET, SO THE HAND-OFF CAN FILTER ON IDENTITY.
438
+ #: `_media_deferrals` uses this to lift ONLY posts/comments snapshots out of the local deferral
439
+ #: list. That is what makes it structurally impossible to file a PROFILE snapshot in the engine's
440
+ #: metric queue β€” the defect a draft of T10 shipped and A-39 booked as "the wrong fix is worse
441
+ #: than the gap". A membership test cannot be got wrong by a later edit the way `if` order can.
442
+ TT_MEDIA_DATASETS = (TT_DS_POSTS, TT_DS_COMMENTS)
443
+
444
+
445
+ def _media_deferrals(deferred):
446
+ """The POSTS/COMMENTS entries of a `bd_scrape` deferral list β€” never the profile's.
447
+
448
+ ⚠ The engine, not this module, decides what a deferral MEANS: it stamps `kind` and the
449
+ handle and files it. TikTok needs no `_tag_metric_deferrals` twin because one dataset is one
450
+ kind here, so the id already carries everything a mapper choice depends on β€” and importing
451
+ Instagram's tagger is not available anyway (W30-T09 gates ZERO `from connectors_ig` lines).
452
+ """
453
+ out = []
454
+ for d in deferred or []:
455
+ if isinstance(d, dict) and str(d.get("datasetId") or "") in TT_MEDIA_DATASETS:
456
+ out.append(dict(d))
457
+ return out
458
+
459
+
460
+ def pull_profile_tt(url, log=print, pending_profile=None, prefetch=None,
461
+ max_posts=0, post_metrics=False, comment_metrics=False):
462
+ """ONE TikTok profile from the vendor. Same return contract as `pull_profile`.
463
+
464
+ `{state, profile, posts, comments, via, note}` with `state ∈ ok | partial | blocked | error`,
465
+ so the engine's enrich branch treats every network identically and no caller learns a new
466
+ shape.
467
+
468
+ ⭐ WAVE 30 Β· T10 β€” POSTS AND COMMENTS ARE REAL NOW, AND BOTH DEFAULT OFF, exactly as Instagram's
469
+ do. `post_metrics` scrapes the profile row's own `top_videos` permalinks (see `tt_post_urls` β€”
470
+ no discovery call, because both TikTok discovery datasets 404 for our key); `comment_metrics`
471
+ then scrapes the comments of the posts that came back. ⚠ COMMENTS REQUIRE POSTS by construction
472
+ rather than by a rule: their input IS a post permalink, so asking for comments with post capture
473
+ off is a request with no subject, and it returns none instead of quietly buying posts nobody
474
+ asked for.
475
+
476
+ β›” `partial` IS THE SUCCESS STATE WHENEVER NO MEDIA WAS READ, and that is deliberate rather than
477
+ pessimistic. The Instagram contract reads `ok` only when identity AND media both landed
478
+ (`pull_profile_bd`: *"identity without media is still partial ... a run that wrote a follower
479
+ count and no posts must not paint green over a posts table that did not grow"*). So: posts not
480
+ ASKED for β†’ `partial`, saying so; posts asked for and landed β†’ `ok`; asked for and none came β†’
481
+ `partial` with the vendor's reason. The state answers "did this pull deliver what it went for",
482
+ never "did the function finish".
483
+
484
+ ⚠ **NO FREE RUNG, AND NO FALLBACK CHAIN.** Instagram's `pull_profile` drops to Apify when the
485
+ paid rung refuses; `providers.DEFAULT_CHAINS["tt_profile"]` is deliberately single-provider,
486
+ with its own note explaining that a multi-provider chain is a promise something walks it and
487
+ that nothing walks Instagram's second name today either. So a refusal here is final, and it
488
+ says so instead of implying a retry somewhere.
489
+ """
490
+ handle = tt_handle(url)
491
+ if not handle:
492
+ return {"state": "error", "profile": {}, "posts": [], "comments": [], "via": "",
493
+ "note": f"{url!r} is not a TikTok profile URL or handle"}
494
+
495
+ # ⭐ THE BATCH FAST PATH, same shape as the Instagram side: `prefetch` is `{handle: node}` from
496
+ # one multi-URL scrape covering a whole selection. A hit is a vendor round trip that does not
497
+ # happen; a miss falls through to the single-URL call below.
498
+ cached = prefetch.get(handle) if isinstance(prefetch, dict) else None
499
+ _deferred = []
500
+ if isinstance(cached, dict) and cached:
501
+ rows, note = [cached], ""
502
+ else:
503
+ rows, note = bd_scrape(TT_DS_PROFILES, [tt_profile_url(handle)], deferred=_deferred)
504
+
505
+ node = rows[0] if rows else {}
506
+ profile = normalize_profile(node, handle) if node else {}
507
+ # β›” THE READABILITY TEST IS `followers`/`following`, NOT "did we get a dict". `normalize_profile`
508
+ # drops blanks, so an unreadable row still returns `{"platform": …, "handle": …}` β€” truthy, and
509
+ # carrying nothing anybody asked for. The Instagram rung tests exactly this pair for exactly
510
+ # this reason, and answering "0 followers" instead is the failure it exists to prevent.
511
+ unreadable = profile.get("followers") is None and profile.get("following") is None
512
+ if note or unreadable:
513
+ # ⭐ THE DEFERRAL IS HANDED OVER RATHER THAN DISCARDED. A snapshot the vendor is still
514
+ # building HAS ALREADY BEEN PAID FOR; dropping its id bills again on the next run for the
515
+ # same record. That was live on the Instagram profile path until 2026-08-09 β€” measured on
516
+ # nurilab as two runs, two fresh snapshots, both abandoned β€” and it is not being
517
+ # reintroduced here by omission.
518
+ if isinstance(pending_profile, list):
519
+ for d in _deferred:
520
+ pending_profile.append({**d, "kind": "profile", "influencer": handle})
521
+ why = note or ("the scrape answered, but no follower/following counts were readable in it "
522
+ "(the field names may have moved - see tiktok-capture.md)")
523
+ return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
524
+ "deferredProfile": [d.get("snapshotId") for d in _deferred],
525
+ "note": why}
526
+
527
+ # --- W30-T10: THE MEDIA, ONLY WHEN IT WAS ASKED FOR. ------------------------------------
528
+ if not post_metrics:
529
+ return {"state": "partial", "profile": profile, "posts": [], "comments": [],
530
+ "via": "brightdata",
531
+ "note": note or "profile read; post capture is off for this step"}
532
+ urls = tt_post_urls(node, limit=max_posts)
533
+ if not urls:
534
+ # ⚠ NOT AN ERROR AND NOT A RETRY. A creator with no `top_videos` has nothing to buy, and
535
+ # saying so is what stops the next run paying to be told the same thing.
536
+ return {"state": "partial", "profile": profile, "posts": [], "comments": [],
537
+ "via": "brightdata",
538
+ "note": note or "profile read; this account's row carried no post links"}
539
+ posts, p_note = pull_posts_tt(urls, log=log, deferred=_deferred)
540
+ comments, c_note = ([], "")
541
+ if comment_metrics and posts:
542
+ # The comments dataset is keyed on a POST permalink, so it reads the posts we just bought β€”
543
+ # `url` from the mapper, never the profile's raw array, so a post the posts scrape refused
544
+ # is not silently asked about again one rung later.
545
+ comments, c_note = pull_comments_tt([p.get("url") for p in posts if p.get("url")],
546
+ log=log, deferred=_deferred)
547
+ # ⭐⭐ WAVE 30 Β· D-156 β€” THE MEDIA DEFERRALS ARE HANDED BACK, and the shape of the hand-off is
548
+ # the whole lesson. An earlier draft of T10 appended every `_deferred` entry to
549
+ # `pending_profile` tagged `kind: "profile"`. By the time control reaches here a PROFILE
550
+ # deferral is impossible β€” the profile branch above returns `blocked` on any note β€” so **every
551
+ # id fanned out that way was a POSTS or COMMENTS snapshot in the PROFILE queue**, whose
552
+ # collector writes preset profile cells onto somebody's record from post rows. The engine keeps
553
+ # the two queues apart deliberately (`_pending_profile_tasks` vs `_pending_metric_tasks`).
554
+ # β‡’ So this returns them under their OWN key, filtered by dataset identity
555
+ # (`_media_deferrals`), and the engine files them in the metric queue with the handle it
556
+ # already holds. Returning rather than appending also keeps the queue's vocabulary out of a
557
+ # connector: this module knows which CORPUS deferred, never what the engine calls it.
558
+ # ⚠ `deferredMedia` rides BOTH returns on purpose. The empty-posts case is the one that
559
+ # matters most β€” that is exactly the run where the vendor took too long, so a caller reading
560
+ # the ids only from the success path would lose every batch it actually paid for.
561
+ deferred_media = _media_deferrals(_deferred)
562
+ if not posts:
563
+ return {"state": "partial", "profile": profile, "posts": [], "comments": [],
564
+ "via": "brightdata", "deferredMedia": deferred_media,
565
+ "note": p_note or note or "profile read; the post source returned nothing"}
566
+ return {"state": "ok", "profile": profile, "posts": posts, "comments": comments,
567
+ "via": "brightdata", "deferredMedia": deferred_media,
568
+ "note": c_note or note or ""}
api/providers.py CHANGED
The diff for this file is too large to render. See raw diff
 
api/routes_agent_harness.py CHANGED
@@ -1,455 +1,455 @@
1
- """routes_agent_harness.py β€” CONTRACT C4: the agent's HARNESS, kept as versioned files.
2
-
3
- Owner item 3, verbatim (2026-08-18): *"This new module under agent is supposed to host any file
4
- pertaining to the agent skills, router etc. So we build a user can build a custom harness for each
5
- agent through the chat interface."*
6
-
7
- GET /api/v1/agents/{id}/harness the file LIST (no bodies)
8
- GET /api/v1/agents/{id}/harness?path=… one file: current body + its versions
9
- GET /api/v1/agents/{id}/harness?path=…&version=N one older body, verbatim
10
- PUT /api/v1/agents/{id}/harness write a NEW version of one file
11
- DELETE /api/v1/agents/{id}/harness?path=… drop a file and its history
12
-
13
- ⭐⭐ **R8 IS THE WHOLE SHAPE: BOTH PRINCIPALS WRITE, AND NOTHING IS EVER OVERWRITTEN.** A write
14
- appends a version; a roll-back is a write of an older body (`restoredFrom`), never a delete. So the
15
- history is a record of what happened rather than of what somebody last wanted it to look like.
16
-
17
- β›” **R8 IS DELIBERATELY NOT R9.** An agent-authored ACTION's configuration is agent-only (item 8,
18
- `routes_automation`); a harness file is not. Do not copy this file's posture over there or that
19
- one's over here β€” the two rulings differ on purpose and they sit one screen apart in the product.
20
-
21
- ⚠ **`author` IS THE SESSION, `authorKind` IS THE PROVENANCE, AND THEY ARE DIFFERENT FACTS.** Every
22
- write through this router is made BY a signed-in administrator, so `author` is stamped from the
23
- session and can never be supplied by the caller. `authorKind` says whether the BODY was drafted by
24
- a person or by the agent in the chat β€” a claim the client is entitled to make, because both are
25
- permitted (R8) and so nothing is bought by forging it. `record_version()` below is the server-side
26
- door the automation engine uses when the agent writes with no session at all; that one stamps the
27
- agent's own id as the author, which is the only case where `author` is not a username.
28
-
29
- β›” **THE VERSION LIST IS CAPPED AND THE CAP IS REPORTED, NEVER SILENT.** `MAX_VERSIONS` versions of
30
- one file are kept; past that the OLDEST are dropped and the count of what was dropped rides in
31
- `trimmed` on every payload that mentions the file, so a reader can see that the history is partial
32
- rather than infer that the file was only ever saved twice. This is the tenant document, which is
33
- already 28.6 MB on tenant #0 and is deep-copied on every read: an unbounded per-agent history is
34
- a store-sized leak with a UI in front of it.
35
- """
36
- from datetime import datetime, timezone
37
-
38
- from fastapi import APIRouter, Body, Depends
39
-
40
- from deps import Session, err, require_session
41
-
42
- router = APIRouter(prefix="/api/v1")
43
-
44
- #: The tenant's harness files: `{agent_id: {path: file_record}}`. A per-tenant bucket, so it rides
45
- #: `runtime.store_key`'s prefix and never lands in tenant #0's namespace β€” the same rule
46
- #: `routes_slack.AGENTS_KEY` follows for the agent records these hang off.
47
- HARNESS_KEY = "agent_harness"
48
-
49
- #: One body. Generous for a skill or a router file and far under the point where a single write
50
- #: would move the tenant document measurably. A larger body is a REFUSAL at the door, not a
51
- #: truncation: a silently truncated skill file is a harness that does not do what its text says.
52
- MAX_BODY_BYTES = 128 * 1024
53
-
54
- #: Files per agent. A refusal, not a trim β€” creating the 65th file is a different act from saving
55
- #: the 101st version of one, and only the second can be a routine consequence of ordinary editing.
56
- MAX_FILES = 64
57
-
58
- #: Versions kept per file. Past this the oldest go and `trimmed` counts them (see the header).
59
- MAX_VERSIONS = 100
60
-
61
- MAX_PATH = 200
62
-
63
- #: What a path may contain. β›” THIS IS NOT A FILESYSTEM PATH AND NOTHING HERE EVER TOUCHES A DISK β€”
64
- #: the "files" are keys in a store bucket. The character rule exists so the key is displayable, is
65
- #: safe to put in a URL, and cannot carry a traversal sequence that would look meaningful to a
66
- #: future reader who assumes it IS a filesystem path. Fail-closed on the character set, not on a
67
- #: list of forbidden sequences: an allow-list cannot be walked around by a spelling.
68
- _PATH_OK = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-/")
69
-
70
- AUTHOR_KINDS = ("user", "agent")
71
-
72
-
73
- def _now():
74
- return datetime.now(timezone.utc).isoformat(timespec="seconds")
75
-
76
-
77
- def _all(rt):
78
- """`{agent_id: {path: record}}` for one tenant. `{}` on any failure β€” an unreadable bucket must
79
- degrade to "this agent has no harness files", never to a 500 on the pane that lists them."""
80
- try:
81
- found = rt.get(HARNESS_KEY) or {}
82
- except Exception: # noqa: BLE001
83
- return {}
84
- return found if isinstance(found, dict) else {}
85
-
86
-
87
- def _files(rt, agent_id):
88
- found = _all(rt).get(str(agent_id))
89
- return found if isinstance(found, dict) else {}
90
-
91
-
92
- #: What kind of principal an id names. `None` = this tenant has no agent with that id.
93
- #:
94
- #: β›”β›” THERE ARE TWO AGENT REGISTRIES IN THIS PRODUCT AND THE FIRST DRAFT OF THIS FILE KNEW ONLY
95
- #: ONE (ASK D-5, 2026-08-18). `routes_slack._agents` is the per-Slack-channel permission wall under
96
- #: Manage users. The **Agents module** the owner's item 3 is about is the AUTOMATION surface β€”
97
- #: `Shell.tsx` mounts `<Lazily surface="Agents"><AutomationSurface /></Lazily>`, and
98
- #: `AutomationDetail`'s `panelTabs` is literally the `Properties | Run history` strip R7 adds
99
- #: "Harness" to. Keyed on the Slack bucket alone, every `GET/PUT /agents/{id}/harness` from that
100
- #: tab would have answered **404 no_agent**: whole, gate-green and dead on arrival
101
- #: [[reachable-is-not-the-same-as-built]]. Verified independently before acting, not taken on
102
- #: report: `surface="Agents"` mounts `AutomationSurface`, and `ManageAgentPane` contains ZERO
103
- #: occurrences of Canvas, Properties, Run history or panelTabs.
104
- #:
105
- #: ⭐ ONE STORE, BOTH PRINCIPALS β€” never a second bucket keyed by surface. The owner's "agent
106
- #: skills, router" files in two places is the parallel code path item 13 exists to refuse.
107
- AGENT_SLACK = "slack"
108
- AGENT_AUTOMATION = "automation"
109
-
110
-
111
- def agent_kind(rt, agent_id):
112
- """Which registry holds this id β€” `AGENT_SLACK`, `AGENT_AUTOMATION`, or `None`.
113
-
114
- ⚠ A SYNTHETIC ROW IS NOT AN AGENT FOR THIS PURPOSE. `field:` and `system:` ids are DERIVED at
115
- read time from a column definition or a connector schedule; they have no stored home, so a
116
- harness file hung off one is an orphan the moment the column changes. `patch_automation`
117
- already refuses those ids for the neighbouring reason, and this refuses them by simply not
118
- finding them β€” `all_definitions` holds stored automations only.
119
- """
120
- import routes_slack
121
- aid = str(agent_id or "")
122
- if isinstance(routes_slack._agents(rt).get(aid), dict):
123
- return AGENT_SLACK
124
- import automation_engine as engine
125
- try:
126
- known = engine.all_definitions(rt) or {}
127
- except Exception: # noqa: BLE001
128
- return None
129
- return AGENT_AUTOMATION if aid in known else None
130
-
131
-
132
- def _known_agent(rt, agent_id):
133
- """Does this tenant have an agent with this id, in EITHER registry?"""
134
- return agent_kind(rt, agent_id) is not None
135
-
136
-
137
- def agent_wall(session, agent_id):
138
- """404 for an unknown id, else apply the wall THAT PRINCIPAL'S OWN SURFACE applies.
139
-
140
- β›”β›” ONE DOOR, TWO WALLS, AND THAT IS NOT A SECOND CODE PATH β€” it is the refusal to invent a
141
- THIRD wall. A Slack channel agent is administered under Manage users and every `/agents/*` door
142
- in `routes_slack` is `admin_gate`; an automation lives in the Agents module and every door in
143
- `routes_automation` is `module_gate("automation")`. A harness file is configuration OF the
144
- agent it hangs off, so it is reached by whoever may already configure that agent. Picking one
145
- of the two walls for both would either lock the Agents module's own users out of a tab the
146
- owner asked for, or hand the Slack permission wall to anyone with an automation grant.
147
- """
148
- kind = agent_kind(session.runtime, agent_id)
149
- if kind is None:
150
- raise err(404, "no_agent", "there is no agent with that id in this workspace")
151
- if kind == AGENT_SLACK:
152
- import core.perms as perms
153
- if not perms.is_admin(session.user):
154
- raise err(403, "forbidden", "administrators only")
155
- else:
156
- session.require("automation")
157
- return kind
158
-
159
-
160
- def normalize_path(raw):
161
- """THE path rule, in ONE place. Returns the cleaned path, or `None` if it is not acceptable.
162
-
163
- β›”β›” ONE RULE, TWO DOORS, AND THAT IS WHY THIS IS A FUNCTION RATHER THAN TWO IF-BLOCKS. There
164
- are two ways into this store β€” the HTTP route (which must answer 400) and `record_version()`
165
- (which must raise `ValueError`, having no response to put a status into). Written twice, the
166
- two copies are [[one-question-two-normalizers]] waiting to happen: the first weakening of one
167
- copy is invisible because the other still refuses, so nothing goes red and the wall is now
168
- half there. Written once, a change to the rule is felt at both doors and by the gate.
169
- """
170
- path = str(raw or "").strip().strip("/")
171
- if not path or len(path) > MAX_PATH:
172
- return None
173
- if set(path) - _PATH_OK or ".." in path or "//" in path:
174
- return None
175
- return path
176
-
177
-
178
- def _clean_path(raw):
179
- """`normalize_path` at the HTTP door, where a refusal is a 400 with a reason."""
180
- path = normalize_path(raw)
181
- if path is None:
182
- if not str(raw or "").strip().strip("/"):
183
- raise err(400, "no_path", "a harness file needs a path, for example skills/router.md")
184
- if len(str(raw)) > MAX_PATH:
185
- raise err(400, "path_too_long", f"a harness path is at most {MAX_PATH} characters")
186
- raise err(400, "bad_path",
187
- "a harness path may use letters, digits, dot, dash, underscore and / only")
188
- return path
189
-
190
-
191
- def _blank(path, author, author_kind):
192
- return {"path": path, "versions": [], "trimmed": 0,
193
- "created": _now(), "createdBy": author, "createdKind": author_kind}
194
-
195
-
196
- def _append(record, body, author, author_kind, restored_from=None):
197
- """Append ONE version to a file record, in place, and report what was trimmed.
198
-
199
- The version NUMBER is monotonic and survives trimming β€” it counts writes, not stored entries.
200
- A version list whose numbers restart at 1 after a trim would make two different bodies share a
201
- name, and `restoredFrom` would then point at whichever one happened to be in the window.
202
- """
203
- # ⚠ A NEW LIST, NEVER `versions.append(...)` ON THE STORED ONE. `update()` hands the callback
204
- # the live document and may run it more than once; appending in place would then stack two
205
- # copies of the same version into the history on a retry.
206
- prior = record.get("versions") if isinstance(record.get("versions"), list) else []
207
- last = max((int(v.get("version") or 0) for v in prior if isinstance(v, dict)), default=0)
208
- entry = {"version": last + 1, "body": body, "author": author, "authorKind": author_kind,
209
- "created": _now(), "bytes": len(body.encode("utf-8"))}
210
- if restored_from:
211
- entry["restoredFrom"] = int(restored_from)
212
- versions = [*prior, entry]
213
- dropped = max(0, len(versions) - MAX_VERSIONS)
214
- if dropped:
215
- versions = versions[dropped:]
216
- record["versions"] = versions
217
- record["trimmed"] = int(record.get("trimmed") or 0) + dropped
218
- return entry
219
-
220
-
221
- def _head(record):
222
- """The newest version of a file record, or `None` for a record with no versions at all."""
223
- versions = record.get("versions") if isinstance(record.get("versions"), list) else []
224
- return versions[-1] if versions else None
225
-
226
-
227
- def _row(record):
228
- """One file, as the LIST door reports it: everything except the bodies.
229
-
230
- ⚠ NO BODY, AND THAT IS THE POINT. A list door that carried every version of every file would
231
- ship the whole harness on every pane render; the Harness tab lists first and opens one file
232
- second, which is exactly the shape this answers.
233
- """
234
- head = _head(record) or {}
235
- versions = record.get("versions") if isinstance(record.get("versions"), list) else []
236
- return {"path": record.get("path") or "",
237
- "version": int(head.get("version") or 0),
238
- "bytes": int(head.get("bytes") or 0),
239
- "author": head.get("author") or record.get("createdBy") or "",
240
- "authorKind": head.get("authorKind") or record.get("createdKind") or "user",
241
- "updated": head.get("created") or record.get("created") or "",
242
- "created": record.get("created") or "",
243
- "versions": len(versions),
244
- "trimmed": int(record.get("trimmed") or 0)}
245
-
246
-
247
- def _version_rows(record):
248
- """The history of one file, newest first, WITHOUT the bodies.
249
-
250
- A body per version is what makes a diff possible, and it is also what makes this payload big:
251
- 100 versions of a 128 KB file is 12 MB. The client asks for the two bodies it is diffing
252
- (`?path=…&version=N`), which is two round trips for a diff and none for a history list.
253
- """
254
- versions = record.get("versions") if isinstance(record.get("versions"), list) else []
255
- out = []
256
- for entry in reversed(versions):
257
- if not isinstance(entry, dict):
258
- continue
259
- row = {"version": int(entry.get("version") or 0),
260
- "author": entry.get("author") or "",
261
- "authorKind": entry.get("authorKind") or "user",
262
- "created": entry.get("created") or "",
263
- "bytes": int(entry.get("bytes") or 0)}
264
- if entry.get("restoredFrom"):
265
- row["restoredFrom"] = int(entry["restoredFrom"])
266
- out.append(row)
267
- return out
268
-
269
-
270
- def _limits():
271
- """The caps, IN the payload, so a client can say "this file is full" before a write fails.
272
-
273
- ⚠ A limit the client cannot see is a limit the user meets as an error. `trimmed` reports the
274
- one cap that acts without refusing; these report the three that refuse.
275
- """
276
- return {"maxBodyBytes": MAX_BODY_BYTES, "maxFiles": MAX_FILES,
277
- "maxVersions": MAX_VERSIONS, "maxPath": MAX_PATH}
278
-
279
-
280
- # ── the write door the SERVER uses (no session) ────────────────────────────────────────────────
281
- def record_version(runtime, agent_id, path, body, author="", author_kind="agent",
282
- restored_from=None):
283
- """Write one version from INSIDE the server β€” the agent's own half of R8.
284
-
285
- ⭐ THIS IS THE FUNCTION, NOT THE ROUTE, THAT MAKES "editable by BOTH the user and the agent"
286
- true. An agent acting inside an automation run holds no session and no cookie; if its only way
287
- to write were the HTTP door it would have to borrow a person's identity, and the authorship
288
- column would then be a record of who was logged in rather than of what wrote the file.
289
-
290
- Returns the appended entry. Raises nothing the caller cannot handle: an unknown agent is a
291
- `ValueError`, because a server-side caller has no HTTP response to put a 404 into.
292
- """
293
- agent_id = str(agent_id or "")
294
- if not _known_agent(runtime, agent_id):
295
- raise ValueError(f"no agent {agent_id!r} in this workspace")
296
- path = normalize_path(path)
297
- if path is None:
298
- raise ValueError("that is not an acceptable harness path")
299
- body = str(body or "")
300
- if len(body.encode("utf-8")) > MAX_BODY_BYTES:
301
- raise ValueError("harness body is over the size limit")
302
- kind = author_kind if author_kind in AUTHOR_KINDS else "agent"
303
- author = str(author or agent_id)
304
- # β›” THE FILE-COUNT CEILING IS CHECKED HERE, NOT INSIDE `_set`. An exception raised inside a
305
- # store `update` callback propagates out of a half-run read-modify-write, and the one thing a
306
- # refusal must never do is leave the caller unsure whether the write happened.
307
- existing = _files(runtime, agent_id)
308
- if path not in existing and len(existing) >= MAX_FILES:
309
- raise ValueError(f"this agent already has {MAX_FILES} harness files")
310
- appended = {}
311
-
312
- def _set(cur):
313
- cur = dict(cur or {})
314
- files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
315
- record = dict(files[path]) if isinstance(files.get(path), dict) else _blank(path, author, kind)
316
- appended.clear()
317
- appended.update(_append(record, body, author, kind, restored_from))
318
- files[path] = record
319
- cur[agent_id] = files
320
- return cur
321
-
322
- runtime.update(HARNESS_KEY, _set, flush="sync")
323
- return appended
324
-
325
-
326
- # ── the routes ────────────────────────────────────────────────────────────────────────────────
327
- @router.get("/agents/{agent_id}/harness")
328
- def get_harness(agent_id: str, path: str = "", version: int = 0,
329
- session: Session = Depends(require_session)):
330
- """The list, one file, or one older body β€” decided by the query string (C4).
331
-
332
- ⚠ ADMIN-GATED LIKE EVERY OTHER AGENT DOOR (`routes_slack`), and for a stronger reason than
333
- consistency: a harness file is what the agent is INSTRUCTED to do, so writing one is closer to
334
- editing a permission than to editing a document.
335
- """
336
- agent_id = str(agent_id or "")
337
- agent_wall(session, agent_id)
338
- files = _files(session.runtime, agent_id)
339
- if not path:
340
- rows = [_row(rec) for _p, rec in sorted(files.items()) if isinstance(rec, dict)]
341
- return {"agent": agent_id, "files": rows, "limits": _limits()}
342
-
343
- wanted = _clean_path(path)
344
- record = files.get(wanted)
345
- if not isinstance(record, dict):
346
- raise err(404, "no_file", f"this agent has no harness file at {wanted}")
347
- versions = record.get("versions") if isinstance(record.get("versions"), list) else []
348
- if version:
349
- for entry in versions:
350
- if isinstance(entry, dict) and int(entry.get("version") or 0) == int(version):
351
- return {"agent": agent_id, **_row(record), "body": entry.get("body") or "",
352
- "atVersion": int(version), "history": _version_rows(record),
353
- "limits": _limits()}
354
- # β›” A TRIMMED VERSION IS A NAMED REFUSAL, NOT A 404 SHAPED LIKE A TYPO. The client asked
355
- # for something that existed and no longer does, and telling it apart from a bad number is
356
- # the difference between "roll back to v3" failing loudly and failing as if v3 never was.
357
- trimmed = int(record.get("trimmed") or 0)
358
- if trimmed and int(version) <= trimmed:
359
- raise err(410, "version_trimmed",
360
- f"version {int(version)} is older than the {MAX_VERSIONS} versions kept "
361
- f"for this file, and its body is gone")
362
- raise err(404, "no_version", f"this file has no version {int(version)}")
363
- head = _head(record) or {}
364
- return {"agent": agent_id, **_row(record), "body": head.get("body") or "",
365
- "atVersion": int(head.get("version") or 0), "history": _version_rows(record),
366
- "limits": _limits()}
367
-
368
-
369
- @router.put("/agents/{agent_id}/harness")
370
- def put_harness(agent_id: str, body: dict = Body(default=None),
371
- session: Session = Depends(require_session)):
372
- """Write a NEW version of one harness file. `{path, body, authorKind?, restoredFrom?}` (C4).
373
-
374
- β›” THERE IS NO OVERWRITE HERE AND THERE IS NO EDIT-IN-PLACE. R8's "every version kept" is not a
375
- UI affordance; it is this function refusing to have a code path that replaces a body. A
376
- roll-back arrives as an ordinary write carrying `restoredFrom`, so the history records that
377
- somebody went back rather than pretending the intervening versions never happened.
378
- """
379
- agent_id = str(agent_id or "")
380
- agent_wall(session, agent_id)
381
- body = body if isinstance(body, dict) else {}
382
- path = _clean_path(body.get("path"))
383
- text = body.get("body")
384
- if not isinstance(text, str):
385
- raise err(400, "no_body", "a harness file needs a body, even an empty one")
386
- if len(text.encode("utf-8")) > MAX_BODY_BYTES:
387
- raise err(413, "body_too_long",
388
- f"a harness file is at most {MAX_BODY_BYTES // 1024} KB; this one is larger")
389
-
390
- # ⚠ THE CALLER DECLARES THE PROVENANCE AND THE SERVER STAMPS THE IDENTITY. `authorKind` is a
391
- # claim about who WROTE the text (the person, or the agent in the chat panel); `author` is the
392
- # session and is never read off the request. Nothing is bought by forging the first β€” both
393
- # principals may write (R8) β€” and everything would be bought by forging the second.
394
- kind = str(body.get("authorKind") or "user").strip().lower()
395
- if kind not in AUTHOR_KINDS:
396
- raise err(400, "bad_author_kind", "authorKind is either user or agent")
397
- restored = body.get("restoredFrom")
398
- try:
399
- restored = int(restored) if restored else None
400
- except (TypeError, ValueError):
401
- raise err(400, "bad_version", "restoredFrom must be a version number")
402
-
403
- files = _files(session.runtime, agent_id)
404
- if path not in files and len(files) >= MAX_FILES:
405
- raise err(409, "too_many_files",
406
- f"this agent already has {MAX_FILES} harness files; delete one to add another")
407
- try:
408
- record_version(session.runtime, agent_id, path, text,
409
- author=session.uname, author_kind=kind, restored_from=restored)
410
- except ValueError as exc:
411
- raise err(400, "refused", str(exc))
412
-
413
- fresh = _files(session.runtime, agent_id).get(path)
414
- if not isinstance(fresh, dict) or not _head(fresh):
415
- # The store took the write and did not record it. A 200 here would tell an administrator
416
- # their skill file was saved when it was not β€” the shape `routes_slack` refuses too.
417
- raise err(503, "store_unavailable", "the harness file was NOT saved")
418
- head = _head(fresh)
419
- return {"agent": agent_id, **_row(fresh), "body": head.get("body") or "",
420
- "atVersion": int(head.get("version") or 0), "history": _version_rows(fresh),
421
- "limits": _limits()}
422
-
423
-
424
- @router.delete("/agents/{agent_id}/harness")
425
- def delete_harness(agent_id: str, path: str = "", session: Session = Depends(require_session)):
426
- """Drop one harness file AND its history.
427
-
428
- ⚠ THIS IS NOT THE THING R8 FORBIDS. R8 forbids a ROLL-BACK implemented as a delete β€” losing
429
- versions as a side effect of an edit. Deleting a file is a person deciding the file should not
430
- exist, which is a different act with a different button, and a store with no way to remove a
431
- file is one where a typo'd path is permanent.
432
- """
433
- agent_id = str(agent_id or "")
434
- agent_wall(session, agent_id)
435
- wanted = _clean_path(path)
436
- if wanted not in _files(session.runtime, agent_id):
437
- raise err(404, "no_file", f"this agent has no harness file at {wanted}")
438
-
439
- def _set(cur):
440
- cur = dict(cur or {})
441
- files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
442
- files.pop(wanted, None)
443
- # An agent with no harness files leaves NO key behind. An empty dict per agent id is how a
444
- # bucket accumulates a row for every agent anybody ever opened the tab on.
445
- if files:
446
- cur[agent_id] = files
447
- else:
448
- cur.pop(agent_id, None)
449
- return cur
450
-
451
- session.runtime.update(HARNESS_KEY, _set, flush="sync")
452
- return {"agent": agent_id, "deleted": wanted,
453
- "files": [_row(rec) for _p, rec in sorted(_files(session.runtime, agent_id).items())
454
- if isinstance(rec, dict)],
455
- "limits": _limits()}
 
1
+ """routes_agent_harness.py β€” CONTRACT C4: the agent's HARNESS, kept as versioned files.
2
+
3
+ Owner item 3, verbatim (2026-08-18): *"This new module under agent is supposed to host any file
4
+ pertaining to the agent skills, router etc. So we build a user can build a custom harness for each
5
+ agent through the chat interface."*
6
+
7
+ GET /api/v1/agents/{id}/harness the file LIST (no bodies)
8
+ GET /api/v1/agents/{id}/harness?path=… one file: current body + its versions
9
+ GET /api/v1/agents/{id}/harness?path=…&version=N one older body, verbatim
10
+ PUT /api/v1/agents/{id}/harness write a NEW version of one file
11
+ DELETE /api/v1/agents/{id}/harness?path=… drop a file and its history
12
+
13
+ ⭐⭐ **R8 IS THE WHOLE SHAPE: BOTH PRINCIPALS WRITE, AND NOTHING IS EVER OVERWRITTEN.** A write
14
+ appends a version; a roll-back is a write of an older body (`restoredFrom`), never a delete. So the
15
+ history is a record of what happened rather than of what somebody last wanted it to look like.
16
+
17
+ β›” **R8 IS DELIBERATELY NOT R9.** An agent-authored ACTION's configuration is agent-only (item 8,
18
+ `routes_automation`); a harness file is not. Do not copy this file's posture over there or that
19
+ one's over here β€” the two rulings differ on purpose and they sit one screen apart in the product.
20
+
21
+ ⚠ **`author` IS THE SESSION, `authorKind` IS THE PROVENANCE, AND THEY ARE DIFFERENT FACTS.** Every
22
+ write through this router is made BY a signed-in administrator, so `author` is stamped from the
23
+ session and can never be supplied by the caller. `authorKind` says whether the BODY was drafted by
24
+ a person or by the agent in the chat β€” a claim the client is entitled to make, because both are
25
+ permitted (R8) and so nothing is bought by forging it. `record_version()` below is the server-side
26
+ door the automation engine uses when the agent writes with no session at all; that one stamps the
27
+ agent's own id as the author, which is the only case where `author` is not a username.
28
+
29
+ β›” **THE VERSION LIST IS CAPPED AND THE CAP IS REPORTED, NEVER SILENT.** `MAX_VERSIONS` versions of
30
+ one file are kept; past that the OLDEST are dropped and the count of what was dropped rides in
31
+ `trimmed` on every payload that mentions the file, so a reader can see that the history is partial
32
+ rather than infer that the file was only ever saved twice. This is the tenant document, which is
33
+ already 28.6 MB on tenant #0 and is deep-copied on every read: an unbounded per-agent history is
34
+ a store-sized leak with a UI in front of it.
35
+ """
36
+ from datetime import datetime, timezone
37
+
38
+ from fastapi import APIRouter, Body, Depends
39
+
40
+ from deps import Session, err, require_session
41
+
42
+ router = APIRouter(prefix="/api/v1")
43
+
44
+ #: The tenant's harness files: `{agent_id: {path: file_record}}`. A per-tenant bucket, so it rides
45
+ #: `runtime.store_key`'s prefix and never lands in tenant #0's namespace β€” the same rule
46
+ #: `routes_slack.AGENTS_KEY` follows for the agent records these hang off.
47
+ HARNESS_KEY = "agent_harness"
48
+
49
+ #: One body. Generous for a skill or a router file and far under the point where a single write
50
+ #: would move the tenant document measurably. A larger body is a REFUSAL at the door, not a
51
+ #: truncation: a silently truncated skill file is a harness that does not do what its text says.
52
+ MAX_BODY_BYTES = 128 * 1024
53
+
54
+ #: Files per agent. A refusal, not a trim β€” creating the 65th file is a different act from saving
55
+ #: the 101st version of one, and only the second can be a routine consequence of ordinary editing.
56
+ MAX_FILES = 64
57
+
58
+ #: Versions kept per file. Past this the oldest go and `trimmed` counts them (see the header).
59
+ MAX_VERSIONS = 100
60
+
61
+ MAX_PATH = 200
62
+
63
+ #: What a path may contain. β›” THIS IS NOT A FILESYSTEM PATH AND NOTHING HERE EVER TOUCHES A DISK β€”
64
+ #: the "files" are keys in a store bucket. The character rule exists so the key is displayable, is
65
+ #: safe to put in a URL, and cannot carry a traversal sequence that would look meaningful to a
66
+ #: future reader who assumes it IS a filesystem path. Fail-closed on the character set, not on a
67
+ #: list of forbidden sequences: an allow-list cannot be walked around by a spelling.
68
+ _PATH_OK = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-/")
69
+
70
+ AUTHOR_KINDS = ("user", "agent")
71
+
72
+
73
+ def _now():
74
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
75
+
76
+
77
+ def _all(rt):
78
+ """`{agent_id: {path: record}}` for one tenant. `{}` on any failure β€” an unreadable bucket must
79
+ degrade to "this agent has no harness files", never to a 500 on the pane that lists them."""
80
+ try:
81
+ found = rt.get(HARNESS_KEY) or {}
82
+ except Exception: # noqa: BLE001
83
+ return {}
84
+ return found if isinstance(found, dict) else {}
85
+
86
+
87
+ def _files(rt, agent_id):
88
+ found = _all(rt).get(str(agent_id))
89
+ return found if isinstance(found, dict) else {}
90
+
91
+
92
+ #: What kind of principal an id names. `None` = this tenant has no agent with that id.
93
+ #:
94
+ #: β›”β›” THERE ARE TWO AGENT REGISTRIES IN THIS PRODUCT AND THE FIRST DRAFT OF THIS FILE KNEW ONLY
95
+ #: ONE (ASK D-5, 2026-08-18). `routes_slack._agents` is the per-Slack-channel permission wall under
96
+ #: Manage users. The **Agents module** the owner's item 3 is about is the AUTOMATION surface β€”
97
+ #: `Shell.tsx` mounts `<Lazily surface="Agents"><AutomationSurface /></Lazily>`, and
98
+ #: `AutomationDetail`'s `panelTabs` is literally the `Properties | Run history` strip R7 adds
99
+ #: "Harness" to. Keyed on the Slack bucket alone, every `GET/PUT /agents/{id}/harness` from that
100
+ #: tab would have answered **404 no_agent**: whole, gate-green and dead on arrival
101
+ #: [[reachable-is-not-the-same-as-built]]. Verified independently before acting, not taken on
102
+ #: report: `surface="Agents"` mounts `AutomationSurface`, and `ManageAgentPane` contains ZERO
103
+ #: occurrences of Canvas, Properties, Run history or panelTabs.
104
+ #:
105
+ #: ⭐ ONE STORE, BOTH PRINCIPALS β€” never a second bucket keyed by surface. The owner's "agent
106
+ #: skills, router" files in two places is the parallel code path item 13 exists to refuse.
107
+ AGENT_SLACK = "slack"
108
+ AGENT_AUTOMATION = "automation"
109
+
110
+
111
+ def agent_kind(rt, agent_id):
112
+ """Which registry holds this id β€” `AGENT_SLACK`, `AGENT_AUTOMATION`, or `None`.
113
+
114
+ ⚠ A SYNTHETIC ROW IS NOT AN AGENT FOR THIS PURPOSE. `field:` and `system:` ids are DERIVED at
115
+ read time from a column definition or a connector schedule; they have no stored home, so a
116
+ harness file hung off one is an orphan the moment the column changes. `patch_automation`
117
+ already refuses those ids for the neighbouring reason, and this refuses them by simply not
118
+ finding them β€” `all_definitions` holds stored automations only.
119
+ """
120
+ import routes_slack
121
+ aid = str(agent_id or "")
122
+ if isinstance(routes_slack._agents(rt).get(aid), dict):
123
+ return AGENT_SLACK
124
+ import automation_engine as engine
125
+ try:
126
+ known = engine.all_definitions(rt) or {}
127
+ except Exception: # noqa: BLE001
128
+ return None
129
+ return AGENT_AUTOMATION if aid in known else None
130
+
131
+
132
+ def _known_agent(rt, agent_id):
133
+ """Does this tenant have an agent with this id, in EITHER registry?"""
134
+ return agent_kind(rt, agent_id) is not None
135
+
136
+
137
+ def agent_wall(session, agent_id):
138
+ """404 for an unknown id, else apply the wall THAT PRINCIPAL'S OWN SURFACE applies.
139
+
140
+ β›”β›” ONE DOOR, TWO WALLS, AND THAT IS NOT A SECOND CODE PATH β€” it is the refusal to invent a
141
+ THIRD wall. A Slack channel agent is administered under Manage users and every `/agents/*` door
142
+ in `routes_slack` is `admin_gate`; an automation lives in the Agents module and every door in
143
+ `routes_automation` is `module_gate("automation")`. A harness file is configuration OF the
144
+ agent it hangs off, so it is reached by whoever may already configure that agent. Picking one
145
+ of the two walls for both would either lock the Agents module's own users out of a tab the
146
+ owner asked for, or hand the Slack permission wall to anyone with an automation grant.
147
+ """
148
+ kind = agent_kind(session.runtime, agent_id)
149
+ if kind is None:
150
+ raise err(404, "no_agent", "there is no agent with that id in this workspace")
151
+ if kind == AGENT_SLACK:
152
+ import core.perms as perms
153
+ if not perms.is_admin(session.user):
154
+ raise err(403, "forbidden", "administrators only")
155
+ else:
156
+ session.require("automation")
157
+ return kind
158
+
159
+
160
+ def normalize_path(raw):
161
+ """THE path rule, in ONE place. Returns the cleaned path, or `None` if it is not acceptable.
162
+
163
+ β›”β›” ONE RULE, TWO DOORS, AND THAT IS WHY THIS IS A FUNCTION RATHER THAN TWO IF-BLOCKS. There
164
+ are two ways into this store β€” the HTTP route (which must answer 400) and `record_version()`
165
+ (which must raise `ValueError`, having no response to put a status into). Written twice, the
166
+ two copies are [[one-question-two-normalizers]] waiting to happen: the first weakening of one
167
+ copy is invisible because the other still refuses, so nothing goes red and the wall is now
168
+ half there. Written once, a change to the rule is felt at both doors and by the gate.
169
+ """
170
+ path = str(raw or "").strip().strip("/")
171
+ if not path or len(path) > MAX_PATH:
172
+ return None
173
+ if set(path) - _PATH_OK or ".." in path or "//" in path:
174
+ return None
175
+ return path
176
+
177
+
178
+ def _clean_path(raw):
179
+ """`normalize_path` at the HTTP door, where a refusal is a 400 with a reason."""
180
+ path = normalize_path(raw)
181
+ if path is None:
182
+ if not str(raw or "").strip().strip("/"):
183
+ raise err(400, "no_path", "a harness file needs a path, for example skills/router.md")
184
+ if len(str(raw)) > MAX_PATH:
185
+ raise err(400, "path_too_long", f"a harness path is at most {MAX_PATH} characters")
186
+ raise err(400, "bad_path",
187
+ "a harness path may use letters, digits, dot, dash, underscore and / only")
188
+ return path
189
+
190
+
191
+ def _blank(path, author, author_kind):
192
+ return {"path": path, "versions": [], "trimmed": 0,
193
+ "created": _now(), "createdBy": author, "createdKind": author_kind}
194
+
195
+
196
+ def _append(record, body, author, author_kind, restored_from=None):
197
+ """Append ONE version to a file record, in place, and report what was trimmed.
198
+
199
+ The version NUMBER is monotonic and survives trimming β€” it counts writes, not stored entries.
200
+ A version list whose numbers restart at 1 after a trim would make two different bodies share a
201
+ name, and `restoredFrom` would then point at whichever one happened to be in the window.
202
+ """
203
+ # ⚠ A NEW LIST, NEVER `versions.append(...)` ON THE STORED ONE. `update()` hands the callback
204
+ # the live document and may run it more than once; appending in place would then stack two
205
+ # copies of the same version into the history on a retry.
206
+ prior = record.get("versions") if isinstance(record.get("versions"), list) else []
207
+ last = max((int(v.get("version") or 0) for v in prior if isinstance(v, dict)), default=0)
208
+ entry = {"version": last + 1, "body": body, "author": author, "authorKind": author_kind,
209
+ "created": _now(), "bytes": len(body.encode("utf-8"))}
210
+ if restored_from:
211
+ entry["restoredFrom"] = int(restored_from)
212
+ versions = [*prior, entry]
213
+ dropped = max(0, len(versions) - MAX_VERSIONS)
214
+ if dropped:
215
+ versions = versions[dropped:]
216
+ record["versions"] = versions
217
+ record["trimmed"] = int(record.get("trimmed") or 0) + dropped
218
+ return entry
219
+
220
+
221
+ def _head(record):
222
+ """The newest version of a file record, or `None` for a record with no versions at all."""
223
+ versions = record.get("versions") if isinstance(record.get("versions"), list) else []
224
+ return versions[-1] if versions else None
225
+
226
+
227
+ def _row(record):
228
+ """One file, as the LIST door reports it: everything except the bodies.
229
+
230
+ ⚠ NO BODY, AND THAT IS THE POINT. A list door that carried every version of every file would
231
+ ship the whole harness on every pane render; the Harness tab lists first and opens one file
232
+ second, which is exactly the shape this answers.
233
+ """
234
+ head = _head(record) or {}
235
+ versions = record.get("versions") if isinstance(record.get("versions"), list) else []
236
+ return {"path": record.get("path") or "",
237
+ "version": int(head.get("version") or 0),
238
+ "bytes": int(head.get("bytes") or 0),
239
+ "author": head.get("author") or record.get("createdBy") or "",
240
+ "authorKind": head.get("authorKind") or record.get("createdKind") or "user",
241
+ "updated": head.get("created") or record.get("created") or "",
242
+ "created": record.get("created") or "",
243
+ "versions": len(versions),
244
+ "trimmed": int(record.get("trimmed") or 0)}
245
+
246
+
247
+ def _version_rows(record):
248
+ """The history of one file, newest first, WITHOUT the bodies.
249
+
250
+ A body per version is what makes a diff possible, and it is also what makes this payload big:
251
+ 100 versions of a 128 KB file is 12 MB. The client asks for the two bodies it is diffing
252
+ (`?path=…&version=N`), which is two round trips for a diff and none for a history list.
253
+ """
254
+ versions = record.get("versions") if isinstance(record.get("versions"), list) else []
255
+ out = []
256
+ for entry in reversed(versions):
257
+ if not isinstance(entry, dict):
258
+ continue
259
+ row = {"version": int(entry.get("version") or 0),
260
+ "author": entry.get("author") or "",
261
+ "authorKind": entry.get("authorKind") or "user",
262
+ "created": entry.get("created") or "",
263
+ "bytes": int(entry.get("bytes") or 0)}
264
+ if entry.get("restoredFrom"):
265
+ row["restoredFrom"] = int(entry["restoredFrom"])
266
+ out.append(row)
267
+ return out
268
+
269
+
270
+ def _limits():
271
+ """The caps, IN the payload, so a client can say "this file is full" before a write fails.
272
+
273
+ ⚠ A limit the client cannot see is a limit the user meets as an error. `trimmed` reports the
274
+ one cap that acts without refusing; these report the three that refuse.
275
+ """
276
+ return {"maxBodyBytes": MAX_BODY_BYTES, "maxFiles": MAX_FILES,
277
+ "maxVersions": MAX_VERSIONS, "maxPath": MAX_PATH}
278
+
279
+
280
+ # ── the write door the SERVER uses (no session) ────────────────────────────────────────────────
281
+ def record_version(runtime, agent_id, path, body, author="", author_kind="agent",
282
+ restored_from=None):
283
+ """Write one version from INSIDE the server β€” the agent's own half of R8.
284
+
285
+ ⭐ THIS IS THE FUNCTION, NOT THE ROUTE, THAT MAKES "editable by BOTH the user and the agent"
286
+ true. An agent acting inside an automation run holds no session and no cookie; if its only way
287
+ to write were the HTTP door it would have to borrow a person's identity, and the authorship
288
+ column would then be a record of who was logged in rather than of what wrote the file.
289
+
290
+ Returns the appended entry. Raises nothing the caller cannot handle: an unknown agent is a
291
+ `ValueError`, because a server-side caller has no HTTP response to put a 404 into.
292
+ """
293
+ agent_id = str(agent_id or "")
294
+ if not _known_agent(runtime, agent_id):
295
+ raise ValueError(f"no agent {agent_id!r} in this workspace")
296
+ path = normalize_path(path)
297
+ if path is None:
298
+ raise ValueError("that is not an acceptable harness path")
299
+ body = str(body or "")
300
+ if len(body.encode("utf-8")) > MAX_BODY_BYTES:
301
+ raise ValueError("harness body is over the size limit")
302
+ kind = author_kind if author_kind in AUTHOR_KINDS else "agent"
303
+ author = str(author or agent_id)
304
+ # β›” THE FILE-COUNT CEILING IS CHECKED HERE, NOT INSIDE `_set`. An exception raised inside a
305
+ # store `update` callback propagates out of a half-run read-modify-write, and the one thing a
306
+ # refusal must never do is leave the caller unsure whether the write happened.
307
+ existing = _files(runtime, agent_id)
308
+ if path not in existing and len(existing) >= MAX_FILES:
309
+ raise ValueError(f"this agent already has {MAX_FILES} harness files")
310
+ appended = {}
311
+
312
+ def _set(cur):
313
+ cur = dict(cur or {})
314
+ files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
315
+ record = dict(files[path]) if isinstance(files.get(path), dict) else _blank(path, author, kind)
316
+ appended.clear()
317
+ appended.update(_append(record, body, author, kind, restored_from))
318
+ files[path] = record
319
+ cur[agent_id] = files
320
+ return cur
321
+
322
+ runtime.update(HARNESS_KEY, _set, flush="sync")
323
+ return appended
324
+
325
+
326
+ # ── the routes ────────────────────────────────────────────────────────────────────────────────
327
+ @router.get("/agents/{agent_id}/harness")
328
+ def get_harness(agent_id: str, path: str = "", version: int = 0,
329
+ session: Session = Depends(require_session)):
330
+ """The list, one file, or one older body β€” decided by the query string (C4).
331
+
332
+ ⚠ ADMIN-GATED LIKE EVERY OTHER AGENT DOOR (`routes_slack`), and for a stronger reason than
333
+ consistency: a harness file is what the agent is INSTRUCTED to do, so writing one is closer to
334
+ editing a permission than to editing a document.
335
+ """
336
+ agent_id = str(agent_id or "")
337
+ agent_wall(session, agent_id)
338
+ files = _files(session.runtime, agent_id)
339
+ if not path:
340
+ rows = [_row(rec) for _p, rec in sorted(files.items()) if isinstance(rec, dict)]
341
+ return {"agent": agent_id, "files": rows, "limits": _limits()}
342
+
343
+ wanted = _clean_path(path)
344
+ record = files.get(wanted)
345
+ if not isinstance(record, dict):
346
+ raise err(404, "no_file", f"this agent has no harness file at {wanted}")
347
+ versions = record.get("versions") if isinstance(record.get("versions"), list) else []
348
+ if version:
349
+ for entry in versions:
350
+ if isinstance(entry, dict) and int(entry.get("version") or 0) == int(version):
351
+ return {"agent": agent_id, **_row(record), "body": entry.get("body") or "",
352
+ "atVersion": int(version), "history": _version_rows(record),
353
+ "limits": _limits()}
354
+ # β›” A TRIMMED VERSION IS A NAMED REFUSAL, NOT A 404 SHAPED LIKE A TYPO. The client asked
355
+ # for something that existed and no longer does, and telling it apart from a bad number is
356
+ # the difference between "roll back to v3" failing loudly and failing as if v3 never was.
357
+ trimmed = int(record.get("trimmed") or 0)
358
+ if trimmed and int(version) <= trimmed:
359
+ raise err(410, "version_trimmed",
360
+ f"version {int(version)} is older than the {MAX_VERSIONS} versions kept "
361
+ f"for this file, and its body is gone")
362
+ raise err(404, "no_version", f"this file has no version {int(version)}")
363
+ head = _head(record) or {}
364
+ return {"agent": agent_id, **_row(record), "body": head.get("body") or "",
365
+ "atVersion": int(head.get("version") or 0), "history": _version_rows(record),
366
+ "limits": _limits()}
367
+
368
+
369
+ @router.put("/agents/{agent_id}/harness")
370
+ def put_harness(agent_id: str, body: dict = Body(default=None),
371
+ session: Session = Depends(require_session)):
372
+ """Write a NEW version of one harness file. `{path, body, authorKind?, restoredFrom?}` (C4).
373
+
374
+ β›” THERE IS NO OVERWRITE HERE AND THERE IS NO EDIT-IN-PLACE. R8's "every version kept" is not a
375
+ UI affordance; it is this function refusing to have a code path that replaces a body. A
376
+ roll-back arrives as an ordinary write carrying `restoredFrom`, so the history records that
377
+ somebody went back rather than pretending the intervening versions never happened.
378
+ """
379
+ agent_id = str(agent_id or "")
380
+ agent_wall(session, agent_id)
381
+ body = body if isinstance(body, dict) else {}
382
+ path = _clean_path(body.get("path"))
383
+ text = body.get("body")
384
+ if not isinstance(text, str):
385
+ raise err(400, "no_body", "a harness file needs a body, even an empty one")
386
+ if len(text.encode("utf-8")) > MAX_BODY_BYTES:
387
+ raise err(413, "body_too_long",
388
+ f"a harness file is at most {MAX_BODY_BYTES // 1024} KB; this one is larger")
389
+
390
+ # ⚠ THE CALLER DECLARES THE PROVENANCE AND THE SERVER STAMPS THE IDENTITY. `authorKind` is a
391
+ # claim about who WROTE the text (the person, or the agent in the chat panel); `author` is the
392
+ # session and is never read off the request. Nothing is bought by forging the first β€” both
393
+ # principals may write (R8) β€” and everything would be bought by forging the second.
394
+ kind = str(body.get("authorKind") or "user").strip().lower()
395
+ if kind not in AUTHOR_KINDS:
396
+ raise err(400, "bad_author_kind", "authorKind is either user or agent")
397
+ restored = body.get("restoredFrom")
398
+ try:
399
+ restored = int(restored) if restored else None
400
+ except (TypeError, ValueError):
401
+ raise err(400, "bad_version", "restoredFrom must be a version number")
402
+
403
+ files = _files(session.runtime, agent_id)
404
+ if path not in files and len(files) >= MAX_FILES:
405
+ raise err(409, "too_many_files",
406
+ f"this agent already has {MAX_FILES} harness files; delete one to add another")
407
+ try:
408
+ record_version(session.runtime, agent_id, path, text,
409
+ author=session.uname, author_kind=kind, restored_from=restored)
410
+ except ValueError as exc:
411
+ raise err(400, "refused", str(exc))
412
+
413
+ fresh = _files(session.runtime, agent_id).get(path)
414
+ if not isinstance(fresh, dict) or not _head(fresh):
415
+ # The store took the write and did not record it. A 200 here would tell an administrator
416
+ # their skill file was saved when it was not β€” the shape `routes_slack` refuses too.
417
+ raise err(503, "store_unavailable", "the harness file was NOT saved")
418
+ head = _head(fresh)
419
+ return {"agent": agent_id, **_row(fresh), "body": head.get("body") or "",
420
+ "atVersion": int(head.get("version") or 0), "history": _version_rows(fresh),
421
+ "limits": _limits()}
422
+
423
+
424
+ @router.delete("/agents/{agent_id}/harness")
425
+ def delete_harness(agent_id: str, path: str = "", session: Session = Depends(require_session)):
426
+ """Drop one harness file AND its history.
427
+
428
+ ⚠ THIS IS NOT THE THING R8 FORBIDS. R8 forbids a ROLL-BACK implemented as a delete β€” losing
429
+ versions as a side effect of an edit. Deleting a file is a person deciding the file should not
430
+ exist, which is a different act with a different button, and a store with no way to remove a
431
+ file is one where a typo'd path is permanent.
432
+ """
433
+ agent_id = str(agent_id or "")
434
+ agent_wall(session, agent_id)
435
+ wanted = _clean_path(path)
436
+ if wanted not in _files(session.runtime, agent_id):
437
+ raise err(404, "no_file", f"this agent has no harness file at {wanted}")
438
+
439
+ def _set(cur):
440
+ cur = dict(cur or {})
441
+ files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
442
+ files.pop(wanted, None)
443
+ # An agent with no harness files leaves NO key behind. An empty dict per agent id is how a
444
+ # bucket accumulates a row for every agent anybody ever opened the tab on.
445
+ if files:
446
+ cur[agent_id] = files
447
+ else:
448
+ cur.pop(agent_id, None)
449
+ return cur
450
+
451
+ session.runtime.update(HARNESS_KEY, _set, flush="sync")
452
+ return {"agent": agent_id, "deleted": wanted,
453
+ "files": [_row(rec) for _p, rec in sorted(_files(session.runtime, agent_id).items())
454
+ if isinstance(rec, dict)],
455
+ "limits": _limits()}
api/routes_geo.py CHANGED
@@ -324,7 +324,8 @@ def _zone_context(session, raw_table_key):
324
 
325
  def _zone_subject(session, table_key, zone_id):
326
  from core import route_system
327
- zone = next((item for item in route_system.list_zones(session.runtime)
 
328
  if str(item.get("id") or "") == str(zone_id)), None)
329
  if not isinstance(zone, dict):
330
  raise err(404, "unknown_zone", "no Zone with that id")
@@ -507,7 +508,7 @@ def geo_zones(tableKey: str = Query(default=""), session: Session = Depends(requ
507
  """The canonical table-scoped Zone DTOs a Map may draw or filter by."""
508
  from core import route_system
509
  table_key, _fields, pids, rows = _zone_context(session, tableKey)
510
- zones = route_system.list_zones(session.runtime, rows)
511
  # A hidden Zone remains recoverable to its creator/admin, but cannot become visible through a
512
  # second table simply because row ids happen to collide there.
513
  visible = [zone for zone in zones if zone.get("visible", True)
@@ -530,7 +531,8 @@ def geo_zone_create(body: dict = Body(default=None), session: Session = Depends(
530
  "id": body.get("id"), "name": body.get("name"), "color": body.get("color"),
531
  "geometryGeoJson": body.get("geometryGeoJson"), "zipCodes": body.get("zipCodes"),
532
  "visible": body.get("visible"), "geographicField": body.get("geographicField")
533
- }, rows=rows, tenant_id=session.tenant, created_by=session.uname)
 
534
  if zone is None:
535
  raise ValueError("the Zone does not match this database's fields and records")
536
  except ValueError as exc:
@@ -558,7 +560,8 @@ def geo_zone_update(zone_id: str, body: dict = Body(default=None),
558
  "zipCodes": body.get("zipCodes", previous.get("zipCodes")),
559
  "visible": body.get("visible", previous.get("visible")),
560
  "geographicField": body.get("geographicField", previous.get("geographicField"))
561
- }, rows=rows, tenant_id=session.tenant, created_by=session.uname)
 
562
  if zone is None:
563
  raise ValueError("the Zone does not match this database's fields and records")
564
  except ValueError as exc:
@@ -574,7 +577,7 @@ def geo_zone_delete(zone_id: str, body: dict = Body(default=None),
574
  table_key, _fields, _pids, _rows = _zone_context(session, body.get("tableKey"))
575
  _zone_subject(session, table_key, zone_id)
576
  from core import route_system
577
- if not route_system.delete_zone(session.runtime, zone_id):
578
  raise err(404, "unknown_zone", "no Zone with that id")
579
  return {"deleted": str(zone_id)}
580
 
 
324
 
325
  def _zone_subject(session, table_key, zone_id):
326
  from core import route_system
327
+ zone = next((item for item in route_system.list_zones(
328
+ session.runtime, table_key=table_key)
329
  if str(item.get("id") or "") == str(zone_id)), None)
330
  if not isinstance(zone, dict):
331
  raise err(404, "unknown_zone", "no Zone with that id")
 
508
  """The canonical table-scoped Zone DTOs a Map may draw or filter by."""
509
  from core import route_system
510
  table_key, _fields, pids, rows = _zone_context(session, tableKey)
511
+ zones = route_system.list_zones(session.runtime, rows, table_key=table_key)
512
  # A hidden Zone remains recoverable to its creator/admin, but cannot become visible through a
513
  # second table simply because row ids happen to collide there.
514
  visible = [zone for zone in zones if zone.get("visible", True)
 
531
  "id": body.get("id"), "name": body.get("name"), "color": body.get("color"),
532
  "geometryGeoJson": body.get("geometryGeoJson"), "zipCodes": body.get("zipCodes"),
533
  "visible": body.get("visible"), "geographicField": body.get("geographicField")
534
+ }, rows=rows, tenant_id=session.tenant, created_by=session.uname,
535
+ table_key=table_key)
536
  if zone is None:
537
  raise ValueError("the Zone does not match this database's fields and records")
538
  except ValueError as exc:
 
560
  "zipCodes": body.get("zipCodes", previous.get("zipCodes")),
561
  "visible": body.get("visible", previous.get("visible")),
562
  "geographicField": body.get("geographicField", previous.get("geographicField"))
563
+ }, rows=rows, tenant_id=session.tenant, created_by=session.uname,
564
+ table_key=table_key)
565
  if zone is None:
566
  raise ValueError("the Zone does not match this database's fields and records")
567
  except ValueError as exc:
 
577
  table_key, _fields, _pids, _rows = _zone_context(session, body.get("tableKey"))
578
  _zone_subject(session, table_key, zone_id)
579
  from core import route_system
580
+ if not route_system.delete_zone(session.runtime, zone_id, table_key=table_key):
581
  raise err(404, "unknown_zone", "no Zone with that id")
582
  return {"deleted": str(zone_id)}
583
 
api/routes_keychain.py CHANGED
The diff for this file is too large to render. See raw diff
 
api/routes_oauth.py CHANGED
@@ -1,114 +1,114 @@
1
- """routes_oauth.py β€” the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
2
-
3
- Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
4
- shapes and status codes here; every decision that could be wrong lives in the module a gate
5
- can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
6
- so the day a second provider lands here is the day nothing in this file changes.
7
-
8
- MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
9
- `main.py`, and `routes_automation` is already included there β€” so this router rides inside it
10
- (`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
11
- alters no path.
12
-
13
- ⚠ THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
14
- screen** β€” it is a top-level navigation the client reaches by `<a href>`, never JSON. The
15
- callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
16
- `oauth_connect.safe_next`), so the user lands where they left β€” connected or not, whatever
17
- went wrong rides in the query string; a dead-end error page where the app used to be reads as
18
- "the product broke", not "the connect failed".
19
- """
20
- import os
21
-
22
- from fastapi import APIRouter, Depends, Request
23
- from fastapi.responses import RedirectResponse
24
-
25
- import oauth_connect
26
- from deps import Session, err, require_session
27
-
28
- router = APIRouter(prefix="/oauth")
29
-
30
-
31
- def _redirect_uri(request: Request, provider: str) -> str:
32
- """The redirect URI this deployment registers at the provider β€” env-pinned when the
33
- container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
34
- the request. MUST match a console-registered URI verbatim, so it is computed in exactly
35
- one place.
36
-
37
- ⭐ WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
38
- the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
39
- the request-derived fallback below is effectively dev-only.
40
- β›” THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
41
- this returns is where the provider sends the user BACK, and the session cookie is host-only
42
- (`aios_session.py:114-117`, no `domain=`) β€” so a callback base that disagrees with the host
43
- the user actually browsed plants the session on the wrong hostname and they return logged
44
- out. Moving the app to a new hostname means moving this value AND re-registering the
45
- resulting URI in the provider console; one without the other fails closed.
46
- Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
47
- base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
48
- if not base:
49
- base = f"{request.url.scheme}://{request.url.netloc}"
50
- return f"{base}/api/v1/oauth/{provider}/callback"
51
-
52
-
53
- @router.get("/status")
54
- def oauth_status(session: Session = Depends(require_session)):
55
- """C5's status shape for the SESSION user, one entry per registry provider:
56
- `{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
57
- `ready` reads through."""
58
- return oauth_connect.status(session.runtime, session.uname)
59
-
60
-
61
- def _offered_or_404(provider: str):
62
- """β›”β›” W32-T14 / OWNER ITEM 12 / R6 β€” A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
63
-
64
- The owner pasted the failure this replaces: clicking Connect on the Google card answered
65
- `503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error β€” it is that the flow is
66
- not offered at all, so the honest status is the one for a URL that does not exist. `404`
67
- rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
68
- coming back until somebody pays for CASA verification (D-45, ~$540–1,800/yr).
69
-
70
- ⚠ Every door in this router goes through it, START included, because the JSON the owner saw
71
- came from the start route and a guard on one leg is a guard on one leg.
72
- """
73
- if not oauth_connect.offered(provider):
74
- raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
75
-
76
-
77
- @router.get("/{provider}/start")
78
- def oauth_start(provider: str, request: Request, next: str = "",
79
- session: Session = Depends(require_session)):
80
- """302 to the provider's consent screen (A3 β€” a navigation, never JSON). `?next=` is the
81
- RELATIVE path the callback returns the browser to; it rides inside the single-use state,
82
- sanitised, so the round trip cannot be steered off-origin."""
83
- _offered_or_404(provider)
84
- url, problem = oauth_connect.start(provider, session.uname,
85
- _redirect_uri(request, provider), next_path=next)
86
- if problem:
87
- raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
88
- return RedirectResponse(url, status_code=302)
89
-
90
-
91
- @router.get("/{provider}/callback")
92
- def oauth_callback(provider: str, request: Request,
93
- session: Session = Depends(require_session),
94
- state: str = "", code: str = "", error: str = ""):
95
- """The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
96
- the browser back to the state's return path β€” connected or not (see module header)."""
97
- _offered_or_404(provider)
98
- if error:
99
- home = "/#/"
100
- return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
101
- email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
102
- sep = "&" if "?" in home else "?"
103
- if problem:
104
- return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
105
- return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
106
-
107
-
108
- @router.post("/{provider}/disconnect")
109
- def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
110
- _offered_or_404(provider)
111
- if oauth_connect.provider_def(provider) is None:
112
- raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
113
- oauth_connect.disconnect(session.runtime, session.uname, provider)
114
- return {"disconnected": provider}
 
1
+ """routes_oauth.py β€” the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
2
+
3
+ Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
4
+ shapes and status codes here; every decision that could be wrong lives in the module a gate
5
+ can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
6
+ so the day a second provider lands here is the day nothing in this file changes.
7
+
8
+ MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
9
+ `main.py`, and `routes_automation` is already included there β€” so this router rides inside it
10
+ (`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
11
+ alters no path.
12
+
13
+ ⚠ THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
14
+ screen** β€” it is a top-level navigation the client reaches by `<a href>`, never JSON. The
15
+ callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
16
+ `oauth_connect.safe_next`), so the user lands where they left β€” connected or not, whatever
17
+ went wrong rides in the query string; a dead-end error page where the app used to be reads as
18
+ "the product broke", not "the connect failed".
19
+ """
20
+ import os
21
+
22
+ from fastapi import APIRouter, Depends, Request
23
+ from fastapi.responses import RedirectResponse
24
+
25
+ import oauth_connect
26
+ from deps import Session, err, require_session
27
+
28
+ router = APIRouter(prefix="/oauth")
29
+
30
+
31
+ def _redirect_uri(request: Request, provider: str) -> str:
32
+ """The redirect URI this deployment registers at the provider β€” env-pinned when the
33
+ container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
34
+ the request. MUST match a console-registered URI verbatim, so it is computed in exactly
35
+ one place.
36
+
37
+ ⭐ WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
38
+ the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
39
+ the request-derived fallback below is effectively dev-only.
40
+ β›” THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
41
+ this returns is where the provider sends the user BACK, and the session cookie is host-only
42
+ (`aios_session.py:114-117`, no `domain=`) β€” so a callback base that disagrees with the host
43
+ the user actually browsed plants the session on the wrong hostname and they return logged
44
+ out. Moving the app to a new hostname means moving this value AND re-registering the
45
+ resulting URI in the provider console; one without the other fails closed.
46
+ Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
47
+ base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
48
+ if not base:
49
+ base = f"{request.url.scheme}://{request.url.netloc}"
50
+ return f"{base}/api/v1/oauth/{provider}/callback"
51
+
52
+
53
+ @router.get("/status")
54
+ def oauth_status(session: Session = Depends(require_session)):
55
+ """C5's status shape for the SESSION user, one entry per registry provider:
56
+ `{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
57
+ `ready` reads through."""
58
+ return oauth_connect.status(session.runtime, session.uname)
59
+
60
+
61
+ def _offered_or_404(provider: str):
62
+ """β›”β›” W32-T14 / OWNER ITEM 12 / R6 β€” A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
63
+
64
+ The owner pasted the failure this replaces: clicking Connect on the Google card answered
65
+ `503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error β€” it is that the flow is
66
+ not offered at all, so the honest status is the one for a URL that does not exist. `404`
67
+ rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
68
+ coming back until somebody pays for CASA verification (D-45, ~$540–1,800/yr).
69
+
70
+ ⚠ Every door in this router goes through it, START included, because the JSON the owner saw
71
+ came from the start route and a guard on one leg is a guard on one leg.
72
+ """
73
+ if not oauth_connect.offered(provider):
74
+ raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
75
+
76
+
77
+ @router.get("/{provider}/start")
78
+ def oauth_start(provider: str, request: Request, next: str = "",
79
+ session: Session = Depends(require_session)):
80
+ """302 to the provider's consent screen (A3 β€” a navigation, never JSON). `?next=` is the
81
+ RELATIVE path the callback returns the browser to; it rides inside the single-use state,
82
+ sanitised, so the round trip cannot be steered off-origin."""
83
+ _offered_or_404(provider)
84
+ url, problem = oauth_connect.start(provider, session.uname,
85
+ _redirect_uri(request, provider), next_path=next)
86
+ if problem:
87
+ raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
88
+ return RedirectResponse(url, status_code=302)
89
+
90
+
91
+ @router.get("/{provider}/callback")
92
+ def oauth_callback(provider: str, request: Request,
93
+ session: Session = Depends(require_session),
94
+ state: str = "", code: str = "", error: str = ""):
95
+ """The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
96
+ the browser back to the state's return path β€” connected or not (see module header)."""
97
+ _offered_or_404(provider)
98
+ if error:
99
+ home = "/#/"
100
+ return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
101
+ email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
102
+ sep = "&" if "?" in home else "?"
103
+ if problem:
104
+ return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
105
+ return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
106
+
107
+
108
+ @router.post("/{provider}/disconnect")
109
+ def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
110
+ _offered_or_404(provider)
111
+ if oauth_connect.provider_def(provider) is None:
112
+ raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
113
+ oauth_connect.disconnect(session.runtime, session.uname, provider)
114
+ return {"disconnected": provider}
api/routes_records.py CHANGED
@@ -1,211 +1,211 @@
1
- """Record detail routes: durable comments, scoped to the caller's book β€” ON EVERY DATABASE.
2
-
3
- ⭐ WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
4
- customer-shaped wall bolted to the module import line: `_in_book` asked
5
- `routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
6
- typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
7
- panel answered "that customer is not in your book" β€” the owner's report. The dangerous half is
8
- the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
9
- is filed against somebody's customer where the whole team can read it.
10
-
11
- THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
12
- events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
13
- per scope β€” the GRANT and the ROW SET β€” by asking that topic's own route, never by re-deriving
14
- one here:
15
-
16
- customer / cohort `routes_customers.allowed_pids` behind the `customer_data` grant
17
- product `routes_products.scoped_pool` behind the `product_data` grant
18
- ut_<slug> `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
19
- (404 unknown / 403 not yours β€” a user table has no module grant).
20
- ⭐ W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` β€” the pool builds every
21
- ROW to derive a pid set this module discards, and RAISES 409 on a
22
- read-through grid past one window, which is why the record drawer painted
23
- an error page on `ut_odoo_gl_lines`.
24
-
25
- ⚠ THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
26
- section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
27
- another session's gate mid-wave β€” the WALL is the query parameter, not the word.
28
-
29
- ⚠ NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
30
- shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
31
- 400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
32
- the same reason: a typo served as `customer` answers a question nobody asked).
33
- """
34
- from fastapi import APIRouter, Body, Depends, Query
35
-
36
- from deps import Session, err, require_session
37
-
38
- router = APIRouter(prefix="/api/v1")
39
-
40
- #: The customer topic's two names β€” one book, two surfaces (the Cohort page is the customer table
41
- #: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
42
- _CUSTOMER_SCOPES = ("", "customer", "cohort")
43
-
44
-
45
- def _scope_or_400(raw):
46
- scope = str(raw or "customer").strip().lower()
47
- if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
48
- return "customer" if scope in _CUSTOMER_SCOPES else scope
49
- raise err(400, "bad_scope",
50
- "scope must be customer, cohort, product or a ut_ database β€” refusing to guess")
51
-
52
-
53
- def _pool_or_refuse(session: Session, scope: str):
54
- """The pids this session may attach comments to ON THIS DATABASE β€” grant wall included.
55
-
56
- Returns **`(pids, unbounded)`** β€” a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
57
- so a caller who may not open the surface never learns anything about the row they asked about.
58
-
59
- β›” `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
60
- one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
61
- `frozenset()` for both β€” see the branch below.
62
- ⚠ THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
63
- do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
64
- that REPLACES this function with its own lambda. A gate's test double is a caller
65
- ([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
66
- bare frozenset and the section died on `ValueError: too many values to unpack` β€” no tally, no
67
- failing name. Change the shape here and that double changes with it.
68
- """
69
- if scope == "product":
70
- from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
71
-
72
- session.require(PRODUCT_MODULE)
73
- pids, _team, _rows, _fields = scoped_pool(session)
74
- # ⚠ `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
75
- # after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
76
- # a `TypeError` β€” a 500 on every product comment β€” while both other branches worked. A
77
- # return shape is a contract even when the function is private.
78
- return (pids, False)
79
- if scope.startswith("ut_"):
80
- # No module grant exists for a user table β€” `_defn_or_refuse` inside `scoped_pids` IS
81
- # the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
82
- # rows routes do.
83
- #
84
- # ⭐⭐ W33-T03 / D-183 β€” `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
85
- # `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
86
- # a read-through grid larger than one window it RAISES `409 window_required`. So opening the
87
- # record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page β€” for a panel
88
- # that renders comments about ONE row it already has. `scoped_pids` answers the identical
89
- # question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
90
- # W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
91
- # used to become openable on those two grids.
92
- from routes_tables import scoped_pids
93
-
94
- limits = []
95
- pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
96
- # β›” AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
97
- # how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
98
- # database with no rows and for a read-through grid too big to enumerate β€” it distinguishes
99
- # them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
100
- # from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
101
- # is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
102
- # ⚠ ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
103
- # THE TENANT IS THE UNIT β€” `scoped_pool` itself carries "no per-row owner filter; the
104
- # table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
105
- # `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
106
- return (pids, bool(limits))
107
- from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
108
-
109
- session.require(CUSTOMER_MODULE)
110
- return (frozenset(allowed_pids(session)), False)
111
-
112
-
113
- def _in_book(pid, session, scope):
114
- pids, unbounded = _pool_or_refuse(session, scope)
115
- if unbounded:
116
- # The table wall passed and the row set is larger than this process will enumerate. Said
117
- # out loud rather than silently admitting: R6's second sentence is that a limit which
118
- # cannot be removed gets REPORTED, and this is the one place the report has no envelope to
119
- # ride in.
120
- print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) β€” "
121
- f"admitting on the table wall alone, per D-72")
122
- return
123
- if pid not in pids:
124
- # 403, not 404: the record may exist, but this session may not inspect it.
125
- raise err(403, "out_of_scope", "that record is not in your book")
126
-
127
-
128
- def _unavailable():
129
- return err(
130
- 503,
131
- "store_unavailable",
132
- "record comments are temporarily unavailable β€” no change was saved",
133
- )
134
-
135
-
136
- # ⭐ WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments β€” comments hang off a RECORD
137
- # in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
138
- # wall was always the query param). The old path stays as an ALIAS because the shipped client
139
- # still calls it; verify_api pins the canonical path AND that the alias answers, so removing
140
- # the alias later is a decision, never an accident.
141
- @router.get("/records/{pid}/comments")
142
- @router.get("/customers/{pid}/comments")
143
- def comments(pid: int, scope: str = Query(default="customer"),
144
- session: Session = Depends(require_session)):
145
- from core import record_comments
146
-
147
- scope = _scope_or_400(scope)
148
- _in_book(pid, session, scope)
149
- try:
150
- rows = record_comments.list_comments(session.runtime, pid, scope=scope)
151
- except record_comments.CommentsUnavailable:
152
- raise _unavailable()
153
- return {"comments": rows}
154
-
155
-
156
- @router.post("/records/{pid}/comments", status_code=201)
157
- @router.post("/customers/{pid}/comments", status_code=201)
158
- def create_comment(
159
- pid: int,
160
- body: dict = Body(default=None),
161
- scope: str = Query(default="customer"),
162
- session: Session = Depends(require_session),
163
- ):
164
- from core import record_comments
165
-
166
- scope = _scope_or_400(scope)
167
- _in_book(pid, session, scope)
168
- try:
169
- comment = record_comments.add_comment(
170
- session.runtime,
171
- pid,
172
- (body or {}).get("body"),
173
- session.uname,
174
- session.user.get("name") or session.uname,
175
- scope=scope,
176
- )
177
- except ValueError as exc:
178
- raise err(400, "bad_comment", str(exc))
179
- except record_comments.CommentsUnavailable:
180
- raise _unavailable()
181
- return {"comment": comment}
182
-
183
-
184
- @router.delete("/records/{pid}/comments/{comment_id}")
185
- @router.delete("/customers/{pid}/comments/{comment_id}")
186
- def remove_comment(
187
- pid: int,
188
- comment_id: str,
189
- scope: str = Query(default="customer"),
190
- session: Session = Depends(require_session),
191
- ):
192
- from core import record_comments
193
-
194
- scope = _scope_or_400(scope)
195
- _in_book(pid, session, scope)
196
- try:
197
- deleted = record_comments.delete_comment(
198
- session.runtime,
199
- pid,
200
- comment_id,
201
- session.uname,
202
- admin=session.admin,
203
- scope=scope,
204
- )
205
- except record_comments.CommentForbidden:
206
- raise err(403, "comment_forbidden", "only the author may delete this comment")
207
- except record_comments.CommentsUnavailable:
208
- raise _unavailable()
209
- if not deleted:
210
- raise err(404, "comment_not_found", "that comment no longer exists")
211
- return {"ok": True, "id": comment_id}
 
1
+ """Record detail routes: durable comments, scoped to the caller's book β€” ON EVERY DATABASE.
2
+
3
+ ⭐ WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
4
+ customer-shaped wall bolted to the module import line: `_in_book` asked
5
+ `routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
6
+ typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
7
+ panel answered "that customer is not in your book" β€” the owner's report. The dangerous half is
8
+ the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
9
+ is filed against somebody's customer where the whole team can read it.
10
+
11
+ THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
12
+ events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
13
+ per scope β€” the GRANT and the ROW SET β€” by asking that topic's own route, never by re-deriving
14
+ one here:
15
+
16
+ customer / cohort `routes_customers.allowed_pids` behind the `customer_data` grant
17
+ product `routes_products.scoped_pool` behind the `product_data` grant
18
+ ut_<slug> `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
19
+ (404 unknown / 403 not yours β€” a user table has no module grant).
20
+ ⭐ W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` β€” the pool builds every
21
+ ROW to derive a pid set this module discards, and RAISES 409 on a
22
+ read-through grid past one window, which is why the record drawer painted
23
+ an error page on `ut_odoo_gl_lines`.
24
+
25
+ ⚠ THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
26
+ section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
27
+ another session's gate mid-wave β€” the WALL is the query parameter, not the word.
28
+
29
+ ⚠ NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
30
+ shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
31
+ 400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
32
+ the same reason: a typo served as `customer` answers a question nobody asked).
33
+ """
34
+ from fastapi import APIRouter, Body, Depends, Query
35
+
36
+ from deps import Session, err, require_session
37
+
38
+ router = APIRouter(prefix="/api/v1")
39
+
40
+ #: The customer topic's two names β€” one book, two surfaces (the Cohort page is the customer table
41
+ #: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
42
+ _CUSTOMER_SCOPES = ("", "customer", "cohort")
43
+
44
+
45
+ def _scope_or_400(raw):
46
+ scope = str(raw or "customer").strip().lower()
47
+ if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
48
+ return "customer" if scope in _CUSTOMER_SCOPES else scope
49
+ raise err(400, "bad_scope",
50
+ "scope must be customer, cohort, product or a ut_ database β€” refusing to guess")
51
+
52
+
53
+ def _pool_or_refuse(session: Session, scope: str):
54
+ """The pids this session may attach comments to ON THIS DATABASE β€” grant wall included.
55
+
56
+ Returns **`(pids, unbounded)`** β€” a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
57
+ so a caller who may not open the surface never learns anything about the row they asked about.
58
+
59
+ β›” `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
60
+ one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
61
+ `frozenset()` for both β€” see the branch below.
62
+ ⚠ THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
63
+ do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
64
+ that REPLACES this function with its own lambda. A gate's test double is a caller
65
+ ([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
66
+ bare frozenset and the section died on `ValueError: too many values to unpack` β€” no tally, no
67
+ failing name. Change the shape here and that double changes with it.
68
+ """
69
+ if scope == "product":
70
+ from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
71
+
72
+ session.require(PRODUCT_MODULE)
73
+ pids, _team, _rows, _fields = scoped_pool(session)
74
+ # ⚠ `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
75
+ # after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
76
+ # a `TypeError` β€” a 500 on every product comment β€” while both other branches worked. A
77
+ # return shape is a contract even when the function is private.
78
+ return (pids, False)
79
+ if scope.startswith("ut_"):
80
+ # No module grant exists for a user table β€” `_defn_or_refuse` inside `scoped_pids` IS
81
+ # the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
82
+ # rows routes do.
83
+ #
84
+ # ⭐⭐ W33-T03 / D-183 β€” `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
85
+ # `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
86
+ # a read-through grid larger than one window it RAISES `409 window_required`. So opening the
87
+ # record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page β€” for a panel
88
+ # that renders comments about ONE row it already has. `scoped_pids` answers the identical
89
+ # question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
90
+ # W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
91
+ # used to become openable on those two grids.
92
+ from routes_tables import scoped_pids
93
+
94
+ limits = []
95
+ pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
96
+ # β›” AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
97
+ # how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
98
+ # database with no rows and for a read-through grid too big to enumerate β€” it distinguishes
99
+ # them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
100
+ # from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
101
+ # is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
102
+ # ⚠ ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
103
+ # THE TENANT IS THE UNIT β€” `scoped_pool` itself carries "no per-row owner filter; the
104
+ # table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
105
+ # `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
106
+ return (pids, bool(limits))
107
+ from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
108
+
109
+ session.require(CUSTOMER_MODULE)
110
+ return (frozenset(allowed_pids(session)), False)
111
+
112
+
113
+ def _in_book(pid, session, scope):
114
+ pids, unbounded = _pool_or_refuse(session, scope)
115
+ if unbounded:
116
+ # The table wall passed and the row set is larger than this process will enumerate. Said
117
+ # out loud rather than silently admitting: R6's second sentence is that a limit which
118
+ # cannot be removed gets REPORTED, and this is the one place the report has no envelope to
119
+ # ride in.
120
+ print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) β€” "
121
+ f"admitting on the table wall alone, per D-72")
122
+ return
123
+ if pid not in pids:
124
+ # 403, not 404: the record may exist, but this session may not inspect it.
125
+ raise err(403, "out_of_scope", "that record is not in your book")
126
+
127
+
128
+ def _unavailable():
129
+ return err(
130
+ 503,
131
+ "store_unavailable",
132
+ "record comments are temporarily unavailable β€” no change was saved",
133
+ )
134
+
135
+
136
+ # ⭐ WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments β€” comments hang off a RECORD
137
+ # in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
138
+ # wall was always the query param). The old path stays as an ALIAS because the shipped client
139
+ # still calls it; verify_api pins the canonical path AND that the alias answers, so removing
140
+ # the alias later is a decision, never an accident.
141
+ @router.get("/records/{pid}/comments")
142
+ @router.get("/customers/{pid}/comments")
143
+ def comments(pid: int, scope: str = Query(default="customer"),
144
+ session: Session = Depends(require_session)):
145
+ from core import record_comments
146
+
147
+ scope = _scope_or_400(scope)
148
+ _in_book(pid, session, scope)
149
+ try:
150
+ rows = record_comments.list_comments(session.runtime, pid, scope=scope)
151
+ except record_comments.CommentsUnavailable:
152
+ raise _unavailable()
153
+ return {"comments": rows}
154
+
155
+
156
+ @router.post("/records/{pid}/comments", status_code=201)
157
+ @router.post("/customers/{pid}/comments", status_code=201)
158
+ def create_comment(
159
+ pid: int,
160
+ body: dict = Body(default=None),
161
+ scope: str = Query(default="customer"),
162
+ session: Session = Depends(require_session),
163
+ ):
164
+ from core import record_comments
165
+
166
+ scope = _scope_or_400(scope)
167
+ _in_book(pid, session, scope)
168
+ try:
169
+ comment = record_comments.add_comment(
170
+ session.runtime,
171
+ pid,
172
+ (body or {}).get("body"),
173
+ session.uname,
174
+ session.user.get("name") or session.uname,
175
+ scope=scope,
176
+ )
177
+ except ValueError as exc:
178
+ raise err(400, "bad_comment", str(exc))
179
+ except record_comments.CommentsUnavailable:
180
+ raise _unavailable()
181
+ return {"comment": comment}
182
+
183
+
184
+ @router.delete("/records/{pid}/comments/{comment_id}")
185
+ @router.delete("/customers/{pid}/comments/{comment_id}")
186
+ def remove_comment(
187
+ pid: int,
188
+ comment_id: str,
189
+ scope: str = Query(default="customer"),
190
+ session: Session = Depends(require_session),
191
+ ):
192
+ from core import record_comments
193
+
194
+ scope = _scope_or_400(scope)
195
+ _in_book(pid, session, scope)
196
+ try:
197
+ deleted = record_comments.delete_comment(
198
+ session.runtime,
199
+ pid,
200
+ comment_id,
201
+ session.uname,
202
+ admin=session.admin,
203
+ scope=scope,
204
+ )
205
+ except record_comments.CommentForbidden:
206
+ raise err(403, "comment_forbidden", "only the author may delete this comment")
207
+ except record_comments.CommentsUnavailable:
208
+ raise _unavailable()
209
+ if not deleted:
210
+ raise err(404, "comment_not_found", "that comment no longer exists")
211
+ return {"ok": True, "id": comment_id}
api/routes_script_views.py CHANGED
@@ -1,439 +1,439 @@
1
- """routes_script_views.py β€” CONTRACT C3: a database View that is a PYTHON SCRIPT (R3 / R5 / R10).
2
-
3
- Owner item 6, verbatim (2026-08-18): *"Add code script as an interface (database View) so a user
4
- can build whatever they want through the Agent chat interface. be able to create any dashboard
5
- they want. User should have the ability to see the code AND the dashboard output of course… Limit
6
- the code script View per database… Any agent can add into more AI script, so we can see different
7
- versions or different things the AI code for us."*
8
-
9
- GET /api/v1/script-views?database=K the views bound to ONE database
10
- POST /api/v1/script-views create one {database, name?, source}
11
- GET /api/v1/script-views/{id} one view, its source and its history
12
- PUT /api/v1/script-views/{id} a NEW VERSION of the source
13
- DELETE /api/v1/script-views/{id} drop it
14
- POST /api/v1/script-views/{id}/run run it -> {ok, spec | error, stdout, ms}
15
- POST /api/v1/script-views/{id}/revert go back to an earlier version {version}
16
-
17
- ⭐⭐ **R3 IS "SCOPED, NOT CAPPED", AND THE TWO HALVES POINT OPPOSITE WAYS.** *Scoped*: a view may
18
- read ONLY the database it lives in, and a script that names another database is REFUSED with a
19
- message naming both. *Not capped*: there is **no limit on how many script views a database may
20
- carry**, because that is how an agent offers three attempts and the owner picks one. So nothing
21
- below counts views. What IS bounded is what makes them big β€” one source is capped, and one view's
22
- edit history is capped and REPORTS what it dropped.
23
-
24
- β›” **THE RUN IS THE CALLER'S, NEVER THE AUTHOR'S (R5).** `script_sandbox.run_view` is handed
25
- `session.user`, so a script written by an administrator and opened by a scoped analyst reads the
26
- ANALYST's rows. The author decides what the code does; the reader decides what it can see.
27
- ⚠ And the reverse case is safe rather than lucky: a narrowly-scoped author cannot write a script
28
- that exfiltrates anything, because the only thing a script can return is a render spec drawn on
29
- the screen of the person who ran it. There is no network, no file and no second reader.
30
-
31
- β›” **`run` IS `def`, NOT `async def`.** It waits on a subprocess for up to ten seconds; as a
32
- coroutine that would block the event loop for every other request in the container. FastAPI runs a
33
- plain `def` in the threadpool, which is what makes one slow script one slow REQUEST.
34
- """
35
- import threading
36
- from datetime import datetime, timezone
37
-
38
- from fastapi import APIRouter, Body, Depends
39
-
40
- from deps import Session, err, require_session
41
-
42
- router = APIRouter(prefix="/api/v1")
43
-
44
- #: The tenant's script views: `{id: record}`. Per tenant, so it rides `runtime.store_key`.
45
- VIEWS_KEY = "script_views"
46
-
47
- MAX_NAME = 80
48
- MAX_SOURCE_BYTES = 128 * 1024
49
-
50
- #: Edit history per view. ⚠ NOT a cap on the NUMBER of views (R3 forbids that) β€” a cap on how far
51
- #: back ONE view's source is kept. Past this the oldest go and `trimmed` counts them, so a reader
52
- #: can see the history is partial instead of concluding the view was only ever saved twice.
53
- MAX_HISTORY = 40
54
-
55
- #: β›” HOW MANY SCRIPTS MAY BE RUNNING IN THIS CONTAINER AT ONCE, and it is a REPORTED refusal
56
- #: rather than a queue. Each run is a real subprocess with a ten-second wall clock; without this,
57
- #: holding down refresh forks until the box gives up, and the tenant's ONE FastAPI process is what
58
- #: gives up. A 429 that says so is honest; an unbounded fork is not.
59
- MAX_CONCURRENT_RUNS = 4
60
- _RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
61
-
62
-
63
- def _now():
64
- return datetime.now(timezone.utc).isoformat(timespec="seconds")
65
-
66
-
67
- def _all(rt):
68
- """`{id: record}` for one tenant. `{}` on any failure β€” an unreadable bucket must degrade to
69
- "this database has no script views", never to a 500 on the view rail."""
70
- try:
71
- found = rt.get(VIEWS_KEY) or {}
72
- except Exception: # noqa: BLE001
73
- return {}
74
- return found if isinstance(found, dict) else {}
75
-
76
-
77
- def _database_ok(session, database):
78
- """Does this database EXIST, and may this caller read it? Answered by C1, never by a list.
79
-
80
- β›” `perm_scope.may_read` ALONE IS NOT ENOUGH and the reason is easy to miss: it answers True
81
- for an ADMIN on any key at all, including one no database answers to. So a create validated
82
- with `may_read` would let an administrator bind a view to a typo and leave an orphan nothing
83
- can ever run. `scoped_fields` is the cheap half of C1 (a `ut_*` definition, no rows) and it
84
- RAISES `UnknownTable`, which is exactly the question being asked.
85
- """
86
- import core.perm_scope as perm_scope
87
- try:
88
- perm_scope.scoped_fields(session.user, database, st=session.runtime)
89
- except perm_scope.UnknownTable:
90
- raise err(404, "no_database", f"there is no database '{database}' in this workspace")
91
- except perm_scope.Denied:
92
- raise err(403, "forbidden", f"your account may not read '{database}'")
93
- except perm_scope.Unresolvable as exc:
94
- # The database is real and cannot be served under this call's constraints. Standing rule
95
- # 1's second sentence: report the cause and the recommendation, never a bare refusal.
96
- raise err(409, "unresolvable", str(exc)) from None
97
-
98
-
99
- def _clean_source(raw, *, allow_empty=False):
100
- """The stored source, or a 400. `allow_empty` is CREATE's alone and the asymmetry is the point.
101
-
102
- ⭐⭐ W37-T41 β€” WHY CREATE MAY BE EMPTY AND SAVE MAY NOT.
103
- Picking "Custom View" in the mode picker mints the view immediately, before a line of code
104
- exists, so that `mode === 'script'` always implies a real id and no reader has to carry a
105
- "the id might be missing" branch (the create semantics handed to lane C in mailbox E-7).
106
- A view that has been created and not yet written is therefore a REAL, legible state: the editor
107
- shows its starter placeholder and the Run control is right there.
108
- A PUT is a different act. It appends a VERSION to a history capped at 40, and blanking a
109
- working script by saving nothing over it is not an edit anybody means to make. So the guard
110
- stays exactly where it was on that door, and a person who wants the view gone deletes it.
111
-
112
- β›” THIS WAS FOUND BY THE GATE, NOT BY READING. `core.script_sandbox.check_source("")` returns
113
- None, so "an empty script is storable" looked true and was written into a mailbox answer another
114
- lane was about to build on. The refusal was HERE, one layer above, in a function the sandbox
115
- knows nothing about. Two validators for one question, disagreeing
116
- [[one-question-two-normalizers]] β€” and the one that would have bitten a person is the one no
117
- unit of this feature was asserting.
118
- """
119
- source = str(raw or "")
120
- if not source.strip() and not allow_empty:
121
- raise err(400, "no_source", "a script view needs some code")
122
- if len(source.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
123
- raise err(413, "source_too_long",
124
- f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of code")
125
- return source
126
-
127
-
128
- def _row(rec, *, source=False):
129
- """One view as the list door reports it. ⚠ NO SOURCE unless asked: the rail lists names."""
130
- out = {"id": rec.get("id") or "", "database": rec.get("database") or "",
131
- "name": rec.get("name") or "", "author": rec.get("author") or "",
132
- "version": int(rec.get("version") or 1),
133
- "created": rec.get("created") or "", "updated": rec.get("updated") or "",
134
- "versions": len(rec.get("history") or []) + 1,
135
- "trimmed": int(rec.get("trimmed") or 0),
136
- # ⭐ W37-T46: which version this one was RESTORED from, when it was. Present on the
137
- # row (not only the history) because the editor's header is where a person reads "what
138
- # am I looking at", and "v5, restored from v2" is the sentence that makes a roll-back
139
- # legible as an event rather than as a coincidence of matching code.
140
- "restoredFrom": rec.get("restoredFrom")}
141
- if source:
142
- out["source"] = rec.get("source") or ""
143
- out["history"] = [{"version": int(h.get("version") or 0), "author": h.get("author") or "",
144
- "created": h.get("created") or "",
145
- "bytes": len(str(h.get("source") or "").encode("utf-8", "replace"))}
146
- for h in reversed(rec.get("history") or []) if isinstance(h, dict)]
147
- return out
148
-
149
-
150
- def _limits():
151
- return {"maxSourceBytes": MAX_SOURCE_BYTES, "maxName": MAX_NAME,
152
- "maxHistory": MAX_HISTORY, "maxConcurrentRuns": MAX_CONCURRENT_RUNS,
153
- # ⭐ SAID OUT LOUD, because R3's "not capped" half is the one a reader assumes wrong.
154
- "maxViewsPerDatabase": None}
155
-
156
-
157
- def _put(session, view_id, mutate):
158
- """Read-modify-write ONE view, synchronously β€” the client re-reads the rail immediately."""
159
- def _set(cur):
160
- cur = dict(cur or {})
161
- nxt = mutate(cur.get(view_id) if isinstance(cur.get(view_id), dict) else None)
162
- if nxt is None:
163
- cur.pop(view_id, None)
164
- else:
165
- cur[view_id] = nxt
166
- return cur
167
-
168
- session.runtime.update(VIEWS_KEY, _set, flush="sync")
169
-
170
-
171
- def _mine_or_admin(session, rec):
172
- """Who may EDIT or DELETE a view: its author, or an administrator.
173
-
174
- ⚠ RUNNING IS A DIFFERENT QUESTION and deliberately wider β€” anybody who may read the database
175
- may run any view on it, under their OWN scope. That is the whole of "so we can see different
176
- versions or different things the AI code for us": a colleague's attempt is worth nothing if
177
- only its author can open it.
178
- """
179
- if session.admin or str(rec.get("author") or "") == session.uname:
180
- return
181
- raise err(403, "forbidden", "only the author or an administrator can change this script view")
182
-
183
-
184
- # ── the routes ────────────────────────────────────────────────────────────────────────────────
185
- @router.get("/script-views")
186
- def list_script_views(database: str = "", session: Session = Depends(require_session)):
187
- """Every script view bound to ONE database, newest first. `database` is required."""
188
- key = str(database or "").strip()
189
- if not key:
190
- raise err(400, "no_database", "name the database whose script views you want")
191
- _database_ok(session, key)
192
- rows = [_row(rec) for rec in _all(session.runtime).values()
193
- if isinstance(rec, dict) and str(rec.get("database") or "") == key]
194
- rows.sort(key=lambda r: (r["created"], r["id"]), reverse=True)
195
- return {"database": key, "views": rows, "limits": _limits()}
196
-
197
-
198
- @router.post("/script-views")
199
- def create_script_view(body: dict = Body(default=None),
200
- session: Session = Depends(require_session)):
201
- """Create one. β›” THE SOURCE IS CHECKED BEFORE IT IS STORED, not first at run time.
202
-
203
- A script view that cannot be run is a broken feature the reader discovers by pressing a button,
204
- and the agent that wrote it is long gone by then. `check_source` is pure and costs no process,
205
- so the refusal arrives while the author still has the code in front of them.
206
- """
207
- import secrets # noqa: PLC0415
208
- import core.script_sandbox as sandbox # noqa: PLC0415
209
-
210
- body = body if isinstance(body, dict) else {}
211
- database = str(body.get("database") or "").strip()
212
- if not database:
213
- raise err(400, "no_database", "a script view is bound to one database")
214
- _database_ok(session, database)
215
- # ⭐ `allow_empty` is CREATE's alone - see `_clean_source`. The picker mints a view the
216
- # moment a person chooses the mode, so the empty source is the normal first state, not a slip.
217
- source = _clean_source(body.get("source"), allow_empty=True)
218
- refusal = sandbox.check_source(source)
219
- if refusal is not None:
220
- raise err(400, refusal.code, refusal.message)
221
-
222
- view_id = "sv_" + secrets.token_urlsafe(9)
223
- rec = {"id": view_id, "database": database,
224
- "name": " ".join(str(body.get("name") or "Script view").split())[:MAX_NAME],
225
- "source": source, "author": session.uname, "version": 1,
226
- "created": _now(), "updated": _now(), "history": [], "trimmed": 0}
227
- _put(session, view_id, lambda _prior: rec)
228
- fresh = _all(session.runtime).get(view_id)
229
- if not isinstance(fresh, dict):
230
- # The store took the write and did not record it. A 200 here would tell the author their
231
- # script was saved when it was not.
232
- raise err(503, "store_unavailable", "the script view was NOT created")
233
- return {"view": _row(fresh, source=True), "limits": _limits()}
234
-
235
-
236
- @router.get("/script-views/{view_id}")
237
- def get_script_view(view_id: str, session: Session = Depends(require_session)):
238
- """One view WITH its source and its edit history. Owner item 6's *"see the code"* half."""
239
- rec = _all(session.runtime).get(str(view_id))
240
- if not isinstance(rec, dict):
241
- raise err(404, "no_view", "there is no script view with that id")
242
- _database_ok(session, str(rec.get("database") or ""))
243
- return {"view": _row(rec, source=True), "limits": _limits()}
244
-
245
-
246
- @router.put("/script-views/{view_id}")
247
- def update_script_view(view_id: str, body: dict = Body(default=None),
248
- session: Session = Depends(require_session)):
249
- """A NEW VERSION of one view's source. The prior source is KEPT, never replaced in place."""
250
- import core.script_sandbox as sandbox # noqa: PLC0415
251
-
252
- view_id = str(view_id)
253
- rec = _all(session.runtime).get(view_id)
254
- if not isinstance(rec, dict):
255
- raise err(404, "no_view", "there is no script view with that id")
256
- _mine_or_admin(session, rec)
257
- body = body if isinstance(body, dict) else {}
258
- source = _clean_source(body.get("source"))
259
- refusal = sandbox.check_source(source)
260
- if refusal is not None:
261
- raise err(400, refusal.code, refusal.message)
262
-
263
- def _mutate(prior):
264
- prior = dict(prior or rec)
265
- history = list(prior.get("history") or [])
266
- history.append({"version": int(prior.get("version") or 1),
267
- "source": prior.get("source") or "",
268
- "author": prior.get("author") or "", "created": prior.get("updated") or ""})
269
- dropped = max(0, len(history) - MAX_HISTORY)
270
- prior["history"] = history[dropped:] if dropped else history
271
- prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
272
- prior["source"] = source
273
- prior["version"] = int(prior.get("version") or 1) + 1
274
- prior["updated"] = _now()
275
- if body.get("name"):
276
- prior["name"] = " ".join(str(body["name"]).split())[:MAX_NAME]
277
- return prior
278
-
279
- _put(session, view_id, _mutate)
280
- fresh = _all(session.runtime).get(view_id)
281
- if not isinstance(fresh, dict):
282
- raise err(503, "store_unavailable", "the new version was NOT saved")
283
- return {"view": _row(fresh, source=True), "limits": _limits()}
284
-
285
-
286
- @router.post("/script-views/{view_id}/revert")
287
- def revert_script_view(view_id: str, body: dict = Body(default=None),
288
- session: Session = Depends(require_session)):
289
- """Put one view back to an earlier version. D-338 / W37-T46.
290
-
291
- ⭐⭐ A ROLL-BACK IS A NEW VERSION, NEVER A DELETE OF THE ONES AFTER IT, and that is the whole
292
- point of the ticket rather than an implementation detail. The history is what lets a person
293
- trust an agent with their code: if reverting destroyed the versions it stepped over, one
294
- mistaken revert would cost exactly what the history existed to protect, and there would be no
295
- way back from the way back. So this appends, and `restoredFrom` records where the text came
296
- from β€” the same posture the agent-harness roll-back already takes, so a reader who has seen one
297
- is not surprised by the other.
298
-
299
- β›” IT LIVES ON THE SERVER BECAUSE THE HISTORY DOES. The list door deliberately serves history
300
- entries WITHOUT their source (`_row`: the rail lists names), so a client cannot assemble an old
301
- version's text to re-PUT it. Handing the source out just so the client could send it straight
302
- back would widen a payload for a round trip that does not need to exist, and would make the
303
- revert non-atomic: two calls, and a failure between them leaves the person looking at code that
304
- is not what is stored.
305
- ⚠ `_clean_source` is NOT re-run. The text being restored was already validated when it was
306
- first saved, and a source that a later, stricter rule would now reject is exactly the source a
307
- person is most likely to want back. `check_source` still runs, because the SANDBOX's refusal is
308
- about what the code would DO and that must never be bypassed by a route.
309
- """
310
- import core.script_sandbox as sandbox # noqa: PLC0415
311
-
312
- view_id = str(view_id)
313
- rec = _all(session.runtime).get(view_id)
314
- if not isinstance(rec, dict):
315
- raise err(404, "no_view", "there is no script view with that id")
316
- _mine_or_admin(session, rec)
317
- body = body if isinstance(body, dict) else {}
318
- try:
319
- want = int(body.get("version"))
320
- except (TypeError, ValueError):
321
- raise err(400, "no_version", "say which version to go back to") from None
322
-
323
- history = [h for h in (rec.get("history") or []) if isinstance(h, dict)]
324
- match = next((h for h in history if int(h.get("version") or 0) == want), None)
325
- if match is None:
326
- # β›” TWO REASONS A VERSION IS MISSING AND THEY ARE NOT THE SAME FACT. One was never
327
- # written; the other was TRIMMED off the 40-deep history and the record even counts how
328
- # many. Saying "that version is gone" for the first would be a lie a person could act on.
329
- trimmed = int(rec.get("trimmed") or 0)
330
- if trimmed and want <= trimmed:
331
- raise err(410, "version_trimmed",
332
- f"version {want} is older than this view's history keeps "
333
- f"({trimmed} earlier versions have been dropped)")
334
- raise err(404, "no_version", f"this view has no version {want}")
335
-
336
- source = str(match.get("source") or "")
337
- refusal = sandbox.check_source(source)
338
- if refusal is not None:
339
- # An older version that today's sandbox refuses. The person is told which version and why,
340
- # rather than being handed a 400 about code they did not just type.
341
- raise err(400, refusal.code, f"version {want} cannot be restored: {refusal.message}")
342
-
343
- def _mutate(prior):
344
- prior = dict(prior or rec)
345
- history_now = list(prior.get("history") or [])
346
- history_now.append({"version": int(prior.get("version") or 1),
347
- "source": prior.get("source") or "",
348
- "author": prior.get("author") or "",
349
- "created": prior.get("updated") or ""})
350
- dropped = max(0, len(history_now) - MAX_HISTORY)
351
- prior["history"] = history_now[dropped:] if dropped else history_now
352
- prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
353
- prior["source"] = source
354
- prior["version"] = int(prior.get("version") or 1) + 1
355
- prior["updated"] = _now()
356
- # ⚠ ON THE RECORD, so the history reads as WHAT HAPPENED rather than as a version that
357
- # mysteriously matches an older one. Without it a reader sees v5 and v2 with identical
358
- # code and no way to tell a revert from a coincidence.
359
- prior["restoredFrom"] = want
360
- return prior
361
-
362
- _put(session, view_id, _mutate)
363
- fresh = _all(session.runtime).get(view_id)
364
- if not isinstance(fresh, dict):
365
- raise err(503, "store_unavailable", "the roll-back was NOT saved")
366
- return {"view": _row(fresh, source=True), "restoredFrom": want, "limits": _limits()}
367
-
368
-
369
- @router.delete("/script-views/{view_id}")
370
- def delete_script_view(view_id: str, session: Session = Depends(require_session)):
371
- view_id = str(view_id)
372
- rec = _all(session.runtime).get(view_id)
373
- if not isinstance(rec, dict):
374
- raise err(404, "no_view", "there is no script view with that id")
375
- _mine_or_admin(session, rec)
376
- _put(session, view_id, lambda _prior: None)
377
- return {"deleted": view_id}
378
-
379
-
380
- @router.post("/script-views/{view_id}/run")
381
- def run_script_view(view_id: str, body: dict = Body(default=None),
382
- session: Session = Depends(require_session)):
383
- """CONTRACT C3's run door: `{ok, spec | error, stdout, ms}`.
384
-
385
- β›” `spec` IS A DESCRIPTION THE CLIENT DRAWS. It is never HTML and never text the browser
386
- executes β€” the sandbox refuses a spec carrying an `html`, `script`, `src`, `href` or `on*` key
387
- before this function ever sees it, so a renderer cannot be talked into running something by a
388
- script that was itself perfectly well behaved.
389
-
390
- β›” AND IT IS PLAIN `def`, NOT `async def` β€” see this module's header. A ten-second subprocess
391
- wait on the event loop is a ten-second outage for the whole container.
392
- """
393
- import core.script_sandbox as sandbox # noqa: PLC0415
394
-
395
- rec = _all(session.runtime).get(str(view_id))
396
- if not isinstance(rec, dict):
397
- raise err(404, "no_view", "there is no script view with that id")
398
- database = str(rec.get("database") or "")
399
- # A DRAFT run: the editor sends unsaved code so the author can try it before committing to it.
400
- # It is checked exactly as a stored one is, because "unsaved" is not a permission.
401
- draft = (body or {}).get("source") if isinstance(body, dict) else None
402
- source = _clean_source(draft) if draft else str(rec.get("source") or "")
403
- # ⚠ NO `_database_ok` CALL HERE. `run_view` asks C1 the identical question a line later, and
404
- # asking twice builds a registry topic's pool twice. The three refusals are translated below
405
- # instead, which is the same wall reached through the same door.
406
-
407
- if not _RUN_SLOTS.acquire(blocking=False):
408
- raise err(429, "busy",
409
- f"{MAX_CONCURRENT_RUNS} script views are already running on this server. "
410
- f"Try again in a moment")
411
- try:
412
- out = sandbox.run_view(session.user, database, source, st=session.runtime)
413
- finally:
414
- _RUN_SLOTS.release()
415
-
416
- # β›” C1'S THREE REFUSALS ARE HTTP STATUSES, NOT `ok:false`. "You may not read this database"
417
- # answered 200 would be a permission decision the client has to go looking for, and every
418
- # other door in this app answers 403 for it. Everything BELOW this line is a well-formed
419
- # request whose ANSWER is that the script did not produce a view β€” that is a 200 with
420
- # `ok:false`, the shape `routes_web_agent.test` already uses for the same reason.
421
- if out.get("code") == "unknown_table":
422
- raise err(404, "no_database", out.get("message") or f"there is no database '{database}'")
423
- if out.get("code") == "denied":
424
- raise err(403, "forbidden", out.get("message") or "your account may not read that database")
425
- if out.get("code") == "unresolvable":
426
- refusal = err(409, "unresolvable", out.get("message") or "these rows cannot be served")
427
- refusal.detail["error"]["limit"] = out.get("limit") or {}
428
- raise refusal
429
-
430
- answer = {"ok": bool(out.get("ok")), "spec": out.get("spec"),
431
- "stdout": out.get("stdout") or "", "truncated": bool(out.get("truncated")),
432
- "ms": int(out.get("ms") or 0), "code": out.get("code") or "",
433
- # ⭐ `caps` RIDES ON THE ANSWER (standing rule 1). On a POSIX host all three limits
434
- # were applied; on a Windows host the memory and CPU ones were not, and a screen
435
- # that claims an enforcement which did not happen is the failure the rule is about.
436
- "caps": out.get("caps") or {}}
437
- if not answer["ok"]:
438
- answer["error"] = out.get("message") or "the script view did not produce a view"
439
- return answer
 
1
+ """routes_script_views.py β€” CONTRACT C3: a database View that is a PYTHON SCRIPT (R3 / R5 / R10).
2
+
3
+ Owner item 6, verbatim (2026-08-18): *"Add code script as an interface (database View) so a user
4
+ can build whatever they want through the Agent chat interface. be able to create any dashboard
5
+ they want. User should have the ability to see the code AND the dashboard output of course… Limit
6
+ the code script View per database… Any agent can add into more AI script, so we can see different
7
+ versions or different things the AI code for us."*
8
+
9
+ GET /api/v1/script-views?database=K the views bound to ONE database
10
+ POST /api/v1/script-views create one {database, name?, source}
11
+ GET /api/v1/script-views/{id} one view, its source and its history
12
+ PUT /api/v1/script-views/{id} a NEW VERSION of the source
13
+ DELETE /api/v1/script-views/{id} drop it
14
+ POST /api/v1/script-views/{id}/run run it -> {ok, spec | error, stdout, ms}
15
+ POST /api/v1/script-views/{id}/revert go back to an earlier version {version}
16
+
17
+ ⭐⭐ **R3 IS "SCOPED, NOT CAPPED", AND THE TWO HALVES POINT OPPOSITE WAYS.** *Scoped*: a view may
18
+ read ONLY the database it lives in, and a script that names another database is REFUSED with a
19
+ message naming both. *Not capped*: there is **no limit on how many script views a database may
20
+ carry**, because that is how an agent offers three attempts and the owner picks one. So nothing
21
+ below counts views. What IS bounded is what makes them big β€” one source is capped, and one view's
22
+ edit history is capped and REPORTS what it dropped.
23
+
24
+ β›” **THE RUN IS THE CALLER'S, NEVER THE AUTHOR'S (R5).** `script_sandbox.run_view` is handed
25
+ `session.user`, so a script written by an administrator and opened by a scoped analyst reads the
26
+ ANALYST's rows. The author decides what the code does; the reader decides what it can see.
27
+ ⚠ And the reverse case is safe rather than lucky: a narrowly-scoped author cannot write a script
28
+ that exfiltrates anything, because the only thing a script can return is a render spec drawn on
29
+ the screen of the person who ran it. There is no network, no file and no second reader.
30
+
31
+ β›” **`run` IS `def`, NOT `async def`.** It waits on a subprocess for up to ten seconds; as a
32
+ coroutine that would block the event loop for every other request in the container. FastAPI runs a
33
+ plain `def` in the threadpool, which is what makes one slow script one slow REQUEST.
34
+ """
35
+ import threading
36
+ from datetime import datetime, timezone
37
+
38
+ from fastapi import APIRouter, Body, Depends
39
+
40
+ from deps import Session, err, require_session
41
+
42
+ router = APIRouter(prefix="/api/v1")
43
+
44
+ #: The tenant's script views: `{id: record}`. Per tenant, so it rides `runtime.store_key`.
45
+ VIEWS_KEY = "script_views"
46
+
47
+ MAX_NAME = 80
48
+ MAX_SOURCE_BYTES = 128 * 1024
49
+
50
+ #: Edit history per view. ⚠ NOT a cap on the NUMBER of views (R3 forbids that) β€” a cap on how far
51
+ #: back ONE view's source is kept. Past this the oldest go and `trimmed` counts them, so a reader
52
+ #: can see the history is partial instead of concluding the view was only ever saved twice.
53
+ MAX_HISTORY = 40
54
+
55
+ #: β›” HOW MANY SCRIPTS MAY BE RUNNING IN THIS CONTAINER AT ONCE, and it is a REPORTED refusal
56
+ #: rather than a queue. Each run is a real subprocess with a ten-second wall clock; without this,
57
+ #: holding down refresh forks until the box gives up, and the tenant's ONE FastAPI process is what
58
+ #: gives up. A 429 that says so is honest; an unbounded fork is not.
59
+ MAX_CONCURRENT_RUNS = 4
60
+ _RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
61
+
62
+
63
+ def _now():
64
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
65
+
66
+
67
+ def _all(rt):
68
+ """`{id: record}` for one tenant. `{}` on any failure β€” an unreadable bucket must degrade to
69
+ "this database has no script views", never to a 500 on the view rail."""
70
+ try:
71
+ found = rt.get(VIEWS_KEY) or {}
72
+ except Exception: # noqa: BLE001
73
+ return {}
74
+ return found if isinstance(found, dict) else {}
75
+
76
+
77
+ def _database_ok(session, database):
78
+ """Does this database EXIST, and may this caller read it? Answered by C1, never by a list.
79
+
80
+ β›” `perm_scope.may_read` ALONE IS NOT ENOUGH and the reason is easy to miss: it answers True
81
+ for an ADMIN on any key at all, including one no database answers to. So a create validated
82
+ with `may_read` would let an administrator bind a view to a typo and leave an orphan nothing
83
+ can ever run. `scoped_fields` is the cheap half of C1 (a `ut_*` definition, no rows) and it
84
+ RAISES `UnknownTable`, which is exactly the question being asked.
85
+ """
86
+ import core.perm_scope as perm_scope
87
+ try:
88
+ perm_scope.scoped_fields(session.user, database, st=session.runtime)
89
+ except perm_scope.UnknownTable:
90
+ raise err(404, "no_database", f"there is no database '{database}' in this workspace")
91
+ except perm_scope.Denied:
92
+ raise err(403, "forbidden", f"your account may not read '{database}'")
93
+ except perm_scope.Unresolvable as exc:
94
+ # The database is real and cannot be served under this call's constraints. Standing rule
95
+ # 1's second sentence: report the cause and the recommendation, never a bare refusal.
96
+ raise err(409, "unresolvable", str(exc)) from None
97
+
98
+
99
+ def _clean_source(raw, *, allow_empty=False):
100
+ """The stored source, or a 400. `allow_empty` is CREATE's alone and the asymmetry is the point.
101
+
102
+ ⭐⭐ W37-T41 β€” WHY CREATE MAY BE EMPTY AND SAVE MAY NOT.
103
+ Picking "Custom View" in the mode picker mints the view immediately, before a line of code
104
+ exists, so that `mode === 'script'` always implies a real id and no reader has to carry a
105
+ "the id might be missing" branch (the create semantics handed to lane C in mailbox E-7).
106
+ A view that has been created and not yet written is therefore a REAL, legible state: the editor
107
+ shows its starter placeholder and the Run control is right there.
108
+ A PUT is a different act. It appends a VERSION to a history capped at 40, and blanking a
109
+ working script by saving nothing over it is not an edit anybody means to make. So the guard
110
+ stays exactly where it was on that door, and a person who wants the view gone deletes it.
111
+
112
+ β›” THIS WAS FOUND BY THE GATE, NOT BY READING. `core.script_sandbox.check_source("")` returns
113
+ None, so "an empty script is storable" looked true and was written into a mailbox answer another
114
+ lane was about to build on. The refusal was HERE, one layer above, in a function the sandbox
115
+ knows nothing about. Two validators for one question, disagreeing
116
+ [[one-question-two-normalizers]] β€” and the one that would have bitten a person is the one no
117
+ unit of this feature was asserting.
118
+ """
119
+ source = str(raw or "")
120
+ if not source.strip() and not allow_empty:
121
+ raise err(400, "no_source", "a script view needs some code")
122
+ if len(source.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
123
+ raise err(413, "source_too_long",
124
+ f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of code")
125
+ return source
126
+
127
+
128
+ def _row(rec, *, source=False):
129
+ """One view as the list door reports it. ⚠ NO SOURCE unless asked: the rail lists names."""
130
+ out = {"id": rec.get("id") or "", "database": rec.get("database") or "",
131
+ "name": rec.get("name") or "", "author": rec.get("author") or "",
132
+ "version": int(rec.get("version") or 1),
133
+ "created": rec.get("created") or "", "updated": rec.get("updated") or "",
134
+ "versions": len(rec.get("history") or []) + 1,
135
+ "trimmed": int(rec.get("trimmed") or 0),
136
+ # ⭐ W37-T46: which version this one was RESTORED from, when it was. Present on the
137
+ # row (not only the history) because the editor's header is where a person reads "what
138
+ # am I looking at", and "v5, restored from v2" is the sentence that makes a roll-back
139
+ # legible as an event rather than as a coincidence of matching code.
140
+ "restoredFrom": rec.get("restoredFrom")}
141
+ if source:
142
+ out["source"] = rec.get("source") or ""
143
+ out["history"] = [{"version": int(h.get("version") or 0), "author": h.get("author") or "",
144
+ "created": h.get("created") or "",
145
+ "bytes": len(str(h.get("source") or "").encode("utf-8", "replace"))}
146
+ for h in reversed(rec.get("history") or []) if isinstance(h, dict)]
147
+ return out
148
+
149
+
150
+ def _limits():
151
+ return {"maxSourceBytes": MAX_SOURCE_BYTES, "maxName": MAX_NAME,
152
+ "maxHistory": MAX_HISTORY, "maxConcurrentRuns": MAX_CONCURRENT_RUNS,
153
+ # ⭐ SAID OUT LOUD, because R3's "not capped" half is the one a reader assumes wrong.
154
+ "maxViewsPerDatabase": None}
155
+
156
+
157
+ def _put(session, view_id, mutate):
158
+ """Read-modify-write ONE view, synchronously β€” the client re-reads the rail immediately."""
159
+ def _set(cur):
160
+ cur = dict(cur or {})
161
+ nxt = mutate(cur.get(view_id) if isinstance(cur.get(view_id), dict) else None)
162
+ if nxt is None:
163
+ cur.pop(view_id, None)
164
+ else:
165
+ cur[view_id] = nxt
166
+ return cur
167
+
168
+ session.runtime.update(VIEWS_KEY, _set, flush="sync")
169
+
170
+
171
+ def _mine_or_admin(session, rec):
172
+ """Who may EDIT or DELETE a view: its author, or an administrator.
173
+
174
+ ⚠ RUNNING IS A DIFFERENT QUESTION and deliberately wider β€” anybody who may read the database
175
+ may run any view on it, under their OWN scope. That is the whole of "so we can see different
176
+ versions or different things the AI code for us": a colleague's attempt is worth nothing if
177
+ only its author can open it.
178
+ """
179
+ if session.admin or str(rec.get("author") or "") == session.uname:
180
+ return
181
+ raise err(403, "forbidden", "only the author or an administrator can change this script view")
182
+
183
+
184
+ # ── the routes ────────────────────────────────────────────────────────────────────────────────
185
+ @router.get("/script-views")
186
+ def list_script_views(database: str = "", session: Session = Depends(require_session)):
187
+ """Every script view bound to ONE database, newest first. `database` is required."""
188
+ key = str(database or "").strip()
189
+ if not key:
190
+ raise err(400, "no_database", "name the database whose script views you want")
191
+ _database_ok(session, key)
192
+ rows = [_row(rec) for rec in _all(session.runtime).values()
193
+ if isinstance(rec, dict) and str(rec.get("database") or "") == key]
194
+ rows.sort(key=lambda r: (r["created"], r["id"]), reverse=True)
195
+ return {"database": key, "views": rows, "limits": _limits()}
196
+
197
+
198
+ @router.post("/script-views")
199
+ def create_script_view(body: dict = Body(default=None),
200
+ session: Session = Depends(require_session)):
201
+ """Create one. β›” THE SOURCE IS CHECKED BEFORE IT IS STORED, not first at run time.
202
+
203
+ A script view that cannot be run is a broken feature the reader discovers by pressing a button,
204
+ and the agent that wrote it is long gone by then. `check_source` is pure and costs no process,
205
+ so the refusal arrives while the author still has the code in front of them.
206
+ """
207
+ import secrets # noqa: PLC0415
208
+ import core.script_sandbox as sandbox # noqa: PLC0415
209
+
210
+ body = body if isinstance(body, dict) else {}
211
+ database = str(body.get("database") or "").strip()
212
+ if not database:
213
+ raise err(400, "no_database", "a script view is bound to one database")
214
+ _database_ok(session, database)
215
+ # ⭐ `allow_empty` is CREATE's alone - see `_clean_source`. The picker mints a view the
216
+ # moment a person chooses the mode, so the empty source is the normal first state, not a slip.
217
+ source = _clean_source(body.get("source"), allow_empty=True)
218
+ refusal = sandbox.check_source(source)
219
+ if refusal is not None:
220
+ raise err(400, refusal.code, refusal.message)
221
+
222
+ view_id = "sv_" + secrets.token_urlsafe(9)
223
+ rec = {"id": view_id, "database": database,
224
+ "name": " ".join(str(body.get("name") or "Script view").split())[:MAX_NAME],
225
+ "source": source, "author": session.uname, "version": 1,
226
+ "created": _now(), "updated": _now(), "history": [], "trimmed": 0}
227
+ _put(session, view_id, lambda _prior: rec)
228
+ fresh = _all(session.runtime).get(view_id)
229
+ if not isinstance(fresh, dict):
230
+ # The store took the write and did not record it. A 200 here would tell the author their
231
+ # script was saved when it was not.
232
+ raise err(503, "store_unavailable", "the script view was NOT created")
233
+ return {"view": _row(fresh, source=True), "limits": _limits()}
234
+
235
+
236
+ @router.get("/script-views/{view_id}")
237
+ def get_script_view(view_id: str, session: Session = Depends(require_session)):
238
+ """One view WITH its source and its edit history. Owner item 6's *"see the code"* half."""
239
+ rec = _all(session.runtime).get(str(view_id))
240
+ if not isinstance(rec, dict):
241
+ raise err(404, "no_view", "there is no script view with that id")
242
+ _database_ok(session, str(rec.get("database") or ""))
243
+ return {"view": _row(rec, source=True), "limits": _limits()}
244
+
245
+
246
+ @router.put("/script-views/{view_id}")
247
+ def update_script_view(view_id: str, body: dict = Body(default=None),
248
+ session: Session = Depends(require_session)):
249
+ """A NEW VERSION of one view's source. The prior source is KEPT, never replaced in place."""
250
+ import core.script_sandbox as sandbox # noqa: PLC0415
251
+
252
+ view_id = str(view_id)
253
+ rec = _all(session.runtime).get(view_id)
254
+ if not isinstance(rec, dict):
255
+ raise err(404, "no_view", "there is no script view with that id")
256
+ _mine_or_admin(session, rec)
257
+ body = body if isinstance(body, dict) else {}
258
+ source = _clean_source(body.get("source"))
259
+ refusal = sandbox.check_source(source)
260
+ if refusal is not None:
261
+ raise err(400, refusal.code, refusal.message)
262
+
263
+ def _mutate(prior):
264
+ prior = dict(prior or rec)
265
+ history = list(prior.get("history") or [])
266
+ history.append({"version": int(prior.get("version") or 1),
267
+ "source": prior.get("source") or "",
268
+ "author": prior.get("author") or "", "created": prior.get("updated") or ""})
269
+ dropped = max(0, len(history) - MAX_HISTORY)
270
+ prior["history"] = history[dropped:] if dropped else history
271
+ prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
272
+ prior["source"] = source
273
+ prior["version"] = int(prior.get("version") or 1) + 1
274
+ prior["updated"] = _now()
275
+ if body.get("name"):
276
+ prior["name"] = " ".join(str(body["name"]).split())[:MAX_NAME]
277
+ return prior
278
+
279
+ _put(session, view_id, _mutate)
280
+ fresh = _all(session.runtime).get(view_id)
281
+ if not isinstance(fresh, dict):
282
+ raise err(503, "store_unavailable", "the new version was NOT saved")
283
+ return {"view": _row(fresh, source=True), "limits": _limits()}
284
+
285
+
286
+ @router.post("/script-views/{view_id}/revert")
287
+ def revert_script_view(view_id: str, body: dict = Body(default=None),
288
+ session: Session = Depends(require_session)):
289
+ """Put one view back to an earlier version. D-338 / W37-T46.
290
+
291
+ ⭐⭐ A ROLL-BACK IS A NEW VERSION, NEVER A DELETE OF THE ONES AFTER IT, and that is the whole
292
+ point of the ticket rather than an implementation detail. The history is what lets a person
293
+ trust an agent with their code: if reverting destroyed the versions it stepped over, one
294
+ mistaken revert would cost exactly what the history existed to protect, and there would be no
295
+ way back from the way back. So this appends, and `restoredFrom` records where the text came
296
+ from β€” the same posture the agent-harness roll-back already takes, so a reader who has seen one
297
+ is not surprised by the other.
298
+
299
+ β›” IT LIVES ON THE SERVER BECAUSE THE HISTORY DOES. The list door deliberately serves history
300
+ entries WITHOUT their source (`_row`: the rail lists names), so a client cannot assemble an old
301
+ version's text to re-PUT it. Handing the source out just so the client could send it straight
302
+ back would widen a payload for a round trip that does not need to exist, and would make the
303
+ revert non-atomic: two calls, and a failure between them leaves the person looking at code that
304
+ is not what is stored.
305
+ ⚠ `_clean_source` is NOT re-run. The text being restored was already validated when it was
306
+ first saved, and a source that a later, stricter rule would now reject is exactly the source a
307
+ person is most likely to want back. `check_source` still runs, because the SANDBOX's refusal is
308
+ about what the code would DO and that must never be bypassed by a route.
309
+ """
310
+ import core.script_sandbox as sandbox # noqa: PLC0415
311
+
312
+ view_id = str(view_id)
313
+ rec = _all(session.runtime).get(view_id)
314
+ if not isinstance(rec, dict):
315
+ raise err(404, "no_view", "there is no script view with that id")
316
+ _mine_or_admin(session, rec)
317
+ body = body if isinstance(body, dict) else {}
318
+ try:
319
+ want = int(body.get("version"))
320
+ except (TypeError, ValueError):
321
+ raise err(400, "no_version", "say which version to go back to") from None
322
+
323
+ history = [h for h in (rec.get("history") or []) if isinstance(h, dict)]
324
+ match = next((h for h in history if int(h.get("version") or 0) == want), None)
325
+ if match is None:
326
+ # β›” TWO REASONS A VERSION IS MISSING AND THEY ARE NOT THE SAME FACT. One was never
327
+ # written; the other was TRIMMED off the 40-deep history and the record even counts how
328
+ # many. Saying "that version is gone" for the first would be a lie a person could act on.
329
+ trimmed = int(rec.get("trimmed") or 0)
330
+ if trimmed and want <= trimmed:
331
+ raise err(410, "version_trimmed",
332
+ f"version {want} is older than this view's history keeps "
333
+ f"({trimmed} earlier versions have been dropped)")
334
+ raise err(404, "no_version", f"this view has no version {want}")
335
+
336
+ source = str(match.get("source") or "")
337
+ refusal = sandbox.check_source(source)
338
+ if refusal is not None:
339
+ # An older version that today's sandbox refuses. The person is told which version and why,
340
+ # rather than being handed a 400 about code they did not just type.
341
+ raise err(400, refusal.code, f"version {want} cannot be restored: {refusal.message}")
342
+
343
+ def _mutate(prior):
344
+ prior = dict(prior or rec)
345
+ history_now = list(prior.get("history") or [])
346
+ history_now.append({"version": int(prior.get("version") or 1),
347
+ "source": prior.get("source") or "",
348
+ "author": prior.get("author") or "",
349
+ "created": prior.get("updated") or ""})
350
+ dropped = max(0, len(history_now) - MAX_HISTORY)
351
+ prior["history"] = history_now[dropped:] if dropped else history_now
352
+ prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
353
+ prior["source"] = source
354
+ prior["version"] = int(prior.get("version") or 1) + 1
355
+ prior["updated"] = _now()
356
+ # ⚠ ON THE RECORD, so the history reads as WHAT HAPPENED rather than as a version that
357
+ # mysteriously matches an older one. Without it a reader sees v5 and v2 with identical
358
+ # code and no way to tell a revert from a coincidence.
359
+ prior["restoredFrom"] = want
360
+ return prior
361
+
362
+ _put(session, view_id, _mutate)
363
+ fresh = _all(session.runtime).get(view_id)
364
+ if not isinstance(fresh, dict):
365
+ raise err(503, "store_unavailable", "the roll-back was NOT saved")
366
+ return {"view": _row(fresh, source=True), "restoredFrom": want, "limits": _limits()}
367
+
368
+
369
+ @router.delete("/script-views/{view_id}")
370
+ def delete_script_view(view_id: str, session: Session = Depends(require_session)):
371
+ view_id = str(view_id)
372
+ rec = _all(session.runtime).get(view_id)
373
+ if not isinstance(rec, dict):
374
+ raise err(404, "no_view", "there is no script view with that id")
375
+ _mine_or_admin(session, rec)
376
+ _put(session, view_id, lambda _prior: None)
377
+ return {"deleted": view_id}
378
+
379
+
380
+ @router.post("/script-views/{view_id}/run")
381
+ def run_script_view(view_id: str, body: dict = Body(default=None),
382
+ session: Session = Depends(require_session)):
383
+ """CONTRACT C3's run door: `{ok, spec | error, stdout, ms}`.
384
+
385
+ β›” `spec` IS A DESCRIPTION THE CLIENT DRAWS. It is never HTML and never text the browser
386
+ executes β€” the sandbox refuses a spec carrying an `html`, `script`, `src`, `href` or `on*` key
387
+ before this function ever sees it, so a renderer cannot be talked into running something by a
388
+ script that was itself perfectly well behaved.
389
+
390
+ β›” AND IT IS PLAIN `def`, NOT `async def` β€” see this module's header. A ten-second subprocess
391
+ wait on the event loop is a ten-second outage for the whole container.
392
+ """
393
+ import core.script_sandbox as sandbox # noqa: PLC0415
394
+
395
+ rec = _all(session.runtime).get(str(view_id))
396
+ if not isinstance(rec, dict):
397
+ raise err(404, "no_view", "there is no script view with that id")
398
+ database = str(rec.get("database") or "")
399
+ # A DRAFT run: the editor sends unsaved code so the author can try it before committing to it.
400
+ # It is checked exactly as a stored one is, because "unsaved" is not a permission.
401
+ draft = (body or {}).get("source") if isinstance(body, dict) else None
402
+ source = _clean_source(draft) if draft else str(rec.get("source") or "")
403
+ # ⚠ NO `_database_ok` CALL HERE. `run_view` asks C1 the identical question a line later, and
404
+ # asking twice builds a registry topic's pool twice. The three refusals are translated below
405
+ # instead, which is the same wall reached through the same door.
406
+
407
+ if not _RUN_SLOTS.acquire(blocking=False):
408
+ raise err(429, "busy",
409
+ f"{MAX_CONCURRENT_RUNS} script views are already running on this server. "
410
+ f"Try again in a moment")
411
+ try:
412
+ out = sandbox.run_view(session.user, database, source, st=session.runtime)
413
+ finally:
414
+ _RUN_SLOTS.release()
415
+
416
+ # β›” C1'S THREE REFUSALS ARE HTTP STATUSES, NOT `ok:false`. "You may not read this database"
417
+ # answered 200 would be a permission decision the client has to go looking for, and every
418
+ # other door in this app answers 403 for it. Everything BELOW this line is a well-formed
419
+ # request whose ANSWER is that the script did not produce a view β€” that is a 200 with
420
+ # `ok:false`, the shape `routes_web_agent.test` already uses for the same reason.
421
+ if out.get("code") == "unknown_table":
422
+ raise err(404, "no_database", out.get("message") or f"there is no database '{database}'")
423
+ if out.get("code") == "denied":
424
+ raise err(403, "forbidden", out.get("message") or "your account may not read that database")
425
+ if out.get("code") == "unresolvable":
426
+ refusal = err(409, "unresolvable", out.get("message") or "these rows cannot be served")
427
+ refusal.detail["error"]["limit"] = out.get("limit") or {}
428
+ raise refusal
429
+
430
+ answer = {"ok": bool(out.get("ok")), "spec": out.get("spec"),
431
+ "stdout": out.get("stdout") or "", "truncated": bool(out.get("truncated")),
432
+ "ms": int(out.get("ms") or 0), "code": out.get("code") or "",
433
+ # ⭐ `caps` RIDES ON THE ANSWER (standing rule 1). On a POSIX host all three limits
434
+ # were applied; on a Windows host the memory and CPU ones were not, and a screen
435
+ # that claims an enforcement which did not happen is the failure the rule is about.
436
+ "caps": out.get("caps") or {}}
437
+ if not answer["ok"]:
438
+ answer["error"] = out.get("message") or "the script view did not produce a view"
439
+ return answer
api/routes_slack.py CHANGED
@@ -1,789 +1,789 @@
1
- """routes_slack.py β€” MANAGE AGENT: a bot per Slack channel, walled by the engine that walls a
2
- person. (wave 33, owner item 10 Β· `W33-T38` / `W33-T39` / `W33-T67`.)
3
-
4
- Owner, verbatim (2026-08-14): *"Expand Slack we need to be able to configure an AI bot PER channel
5
- whose permissions we can toggle based on Fields etc of the databases, exactly like how we toggle
6
- permissioning per user."*
7
-
8
- ────────────────────────────────────────────────────────────────────────────────────────────────
9
- β›”β›” D-84 SAID THIS WAS "adapted from OpenTag" AND THAT PREMISE IS FALSE (PRD amendment A1).
10
-
11
- `PENDING.md` D-84 has named OpenTag as the model for per-Slack-channel permissioning since
12
- 2026-08-08. **OpenTag has no permission model to adapt.** `app/runtime-host.ts` is
13
- `identifyUser: () => OPENTAG_SERVICE_USER` β€” ONE constant identity for every request β€” and its own
14
- `sender-context.ts` says the Slack sender is *"informational only… not gating access."* Its
15
- authorization ceiling is whole-MCP-server, decided once at process boot from env vars. It is a
16
- live specimen of identity that LOOKS like a permission and is not.
17
-
18
- `core/perm_scope.py` is already strictly more expressive: per database, per row, per FIELD, per
19
- principal. So item 10 is OUR engine projected onto a CHANNEL principal β€” see `agent_principal`
20
- below, which is the whole projection and is nine lines. Study:
21
- `.claude/wiki/research/opentag-adoption.md` (licence gate: MIT, PASSED).
22
-
23
- What OpenTag genuinely contributes is the WRITE-APPROVAL interceptor (`W33-T67`, `approval_card`
24
- below) and nothing else. Its TRANSPORT is AVOID wholesale β€” hosted CopilotKit Intelligence, a
25
- second Node process, a persistent outbound socket and each tenant's Slack credentials held by a
26
- third party, against ONE process on the HF free tier. The door here is `routes_forms.py`'s proven
27
- unauthenticated-public shape plus Slack's signing-secret check.
28
-
29
- ────────────────────────────────────────────────────────────────────────────────────────────────
30
- ⚠ A CHANNEL IS A PRINCIPAL, NOT A PERSON. The wall binds to the Slack conversation id, so every
31
- human in that channel reads through the same rules. That is the honest reading of "a bot per
32
- channel" and the pane says it out loud, because the alternative is an admin assuming per-person
33
- scoping from a screen that looks exactly like the per-person one.
34
-
35
- ⚠ AND THE IDENTITY IS THE CHANNEL ID, NEVER ITS NAME. A channel can be renamed; its id cannot.
36
- A wall bound to `#sales` silently re-points the day somebody renames the channel.
37
- """
38
- import hmac
39
- import json
40
- import os
41
- import secrets
42
- import time
43
- from datetime import datetime, timezone
44
-
45
- from fastapi import APIRouter, Body, Depends, Request
46
-
47
- from deps import Session, err, require_session
48
- from routes_admin import admin_gate
49
-
50
- router = APIRouter(prefix="/api/v1")
51
-
52
- #: The tenant's channel agents: `{id: record}`. A per-tenant bucket, so it rides
53
- #: `runtime.store_key`'s prefix and never lands in tenant #0's namespace.
54
- AGENTS_KEY = "slack_agents"
55
-
56
- #: Pending mutations awaiting a human's click (`W33-T67`). Server-only, per tenant.
57
- PENDING_KEY = "slack_pending_writes"
58
-
59
- #: How long an approval card stays clickable. An approval is a statement about the world as it was
60
- #: when the card was rendered; an hour later the values it names may no longer be the values it
61
- #: would write. Expiring is the honest behaviour, and an expired card says so rather than 403ing.
62
- APPROVAL_TTL_S = 15 * 60
63
-
64
- #: Slack rejects a replayed request older than 5 minutes; so do we, before any signature work.
65
- SLACK_MAX_SKEW_S = 60 * 5
66
-
67
- MAX_BODY_BYTES = 64 * 1024
68
-
69
- #: β›” ROW-CAPPED BECAUSE AN APPROVER WHO CANNOT READ THE CARD CANNOT APPROVE IT. Copied
70
- #: deliberately from OpenTag's `agent/write_confirmation.py`, which caps for the same reason:
71
- #: past a certain length Slack collapses a message behind "Show more", and a human clicking
72
- #: Approve on a card whose tail they never saw is worse than no card at all.
73
- APPROVAL_MAX_ROWS = 12
74
-
75
-
76
- # ── the tenant's agent records ───────────────────────────────────────────────────────────────
77
- def _agents(rt):
78
- """`{id: record}` for one tenant. `{}` on any failure β€” an unreadable bucket must degrade to
79
- "this tenant has no agents", never to a 500 on the settings pane."""
80
- try:
81
- found = rt.get(AGENTS_KEY) or {}
82
- except Exception: # noqa: BLE001
83
- return {}
84
- return found if isinstance(found, dict) else {}
85
-
86
-
87
- def _clean_agent(raw, prior=None):
88
- """One stored record, built KEY BY KEY.
89
-
90
- β›” Never `dict(raw)` and never `**raw`. This record is the SUBJECT of a permission decision;
91
- a client-supplied key landing in it is a client-supplied input to `perm_scope`. The same rule
92
- `routes_forms._public_form` follows on the way out, applied here on the way in.
93
- """
94
- prior = prior if isinstance(prior, dict) else {}
95
- out = {
96
- "id": str(prior.get("id") or raw.get("id") or ""),
97
- "channel": str(raw.get("channel") or prior.get("channel") or "").strip()[:64],
98
- "channelName": str(raw.get("channelName") or prior.get("channelName") or "").strip()[:80],
99
- "label": " ".join(str(raw.get("label") or prior.get("label") or "").split())[:80],
100
- "active": bool(raw.get("active", prior.get("active", True))),
101
- # β›” DEFAULT TRUE, AND `is not False` RATHER THAN TRUTHINESS. A record written before this
102
- # key existed must read as "approval required": the one direction a default here is
103
- # allowed to be wrong in is the safe one, because an unattended write cannot be undone by
104
- # revoking the bot afterwards [[default-must-pass-its-own-guard]].
105
- "writeApproval": raw.get("writeApproval", prior.get("writeApproval", True)) is not False,
106
- # The permission block. Same shape, same validator, same engine as a user's.
107
- "perms": prior.get("perms") if isinstance(prior.get("perms"), dict) else {},
108
- "perms_v": int(prior.get("perms_v") or 0),
109
- "createdBy": str(prior.get("createdBy") or raw.get("createdBy") or ""),
110
- "createdAt": str(prior.get("createdAt") or raw.get("createdAt") or ""),
111
- }
112
- return out
113
-
114
-
115
- def _put_agent(session, agent_id, mutate):
116
- """Read-modify-write ONE agent under the tenant's bucket, synchronously.
117
-
118
- `flush="sync"` because the client re-reads the list immediately after every write here, and an
119
- async flush would let the refetch win the race and paint the pre-write state β€” the
120
- [[refetch-eats-its-own-write]] shape.
121
- """
122
- def _set(cur):
123
- cur = dict(cur or {})
124
- rec = cur.get(agent_id) if isinstance(cur.get(agent_id), dict) else None
125
- nxt = mutate(rec)
126
- if nxt is None:
127
- cur.pop(agent_id, None)
128
- else:
129
- cur[agent_id] = nxt
130
- return cur
131
-
132
- session.runtime.update(AGENTS_KEY, _set, flush="sync")
133
-
134
-
135
- # ── ⭐⭐ THE PROJECTION β€” THE WHOLE OF "the same engine that permissions a user" ───────────────
136
- def agent_principal(agent):
137
- """A channel agent, as a PRINCIPAL `core/perm_scope` already understands.
138
-
139
- ⭐⭐ THIS IS THE ENTIRE POINT OF THE TICKET AND IT IS NINE LINES. `perm_scope` takes a user
140
- RECORD β€” a plain dict with `perms`, `perms_v` and `role` β€” not a User object and not a session.
141
- So a channel agent carrying a `perms` block simply IS such a record, and `may_access`,
142
- `visible_fields`, `hidden_keys` and `apply_row_scope` work on it unmodified. There is no second
143
- engine, no parallel vocabulary, and nothing about a channel to keep in step with anything about
144
- a person. That is what the owner's *"exactly like how we toggle permissioning per user"* means
145
- when it is true in code rather than in appearance.
146
-
147
- β›” `role` IS HARDCODED NON-ADMIN AND MUST STAY SO. `perm_scope.may_access` returns True
148
- unconditionally for `role == 'admin'` β€” the break-glass clause that keeps the owner out of a
149
- locked store. A bot has no such emergency and no hands: an agent record that could carry
150
- `role: 'admin'` would be one stored key away from bypassing every wall on this page. The key is
151
- not copied from the record; it is written here, every time.
152
-
153
- β›” AND `perms_v` IS FORCED TO THE CURRENT VERSION, which makes an UNDECLARED database DENY
154
- (C-PERM amendment 4). Without it a fresh agent would fall through to `perms.may_open`'s legacy
155
- grant wall and read `modules: 'all'`-shaped defaults β€” i.e. a brand-new bot would start with
156
- access to everything. Fail-closed from the first byte.
157
- """
158
- import core.perm_scope as perm_scope
159
- return {
160
- "username": f"slack:{(agent or {}).get('channel') or '?'}",
161
- "role": "agent",
162
- "perms": (agent or {}).get("perms") or {},
163
- "perms_v": perm_scope.PERMS_VERSION,
164
- # No `bus`, no `agent`: a channel is not a business unit and not a salesperson. Absent
165
- # rather than 'all' β€” `perms.allowed_bu_labels` narrows on absence, which is the direction
166
- # this must fail in.
167
- }
168
-
169
-
170
- def agent_may_read(agent, module):
171
- """May this channel open `module` at all?"""
172
- import core.perm_scope as perm_scope
173
- if not (agent or {}).get("active", True):
174
- return False
175
- return bool(perm_scope.may_access(agent_principal(agent), module))
176
-
177
-
178
- def agent_visible_fields(agent, fields, module):
179
- """`fields` minus this channel's hidden closure β€” the SAME transitive closure a person gets,
180
- so a formula over a hidden column cannot leak it back through arithmetic."""
181
- import core.perm_scope as perm_scope
182
- return perm_scope.visible_fields(fields, agent_principal(agent), module)
183
-
184
-
185
- def agent_rows(agent, rows, module, fields, ctx=None, st=None):
186
- """The rows this channel may receive β€” `permits()`, so an unanswerable permanent filter DENIES
187
- rather than being ignored.
188
-
189
- ⭐⭐ `st` IS THE TENANT HANDLE AND IT IS HERE BECAUSE OF THE SENTENCE IN `agent_principal`:
190
- a channel agent IS a principal of the same wall, so a permanent filter naming a
191
- user-generated column has to mean the SAME thing here as it does on the grid (owner I16).
192
- A door that lends the handle and a door that does not are one stored rule with two meanings.
193
-
194
- ⚠ PASS THE TENANT'S OWN RUNTIME β€” every other store read in this file takes
195
- `session.runtime`, and a channel is not a second tenancy. It is a keyword with a `None`
196
- default for the same reason `perm_scope.apply_row_scope`'s is: without one this is
197
- byte-identical to the wall that shipped before the argument existed.
198
-
199
- ⚠ `hidden_keys` DELIBERATELY DOES NOT TAKE IT IN THIS CHANGE. Its field-grant leg
200
- under-hides without a handle (see `perm_scope.visible_overlays`), which is a real and
201
- separate gap on this surface β€” but it is the FIELD wall, it moves what a channel receives
202
- rather than what I16 asked for, and widening two walls in one ticket is how a permission
203
- change stops being reviewable.
204
- """
205
- import core.perm_scope as perm_scope
206
- p = agent_principal(agent)
207
- hide = perm_scope.hidden_keys(p, module, fields)
208
- kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx, st=st)
209
- # Both wires, never one: the field list and the row payload are separate, and stripping only
210
- # the first leaves the value sitting in the second where anyone can read it.
211
- return [perm_scope.strip_row(r, hide) for r in kept]
212
-
213
-
214
- # ── the credential ───────────────────────────────────────────────────────────────────────────
215
- def slack_creds(rt):
216
- """This TENANT's Slack credentials from its own keychain, or None.
217
-
218
- β›” NO ENVIRONMENT FALLBACK, DELIBERATELY, AND THIS IS D-202's LESSON APPLIED BEFORE IT
219
- HAPPENS AGAIN. Meta Ads shipped loading end-to-end and was still not a connector, because
220
- `keychain.meta_creds` had no caller and the token came from the owner's `.env` β€” making it a
221
- tenant-#0 FACT indistinguishable from a screenshot. `keychain.meta_creds`' own docstring spells
222
- out the rule: handing the environment's credential to a tenant whose admin has not stored one
223
- is the leak the resolver exists to prevent. So a tenant with no entry gets None and the pane
224
- SAYS so.
225
-
226
- ⚠ Reads through `list_entries` + `read_fields` (both public) rather than `keychain._first_creds`
227
- (private, and in a file outside this lane's fence). Same deterministic rule: entries are
228
- id-sorted, so "first" is stable across reads rather than dict-order luck.
229
- """
230
- try:
231
- import core.keychain as keychain
232
- for row in keychain.list_entries(rt):
233
- if str(row.get("type") or "") != "slack":
234
- continue
235
- fields = keychain.read_fields(rt, row.get("id"))
236
- if isinstance(fields, dict) and fields.get("signing_secret"):
237
- return fields
238
- except Exception: # noqa: BLE001
239
- # A locked or unreadable keychain reads as "not configured" for the PANE, which is honest;
240
- # the signature check below fails closed regardless, so this cannot widen anything.
241
- return None
242
- return None
243
-
244
-
245
- # ── the authenticated doors (the Manage agent surface) ───────────────────────────────────────
246
- def _summary(agent, modules):
247
- """One sentence per agent for the list row β€” computed here, because the alternative is one
248
- round trip per row to fill one cell (the same reason `AdminUser.access` exists)."""
249
- # ⭐ W36-T22 / C2 β€” every listed database is governed now; the `enforced` flag it used to
250
- # filter on is DELETED, and `m.get("enforced")` would have gone silently falsy here and
251
- # summarised every agent as "" (no databases at all).
252
- governed = list(modules)
253
- perms = agent.get("perms") or {}
254
- open_n = sum(1 for m in governed if (perms.get(m["key"]) or {}).get("access"))
255
- if not governed:
256
- return ""
257
- if open_n == 0:
258
- return "No access"
259
- restricted = sum(1 for m in governed
260
- if (perms.get(m["key"]) or {}).get("access")
261
- and ((perms.get(m["key"]) or {}).get("filter")
262
- or (perms.get(m["key"]) or {}).get("hiddenFields")))
263
- head = (f"All {open_n} database{'' if open_n == 1 else 's'}" if open_n == len(governed)
264
- else f"{open_n} of {len(governed)} databases")
265
- return f"{head}, {restricted} restricted" if restricted else head
266
-
267
-
268
- @router.get("/agents")
269
- def list_channel_agents(session: Session = Depends(admin_gate)):
270
- """This tenant's channel agents, plus whether Slack is reachable at all."""
271
- import routes_admin
272
- modules = routes_admin._perm_modules(session)
273
- rows = []
274
- for aid, a in sorted(_agents(session.runtime).items()):
275
- if not isinstance(a, dict):
276
- continue
277
- rows.append({"id": aid, "channel": a.get("channel") or "",
278
- "channelName": a.get("channelName") or "",
279
- "label": a.get("label") or "", "active": a.get("active", True) is not False,
280
- "writeApproval": a.get("writeApproval", True) is not False,
281
- "summary": _summary(a, modules)})
282
- return {"agents": rows, "configured": slack_creds(session.runtime) is not None}
283
-
284
-
285
- @router.post("/agents")
286
- def create_channel_agent(body: dict = Body(default=None),
287
- session: Session = Depends(admin_gate)):
288
- body = body if isinstance(body, dict) else {}
289
- channel = str(body.get("channel") or "").strip()
290
- if not channel:
291
- raise err(400, "no_channel", "a Slack channel ID is required")
292
- existing = _agents(session.runtime)
293
- # ⚠ ONE AGENT PER CHANNEL. Two records for one conversation would mean two walls, and nothing
294
- # anywhere decides which one applies β€” the [[one-question-two-normalizers]] shape, in the one
295
- # place where the two answers are "may read" and "may not".
296
- for a in existing.values():
297
- if isinstance(a, dict) and str(a.get("channel") or "") == channel:
298
- raise err(409, "channel_taken",
299
- "that channel already has an agent β€” edit it instead of adding a second")
300
- aid = secrets.token_urlsafe(9)
301
- rec = _clean_agent(dict(body, id=aid, createdBy=session.uname,
302
- createdAt=datetime.now(timezone.utc).isoformat(timespec="seconds")))
303
- _put_agent(session, aid, lambda _prior: rec)
304
- fresh = _agents(session.runtime).get(aid)
305
- if not isinstance(fresh, dict):
306
- # The store took the write and did not record it. A 200 here would tell an administrator
307
- # the agent exists when it does not.
308
- raise err(503, "store_unavailable", "the agent was NOT created")
309
- return {"agent": {"id": aid, "channel": rec["channel"], "channelName": rec["channelName"],
310
- "label": rec["label"], "active": rec["active"],
311
- "writeApproval": rec["writeApproval"], "summary": "No access"}}
312
-
313
-
314
- @router.get("/agents/{agent_id}")
315
- def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
316
- """The agent PLUS the permission envelope β€” the SAME shape `get_perms` answers with.
317
-
318
- ⭐ ONE PAYLOAD SHAPE FOR TWO ROOMS. `permsModel.parsePermsPayload` parses this, and
319
- `settings/ModulePermsList` renders it, because they are literally the same client code. A
320
- second envelope here would mean a second parser and a second set of defaults within a wave.
321
- """
322
- import routes_admin
323
- a = _agents(session.runtime).get(str(agent_id))
324
- if not isinstance(a, dict):
325
- raise err(404, "no_such_agent", "no agent with that id")
326
- modules = routes_admin._perm_modules(session)
327
- # ⭐⭐ W36-T22 / C2 β€” EVERY listed database, `ut_*` included. β›” THIS IS WHY THE FLAG'S
328
- # DELETION IS NOT A ONE-FILE CHANGE: `m.get("enforced")` on a row that no longer carries the
329
- # key is None, so this list would have been EMPTY and the channel perms editor would have
330
- # governed ZERO databases while looking entirely correct. A Slack channel is a principal of
331
- # the SAME wall (`verify_perm_scope` section H) and gets the same catalogue.
332
- governed = [m["key"] for m in modules]
333
- stored = a.get("perms") or {}
334
- principal = agent_principal(a)
335
- import core.perm_scope as perm_scope
336
- perms_out = {}
337
- for k in governed:
338
- e = stored.get(k)
339
- # β›” W36-T22 β€” `may_read`, the same evaluator the read door uses, for the reason spelled
340
- # out at `routes_admin.get_perms`. ⚠ It answers DIFFERENTLY here and correctly so: a
341
- # channel agent is not a person with a share, so a `ut_*` key it has not been granted
342
- # defaults CLOSED β€” which is the fail-closed direction for a bot, and the same answer the
343
- # table routes would give it.
344
- perms_out[k] = e if isinstance(e, dict) else {
345
- "access": bool(perm_scope.may_read(principal, k, st=session.runtime)),
346
- "filter": None, "hiddenFields": []}
347
- return {"id": str(agent_id), "channel": a.get("channel") or "",
348
- "channelName": a.get("channelName") or "", "label": a.get("label") or "",
349
- "active": a.get("active", True) is not False,
350
- "writeApproval": a.get("writeApproval", True) is not False,
351
- "perms": perms_out,
352
- # β›” ALWAYS THE CURRENT VERSION, because `agent_principal` forces it: the editor must
353
- # render "undeclared = denied", not the legacy-grant reading it would show at 0.
354
- "perms_v": perm_scope.PERMS_VERSION,
355
- # A bot is NEVER an admin β€” see `agent_principal`. Sent so the editor never paints
356
- # the "Everything (admin)" state for a principal that cannot have it.
357
- "is_admin": False,
358
- "modules": modules,
359
- "fields_by_module": {k: routes_admin._module_fields(k, session=session)
360
- for k in governed}}
361
-
362
-
363
- @router.put("/agents/{agent_id}/perms")
364
- def put_channel_agent_perms(agent_id: str, body: dict = Body(default=None),
365
- session: Session = Depends(admin_gate)):
366
- """Replace this agent's permission block wholesale β€” the same validator a user's block gets."""
367
- import routes_admin
368
- body = body if isinstance(body, dict) else {}
369
- if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
370
- raise err(404, "no_such_agent", "no agent with that id")
371
- if "perms" not in body:
372
- raise err(400, "empty_patch", "no perms to save")
373
- mods = routes_admin._perm_modules(session)
374
- # ⭐ THE SAME `_clean_perms`, NOT A COPY OF IT. It refuses a filter this module cannot
375
- # evaluate, refuses a hiddenFields key that names nothing, and refuses a BU condition the
376
- # pushdown cannot read. Every one of those is exactly as true for a channel as for a person,
377
- # and a second validator here is a second place for one of them to go missing.
378
- # ⚠ CORRECTED W36-T22: this list used to end "refuses an unenforced `ut_*` key". That refusal
379
- # is DELETED β€” W36-T21 armed the wall over every database, so there is no unenforced key left
380
- # to refuse, and a comment naming a rule that no longer exists is how the next wave re-derives
381
- # it ([[two-gates-can-assert-opposite-things]]).
382
- cleaned = routes_admin._clean_perms(
383
- body.get("perms"),
384
- governed_keys={m["key"] for m in mods}, session=session) or {}
385
-
386
- import core.perm_scope as perm_scope
387
-
388
- def _mut(prior):
389
- if not isinstance(prior, dict):
390
- return None
391
- nxt = dict(prior)
392
- nxt["perms"] = cleaned
393
- nxt["perms_v"] = perm_scope.PERMS_VERSION
394
- return nxt
395
-
396
- _put_agent(session, str(agent_id), _mut)
397
- fresh = _agents(session.runtime).get(str(agent_id)) or {}
398
- if (fresh.get("perms") or {}) != cleaned:
399
- # The one direction this must never fail in: telling an administrator the wall is up when
400
- # it is not.
401
- raise err(503, "store_unavailable", "the permissions were not saved β€” the agent is UNCHANGED")
402
- return {"id": str(agent_id), "perms": fresh.get("perms") or {},
403
- "perms_v": int(fresh.get("perms_v") or 0)}
404
-
405
-
406
- @router.patch("/agents/{agent_id}")
407
- def patch_channel_agent(agent_id: str, body: dict = Body(default=None),
408
- session: Session = Depends(admin_gate)):
409
- body = body if isinstance(body, dict) else {}
410
- if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
411
- raise err(404, "no_such_agent", "no agent with that id")
412
- #: β›” `perms` IS NOT PATCHABLE HERE. It has its own door with its own validator; accepting it
413
- #: on the metadata route would be a second, unvalidated way to write the wall.
414
- allowed = {k: v for k, v in body.items()
415
- if k in ("label", "active", "writeApproval", "channelName")}
416
- if not allowed:
417
- raise err(400, "empty_patch", "nothing to change")
418
-
419
- def _mut(prior):
420
- return _clean_agent(allowed, prior=prior) if isinstance(prior, dict) else None
421
-
422
- _put_agent(session, str(agent_id), _mut)
423
- import routes_admin
424
- a = _agents(session.runtime).get(str(agent_id)) or {}
425
- return {"agent": {"id": str(agent_id), "channel": a.get("channel") or "",
426
- "channelName": a.get("channelName") or "", "label": a.get("label") or "",
427
- "active": a.get("active", True) is not False,
428
- "writeApproval": a.get("writeApproval", True) is not False,
429
- "summary": _summary(a, routes_admin._perm_modules(session))}}
430
-
431
-
432
- @router.delete("/agents/{agent_id}")
433
- def delete_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
434
- if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
435
- raise err(404, "no_such_agent", "no agent with that id")
436
- _put_agent(session, str(agent_id), lambda _prior: None)
437
- if isinstance(_agents(session.runtime).get(str(agent_id)), dict):
438
- raise err(503, "store_unavailable", "the agent was NOT removed")
439
- return {"ok": True}
440
-
441
-
442
- # ── ⭐ W33-T67: THE WRITE-APPROVAL GATE ───────────────────────────────────────────────────────
443
- def _is_empty(value):
444
- """Is this value ABSENT, as opposed to falsy?
445
-
446
- β›” COPIED EXACTLY FROM OpenTag's `agent/write_confirmation.py`, and the exactness is the point:
447
- `0` and `False` are VALUES a human must see on the card. Setting a price to 0 or a flag to
448
- False is precisely the kind of write somebody needs to approve, and a naive `if not value`
449
- drops both rows silently β€” the approver then reads a card that does not describe the write
450
- they are approving. The MIT licence gate for this borrowing is recorded in
451
- `.claude/wiki/research/opentag-adoption.md`.
452
- """
453
- return value is None or (isinstance(value, str) and value.strip() == "")
454
-
455
-
456
- def approval_card(action, values, agent=None):
457
- """The card a human reads before a bot writes. `{action, rows, truncated, note}`.
458
-
459
- β›” ROW-CAPPED, and the cap is a SAFETY property rather than a layout one: past a certain
460
- length Slack collapses a message behind "Show more", and **an approver who cannot read the
461
- card cannot approve it.** When rows are dropped the card SAYS how many β€” a truncation nobody
462
- was told about is the violation, not the truncation (wave-30 R6's second sentence).
463
- """
464
- rows = [{"field": str(k), "value": v}
465
- for k, v in (values or {}).items() if not _is_empty(v)]
466
- rows.sort(key=lambda r: r["field"])
467
- shown, dropped = rows[:APPROVAL_MAX_ROWS], max(0, len(rows) - APPROVAL_MAX_ROWS)
468
- return {
469
- "action": str(action or "")[:80],
470
- "rows": shown,
471
- "truncated": dropped,
472
- "note": (f"{dropped} more field(s) not shown β€” open the record to review them before "
473
- f"approving." if dropped else ""),
474
- "agent": (agent or {}).get("label") or (agent or {}).get("channel") or "",
475
- }
476
-
477
-
478
- def intercept_write(agent, action, values, stash):
479
- """THE INTERCEPTOR. Returns `("commit", None)` or `("await_approval", card)`.
480
-
481
- ⭐ The one thing worth taking from OpenTag: a MUTATING tool call is halted, rendered as a card
482
- naming the action and its values, and committed only on an explicit human accept. Everything
483
- else in that repo β€” the transport, the runtime, the identity model β€” is AVOID (amendment A1).
484
-
485
- β›” FAIL-CLOSED ON A MISSING FLAG: `is not False`, so a record written before `writeApproval`
486
- existed requires approval. The unsafe direction here is not recoverable β€” revoking a bot does
487
- not un-write what it wrote.
488
- """
489
- if (agent or {}).get("writeApproval", True) is not False:
490
- card = approval_card(action, values, agent)
491
- stash(card)
492
- return "await_approval", card
493
- return "commit", None
494
-
495
-
496
- def _pending(rt):
497
- try:
498
- found = rt.get(PENDING_KEY) or {}
499
- except Exception: # noqa: BLE001
500
- return {}
501
- return found if isinstance(found, dict) else {}
502
-
503
-
504
- def stash_pending(rt, agent, action, values, now=None):
505
- """Store one awaiting-approval mutation and return its token.
506
-
507
- The token is what rides the card's button, so it is `secrets.token_urlsafe` and not the
508
- action's id: a guessable value on an unauthenticated door is a way to approve somebody else's
509
- write. Server-only bucket, per tenant, exactly as `routes_forms.TOKENS_KEY` is.
510
- """
511
- token = secrets.token_urlsafe(18)
512
- row = {"at": float(now if now is not None else time.time()),
513
- "channel": str((agent or {}).get("channel") or ""),
514
- "action": str(action or "")[:80],
515
- "values": values if isinstance(values, dict) else {}}
516
- rt.update(PENDING_KEY, lambda cur: {**(cur or {}), token: row}, flush="sync")
517
- return token
518
-
519
-
520
- #: `{action kind: fn(rt, row) -> None}`. Registered by whatever can actually perform a mutation.
521
- #:
522
- #: β›”β›” EMPTY IN PRODUCTION TODAY, AND SAYING SO IS THE POINT. `commit_pending` below is the ONE
523
- #: place an approved write may be performed, so it is the place a negative control can bite β€” but
524
- #: a gate is only as honest as what it guards. Until something registers here, an approved card
525
- #: performs NOTHING and `commit_pending` returns `no_committer` rather than pretending. That is a
526
- #: declared absence, not a silent one [[flag-shipped-without-its-writer]].
527
- _COMMITTERS = {}
528
-
529
-
530
- def register_committer(kind, fn):
531
- """Declare who may perform an approved mutation of `kind`. Idempotent by key."""
532
- _COMMITTERS[str(kind)] = fn
533
-
534
-
535
- def commit_pending(rt, token, approved, now=None):
536
- """Resolve ONE approval card. Returns one of
537
- `expired` Β· `unknown` Β· `rejected` Β· `no_committer` Β· `committed` Β· `failed`.
538
-
539
- β›”β›” THIS IS THE WRITE GATE, AND IT IS A SEPARATE FUNCTION FROM THE ROUTE ON PURPOSE. T67's
540
- `done-when` asks for an NC proving a REJECTED card writes nothing. A control aimed at the
541
- route could not bite while the route had no write in it at all β€” it would stay green with the
542
- guard deleted, because there would be nothing for the guard to be protecting anything from
543
- ([[gate-can-report-green-on-nothing]], and a verifier caught exactly that on this ticket's
544
- first draft). Putting the commit behind ONE named seam gives the control a real subject: the
545
- gate registers a recorder, and `rejected` must leave it untouched while `approve` must call it
546
- exactly once.
547
-
548
- β›” THE TOKEN IS CONSUMED BEFORE EITHER BRANCH, and before any committer runs. A card that
549
- survives its own click is a replayable write, and "approve twice" must never mean "write
550
- twice". The delete is `flush="sync"` for the same reason.
551
- """
552
- now = float(now if now is not None else time.time())
553
- row = _pending(rt).get(str(token))
554
- if not isinstance(row, dict):
555
- return "unknown"
556
- # Consume FIRST β€” before the TTL verdict, before the approve/reject branch, before any write.
557
- rt.update(PENDING_KEY,
558
- lambda cur: {k: v for k, v in (cur or {}).items() if k != str(token)},
559
- flush="sync")
560
- if now - float(row.get("at") or 0) > APPROVAL_TTL_S:
561
- return "expired"
562
- if not approved:
563
- # β›” NOTHING BELOW THIS LINE RUNS FOR A REJECTED CARD. The whole gate is this return.
564
- return "rejected"
565
- fn = _COMMITTERS.get(str(row.get("action") or ""))
566
- if fn is None:
567
- return "no_committer"
568
- try:
569
- fn(rt, row)
570
- except Exception: # noqa: BLE001
571
- # A committer that raises must not read as a commit. The card is already consumed, so the
572
- # honest report is that it failed, and the human asks again.
573
- return "failed"
574
- return "committed"
575
-
576
-
577
- # ── the UNAUTHENTICATED Slack door ───────────────────────────────────────────────────────────
578
- #: Sliding window, keyed on the SLACK TEAM, never the client IP.
579
- #:
580
- #: β›” WHY NOT THE IP, WHICH IS WHAT `routes_forms` DOES. Every Slack event arrives from Slack's own
581
- #: infrastructure, so an IP window is one shared bucket for every workspace on the platform: one
582
- #: busy tenant would spend the allowance for all of them, and the symptom would be another
583
- #: tenant's bot going quiet. The team id is the closest thing to the actual noisy party.
584
- #: ⚠ It is attacker-CONTROLLED before the signature is checked, so the window is applied AFTER
585
- #: verification, never before β€” an unsigned request is refused on cost grounds anyway (a signature
586
- #: check is a single HMAC).
587
- RATE_WINDOW_S, RATE_PER_WINDOW = 60, 60
588
- _HITS: dict = {}
589
-
590
-
591
- def _rate_ok(key, now):
592
- seen = [t for t in _HITS.get(key, ()) if now - t < RATE_WINDOW_S]
593
- seen.append(now)
594
- _HITS[key] = seen
595
- if len(_HITS) > 4096:
596
- for k in [k for k, v in _HITS.items() if not v or now - v[-1] > RATE_WINDOW_S]:
597
- _HITS.pop(k, None)
598
- return len(seen) <= RATE_PER_WINDOW
599
-
600
-
601
- async def _raw_body(request):
602
- """The body as RAW BYTES, capped.
603
-
604
- β›”β›” RAW, NOT PARSED, AND THAT IS NOT A STYLE CHOICE. Slack signs the literal string
605
- `v0:{timestamp}:{body}` byte for byte. `routes_forms._bounded_body` β€” the function this is
606
- otherwise copied from β€” returns only the parsed dict and DISCARDS the bytes, so a verbatim
607
- copy of it could not verify a Slack signature at all: re-serialising the dict changes
608
- whitespace and key order and the HMAC no longer matches. The bug would look like "Slack
609
- signatures are always invalid", which is indistinguishable from a wrong secret.
610
-
611
- ⚠ And it streams rather than calling `request.body()`: FastAPI would otherwise have buffered
612
- the whole body before the handler's first line, so a content-length check inside the handler
613
- caps nothing (`routes_forms`' own scar, recorded in its docstring).
614
- """
615
- size, chunks = 0, []
616
- async for chunk in request.stream():
617
- size += len(chunk)
618
- if size > MAX_BODY_BYTES:
619
- raise err(413, "body_too_large", "that request is too large")
620
- chunks.append(chunk)
621
- return b"".join(chunks)
622
-
623
-
624
- def _refuse():
625
- """ONE refusal for every reason. No oracle.
626
-
627
- A wrong signature, a stale timestamp, an unknown team, an unconfigured tenant and a channel
628
- with no agent all answer identically β€” otherwise the door tells an unauthenticated caller
629
- which tenants exist and which channels are configured, which is the question it was built to
630
- not answer. `routes_forms._refuse` takes the same posture for the same reason.
631
- """
632
- return err(403, "bad_request", "that request could not be verified")
633
-
634
-
635
- def _verify(secret, timestamp, raw, signature, now):
636
- """Slack's v0 signature, with the replay window checked FIRST."""
637
- try:
638
- ts = int(str(timestamp or "0"))
639
- except ValueError:
640
- return False
641
- if abs(now - ts) > SLACK_MAX_SKEW_S:
642
- return False
643
- base = b"v0:" + str(ts).encode("ascii") + b":" + (raw or b"")
644
- import hashlib
645
- expected = "v0=" + hmac.new(str(secret).encode("utf-8"), base, hashlib.sha256).hexdigest()
646
- return hmac.compare_digest(expected, str(signature or ""))
647
-
648
-
649
- def _resolve_tenant(raw, timestamp, signature, now):
650
- """`(slug, runtime, creds)` for the tenant whose signing secret verifies this request.
651
-
652
- β›” THE TENANT IS DECIDED BY THE SIGNATURE, NEVER BY THE PAYLOAD. A body-supplied `team_id`
653
- would let an unauthenticated caller name the tenant it wants to be β€” the exact widening
654
- `deps._user_for`'s tenant-equality check closes on the authenticated side. So every configured
655
- tenant's secret is tried and the one that VERIFIES names the tenant.
656
-
657
- ⚠ NO EARLY `break` ON A FAILED CANDIDATE and no per-tenant error: the loop's cost must not
658
- depend on which tenant matched. `routes_forms._resolve` walks tenants the same way, for the
659
- same reason β€” a public door has no session to ask.
660
- """
661
- from harness import runtime as _rt
662
- hit = None
663
- try:
664
- slugs = list(_rt.known_tenants())
665
- except Exception: # noqa: BLE001
666
- return None, None, None
667
- for slug in slugs:
668
- try:
669
- rt = _rt.get_runtime(slug)
670
- except Exception: # noqa: BLE001
671
- continue
672
- creds = slack_creds(rt)
673
- if not creds:
674
- continue
675
- if _verify(creds.get("signing_secret"), timestamp, raw, signature, now) and hit is None:
676
- hit = (slug, rt, creds)
677
- return hit if hit else (None, None, None)
678
-
679
-
680
- @router.post("/slack/events")
681
- async def slack_events(request: Request):
682
- """Slack's Events API. UNAUTHENTICATED BY CONSTRUCTION β€” no `Depends(require_session)`.
683
-
684
- ⭐ Built like `routes_forms.py`'s public door and not like OpenTag's: one process, no vendor,
685
- no second runtime, no persistent outbound socket, and this tenant's Slack secret never leaves
686
- this deployment (amendment A1).
687
- """
688
- now = time.time()
689
- raw = await _raw_body(request)
690
- ts = request.headers.get("x-slack-request-timestamp")
691
- sig = request.headers.get("x-slack-signature")
692
- slug, rt, _creds = _resolve_tenant(raw, ts, sig, now)
693
- if not rt:
694
- raise _refuse()
695
-
696
- try:
697
- payload = json.loads(raw or b"{}")
698
- except ValueError:
699
- raise _refuse()
700
- if not isinstance(payload, dict):
701
- raise _refuse()
702
-
703
- # Slack's one-time endpoint handshake. Answered ONLY after the signature verified β€” an
704
- # unsigned challenge echo would confirm the endpoint exists to anyone who probes it.
705
- if payload.get("type") == "url_verification":
706
- return {"challenge": str(payload.get("challenge") or "")[:512]}
707
-
708
- team = str(payload.get("team_id") or slug)
709
- if not _rate_ok(f"{slug}:{team}", now):
710
- raise err(429, "too_many_requests", "too many requests β€” wait a moment and try again")
711
-
712
- event = payload.get("event") if isinstance(payload.get("event"), dict) else {}
713
- channel = str(event.get("channel") or "")
714
- agent = None
715
- for a in _agents(rt).values():
716
- if isinstance(a, dict) and str(a.get("channel") or "") == channel:
717
- agent = a
718
- break
719
- # β›” NO AGENT, OR AN INACTIVE ONE, IS SILENCE β€” a 200 with no action. Not a 403: Slack retries
720
- # a non-2xx up to three times, so refusing here would turn "this channel is not configured"
721
- # into three refusals per message, and the retry storm would be the only visible symptom.
722
- # ⚠ And it must not say WHICH β€” a distinguishable answer tells an unauthenticated caller which
723
- # channels this workspace has configured.
724
- if not isinstance(agent, dict) or agent.get("active", True) is False:
725
- return {"ok": True}
726
-
727
- # β›”β›” THE ANSWERING HALF IS NOT BUILT YET, AND SAYING SO IS THE POINT. What ships here is the
728
- # DOOR and the WALL: a verified request, resolved to a tenant by signature, matched to a
729
- # channel agent whose `perms` block is a `perm_scope` principal (`agent_principal`). Composing
730
- # a reply means an LLM call on the cheap-first ladder plus the read path, and a half-built
731
- # answerer that returns something plausible is worse than one that returns nothing.
732
- # Booked rather than faked [[flag-shipped-without-its-writer]].
733
- return {"ok": True}
734
-
735
-
736
- @router.post("/slack/interact")
737
- async def slack_interact(request: Request):
738
- """The approval card's button (`W33-T67`). UNAUTHENTICATED, signature-verified, same shape."""
739
- now = time.time()
740
- raw = await _raw_body(request)
741
- slug, rt, _creds = _resolve_tenant(raw, request.headers.get("x-slack-request-timestamp"),
742
- request.headers.get("x-slack-signature"), now)
743
- if not rt:
744
- raise _refuse()
745
- # Slack posts interactions as `application/x-www-form-urlencoded` with a `payload=` field.
746
- from urllib.parse import parse_qs
747
- try:
748
- form = parse_qs(raw.decode("utf-8"))
749
- payload = json.loads((form.get("payload") or ["{}"])[0])
750
- except Exception: # noqa: BLE001
751
- raise _refuse()
752
- if not isinstance(payload, dict):
753
- raise _refuse()
754
- if not _rate_ok(f"{slug}:interact", now):
755
- raise err(429, "too_many_requests", "too many requests β€” wait a moment and try again")
756
-
757
- actions = payload.get("actions") if isinstance(payload.get("actions"), list) else []
758
- choice = (actions[0] if actions and isinstance(actions[0], dict) else {})
759
- token = str(choice.get("value") or "")
760
- # ⭐ ANYTHING THAT IS NOT LITERALLY "approve" IS A REJECT. Fail-closed on a malformed,
761
- # truncated or unknown action id: the direction that can be wrong here without anyone
762
- # noticing is the one that writes.
763
- approved = str(choice.get("action_id") or "") == "approve"
764
- # β›” THE ROUTE DOES NOT DECIDE β€” `commit_pending` does, and it is the ONE seam a negative
765
- # control can aim at. Consumption, the TTL, the reject branch and the committer lookup all
766
- # live there; this handler only turns its verdict into a sentence.
767
- verdict = commit_pending(rt, token, approved, now=now)
768
- return {"text": {
769
- # An unknown, already-used or expired token is not an error: a person clicking a stale
770
- # card should be told it is stale, not shown a failure.
771
- "unknown": "That approval is no longer available. Ask the bot again.",
772
- "expired": "That approval expired before it was answered. Ask the bot again.",
773
- "rejected": "Rejected. Nothing was changed.",
774
- # ⚠ HONEST, not reassuring: the answering half that would register a committer is booked,
775
- # so an approved card today performs nothing and says exactly that rather than "Approved."
776
- "no_committer": "Approved β€” but this workspace has nothing configured to carry it out yet.",
777
- "failed": "That change could not be completed. Nothing was saved; ask the bot again.",
778
- "committed": "Approved.",
779
- }.get(verdict, "That approval is no longer available. Ask the bot again.")}
780
-
781
-
782
- @router.get("/slack/health")
783
- def slack_health(session: Session = Depends(require_session)):
784
- """Is Slack configured for THIS tenant? Session-gated, and it answers about one tenant only β€”
785
- enumerating the others would answer a question about our customer list."""
786
- creds = slack_creds(session.runtime)
787
- return {"configured": creds is not None,
788
- "agents": len(_agents(session.runtime)),
789
- "hasBotToken": bool((creds or {}).get("bot_token"))}
 
1
+ """routes_slack.py β€” MANAGE AGENT: a bot per Slack channel, walled by the engine that walls a
2
+ person. (wave 33, owner item 10 Β· `W33-T38` / `W33-T39` / `W33-T67`.)
3
+
4
+ Owner, verbatim (2026-08-14): *"Expand Slack we need to be able to configure an AI bot PER channel
5
+ whose permissions we can toggle based on Fields etc of the databases, exactly like how we toggle
6
+ permissioning per user."*
7
+
8
+ ────────────────────────────────────────────────────────────────────────────────────────────────
9
+ β›”β›” D-84 SAID THIS WAS "adapted from OpenTag" AND THAT PREMISE IS FALSE (PRD amendment A1).
10
+
11
+ `PENDING.md` D-84 has named OpenTag as the model for per-Slack-channel permissioning since
12
+ 2026-08-08. **OpenTag has no permission model to adapt.** `app/runtime-host.ts` is
13
+ `identifyUser: () => OPENTAG_SERVICE_USER` β€” ONE constant identity for every request β€” and its own
14
+ `sender-context.ts` says the Slack sender is *"informational only… not gating access."* Its
15
+ authorization ceiling is whole-MCP-server, decided once at process boot from env vars. It is a
16
+ live specimen of identity that LOOKS like a permission and is not.
17
+
18
+ `core/perm_scope.py` is already strictly more expressive: per database, per row, per FIELD, per
19
+ principal. So item 10 is OUR engine projected onto a CHANNEL principal β€” see `agent_principal`
20
+ below, which is the whole projection and is nine lines. Study:
21
+ `.claude/wiki/research/opentag-adoption.md` (licence gate: MIT, PASSED).
22
+
23
+ What OpenTag genuinely contributes is the WRITE-APPROVAL interceptor (`W33-T67`, `approval_card`
24
+ below) and nothing else. Its TRANSPORT is AVOID wholesale β€” hosted CopilotKit Intelligence, a
25
+ second Node process, a persistent outbound socket and each tenant's Slack credentials held by a
26
+ third party, against ONE process on the HF free tier. The door here is `routes_forms.py`'s proven
27
+ unauthenticated-public shape plus Slack's signing-secret check.
28
+
29
+ ────────────────────────────────────────────────────────────────────────────────────────────────
30
+ ⚠ A CHANNEL IS A PRINCIPAL, NOT A PERSON. The wall binds to the Slack conversation id, so every
31
+ human in that channel reads through the same rules. That is the honest reading of "a bot per
32
+ channel" and the pane says it out loud, because the alternative is an admin assuming per-person
33
+ scoping from a screen that looks exactly like the per-person one.
34
+
35
+ ⚠ AND THE IDENTITY IS THE CHANNEL ID, NEVER ITS NAME. A channel can be renamed; its id cannot.
36
+ A wall bound to `#sales` silently re-points the day somebody renames the channel.
37
+ """
38
+ import hmac
39
+ import json
40
+ import os
41
+ import secrets
42
+ import time
43
+ from datetime import datetime, timezone
44
+
45
+ from fastapi import APIRouter, Body, Depends, Request
46
+
47
+ from deps import Session, err, require_session
48
+ from routes_admin import admin_gate
49
+
50
+ router = APIRouter(prefix="/api/v1")
51
+
52
+ #: The tenant's channel agents: `{id: record}`. A per-tenant bucket, so it rides
53
+ #: `runtime.store_key`'s prefix and never lands in tenant #0's namespace.
54
+ AGENTS_KEY = "slack_agents"
55
+
56
+ #: Pending mutations awaiting a human's click (`W33-T67`). Server-only, per tenant.
57
+ PENDING_KEY = "slack_pending_writes"
58
+
59
+ #: How long an approval card stays clickable. An approval is a statement about the world as it was
60
+ #: when the card was rendered; an hour later the values it names may no longer be the values it
61
+ #: would write. Expiring is the honest behaviour, and an expired card says so rather than 403ing.
62
+ APPROVAL_TTL_S = 15 * 60
63
+
64
+ #: Slack rejects a replayed request older than 5 minutes; so do we, before any signature work.
65
+ SLACK_MAX_SKEW_S = 60 * 5
66
+
67
+ MAX_BODY_BYTES = 64 * 1024
68
+
69
+ #: β›” ROW-CAPPED BECAUSE AN APPROVER WHO CANNOT READ THE CARD CANNOT APPROVE IT. Copied
70
+ #: deliberately from OpenTag's `agent/write_confirmation.py`, which caps for the same reason:
71
+ #: past a certain length Slack collapses a message behind "Show more", and a human clicking
72
+ #: Approve on a card whose tail they never saw is worse than no card at all.
73
+ APPROVAL_MAX_ROWS = 12
74
+
75
+
76
+ # ── the tenant's agent records ───────────────────────────────────────────────────────────────
77
+ def _agents(rt):
78
+ """`{id: record}` for one tenant. `{}` on any failure β€” an unreadable bucket must degrade to
79
+ "this tenant has no agents", never to a 500 on the settings pane."""
80
+ try:
81
+ found = rt.get(AGENTS_KEY) or {}
82
+ except Exception: # noqa: BLE001
83
+ return {}
84
+ return found if isinstance(found, dict) else {}
85
+
86
+
87
+ def _clean_agent(raw, prior=None):
88
+ """One stored record, built KEY BY KEY.
89
+
90
+ β›” Never `dict(raw)` and never `**raw`. This record is the SUBJECT of a permission decision;
91
+ a client-supplied key landing in it is a client-supplied input to `perm_scope`. The same rule
92
+ `routes_forms._public_form` follows on the way out, applied here on the way in.
93
+ """
94
+ prior = prior if isinstance(prior, dict) else {}
95
+ out = {
96
+ "id": str(prior.get("id") or raw.get("id") or ""),
97
+ "channel": str(raw.get("channel") or prior.get("channel") or "").strip()[:64],
98
+ "channelName": str(raw.get("channelName") or prior.get("channelName") or "").strip()[:80],
99
+ "label": " ".join(str(raw.get("label") or prior.get("label") or "").split())[:80],
100
+ "active": bool(raw.get("active", prior.get("active", True))),
101
+ # β›” DEFAULT TRUE, AND `is not False` RATHER THAN TRUTHINESS. A record written before this
102
+ # key existed must read as "approval required": the one direction a default here is
103
+ # allowed to be wrong in is the safe one, because an unattended write cannot be undone by
104
+ # revoking the bot afterwards [[default-must-pass-its-own-guard]].
105
+ "writeApproval": raw.get("writeApproval", prior.get("writeApproval", True)) is not False,
106
+ # The permission block. Same shape, same validator, same engine as a user's.
107
+ "perms": prior.get("perms") if isinstance(prior.get("perms"), dict) else {},
108
+ "perms_v": int(prior.get("perms_v") or 0),
109
+ "createdBy": str(prior.get("createdBy") or raw.get("createdBy") or ""),
110
+ "createdAt": str(prior.get("createdAt") or raw.get("createdAt") or ""),
111
+ }
112
+ return out
113
+
114
+
115
+ def _put_agent(session, agent_id, mutate):
116
+ """Read-modify-write ONE agent under the tenant's bucket, synchronously.
117
+
118
+ `flush="sync"` because the client re-reads the list immediately after every write here, and an
119
+ async flush would let the refetch win the race and paint the pre-write state β€” the
120
+ [[refetch-eats-its-own-write]] shape.
121
+ """
122
+ def _set(cur):
123
+ cur = dict(cur or {})
124
+ rec = cur.get(agent_id) if isinstance(cur.get(agent_id), dict) else None
125
+ nxt = mutate(rec)
126
+ if nxt is None:
127
+ cur.pop(agent_id, None)
128
+ else:
129
+ cur[agent_id] = nxt
130
+ return cur
131
+
132
+ session.runtime.update(AGENTS_KEY, _set, flush="sync")
133
+
134
+
135
+ # ── ⭐⭐ THE PROJECTION β€” THE WHOLE OF "the same engine that permissions a user" ───────────────
136
+ def agent_principal(agent):
137
+ """A channel agent, as a PRINCIPAL `core/perm_scope` already understands.
138
+
139
+ ⭐⭐ THIS IS THE ENTIRE POINT OF THE TICKET AND IT IS NINE LINES. `perm_scope` takes a user
140
+ RECORD β€” a plain dict with `perms`, `perms_v` and `role` β€” not a User object and not a session.
141
+ So a channel agent carrying a `perms` block simply IS such a record, and `may_access`,
142
+ `visible_fields`, `hidden_keys` and `apply_row_scope` work on it unmodified. There is no second
143
+ engine, no parallel vocabulary, and nothing about a channel to keep in step with anything about
144
+ a person. That is what the owner's *"exactly like how we toggle permissioning per user"* means
145
+ when it is true in code rather than in appearance.
146
+
147
+ β›” `role` IS HARDCODED NON-ADMIN AND MUST STAY SO. `perm_scope.may_access` returns True
148
+ unconditionally for `role == 'admin'` β€” the break-glass clause that keeps the owner out of a
149
+ locked store. A bot has no such emergency and no hands: an agent record that could carry
150
+ `role: 'admin'` would be one stored key away from bypassing every wall on this page. The key is
151
+ not copied from the record; it is written here, every time.
152
+
153
+ β›” AND `perms_v` IS FORCED TO THE CURRENT VERSION, which makes an UNDECLARED database DENY
154
+ (C-PERM amendment 4). Without it a fresh agent would fall through to `perms.may_open`'s legacy
155
+ grant wall and read `modules: 'all'`-shaped defaults β€” i.e. a brand-new bot would start with
156
+ access to everything. Fail-closed from the first byte.
157
+ """
158
+ import core.perm_scope as perm_scope
159
+ return {
160
+ "username": f"slack:{(agent or {}).get('channel') or '?'}",
161
+ "role": "agent",
162
+ "perms": (agent or {}).get("perms") or {},
163
+ "perms_v": perm_scope.PERMS_VERSION,
164
+ # No `bus`, no `agent`: a channel is not a business unit and not a salesperson. Absent
165
+ # rather than 'all' β€” `perms.allowed_bu_labels` narrows on absence, which is the direction
166
+ # this must fail in.
167
+ }
168
+
169
+
170
+ def agent_may_read(agent, module):
171
+ """May this channel open `module` at all?"""
172
+ import core.perm_scope as perm_scope
173
+ if not (agent or {}).get("active", True):
174
+ return False
175
+ return bool(perm_scope.may_access(agent_principal(agent), module))
176
+
177
+
178
+ def agent_visible_fields(agent, fields, module):
179
+ """`fields` minus this channel's hidden closure β€” the SAME transitive closure a person gets,
180
+ so a formula over a hidden column cannot leak it back through arithmetic."""
181
+ import core.perm_scope as perm_scope
182
+ return perm_scope.visible_fields(fields, agent_principal(agent), module)
183
+
184
+
185
+ def agent_rows(agent, rows, module, fields, ctx=None, st=None):
186
+ """The rows this channel may receive β€” `permits()`, so an unanswerable permanent filter DENIES
187
+ rather than being ignored.
188
+
189
+ ⭐⭐ `st` IS THE TENANT HANDLE AND IT IS HERE BECAUSE OF THE SENTENCE IN `agent_principal`:
190
+ a channel agent IS a principal of the same wall, so a permanent filter naming a
191
+ user-generated column has to mean the SAME thing here as it does on the grid (owner I16).
192
+ A door that lends the handle and a door that does not are one stored rule with two meanings.
193
+
194
+ ⚠ PASS THE TENANT'S OWN RUNTIME β€” every other store read in this file takes
195
+ `session.runtime`, and a channel is not a second tenancy. It is a keyword with a `None`
196
+ default for the same reason `perm_scope.apply_row_scope`'s is: without one this is
197
+ byte-identical to the wall that shipped before the argument existed.
198
+
199
+ ⚠ `hidden_keys` DELIBERATELY DOES NOT TAKE IT IN THIS CHANGE. Its field-grant leg
200
+ under-hides without a handle (see `perm_scope.visible_overlays`), which is a real and
201
+ separate gap on this surface β€” but it is the FIELD wall, it moves what a channel receives
202
+ rather than what I16 asked for, and widening two walls in one ticket is how a permission
203
+ change stops being reviewable.
204
+ """
205
+ import core.perm_scope as perm_scope
206
+ p = agent_principal(agent)
207
+ hide = perm_scope.hidden_keys(p, module, fields)
208
+ kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx, st=st)
209
+ # Both wires, never one: the field list and the row payload are separate, and stripping only
210
+ # the first leaves the value sitting in the second where anyone can read it.
211
+ return [perm_scope.strip_row(r, hide) for r in kept]
212
+
213
+
214
+ # ── the credential ───────────────────────────────────────────────────────────────────────────
215
+ def slack_creds(rt):
216
+ """This TENANT's Slack credentials from its own keychain, or None.
217
+
218
+ β›” NO ENVIRONMENT FALLBACK, DELIBERATELY, AND THIS IS D-202's LESSON APPLIED BEFORE IT
219
+ HAPPENS AGAIN. Meta Ads shipped loading end-to-end and was still not a connector, because
220
+ `keychain.meta_creds` had no caller and the token came from the owner's `.env` β€” making it a
221
+ tenant-#0 FACT indistinguishable from a screenshot. `keychain.meta_creds`' own docstring spells
222
+ out the rule: handing the environment's credential to a tenant whose admin has not stored one
223
+ is the leak the resolver exists to prevent. So a tenant with no entry gets None and the pane
224
+ SAYS so.
225
+
226
+ ⚠ Reads through `list_entries` + `read_fields` (both public) rather than `keychain._first_creds`
227
+ (private, and in a file outside this lane's fence). Same deterministic rule: entries are
228
+ id-sorted, so "first" is stable across reads rather than dict-order luck.
229
+ """
230
+ try:
231
+ import core.keychain as keychain
232
+ for row in keychain.list_entries(rt):
233
+ if str(row.get("type") or "") != "slack":
234
+ continue
235
+ fields = keychain.read_fields(rt, row.get("id"))
236
+ if isinstance(fields, dict) and fields.get("signing_secret"):
237
+ return fields
238
+ except Exception: # noqa: BLE001
239
+ # A locked or unreadable keychain reads as "not configured" for the PANE, which is honest;
240
+ # the signature check below fails closed regardless, so this cannot widen anything.
241
+ return None
242
+ return None
243
+
244
+
245
+ # ── the authenticated doors (the Manage agent surface) ───────────────────────────────────────
246
+ def _summary(agent, modules):
247
+ """One sentence per agent for the list row β€” computed here, because the alternative is one
248
+ round trip per row to fill one cell (the same reason `AdminUser.access` exists)."""
249
+ # ⭐ W36-T22 / C2 β€” every listed database is governed now; the `enforced` flag it used to
250
+ # filter on is DELETED, and `m.get("enforced")` would have gone silently falsy here and
251
+ # summarised every agent as "" (no databases at all).
252
+ governed = list(modules)
253
+ perms = agent.get("perms") or {}
254
+ open_n = sum(1 for m in governed if (perms.get(m["key"]) or {}).get("access"))
255
+ if not governed:
256
+ return ""
257
+ if open_n == 0:
258
+ return "No access"
259
+ restricted = sum(1 for m in governed
260
+ if (perms.get(m["key"]) or {}).get("access")
261
+ and ((perms.get(m["key"]) or {}).get("filter")
262
+ or (perms.get(m["key"]) or {}).get("hiddenFields")))
263
+ head = (f"All {open_n} database{'' if open_n == 1 else 's'}" if open_n == len(governed)
264
+ else f"{open_n} of {len(governed)} databases")
265
+ return f"{head}, {restricted} restricted" if restricted else head
266
+
267
+
268
+ @router.get("/agents")
269
+ def list_channel_agents(session: Session = Depends(admin_gate)):
270
+ """This tenant's channel agents, plus whether Slack is reachable at all."""
271
+ import routes_admin
272
+ modules = routes_admin._perm_modules(session)
273
+ rows = []
274
+ for aid, a in sorted(_agents(session.runtime).items()):
275
+ if not isinstance(a, dict):
276
+ continue
277
+ rows.append({"id": aid, "channel": a.get("channel") or "",
278
+ "channelName": a.get("channelName") or "",
279
+ "label": a.get("label") or "", "active": a.get("active", True) is not False,
280
+ "writeApproval": a.get("writeApproval", True) is not False,
281
+ "summary": _summary(a, modules)})
282
+ return {"agents": rows, "configured": slack_creds(session.runtime) is not None}
283
+
284
+
285
+ @router.post("/agents")
286
+ def create_channel_agent(body: dict = Body(default=None),
287
+ session: Session = Depends(admin_gate)):
288
+ body = body if isinstance(body, dict) else {}
289
+ channel = str(body.get("channel") or "").strip()
290
+ if not channel:
291
+ raise err(400, "no_channel", "a Slack channel ID is required")
292
+ existing = _agents(session.runtime)
293
+ # ⚠ ONE AGENT PER CHANNEL. Two records for one conversation would mean two walls, and nothing
294
+ # anywhere decides which one applies β€” the [[one-question-two-normalizers]] shape, in the one
295
+ # place where the two answers are "may read" and "may not".
296
+ for a in existing.values():
297
+ if isinstance(a, dict) and str(a.get("channel") or "") == channel:
298
+ raise err(409, "channel_taken",
299
+ "that channel already has an agent β€” edit it instead of adding a second")
300
+ aid = secrets.token_urlsafe(9)
301
+ rec = _clean_agent(dict(body, id=aid, createdBy=session.uname,
302
+ createdAt=datetime.now(timezone.utc).isoformat(timespec="seconds")))
303
+ _put_agent(session, aid, lambda _prior: rec)
304
+ fresh = _agents(session.runtime).get(aid)
305
+ if not isinstance(fresh, dict):
306
+ # The store took the write and did not record it. A 200 here would tell an administrator
307
+ # the agent exists when it does not.
308
+ raise err(503, "store_unavailable", "the agent was NOT created")
309
+ return {"agent": {"id": aid, "channel": rec["channel"], "channelName": rec["channelName"],
310
+ "label": rec["label"], "active": rec["active"],
311
+ "writeApproval": rec["writeApproval"], "summary": "No access"}}
312
+
313
+
314
+ @router.get("/agents/{agent_id}")
315
+ def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
316
+ """The agent PLUS the permission envelope β€” the SAME shape `get_perms` answers with.
317
+
318
+ ⭐ ONE PAYLOAD SHAPE FOR TWO ROOMS. `permsModel.parsePermsPayload` parses this, and
319
+ `settings/ModulePermsList` renders it, because they are literally the same client code. A
320
+ second envelope here would mean a second parser and a second set of defaults within a wave.
321
+ """
322
+ import routes_admin
323
+ a = _agents(session.runtime).get(str(agent_id))
324
+ if not isinstance(a, dict):
325
+ raise err(404, "no_such_agent", "no agent with that id")
326
+ modules = routes_admin._perm_modules(session)
327
+ # ⭐⭐ W36-T22 / C2 β€” EVERY listed database, `ut_*` included. β›” THIS IS WHY THE FLAG'S
328
+ # DELETION IS NOT A ONE-FILE CHANGE: `m.get("enforced")` on a row that no longer carries the
329
+ # key is None, so this list would have been EMPTY and the channel perms editor would have
330
+ # governed ZERO databases while looking entirely correct. A Slack channel is a principal of
331
+ # the SAME wall (`verify_perm_scope` section H) and gets the same catalogue.
332
+ governed = [m["key"] for m in modules]
333
+ stored = a.get("perms") or {}
334
+ principal = agent_principal(a)
335
+ import core.perm_scope as perm_scope
336
+ perms_out = {}
337
+ for k in governed:
338
+ e = stored.get(k)
339
+ # β›” W36-T22 β€” `may_read`, the same evaluator the read door uses, for the reason spelled
340
+ # out at `routes_admin.get_perms`. ⚠ It answers DIFFERENTLY here and correctly so: a
341
+ # channel agent is not a person with a share, so a `ut_*` key it has not been granted
342
+ # defaults CLOSED β€” which is the fail-closed direction for a bot, and the same answer the
343
+ # table routes would give it.
344
+ perms_out[k] = e if isinstance(e, dict) else {
345
+ "access": bool(perm_scope.may_read(principal, k, st=session.runtime)),
346
+ "filter": None, "hiddenFields": []}
347
+ return {"id": str(agent_id), "channel": a.get("channel") or "",
348
+ "channelName": a.get("channelName") or "", "label": a.get("label") or "",
349
+ "active": a.get("active", True) is not False,
350
+ "writeApproval": a.get("writeApproval", True) is not False,
351
+ "perms": perms_out,
352
+ # β›” ALWAYS THE CURRENT VERSION, because `agent_principal` forces it: the editor must
353
+ # render "undeclared = denied", not the legacy-grant reading it would show at 0.
354
+ "perms_v": perm_scope.PERMS_VERSION,
355
+ # A bot is NEVER an admin β€” see `agent_principal`. Sent so the editor never paints
356
+ # the "Everything (admin)" state for a principal that cannot have it.
357
+ "is_admin": False,
358
+ "modules": modules,
359
+ "fields_by_module": {k: routes_admin._module_fields(k, session=session)
360
+ for k in governed}}
361
+
362
+
363
+ @router.put("/agents/{agent_id}/perms")
364
+ def put_channel_agent_perms(agent_id: str, body: dict = Body(default=None),
365
+ session: Session = Depends(admin_gate)):
366
+ """Replace this agent's permission block wholesale β€” the same validator a user's block gets."""
367
+ import routes_admin
368
+ body = body if isinstance(body, dict) else {}
369
+ if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
370
+ raise err(404, "no_such_agent", "no agent with that id")
371
+ if "perms" not in body:
372
+ raise err(400, "empty_patch", "no perms to save")
373
+ mods = routes_admin._perm_modules(session)
374
+ # ⭐ THE SAME `_clean_perms`, NOT A COPY OF IT. It refuses a filter this module cannot
375
+ # evaluate, refuses a hiddenFields key that names nothing, and refuses a BU condition the
376
+ # pushdown cannot read. Every one of those is exactly as true for a channel as for a person,
377
+ # and a second validator here is a second place for one of them to go missing.
378
+ # ⚠ CORRECTED W36-T22: this list used to end "refuses an unenforced `ut_*` key". That refusal
379
+ # is DELETED β€” W36-T21 armed the wall over every database, so there is no unenforced key left
380
+ # to refuse, and a comment naming a rule that no longer exists is how the next wave re-derives
381
+ # it ([[two-gates-can-assert-opposite-things]]).
382
+ cleaned = routes_admin._clean_perms(
383
+ body.get("perms"),
384
+ governed_keys={m["key"] for m in mods}, session=session) or {}
385
+
386
+ import core.perm_scope as perm_scope
387
+
388
+ def _mut(prior):
389
+ if not isinstance(prior, dict):
390
+ return None
391
+ nxt = dict(prior)
392
+ nxt["perms"] = cleaned
393
+ nxt["perms_v"] = perm_scope.PERMS_VERSION
394
+ return nxt
395
+
396
+ _put_agent(session, str(agent_id), _mut)
397
+ fresh = _agents(session.runtime).get(str(agent_id)) or {}
398
+ if (fresh.get("perms") or {}) != cleaned:
399
+ # The one direction this must never fail in: telling an administrator the wall is up when
400
+ # it is not.
401
+ raise err(503, "store_unavailable", "the permissions were not saved β€” the agent is UNCHANGED")
402
+ return {"id": str(agent_id), "perms": fresh.get("perms") or {},
403
+ "perms_v": int(fresh.get("perms_v") or 0)}
404
+
405
+
406
+ @router.patch("/agents/{agent_id}")
407
+ def patch_channel_agent(agent_id: str, body: dict = Body(default=None),
408
+ session: Session = Depends(admin_gate)):
409
+ body = body if isinstance(body, dict) else {}
410
+ if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
411
+ raise err(404, "no_such_agent", "no agent with that id")
412
+ #: β›” `perms` IS NOT PATCHABLE HERE. It has its own door with its own validator; accepting it
413
+ #: on the metadata route would be a second, unvalidated way to write the wall.
414
+ allowed = {k: v for k, v in body.items()
415
+ if k in ("label", "active", "writeApproval", "channelName")}
416
+ if not allowed:
417
+ raise err(400, "empty_patch", "nothing to change")
418
+
419
+ def _mut(prior):
420
+ return _clean_agent(allowed, prior=prior) if isinstance(prior, dict) else None
421
+
422
+ _put_agent(session, str(agent_id), _mut)
423
+ import routes_admin
424
+ a = _agents(session.runtime).get(str(agent_id)) or {}
425
+ return {"agent": {"id": str(agent_id), "channel": a.get("channel") or "",
426
+ "channelName": a.get("channelName") or "", "label": a.get("label") or "",
427
+ "active": a.get("active", True) is not False,
428
+ "writeApproval": a.get("writeApproval", True) is not False,
429
+ "summary": _summary(a, routes_admin._perm_modules(session))}}
430
+
431
+
432
+ @router.delete("/agents/{agent_id}")
433
+ def delete_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
434
+ if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
435
+ raise err(404, "no_such_agent", "no agent with that id")
436
+ _put_agent(session, str(agent_id), lambda _prior: None)
437
+ if isinstance(_agents(session.runtime).get(str(agent_id)), dict):
438
+ raise err(503, "store_unavailable", "the agent was NOT removed")
439
+ return {"ok": True}
440
+
441
+
442
+ # ── ⭐ W33-T67: THE WRITE-APPROVAL GATE ───────────────────────────────────────────────────────
443
+ def _is_empty(value):
444
+ """Is this value ABSENT, as opposed to falsy?
445
+
446
+ β›” COPIED EXACTLY FROM OpenTag's `agent/write_confirmation.py`, and the exactness is the point:
447
+ `0` and `False` are VALUES a human must see on the card. Setting a price to 0 or a flag to
448
+ False is precisely the kind of write somebody needs to approve, and a naive `if not value`
449
+ drops both rows silently β€” the approver then reads a card that does not describe the write
450
+ they are approving. The MIT licence gate for this borrowing is recorded in
451
+ `.claude/wiki/research/opentag-adoption.md`.
452
+ """
453
+ return value is None or (isinstance(value, str) and value.strip() == "")
454
+
455
+
456
+ def approval_card(action, values, agent=None):
457
+ """The card a human reads before a bot writes. `{action, rows, truncated, note}`.
458
+
459
+ β›” ROW-CAPPED, and the cap is a SAFETY property rather than a layout one: past a certain
460
+ length Slack collapses a message behind "Show more", and **an approver who cannot read the
461
+ card cannot approve it.** When rows are dropped the card SAYS how many β€” a truncation nobody
462
+ was told about is the violation, not the truncation (wave-30 R6's second sentence).
463
+ """
464
+ rows = [{"field": str(k), "value": v}
465
+ for k, v in (values or {}).items() if not _is_empty(v)]
466
+ rows.sort(key=lambda r: r["field"])
467
+ shown, dropped = rows[:APPROVAL_MAX_ROWS], max(0, len(rows) - APPROVAL_MAX_ROWS)
468
+ return {
469
+ "action": str(action or "")[:80],
470
+ "rows": shown,
471
+ "truncated": dropped,
472
+ "note": (f"{dropped} more field(s) not shown β€” open the record to review them before "
473
+ f"approving." if dropped else ""),
474
+ "agent": (agent or {}).get("label") or (agent or {}).get("channel") or "",
475
+ }
476
+
477
+
478
+ def intercept_write(agent, action, values, stash):
479
+ """THE INTERCEPTOR. Returns `("commit", None)` or `("await_approval", card)`.
480
+
481
+ ⭐ The one thing worth taking from OpenTag: a MUTATING tool call is halted, rendered as a card
482
+ naming the action and its values, and committed only on an explicit human accept. Everything
483
+ else in that repo β€” the transport, the runtime, the identity model β€” is AVOID (amendment A1).
484
+
485
+ β›” FAIL-CLOSED ON A MISSING FLAG: `is not False`, so a record written before `writeApproval`
486
+ existed requires approval. The unsafe direction here is not recoverable β€” revoking a bot does
487
+ not un-write what it wrote.
488
+ """
489
+ if (agent or {}).get("writeApproval", True) is not False:
490
+ card = approval_card(action, values, agent)
491
+ stash(card)
492
+ return "await_approval", card
493
+ return "commit", None
494
+
495
+
496
+ def _pending(rt):
497
+ try:
498
+ found = rt.get(PENDING_KEY) or {}
499
+ except Exception: # noqa: BLE001
500
+ return {}
501
+ return found if isinstance(found, dict) else {}
502
+
503
+
504
+ def stash_pending(rt, agent, action, values, now=None):
505
+ """Store one awaiting-approval mutation and return its token.
506
+
507
+ The token is what rides the card's button, so it is `secrets.token_urlsafe` and not the
508
+ action's id: a guessable value on an unauthenticated door is a way to approve somebody else's
509
+ write. Server-only bucket, per tenant, exactly as `routes_forms.TOKENS_KEY` is.
510
+ """
511
+ token = secrets.token_urlsafe(18)
512
+ row = {"at": float(now if now is not None else time.time()),
513
+ "channel": str((agent or {}).get("channel") or ""),
514
+ "action": str(action or "")[:80],
515
+ "values": values if isinstance(values, dict) else {}}
516
+ rt.update(PENDING_KEY, lambda cur: {**(cur or {}), token: row}, flush="sync")
517
+ return token
518
+
519
+
520
+ #: `{action kind: fn(rt, row) -> None}`. Registered by whatever can actually perform a mutation.
521
+ #:
522
+ #: β›”β›” EMPTY IN PRODUCTION TODAY, AND SAYING SO IS THE POINT. `commit_pending` below is the ONE
523
+ #: place an approved write may be performed, so it is the place a negative control can bite β€” but
524
+ #: a gate is only as honest as what it guards. Until something registers here, an approved card
525
+ #: performs NOTHING and `commit_pending` returns `no_committer` rather than pretending. That is a
526
+ #: declared absence, not a silent one [[flag-shipped-without-its-writer]].
527
+ _COMMITTERS = {}
528
+
529
+
530
+ def register_committer(kind, fn):
531
+ """Declare who may perform an approved mutation of `kind`. Idempotent by key."""
532
+ _COMMITTERS[str(kind)] = fn
533
+
534
+
535
+ def commit_pending(rt, token, approved, now=None):
536
+ """Resolve ONE approval card. Returns one of
537
+ `expired` Β· `unknown` Β· `rejected` Β· `no_committer` Β· `committed` Β· `failed`.
538
+
539
+ β›”β›” THIS IS THE WRITE GATE, AND IT IS A SEPARATE FUNCTION FROM THE ROUTE ON PURPOSE. T67's
540
+ `done-when` asks for an NC proving a REJECTED card writes nothing. A control aimed at the
541
+ route could not bite while the route had no write in it at all β€” it would stay green with the
542
+ guard deleted, because there would be nothing for the guard to be protecting anything from
543
+ ([[gate-can-report-green-on-nothing]], and a verifier caught exactly that on this ticket's
544
+ first draft). Putting the commit behind ONE named seam gives the control a real subject: the
545
+ gate registers a recorder, and `rejected` must leave it untouched while `approve` must call it
546
+ exactly once.
547
+
548
+ β›” THE TOKEN IS CONSUMED BEFORE EITHER BRANCH, and before any committer runs. A card that
549
+ survives its own click is a replayable write, and "approve twice" must never mean "write
550
+ twice". The delete is `flush="sync"` for the same reason.
551
+ """
552
+ now = float(now if now is not None else time.time())
553
+ row = _pending(rt).get(str(token))
554
+ if not isinstance(row, dict):
555
+ return "unknown"
556
+ # Consume FIRST β€” before the TTL verdict, before the approve/reject branch, before any write.
557
+ rt.update(PENDING_KEY,
558
+ lambda cur: {k: v for k, v in (cur or {}).items() if k != str(token)},
559
+ flush="sync")
560
+ if now - float(row.get("at") or 0) > APPROVAL_TTL_S:
561
+ return "expired"
562
+ if not approved:
563
+ # β›” NOTHING BELOW THIS LINE RUNS FOR A REJECTED CARD. The whole gate is this return.
564
+ return "rejected"
565
+ fn = _COMMITTERS.get(str(row.get("action") or ""))
566
+ if fn is None:
567
+ return "no_committer"
568
+ try:
569
+ fn(rt, row)
570
+ except Exception: # noqa: BLE001
571
+ # A committer that raises must not read as a commit. The card is already consumed, so the
572
+ # honest report is that it failed, and the human asks again.
573
+ return "failed"
574
+ return "committed"
575
+
576
+
577
+ # ── the UNAUTHENTICATED Slack door ───────────────────────────────────────────────────────────
578
+ #: Sliding window, keyed on the SLACK TEAM, never the client IP.
579
+ #:
580
+ #: β›” WHY NOT THE IP, WHICH IS WHAT `routes_forms` DOES. Every Slack event arrives from Slack's own
581
+ #: infrastructure, so an IP window is one shared bucket for every workspace on the platform: one
582
+ #: busy tenant would spend the allowance for all of them, and the symptom would be another
583
+ #: tenant's bot going quiet. The team id is the closest thing to the actual noisy party.
584
+ #: ⚠ It is attacker-CONTROLLED before the signature is checked, so the window is applied AFTER
585
+ #: verification, never before β€” an unsigned request is refused on cost grounds anyway (a signature
586
+ #: check is a single HMAC).
587
+ RATE_WINDOW_S, RATE_PER_WINDOW = 60, 60
588
+ _HITS: dict = {}
589
+
590
+
591
+ def _rate_ok(key, now):
592
+ seen = [t for t in _HITS.get(key, ()) if now - t < RATE_WINDOW_S]
593
+ seen.append(now)
594
+ _HITS[key] = seen
595
+ if len(_HITS) > 4096:
596
+ for k in [k for k, v in _HITS.items() if not v or now - v[-1] > RATE_WINDOW_S]:
597
+ _HITS.pop(k, None)
598
+ return len(seen) <= RATE_PER_WINDOW
599
+
600
+
601
+ async def _raw_body(request):
602
+ """The body as RAW BYTES, capped.
603
+
604
+ β›”β›” RAW, NOT PARSED, AND THAT IS NOT A STYLE CHOICE. Slack signs the literal string
605
+ `v0:{timestamp}:{body}` byte for byte. `routes_forms._bounded_body` β€” the function this is
606
+ otherwise copied from β€” returns only the parsed dict and DISCARDS the bytes, so a verbatim
607
+ copy of it could not verify a Slack signature at all: re-serialising the dict changes
608
+ whitespace and key order and the HMAC no longer matches. The bug would look like "Slack
609
+ signatures are always invalid", which is indistinguishable from a wrong secret.
610
+
611
+ ⚠ And it streams rather than calling `request.body()`: FastAPI would otherwise have buffered
612
+ the whole body before the handler's first line, so a content-length check inside the handler
613
+ caps nothing (`routes_forms`' own scar, recorded in its docstring).
614
+ """
615
+ size, chunks = 0, []
616
+ async for chunk in request.stream():
617
+ size += len(chunk)
618
+ if size > MAX_BODY_BYTES:
619
+ raise err(413, "body_too_large", "that request is too large")
620
+ chunks.append(chunk)
621
+ return b"".join(chunks)
622
+
623
+
624
+ def _refuse():
625
+ """ONE refusal for every reason. No oracle.
626
+
627
+ A wrong signature, a stale timestamp, an unknown team, an unconfigured tenant and a channel
628
+ with no agent all answer identically β€” otherwise the door tells an unauthenticated caller
629
+ which tenants exist and which channels are configured, which is the question it was built to
630
+ not answer. `routes_forms._refuse` takes the same posture for the same reason.
631
+ """
632
+ return err(403, "bad_request", "that request could not be verified")
633
+
634
+
635
+ def _verify(secret, timestamp, raw, signature, now):
636
+ """Slack's v0 signature, with the replay window checked FIRST."""
637
+ try:
638
+ ts = int(str(timestamp or "0"))
639
+ except ValueError:
640
+ return False
641
+ if abs(now - ts) > SLACK_MAX_SKEW_S:
642
+ return False
643
+ base = b"v0:" + str(ts).encode("ascii") + b":" + (raw or b"")
644
+ import hashlib
645
+ expected = "v0=" + hmac.new(str(secret).encode("utf-8"), base, hashlib.sha256).hexdigest()
646
+ return hmac.compare_digest(expected, str(signature or ""))
647
+
648
+
649
+ def _resolve_tenant(raw, timestamp, signature, now):
650
+ """`(slug, runtime, creds)` for the tenant whose signing secret verifies this request.
651
+
652
+ β›” THE TENANT IS DECIDED BY THE SIGNATURE, NEVER BY THE PAYLOAD. A body-supplied `team_id`
653
+ would let an unauthenticated caller name the tenant it wants to be β€” the exact widening
654
+ `deps._user_for`'s tenant-equality check closes on the authenticated side. So every configured
655
+ tenant's secret is tried and the one that VERIFIES names the tenant.
656
+
657
+ ⚠ NO EARLY `break` ON A FAILED CANDIDATE and no per-tenant error: the loop's cost must not
658
+ depend on which tenant matched. `routes_forms._resolve` walks tenants the same way, for the
659
+ same reason β€” a public door has no session to ask.
660
+ """
661
+ from harness import runtime as _rt
662
+ hit = None
663
+ try:
664
+ slugs = list(_rt.known_tenants())
665
+ except Exception: # noqa: BLE001
666
+ return None, None, None
667
+ for slug in slugs:
668
+ try:
669
+ rt = _rt.get_runtime(slug)
670
+ except Exception: # noqa: BLE001
671
+ continue
672
+ creds = slack_creds(rt)
673
+ if not creds:
674
+ continue
675
+ if _verify(creds.get("signing_secret"), timestamp, raw, signature, now) and hit is None:
676
+ hit = (slug, rt, creds)
677
+ return hit if hit else (None, None, None)
678
+
679
+
680
+ @router.post("/slack/events")
681
+ async def slack_events(request: Request):
682
+ """Slack's Events API. UNAUTHENTICATED BY CONSTRUCTION β€” no `Depends(require_session)`.
683
+
684
+ ⭐ Built like `routes_forms.py`'s public door and not like OpenTag's: one process, no vendor,
685
+ no second runtime, no persistent outbound socket, and this tenant's Slack secret never leaves
686
+ this deployment (amendment A1).
687
+ """
688
+ now = time.time()
689
+ raw = await _raw_body(request)
690
+ ts = request.headers.get("x-slack-request-timestamp")
691
+ sig = request.headers.get("x-slack-signature")
692
+ slug, rt, _creds = _resolve_tenant(raw, ts, sig, now)
693
+ if not rt:
694
+ raise _refuse()
695
+
696
+ try:
697
+ payload = json.loads(raw or b"{}")
698
+ except ValueError:
699
+ raise _refuse()
700
+ if not isinstance(payload, dict):
701
+ raise _refuse()
702
+
703
+ # Slack's one-time endpoint handshake. Answered ONLY after the signature verified β€” an
704
+ # unsigned challenge echo would confirm the endpoint exists to anyone who probes it.
705
+ if payload.get("type") == "url_verification":
706
+ return {"challenge": str(payload.get("challenge") or "")[:512]}
707
+
708
+ team = str(payload.get("team_id") or slug)
709
+ if not _rate_ok(f"{slug}:{team}", now):
710
+ raise err(429, "too_many_requests", "too many requests β€” wait a moment and try again")
711
+
712
+ event = payload.get("event") if isinstance(payload.get("event"), dict) else {}
713
+ channel = str(event.get("channel") or "")
714
+ agent = None
715
+ for a in _agents(rt).values():
716
+ if isinstance(a, dict) and str(a.get("channel") or "") == channel:
717
+ agent = a
718
+ break
719
+ # β›” NO AGENT, OR AN INACTIVE ONE, IS SILENCE β€” a 200 with no action. Not a 403: Slack retries
720
+ # a non-2xx up to three times, so refusing here would turn "this channel is not configured"
721
+ # into three refusals per message, and the retry storm would be the only visible symptom.
722
+ # ⚠ And it must not say WHICH β€” a distinguishable answer tells an unauthenticated caller which
723
+ # channels this workspace has configured.
724
+ if not isinstance(agent, dict) or agent.get("active", True) is False:
725
+ return {"ok": True}
726
+
727
+ # β›”β›” THE ANSWERING HALF IS NOT BUILT YET, AND SAYING SO IS THE POINT. What ships here is the
728
+ # DOOR and the WALL: a verified request, resolved to a tenant by signature, matched to a
729
+ # channel agent whose `perms` block is a `perm_scope` principal (`agent_principal`). Composing
730
+ # a reply means an LLM call on the cheap-first ladder plus the read path, and a half-built
731
+ # answerer that returns something plausible is worse than one that returns nothing.
732
+ # Booked rather than faked [[flag-shipped-without-its-writer]].
733
+ return {"ok": True}
734
+
735
+
736
+ @router.post("/slack/interact")
737
+ async def slack_interact(request: Request):
738
+ """The approval card's button (`W33-T67`). UNAUTHENTICATED, signature-verified, same shape."""
739
+ now = time.time()
740
+ raw = await _raw_body(request)
741
+ slug, rt, _creds = _resolve_tenant(raw, request.headers.get("x-slack-request-timestamp"),
742
+ request.headers.get("x-slack-signature"), now)
743
+ if not rt:
744
+ raise _refuse()
745
+ # Slack posts interactions as `application/x-www-form-urlencoded` with a `payload=` field.
746
+ from urllib.parse import parse_qs
747
+ try:
748
+ form = parse_qs(raw.decode("utf-8"))
749
+ payload = json.loads((form.get("payload") or ["{}"])[0])
750
+ except Exception: # noqa: BLE001
751
+ raise _refuse()
752
+ if not isinstance(payload, dict):
753
+ raise _refuse()
754
+ if not _rate_ok(f"{slug}:interact", now):
755
+ raise err(429, "too_many_requests", "too many requests β€” wait a moment and try again")
756
+
757
+ actions = payload.get("actions") if isinstance(payload.get("actions"), list) else []
758
+ choice = (actions[0] if actions and isinstance(actions[0], dict) else {})
759
+ token = str(choice.get("value") or "")
760
+ # ⭐ ANYTHING THAT IS NOT LITERALLY "approve" IS A REJECT. Fail-closed on a malformed,
761
+ # truncated or unknown action id: the direction that can be wrong here without anyone
762
+ # noticing is the one that writes.
763
+ approved = str(choice.get("action_id") or "") == "approve"
764
+ # β›” THE ROUTE DOES NOT DECIDE β€” `commit_pending` does, and it is the ONE seam a negative
765
+ # control can aim at. Consumption, the TTL, the reject branch and the committer lookup all
766
+ # live there; this handler only turns its verdict into a sentence.
767
+ verdict = commit_pending(rt, token, approved, now=now)
768
+ return {"text": {
769
+ # An unknown, already-used or expired token is not an error: a person clicking a stale
770
+ # card should be told it is stale, not shown a failure.
771
+ "unknown": "That approval is no longer available. Ask the bot again.",
772
+ "expired": "That approval expired before it was answered. Ask the bot again.",
773
+ "rejected": "Rejected. Nothing was changed.",
774
+ # ⚠ HONEST, not reassuring: the answering half that would register a committer is booked,
775
+ # so an approved card today performs nothing and says exactly that rather than "Approved."
776
+ "no_committer": "Approved β€” but this workspace has nothing configured to carry it out yet.",
777
+ "failed": "That change could not be completed. Nothing was saved; ask the bot again.",
778
+ "committed": "Approved.",
779
+ }.get(verdict, "That approval is no longer available. Ask the bot again.")}
780
+
781
+
782
+ @router.get("/slack/health")
783
+ def slack_health(session: Session = Depends(require_session)):
784
+ """Is Slack configured for THIS tenant? Session-gated, and it answers about one tenant only β€”
785
+ enumerating the others would answer a question about our customer list."""
786
+ creds = slack_creds(session.runtime)
787
+ return {"configured": creds is not None,
788
+ "agents": len(_agents(session.runtime)),
789
+ "hasBotToken": bool((creds or {}).get("bot_token"))}
api/routes_statements.py CHANGED
@@ -1,298 +1,298 @@
1
- """routes_statements.py β€” the statement-of-account sender, ported off Streamlit (EXIT-6).
2
-
3
- β›” THIS IS THE ONE SANCTIONED ODOO WRITER IN THE ENTIRE SYSTEM. Everything else in AIOS is
4
- read-only on Odoo by hard block. `modules/collections_send.py` owns a narrow client that whitelists
5
- exactly `mail.mail create` (queueing an outbound email) and nothing else; these routes call it and
6
- add no write of their own.
7
-
8
- WHY IT EXISTS SEPARATELY FROM THE COLLECTIONS PAGE. Owner ruling wave-17 item 15 retired the
9
- Collections *dashboard* β€” the worklist is the shared "Collections" view on the Customer grid, from
10
- the same reconciled blocks. What that ruling explicitly left "untouched" is this send workflow, so
11
- when `app.py` is deleted it is the ONLY live Streamlit-only feature, and it moves here rather than
12
- dying with the host. Ported faithfully: same tiers, same filters, same template placeholders, same
13
- preview, same test-send, same two-step confirm.
14
-
15
- THE THREE GUARDRAILS, and where each is enforced:
16
- 1. SAFE_MODE (default ON) β€” in the DATA LAYER (`collections_send.queue_statement`), so no route,
17
- payload or UI can bypass it. These routes only REPORT it; they never re-implement the check.
18
- 2. Admin only β€” `admin_gate` (role, fail-closed), mirroring the Streamlit `if not is_admin()`.
19
- 3. ⭐ TENANT β€” NEW HERE, and it did not exist in Streamlit because it could not. `cs_mod.Odoo()`
20
- reads Odoo credentials from the ENVIRONMENT, which after the keychain cutover belongs to
21
- TENANT #0 ALONE. On the multi-tenant API an unguarded route would let a nurilab or gtmlab
22
- admin queue mail from Royal Imports' Odoo, as Royal Imports. `_royal_only` closes that; the
23
- single-tenant Streamlit host never had the exposure, so this is a port that must ADD a wall
24
- rather than copy one.
25
-
26
- NOTHING SENDS ON A GET. The send route requires an explicit customer list in the body; there is no
27
- "send all" parameter, deliberately β€” the confirm step is a product requirement, not a formality.
28
- """
29
- from fastapi import APIRouter, Body, Depends
30
-
31
- from deps import Session, err
32
- from routes_admin import admin_gate
33
-
34
- # W35-T35 (C8): the tenant predicate, held once. See `_royal_only` for why the import runs this
35
- # way round. `main.py` already imports both modules, so this adds no load.
36
- import automation_engine as engine
37
-
38
- router = APIRouter(prefix="/api/v1")
39
-
40
- #: Cache the Odoo follow-up pull briefly. The Streamlit page used `@st.cache_data(ttl=1800)`; the
41
- #: list moves slowly (it is a dunning worklist, not a live feed) and the pull is a multi-model read.
42
- _TTL = 1800
43
- _cache = {"at": 0.0, "rows": None}
44
-
45
-
46
- def _cs():
47
- import modules.collections_send as cs
48
- return cs
49
-
50
-
51
- def _royal_only(session: Session) -> Session:
52
- """β›” See the module docstring, guardrail 3. The send client is env-credentialed, so it is
53
- tenant #0's and only tenant #0's. Refuse for anyone else rather than send as the wrong company.
54
-
55
- Keyed on the runtime, never on a request field: a tenant is a property of the SESSION.
56
-
57
- ⭐⭐ WAVE 35 Β· T35 / CONTRACT C8 β€” THE TEST ITSELF NOW LIVES IN ONE PLACE. Statements became an
58
- agent step this wave, so the automation engine has to answer the same question at two more
59
- doors (which tenants see the action, which tenants may store it). C8's words are "the predicate
60
- is imported, never re-expressed", and this is the direction that import can run: the engine
61
- imports no route module and no FastAPI, so reaching `_royal_only` FROM it would drag `deps` and
62
- `routes_admin` into a route-free module. The engine holds the boolean; this holds the refusal.
63
- ⚠ WHAT STAYS HERE IS THE HTTP SHAPE, and that is deliberate β€” a 404 rather than a 403, so the
64
- surface is invisible rather than forbidden. The engine must not know about status codes."""
65
- if not engine.is_statement_tenant(session.runtime):
66
- raise err(404, "not_found", "statements are not configured for this workspace")
67
- return session
68
-
69
-
70
- def _gate(session: Session = Depends(admin_gate)) -> Session:
71
- return _royal_only(session)
72
-
73
-
74
- def _rows(force=False):
75
- import time
76
- cs = _cs()
77
- if force or _cache["rows"] is None or (time.time() - _cache["at"]) > _TTL:
78
- _cache["rows"] = cs.load_collection_list(cs.Odoo())
79
- _cache["at"] = time.time()
80
- return _cache["rows"], time.strftime("%Y-%m-%d %H:%M", time.localtime(_cache["at"]))
81
-
82
-
83
- def _public(row):
84
- """Strip the internals the Streamlit grid also hid (`_`-prefixed + partner_id is kept, because
85
- the client needs a stable row identity that is not the display name)."""
86
- return {k: v for k, v in row.items() if not str(k).startswith("_")}
87
-
88
-
89
- @router.get("/admin/statements")
90
- def statements(refresh: int = 0, session: Session = Depends(_gate)):
91
- """The worklist + everything the sender UI needs to render itself honestly."""
92
- cs = _cs()
93
- try:
94
- rows, loaded_at = _rows(force=bool(refresh))
95
- except Exception as e:
96
- raise err(502, "odoo_unavailable", f"could not load the collection list: {str(e)[:200]}")
97
- return {
98
- "rows": [_public(r) for r in rows],
99
- "loadedAt": loaded_at,
100
- # The guardrail is reported, never decided, here β€” the data layer owns it.
101
- "safeMode": bool(cs.SAFE_MODE),
102
- "safeRecipients": sorted(cs.SAFE_RECIPIENTS),
103
- "sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL,
104
- "replyTo": cs.REPLY_TO, "company": cs.COMPANY},
105
- "templates": {"subject": cs.DEFAULT_SUBJECT, "intro": cs.DEFAULT_INTRO,
106
- "footer": cs.DEFAULT_FOOTER},
107
- # W35-T35: ONE literal, read from the engine, so the sender's worklist and a statements
108
- # agent's tier filter cannot come to mean different things.
109
- "tiers": list(engine.STATEMENT_TIERS),
110
- }
111
-
112
-
113
- def _find(rows, customer):
114
- return next((r for r in rows if r.get("Customer") == customer), None)
115
-
116
-
117
- @router.post("/admin/statements/preview")
118
- def preview(body: dict = Body(default=None), session: Session = Depends(_gate)):
119
- """Render ONE customer's statement exactly as the send path would."""
120
- cs = _cs()
121
- body = body or {}
122
- rows, _ = _rows()
123
- row = _find(rows, body.get("customer"))
124
- if row is None:
125
- raise err(404, "not_found", "no such customer on the collection list")
126
- t = body.get("templates") or {}
127
- import datetime as dt
128
- month = dt.date.today().strftime("%B %Y")
129
- subject = (t.get("subject") or cs.DEFAULT_SUBJECT)
130
- try:
131
- subject = subject.format(customer=row["Customer"], company=cs.COMPANY, month=month)
132
- except Exception: # noqa: BLE001
133
- # An unknown placeholder is the user's typo, not a 500. Show the template verbatim so they
134
- # can see what they typed rather than getting an opaque error.
135
- # β›” W36-T42: THIS CAUGHT THREE OF THE WAYS `str.format` FAILS AND THERE ARE MORE.
136
- # `{customer` is a ValueError, `{customer.x}` an AttributeError, `{customer:%Y}` a
137
- # TypeError, and every one of them is the same user mistake this branch was written for.
138
- # Naming a subset of the exception types turns a typo in the OTHER half into a 500 on the
139
- # one screen somebody opens to avoid mailing 200 people the wrong thing.
140
- pass
141
- return {
142
- "html": cs.render_statement_html(row, t.get("intro") or cs.DEFAULT_INTRO,
143
- t.get("footer") or cs.DEFAULT_FOOTER),
144
- "to": row.get("Email") or "",
145
- "subject": subject,
146
- }
147
-
148
-
149
- @router.post("/admin/statements/send")
150
- def send(body: dict = Body(default=None), session: Session = Depends(_gate)):
151
- """Queue statements. Returns per-customer outcomes β€” NEVER a bare count.
152
-
153
- `overrideTo` is the test-send path: one customer, one address. SAFE_MODE still applies (the
154
- data layer refuses an address outside the allow-list), which is why the route does not check it.
155
- """
156
- cs = _cs()
157
- body = body or {}
158
- names = [str(n) for n in (body.get("customers") or []) if str(n).strip()]
159
- if not names:
160
- raise err(400, "bad_request", "name at least one customer")
161
- # β›”β›” W36-T42 / D-299 β€” A DECLARED TEST SEND WITH NO ADDRESS REFUSES. IT DOES NOT BECOME A
162
- # REAL ONE. This read `(body.get("overrideTo") or "").strip() or None`, so a caller who sent
163
- # `overrideTo: ""` (the field left blank, the state not yet typed into, a trimmed-away space)
164
- # got a REAL statement mailed to the debtor's own address, reported back as `test: false`. On
165
- # the one route in this product that is allowed to write to Odoo, the difference between a
166
- # rehearsal and mailing a live customer was one empty string.
167
- #
168
- # ⭐ THE DISCRIMINATOR IS THE CALLER'S DECLARATION, NOT THE VALUE. A body with no `overrideTo`
169
- # key and no `test` flag is the PRODUCTION send, and refusing that would delete the feature
170
- # D-299 exists to preserve. What can be refused is a caller who SAID this is a test: the key
171
- # being present, or `test: true`, is that statement, and an empty address beside it is the
172
- # mistake. So both spellings of "absent" are covered: the key present and blank, and `test`
173
- # asserted with no key at all.
174
- #
175
- # ⚠ THIS IS THE SECOND OF THREE WALLS AND THE ONLY ONE A PAYLOAD CANNOT ROUTE AROUND.
176
- # `automationApi.testSendStatement` refuses an empty address before the request is built, and
177
- # SAFE_MODE refuses an address outside the allow-list inside `queue_statement`. The client
178
- # wall is bypassable by construction (anything can POST); this one is not.
179
- declared_test = ("overrideTo" in body) or bool(body.get("test"))
180
- override = str(body.get("overrideTo") or "").strip()
181
- if declared_test and not override:
182
- raise err(400, "no_override_address",
183
- "a test send needs the address to send the test to. Without one this would "
184
- "mail the customer's own address, which is the opposite of a test")
185
- override = override or None
186
- if override and len(names) != 1:
187
- raise err(400, "bad_request", "a test send takes exactly one customer")
188
- t = body.get("templates") or {}
189
- rows, _ = _rows()
190
-
191
- sent, failed, skipped = [], [], []
192
- for name in names:
193
- row = _find(rows, name)
194
- if row is None:
195
- failed.append({"customer": name, "error": "not on the current collection list"})
196
- continue
197
- if not override and not row.get("Email"):
198
- # The Streamlit page warned and skipped these. Reporting them SEPARATELY from failures
199
- # keeps "we could not" distinct from "there was nowhere to send".
200
- skipped.append({"customer": name, "reason": "no email address on the customer record"})
201
- continue
202
- try:
203
- mid = cs.queue_statement(cs.Odoo(), row, t.get("subject") or cs.DEFAULT_SUBJECT,
204
- t.get("intro") or cs.DEFAULT_INTRO,
205
- t.get("footer") or cs.DEFAULT_FOOTER, override_to=override)
206
- sent.append({"customer": name, "to": override or row.get("Email"), "mailId": mid})
207
- except Exception as e:
208
- # SafeModeBlocked lands here too, and that is correct: to the caller a guardrail refusal
209
- # and an Odoo error are both "this one did not go", each with its own honest message.
210
- failed.append({"customer": name, "error": str(e)[:200]})
211
- return {"sent": sent, "failed": failed, "skipped": skipped,
212
- "safeMode": bool(cs.SAFE_MODE), "test": bool(override)}
213
-
214
-
215
- # ---------------------------------------------------------------------------------------------
216
- # WAVE 35 Β· T36 / CONTRACT C8 / OWNER RULING R10 β€” THE AGENT'S PARKED BATCH.
217
- #
218
- # β›”β›” THE AGENT ASSEMBLES; A PERSON CLICKS SEND. `automation_engine.run_statements` renders a batch
219
- # and parks it on the automation definition, and it imports no mail path at all. THIS is the only
220
- # door that releases one, and it is deliberately built out of the parts already here:
221
- # Β· `_gate` β€” `admin_gate` THEN `_royal_only`, byte-for-byte the dependency the other three
222
- # endpoints use. Not a copy of the checks: the same object.
223
- # Β· `cs.queue_statement` β€” the same call `send()` above makes, so SAFE_MODE's allow-list refusal
224
- # happens in the DATA LAYER, where no route, payload or UI can reach around it.
225
- # β‡’ Nothing about the guardrails is re-expressed here, which is what makes "unchanged" checkable.
226
- #
227
- # ⚠ WHY THE BATCH IS RE-RENDERED FROM THE LIVE WORKLIST RATHER THAN SENT AS STORED. The parked
228
- # `html` is what a person APPROVED and is what the review screen shows; but a balance can move
229
- # between the parking and the click, and mailing a figure we know to be stale is worse than mailing
230
- # a fresh one. So the parked batch decides WHO and WITH WHAT WORDS, and the live row decides the
231
- # NUMBERS β€” the same split `preview` already makes. A customer who has left the worklist entirely
232
- # (they paid) is reported as skipped rather than invoiced.
233
-
234
- @router.get("/admin/statements/agent/{auto_id}")
235
- def agent_batch(auto_id: str, session: Session = Depends(_gate)):
236
- """What is parked and waiting for a click, for ONE agent. `null` when nothing is."""
237
- defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
238
- pending = defn.get("pendingStatements")
239
- if not isinstance(pending, dict):
240
- return {"pending": None}
241
- # ⚠ The rendered `html` is NOT returned in the list β€” a 200-statement batch of rendered mail is
242
- # megabytes, and the review screen needs the count and the names to decide. `preview` already
243
- # renders ONE on demand.
244
- return {"pending": {
245
- "ts": pending.get("ts"), "count": int(pending.get("count") or 0),
246
- "notes": list(pending.get("notes") or []),
247
- "items": [{k: v for k, v in it.items() if k != "html"}
248
- for it in (pending.get("items") or [])],
249
- "safeMode": bool(_cs().SAFE_MODE)}}
250
-
251
-
252
- @router.post("/admin/statements/agent/{auto_id}/send")
253
- def agent_send(auto_id: str, body: dict = Body(default=None),
254
- session: Session = Depends(_gate)):
255
- """Release a parked batch. THE CLICK R10 REQUIRES β€” nothing else in the system calls this.
256
-
257
- β›” IT REFUSES AN EMPTY OR MISSING BATCH rather than answering 200 with nothing sent: a send
258
- that reports success and mails nobody is the `view_upsert` failure mode (200 OK, zero writes)
259
- arriving on the one route in this system that talks to a mail server.
260
- """
261
- cs = _cs()
262
- defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
263
- pending = defn.get("pendingStatements")
264
- items = list((pending or {}).get("items") or []) if isinstance(pending, dict) else []
265
- if not items:
266
- raise err(404, "no_batch", "there is nothing parked for this agent to send")
267
- # ⚠ An explicit subset is allowed (a person unticking a customer on the review screen) but it
268
- # may only NARROW the parked batch. A name that was never parked cannot be introduced by the
269
- # payload, or the review stops being what authorised the send.
270
- want = {str(n) for n in (body or {}).get("customers") or []}
271
- if want:
272
- items = [it for it in items if str(it.get("customer")) in want]
273
- if not items:
274
- raise err(400, "bad_request", "none of those customers are in the parked batch")
275
- rows, _ = _rows()
276
- sent, failed, skipped = [], [], []
277
- for it in items:
278
- name = str(it.get("customer") or "")
279
- row = _find(rows, name)
280
- if row is None:
281
- skipped.append({"customer": name,
282
- "reason": "no longer on the collection list, so nothing is owed"})
283
- continue
284
- try:
285
- # β›” THE SAME DATA-LAYER CALL `send()` MAKES. SafeModeBlocked is raised INSIDE
286
- # `queue_statement`, so the guardrail cannot be argued with from here.
287
- mid = cs.queue_statement(cs.Odoo(), row,
288
- str(it.get("subject") or "") or cs.DEFAULT_SUBJECT,
289
- cs.DEFAULT_INTRO, cs.DEFAULT_FOOTER)
290
- sent.append({"customer": name, "to": row.get("Email"), "mailId": mid})
291
- except Exception as e: # noqa: BLE001
292
- failed.append({"customer": name, "error": str(e)[:200]})
293
- # ⚠ CLEARED ONLY WHEN NOTHING IS LEFT TO RETRY. A batch dropped while some of it failed would
294
- # lose the list of who still needs a statement, and nobody would know to look.
295
- if sent and not failed:
296
- engine.clear_statements(session.runtime, auto_id)
297
- return {"sent": sent, "failed": failed, "skipped": skipped,
298
- "safeMode": bool(cs.SAFE_MODE), "cleared": bool(sent and not failed)}
 
1
+ """routes_statements.py β€” the statement-of-account sender, ported off Streamlit (EXIT-6).
2
+
3
+ β›” THIS IS THE ONE SANCTIONED ODOO WRITER IN THE ENTIRE SYSTEM. Everything else in AIOS is
4
+ read-only on Odoo by hard block. `modules/collections_send.py` owns a narrow client that whitelists
5
+ exactly `mail.mail create` (queueing an outbound email) and nothing else; these routes call it and
6
+ add no write of their own.
7
+
8
+ WHY IT EXISTS SEPARATELY FROM THE COLLECTIONS PAGE. Owner ruling wave-17 item 15 retired the
9
+ Collections *dashboard* β€” the worklist is the shared "Collections" view on the Customer grid, from
10
+ the same reconciled blocks. What that ruling explicitly left "untouched" is this send workflow, so
11
+ when `app.py` is deleted it is the ONLY live Streamlit-only feature, and it moves here rather than
12
+ dying with the host. Ported faithfully: same tiers, same filters, same template placeholders, same
13
+ preview, same test-send, same two-step confirm.
14
+
15
+ THE THREE GUARDRAILS, and where each is enforced:
16
+ 1. SAFE_MODE (default ON) β€” in the DATA LAYER (`collections_send.queue_statement`), so no route,
17
+ payload or UI can bypass it. These routes only REPORT it; they never re-implement the check.
18
+ 2. Admin only β€” `admin_gate` (role, fail-closed), mirroring the Streamlit `if not is_admin()`.
19
+ 3. ⭐ TENANT β€” NEW HERE, and it did not exist in Streamlit because it could not. `cs_mod.Odoo()`
20
+ reads Odoo credentials from the ENVIRONMENT, which after the keychain cutover belongs to
21
+ TENANT #0 ALONE. On the multi-tenant API an unguarded route would let a nurilab or gtmlab
22
+ admin queue mail from Royal Imports' Odoo, as Royal Imports. `_royal_only` closes that; the
23
+ single-tenant Streamlit host never had the exposure, so this is a port that must ADD a wall
24
+ rather than copy one.
25
+
26
+ NOTHING SENDS ON A GET. The send route requires an explicit customer list in the body; there is no
27
+ "send all" parameter, deliberately β€” the confirm step is a product requirement, not a formality.
28
+ """
29
+ from fastapi import APIRouter, Body, Depends
30
+
31
+ from deps import Session, err
32
+ from routes_admin import admin_gate
33
+
34
+ # W35-T35 (C8): the tenant predicate, held once. See `_royal_only` for why the import runs this
35
+ # way round. `main.py` already imports both modules, so this adds no load.
36
+ import automation_engine as engine
37
+
38
+ router = APIRouter(prefix="/api/v1")
39
+
40
+ #: Cache the Odoo follow-up pull briefly. The Streamlit page used `@st.cache_data(ttl=1800)`; the
41
+ #: list moves slowly (it is a dunning worklist, not a live feed) and the pull is a multi-model read.
42
+ _TTL = 1800
43
+ _cache = {"at": 0.0, "rows": None}
44
+
45
+
46
+ def _cs():
47
+ import modules.collections_send as cs
48
+ return cs
49
+
50
+
51
+ def _royal_only(session: Session) -> Session:
52
+ """β›” See the module docstring, guardrail 3. The send client is env-credentialed, so it is
53
+ tenant #0's and only tenant #0's. Refuse for anyone else rather than send as the wrong company.
54
+
55
+ Keyed on the runtime, never on a request field: a tenant is a property of the SESSION.
56
+
57
+ ⭐⭐ WAVE 35 Β· T35 / CONTRACT C8 β€” THE TEST ITSELF NOW LIVES IN ONE PLACE. Statements became an
58
+ agent step this wave, so the automation engine has to answer the same question at two more
59
+ doors (which tenants see the action, which tenants may store it). C8's words are "the predicate
60
+ is imported, never re-expressed", and this is the direction that import can run: the engine
61
+ imports no route module and no FastAPI, so reaching `_royal_only` FROM it would drag `deps` and
62
+ `routes_admin` into a route-free module. The engine holds the boolean; this holds the refusal.
63
+ ⚠ WHAT STAYS HERE IS THE HTTP SHAPE, and that is deliberate β€” a 404 rather than a 403, so the
64
+ surface is invisible rather than forbidden. The engine must not know about status codes."""
65
+ if not engine.is_statement_tenant(session.runtime):
66
+ raise err(404, "not_found", "statements are not configured for this workspace")
67
+ return session
68
+
69
+
70
+ def _gate(session: Session = Depends(admin_gate)) -> Session:
71
+ return _royal_only(session)
72
+
73
+
74
+ def _rows(force=False):
75
+ import time
76
+ cs = _cs()
77
+ if force or _cache["rows"] is None or (time.time() - _cache["at"]) > _TTL:
78
+ _cache["rows"] = cs.load_collection_list(cs.Odoo())
79
+ _cache["at"] = time.time()
80
+ return _cache["rows"], time.strftime("%Y-%m-%d %H:%M", time.localtime(_cache["at"]))
81
+
82
+
83
+ def _public(row):
84
+ """Strip the internals the Streamlit grid also hid (`_`-prefixed + partner_id is kept, because
85
+ the client needs a stable row identity that is not the display name)."""
86
+ return {k: v for k, v in row.items() if not str(k).startswith("_")}
87
+
88
+
89
+ @router.get("/admin/statements")
90
+ def statements(refresh: int = 0, session: Session = Depends(_gate)):
91
+ """The worklist + everything the sender UI needs to render itself honestly."""
92
+ cs = _cs()
93
+ try:
94
+ rows, loaded_at = _rows(force=bool(refresh))
95
+ except Exception as e:
96
+ raise err(502, "odoo_unavailable", f"could not load the collection list: {str(e)[:200]}")
97
+ return {
98
+ "rows": [_public(r) for r in rows],
99
+ "loadedAt": loaded_at,
100
+ # The guardrail is reported, never decided, here β€” the data layer owns it.
101
+ "safeMode": bool(cs.SAFE_MODE),
102
+ "safeRecipients": sorted(cs.SAFE_RECIPIENTS),
103
+ "sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL,
104
+ "replyTo": cs.REPLY_TO, "company": cs.COMPANY},
105
+ "templates": {"subject": cs.DEFAULT_SUBJECT, "intro": cs.DEFAULT_INTRO,
106
+ "footer": cs.DEFAULT_FOOTER},
107
+ # W35-T35: ONE literal, read from the engine, so the sender's worklist and a statements
108
+ # agent's tier filter cannot come to mean different things.
109
+ "tiers": list(engine.STATEMENT_TIERS),
110
+ }
111
+
112
+
113
+ def _find(rows, customer):
114
+ return next((r for r in rows if r.get("Customer") == customer), None)
115
+
116
+
117
+ @router.post("/admin/statements/preview")
118
+ def preview(body: dict = Body(default=None), session: Session = Depends(_gate)):
119
+ """Render ONE customer's statement exactly as the send path would."""
120
+ cs = _cs()
121
+ body = body or {}
122
+ rows, _ = _rows()
123
+ row = _find(rows, body.get("customer"))
124
+ if row is None:
125
+ raise err(404, "not_found", "no such customer on the collection list")
126
+ t = body.get("templates") or {}
127
+ import datetime as dt
128
+ month = dt.date.today().strftime("%B %Y")
129
+ subject = (t.get("subject") or cs.DEFAULT_SUBJECT)
130
+ try:
131
+ subject = subject.format(customer=row["Customer"], company=cs.COMPANY, month=month)
132
+ except Exception: # noqa: BLE001
133
+ # An unknown placeholder is the user's typo, not a 500. Show the template verbatim so they
134
+ # can see what they typed rather than getting an opaque error.
135
+ # β›” W36-T42: THIS CAUGHT THREE OF THE WAYS `str.format` FAILS AND THERE ARE MORE.
136
+ # `{customer` is a ValueError, `{customer.x}` an AttributeError, `{customer:%Y}` a
137
+ # TypeError, and every one of them is the same user mistake this branch was written for.
138
+ # Naming a subset of the exception types turns a typo in the OTHER half into a 500 on the
139
+ # one screen somebody opens to avoid mailing 200 people the wrong thing.
140
+ pass
141
+ return {
142
+ "html": cs.render_statement_html(row, t.get("intro") or cs.DEFAULT_INTRO,
143
+ t.get("footer") or cs.DEFAULT_FOOTER),
144
+ "to": row.get("Email") or "",
145
+ "subject": subject,
146
+ }
147
+
148
+
149
+ @router.post("/admin/statements/send")
150
+ def send(body: dict = Body(default=None), session: Session = Depends(_gate)):
151
+ """Queue statements. Returns per-customer outcomes β€” NEVER a bare count.
152
+
153
+ `overrideTo` is the test-send path: one customer, one address. SAFE_MODE still applies (the
154
+ data layer refuses an address outside the allow-list), which is why the route does not check it.
155
+ """
156
+ cs = _cs()
157
+ body = body or {}
158
+ names = [str(n) for n in (body.get("customers") or []) if str(n).strip()]
159
+ if not names:
160
+ raise err(400, "bad_request", "name at least one customer")
161
+ # β›”β›” W36-T42 / D-299 β€” A DECLARED TEST SEND WITH NO ADDRESS REFUSES. IT DOES NOT BECOME A
162
+ # REAL ONE. This read `(body.get("overrideTo") or "").strip() or None`, so a caller who sent
163
+ # `overrideTo: ""` (the field left blank, the state not yet typed into, a trimmed-away space)
164
+ # got a REAL statement mailed to the debtor's own address, reported back as `test: false`. On
165
+ # the one route in this product that is allowed to write to Odoo, the difference between a
166
+ # rehearsal and mailing a live customer was one empty string.
167
+ #
168
+ # ⭐ THE DISCRIMINATOR IS THE CALLER'S DECLARATION, NOT THE VALUE. A body with no `overrideTo`
169
+ # key and no `test` flag is the PRODUCTION send, and refusing that would delete the feature
170
+ # D-299 exists to preserve. What can be refused is a caller who SAID this is a test: the key
171
+ # being present, or `test: true`, is that statement, and an empty address beside it is the
172
+ # mistake. So both spellings of "absent" are covered: the key present and blank, and `test`
173
+ # asserted with no key at all.
174
+ #
175
+ # ⚠ THIS IS THE SECOND OF THREE WALLS AND THE ONLY ONE A PAYLOAD CANNOT ROUTE AROUND.
176
+ # `automationApi.testSendStatement` refuses an empty address before the request is built, and
177
+ # SAFE_MODE refuses an address outside the allow-list inside `queue_statement`. The client
178
+ # wall is bypassable by construction (anything can POST); this one is not.
179
+ declared_test = ("overrideTo" in body) or bool(body.get("test"))
180
+ override = str(body.get("overrideTo") or "").strip()
181
+ if declared_test and not override:
182
+ raise err(400, "no_override_address",
183
+ "a test send needs the address to send the test to. Without one this would "
184
+ "mail the customer's own address, which is the opposite of a test")
185
+ override = override or None
186
+ if override and len(names) != 1:
187
+ raise err(400, "bad_request", "a test send takes exactly one customer")
188
+ t = body.get("templates") or {}
189
+ rows, _ = _rows()
190
+
191
+ sent, failed, skipped = [], [], []
192
+ for name in names:
193
+ row = _find(rows, name)
194
+ if row is None:
195
+ failed.append({"customer": name, "error": "not on the current collection list"})
196
+ continue
197
+ if not override and not row.get("Email"):
198
+ # The Streamlit page warned and skipped these. Reporting them SEPARATELY from failures
199
+ # keeps "we could not" distinct from "there was nowhere to send".
200
+ skipped.append({"customer": name, "reason": "no email address on the customer record"})
201
+ continue
202
+ try:
203
+ mid = cs.queue_statement(cs.Odoo(), row, t.get("subject") or cs.DEFAULT_SUBJECT,
204
+ t.get("intro") or cs.DEFAULT_INTRO,
205
+ t.get("footer") or cs.DEFAULT_FOOTER, override_to=override)
206
+ sent.append({"customer": name, "to": override or row.get("Email"), "mailId": mid})
207
+ except Exception as e:
208
+ # SafeModeBlocked lands here too, and that is correct: to the caller a guardrail refusal
209
+ # and an Odoo error are both "this one did not go", each with its own honest message.
210
+ failed.append({"customer": name, "error": str(e)[:200]})
211
+ return {"sent": sent, "failed": failed, "skipped": skipped,
212
+ "safeMode": bool(cs.SAFE_MODE), "test": bool(override)}
213
+
214
+
215
+ # ---------------------------------------------------------------------------------------------
216
+ # WAVE 35 Β· T36 / CONTRACT C8 / OWNER RULING R10 β€” THE AGENT'S PARKED BATCH.
217
+ #
218
+ # β›”β›” THE AGENT ASSEMBLES; A PERSON CLICKS SEND. `automation_engine.run_statements` renders a batch
219
+ # and parks it on the automation definition, and it imports no mail path at all. THIS is the only
220
+ # door that releases one, and it is deliberately built out of the parts already here:
221
+ # Β· `_gate` β€” `admin_gate` THEN `_royal_only`, byte-for-byte the dependency the other three
222
+ # endpoints use. Not a copy of the checks: the same object.
223
+ # Β· `cs.queue_statement` β€” the same call `send()` above makes, so SAFE_MODE's allow-list refusal
224
+ # happens in the DATA LAYER, where no route, payload or UI can reach around it.
225
+ # β‡’ Nothing about the guardrails is re-expressed here, which is what makes "unchanged" checkable.
226
+ #
227
+ # ⚠ WHY THE BATCH IS RE-RENDERED FROM THE LIVE WORKLIST RATHER THAN SENT AS STORED. The parked
228
+ # `html` is what a person APPROVED and is what the review screen shows; but a balance can move
229
+ # between the parking and the click, and mailing a figure we know to be stale is worse than mailing
230
+ # a fresh one. So the parked batch decides WHO and WITH WHAT WORDS, and the live row decides the
231
+ # NUMBERS β€” the same split `preview` already makes. A customer who has left the worklist entirely
232
+ # (they paid) is reported as skipped rather than invoiced.
233
+
234
+ @router.get("/admin/statements/agent/{auto_id}")
235
+ def agent_batch(auto_id: str, session: Session = Depends(_gate)):
236
+ """What is parked and waiting for a click, for ONE agent. `null` when nothing is."""
237
+ defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
238
+ pending = defn.get("pendingStatements")
239
+ if not isinstance(pending, dict):
240
+ return {"pending": None}
241
+ # ⚠ The rendered `html` is NOT returned in the list β€” a 200-statement batch of rendered mail is
242
+ # megabytes, and the review screen needs the count and the names to decide. `preview` already
243
+ # renders ONE on demand.
244
+ return {"pending": {
245
+ "ts": pending.get("ts"), "count": int(pending.get("count") or 0),
246
+ "notes": list(pending.get("notes") or []),
247
+ "items": [{k: v for k, v in it.items() if k != "html"}
248
+ for it in (pending.get("items") or [])],
249
+ "safeMode": bool(_cs().SAFE_MODE)}}
250
+
251
+
252
+ @router.post("/admin/statements/agent/{auto_id}/send")
253
+ def agent_send(auto_id: str, body: dict = Body(default=None),
254
+ session: Session = Depends(_gate)):
255
+ """Release a parked batch. THE CLICK R10 REQUIRES β€” nothing else in the system calls this.
256
+
257
+ β›” IT REFUSES AN EMPTY OR MISSING BATCH rather than answering 200 with nothing sent: a send
258
+ that reports success and mails nobody is the `view_upsert` failure mode (200 OK, zero writes)
259
+ arriving on the one route in this system that talks to a mail server.
260
+ """
261
+ cs = _cs()
262
+ defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
263
+ pending = defn.get("pendingStatements")
264
+ items = list((pending or {}).get("items") or []) if isinstance(pending, dict) else []
265
+ if not items:
266
+ raise err(404, "no_batch", "there is nothing parked for this agent to send")
267
+ # ⚠ An explicit subset is allowed (a person unticking a customer on the review screen) but it
268
+ # may only NARROW the parked batch. A name that was never parked cannot be introduced by the
269
+ # payload, or the review stops being what authorised the send.
270
+ want = {str(n) for n in (body or {}).get("customers") or []}
271
+ if want:
272
+ items = [it for it in items if str(it.get("customer")) in want]
273
+ if not items:
274
+ raise err(400, "bad_request", "none of those customers are in the parked batch")
275
+ rows, _ = _rows()
276
+ sent, failed, skipped = [], [], []
277
+ for it in items:
278
+ name = str(it.get("customer") or "")
279
+ row = _find(rows, name)
280
+ if row is None:
281
+ skipped.append({"customer": name,
282
+ "reason": "no longer on the collection list, so nothing is owed"})
283
+ continue
284
+ try:
285
+ # β›” THE SAME DATA-LAYER CALL `send()` MAKES. SafeModeBlocked is raised INSIDE
286
+ # `queue_statement`, so the guardrail cannot be argued with from here.
287
+ mid = cs.queue_statement(cs.Odoo(), row,
288
+ str(it.get("subject") or "") or cs.DEFAULT_SUBJECT,
289
+ cs.DEFAULT_INTRO, cs.DEFAULT_FOOTER)
290
+ sent.append({"customer": name, "to": row.get("Email"), "mailId": mid})
291
+ except Exception as e: # noqa: BLE001
292
+ failed.append({"customer": name, "error": str(e)[:200]})
293
+ # ⚠ CLEARED ONLY WHEN NOTHING IS LEFT TO RETRY. A batch dropped while some of it failed would
294
+ # lose the list of who still needs a statement, and nobody would know to look.
295
+ if sent and not failed:
296
+ engine.clear_statements(session.runtime, auto_id)
297
+ return {"sent": sent, "failed": failed, "skipped": skipped,
298
+ "safeMode": bool(cs.SAFE_MODE), "cleared": bool(sent and not failed)}
api/routes_tables.py CHANGED
@@ -1740,6 +1740,11 @@ def list_tables(brief: bool = Query(False),
1740
  lent = ut.lend(session.runtime, **{ut.STORE_KEY: tables})
1741
  for key, t in sorted(tables.items(),
1742
  key=lambda kv: (ut_label(kv[1], kv[0], meta) or "").lower()):
 
 
 
 
 
1743
  if not ut.may_open(key, session.uname, session.admin, st=lent):
1744
  continue
1745
  row = {"key": key, "label": ut_label(t, key, meta),
@@ -1757,18 +1762,9 @@ def list_tables(brief: bool = Query(False),
1757
  # picker renders this order verbatim.
1758
  out.extend(_module_link_targets(session, meta, st=lent))
1759
  out.sort(key=lambda r: (r.get("label") or "").lower())
1760
- else:
1761
- # C1's Loopable folder has virtual descriptor rows even before the first Route/Zone
1762
- # exists. They deliberately do NOT enter `brief=1`: stops are a protected relation,
1763
- # never a generic Link target.
1764
- try:
1765
- session.require("customer_data")
1766
- except Exception:
1767
- pass
1768
- else:
1769
- from core import route_system
1770
- out.extend(route_system.system_table_descriptors())
1771
- out.sort(key=lambda r: (r.get("label") or "").lower())
1772
  return {"tables": out}
1773
 
1774
 
@@ -2239,7 +2235,8 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
2239
  # Zone memberships are row identities and therefore pass through the same row wall as the
2240
  # rows themselves. A map reader cannot infer a hidden record from a saved zone boundary.
2241
  _zone_pids = {str(pid) for pid in g["pids"]}
2242
- _zones = [dict(zone, memberships=[pid for pid in zone.get("memberships", [])
 
2243
  if str(pid) in _zone_pids])
2244
  for zone in _ut().zones(table_key, st=_lent)]
2245
  return {"fields": _field_axes(g["fields"]), "rows": rows, "today": g["today"],
 
1740
  lent = ut.lend(session.runtime, **{ut.STORE_KEY: tables})
1741
  for key, t in sorted(tables.items(),
1742
  key=lambda kv: (ut_label(kv[1], kv[0], meta) or "").lower()):
1743
+ # Defense in depth for legacy or malformed documents. Generic creation refuses these
1744
+ # keys, but a pre-existing collision must still never disclose a Loopable system store in
1745
+ # either the full database manager or the brief link-field picker.
1746
+ if ut.is_managed_system_table(key, st=lent, definition=t):
1747
+ continue
1748
  if not ut.may_open(key, session.uname, session.admin, st=lent):
1749
  continue
1750
  row = {"key": key, "label": ut_label(t, key, meta),
 
1762
  # picker renders this order verbatim.
1763
  out.extend(_module_link_targets(session, meta, st=lent))
1764
  out.sort(key=lambda r: (r.get("label") or "").lower())
1765
+ # Loopable-owned backing stores never enter either ordinary table index. Platform admins
1766
+ # inspect their definition-only descriptors through /admin/system-data; all other users must
1767
+ # be unable to discover them through response data, even when they can use Routes or Zones.
 
 
 
 
 
 
 
 
 
1768
  return {"tables": out}
1769
 
1770
 
 
2235
  # Zone memberships are row identities and therefore pass through the same row wall as the
2236
  # rows themselves. A map reader cannot infer a hidden record from a saved zone boundary.
2237
  _zone_pids = {str(pid) for pid in g["pids"]}
2238
+ from core import route_system as _route_zones
2239
+ _zones = [dict(zone, memberships=[pid for pid in _route_zones.zone_members(zone, rows)
2240
  if str(pid) in _zone_pids])
2241
  for zone in _ut().zones(table_key, st=_lent)]
2242
  return {"fields": _field_axes(g["fields"]), "rows": rows, "today": g["today"],
api/routes_web_agent.py CHANGED
@@ -1,84 +1,84 @@
1
- """routes_web_agent.py β€” the door that lets a person TEST the web agent (wave 31, R10 / D-51).
2
-
3
- The owner's words are the whole reason this file exists: *"we already laid the foundation of this
4
- but never test anything."* The capability is otherwise reachable only from inside an automation
5
- run, which means the first person to discover it is broken is a customer at 3am.
6
-
7
- GET /api/v1/web-agent/capability any session β€” can this deployment run a web step, and
8
- if not, the SENTENCE saying why
9
- POST /api/v1/web-agent/test ADMIN β€” run one real `web_read` and show what
10
- came back, or the sentence
11
-
12
- β›” NEITHER ROUTE IS THE SEAM. `automation_engine` calls `web_agent.run_step` directly (contract
13
- C5); these are an operator surface over the same function, so a green test here and a red run
14
- there cannot disagree about anything except the input.
15
-
16
- ⚠ `POST /test` BLOCKS FOR ~10-30 s and COSTS A FRACTION OF A CENT. It is `def`, not `async def`,
17
- so FastAPI runs it in the threadpool and one test cannot stall the event loop for everybody.
18
-
19
- ⚠ ON THE URL IT WILL FETCH: the fetch happens inside an ephemeral HF Job on Hugging Face's
20
- network, never from this server, so this is not a door into our own infrastructure. It is still
21
- admin-gated, because it spends money and because D-51 Β§5's authorisation posture ("only systems
22
- the tenant is authorised to use, at their instruction") is not something an ordinary member
23
- should be able to commit the tenant to.
24
-
25
- ⭐ MOUNTED, and the gate is what says so rather than this sentence: `main.py:80` imports it and
26
- `main.py:316` includes it, and `verify_web_agent.py` asserts the route answers rather than trusting
27
- either line. This paragraph read "NOT MOUNTED YET" for a whole wave after the mount landed, which
28
- is the same class of stale claim as a green gate on a router nobody wired: three finished routers
29
- once shipped 404-dead behind entirely green gates, and prose is not the control that stops it.
30
- """
31
- from fastapi import APIRouter, Body, Depends
32
-
33
- import web_agent
34
- from deps import Session, require_session, err
35
- from routes_admin import admin_gate
36
-
37
- router = APIRouter(prefix="/api/v1")
38
-
39
- MAX_URL = 2000
40
- MAX_SELECTOR = 400
41
-
42
-
43
- @router.get("/web-agent/capability")
44
- def web_agent_capability(session: Session = Depends(require_session)):
45
- """Can a web step run here at all? Configuration, not liveness β€” see `web_agent.capability`.
46
-
47
- Deliberately NARROW: it answers the question a UI needs ("may I offer this, and what do I say
48
- if not") and withholds the deployment detail (namespace, which token key, the image) that
49
- only an operator has any use for. Nothing here is ever a credential.
50
- """
51
- cap = web_agent.capability()
52
- return {"ready": bool(cap["ready"]), "reason": cap["reason"],
53
- "runnableKinds": cap["runnableKinds"], "profile": cap["profile"]}
54
-
55
-
56
- @router.post("/web-agent/test")
57
- def web_agent_test(session: Session = Depends(admin_gate), body: dict = Body(...)):
58
- """Run ONE real `web_read` and report exactly what the seam returned.
59
-
60
- The response mirrors the seam's own contract rather than flattening it: `ok` plus a `value`,
61
- or `ok:false` plus the SENTENCE. A test surface that turns a named failure into "something
62
- went wrong" would hide the one thing it exists to show.
63
- """
64
- url = str(body.get("url") or "").strip()
65
- selector = str(body.get("selector") or "").strip()
66
- if len(url) > MAX_URL or len(selector) > MAX_SELECTOR:
67
- raise err(400, "too_long", "the URL or selector is longer than this door accepts")
68
-
69
- step = {"kind": "web_read", "id": "test", "url": url, "selector": selector,
70
- "attr": (body.get("attr") or "text"), "all": bool(body.get("all")),
71
- "timeoutMs": int(body.get("timeoutMs") or 20000)}
72
- if body.get("waitFor"):
73
- step["waitFor"] = str(body["waitFor"])
74
-
75
- notes = []
76
- result, error = web_agent.run_step(
77
- step, {"tenant": session.tenant, "runId": f"test-{session.tenant}-{session.uname}",
78
- "log": notes.append})
79
- if error:
80
- # 200 with `ok:false`, not a 4xx: the request was well-formed and the ANSWER is that the
81
- # web step did not succeed. A 500 here would make an ordinary "the selector matched
82
- # nothing" look like a server fault.
83
- return {"ok": False, "error": error, "log": notes[-6:]}
84
- return {"ok": True, "result": result, "log": notes[-6:]}
 
1
+ """routes_web_agent.py β€” the door that lets a person TEST the web agent (wave 31, R10 / D-51).
2
+
3
+ The owner's words are the whole reason this file exists: *"we already laid the foundation of this
4
+ but never test anything."* The capability is otherwise reachable only from inside an automation
5
+ run, which means the first person to discover it is broken is a customer at 3am.
6
+
7
+ GET /api/v1/web-agent/capability any session β€” can this deployment run a web step, and
8
+ if not, the SENTENCE saying why
9
+ POST /api/v1/web-agent/test ADMIN β€” run one real `web_read` and show what
10
+ came back, or the sentence
11
+
12
+ β›” NEITHER ROUTE IS THE SEAM. `automation_engine` calls `web_agent.run_step` directly (contract
13
+ C5); these are an operator surface over the same function, so a green test here and a red run
14
+ there cannot disagree about anything except the input.
15
+
16
+ ⚠ `POST /test` BLOCKS FOR ~10-30 s and COSTS A FRACTION OF A CENT. It is `def`, not `async def`,
17
+ so FastAPI runs it in the threadpool and one test cannot stall the event loop for everybody.
18
+
19
+ ⚠ ON THE URL IT WILL FETCH: the fetch happens inside an ephemeral HF Job on Hugging Face's
20
+ network, never from this server, so this is not a door into our own infrastructure. It is still
21
+ admin-gated, because it spends money and because D-51 Β§5's authorisation posture ("only systems
22
+ the tenant is authorised to use, at their instruction") is not something an ordinary member
23
+ should be able to commit the tenant to.
24
+
25
+ ⭐ MOUNTED, and the gate is what says so rather than this sentence: `main.py:80` imports it and
26
+ `main.py:316` includes it, and `verify_web_agent.py` asserts the route answers rather than trusting
27
+ either line. This paragraph read "NOT MOUNTED YET" for a whole wave after the mount landed, which
28
+ is the same class of stale claim as a green gate on a router nobody wired: three finished routers
29
+ once shipped 404-dead behind entirely green gates, and prose is not the control that stops it.
30
+ """
31
+ from fastapi import APIRouter, Body, Depends
32
+
33
+ import web_agent
34
+ from deps import Session, require_session, err
35
+ from routes_admin import admin_gate
36
+
37
+ router = APIRouter(prefix="/api/v1")
38
+
39
+ MAX_URL = 2000
40
+ MAX_SELECTOR = 400
41
+
42
+
43
+ @router.get("/web-agent/capability")
44
+ def web_agent_capability(session: Session = Depends(require_session)):
45
+ """Can a web step run here at all? Configuration, not liveness β€” see `web_agent.capability`.
46
+
47
+ Deliberately NARROW: it answers the question a UI needs ("may I offer this, and what do I say
48
+ if not") and withholds the deployment detail (namespace, which token key, the image) that
49
+ only an operator has any use for. Nothing here is ever a credential.
50
+ """
51
+ cap = web_agent.capability()
52
+ return {"ready": bool(cap["ready"]), "reason": cap["reason"],
53
+ "runnableKinds": cap["runnableKinds"], "profile": cap["profile"]}
54
+
55
+
56
+ @router.post("/web-agent/test")
57
+ def web_agent_test(session: Session = Depends(admin_gate), body: dict = Body(...)):
58
+ """Run ONE real `web_read` and report exactly what the seam returned.
59
+
60
+ The response mirrors the seam's own contract rather than flattening it: `ok` plus a `value`,
61
+ or `ok:false` plus the SENTENCE. A test surface that turns a named failure into "something
62
+ went wrong" would hide the one thing it exists to show.
63
+ """
64
+ url = str(body.get("url") or "").strip()
65
+ selector = str(body.get("selector") or "").strip()
66
+ if len(url) > MAX_URL or len(selector) > MAX_SELECTOR:
67
+ raise err(400, "too_long", "the URL or selector is longer than this door accepts")
68
+
69
+ step = {"kind": "web_read", "id": "test", "url": url, "selector": selector,
70
+ "attr": (body.get("attr") or "text"), "all": bool(body.get("all")),
71
+ "timeoutMs": int(body.get("timeoutMs") or 20000)}
72
+ if body.get("waitFor"):
73
+ step["waitFor"] = str(body["waitFor"])
74
+
75
+ notes = []
76
+ result, error = web_agent.run_step(
77
+ step, {"tenant": session.tenant, "runId": f"test-{session.tenant}-{session.uname}",
78
+ "log": notes.append})
79
+ if error:
80
+ # 200 with `ok:false`, not a 4xx: the request was well-formed and the ANSWER is that the
81
+ # web step did not succeed. A 500 here would make an ordinary "the selector matched
82
+ # nothing" look like a server fault.
83
+ return {"ok": False, "error": error, "log": notes[-6:]}
84
+ return {"ok": True, "result": result, "log": notes[-6:]}
platform/core/grid_events.py CHANGED
@@ -1481,11 +1481,25 @@ def handle_one(event, ctx):
1481
  # ⭐⭐ W41-T20 clause 5 / C6 -- see `_clean_secondary_view` above.
1482
  'secondaryView': _clean_secondary_view(cfg.get('secondaryView')),
1483
  }
1484
- # Wave-6 item 10: a non-grid display mode rides the view config, validated
1485
- # structurally (mode whitelist, refs must be this table's fields).
1486
- display = _ag._clean_display(cfg.get('display'), valid_keys)
1487
- if display:
1488
- config['display'] = display
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1489
  # Wave-6 item 11 (pin): how many leading columns stay frozen while scrolling
1490
  # sideways. Clamped 1..8 β€” 0 would unfreeze the identity column the whole
1491
  # surface pivots on; absent = the legacy single frozen column.
@@ -1538,6 +1552,10 @@ def handle_one(event, ctx):
1538
  and prior.get('kind') != 'system'
1539
  and view_id != 'all-customers')
1540
  if _mode_frozen:
 
 
 
 
1541
  if prior.get('config', {}).get('display'):
1542
  config['display'] = dict(prior['config']['display'])
1543
  else:
 
1481
  # ⭐⭐ W41-T20 clause 5 / C6 -- see `_clean_secondary_view` above.
1482
  'secondaryView': _clean_secondary_view(cfg.get('secondaryView')),
1483
  }
1484
+ # W45 C3: a View either owns a direct display spec OR references one reusable
1485
+ # Application. It never stores both. The identity/revision cleaner is shared with the
1486
+ # template projection, and this is its production write path (not a verifier-only helper).
1487
+ from core import view_templates as _view_templates
1488
+ application = None
1489
+ if cfg.get('application') is not None:
1490
+ application = _view_templates.application_ref({'config': cfg})
1491
+ if application is None:
1492
+ _refuse(ctx, 'invalid_application_ref',
1493
+ 'that Application reference is not a valid typed identity', view_id)
1494
+ return False
1495
+ config['application'] = application
1496
+ # Wave-6 item 10: a direct non-grid display mode rides the view config, validated
1497
+ # structurally (mode whitelist, refs must be this table's fields). A bound Application's
1498
+ # config remains in the registry and is resolved on read, so an offered clone is dropped.
1499
+ if application is None:
1500
+ display = _ag._clean_display(cfg.get('display'), valid_keys)
1501
+ if display:
1502
+ config['display'] = display
1503
  # Wave-6 item 11 (pin): how many leading columns stay frozen while scrolling
1504
  # sideways. Clamped 1..8 β€” 0 would unfreeze the identity column the whole
1505
  # surface pivots on; absent = the legacy single frozen column.
 
1552
  and prior.get('kind') != 'system'
1553
  and view_id != 'all-customers')
1554
  if _mode_frozen:
1555
+ if prior.get('config', {}).get('application'):
1556
+ config['application'] = dict(prior['config']['application'])
1557
+ else:
1558
+ config.pop('application', None)
1559
  if prior.get('config', {}).get('display'):
1560
  config['display'] = dict(prior['config']['display'])
1561
  else:
platform/core/route_system.py CHANGED
@@ -20,6 +20,7 @@ LOOPABLE_FOLDER = {"id": LOOPABLE_FOLDER_ID, "name": "Loopable", "managedBy": MA
20
  ROUTES_KEY, ZONES_KEY = "ut_odoo_customers_routes", "ut_odoo_customers_zones"
21
  SYSTEM_TABLES = {ROUTES_KEY: "Odoo Customers - Routes", ZONES_KEY: "Odoo Customers - Zones"}
22
  ZONE_FIELD_KEY = "__zone__"
 
23
  CLIENT_ZONE_MEMBERSHIP_KEYS = frozenset(("memberPids", "member_pids", "memberships"))
24
 
25
  # TenantRuntime namespaces this bucket. User-table rows are scalar user data; route stops are a
@@ -124,6 +125,12 @@ def _now():
124
 
125
  def _store(st):
126
  try:
 
 
 
 
 
 
127
  return dict(st.get(STORE_KEY) or {})
128
  except Exception:
129
  return {}
@@ -313,7 +320,9 @@ def point_in_zone(geometry, lon, lat):
313
  def _zone(raw, *, ordinal=0, created_by="", tenant_id="", prior=None):
314
  raw = raw if isinstance(raw, dict) else {}
315
  prior = prior if isinstance(prior, dict) else {}
316
- name = _name(raw.get("name", prior.get("name")))
 
 
317
  geometry = clean_zone_geometry(raw.get("geometryGeoJson", prior.get("geometryGeoJson")))
318
  zips_raw = raw.get("zipCodes", prior.get("zipCodes", ()))
319
  zips, seen = [], set()
@@ -324,13 +333,17 @@ def _zone(raw, *, ordinal=0, created_by="", tenant_id="", prior=None):
324
  zips.append(text)
325
  if not name or geometry is None:
326
  return None
 
 
 
327
  zid = str(raw.get("id") or prior.get("id") or "zone_" + uuid.uuid4().hex)[:96]
328
  source_view = raw.get("sourceViewId", prior.get("sourceViewId"))
329
  source_view = str(source_view or "").strip()[:120] or None
330
  geographic_field = raw.get("geographicField", prior.get("geographicField"))
331
  geographic_field = str(geographic_field or "").strip()[:120]
332
  stamp = _now()
333
- return {"id": zid, "tenantId": str(tenant_id or prior.get("tenantId") or ""), "name": name,
 
334
  "color": _color(raw.get("color", prior.get("color")), ordinal),
335
  "geometryGeoJson": geometry,
336
  "zipCodes": zips, "visible": raw.get("visible", prior.get("visible", True)) is not False,
@@ -767,8 +780,19 @@ def reorder_route_folders(st, username, order, routes=(), *, legacy_folders=(),
767
  legacy_folders=legacy_folders, legacy_placements=legacy_placements)
768
 
769
 
770
- def list_zones(st, rows=None):
771
- return [copy.deepcopy(zone) for zone in read(st, rows).get("zones") or [] if isinstance(zone, dict)]
 
 
 
 
 
 
 
 
 
 
 
772
 
773
 
774
  def put_route(st, raw, *, tenant_id, created_by, today=None):
@@ -880,19 +904,24 @@ def delete_route(st, route_id, *, today=None):
880
  return bool(_persist(st, mutate))
881
 
882
 
883
- def put_zone(st, raw, *, rows, tenant_id, created_by):
884
  # Membership is always derived from the permission-scoped current rows supplied by the
885
  # mounted route. Refuse forged membership keys instead of silently lending them authority.
886
  if not isinstance(raw, dict) or any(key in raw for key in CLIENT_ZONE_MEMBERSHIP_KEYS):
887
  return None
 
 
 
888
  wanted = str((raw or {}).get("id") or "").strip()
889
 
890
  def mutate(state):
891
  zones = list(state.get("zones") or [])
892
  prior_index = next((index for index, item in enumerate(zones)
893
- if isinstance(item, dict) and item.get("id") == wanted), None)
 
894
  prior = zones[prior_index] if prior_index is not None else None
895
- clean = _zone(raw, ordinal=prior_index if prior_index is not None else len(zones),
 
896
  created_by=created_by, tenant_id=tenant_id, prior=prior)
897
  if clean is None:
898
  return state, None
@@ -910,17 +939,35 @@ def put_zone(st, raw, *, rows, tenant_id, created_by):
910
  return _persist(st, mutate)
911
 
912
 
913
- def delete_zone(st, zone_id):
914
  zone_id = str(zone_id or "").strip()
 
915
 
916
  def mutate(state):
917
  prior = list(state.get("zones") or [])
918
- state["zones"] = [item for item in prior if not (isinstance(item, dict) and item.get("id") == zone_id)]
 
 
919
  return state, len(prior) != len(state["zones"])
920
 
921
  return bool(_persist(st, mutate))
922
 
923
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
924
  def customer_projections(routes, zones):
925
  """Derived read-only customer multi-select values; stops are never generic Link cells."""
926
  projections = {}
 
20
  ROUTES_KEY, ZONES_KEY = "ut_odoo_customers_routes", "ut_odoo_customers_zones"
21
  SYSTEM_TABLES = {ROUTES_KEY: "Odoo Customers - Routes", ZONES_KEY: "Odoo Customers - Zones"}
22
  ZONE_FIELD_KEY = "__zone__"
23
+ DEFAULT_ZONE_TABLE = "customer_data"
24
  CLIENT_ZONE_MEMBERSHIP_KEYS = frozenset(("memberPids", "member_pids", "memberships"))
25
 
26
  # TenantRuntime namespaces this bucket. User-table rows are scalar user data; route stops are a
 
125
 
126
  def _store(st):
127
  try:
128
+ projected = getattr(st, "get_projection", None)
129
+ if callable(projected):
130
+ # The normalized Route/Zone document is definition-sized. Read it through the
131
+ # projection door so a database switch does not add another whole-document copy to
132
+ # the exact workspace budget; mutating callers still use update()'s strict whole read.
133
+ return dict(projected(STORE_KEY, drop=()) or {})
134
  return dict(st.get(STORE_KEY) or {})
135
  except Exception:
136
  return {}
 
320
  def _zone(raw, *, ordinal=0, created_by="", tenant_id="", prior=None):
321
  raw = raw if isinstance(raw, dict) else {}
322
  prior = prior if isinstance(prior, dict) else {}
323
+ # Grid multiselect cells use comma-delimited display values, so one Zone label cannot contain
324
+ # a comma without presenting itself as two choices to the filter/sort contract.
325
+ name = _name(str(raw.get("name", prior.get("name")) or "").replace(",", " "))
326
  geometry = clean_zone_geometry(raw.get("geometryGeoJson", prior.get("geometryGeoJson")))
327
  zips_raw = raw.get("zipCodes", prior.get("zipCodes", ()))
328
  zips, seen = [], set()
 
333
  zips.append(text)
334
  if not name or geometry is None:
335
  return None
336
+ table_key = str(raw.get("tableKey") or prior.get("tableKey") or DEFAULT_ZONE_TABLE).strip()[:120]
337
+ if not table_key:
338
+ return None
339
  zid = str(raw.get("id") or prior.get("id") or "zone_" + uuid.uuid4().hex)[:96]
340
  source_view = raw.get("sourceViewId", prior.get("sourceViewId"))
341
  source_view = str(source_view or "").strip()[:120] or None
342
  geographic_field = raw.get("geographicField", prior.get("geographicField"))
343
  geographic_field = str(geographic_field or "").strip()[:120]
344
  stamp = _now()
345
+ return {"id": zid, "tenantId": str(tenant_id or prior.get("tenantId") or ""),
346
+ "tableKey": table_key, "name": name,
347
  "color": _color(raw.get("color", prior.get("color")), ordinal),
348
  "geometryGeoJson": geometry,
349
  "zipCodes": zips, "visible": raw.get("visible", prior.get("visible", True)) is not False,
 
780
  legacy_folders=legacy_folders, legacy_placements=legacy_placements)
781
 
782
 
783
+ def _zone_table_key(zone):
784
+ """Old normalized Zones predate table scoping and belong to the customer database."""
785
+ return str((zone or {}).get("tableKey") or DEFAULT_ZONE_TABLE)
786
+
787
+
788
+ def list_zones(st, rows=None, *, table_key=DEFAULT_ZONE_TABLE):
789
+ """Zones for exactly one database; current rows refresh only that database's memberships."""
790
+ wanted = str(table_key or DEFAULT_ZONE_TABLE).strip()
791
+ selected = [copy.deepcopy(zone) for zone in read(st).get("zones") or []
792
+ if isinstance(zone, dict) and _zone_table_key(zone) == wanted]
793
+ if rows is not None:
794
+ selected = refresh_zone_memberships({"zones": selected}, rows).get("zones") or []
795
+ return selected
796
 
797
 
798
  def put_route(st, raw, *, tenant_id, created_by, today=None):
 
904
  return bool(_persist(st, mutate))
905
 
906
 
907
+ def put_zone(st, raw, *, rows, tenant_id, created_by, table_key=DEFAULT_ZONE_TABLE):
908
  # Membership is always derived from the permission-scoped current rows supplied by the
909
  # mounted route. Refuse forged membership keys instead of silently lending them authority.
910
  if not isinstance(raw, dict) or any(key in raw for key in CLIENT_ZONE_MEMBERSHIP_KEYS):
911
  return None
912
+ table_key = str(table_key or (raw or {}).get("tableKey") or DEFAULT_ZONE_TABLE).strip()[:120]
913
+ if not table_key:
914
+ return None
915
  wanted = str((raw or {}).get("id") or "").strip()
916
 
917
  def mutate(state):
918
  zones = list(state.get("zones") or [])
919
  prior_index = next((index for index, item in enumerate(zones)
920
+ if isinstance(item, dict) and item.get("id") == wanted
921
+ and _zone_table_key(item) == table_key), None)
922
  prior = zones[prior_index] if prior_index is not None else None
923
+ clean = _zone({**raw, "tableKey": table_key},
924
+ ordinal=prior_index if prior_index is not None else len(zones),
925
  created_by=created_by, tenant_id=tenant_id, prior=prior)
926
  if clean is None:
927
  return state, None
 
939
  return _persist(st, mutate)
940
 
941
 
942
+ def delete_zone(st, zone_id, *, table_key=DEFAULT_ZONE_TABLE):
943
  zone_id = str(zone_id or "").strip()
944
+ table_key = str(table_key or DEFAULT_ZONE_TABLE).strip()
945
 
946
  def mutate(state):
947
  prior = list(state.get("zones") or [])
948
+ state["zones"] = [item for item in prior if not (
949
+ isinstance(item, dict) and item.get("id") == zone_id
950
+ and _zone_table_key(item) == table_key)]
951
  return state, len(prior) != len(state["zones"])
952
 
953
  return bool(_persist(st, mutate))
954
 
955
 
956
+ def delete_zones_for_table(st, table_key):
957
+ """Remove the Zone family attached to a database that is itself being deleted."""
958
+ table_key = str(table_key or "").strip()
959
+ if not table_key:
960
+ return 0
961
+
962
+ def mutate(state):
963
+ prior = list(state.get("zones") or [])
964
+ state["zones"] = [item for item in prior if not (
965
+ isinstance(item, dict) and _zone_table_key(item) == table_key)]
966
+ return state, len(prior) - len(state["zones"])
967
+
968
+ return int(_persist(st, mutate) or 0)
969
+
970
+
971
  def customer_projections(routes, zones):
972
  """Derived read-only customer multi-select values; stops are never generic Link cells."""
973
  projections = {}
platform/core/script_sandbox.py CHANGED
@@ -1,519 +1,519 @@
1
- """core/script_sandbox.py β€” WAVE 36 (R5 / R10, contract C1): running a tenant's OWN Python.
2
-
3
- Owner item 6: *"Add code script as an interface (database View) so a user can build whatever they
4
- want through the Agent chat interface."* Item 8: *"We need to really guardrail the reach of this
5
- script. So let's really grill this down."* R10 ruled it SERVER-SIDE PYTHON after the trade was
6
- stated, so this file is the guardrail, and one engine serves both items.
7
-
8
- ════════════════════════════════════════════════════════════════════════════════════════════════
9
- β›”β›” THE ONE PARAGRAPH TO READ BEFORE CHANGING ANYTHING HERE.
10
-
11
- In-process CPython cannot deliver two of this ticket's clauses. An AST allow-list plus a curated
12
- namespace stops import, file, network and environment access β€” but it **cannot cap memory and
13
- cannot interrupt a runaway loop**, because a `while True:` in the same interpreter is not a slow
14
- request, it is the tenant's ONE FastAPI process gone. So the script runs in a **SUBPROCESS**:
15
- `resource.setrlimit` for address space and CPU, a hard wall-clock kill from the parent, and the
16
- allow-list inside. Neither half is sufficient; both are load-bearing.
17
-
18
- ⭐ AND THE SUBPROCESS RECEIVES **ROWS, NEVER A STORE**. The parent calls C1's `scoped_table` under
19
- the CALLING user's record and serialises the result; the child imports nothing from this repo and
20
- holds no credential, no runtime and no store handle. Wiring W1 ("the sandbox has no second store
21
- path") is then true by CONSTRUCTION rather than by discipline, and it is checkable: the child
22
- reports its own `sys.modules`, and no `core.*` name may appear in it.
23
-
24
- β›” NEVER A BLACKLIST. Every rule below is an ALLOW-LIST β€” a set of node types, a set of attribute
25
- names, a dict of builtins. A blacklist of dangerous spellings is bypassable by construction, and
26
- the bypass is usually one string method away (`"{0.__class__}".format(x)` performs its attribute
27
- lookup inside `format`, so there is no `ast.Attribute` node to refuse).
28
- ════════════════════════════════════════════════════════════════════════════════════════════════
29
-
30
- The two layers, and they refuse DIFFERENT things on purpose:
31
-
32
- 1. `check_source()` β€” a pure function over source text. Refuses a construct the language offers
33
- and this sandbox does not: `import`, `class`, `with`, `async`, `yield`, `global`, and every
34
- attribute name outside `ALLOWED_ATTRS`.
35
- 2. `SANDBOX_BUILTINS` β€” the names that resolve at all. `__import__`, `open`, `eval`, `exec`,
36
- `compile`, `getattr`, `globals`, `vars` and `type` are simply absent, so a source that gets
37
- past layer 1 still finds nothing to call.
38
-
39
- ⚠ THAT DUPLICATION IS DELIBERATE AND IT CHANGES HOW THE GATE MUST BE WRITTEN. `import os` is
40
- refused twice, so a negative control that drops ONE layer sees the other refuse and reports
41
- green β€” the shape that already cost this wave one missed control in `routes_agent_harness`. So
42
- each layer is tested AT ITS OWN BOUNDARY: `check_source()` is called directly on source strings,
43
- and `run()` is driven end to end. An NC drops one entry from one frozenset and the matching
44
- boundary goes red.
45
- """
46
- import ast
47
- import json
48
- import os
49
- import subprocess
50
- import sys
51
- import tempfile
52
- import time
53
- from pathlib import Path
54
-
55
- #: Wall clock, enforced by the PARENT with a kill. The one cap that works on every platform.
56
- DEFAULT_TIMEOUT_S = 10.0
57
-
58
- #: Address space for the child (`RLIMIT_AS`). POSIX only β€” see `run()`'s `caps` report.
59
- DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024
60
-
61
- #: CPU seconds for the child (`RLIMIT_CPU`). POSIX only. Deliberately above the wall clock: the
62
- #: wall-clock kill is the primary control and this is the backstop for a child that stops being
63
- #: reachable. A CPU limit BELOW the timeout would make every slow script look like a CPU refusal.
64
- DEFAULT_CPU_SECONDS = 15
65
-
66
- #: What the script may print, in bytes. `print` is a curated builtin writing to a capped buffer,
67
- #: and the child's real stdout goes to DEVNULL β€” so a script cannot fill a pipe, and anything
68
- #: that escaped far enough to write to fd 1 has nowhere for it to land.
69
- MAX_STDOUT_BYTES = 64 * 1024
70
-
71
- #: The serialised ROW payload handed to the child. β›” A REFUSAL, NEVER A TRUNCATION (standing rule
72
- #: 1): a short answer from a data tool is a wrong answer that looks right. Over this, `run()`
73
- #: returns a named limit carrying its cause and a recommendation.
74
- MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
75
-
76
- #: The emitted spec. A render spec is a description of a picture; one larger than this is data
77
- #: pretending to be a description.
78
- MAX_SPEC_BYTES = 2 * 1024 * 1024
79
-
80
- MAX_SOURCE_BYTES = 128 * 1024
81
-
82
-
83
- # ══════════════════════════════════════════════════════ LAYER 1 β€” the AST allow-list ═══════════
84
- #: Every `ast` node class a script may contain. β›” THE ABSENCES ARE THE POLICY: `Import` /
85
- #: `ImportFrom` (no module reaches the script), `ClassDef` (a class body is a namespace with its
86
- #: own scoping rules and buys a data script nothing), `With` (a context manager is `__enter__`
87
- #: by another spelling), `Global` / `Nonlocal` (rebinding the sandbox's own names), and every
88
- #: `Async*` / `Await` / `Yield` form (this engine is synchronous; a coroutine that is never
89
- #: awaited is a silent no-op that looks like a working script).
90
- ALLOWED_NODES = frozenset("""
91
- Module Expr Assign AugAssign AnnAssign NamedExpr Return Pass Break Continue Delete Assert Raise
92
- If For While Try TryStar ExceptHandler FunctionDef Lambda arguments arg keyword
93
- BoolOp BinOp UnaryOp IfExp Dict Set List Tuple Starred Subscript Slice Compare Call Attribute Name
94
- Constant JoinedStr FormattedValue ListComp SetComp DictComp GeneratorExp comprehension
95
- Load Store Del
96
- And Or Not Invert UAdd USub
97
- Add Sub Mult Div FloorDiv Mod Pow LShift RShift BitOr BitXor BitAnd MatMult
98
- Eq NotEq Lt LtE Gt GtE Is IsNot In NotIn
99
- """.split())
100
-
101
- #: Every attribute name a script may READ or CALL. β›”β›” THIS IS THE LOAD-BEARING SET, and it is
102
- #: an allow-list of NAMES rather than a refusal of dunders, because the interesting escapes are
103
- #: ordinary-looking: `f.__globals__` on any function reaches the runner's own module namespace,
104
- #: `e.__traceback__.tb_frame.f_globals` reaches it from an exception handler, and `().__class__`
105
- #: reaches `object.__subclasses__`. None of those names is here, and neither is any name this
106
- #: sandbox has not been asked for.
107
- #: ⚠ `format` IS ABSENT DELIBERATELY. `"{0.__class__}".format(x)` performs the attribute lookup
108
- #: INSIDE `str.format`, where no `ast.Attribute` node exists for layer 1 to see. f-strings are
109
- #: fine β€” `f"{x.__class__}"` compiles to a real `Attribute` node and is refused.
110
- ALLOWED_ATTRS = frozenset("""
111
- append extend insert pop remove clear sort reverse copy count index
112
- keys values items get setdefault update
113
- add discard union intersection difference issubset issuperset
114
- join split rsplit splitlines strip lstrip rstrip lower upper title capitalize casefold
115
- replace startswith endswith find rfind zfill ljust rjust center partition removeprefix removesuffix
116
- isdigit isalpha isalnum isspace isupper islower isnumeric
117
- real imag numerator denominator
118
- """.split())
119
-
120
-
121
- class Refused(Exception):
122
- """A named refusal: `code` for a caller to branch on, `message` for a person to read."""
123
-
124
- def __init__(self, code, message):
125
- self.code, self.message = code, message
126
- super().__init__(f"{code}: {message}")
127
-
128
-
129
- def _attr_ok(name):
130
- """An attribute name passes only if it is on the list AND is not private.
131
-
132
- ⚠ THE SECOND TEST IS NOT A BLACKLIST β€” it narrows an allow-list that already excludes every
133
- private name. It is here so that adding a name to `ALLOWED_ATTRS` cannot open a dunder by
134
- accident, which is the one edit a future reader is most likely to make in a hurry.
135
- """
136
- return name in ALLOWED_ATTRS and not name.startswith("_")
137
-
138
-
139
- def check_source(source):
140
- """LAYER 1. Return a `Refused` for source this sandbox will not run, or `None`.
141
-
142
- ⭐ PURE, AND THAT IS WHAT MAKES IT TESTABLE AT ITS OWN BOUNDARY. It reads no file, spawns no
143
- process and touches no store, so a gate can hand it a hundred hostile strings for free and an
144
- NC can drop one entry from one frozenset and watch exactly this function change its answer.
145
- """
146
- text = str(source or "")
147
- if len(text.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
148
- return Refused("source_too_long",
149
- f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of source")
150
- try:
151
- tree = ast.parse(text)
152
- except SyntaxError as exc:
153
- return Refused("syntax", f"line {exc.lineno or 0}: {exc.msg}")
154
-
155
- for node in ast.walk(tree):
156
- kind = type(node).__name__
157
- if kind not in ALLOWED_NODES:
158
- return Refused("refused_construct",
159
- f"line {getattr(node, 'lineno', 0)}: this sandbox does not run "
160
- f"{_english(kind)}")
161
- if isinstance(node, ast.Attribute) and not _attr_ok(node.attr):
162
- return Refused("refused_attribute",
163
- f"line {getattr(node, 'lineno', 0)}: the attribute "
164
- f"'{node.attr}' is not available inside a script view")
165
- # β›” A NAME may not be private either. `_` prefixed names are the runner's own, and a
166
- # script that could bind one could shadow the machinery it runs on top of.
167
- if isinstance(node, ast.Name) and node.id.startswith("_"):
168
- return Refused("reserved_name",
169
- f"line {getattr(node, 'lineno', 0)}: names starting with an "
170
- f"underscore are reserved by the sandbox")
171
- if isinstance(node, (ast.FunctionDef, ast.arg, ast.ExceptHandler)) and str(
172
- getattr(node, "name", None) or getattr(node, "arg", "") or "").startswith("_"):
173
- return Refused("reserved_name",
174
- f"line {getattr(node, 'lineno', 0)}: names starting with an "
175
- f"underscore are reserved by the sandbox")
176
- if isinstance(node, ast.keyword) and str(node.arg or "").startswith("_"):
177
- return Refused("reserved_name",
178
- f"line {getattr(node, 'lineno', 0)}: keyword arguments starting with "
179
- f"an underscore are reserved by the sandbox")
180
- return None
181
-
182
-
183
- _ENGLISH = {
184
- "Import": "an import", "ImportFrom": "an import", "ClassDef": "a class definition",
185
- "With": "a with block", "AsyncWith": "a with block", "AsyncFor": "an async loop",
186
- "AsyncFunctionDef": "an async function", "Await": "await", "Yield": "yield",
187
- "YieldFrom": "yield from", "Global": "a global statement", "Nonlocal": "a nonlocal statement",
188
- "Match": "a match statement",
189
- }
190
-
191
-
192
- def _english(kind):
193
- return _ENGLISH.get(kind, f"a {kind} expression")
194
-
195
-
196
- # ══════════════════════════════════════════ LAYER 2 β€” the namespace, and the child program ═════
197
- #: The builtins a script may reach, BY NAME. Everything else is a `NameError` in the child.
198
- #: β›” THE ABSENCES, again, are the policy: `__import__` `open` `eval` `exec` `compile` `input`
199
- #: `getattr` `setattr` `delattr` `globals` `locals` `vars` `dir` `type` `super` `object` `help`
200
- #: `exit` `breakpoint` `memoryview` `id`. Several are harmless on their own; each one is a step
201
- #: on a published escape, and none has ever been asked for by a script that shapes rows.
202
- #: ⚠ THE EXCEPTION CLASSES ARE HERE BECAUSE `try:` IS, and a `try` block whose `except` clause
203
- #: cannot name what it catches is a construct that reads as supported and is not. They are safe
204
- #: for the same reason everything else is: `Exception.__subclasses__` needs an attribute this
205
- #: sandbox does not allow, so a class object in the namespace is a leaf, not a doorway.
206
- SANDBOX_BUILTIN_NAMES = (
207
- "abs all any bool bytes callable chr dict divmod enumerate filter float frozenset hash hex "
208
- "int isinstance issubclass iter len list map max min next oct ord pow range repr reversed "
209
- "round set slice sorted str sum tuple zip True False None "
210
- "Exception ValueError TypeError KeyError IndexError ZeroDivisionError ArithmeticError "
211
- "AttributeError StopIteration OverflowError"
212
- ).split()
213
-
214
- #: The literal program the child runs. It is TEXT rather than a module because the child must
215
- #: import nothing from this repo: a module would be found on `sys.path` and would drag `core`
216
- #: with it, which is exactly the second store path W1 forbids.
217
- #: ⚠ Every name in here is underscore-prefixed and layer 1 refuses a script from binding one, so
218
- #: the runner's own machinery cannot be shadowed by the source it executes.
219
- _RUNNER = r'''
220
- import json as _json, os as _os, sys as _sys
221
-
222
- _pay = _json.loads(open(_sys.argv[1], "r", encoding="utf-8").read())
223
- _out = {"ok": False, "code": "not_run", "message": "the script did not run",
224
- "stdout": "", "spec": None, "caps": {"wallClock": True, "memory": False, "cpu": False}}
225
-
226
- # ── the caps this platform can actually apply, reported either way (standing rule 1) ──────────
227
- try:
228
- import resource as _res
229
- _mem = int(_pay["memoryBytes"])
230
- _res.setrlimit(_res.RLIMIT_AS, (_mem, _mem))
231
- _out["caps"]["memory"] = True
232
- _cpu = int(_pay["cpuSeconds"])
233
- _res.setrlimit(_res.RLIMIT_CPU, (_cpu, _cpu))
234
- _out["caps"]["cpu"] = True
235
- except Exception:
236
- # `resource` is POSIX only. The wall-clock kill in the parent still applies, and `caps` says
237
- # which of the three held, never a silent partial.
238
- pass
239
-
240
- _printed = []
241
- _spent = [0]
242
- _LIMIT = int(_pay["maxStdout"])
243
-
244
-
245
- def _print(*_a, **_k):
246
- _text = (_k.get("sep") or " ").join(str(_x) for _x in _a) + (_k.get("end") or "\n")
247
- _room = _LIMIT - _spent[0]
248
- if _room > 0:
249
- _printed.append(_text[:_room])
250
- _spent[0] += len(_text)
251
-
252
-
253
- class _Refusal(Exception):
254
- """The SANDBOX refusing, as distinct from the SCRIPT failing.
255
-
256
- Without its own class these arrive as `ValueError`, indistinguishable from a `ValueError` the
257
- script raised itself, and the answer then says "refused" about an ordinary bug in the tenant's
258
- own code. Two different facts, two different codes.
259
- """
260
-
261
-
262
- _emitted = []
263
-
264
-
265
- def _emit(_spec):
266
- if not isinstance(_spec, dict):
267
- raise _Refusal("emit() takes a view spec, which is a dictionary")
268
- if _emitted:
269
- raise _Refusal("emit() was already called; a script view emits exactly one view")
270
- _emitted.append(_spec)
271
-
272
-
273
- _rows = _pay["rows"]
274
- _fields = _pay["fields"]
275
- _bound = _pay["table"]
276
-
277
-
278
- def _scoped_table(_table=None):
279
- if _table is not None and str(_table) != _bound:
280
- raise _Refusal(
281
- "this script view is bound to the database '" + _bound + "' and asked for '"
282
- + str(_table) + "'. A script view reads its own database only")
283
- return [dict(_r) for _r in _rows]
284
-
285
-
286
- def _scoped_fields():
287
- return [dict(_f) for _f in _fields]
288
-
289
-
290
- _ns = {"__builtins__": {_n: __builtins__[_n] if isinstance(__builtins__, dict)
291
- else getattr(__builtins__, _n)
292
- for _n in _pay["builtins"]}}
293
- _ns["__builtins__"]["print"] = _print
294
- _ns["print"] = _print
295
- _ns["emit"] = _emit
296
- _ns["scoped_table"] = _scoped_table
297
- _ns["scoped_fields"] = _scoped_fields
298
- _ns["table"] = _bound
299
-
300
- try:
301
- exec(compile(_pay["source"], "<script view>", "exec"), _ns)
302
- if not _emitted:
303
- _out.update(ok=False, code="no_view",
304
- message="the script finished without calling emit(spec)")
305
- else:
306
- _out.update(ok=True, code="", message="", spec=_emitted[0])
307
- except _Refusal as _e:
308
- _out.update(ok=False, code="refused", message=str(_e)[:400])
309
- except MemoryError:
310
- _out.update(ok=False, code="memory",
311
- message="the script used more memory than a script view is allowed")
312
- except NameError as _e:
313
- _out.update(ok=False, code="refused_name",
314
- message=str(_e)[:200] + ". A script view may use only the names the sandbox "
315
- "provides")
316
- except BaseException as _e:
317
- _out.update(ok=False, code="error",
318
- message=type(_e).__name__ + ": " + str(_e)[:400])
319
-
320
- _out["stdout"] = "".join(_printed)
321
- _out["truncated"] = _spent[0] > _LIMIT
322
- # ⭐ THE PROBE: what this child actually had. The PARENT strips it unless it was asked for, so a
323
- # production run never carries it and a gate can still prove that no `core.*` module and no
324
- # secret-shaped environment key was ever inside this process.
325
- # ⚠ SNAPSHOTTED AFTER `exec`, and `os` is imported at the TOP so this list does not depend on
326
- # dict-literal evaluation order. The first draft called `__import__("os")` inside this very
327
- # expression, so whether `os` appeared depended on which value Python built first: a probe whose
328
- # contents move with an unrelated edit is a probe a gate cannot assert against.
329
- _out["probe"] = {"modules": sorted(_sys.modules), "env": sorted(_os.environ)}
330
- open(_sys.argv[2], "w", encoding="utf-8").write(_json.dumps(_out, default=str))
331
- '''
332
-
333
-
334
- def _child_env():
335
- """The child's WHOLE environment. An allow-list of two keys, and neither is a credential.
336
-
337
- β›” NOT `os.environ.copy()` MINUS SOMETHING. A subtractive environment ships every key nobody
338
- thought to name: `HF_TOKEN`, `ODOO_PASSWORD`, `ANTHROPIC_API_KEY` and whatever the next
339
- connector adds. The three names below are here because Python will not start on Windows
340
- without them; on Linux this returns `{}` and the child runs with no environment at all.
341
- """
342
- env = {}
343
- for name in ("SystemRoot", "SYSTEMROOT", "WINDIR"):
344
- if os.environ.get(name):
345
- env[name] = os.environ[name]
346
- return env
347
-
348
-
349
- def run(source, rows, fields, table_key, *, timeout_s=DEFAULT_TIMEOUT_S,
350
- memory_bytes=DEFAULT_MEMORY_BYTES, cpu_seconds=DEFAULT_CPU_SECONDS, probe=False):
351
- """Run ONE script over rows that are ALREADY scoped. Returns C3's envelope plus `caps`.
352
-
353
- {ok, code, message, spec, stdout, truncated, ms, caps: {wallClock, memory, cpu}}
354
-
355
- β›” THIS FUNCTION NEVER TOUCHES A STORE, AND THAT IS THE POINT: it takes rows. `run_view()`
356
- below is the door that fetches them through C1; keeping the two apart is what lets a gate
357
- drive the sandbox with no tenant, no runtime and no credential anywhere in the process.
358
-
359
- ⚠ `caps` IS PART OF THE ANSWER, NOT DEBUG OUTPUT. On Windows `resource` does not exist, so
360
- the memory and CPU limits are NOT applied and this says so. A caller that reports `ok:true`
361
- without reading `caps` is claiming an enforcement that did not happen (standing rule 1).
362
- """
363
- started = time.monotonic()
364
- refusal = check_source(source)
365
- if refusal is not None:
366
- return _refusal(refusal.code, refusal.message, started)
367
-
368
- payload = {"source": str(source or ""), "rows": rows, "fields": fields,
369
- "table": str(table_key or ""), "builtins": SANDBOX_BUILTIN_NAMES,
370
- "maxStdout": MAX_STDOUT_BYTES, "memoryBytes": int(memory_bytes),
371
- "cpuSeconds": int(cpu_seconds)}
372
- try:
373
- blob = json.dumps(payload, default=str)
374
- except (TypeError, ValueError) as exc:
375
- return _refusal("bad_rows", f"these rows cannot be handed to a script ({exc})", started)
376
- if len(blob.encode("utf-8", "replace")) > MAX_PAYLOAD_BYTES:
377
- # β›” REPORTED, NOT TRUNCATED (standing rule 1's second sentence): cause and recommendation,
378
- # in the words the owner asked for, rather than a quietly short answer.
379
- return _refusal(
380
- "payload_too_large",
381
- f"this database's rows are larger than the {MAX_PAYLOAD_BYTES // (1024 * 1024)} MB a "
382
- f"script view can be handed at once. Narrow the view with a filter, or raise the "
383
- f"sandbox payload limit for this deployment", started)
384
-
385
- with tempfile.TemporaryDirectory(prefix="aios-script-") as work:
386
- pay_path = Path(work) / "payload.json"
387
- res_path = Path(work) / "result.json"
388
- pay_path.write_text(blob, encoding="utf-8")
389
- # `-I` isolates the interpreter (no PYTHON* env, no user site), `-S` skips site-packages,
390
- # and the program arrives on STDIN so there is no file for anything to import it as.
391
- # β›” `-X utf8` AND AN EXPLICIT `encoding` ARE NOT TIDINESS. Without them this pipe is
392
- # encoded with the parent's locale codec, which on this Windows box is cp1252: the runner
393
- # text below cannot be represented in it and `subprocess.run` died with
394
- # `UnicodeEncodeError` before the child ever started. A sandbox whose behaviour depends on
395
- # the operator's locale is a sandbox with two behaviours. `-I` implies `-E`, so
396
- # `PYTHONUTF8` in the environment could not have carried this, it has to be a flag.
397
- argv = [sys.executable, "-I", "-S", "-X", "utf8", "-", str(pay_path), str(res_path)]
398
- try:
399
- done = subprocess.run(
400
- argv, input=_RUNNER, text=True, encoding="utf-8", errors="replace",
401
- cwd=work, env=_child_env(),
402
- stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout_s)
403
- except subprocess.TimeoutExpired:
404
- return _refusal("timeout",
405
- f"the script ran longer than {timeout_s:g} seconds and was stopped",
406
- started)
407
- except OSError as exc:
408
- return _refusal("no_sandbox",
409
- f"a script view could not be started on this deployment ({exc})",
410
- started)
411
-
412
- if not res_path.is_file():
413
- # The child died without writing an answer: an rlimit signal, an OOM kill, or a crash.
414
- # ⚠ NAMED BY ITS RETURN CODE rather than reported as a generic failure β€” a memory kill
415
- # and a bug in this file must not read identically to an operator.
416
- return _refusal(*_died(done), started)
417
- try:
418
- out = json.loads(res_path.read_text(encoding="utf-8"))
419
- except (OSError, ValueError) as exc:
420
- return _refusal("unreadable", f"the script's answer could not be read ({exc})",
421
- started)
422
-
423
- out["ms"] = int((time.monotonic() - started) * 1000)
424
- if out.get("ok"):
425
- spec_error = _check_spec(out.get("spec"))
426
- if spec_error:
427
- out.update(ok=False, code="bad_spec", message=spec_error, spec=None)
428
- if not probe:
429
- out.pop("probe", None)
430
- return out
431
-
432
-
433
- def _died(done):
434
- """`(code, message)` for a child that produced no answer."""
435
- rc = done.returncode
436
- tail = " ".join((done.stderr or "").split())[-300:]
437
- if rc in (-9, 137):
438
- return "memory", "the script was stopped for using too much memory"
439
- if rc in (-24, 152):
440
- return "timeout", "the script used more processor time than a script view is allowed"
441
- return "crashed", f"the script view engine stopped without an answer{': ' + tail if tail else ''}"
442
-
443
-
444
- def _refusal(code, message, started):
445
- return {"ok": False, "code": code, "message": message, "spec": None, "stdout": "",
446
- "truncated": False, "ms": int((time.monotonic() - started) * 1000),
447
- "caps": {"wallClock": True, "memory": False, "cpu": False}}
448
-
449
-
450
- def _check_spec(spec):
451
- """C3: a spec is a DESCRIPTION the client draws. Never HTML, never a script, never a URL.
452
-
453
- β›” THE CHECK IS ON THE KEYS, NOT ON THE STRING CONTENTS. Scanning values for `<script>` is a
454
- blacklist and would pass `<SCR` + `IPT>`; refusing a spec that carries an `html`, `script`,
455
- `src` or `onclick` key refuses the SHAPE that would let a renderer be talked into executing
456
- something. The vocabulary of legal `kind`s is the ROUTE's business (W36-T37) β€” this is the
457
- floor every caller gets whether or not the route above it remembers.
458
- """
459
- if not isinstance(spec, dict):
460
- return "the script emitted something that is not a view spec"
461
- try:
462
- blob = json.dumps(spec)
463
- except (TypeError, ValueError):
464
- return "the emitted view spec is not something the client can be sent"
465
- if len(blob.encode("utf-8", "replace")) > MAX_SPEC_BYTES:
466
- return (f"the emitted view spec is over {MAX_SPEC_BYTES // (1024 * 1024)} MB. A view spec "
467
- f"describes a picture; it is not where the rows go")
468
- banned = {"html", "innerhtml", "script", "src", "srcdoc", "href", "style", "onclick", "onload"}
469
- found = sorted(k for k in _keys_of(spec) if str(k).lower() in banned)
470
- if found:
471
- return (f"a view spec may not carry {', '.join(found)}. The client DRAWS a spec, so a "
472
- f"markup or URL key would be a script by another name")
473
- return None
474
-
475
-
476
- def _keys_of(value, depth=0):
477
- """Every key anywhere in a nested spec. Bounded, so a deep structure cannot spin this."""
478
- if depth > 12:
479
- return
480
- if isinstance(value, dict):
481
- for key, sub in value.items():
482
- yield key
483
- yield from _keys_of(sub, depth + 1)
484
- elif isinstance(value, (list, tuple)):
485
- for sub in value:
486
- yield from _keys_of(sub, depth + 1)
487
-
488
-
489
- # ══════════════════════════════════════════════ THE DOOR β€” C1 is the ONLY way to a row ═════════
490
- def run_view(user, table_key, source, st=None, **kw):
491
- """Fetch through C1 under `user`'s scope, then run the script over what came back (R5).
492
-
493
- ⭐⭐ THE FETCH HAPPENS IN THE PARENT AND ONLY ROWS CROSS INTO THE CHILD. That is wiring W1
494
- made structural: the child has no runtime to ask, no store handle to open and no credential
495
- to use, so "a script cannot read what its caller cannot read" is not a rule anybody has to
496
- keep β€” there is no second path for it to be broken through.
497
-
498
- β›” C1'S THREE EXCEPTIONS ARE ANSWERED, NEVER SWALLOWED. `UnknownTable`, `Denied` and
499
- `Unresolvable` mean three different things to a person; collapsing them into "no rows" is the
500
- silent-empty answer C1 was written to make impossible. `Unresolvable.as_limit()` is handed
501
- through in the words it was raised with β€” standing rule 1's second sentence, verbatim.
502
- """
503
- import core.perm_scope as perm_scope
504
-
505
- key = str(table_key or "")
506
- try:
507
- rows = perm_scope.scoped_table(user, key, st=st)
508
- fields = perm_scope.scoped_fields(user, key, st=st)
509
- except perm_scope.UnknownTable as exc:
510
- return _refusal("unknown_table", str(exc) or f"there is no database '{key}'",
511
- time.monotonic())
512
- except perm_scope.Denied as exc:
513
- return _refusal("denied", str(exc) or "this account may not read that database",
514
- time.monotonic())
515
- except perm_scope.Unresolvable as exc:
516
- out = _refusal("unresolvable", str(exc), time.monotonic())
517
- out["limit"] = exc.as_limit()
518
- return out
519
- return run(source, rows, fields, key, **kw)
 
1
+ """core/script_sandbox.py β€” WAVE 36 (R5 / R10, contract C1): running a tenant's OWN Python.
2
+
3
+ Owner item 6: *"Add code script as an interface (database View) so a user can build whatever they
4
+ want through the Agent chat interface."* Item 8: *"We need to really guardrail the reach of this
5
+ script. So let's really grill this down."* R10 ruled it SERVER-SIDE PYTHON after the trade was
6
+ stated, so this file is the guardrail, and one engine serves both items.
7
+
8
+ ════════════════════════════════════════════════════════════════════════════════════════════════
9
+ β›”β›” THE ONE PARAGRAPH TO READ BEFORE CHANGING ANYTHING HERE.
10
+
11
+ In-process CPython cannot deliver two of this ticket's clauses. An AST allow-list plus a curated
12
+ namespace stops import, file, network and environment access β€” but it **cannot cap memory and
13
+ cannot interrupt a runaway loop**, because a `while True:` in the same interpreter is not a slow
14
+ request, it is the tenant's ONE FastAPI process gone. So the script runs in a **SUBPROCESS**:
15
+ `resource.setrlimit` for address space and CPU, a hard wall-clock kill from the parent, and the
16
+ allow-list inside. Neither half is sufficient; both are load-bearing.
17
+
18
+ ⭐ AND THE SUBPROCESS RECEIVES **ROWS, NEVER A STORE**. The parent calls C1's `scoped_table` under
19
+ the CALLING user's record and serialises the result; the child imports nothing from this repo and
20
+ holds no credential, no runtime and no store handle. Wiring W1 ("the sandbox has no second store
21
+ path") is then true by CONSTRUCTION rather than by discipline, and it is checkable: the child
22
+ reports its own `sys.modules`, and no `core.*` name may appear in it.
23
+
24
+ β›” NEVER A BLACKLIST. Every rule below is an ALLOW-LIST β€” a set of node types, a set of attribute
25
+ names, a dict of builtins. A blacklist of dangerous spellings is bypassable by construction, and
26
+ the bypass is usually one string method away (`"{0.__class__}".format(x)` performs its attribute
27
+ lookup inside `format`, so there is no `ast.Attribute` node to refuse).
28
+ ════════════════════════════════════════════════════════════════════════════════════════════════
29
+
30
+ The two layers, and they refuse DIFFERENT things on purpose:
31
+
32
+ 1. `check_source()` β€” a pure function over source text. Refuses a construct the language offers
33
+ and this sandbox does not: `import`, `class`, `with`, `async`, `yield`, `global`, and every
34
+ attribute name outside `ALLOWED_ATTRS`.
35
+ 2. `SANDBOX_BUILTINS` β€” the names that resolve at all. `__import__`, `open`, `eval`, `exec`,
36
+ `compile`, `getattr`, `globals`, `vars` and `type` are simply absent, so a source that gets
37
+ past layer 1 still finds nothing to call.
38
+
39
+ ⚠ THAT DUPLICATION IS DELIBERATE AND IT CHANGES HOW THE GATE MUST BE WRITTEN. `import os` is
40
+ refused twice, so a negative control that drops ONE layer sees the other refuse and reports
41
+ green β€” the shape that already cost this wave one missed control in `routes_agent_harness`. So
42
+ each layer is tested AT ITS OWN BOUNDARY: `check_source()` is called directly on source strings,
43
+ and `run()` is driven end to end. An NC drops one entry from one frozenset and the matching
44
+ boundary goes red.
45
+ """
46
+ import ast
47
+ import json
48
+ import os
49
+ import subprocess
50
+ import sys
51
+ import tempfile
52
+ import time
53
+ from pathlib import Path
54
+
55
+ #: Wall clock, enforced by the PARENT with a kill. The one cap that works on every platform.
56
+ DEFAULT_TIMEOUT_S = 10.0
57
+
58
+ #: Address space for the child (`RLIMIT_AS`). POSIX only β€” see `run()`'s `caps` report.
59
+ DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024
60
+
61
+ #: CPU seconds for the child (`RLIMIT_CPU`). POSIX only. Deliberately above the wall clock: the
62
+ #: wall-clock kill is the primary control and this is the backstop for a child that stops being
63
+ #: reachable. A CPU limit BELOW the timeout would make every slow script look like a CPU refusal.
64
+ DEFAULT_CPU_SECONDS = 15
65
+
66
+ #: What the script may print, in bytes. `print` is a curated builtin writing to a capped buffer,
67
+ #: and the child's real stdout goes to DEVNULL β€” so a script cannot fill a pipe, and anything
68
+ #: that escaped far enough to write to fd 1 has nowhere for it to land.
69
+ MAX_STDOUT_BYTES = 64 * 1024
70
+
71
+ #: The serialised ROW payload handed to the child. β›” A REFUSAL, NEVER A TRUNCATION (standing rule
72
+ #: 1): a short answer from a data tool is a wrong answer that looks right. Over this, `run()`
73
+ #: returns a named limit carrying its cause and a recommendation.
74
+ MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
75
+
76
+ #: The emitted spec. A render spec is a description of a picture; one larger than this is data
77
+ #: pretending to be a description.
78
+ MAX_SPEC_BYTES = 2 * 1024 * 1024
79
+
80
+ MAX_SOURCE_BYTES = 128 * 1024
81
+
82
+
83
+ # ══════════════════════════════════════════════════════ LAYER 1 β€” the AST allow-list ═══════════
84
+ #: Every `ast` node class a script may contain. β›” THE ABSENCES ARE THE POLICY: `Import` /
85
+ #: `ImportFrom` (no module reaches the script), `ClassDef` (a class body is a namespace with its
86
+ #: own scoping rules and buys a data script nothing), `With` (a context manager is `__enter__`
87
+ #: by another spelling), `Global` / `Nonlocal` (rebinding the sandbox's own names), and every
88
+ #: `Async*` / `Await` / `Yield` form (this engine is synchronous; a coroutine that is never
89
+ #: awaited is a silent no-op that looks like a working script).
90
+ ALLOWED_NODES = frozenset("""
91
+ Module Expr Assign AugAssign AnnAssign NamedExpr Return Pass Break Continue Delete Assert Raise
92
+ If For While Try TryStar ExceptHandler FunctionDef Lambda arguments arg keyword
93
+ BoolOp BinOp UnaryOp IfExp Dict Set List Tuple Starred Subscript Slice Compare Call Attribute Name
94
+ Constant JoinedStr FormattedValue ListComp SetComp DictComp GeneratorExp comprehension
95
+ Load Store Del
96
+ And Or Not Invert UAdd USub
97
+ Add Sub Mult Div FloorDiv Mod Pow LShift RShift BitOr BitXor BitAnd MatMult
98
+ Eq NotEq Lt LtE Gt GtE Is IsNot In NotIn
99
+ """.split())
100
+
101
+ #: Every attribute name a script may READ or CALL. β›”β›” THIS IS THE LOAD-BEARING SET, and it is
102
+ #: an allow-list of NAMES rather than a refusal of dunders, because the interesting escapes are
103
+ #: ordinary-looking: `f.__globals__` on any function reaches the runner's own module namespace,
104
+ #: `e.__traceback__.tb_frame.f_globals` reaches it from an exception handler, and `().__class__`
105
+ #: reaches `object.__subclasses__`. None of those names is here, and neither is any name this
106
+ #: sandbox has not been asked for.
107
+ #: ⚠ `format` IS ABSENT DELIBERATELY. `"{0.__class__}".format(x)` performs the attribute lookup
108
+ #: INSIDE `str.format`, where no `ast.Attribute` node exists for layer 1 to see. f-strings are
109
+ #: fine β€” `f"{x.__class__}"` compiles to a real `Attribute` node and is refused.
110
+ ALLOWED_ATTRS = frozenset("""
111
+ append extend insert pop remove clear sort reverse copy count index
112
+ keys values items get setdefault update
113
+ add discard union intersection difference issubset issuperset
114
+ join split rsplit splitlines strip lstrip rstrip lower upper title capitalize casefold
115
+ replace startswith endswith find rfind zfill ljust rjust center partition removeprefix removesuffix
116
+ isdigit isalpha isalnum isspace isupper islower isnumeric
117
+ real imag numerator denominator
118
+ """.split())
119
+
120
+
121
+ class Refused(Exception):
122
+ """A named refusal: `code` for a caller to branch on, `message` for a person to read."""
123
+
124
+ def __init__(self, code, message):
125
+ self.code, self.message = code, message
126
+ super().__init__(f"{code}: {message}")
127
+
128
+
129
+ def _attr_ok(name):
130
+ """An attribute name passes only if it is on the list AND is not private.
131
+
132
+ ⚠ THE SECOND TEST IS NOT A BLACKLIST β€” it narrows an allow-list that already excludes every
133
+ private name. It is here so that adding a name to `ALLOWED_ATTRS` cannot open a dunder by
134
+ accident, which is the one edit a future reader is most likely to make in a hurry.
135
+ """
136
+ return name in ALLOWED_ATTRS and not name.startswith("_")
137
+
138
+
139
+ def check_source(source):
140
+ """LAYER 1. Return a `Refused` for source this sandbox will not run, or `None`.
141
+
142
+ ⭐ PURE, AND THAT IS WHAT MAKES IT TESTABLE AT ITS OWN BOUNDARY. It reads no file, spawns no
143
+ process and touches no store, so a gate can hand it a hundred hostile strings for free and an
144
+ NC can drop one entry from one frozenset and watch exactly this function change its answer.
145
+ """
146
+ text = str(source or "")
147
+ if len(text.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
148
+ return Refused("source_too_long",
149
+ f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of source")
150
+ try:
151
+ tree = ast.parse(text)
152
+ except SyntaxError as exc:
153
+ return Refused("syntax", f"line {exc.lineno or 0}: {exc.msg}")
154
+
155
+ for node in ast.walk(tree):
156
+ kind = type(node).__name__
157
+ if kind not in ALLOWED_NODES:
158
+ return Refused("refused_construct",
159
+ f"line {getattr(node, 'lineno', 0)}: this sandbox does not run "
160
+ f"{_english(kind)}")
161
+ if isinstance(node, ast.Attribute) and not _attr_ok(node.attr):
162
+ return Refused("refused_attribute",
163
+ f"line {getattr(node, 'lineno', 0)}: the attribute "
164
+ f"'{node.attr}' is not available inside a script view")
165
+ # β›” A NAME may not be private either. `_` prefixed names are the runner's own, and a
166
+ # script that could bind one could shadow the machinery it runs on top of.
167
+ if isinstance(node, ast.Name) and node.id.startswith("_"):
168
+ return Refused("reserved_name",
169
+ f"line {getattr(node, 'lineno', 0)}: names starting with an "
170
+ f"underscore are reserved by the sandbox")
171
+ if isinstance(node, (ast.FunctionDef, ast.arg, ast.ExceptHandler)) and str(
172
+ getattr(node, "name", None) or getattr(node, "arg", "") or "").startswith("_"):
173
+ return Refused("reserved_name",
174
+ f"line {getattr(node, 'lineno', 0)}: names starting with an "
175
+ f"underscore are reserved by the sandbox")
176
+ if isinstance(node, ast.keyword) and str(node.arg or "").startswith("_"):
177
+ return Refused("reserved_name",
178
+ f"line {getattr(node, 'lineno', 0)}: keyword arguments starting with "
179
+ f"an underscore are reserved by the sandbox")
180
+ return None
181
+
182
+
183
+ _ENGLISH = {
184
+ "Import": "an import", "ImportFrom": "an import", "ClassDef": "a class definition",
185
+ "With": "a with block", "AsyncWith": "a with block", "AsyncFor": "an async loop",
186
+ "AsyncFunctionDef": "an async function", "Await": "await", "Yield": "yield",
187
+ "YieldFrom": "yield from", "Global": "a global statement", "Nonlocal": "a nonlocal statement",
188
+ "Match": "a match statement",
189
+ }
190
+
191
+
192
+ def _english(kind):
193
+ return _ENGLISH.get(kind, f"a {kind} expression")
194
+
195
+
196
+ # ══════════════════════════════════════════ LAYER 2 β€” the namespace, and the child program ═════
197
+ #: The builtins a script may reach, BY NAME. Everything else is a `NameError` in the child.
198
+ #: β›” THE ABSENCES, again, are the policy: `__import__` `open` `eval` `exec` `compile` `input`
199
+ #: `getattr` `setattr` `delattr` `globals` `locals` `vars` `dir` `type` `super` `object` `help`
200
+ #: `exit` `breakpoint` `memoryview` `id`. Several are harmless on their own; each one is a step
201
+ #: on a published escape, and none has ever been asked for by a script that shapes rows.
202
+ #: ⚠ THE EXCEPTION CLASSES ARE HERE BECAUSE `try:` IS, and a `try` block whose `except` clause
203
+ #: cannot name what it catches is a construct that reads as supported and is not. They are safe
204
+ #: for the same reason everything else is: `Exception.__subclasses__` needs an attribute this
205
+ #: sandbox does not allow, so a class object in the namespace is a leaf, not a doorway.
206
+ SANDBOX_BUILTIN_NAMES = (
207
+ "abs all any bool bytes callable chr dict divmod enumerate filter float frozenset hash hex "
208
+ "int isinstance issubclass iter len list map max min next oct ord pow range repr reversed "
209
+ "round set slice sorted str sum tuple zip True False None "
210
+ "Exception ValueError TypeError KeyError IndexError ZeroDivisionError ArithmeticError "
211
+ "AttributeError StopIteration OverflowError"
212
+ ).split()
213
+
214
+ #: The literal program the child runs. It is TEXT rather than a module because the child must
215
+ #: import nothing from this repo: a module would be found on `sys.path` and would drag `core`
216
+ #: with it, which is exactly the second store path W1 forbids.
217
+ #: ⚠ Every name in here is underscore-prefixed and layer 1 refuses a script from binding one, so
218
+ #: the runner's own machinery cannot be shadowed by the source it executes.
219
+ _RUNNER = r'''
220
+ import json as _json, os as _os, sys as _sys
221
+
222
+ _pay = _json.loads(open(_sys.argv[1], "r", encoding="utf-8").read())
223
+ _out = {"ok": False, "code": "not_run", "message": "the script did not run",
224
+ "stdout": "", "spec": None, "caps": {"wallClock": True, "memory": False, "cpu": False}}
225
+
226
+ # ── the caps this platform can actually apply, reported either way (standing rule 1) ──────────
227
+ try:
228
+ import resource as _res
229
+ _mem = int(_pay["memoryBytes"])
230
+ _res.setrlimit(_res.RLIMIT_AS, (_mem, _mem))
231
+ _out["caps"]["memory"] = True
232
+ _cpu = int(_pay["cpuSeconds"])
233
+ _res.setrlimit(_res.RLIMIT_CPU, (_cpu, _cpu))
234
+ _out["caps"]["cpu"] = True
235
+ except Exception:
236
+ # `resource` is POSIX only. The wall-clock kill in the parent still applies, and `caps` says
237
+ # which of the three held, never a silent partial.
238
+ pass
239
+
240
+ _printed = []
241
+ _spent = [0]
242
+ _LIMIT = int(_pay["maxStdout"])
243
+
244
+
245
+ def _print(*_a, **_k):
246
+ _text = (_k.get("sep") or " ").join(str(_x) for _x in _a) + (_k.get("end") or "\n")
247
+ _room = _LIMIT - _spent[0]
248
+ if _room > 0:
249
+ _printed.append(_text[:_room])
250
+ _spent[0] += len(_text)
251
+
252
+
253
+ class _Refusal(Exception):
254
+ """The SANDBOX refusing, as distinct from the SCRIPT failing.
255
+
256
+ Without its own class these arrive as `ValueError`, indistinguishable from a `ValueError` the
257
+ script raised itself, and the answer then says "refused" about an ordinary bug in the tenant's
258
+ own code. Two different facts, two different codes.
259
+ """
260
+
261
+
262
+ _emitted = []
263
+
264
+
265
+ def _emit(_spec):
266
+ if not isinstance(_spec, dict):
267
+ raise _Refusal("emit() takes a view spec, which is a dictionary")
268
+ if _emitted:
269
+ raise _Refusal("emit() was already called; a script view emits exactly one view")
270
+ _emitted.append(_spec)
271
+
272
+
273
+ _rows = _pay["rows"]
274
+ _fields = _pay["fields"]
275
+ _bound = _pay["table"]
276
+
277
+
278
+ def _scoped_table(_table=None):
279
+ if _table is not None and str(_table) != _bound:
280
+ raise _Refusal(
281
+ "this script view is bound to the database '" + _bound + "' and asked for '"
282
+ + str(_table) + "'. A script view reads its own database only")
283
+ return [dict(_r) for _r in _rows]
284
+
285
+
286
+ def _scoped_fields():
287
+ return [dict(_f) for _f in _fields]
288
+
289
+
290
+ _ns = {"__builtins__": {_n: __builtins__[_n] if isinstance(__builtins__, dict)
291
+ else getattr(__builtins__, _n)
292
+ for _n in _pay["builtins"]}}
293
+ _ns["__builtins__"]["print"] = _print
294
+ _ns["print"] = _print
295
+ _ns["emit"] = _emit
296
+ _ns["scoped_table"] = _scoped_table
297
+ _ns["scoped_fields"] = _scoped_fields
298
+ _ns["table"] = _bound
299
+
300
+ try:
301
+ exec(compile(_pay["source"], "<script view>", "exec"), _ns)
302
+ if not _emitted:
303
+ _out.update(ok=False, code="no_view",
304
+ message="the script finished without calling emit(spec)")
305
+ else:
306
+ _out.update(ok=True, code="", message="", spec=_emitted[0])
307
+ except _Refusal as _e:
308
+ _out.update(ok=False, code="refused", message=str(_e)[:400])
309
+ except MemoryError:
310
+ _out.update(ok=False, code="memory",
311
+ message="the script used more memory than a script view is allowed")
312
+ except NameError as _e:
313
+ _out.update(ok=False, code="refused_name",
314
+ message=str(_e)[:200] + ". A script view may use only the names the sandbox "
315
+ "provides")
316
+ except BaseException as _e:
317
+ _out.update(ok=False, code="error",
318
+ message=type(_e).__name__ + ": " + str(_e)[:400])
319
+
320
+ _out["stdout"] = "".join(_printed)
321
+ _out["truncated"] = _spent[0] > _LIMIT
322
+ # ⭐ THE PROBE: what this child actually had. The PARENT strips it unless it was asked for, so a
323
+ # production run never carries it and a gate can still prove that no `core.*` module and no
324
+ # secret-shaped environment key was ever inside this process.
325
+ # ⚠ SNAPSHOTTED AFTER `exec`, and `os` is imported at the TOP so this list does not depend on
326
+ # dict-literal evaluation order. The first draft called `__import__("os")` inside this very
327
+ # expression, so whether `os` appeared depended on which value Python built first: a probe whose
328
+ # contents move with an unrelated edit is a probe a gate cannot assert against.
329
+ _out["probe"] = {"modules": sorted(_sys.modules), "env": sorted(_os.environ)}
330
+ open(_sys.argv[2], "w", encoding="utf-8").write(_json.dumps(_out, default=str))
331
+ '''
332
+
333
+
334
+ def _child_env():
335
+ """The child's WHOLE environment. An allow-list of two keys, and neither is a credential.
336
+
337
+ β›” NOT `os.environ.copy()` MINUS SOMETHING. A subtractive environment ships every key nobody
338
+ thought to name: `HF_TOKEN`, `ODOO_PASSWORD`, `ANTHROPIC_API_KEY` and whatever the next
339
+ connector adds. The three names below are here because Python will not start on Windows
340
+ without them; on Linux this returns `{}` and the child runs with no environment at all.
341
+ """
342
+ env = {}
343
+ for name in ("SystemRoot", "SYSTEMROOT", "WINDIR"):
344
+ if os.environ.get(name):
345
+ env[name] = os.environ[name]
346
+ return env
347
+
348
+
349
+ def run(source, rows, fields, table_key, *, timeout_s=DEFAULT_TIMEOUT_S,
350
+ memory_bytes=DEFAULT_MEMORY_BYTES, cpu_seconds=DEFAULT_CPU_SECONDS, probe=False):
351
+ """Run ONE script over rows that are ALREADY scoped. Returns C3's envelope plus `caps`.
352
+
353
+ {ok, code, message, spec, stdout, truncated, ms, caps: {wallClock, memory, cpu}}
354
+
355
+ β›” THIS FUNCTION NEVER TOUCHES A STORE, AND THAT IS THE POINT: it takes rows. `run_view()`
356
+ below is the door that fetches them through C1; keeping the two apart is what lets a gate
357
+ drive the sandbox with no tenant, no runtime and no credential anywhere in the process.
358
+
359
+ ⚠ `caps` IS PART OF THE ANSWER, NOT DEBUG OUTPUT. On Windows `resource` does not exist, so
360
+ the memory and CPU limits are NOT applied and this says so. A caller that reports `ok:true`
361
+ without reading `caps` is claiming an enforcement that did not happen (standing rule 1).
362
+ """
363
+ started = time.monotonic()
364
+ refusal = check_source(source)
365
+ if refusal is not None:
366
+ return _refusal(refusal.code, refusal.message, started)
367
+
368
+ payload = {"source": str(source or ""), "rows": rows, "fields": fields,
369
+ "table": str(table_key or ""), "builtins": SANDBOX_BUILTIN_NAMES,
370
+ "maxStdout": MAX_STDOUT_BYTES, "memoryBytes": int(memory_bytes),
371
+ "cpuSeconds": int(cpu_seconds)}
372
+ try:
373
+ blob = json.dumps(payload, default=str)
374
+ except (TypeError, ValueError) as exc:
375
+ return _refusal("bad_rows", f"these rows cannot be handed to a script ({exc})", started)
376
+ if len(blob.encode("utf-8", "replace")) > MAX_PAYLOAD_BYTES:
377
+ # β›” REPORTED, NOT TRUNCATED (standing rule 1's second sentence): cause and recommendation,
378
+ # in the words the owner asked for, rather than a quietly short answer.
379
+ return _refusal(
380
+ "payload_too_large",
381
+ f"this database's rows are larger than the {MAX_PAYLOAD_BYTES // (1024 * 1024)} MB a "
382
+ f"script view can be handed at once. Narrow the view with a filter, or raise the "
383
+ f"sandbox payload limit for this deployment", started)
384
+
385
+ with tempfile.TemporaryDirectory(prefix="aios-script-") as work:
386
+ pay_path = Path(work) / "payload.json"
387
+ res_path = Path(work) / "result.json"
388
+ pay_path.write_text(blob, encoding="utf-8")
389
+ # `-I` isolates the interpreter (no PYTHON* env, no user site), `-S` skips site-packages,
390
+ # and the program arrives on STDIN so there is no file for anything to import it as.
391
+ # β›” `-X utf8` AND AN EXPLICIT `encoding` ARE NOT TIDINESS. Without them this pipe is
392
+ # encoded with the parent's locale codec, which on this Windows box is cp1252: the runner
393
+ # text below cannot be represented in it and `subprocess.run` died with
394
+ # `UnicodeEncodeError` before the child ever started. A sandbox whose behaviour depends on
395
+ # the operator's locale is a sandbox with two behaviours. `-I` implies `-E`, so
396
+ # `PYTHONUTF8` in the environment could not have carried this, it has to be a flag.
397
+ argv = [sys.executable, "-I", "-S", "-X", "utf8", "-", str(pay_path), str(res_path)]
398
+ try:
399
+ done = subprocess.run(
400
+ argv, input=_RUNNER, text=True, encoding="utf-8", errors="replace",
401
+ cwd=work, env=_child_env(),
402
+ stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout_s)
403
+ except subprocess.TimeoutExpired:
404
+ return _refusal("timeout",
405
+ f"the script ran longer than {timeout_s:g} seconds and was stopped",
406
+ started)
407
+ except OSError as exc:
408
+ return _refusal("no_sandbox",
409
+ f"a script view could not be started on this deployment ({exc})",
410
+ started)
411
+
412
+ if not res_path.is_file():
413
+ # The child died without writing an answer: an rlimit signal, an OOM kill, or a crash.
414
+ # ⚠ NAMED BY ITS RETURN CODE rather than reported as a generic failure β€” a memory kill
415
+ # and a bug in this file must not read identically to an operator.
416
+ return _refusal(*_died(done), started)
417
+ try:
418
+ out = json.loads(res_path.read_text(encoding="utf-8"))
419
+ except (OSError, ValueError) as exc:
420
+ return _refusal("unreadable", f"the script's answer could not be read ({exc})",
421
+ started)
422
+
423
+ out["ms"] = int((time.monotonic() - started) * 1000)
424
+ if out.get("ok"):
425
+ spec_error = _check_spec(out.get("spec"))
426
+ if spec_error:
427
+ out.update(ok=False, code="bad_spec", message=spec_error, spec=None)
428
+ if not probe:
429
+ out.pop("probe", None)
430
+ return out
431
+
432
+
433
+ def _died(done):
434
+ """`(code, message)` for a child that produced no answer."""
435
+ rc = done.returncode
436
+ tail = " ".join((done.stderr or "").split())[-300:]
437
+ if rc in (-9, 137):
438
+ return "memory", "the script was stopped for using too much memory"
439
+ if rc in (-24, 152):
440
+ return "timeout", "the script used more processor time than a script view is allowed"
441
+ return "crashed", f"the script view engine stopped without an answer{': ' + tail if tail else ''}"
442
+
443
+
444
+ def _refusal(code, message, started):
445
+ return {"ok": False, "code": code, "message": message, "spec": None, "stdout": "",
446
+ "truncated": False, "ms": int((time.monotonic() - started) * 1000),
447
+ "caps": {"wallClock": True, "memory": False, "cpu": False}}
448
+
449
+
450
+ def _check_spec(spec):
451
+ """C3: a spec is a DESCRIPTION the client draws. Never HTML, never a script, never a URL.
452
+
453
+ β›” THE CHECK IS ON THE KEYS, NOT ON THE STRING CONTENTS. Scanning values for `<script>` is a
454
+ blacklist and would pass `<SCR` + `IPT>`; refusing a spec that carries an `html`, `script`,
455
+ `src` or `onclick` key refuses the SHAPE that would let a renderer be talked into executing
456
+ something. The vocabulary of legal `kind`s is the ROUTE's business (W36-T37) β€” this is the
457
+ floor every caller gets whether or not the route above it remembers.
458
+ """
459
+ if not isinstance(spec, dict):
460
+ return "the script emitted something that is not a view spec"
461
+ try:
462
+ blob = json.dumps(spec)
463
+ except (TypeError, ValueError):
464
+ return "the emitted view spec is not something the client can be sent"
465
+ if len(blob.encode("utf-8", "replace")) > MAX_SPEC_BYTES:
466
+ return (f"the emitted view spec is over {MAX_SPEC_BYTES // (1024 * 1024)} MB. A view spec "
467
+ f"describes a picture; it is not where the rows go")
468
+ banned = {"html", "innerhtml", "script", "src", "srcdoc", "href", "style", "onclick", "onload"}
469
+ found = sorted(k for k in _keys_of(spec) if str(k).lower() in banned)
470
+ if found:
471
+ return (f"a view spec may not carry {', '.join(found)}. The client DRAWS a spec, so a "
472
+ f"markup or URL key would be a script by another name")
473
+ return None
474
+
475
+
476
+ def _keys_of(value, depth=0):
477
+ """Every key anywhere in a nested spec. Bounded, so a deep structure cannot spin this."""
478
+ if depth > 12:
479
+ return
480
+ if isinstance(value, dict):
481
+ for key, sub in value.items():
482
+ yield key
483
+ yield from _keys_of(sub, depth + 1)
484
+ elif isinstance(value, (list, tuple)):
485
+ for sub in value:
486
+ yield from _keys_of(sub, depth + 1)
487
+
488
+
489
+ # ══════════════════════════════════════════════ THE DOOR β€” C1 is the ONLY way to a row ═════════
490
+ def run_view(user, table_key, source, st=None, **kw):
491
+ """Fetch through C1 under `user`'s scope, then run the script over what came back (R5).
492
+
493
+ ⭐⭐ THE FETCH HAPPENS IN THE PARENT AND ONLY ROWS CROSS INTO THE CHILD. That is wiring W1
494
+ made structural: the child has no runtime to ask, no store handle to open and no credential
495
+ to use, so "a script cannot read what its caller cannot read" is not a rule anybody has to
496
+ keep β€” there is no second path for it to be broken through.
497
+
498
+ β›” C1'S THREE EXCEPTIONS ARE ANSWERED, NEVER SWALLOWED. `UnknownTable`, `Denied` and
499
+ `Unresolvable` mean three different things to a person; collapsing them into "no rows" is the
500
+ silent-empty answer C1 was written to make impossible. `Unresolvable.as_limit()` is handed
501
+ through in the words it was raised with β€” standing rule 1's second sentence, verbatim.
502
+ """
503
+ import core.perm_scope as perm_scope
504
+
505
+ key = str(table_key or "")
506
+ try:
507
+ rows = perm_scope.scoped_table(user, key, st=st)
508
+ fields = perm_scope.scoped_fields(user, key, st=st)
509
+ except perm_scope.UnknownTable as exc:
510
+ return _refusal("unknown_table", str(exc) or f"there is no database '{key}'",
511
+ time.monotonic())
512
+ except perm_scope.Denied as exc:
513
+ return _refusal("denied", str(exc) or "this account may not read that database",
514
+ time.monotonic())
515
+ except perm_scope.Unresolvable as exc:
516
+ out = _refusal("unresolvable", str(exc), time.monotonic())
517
+ out["limit"] = exc.as_limit()
518
+ return out
519
+ return run(source, rows, fields, key, **kw)
platform/core/store.py CHANGED
The diff for this file is too large to render. See raw diff
 
platform/core/user_tables.py CHANGED
@@ -1286,63 +1286,32 @@ def clean_zone(raw, field_keys=None, allowed_row_ids=None):
1286
 
1287
 
1288
  def zones(table_key, st=None):
1289
- """All valid zones for one table, in persisted order; malformed historical entries hide."""
 
 
 
 
1290
  key = str(table_key or '').strip()
1291
  if not key:
1292
  return []
 
 
 
1293
  try:
1294
  raw = (_st(st).get(ZONE_STORE_KEY) or {}).get(key) or []
1295
  except Exception:
1296
- return []
1297
- out = []
1298
  for zone in raw:
1299
  clean = clean_zone(zone)
1300
- if clean and clean.get('id'):
1301
- out.append(clean)
 
 
 
1302
  return out
1303
 
1304
 
1305
- def upsert_zone(table_key, raw, field_keys=None, allowed_row_ids=None, st=None,
1306
- created_by=None):
1307
- """Create/update a zone by id; the returned object is the exact persisted wire shape."""
1308
- key = str(table_key or '').strip()
1309
- if not key:
1310
- return None
1311
- clean = clean_zone(raw, field_keys=field_keys, allowed_row_ids=allowed_row_ids)
1312
- if clean is None:
1313
- return None
1314
- clean.setdefault('id', 'zone_' + _uuid.uuid4().hex)
1315
- result = {}
1316
-
1317
- def _save(current):
1318
- bucket = dict(current or {})
1319
- existing = list(bucket.get(key) or [])
1320
- replaced = False
1321
- next_zones = []
1322
- for zone in existing[:200]:
1323
- if isinstance(zone, dict) and zone.get('id') == clean['id']:
1324
- next_zones.append({**clean,
1325
- 'createdBy': zone.get('createdBy') or str(created_by or ''),
1326
- 'createdAt': zone.get('createdAt') or _dt.datetime.utcnow().isoformat()})
1327
- replaced = True
1328
- else:
1329
- next_zones.append(zone)
1330
- if not replaced:
1331
- if len(next_zones) >= 200:
1332
- return current
1333
- next_zones.append({**clean,
1334
- 'createdBy': str(created_by or ''),
1335
- 'createdAt': _dt.datetime.utcnow().isoformat()})
1336
- bucket[key] = next_zones
1337
- persisted = next((zone for zone in next_zones
1338
- if isinstance(zone, dict) and zone.get('id') == clean['id']), clean)
1339
- result.update(persisted)
1340
- return bucket
1341
-
1342
- _st(st).update(ZONE_STORE_KEY, _save, flush='sync')
1343
- return result or None
1344
-
1345
-
1346
  def zone_field(table_key, st=None):
1347
  """The canonical derived multi-select Field for one table's durable Zones."""
1348
  names, seen = [], set()
@@ -1418,7 +1387,12 @@ def is_user_table(table_key, st=None):
1418
  def is_managed_system_table(table_key, st=None, definition=None):
1419
  """C1 policy predicate, intentionally separate from ordinary record mutability."""
1420
  from core import route_system
1421
- return route_system.is_managed(definition if definition is not None else (get(table_key, st) or table_key))
 
 
 
 
 
1422
 
1423
 
1424
  def create(label, username, fields=None, source=None, st=None, *, managed_by=None, capability=None,
@@ -1439,6 +1413,15 @@ def create(label, username, fields=None, source=None, st=None, *, managed_by=Non
1439
  if len(existing) >= MAX_TABLES:
1440
  return None
1441
  key = KEY_PREFIX + _slug(label)
 
 
 
 
 
 
 
 
 
1442
  if key in existing: # a second table of the same name gets a suffix
1443
  for n in range(2, 50):
1444
  if f'{key}_{n}' not in existing:
@@ -1504,6 +1487,8 @@ def delete(table_key, st=None):
1504
  s.update(ZONE_STORE_KEY,
1505
  lambda cur: {k: v for k, v in (cur or {}).items() if k != key},
1506
  flush='async')
 
 
1507
  except Exception:
1508
  pass
1509
 
 
1286
 
1287
 
1288
  def zones(table_key, st=None):
1289
+ """All valid Zones for one table from the single normalized Route/Zone authority.
1290
+
1291
+ ``table_zones`` is read only as a migration fallback. New and edited Zones live in
1292
+ ``route_system``; canonical ids win so an adopted legacy row cannot appear twice.
1293
+ """
1294
  key = str(table_key or '').strip()
1295
  if not key:
1296
  return []
1297
+ from core import route_system
1298
+ canonical = route_system.list_zones(_st(st), table_key=key)
1299
+ known = {str(zone.get('id') or '') for zone in canonical}
1300
  try:
1301
  raw = (_st(st).get(ZONE_STORE_KEY) or {}).get(key) or []
1302
  except Exception:
1303
+ raw = []
1304
+ out = list(canonical)
1305
  for zone in raw:
1306
  clean = clean_zone(zone)
1307
+ if clean and clean.get('id') and str(clean['id']) not in known:
1308
+ evidence = clean.get('legacyMembershipEvidence') or zone.get('memberships') or []
1309
+ out.append({**clean, 'tableKey': key, 'memberPids': [
1310
+ int(pid) for pid in evidence if str(pid).isdigit()],
1311
+ 'managedBy': route_system.MANAGED_BY, 'membershipRevision': 0})
1312
  return out
1313
 
1314
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1315
  def zone_field(table_key, st=None):
1316
  """The canonical derived multi-select Field for one table's durable Zones."""
1317
  names, seen = [], set()
 
1387
  def is_managed_system_table(table_key, st=None, definition=None):
1388
  """C1 policy predicate, intentionally separate from ordinary record mutability."""
1389
  from core import route_system
1390
+ # The namespace and the marker are independent proofs. A legacy/malformed reserved-key row
1391
+ # may lack managedBy, while an internally materialized row may carry the marker under a key the
1392
+ # caller did not expect; either shape remains system-owned and outside generic table doors.
1393
+ return (route_system.is_managed(table_key)
1394
+ or route_system.is_managed(definition if definition is not None
1395
+ else (get(table_key, st) or {})))
1396
 
1397
 
1398
  def create(label, username, fields=None, source=None, st=None, *, managed_by=None, capability=None,
 
1413
  if len(existing) >= MAX_TABLES:
1414
  return None
1415
  key = KEY_PREFIX + _slug(label)
1416
+ from core import route_system
1417
+ # Route/Zone backing keys are a closed system namespace. Refuse the collision before suffix
1418
+ # allocation: otherwise an ordinary browser create can mint the exact reserved key when the
1419
+ # normalized store is empty, then make that system-shaped row discoverable through /tables.
1420
+ # The opaque internal capability remains the only generic-policy seam allowed to use one.
1421
+ if (route_system.is_managed(key)
1422
+ and (managed_by != route_system.MANAGED_BY
1423
+ or not route_system.is_internal_writer(capability))):
1424
+ return None
1425
  if key in existing: # a second table of the same name gets a suffix
1426
  for n in range(2, 50):
1427
  if f'{key}_{n}' not in existing:
 
1487
  s.update(ZONE_STORE_KEY,
1488
  lambda cur: {k: v for k, v in (cur or {}).items() if k != key},
1489
  flush='async')
1490
+ from core import route_system
1491
+ route_system.delete_zones_for_table(s, key)
1492
  except Exception:
1493
  pass
1494
 
platform/core/view_templates.py CHANGED
@@ -305,21 +305,20 @@ def application_ref(view):
305
  """Return a View's reusable Application reference, never an embedded config copy."""
306
  config = (view or {}).get('config') if isinstance(view, dict) else None
307
  ref = (config or {}).get('application') if isinstance(config, dict) else None
308
- if not isinstance(ref, dict) or not ref.get('id') or not ref.get('type'):
309
  return None
310
- return {'id': str(ref['id']), 'type': str(ref['type']),
311
- 'revision': int(ref.get('revision') or 0)}
312
-
313
-
314
- def bind_application(view, application):
315
- """Copy a View shell and bind identity/revision only; Application config remains single-source."""
316
- import copy
317
- import core.assets as assets
318
- target = assets.application_open_target(application)
319
- if not target:
320
- raise ValueError('that Application has no stable typed target')
321
- out = copy.deepcopy(view) if isinstance(view, dict) else {}
322
- config = out.setdefault('config', {})
323
- config['application'] = {'id': target['id'], 'type': target['type'],
324
- 'revision': int((application or {}).get('revision') or 0)}
325
- return out
 
305
  """Return a View's reusable Application reference, never an embedded config copy."""
306
  config = (view or {}).get('config') if isinstance(view, dict) else None
307
  ref = (config or {}).get('application') if isinstance(config, dict) else None
308
+ if not isinstance(ref, dict):
309
  return None
310
+ app_id = str(ref.get('id') or '').strip()
311
+ app_type = str(ref.get('type') or '').strip().lower()
312
+ revision = ref.get('revision')
313
+ if (not app_id or len(app_id) > 120
314
+ or any(not (char.isalnum() or char in '_-') for char in app_id)
315
+ or app_type not in {'chart', 'route', 'map', 'timeseries'}
316
+ or isinstance(revision, bool)):
317
+ return None
318
+ try:
319
+ revision = int(revision)
320
+ except (TypeError, ValueError):
321
+ return None
322
+ if revision < 0:
323
+ return None
324
+ return {'id': app_id, 'type': app_type, 'revision': revision}
 
platform/harness/meta_store.py CHANGED
@@ -1,521 +1,521 @@
1
- """meta_store.py β€” the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
2
-
3
- python platform/harness/meta_store.py --sync pull into tenant #0's mirror
4
- python platform/harness/meta_store.py --sync --tenant gtmlab
5
- python platform/harness/meta_store.py --status what is in the mirror now
6
-
7
- β›” WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
8
- hardwired to XML-RPC β€” it does `import core.odoo as O` and speaks `search_read` β€” so no amount of
9
- spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
10
- per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
11
- delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
12
- store with two loaders, not two stores.**
13
-
14
- ⭐ THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
15
- the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
16
- `XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
17
- `Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
18
- different first hop.
19
-
20
- ⚠ EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
21
- carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
22
- Ad Account 45 Β· Campaign 35 Β· Ad Set 54 Β· Ad 36 Β· Creative 58 Β· Insights 57
23
- β›” AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
24
- came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
25
- nothing going red β€” which is exactly the "do not drop any column" instruction, broken silently.
26
- The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
27
-
28
- ⚠ `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
29
- answers `403 (#200) Requires business_management permission`, which this token does not carry. One
30
- column of 285. R6's second sentence β€” a limit that cannot be removed gets stated with its cause.
31
-
32
- β›” IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
33
- larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
34
- (W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
35
- """
36
- import argparse
37
- import json
38
- import os
39
- import sys
40
- import time
41
- import urllib.error
42
- import urllib.parse
43
- import urllib.request
44
- from pathlib import Path
45
-
46
- _HERE = Path(__file__).resolve().parent
47
- if str(_HERE.parent) not in sys.path:
48
- sys.path.insert(0, str(_HERE.parent))
49
-
50
- from harness import datastore # noqa: E402
51
-
52
- GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
53
- GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
54
-
55
- #: Numeric columns, by name. Everything else is VARCHAR β€” including ids (see the header) and
56
- #: including anything Graph returns as a nested object, which is stored as compact JSON text.
57
- _INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
58
- "inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
59
- "account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
60
- "min_daily_budget", "min_campaign_group_spend_cap"}
61
- _DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
62
- "inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
63
- "daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
64
- "daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
65
- "lifetime_spend_cap", "lifetime_imps"}
66
-
67
- #: ⭐ THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
68
- #: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
69
- #: the grid links in `meta_relational`.
70
- ACCOUNT_FIELDS = (
71
- "account_id account_status age amount_spent balance business_city business_country_code "
72
- "business_name business_state business_street business_street2 business_zip capabilities "
73
- "created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
74
- "has_migrated_permissions id io_number is_attribution_spec_system_default "
75
- "is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
76
- "is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
77
- "name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
78
- "timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
79
- ).split()
80
-
81
- CAMPAIGN_FIELDS = (
82
- "account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
83
- "campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
84
- "created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
85
- "last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
86
- "promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
87
- "special_ad_category special_ad_category_country spend_cap start_time status stop_time "
88
- "topline_id updated_time"
89
- ).split()
90
-
91
- ADSET_FIELDS = (
92
- "account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
93
- "bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
94
- "campaign_active_time campaign_attribution campaign_id configured_status created_time "
95
- "creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
96
- "effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
97
- "issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
98
- "lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
99
- "optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
100
- "rf_prediction_id source_adset source_adset_id start_time status targeting "
101
- "targeting_optimization_types time_based_ad_rotation_id_blocks "
102
- "time_based_ad_rotation_intervals updated_time use_new_app_click"
103
- ).split()
104
-
105
- AD_FIELDS = (
106
- "account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
107
- "adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
108
- "conversion_domain created_time creative demolink_hash display_sequence effective_status "
109
- "engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
110
- "preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
111
- "tracking_and_conversion_with_defaults tracking_specs updated_time"
112
- ).split()
113
-
114
- CREATIVE_FIELDS = (
115
- "account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
116
- "branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
117
- "category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
118
- "destination_set_id dynamic_ad_voice effective_authorization_category "
119
- "effective_instagram_media_id effective_object_story_id enable_direct_install "
120
- "enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
121
- "instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
122
- "link_deep_link_url link_destination_display_url link_og_id link_url "
123
- "messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
124
- "object_type object_url place_page_set_id platform_customizations playable_asset_id "
125
- "portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
126
- "template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
127
- "use_page_actor_override video_id"
128
- ).split()
129
-
130
- INSIGHT_FIELDS = (
131
- "account_currency account_id account_name action_values actions ad_id ad_name adset_id "
132
- "adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
133
- "clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
134
- "cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
135
- "date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
136
- "impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
137
- "optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
138
- "social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
139
- "video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
140
- "video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
141
- "video_play_actions video_thruplay_watched_actions website_purchase_roas"
142
- ).split()
143
-
144
- #: table -> (graph edge on the account | None, measured fields, parent column)
145
- SPECS = {
146
- "meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
147
- "meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
148
- "meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
149
- "meta_ads": ("ads", AD_FIELDS, "adset_id"),
150
- "meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
151
- }
152
-
153
- #: The daily Insights grain (R2). One row per (ad, day) β€” the id is synthesised because Insights
154
- #: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
155
- INSIGHTS_TABLE = "meta_insights_daily"
156
- INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
157
-
158
- #: β›” INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
159
- #: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
160
- #: β€” Graph's way of saying the synchronous query is too heavy (the async report-run API is the
161
- #: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
162
- #: page 25 answer 200. So the window is walked in slices with every column intact:
163
- #: 57 fields Β· ad level Β· 7d Β· limit 25 -> 200, 25 rows
164
- #: 57 fields Β· account level Β· 7d -> 200, 7 rows
165
- #: ⚠ Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over β€”
166
- #: it drops columns R2 requires, and it does so invisibly.
167
- INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
168
- INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
169
- INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
170
-
171
-
172
- def _slices(days, size):
173
- """[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
174
- from datetime import date, timedelta
175
- end = date.today()
176
- start = end - timedelta(days=max(1, days) - 1)
177
- out, cur = [], start
178
- while cur <= end:
179
- stop = min(cur + timedelta(days=max(1, size) - 1), end)
180
- out.append((cur.isoformat(), stop.isoformat()))
181
- cur = stop + timedelta(days=1)
182
- return out
183
-
184
- #: ⚠ A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
185
- #: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
186
- #: not a row cap on a connected source (R6 forbids that) β€” it is a runaway guard, and reaching it
187
- #: is reported as a problem, never absorbed.
188
- MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
189
- PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
190
-
191
-
192
- class MetaError(RuntimeError):
193
- """A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
194
-
195
-
196
- def token():
197
- """The Meta token from the environment or gitignored `platform/.env`; "" when absent.
198
-
199
- ⚠ Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
200
- `platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
201
- (`core` never imports up). Fifteen lines is the price of that boundary.
202
- """
203
- tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
204
- if tok:
205
- return tok.strip()
206
- env = _HERE.parent / ".env"
207
- if env.exists():
208
- for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
209
- if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
210
- _, _, v = line.partition("=")
211
- return v.strip().strip('"').strip("'")
212
- return ""
213
-
214
-
215
- def _get(path, tok, **params):
216
- params["access_token"] = tok
217
- url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
218
- req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
219
- try:
220
- with urllib.request.urlopen(req, timeout=120) as r:
221
- return json.loads(r.read().decode("utf-8", "replace"))
222
- except urllib.error.HTTPError as e:
223
- try:
224
- msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
225
- ).get("message") or ""
226
- except Exception:
227
- msg = ""
228
- raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
229
- except Exception as e:
230
- raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
231
-
232
-
233
- #: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
234
- #: why it cannot be treated as "the server is broken, give up".
235
- _TOO_MUCH = "reduce the amount of data"
236
-
237
- #: β›” THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
238
- #: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
239
- #: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" β€” the
240
- #: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
241
- #: ⚠ It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
242
- #: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
243
- #: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
244
- _RATE_LIMITED = "too many calls"
245
- _RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
246
- _RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
247
-
248
-
249
- def _walk(path, tok, log, **params):
250
- """Every page of an edge, paged by CURSOR under our own parameters.
251
-
252
- β›” IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
253
- first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
254
- you're asking for"**, the retry at limit=25 succeeds β€” and then `next` carries the ORIGINAL
255
- limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
256
- Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
257
-
258
- ⭐ It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
259
- silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
260
- every column per row.
261
-
262
- -> (rows, hit_page_cap)
263
- """
264
- out, pages = [], 0
265
- limit = int(params.pop("limit", None) or PAGE)
266
- after, waited = None, 0
267
- while True:
268
- call = dict(params, limit=limit)
269
- if after:
270
- call["after"] = after
271
- try:
272
- body = _get(path, tok, **call)
273
- except MetaError as e:
274
- if _TOO_MUCH in str(e) and limit > 5:
275
- limit = max(5, limit // 4)
276
- log(f" page too heavy for /{path} - retrying at limit={limit} "
277
- f"(a payload ceiling, not a row cap; every column is still asked for)")
278
- continue
279
- if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
280
- waited += 1
281
- log(f" rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
282
- f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
283
- time.sleep(_RATE_WAIT)
284
- continue
285
- if _RATE_LIMITED in str(e).lower():
286
- log(f" !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
287
- f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
288
- f"limit is per ad account and persists for minutes. Fix: re-run "
289
- f"`--sync --only <table>` later; the upsert is idempotent.")
290
- return out, True
291
- raise
292
- out.extend(body.get("data") or [])
293
- pages += 1
294
- after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
295
- has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
296
- if not has_next:
297
- return out, False
298
- if pages >= MAX_PAGES:
299
- log(f" !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
300
- f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
301
- f"window with META_INSIGHTS_DAYS.")
302
- return out, True
303
-
304
-
305
- def _cell(value):
306
- """One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
307
- being dropped: R2 says every field the API returns, and `targeting` is a field."""
308
- if value is None or isinstance(value, (str, int, float, bool)):
309
- return value
310
- return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
311
-
312
-
313
- def _coltype(name, rows=None):
314
- """The DuckDB type for one column β€” decided by the DATA when there is data, by the name only
315
- as a fallback.
316
-
317
- β›” THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
318
- `cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
319
- action-type objects** on the Insights edge:
320
- [{"action_type":"outbound_click","value":"1.459854"}]
321
- Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
322
- '[{...}]' to DOUBLE` β€” after five entity tables had already been written, so the sync looked
323
- like it worked and then blew up on the last table.
324
- ⭐ Same principle the field CATALOG is built on, applied one layer down: **ask the response,
325
- do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
326
- that is what `_cell` stores; anything else falls back to the measured name hints.
327
- """
328
- if rows:
329
- seen, kinds = 0, set()
330
- for r in rows:
331
- v = r.get(name)
332
- if v is None or v == "":
333
- continue
334
- kinds.add("json" if isinstance(v, (list, dict)) else
335
- "bool" if isinstance(v, bool) else
336
- "int" if isinstance(v, int) else
337
- "float" if isinstance(v, float) else "str")
338
- seen += 1
339
- if seen >= 200:
340
- break
341
- if kinds:
342
- if "json" in kinds or "str" in kinds:
343
- return "VARCHAR" # a JSON blob, or a numeric STRING
344
- if kinds <= {"int", "bool"}:
345
- return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
346
- return "DOUBLE"
347
- if name in _INT:
348
- return "BIGINT"
349
- if name in _DBL:
350
- return "DOUBLE"
351
- return "VARCHAR" # ids included β€” see the header
352
-
353
-
354
- def _ensure(con, table, fields, rows=None):
355
- """Create or widen the table, with every column typed from `rows` when they are available.
356
-
357
- ⚠ AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
358
- column in place, and this table is DERIVED data that can be re-pulled in minutes β€” so a type
359
- disagreement drops and recreates rather than limping on with a column that refuses every
360
- insert. The alternative is a mirror that is permanently unwritable for one bad guess.
361
- """
362
- want = {f: _coltype(f, rows) for f in fields}
363
- have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
364
- if have:
365
- clash = [f for f, ty in want.items() if f in have and have[f] != ty
366
- and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
367
- if clash:
368
- con.execute(f"DROP TABLE {table}")
369
- have = {}
370
- if not have:
371
- cols = ", ".join(f"{f} {want[f]}" for f in fields)
372
- con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
373
- if "id" not in fields else
374
- f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
375
- return
376
- for f in fields:
377
- if f not in have:
378
- con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
379
-
380
-
381
- def _upsert(con, table, fields, rows):
382
- """Delete-then-insert by id β€” the same idempotence `datastore._upsert` gives the Odoo half, so
383
- a re-sync updates in place and can never append a second copy of the same object."""
384
- if not rows:
385
- return 0
386
- cols = list(fields)
387
- ids = [str(r.get("id") or "") for r in rows]
388
- q = ",".join("?" for _ in ids)
389
- con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
390
- con.executemany(
391
- f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
392
- [[_cell(r.get(c)) for c in cols] for r in rows])
393
- return len(rows)
394
-
395
-
396
- def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
397
- """Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
398
-
399
- Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
400
- exactly as `odoo_relational.refresh` is.
401
- """
402
- tok = tok or token()
403
- # β›” THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME β€” and the difference cost a
404
- # live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
405
- # `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
406
- # imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
407
- # that trips the per-ad-account rate limit and never finishes. The comment beside that call
408
- # claimed a short window the code could not deliver.
409
- # ⭐ The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
410
- # makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
411
- days = int(insights_days or INSIGHTS_DAYS)
412
- report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
413
- if not tok:
414
- report["problems"].append(
415
- "META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
416
- "was pulled. This is a missing CREDENTIAL, not a missing capability.")
417
- return report
418
-
419
- path = datastore.path_for(tenant_key)
420
- if Path(datastore.DB_PATH) != Path(path):
421
- datastore.use_path(path)
422
- con = datastore.connect()
423
- log(f" mirror: {Path(path).name}")
424
-
425
- accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
426
- report["accounts"] = [a.get("id") for a in accts]
427
- if not accts:
428
- report["problems"].append("the token reaches no ad accounts")
429
- return report
430
-
431
- # ── the five entity levels ────────────────────────────────────────────────────────────────
432
- for table, (edge, fields, _parent) in SPECS.items():
433
- rows, capped = [], False
434
- for acct in accts:
435
- aid = acct["id"]
436
- if edge is None:
437
- rows.append(_get(aid, tok, fields=",".join(fields)))
438
- else:
439
- got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
440
- rows.extend(got)
441
- capped = capped or hit
442
- _ensure(con, table, fields, rows)
443
- n = _upsert(con, table, fields, rows)
444
- total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
445
- report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
446
- log(f" {table:<20} pulled {n:>6} mirror total {total:>6}"
447
- + (" !! PAGE CAP HIT" if capped else ""))
448
- if capped:
449
- report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
450
-
451
- # ── the daily Insights grain ──────────────────────────────────────────────────────────────
452
- if insights:
453
- rows, capped = [], False
454
- for acct in accts:
455
- for since, until in _slices(days, INSIGHTS_SLICE):
456
- got, hit = _walk(f"{acct['id']}/insights", tok, log,
457
- fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
458
- time_increment="1", limit=INSIGHTS_PAGE,
459
- time_range=json.dumps({"since": since, "until": until}))
460
- rows.extend(got)
461
- capped = capped or hit
462
- # β›” Insights rows carry no id. The key must be STABLE across runs or every re-sync
463
- # appends a second copy of the same day β€” so it is composed from the grain itself.
464
- for r in rows:
465
- r["id"] = ":".join(str(r.get(k) or "") for k in
466
- (f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
467
- fields = ["id"] + INSIGHT_FIELDS
468
- _ensure(con, INSIGHTS_TABLE, fields, rows)
469
- n = _upsert(con, INSIGHTS_TABLE, fields, rows)
470
- total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
471
- report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
472
- log(f" {INSIGHTS_TABLE:<20} pulled {n:>6} mirror total {total:>6}"
473
- + (" !! PAGE CAP HIT" if capped else ""))
474
-
475
- con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
476
- ["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
477
- sum(t["in_mirror"] for t in report["tables"].values()),
478
- time.strftime("%Y-%m-%d %H:%M:%S")])
479
- return report
480
-
481
-
482
- def status(tenant_key="royal-imports"):
483
- """What is in the mirror right now, per table. Never fetches."""
484
- path = datastore.path_for(tenant_key)
485
- if Path(datastore.DB_PATH) != Path(path):
486
- datastore.use_path(path)
487
- out = {}
488
- con = datastore.connect()
489
- for table in list(SPECS) + [INSIGHTS_TABLE]:
490
- try:
491
- out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
492
- except Exception:
493
- out[table] = None # table absent = never synced
494
- return out
495
-
496
-
497
- def main(argv=None):
498
- ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
499
- ap.add_argument("--sync", action="store_true")
500
- ap.add_argument("--status", action="store_true")
501
- ap.add_argument("--tenant", default="royal-imports")
502
- ap.add_argument("--no-insights", action="store_true")
503
- ap.add_argument("--insights-days", type=int, default=None,
504
- help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
505
- a = ap.parse_args(argv)
506
- if a.status:
507
- for k, v in status(a.tenant).items():
508
- print(f" {k:<20} {'(never synced)' if v is None else v}")
509
- return 0
510
- if not a.sync:
511
- ap.print_help()
512
- return 2
513
- rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
514
- for p in rep["problems"]:
515
- print(" PROBLEM:", p)
516
- print(f" accounts: {len(rep['accounts'])} tables: {len(rep['tables'])}")
517
- return 1 if rep["problems"] else 0
518
-
519
-
520
- if __name__ == "__main__":
521
- sys.exit(main())
 
1
+ """meta_store.py β€” the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
2
+
3
+ python platform/harness/meta_store.py --sync pull into tenant #0's mirror
4
+ python platform/harness/meta_store.py --sync --tenant gtmlab
5
+ python platform/harness/meta_store.py --status what is in the mirror now
6
+
7
+ β›” WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
8
+ hardwired to XML-RPC β€” it does `import core.odoo as O` and speaks `search_read` β€” so no amount of
9
+ spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
10
+ per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
11
+ delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
12
+ store with two loaders, not two stores.**
13
+
14
+ ⭐ THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
15
+ the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
16
+ `XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
17
+ `Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
18
+ different first hop.
19
+
20
+ ⚠ EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
21
+ carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
22
+ Ad Account 45 Β· Campaign 35 Β· Ad Set 54 Β· Ad 36 Β· Creative 58 Β· Insights 57
23
+ β›” AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
24
+ came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
25
+ nothing going red β€” which is exactly the "do not drop any column" instruction, broken silently.
26
+ The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
27
+
28
+ ⚠ `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
29
+ answers `403 (#200) Requires business_management permission`, which this token does not carry. One
30
+ column of 285. R6's second sentence β€” a limit that cannot be removed gets stated with its cause.
31
+
32
+ β›” IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
33
+ larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
34
+ (W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
35
+ """
36
+ import argparse
37
+ import json
38
+ import os
39
+ import sys
40
+ import time
41
+ import urllib.error
42
+ import urllib.parse
43
+ import urllib.request
44
+ from pathlib import Path
45
+
46
+ _HERE = Path(__file__).resolve().parent
47
+ if str(_HERE.parent) not in sys.path:
48
+ sys.path.insert(0, str(_HERE.parent))
49
+
50
+ from harness import datastore # noqa: E402
51
+
52
+ GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
53
+ GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
54
+
55
+ #: Numeric columns, by name. Everything else is VARCHAR β€” including ids (see the header) and
56
+ #: including anything Graph returns as a nested object, which is stored as compact JSON text.
57
+ _INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
58
+ "inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
59
+ "account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
60
+ "min_daily_budget", "min_campaign_group_spend_cap"}
61
+ _DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
62
+ "inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
63
+ "daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
64
+ "daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
65
+ "lifetime_spend_cap", "lifetime_imps"}
66
+
67
+ #: ⭐ THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
68
+ #: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
69
+ #: the grid links in `meta_relational`.
70
+ ACCOUNT_FIELDS = (
71
+ "account_id account_status age amount_spent balance business_city business_country_code "
72
+ "business_name business_state business_street business_street2 business_zip capabilities "
73
+ "created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
74
+ "has_migrated_permissions id io_number is_attribution_spec_system_default "
75
+ "is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
76
+ "is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
77
+ "name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
78
+ "timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
79
+ ).split()
80
+
81
+ CAMPAIGN_FIELDS = (
82
+ "account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
83
+ "campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
84
+ "created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
85
+ "last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
86
+ "promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
87
+ "special_ad_category special_ad_category_country spend_cap start_time status stop_time "
88
+ "topline_id updated_time"
89
+ ).split()
90
+
91
+ ADSET_FIELDS = (
92
+ "account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
93
+ "bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
94
+ "campaign_active_time campaign_attribution campaign_id configured_status created_time "
95
+ "creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
96
+ "effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
97
+ "issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
98
+ "lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
99
+ "optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
100
+ "rf_prediction_id source_adset source_adset_id start_time status targeting "
101
+ "targeting_optimization_types time_based_ad_rotation_id_blocks "
102
+ "time_based_ad_rotation_intervals updated_time use_new_app_click"
103
+ ).split()
104
+
105
+ AD_FIELDS = (
106
+ "account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
107
+ "adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
108
+ "conversion_domain created_time creative demolink_hash display_sequence effective_status "
109
+ "engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
110
+ "preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
111
+ "tracking_and_conversion_with_defaults tracking_specs updated_time"
112
+ ).split()
113
+
114
+ CREATIVE_FIELDS = (
115
+ "account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
116
+ "branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
117
+ "category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
118
+ "destination_set_id dynamic_ad_voice effective_authorization_category "
119
+ "effective_instagram_media_id effective_object_story_id enable_direct_install "
120
+ "enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
121
+ "instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
122
+ "link_deep_link_url link_destination_display_url link_og_id link_url "
123
+ "messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
124
+ "object_type object_url place_page_set_id platform_customizations playable_asset_id "
125
+ "portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
126
+ "template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
127
+ "use_page_actor_override video_id"
128
+ ).split()
129
+
130
+ INSIGHT_FIELDS = (
131
+ "account_currency account_id account_name action_values actions ad_id ad_name adset_id "
132
+ "adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
133
+ "clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
134
+ "cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
135
+ "date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
136
+ "impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
137
+ "optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
138
+ "social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
139
+ "video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
140
+ "video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
141
+ "video_play_actions video_thruplay_watched_actions website_purchase_roas"
142
+ ).split()
143
+
144
+ #: table -> (graph edge on the account | None, measured fields, parent column)
145
+ SPECS = {
146
+ "meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
147
+ "meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
148
+ "meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
149
+ "meta_ads": ("ads", AD_FIELDS, "adset_id"),
150
+ "meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
151
+ }
152
+
153
+ #: The daily Insights grain (R2). One row per (ad, day) β€” the id is synthesised because Insights
154
+ #: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
155
+ INSIGHTS_TABLE = "meta_insights_daily"
156
+ INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
157
+
158
+ #: β›” INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
159
+ #: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
160
+ #: β€” Graph's way of saying the synchronous query is too heavy (the async report-run API is the
161
+ #: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
162
+ #: page 25 answer 200. So the window is walked in slices with every column intact:
163
+ #: 57 fields Β· ad level Β· 7d Β· limit 25 -> 200, 25 rows
164
+ #: 57 fields Β· account level Β· 7d -> 200, 7 rows
165
+ #: ⚠ Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over β€”
166
+ #: it drops columns R2 requires, and it does so invisibly.
167
+ INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
168
+ INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
169
+ INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
170
+
171
+
172
+ def _slices(days, size):
173
+ """[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
174
+ from datetime import date, timedelta
175
+ end = date.today()
176
+ start = end - timedelta(days=max(1, days) - 1)
177
+ out, cur = [], start
178
+ while cur <= end:
179
+ stop = min(cur + timedelta(days=max(1, size) - 1), end)
180
+ out.append((cur.isoformat(), stop.isoformat()))
181
+ cur = stop + timedelta(days=1)
182
+ return out
183
+
184
+ #: ⚠ A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
185
+ #: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
186
+ #: not a row cap on a connected source (R6 forbids that) β€” it is a runaway guard, and reaching it
187
+ #: is reported as a problem, never absorbed.
188
+ MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
189
+ PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
190
+
191
+
192
+ class MetaError(RuntimeError):
193
+ """A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
194
+
195
+
196
+ def token():
197
+ """The Meta token from the environment or gitignored `platform/.env`; "" when absent.
198
+
199
+ ⚠ Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
200
+ `platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
201
+ (`core` never imports up). Fifteen lines is the price of that boundary.
202
+ """
203
+ tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
204
+ if tok:
205
+ return tok.strip()
206
+ env = _HERE.parent / ".env"
207
+ if env.exists():
208
+ for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
209
+ if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
210
+ _, _, v = line.partition("=")
211
+ return v.strip().strip('"').strip("'")
212
+ return ""
213
+
214
+
215
+ def _get(path, tok, **params):
216
+ params["access_token"] = tok
217
+ url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
218
+ req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
219
+ try:
220
+ with urllib.request.urlopen(req, timeout=120) as r:
221
+ return json.loads(r.read().decode("utf-8", "replace"))
222
+ except urllib.error.HTTPError as e:
223
+ try:
224
+ msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
225
+ ).get("message") or ""
226
+ except Exception:
227
+ msg = ""
228
+ raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
229
+ except Exception as e:
230
+ raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
231
+
232
+
233
+ #: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
234
+ #: why it cannot be treated as "the server is broken, give up".
235
+ _TOO_MUCH = "reduce the amount of data"
236
+
237
+ #: β›” THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
238
+ #: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
239
+ #: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" β€” the
240
+ #: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
241
+ #: ⚠ It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
242
+ #: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
243
+ #: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
244
+ _RATE_LIMITED = "too many calls"
245
+ _RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
246
+ _RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
247
+
248
+
249
+ def _walk(path, tok, log, **params):
250
+ """Every page of an edge, paged by CURSOR under our own parameters.
251
+
252
+ β›” IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
253
+ first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
254
+ you're asking for"**, the retry at limit=25 succeeds β€” and then `next` carries the ORIGINAL
255
+ limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
256
+ Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
257
+
258
+ ⭐ It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
259
+ silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
260
+ every column per row.
261
+
262
+ -> (rows, hit_page_cap)
263
+ """
264
+ out, pages = [], 0
265
+ limit = int(params.pop("limit", None) or PAGE)
266
+ after, waited = None, 0
267
+ while True:
268
+ call = dict(params, limit=limit)
269
+ if after:
270
+ call["after"] = after
271
+ try:
272
+ body = _get(path, tok, **call)
273
+ except MetaError as e:
274
+ if _TOO_MUCH in str(e) and limit > 5:
275
+ limit = max(5, limit // 4)
276
+ log(f" page too heavy for /{path} - retrying at limit={limit} "
277
+ f"(a payload ceiling, not a row cap; every column is still asked for)")
278
+ continue
279
+ if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
280
+ waited += 1
281
+ log(f" rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
282
+ f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
283
+ time.sleep(_RATE_WAIT)
284
+ continue
285
+ if _RATE_LIMITED in str(e).lower():
286
+ log(f" !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
287
+ f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
288
+ f"limit is per ad account and persists for minutes. Fix: re-run "
289
+ f"`--sync --only <table>` later; the upsert is idempotent.")
290
+ return out, True
291
+ raise
292
+ out.extend(body.get("data") or [])
293
+ pages += 1
294
+ after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
295
+ has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
296
+ if not has_next:
297
+ return out, False
298
+ if pages >= MAX_PAGES:
299
+ log(f" !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
300
+ f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
301
+ f"window with META_INSIGHTS_DAYS.")
302
+ return out, True
303
+
304
+
305
+ def _cell(value):
306
+ """One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
307
+ being dropped: R2 says every field the API returns, and `targeting` is a field."""
308
+ if value is None or isinstance(value, (str, int, float, bool)):
309
+ return value
310
+ return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
311
+
312
+
313
+ def _coltype(name, rows=None):
314
+ """The DuckDB type for one column β€” decided by the DATA when there is data, by the name only
315
+ as a fallback.
316
+
317
+ β›” THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
318
+ `cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
319
+ action-type objects** on the Insights edge:
320
+ [{"action_type":"outbound_click","value":"1.459854"}]
321
+ Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
322
+ '[{...}]' to DOUBLE` β€” after five entity tables had already been written, so the sync looked
323
+ like it worked and then blew up on the last table.
324
+ ⭐ Same principle the field CATALOG is built on, applied one layer down: **ask the response,
325
+ do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
326
+ that is what `_cell` stores; anything else falls back to the measured name hints.
327
+ """
328
+ if rows:
329
+ seen, kinds = 0, set()
330
+ for r in rows:
331
+ v = r.get(name)
332
+ if v is None or v == "":
333
+ continue
334
+ kinds.add("json" if isinstance(v, (list, dict)) else
335
+ "bool" if isinstance(v, bool) else
336
+ "int" if isinstance(v, int) else
337
+ "float" if isinstance(v, float) else "str")
338
+ seen += 1
339
+ if seen >= 200:
340
+ break
341
+ if kinds:
342
+ if "json" in kinds or "str" in kinds:
343
+ return "VARCHAR" # a JSON blob, or a numeric STRING
344
+ if kinds <= {"int", "bool"}:
345
+ return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
346
+ return "DOUBLE"
347
+ if name in _INT:
348
+ return "BIGINT"
349
+ if name in _DBL:
350
+ return "DOUBLE"
351
+ return "VARCHAR" # ids included β€” see the header
352
+
353
+
354
+ def _ensure(con, table, fields, rows=None):
355
+ """Create or widen the table, with every column typed from `rows` when they are available.
356
+
357
+ ⚠ AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
358
+ column in place, and this table is DERIVED data that can be re-pulled in minutes β€” so a type
359
+ disagreement drops and recreates rather than limping on with a column that refuses every
360
+ insert. The alternative is a mirror that is permanently unwritable for one bad guess.
361
+ """
362
+ want = {f: _coltype(f, rows) for f in fields}
363
+ have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
364
+ if have:
365
+ clash = [f for f, ty in want.items() if f in have and have[f] != ty
366
+ and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
367
+ if clash:
368
+ con.execute(f"DROP TABLE {table}")
369
+ have = {}
370
+ if not have:
371
+ cols = ", ".join(f"{f} {want[f]}" for f in fields)
372
+ con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
373
+ if "id" not in fields else
374
+ f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
375
+ return
376
+ for f in fields:
377
+ if f not in have:
378
+ con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
379
+
380
+
381
+ def _upsert(con, table, fields, rows):
382
+ """Delete-then-insert by id β€” the same idempotence `datastore._upsert` gives the Odoo half, so
383
+ a re-sync updates in place and can never append a second copy of the same object."""
384
+ if not rows:
385
+ return 0
386
+ cols = list(fields)
387
+ ids = [str(r.get("id") or "") for r in rows]
388
+ q = ",".join("?" for _ in ids)
389
+ con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
390
+ con.executemany(
391
+ f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
392
+ [[_cell(r.get(c)) for c in cols] for r in rows])
393
+ return len(rows)
394
+
395
+
396
+ def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
397
+ """Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
398
+
399
+ Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
400
+ exactly as `odoo_relational.refresh` is.
401
+ """
402
+ tok = tok or token()
403
+ # β›” THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME β€” and the difference cost a
404
+ # live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
405
+ # `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
406
+ # imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
407
+ # that trips the per-ad-account rate limit and never finishes. The comment beside that call
408
+ # claimed a short window the code could not deliver.
409
+ # ⭐ The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
410
+ # makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
411
+ days = int(insights_days or INSIGHTS_DAYS)
412
+ report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
413
+ if not tok:
414
+ report["problems"].append(
415
+ "META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
416
+ "was pulled. This is a missing CREDENTIAL, not a missing capability.")
417
+ return report
418
+
419
+ path = datastore.path_for(tenant_key)
420
+ if Path(datastore.DB_PATH) != Path(path):
421
+ datastore.use_path(path)
422
+ con = datastore.connect()
423
+ log(f" mirror: {Path(path).name}")
424
+
425
+ accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
426
+ report["accounts"] = [a.get("id") for a in accts]
427
+ if not accts:
428
+ report["problems"].append("the token reaches no ad accounts")
429
+ return report
430
+
431
+ # ── the five entity levels ────────────────────────────────────────────────────────────────
432
+ for table, (edge, fields, _parent) in SPECS.items():
433
+ rows, capped = [], False
434
+ for acct in accts:
435
+ aid = acct["id"]
436
+ if edge is None:
437
+ rows.append(_get(aid, tok, fields=",".join(fields)))
438
+ else:
439
+ got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
440
+ rows.extend(got)
441
+ capped = capped or hit
442
+ _ensure(con, table, fields, rows)
443
+ n = _upsert(con, table, fields, rows)
444
+ total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
445
+ report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
446
+ log(f" {table:<20} pulled {n:>6} mirror total {total:>6}"
447
+ + (" !! PAGE CAP HIT" if capped else ""))
448
+ if capped:
449
+ report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
450
+
451
+ # ── the daily Insights grain ──────────────────────────────────────────────────────────────
452
+ if insights:
453
+ rows, capped = [], False
454
+ for acct in accts:
455
+ for since, until in _slices(days, INSIGHTS_SLICE):
456
+ got, hit = _walk(f"{acct['id']}/insights", tok, log,
457
+ fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
458
+ time_increment="1", limit=INSIGHTS_PAGE,
459
+ time_range=json.dumps({"since": since, "until": until}))
460
+ rows.extend(got)
461
+ capped = capped or hit
462
+ # β›” Insights rows carry no id. The key must be STABLE across runs or every re-sync
463
+ # appends a second copy of the same day β€” so it is composed from the grain itself.
464
+ for r in rows:
465
+ r["id"] = ":".join(str(r.get(k) or "") for k in
466
+ (f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
467
+ fields = ["id"] + INSIGHT_FIELDS
468
+ _ensure(con, INSIGHTS_TABLE, fields, rows)
469
+ n = _upsert(con, INSIGHTS_TABLE, fields, rows)
470
+ total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
471
+ report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
472
+ log(f" {INSIGHTS_TABLE:<20} pulled {n:>6} mirror total {total:>6}"
473
+ + (" !! PAGE CAP HIT" if capped else ""))
474
+
475
+ con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
476
+ ["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
477
+ sum(t["in_mirror"] for t in report["tables"].values()),
478
+ time.strftime("%Y-%m-%d %H:%M:%S")])
479
+ return report
480
+
481
+
482
+ def status(tenant_key="royal-imports"):
483
+ """What is in the mirror right now, per table. Never fetches."""
484
+ path = datastore.path_for(tenant_key)
485
+ if Path(datastore.DB_PATH) != Path(path):
486
+ datastore.use_path(path)
487
+ out = {}
488
+ con = datastore.connect()
489
+ for table in list(SPECS) + [INSIGHTS_TABLE]:
490
+ try:
491
+ out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
492
+ except Exception:
493
+ out[table] = None # table absent = never synced
494
+ return out
495
+
496
+
497
+ def main(argv=None):
498
+ ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
499
+ ap.add_argument("--sync", action="store_true")
500
+ ap.add_argument("--status", action="store_true")
501
+ ap.add_argument("--tenant", default="royal-imports")
502
+ ap.add_argument("--no-insights", action="store_true")
503
+ ap.add_argument("--insights-days", type=int, default=None,
504
+ help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
505
+ a = ap.parse_args(argv)
506
+ if a.status:
507
+ for k, v in status(a.tenant).items():
508
+ print(f" {k:<20} {'(never synced)' if v is None else v}")
509
+ return 0
510
+ if not a.sync:
511
+ ap.print_help()
512
+ return 2
513
+ rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
514
+ for p in rep["problems"]:
515
+ print(" PROBLEM:", p)
516
+ print(f" accounts: {len(rep['accounts'])} tables: {len(rep['tables'])}")
517
+ return 1 if rep["problems"] else 0
518
+
519
+
520
+ if __name__ == "__main__":
521
+ sys.exit(main())
platform/model/metrics/sales.yml CHANGED
@@ -1,149 +1,149 @@
1
- # Metrics: sales β€” the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
2
- # metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
3
- # Fields per metric:
4
- # key/label/description β€” identity + the human definition (visibility = trust)
5
- # agg + field β€” sum | count_distinct over the topic's entity
6
- # agg: ratio β€” numerator/denominator are metric KEYS (resolved recursively)
7
- # agg: derived + expr β€” arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
8
- # format β€” usd | int | pct (rendering hint for surfaces)
9
- # ai_context β€” what a small model must know to use the metric correctly
10
- # validate β€” the INDEPENDENT Odoo cross-check contract (named method implemented in
11
- # harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
12
- # empty β€” W37 C1's EMPTY-WINDOW FAMILY. See below; a metric an ENTITY topic
13
- # offers as a lookback column MUST declare one.
14
- #
15
- # β›”β›” `empty:` β€” WHAT A ROW WITH NO ACTIVITY IN THE WINDOW RENDERS AS (wave 37, contract C1).
16
- # Measured and load-bearing: only 1,646 of 5,836 active products sold in the last 90 days, so a
17
- # per-SKU lookback metric has NO GROUP for 72% of the catalogue. Get the default wrong and every
18
- # product grid reads as broken. Two values, and the difference is whether the blank cell would be
19
- # a TRUE STATEMENT:
20
- # empty: zero ADDITIVE β€” units, revenue, margin $, COGS. "It sold nothing" is a real
21
- # measurement, so 0 is the honest cell and a blank would hide a fact.
22
- # empty: blank RATIO / DERIVED-FROM-A-RATIO β€” GM %, ASP. A 0% margin on zero sales is a
23
- # FALSE statement, not a missing one. β›” AND THE GUARD IS THE DENOMINATOR, NOT
24
- # THE MISSING GROUP: `semantic._post_compute` returns 0.0 for `num/0`, so a SKU
25
- # that DID sell at $0 would print "0.0%" with a group behind it. The resolver
26
- # blanks on a zero denominator, which is the only reading that is never a lie.
27
- # ⚠ A metric with no `empty:` is REFUSED by `entity_measures()` rather than defaulted β€” a
28
- # defaulted family is a guess about truth, and C1 says a metric that cannot say which family it
29
- # is in does not ship.
30
- topic: sales_lines
31
- metrics:
32
- - key: revenue
33
- label: Revenue
34
- agg: sum
35
- field: price_subtotal
36
- format: usd
37
- empty: zero
38
- description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
39
- ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
40
- validate:
41
- method: order_level_revenue
42
- 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)."
43
-
44
- - key: units
45
- label: Units sold
46
- agg: sum
47
- field: product_uom_qty
48
- format: int
49
- empty: zero
50
- description: "Total quantity across confirmed wholesale order lines."
51
- ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
52
-
53
- - key: margin
54
- label: Gross margin $
55
- agg: sum
56
- field: margin
57
- format: usd
58
- empty: zero
59
- description: "Line revenue minus line cost (Odoo Margin module), summed."
60
- 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."
61
-
62
- - key: cogs
63
- label: COGS
64
- agg: derived
65
- expr: "revenue - margin"
66
- format: usd
67
- empty: zero
68
- description: "Cost of goods sold, derived: revenue minus gross margin."
69
- ai_context: "Derived, not pulled β€” Odoo carries cost on lines as margin; COGS is the difference."
70
-
71
- - key: margin_pct
72
- label: Gross margin %
73
- agg: ratio
74
- numerator: margin
75
- denominator: revenue
76
- format: pct
77
- empty: blank
78
- description: "Gross margin as a share of revenue."
79
- 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."
80
-
81
- # ⭐ W37-T10 β€” ASP, the fifth SHIP-FIRST per-SKU metric (proto/P3). Blended $18.76 over 1,646
82
- # SKUs in the 90 days to 2026-08-19. A RATIO of two same-topic base measures, so it survives a
83
- # GROUPED store_query (only a CROSS-TOPIC component is refused β€” that is what stops `aov`,
84
- # whose denominator `orders` lives on sales_orders).
85
- # ⚠ UNITS ARE AS-ORDERED, mixed UoM. `units` says so and this inherits it: a SKU sold in cases
86
- # and in singles has an ASP blended across both, which is the true average selling price of a
87
- # line unit and NOT a per-piece price.
88
- - key: asp
89
- label: Average selling price
90
- agg: ratio
91
- numerator: revenue
92
- denominator: units
93
- format: usd
94
- empty: blank
95
- description: "Revenue per unit sold β€” the blended average selling price."
96
- 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."
97
-
98
- - key: orders
99
- label: Orders
100
- topic: sales_orders
101
- agg: count
102
- format: int
103
- description: "Confirmed wholesale orders in the window (order-header count β€” what the scorecards show)."
104
- 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)."
105
- validate:
106
- method: order_count
107
- note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
108
-
109
- - key: customers
110
- label: Active customers
111
- agg: count_distinct
112
- field: order_partner_id
113
- format: int
114
- empty: zero
115
- description: "Distinct customers with at least one confirmed wholesale order line in the window."
116
- ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
117
-
118
- - key: aov
119
- label: Average order value
120
- agg: ratio
121
- numerator: revenue
122
- denominator: orders
123
- format: usd
124
- description: "Revenue per distinct order."
125
- ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
126
-
127
- # ⭐ Wave 21 R2 β€” the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
128
- # not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
129
- # invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
130
- # `live_domain` filters the live path β€” BOTH or store_parity compares two different questions.
131
- - key: revenue_invoiced
132
- label: Sales β€” fully invoiced
133
- agg: sum
134
- field: price_subtotal
135
- store_filter_sql: "o.invoice_status = 'invoiced'"
136
- live_domain: [["order_id.invoice_status", "=", "invoiced"]]
137
- format: usd
138
- description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
139
- 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."
140
-
141
- - key: orders_invoiced
142
- label: Orders β€” fully invoiced
143
- topic: sales_orders
144
- agg: count
145
- store_filter_sql: "o.invoice_status = 'invoiced'"
146
- live_domain: [["invoice_status", "=", "invoiced"]]
147
- format: int
148
- description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
149
- 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."
 
1
+ # Metrics: sales β€” the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
2
+ # metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
3
+ # Fields per metric:
4
+ # key/label/description β€” identity + the human definition (visibility = trust)
5
+ # agg + field β€” sum | count_distinct over the topic's entity
6
+ # agg: ratio β€” numerator/denominator are metric KEYS (resolved recursively)
7
+ # agg: derived + expr β€” arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
8
+ # format β€” usd | int | pct (rendering hint for surfaces)
9
+ # ai_context β€” what a small model must know to use the metric correctly
10
+ # validate β€” the INDEPENDENT Odoo cross-check contract (named method implemented in
11
+ # harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
12
+ # empty β€” W37 C1's EMPTY-WINDOW FAMILY. See below; a metric an ENTITY topic
13
+ # offers as a lookback column MUST declare one.
14
+ #
15
+ # β›”β›” `empty:` β€” WHAT A ROW WITH NO ACTIVITY IN THE WINDOW RENDERS AS (wave 37, contract C1).
16
+ # Measured and load-bearing: only 1,646 of 5,836 active products sold in the last 90 days, so a
17
+ # per-SKU lookback metric has NO GROUP for 72% of the catalogue. Get the default wrong and every
18
+ # product grid reads as broken. Two values, and the difference is whether the blank cell would be
19
+ # a TRUE STATEMENT:
20
+ # empty: zero ADDITIVE β€” units, revenue, margin $, COGS. "It sold nothing" is a real
21
+ # measurement, so 0 is the honest cell and a blank would hide a fact.
22
+ # empty: blank RATIO / DERIVED-FROM-A-RATIO β€” GM %, ASP. A 0% margin on zero sales is a
23
+ # FALSE statement, not a missing one. β›” AND THE GUARD IS THE DENOMINATOR, NOT
24
+ # THE MISSING GROUP: `semantic._post_compute` returns 0.0 for `num/0`, so a SKU
25
+ # that DID sell at $0 would print "0.0%" with a group behind it. The resolver
26
+ # blanks on a zero denominator, which is the only reading that is never a lie.
27
+ # ⚠ A metric with no `empty:` is REFUSED by `entity_measures()` rather than defaulted β€” a
28
+ # defaulted family is a guess about truth, and C1 says a metric that cannot say which family it
29
+ # is in does not ship.
30
+ topic: sales_lines
31
+ metrics:
32
+ - key: revenue
33
+ label: Revenue
34
+ agg: sum
35
+ field: price_subtotal
36
+ format: usd
37
+ empty: zero
38
+ description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
39
+ ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
40
+ validate:
41
+ method: order_level_revenue
42
+ 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)."
43
+
44
+ - key: units
45
+ label: Units sold
46
+ agg: sum
47
+ field: product_uom_qty
48
+ format: int
49
+ empty: zero
50
+ description: "Total quantity across confirmed wholesale order lines."
51
+ ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
52
+
53
+ - key: margin
54
+ label: Gross margin $
55
+ agg: sum
56
+ field: margin
57
+ format: usd
58
+ empty: zero
59
+ description: "Line revenue minus line cost (Odoo Margin module), summed."
60
+ 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."
61
+
62
+ - key: cogs
63
+ label: COGS
64
+ agg: derived
65
+ expr: "revenue - margin"
66
+ format: usd
67
+ empty: zero
68
+ description: "Cost of goods sold, derived: revenue minus gross margin."
69
+ ai_context: "Derived, not pulled β€” Odoo carries cost on lines as margin; COGS is the difference."
70
+
71
+ - key: margin_pct
72
+ label: Gross margin %
73
+ agg: ratio
74
+ numerator: margin
75
+ denominator: revenue
76
+ format: pct
77
+ empty: blank
78
+ description: "Gross margin as a share of revenue."
79
+ 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."
80
+
81
+ # ⭐ W37-T10 β€” ASP, the fifth SHIP-FIRST per-SKU metric (proto/P3). Blended $18.76 over 1,646
82
+ # SKUs in the 90 days to 2026-08-19. A RATIO of two same-topic base measures, so it survives a
83
+ # GROUPED store_query (only a CROSS-TOPIC component is refused β€” that is what stops `aov`,
84
+ # whose denominator `orders` lives on sales_orders).
85
+ # ⚠ UNITS ARE AS-ORDERED, mixed UoM. `units` says so and this inherits it: a SKU sold in cases
86
+ # and in singles has an ASP blended across both, which is the true average selling price of a
87
+ # line unit and NOT a per-piece price.
88
+ - key: asp
89
+ label: Average selling price
90
+ agg: ratio
91
+ numerator: revenue
92
+ denominator: units
93
+ format: usd
94
+ empty: blank
95
+ description: "Revenue per unit sold β€” the blended average selling price."
96
+ 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."
97
+
98
+ - key: orders
99
+ label: Orders
100
+ topic: sales_orders
101
+ agg: count
102
+ format: int
103
+ description: "Confirmed wholesale orders in the window (order-header count β€” what the scorecards show)."
104
+ 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)."
105
+ validate:
106
+ method: order_count
107
+ note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
108
+
109
+ - key: customers
110
+ label: Active customers
111
+ agg: count_distinct
112
+ field: order_partner_id
113
+ format: int
114
+ empty: zero
115
+ description: "Distinct customers with at least one confirmed wholesale order line in the window."
116
+ ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
117
+
118
+ - key: aov
119
+ label: Average order value
120
+ agg: ratio
121
+ numerator: revenue
122
+ denominator: orders
123
+ format: usd
124
+ description: "Revenue per distinct order."
125
+ ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
126
+
127
+ # ⭐ Wave 21 R2 β€” the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
128
+ # not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
129
+ # invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
130
+ # `live_domain` filters the live path β€” BOTH or store_parity compares two different questions.
131
+ - key: revenue_invoiced
132
+ label: Sales β€” fully invoiced
133
+ agg: sum
134
+ field: price_subtotal
135
+ store_filter_sql: "o.invoice_status = 'invoiced'"
136
+ live_domain: [["order_id.invoice_status", "=", "invoiced"]]
137
+ format: usd
138
+ description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
139
+ 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."
140
+
141
+ - key: orders_invoiced
142
+ label: Orders β€” fully invoiced
143
+ topic: sales_orders
144
+ agg: count
145
+ store_filter_sql: "o.invoice_status = 'invoiced'"
146
+ live_domain: [["invoice_status", "=", "invoiced"]]
147
+ format: int
148
+ description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
149
+ ai_context: "Order-header count under the orders scope plus the fully-invoiced flag; partially invoiced and not-yet-invoiced orders are excluded. Reconciled store-vs-live per BU by store_parity."
platform/model/topics/odoo_accounts.yml CHANGED
@@ -1,60 +1,60 @@
1
- # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
- # the databases a person actually opens, not only the line and document grains.
3
- #
4
- # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
- # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
- # field row: add the column to the grid contract and re-emit, or the agent is being
7
- # trained on a schema the product does not have.
8
- key: odoo_accounts
9
- label: "Odoo GL accounts"
10
- entity: account.account
11
- # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
- grid: ut_odoo_accounts
13
- subject: "odoo:account.account"
14
- grain: "one row per GL account in the chart of accounts"
15
- scope:
16
- population: "every account.account record (192 measured)"
17
- store:
18
- table: account_account
19
- alias: a
20
- # NO date_col β€” a registry is not a dated event stream. Stated rather than
21
- # omitted, so its absence reads as a fact and not as an unfinished file.
22
- dims:
23
- account_type: {label: "Account type"}
24
-
25
- # key / label / type / kind, derived from the grid contract. `kind` says where the
26
- # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
27
- # from another topic; a `link` points at another database.
28
- fields:
29
- - key: account_code
30
- label: "Code"
31
- type: text
32
- kind: data
33
- - key: account_name
34
- label: "Account"
35
- type: text
36
- kind: data
37
- - key: odoo_id
38
- label: "Odoo ID"
39
- type: int
40
- kind: data
41
- means: "The `account.account` id. Also this row's id."
42
- - key: account_type
43
- label: "Type"
44
- type: select
45
- kind: data
46
- - key: is_expense
47
- label: "Expense account"
48
- type: checkbox
49
- kind: data
50
- 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."
51
- - key: refreshed
52
- label: "Refreshed"
53
- type: date
54
- kind: data
55
- means: "When this row was last reconciled against Odoo."
56
-
57
- ai_context: >
58
- The chart of accounts β€” the registry gl_lines posts against.
59
- Use it to resolve an account code to a name or a type.
60
- ⚠ `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.
 
1
+ # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
+ # the databases a person actually opens, not only the line and document grains.
3
+ #
4
+ # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
+ # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
+ # field row: add the column to the grid contract and re-emit, or the agent is being
7
+ # trained on a schema the product does not have.
8
+ key: odoo_accounts
9
+ label: "Odoo GL accounts"
10
+ entity: account.account
11
+ # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
+ grid: ut_odoo_accounts
13
+ subject: "odoo:account.account"
14
+ grain: "one row per GL account in the chart of accounts"
15
+ scope:
16
+ population: "every account.account record (192 measured)"
17
+ store:
18
+ table: account_account
19
+ alias: a
20
+ # NO date_col β€” a registry is not a dated event stream. Stated rather than
21
+ # omitted, so its absence reads as a fact and not as an unfinished file.
22
+ dims:
23
+ account_type: {label: "Account type"}
24
+
25
+ # key / label / type / kind, derived from the grid contract. `kind` says where the
26
+ # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
27
+ # from another topic; a `link` points at another database.
28
+ fields:
29
+ - key: account_code
30
+ label: "Code"
31
+ type: text
32
+ kind: data
33
+ - key: account_name
34
+ label: "Account"
35
+ type: text
36
+ kind: data
37
+ - key: odoo_id
38
+ label: "Odoo ID"
39
+ type: int
40
+ kind: data
41
+ means: "The `account.account` id. Also this row's id."
42
+ - key: account_type
43
+ label: "Type"
44
+ type: select
45
+ kind: data
46
+ - key: is_expense
47
+ label: "Expense account"
48
+ type: checkbox
49
+ kind: data
50
+ 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."
51
+ - key: refreshed
52
+ label: "Refreshed"
53
+ type: date
54
+ kind: data
55
+ means: "When this row was last reconciled against Odoo."
56
+
57
+ ai_context: >
58
+ The chart of accounts β€” the registry gl_lines posts against.
59
+ Use it to resolve an account code to a name or a type.
60
+ ⚠ `is_expense` is a DERIVED boolean standing in for Odoo's five-value `internal_group` (asset/liability/equity/income/expense), which the mirror does not yet carry.
platform/model/topics/odoo_agents.yml CHANGED
@@ -1,91 +1,91 @@
1
- # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
- # the databases a person actually opens, not only the line and document grains.
3
- #
4
- # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
- # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
- # field row: add the column to the grid contract and re-emit, or the agent is being
7
- # trained on a schema the product does not have.
8
- key: odoo_agents
9
- label: "Odoo agents"
10
- entity: res.partner
11
- # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
- grid: ut_odoo_agents
13
- subject: "odoo:res.partner.agent"
14
- grain: "one row per sales agent"
15
- scope:
16
- population: "a UNION of two disagreeing sources β€” partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
17
- 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"
18
- store:
19
- table: res_partner
20
- alias: p
21
- # NO date_col β€” a registry is not a dated event stream. Stated rather than
22
- # omitted, so its absence reads as a fact and not as an unfinished file.
23
-
24
- # ⭐⭐ W37-T12 / owner item 4 (R1) β€” THE LOOKBACK-MEASURE BINDING, the agent half of
25
- # *"It should apply to Odoo agents database as well."* Same contract as
26
- # `odoo_products.yml`: a FACT topic, and the dim of that topic which carries THIS
27
- # entity's identity.
28
- #
29
- # β›”β›” WHICH AGENT SOURCE, STATED β€” because there are THREE in this Odoo and they name
30
- # DIFFERENT PEOPLE (`proto/P3-metric-catalog.md`: 9 agents carry route-1 revenue, 12
31
- # carry commission lines, 17 carry the flag). This binds ROUTE 1, the CUSTOMER-MASTER
32
- # BOOK: `sales_lines.agent` is `rp.agent_id`, the customer's assigned agent, so every
33
- # order of that customer counts toward their agent. That is "whose book is this" and it
34
- # is the right question for a column on the AGENT REGISTRY.
35
- # ⚠ It is NOT commission. `account.invoice.line.agent` (topic `commission_lines`) is the
36
- # per-INVOICE-LINE credited agent and answers a different question; `sales_lines.yml`'s
37
- # own `agent` dim comment carries the full disagreement and says never to "fix" one by
38
- # reading the other.
39
- #
40
- # ⭐ THE JOIN NEEDS NO NEW DIM, unlike the product side. `sales_lines.agent` declares a
41
- # `name_col`, so `store_query` emits `agent_id` β€” which IS `res.partner.id`, which IS
42
- # this grid's `odoo_id` identity. Product needed `product_code` because its grid keys on
43
- # `default_code`; this one already keys on the same integer the fact topic groups by.
44
- measures:
45
- source: sales_lines
46
- dim: agent
47
- keys: [revenue, units, margin, cogs, margin_pct, asp, customers]
48
- not_yet:
49
- - key: orders / aov
50
- 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"
51
- 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"
52
- - key: commission_amount
53
- 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"
54
- 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"
55
-
56
- # key / label / type / kind, derived from the grid contract. `kind` says where the
57
- # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
58
- # from another topic; a `link` points at another database.
59
- fields:
60
- - key: agent
61
- label: "Agent"
62
- type: text
63
- kind: data
64
- - key: odoo_id
65
- label: "Odoo ID"
66
- type: int
67
- kind: data
68
- means: "The `res.partner` id. Also this row's id."
69
- - key: agent_id
70
- label: "Odoo agent id"
71
- type: int
72
- kind: data
73
- - key: flagged
74
- label: "Flagged in Odoo"
75
- type: checkbox
76
- kind: data
77
- 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."
78
- - key: commissioned
79
- label: "Has commission lines"
80
- type: checkbox
81
- kind: data
82
- - key: refreshed
83
- label: "Refreshed"
84
- type: date
85
- kind: data
86
- means: "When this row was last reconciled against Odoo."
87
-
88
- ai_context: >
89
- The sales-agent registry.
90
- `flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
91
- For an agent's BOOK use sales_lines/commission_lines with the agent dim.
 
1
+ # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
+ # the databases a person actually opens, not only the line and document grains.
3
+ #
4
+ # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
+ # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
+ # field row: add the column to the grid contract and re-emit, or the agent is being
7
+ # trained on a schema the product does not have.
8
+ key: odoo_agents
9
+ label: "Odoo agents"
10
+ entity: res.partner
11
+ # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
+ grid: ut_odoo_agents
13
+ subject: "odoo:res.partner.agent"
14
+ grain: "one row per sales agent"
15
+ scope:
16
+ population: "a UNION of two disagreeing sources β€” partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
17
+ 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"
18
+ store:
19
+ table: res_partner
20
+ alias: p
21
+ # NO date_col β€” a registry is not a dated event stream. Stated rather than
22
+ # omitted, so its absence reads as a fact and not as an unfinished file.
23
+
24
+ # ⭐⭐ W37-T12 / owner item 4 (R1) β€” THE LOOKBACK-MEASURE BINDING, the agent half of
25
+ # *"It should apply to Odoo agents database as well."* Same contract as
26
+ # `odoo_products.yml`: a FACT topic, and the dim of that topic which carries THIS
27
+ # entity's identity.
28
+ #
29
+ # β›”β›” WHICH AGENT SOURCE, STATED β€” because there are THREE in this Odoo and they name
30
+ # DIFFERENT PEOPLE (`proto/P3-metric-catalog.md`: 9 agents carry route-1 revenue, 12
31
+ # carry commission lines, 17 carry the flag). This binds ROUTE 1, the CUSTOMER-MASTER
32
+ # BOOK: `sales_lines.agent` is `rp.agent_id`, the customer's assigned agent, so every
33
+ # order of that customer counts toward their agent. That is "whose book is this" and it
34
+ # is the right question for a column on the AGENT REGISTRY.
35
+ # ⚠ It is NOT commission. `account.invoice.line.agent` (topic `commission_lines`) is the
36
+ # per-INVOICE-LINE credited agent and answers a different question; `sales_lines.yml`'s
37
+ # own `agent` dim comment carries the full disagreement and says never to "fix" one by
38
+ # reading the other.
39
+ #
40
+ # ⭐ THE JOIN NEEDS NO NEW DIM, unlike the product side. `sales_lines.agent` declares a
41
+ # `name_col`, so `store_query` emits `agent_id` β€” which IS `res.partner.id`, which IS
42
+ # this grid's `odoo_id` identity. Product needed `product_code` because its grid keys on
43
+ # `default_code`; this one already keys on the same integer the fact topic groups by.
44
+ measures:
45
+ source: sales_lines
46
+ dim: agent
47
+ keys: [revenue, units, margin, cogs, margin_pct, asp, customers]
48
+ not_yet:
49
+ - key: orders / aov
50
+ 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"
51
+ 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"
52
+ - key: commission_amount
53
+ 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"
54
+ 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"
55
+
56
+ # key / label / type / kind, derived from the grid contract. `kind` says where the
57
+ # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
58
+ # from another topic; a `link` points at another database.
59
+ fields:
60
+ - key: agent
61
+ label: "Agent"
62
+ type: text
63
+ kind: data
64
+ - key: odoo_id
65
+ label: "Odoo ID"
66
+ type: int
67
+ kind: data
68
+ means: "The `res.partner` id. Also this row's id."
69
+ - key: agent_id
70
+ label: "Odoo agent id"
71
+ type: int
72
+ kind: data
73
+ - key: flagged
74
+ label: "Flagged in Odoo"
75
+ type: checkbox
76
+ kind: data
77
+ 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."
78
+ - key: commissioned
79
+ label: "Has commission lines"
80
+ type: checkbox
81
+ kind: data
82
+ - key: refreshed
83
+ label: "Refreshed"
84
+ type: date
85
+ kind: data
86
+ means: "When this row was last reconciled against Odoo."
87
+
88
+ ai_context: >
89
+ The sales-agent registry.
90
+ `flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
91
+ For an agent's BOOK use sales_lines/commission_lines with the agent dim.
platform/model/topics/odoo_bills.yml CHANGED
@@ -1,86 +1,86 @@
1
- # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
- # the databases a person actually opens, not only the line and document grains.
3
- #
4
- # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
- # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
- # field row: add the column to the grid contract and re-emit, or the agent is being
7
- # trained on a schema the product does not have.
8
- key: odoo_bills
9
- label: "Odoo vendor bills"
10
- entity: account.move
11
- # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
- grid: ut_odoo_bills
13
- subject: "odoo:account.move.vendor"
14
- grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
15
- scope:
16
- population: "move_type in (in_invoice, in_refund) AND state = posted"
17
- signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
18
- store:
19
- table: account_move
20
- alias: m
21
- date_col: "m.invoice_date"
22
- dims:
23
- vendor: {label: "Vendor"}
24
- payment_state: {label: "Payment state"}
25
- move_type: {label: "Document type"}
26
-
27
- # key / label / type / kind, derived from the grid contract. `kind` says where the
28
- # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
29
- # from another topic; a `link` points at another database.
30
- fields:
31
- - key: bill_no
32
- label: "Bill"
33
- type: text
34
- kind: data
35
- - key: odoo_id
36
- label: "Odoo ID"
37
- type: int
38
- kind: data
39
- means: "The `account.move` id. Also this row's id."
40
- - key: vendor
41
- label: "Vendor"
42
- type: text
43
- kind: data
44
- - key: vendor_id
45
- label: "Odoo vendor id"
46
- type: int
47
- kind: data
48
- - key: invoice_date
49
- label: "Bill date"
50
- type: date
51
- kind: data
52
- - key: due_date
53
- label: "Due date"
54
- type: date
55
- kind: data
56
- - key: amount_untaxed
57
- label: "Billed $"
58
- type: currency
59
- kind: data
60
- - key: residual
61
- label: "Outstanding $"
62
- type: currency
63
- kind: data
64
- - key: payment_state
65
- label: "Payment state"
66
- type: select
67
- kind: data
68
- - key: move_type
69
- label: "Document"
70
- type: select
71
- kind: data
72
- - key: vendor_link
73
- label: "Vendor record"
74
- type: link
75
- kind: link
76
- to_grid: ut_odoo_vendors
77
- - key: refreshed
78
- label: "Refreshed"
79
- type: date
80
- kind: data
81
- means: "When this row was last reconciled against Odoo."
82
-
83
- ai_context: >
84
- Vendor bills at DOCUMENT grain β€” the payables side of account_move.
85
- Use it for AP questions.
86
- ⚠ 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.
 
1
+ # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
+ # the databases a person actually opens, not only the line and document grains.
3
+ #
4
+ # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
+ # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
+ # field row: add the column to the grid contract and re-emit, or the agent is being
7
+ # trained on a schema the product does not have.
8
+ key: odoo_bills
9
+ label: "Odoo vendor bills"
10
+ entity: account.move
11
+ # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
+ grid: ut_odoo_bills
13
+ subject: "odoo:account.move.vendor"
14
+ grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
15
+ scope:
16
+ population: "move_type in (in_invoice, in_refund) AND state = posted"
17
+ signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
18
+ store:
19
+ table: account_move
20
+ alias: m
21
+ date_col: "m.invoice_date"
22
+ dims:
23
+ vendor: {label: "Vendor"}
24
+ payment_state: {label: "Payment state"}
25
+ move_type: {label: "Document type"}
26
+
27
+ # key / label / type / kind, derived from the grid contract. `kind` says where the
28
+ # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
29
+ # from another topic; a `link` points at another database.
30
+ fields:
31
+ - key: bill_no
32
+ label: "Bill"
33
+ type: text
34
+ kind: data
35
+ - key: odoo_id
36
+ label: "Odoo ID"
37
+ type: int
38
+ kind: data
39
+ means: "The `account.move` id. Also this row's id."
40
+ - key: vendor
41
+ label: "Vendor"
42
+ type: text
43
+ kind: data
44
+ - key: vendor_id
45
+ label: "Odoo vendor id"
46
+ type: int
47
+ kind: data
48
+ - key: invoice_date
49
+ label: "Bill date"
50
+ type: date
51
+ kind: data
52
+ - key: due_date
53
+ label: "Due date"
54
+ type: date
55
+ kind: data
56
+ - key: amount_untaxed
57
+ label: "Billed $"
58
+ type: currency
59
+ kind: data
60
+ - key: residual
61
+ label: "Outstanding $"
62
+ type: currency
63
+ kind: data
64
+ - key: payment_state
65
+ label: "Payment state"
66
+ type: select
67
+ kind: data
68
+ - key: move_type
69
+ label: "Document"
70
+ type: select
71
+ kind: data
72
+ - key: vendor_link
73
+ label: "Vendor record"
74
+ type: link
75
+ kind: link
76
+ to_grid: ut_odoo_vendors
77
+ - key: refreshed
78
+ label: "Refreshed"
79
+ type: date
80
+ kind: data
81
+ means: "When this row was last reconciled against Odoo."
82
+
83
+ ai_context: >
84
+ Vendor bills at DOCUMENT grain β€” the payables side of account_move.
85
+ Use it for AP questions.
86
+ ⚠ The census found `ref` (the VENDOR's own invoice number), `journal_id` and `currency_id` populated in Odoo and absent from the mirror, so they cannot be answered from here yet.
platform/model/topics/odoo_invoices.yml CHANGED
@@ -1,98 +1,98 @@
1
- # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
- # the databases a person actually opens, not only the line and document grains.
3
- #
4
- # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
- # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
- # field row: add the column to the grid contract and re-emit, or the agent is being
7
- # trained on a schema the product does not have.
8
- key: odoo_invoices
9
- label: "Odoo invoices"
10
- entity: account.move
11
- # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
- grid: ut_odoo_invoices
13
- subject: "odoo:account.move.customer"
14
- grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
15
- scope:
16
- population: "move_type in (out_invoice, out_refund) AND state = posted"
17
- signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
18
- store:
19
- table: account_move
20
- alias: m
21
- date_col: "m.invoice_date"
22
- dims:
23
- customer: {label: "Customer"}
24
- payment_state: {label: "Payment state"}
25
- move_type: {label: "Document type"}
26
-
27
- # key / label / type / kind, derived from the grid contract. `kind` says where the
28
- # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
29
- # from another topic; a `link` points at another database.
30
- fields:
31
- - key: invoice_no
32
- label: "Invoice"
33
- type: text
34
- kind: data
35
- - key: odoo_id
36
- label: "Odoo ID"
37
- type: int
38
- kind: data
39
- means: "The `account.move` id. Also this row's id."
40
- - key: customer
41
- label: "Customer"
42
- type: text
43
- kind: data
44
- - key: partner_id
45
- label: "Odoo partner id"
46
- type: int
47
- kind: data
48
- - key: invoice_date
49
- label: "Invoice date"
50
- type: date
51
- kind: data
52
- - key: due_date
53
- label: "Due date"
54
- type: date
55
- kind: data
56
- - key: residual
57
- label: "Outstanding $"
58
- type: currency
59
- kind: data
60
- means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
61
- - key: amount_untaxed
62
- label: "Invoiced $"
63
- type: currency
64
- kind: data
65
- - key: payment_state
66
- label: "Payment state"
67
- type: select
68
- kind: data
69
- - key: move_type
70
- label: "Document"
71
- type: select
72
- kind: data
73
- - key: wholesale_scope
74
- label: "In wholesale scope"
75
- type: checkbox
76
- kind: data
77
- 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."
78
- - key: origin_order
79
- label: "Source order"
80
- type: text
81
- kind: data
82
- means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
83
- - key: order_link
84
- label: "Order record"
85
- type: link
86
- kind: link
87
- to_grid: ut_odoo_orders
88
- - key: refreshed
89
- label: "Refreshed"
90
- type: date
91
- kind: data
92
- means: "When this row was last reconciled against Odoo."
93
-
94
- ai_context: >
95
- Customer invoices at DOCUMENT grain β€” one row per invoice, not per line.
96
- Use it for AR questions: what is open, what is overdue, what was invoiced.
97
- For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
98
- `origin_order` is the single stored key that joins an invoice back to the order it was raised from.
 
1
+ # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
+ # the databases a person actually opens, not only the line and document grains.
3
+ #
4
+ # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
+ # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
+ # field row: add the column to the grid contract and re-emit, or the agent is being
7
+ # trained on a schema the product does not have.
8
+ key: odoo_invoices
9
+ label: "Odoo invoices"
10
+ entity: account.move
11
+ # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
+ grid: ut_odoo_invoices
13
+ subject: "odoo:account.move.customer"
14
+ grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
15
+ scope:
16
+ population: "move_type in (out_invoice, out_refund) AND state = posted"
17
+ signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
18
+ store:
19
+ table: account_move
20
+ alias: m
21
+ date_col: "m.invoice_date"
22
+ dims:
23
+ customer: {label: "Customer"}
24
+ payment_state: {label: "Payment state"}
25
+ move_type: {label: "Document type"}
26
+
27
+ # key / label / type / kind, derived from the grid contract. `kind` says where the
28
+ # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
29
+ # from another topic; a `link` points at another database.
30
+ fields:
31
+ - key: invoice_no
32
+ label: "Invoice"
33
+ type: text
34
+ kind: data
35
+ - key: odoo_id
36
+ label: "Odoo ID"
37
+ type: int
38
+ kind: data
39
+ means: "The `account.move` id. Also this row's id."
40
+ - key: customer
41
+ label: "Customer"
42
+ type: text
43
+ kind: data
44
+ - key: partner_id
45
+ label: "Odoo partner id"
46
+ type: int
47
+ kind: data
48
+ - key: invoice_date
49
+ label: "Invoice date"
50
+ type: date
51
+ kind: data
52
+ - key: due_date
53
+ label: "Due date"
54
+ type: date
55
+ kind: data
56
+ - key: residual
57
+ label: "Outstanding $"
58
+ type: currency
59
+ kind: data
60
+ means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
61
+ - key: amount_untaxed
62
+ label: "Invoiced $"
63
+ type: currency
64
+ kind: data
65
+ - key: payment_state
66
+ label: "Payment state"
67
+ type: select
68
+ kind: data
69
+ - key: move_type
70
+ label: "Document"
71
+ type: select
72
+ kind: data
73
+ - key: wholesale_scope
74
+ label: "In wholesale scope"
75
+ type: checkbox
76
+ kind: data
77
+ 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."
78
+ - key: origin_order
79
+ label: "Source order"
80
+ type: text
81
+ kind: data
82
+ means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
83
+ - key: order_link
84
+ label: "Order record"
85
+ type: link
86
+ kind: link
87
+ to_grid: ut_odoo_orders
88
+ - key: refreshed
89
+ label: "Refreshed"
90
+ type: date
91
+ kind: data
92
+ means: "When this row was last reconciled against Odoo."
93
+
94
+ ai_context: >
95
+ Customer invoices at DOCUMENT grain β€” one row per invoice, not per line.
96
+ Use it for AR questions: what is open, what is overdue, what was invoiced.
97
+ For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
98
+ `origin_order` is the single stored key that joins an invoice back to the order it was raised from.
platform/model/topics/odoo_orders.yml CHANGED
@@ -1,87 +1,87 @@
1
- # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
- # the databases a person actually opens, not only the line and document grains.
3
- #
4
- # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
- # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
- # field row: add the column to the grid contract and re-emit, or the agent is being
7
- # trained on a schema the product does not have.
8
- key: odoo_orders
9
- label: "Odoo orders"
10
- entity: sale.order
11
- # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
- grid: ut_odoo_orders
13
- subject: "odoo:sale.order"
14
- grain: "one row per confirmed sales order (document grain)"
15
- scope:
16
- population: "state in (sale, done) β€” quotations and cancellations excluded"
17
- 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"
18
- store:
19
- table: sale_order
20
- alias: o
21
- date_col: "o.date_order"
22
- dims:
23
- customer: {label: "Customer"}
24
- team: {label: "Business unit"}
25
- state: {label: "State"}
26
- invoice_status: {label: "Invoice status"}
27
-
28
- # key / label / type / kind, derived from the grid contract. `kind` says where the
29
- # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
30
- # from another topic; a `link` points at another database.
31
- fields:
32
- - key: order_no
33
- label: "Order"
34
- type: text
35
- kind: data
36
- - key: odoo_id
37
- label: "Odoo ID"
38
- type: int
39
- kind: data
40
- means: "The `sale.order` id. Also this row's id."
41
- - key: customer
42
- label: "Customer"
43
- type: text
44
- kind: data
45
- - key: partner_id
46
- label: "Odoo partner id"
47
- type: int
48
- kind: data
49
- - key: order_date
50
- label: "Order date"
51
- type: date
52
- kind: data
53
- - key: amount_untaxed
54
- label: "Order $"
55
- type: currency
56
- kind: data
57
- - key: team
58
- label: "Business unit"
59
- type: select
60
- kind: data
61
- - key: state
62
- label: "State"
63
- type: select
64
- kind: data
65
- - key: invoice_status
66
- label: "Invoice status"
67
- type: select
68
- kind: data
69
- - key: wholesale_scope
70
- label: "In wholesale scope"
71
- type: checkbox
72
- kind: data
73
- 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."
74
- - key: invoices
75
- label: "Invoices"
76
- type: link
77
- kind: link
78
- to_grid: ut_odoo_invoices
79
- - key: refreshed
80
- label: "Refreshed"
81
- type: date
82
- kind: data
83
- means: "When this row was last reconciled against Odoo."
84
-
85
- ai_context: >
86
- Sales orders at DOCUMENT grain, as the app's grid shows them.
87
- β›” 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.
 
1
+ # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
+ # the databases a person actually opens, not only the line and document grains.
3
+ #
4
+ # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
+ # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
+ # field row: add the column to the grid contract and re-emit, or the agent is being
7
+ # trained on a schema the product does not have.
8
+ key: odoo_orders
9
+ label: "Odoo orders"
10
+ entity: sale.order
11
+ # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
+ grid: ut_odoo_orders
13
+ subject: "odoo:sale.order"
14
+ grain: "one row per confirmed sales order (document grain)"
15
+ scope:
16
+ population: "state in (sale, done) β€” quotations and cancellations excluded"
17
+ 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"
18
+ store:
19
+ table: sale_order
20
+ alias: o
21
+ date_col: "o.date_order"
22
+ dims:
23
+ customer: {label: "Customer"}
24
+ team: {label: "Business unit"}
25
+ state: {label: "State"}
26
+ invoice_status: {label: "Invoice status"}
27
+
28
+ # key / label / type / kind, derived from the grid contract. `kind` says where the
29
+ # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
30
+ # from another topic; a `link` points at another database.
31
+ fields:
32
+ - key: order_no
33
+ label: "Order"
34
+ type: text
35
+ kind: data
36
+ - key: odoo_id
37
+ label: "Odoo ID"
38
+ type: int
39
+ kind: data
40
+ means: "The `sale.order` id. Also this row's id."
41
+ - key: customer
42
+ label: "Customer"
43
+ type: text
44
+ kind: data
45
+ - key: partner_id
46
+ label: "Odoo partner id"
47
+ type: int
48
+ kind: data
49
+ - key: order_date
50
+ label: "Order date"
51
+ type: date
52
+ kind: data
53
+ - key: amount_untaxed
54
+ label: "Order $"
55
+ type: currency
56
+ kind: data
57
+ - key: team
58
+ label: "Business unit"
59
+ type: select
60
+ kind: data
61
+ - key: state
62
+ label: "State"
63
+ type: select
64
+ kind: data
65
+ - key: invoice_status
66
+ label: "Invoice status"
67
+ type: select
68
+ kind: data
69
+ - key: wholesale_scope
70
+ label: "In wholesale scope"
71
+ type: checkbox
72
+ kind: data
73
+ 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."
74
+ - key: invoices
75
+ label: "Invoices"
76
+ type: link
77
+ kind: link
78
+ to_grid: ut_odoo_invoices
79
+ - key: refreshed
80
+ label: "Refreshed"
81
+ type: date
82
+ kind: data
83
+ means: "When this row was last reconciled against Odoo."
84
+
85
+ ai_context: >
86
+ Sales orders at DOCUMENT grain, as the app's grid shows them.
87
+ β›” 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_vendors.yml CHANGED
@@ -1,103 +1,103 @@
1
- # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
- # the databases a person actually opens, not only the line and document grains.
3
- #
4
- # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
- # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
- # field row: add the column to the grid contract and re-emit, or the agent is being
7
- # trained on a schema the product does not have.
8
- key: odoo_vendors
9
- label: "Odoo vendors"
10
- entity: res.partner
11
- # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
- grid: ut_odoo_vendors
13
- subject: "odoo:res.partner.vendor"
14
- grain: "one row per partner we have posted a vendor bill to"
15
- scope:
16
- population: "DERIVED FROM THE BILLS β€” a partner with no posted vendor bill has no payable history to show, so the bill is the population"
17
- asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
18
- overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
19
- store:
20
- table: res_partner
21
- alias: p
22
- # NO date_col β€” a registry is not a dated event stream. Stated rather than
23
- # omitted, so its absence reads as a fact and not as an unfinished file.
24
- dims:
25
- country: {label: "Country"}
26
-
27
- # key / label / type / kind, derived from the grid contract. `kind` says where the
28
- # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
29
- # from another topic; a `link` points at another database.
30
- fields:
31
- - key: vendor
32
- label: "Vendor"
33
- type: text
34
- kind: data
35
- - key: odoo_id
36
- label: "Odoo ID"
37
- type: int
38
- kind: data
39
- means: "The `res.partner` id. Also this row's id."
40
- - key: vendor_id
41
- label: "Odoo vendor id"
42
- type: int
43
- kind: data
44
- - key: country
45
- label: "Country"
46
- type: text
47
- kind: data
48
- - key: email
49
- label: "Email"
50
- type: text
51
- kind: data
52
- - key: phone
53
- label: "Phone"
54
- type: text
55
- kind: data
56
- - key: mobile
57
- label: "Mobile"
58
- type: text
59
- kind: data
60
- - key: vat
61
- label: "Tax ID"
62
- type: text
63
- kind: data
64
- means: "Odoo `vat` β€” the vendor's tax/VAT registration number."
65
- - key: vendor_ref
66
- label: "Vendor reference"
67
- type: text
68
- kind: data
69
- means: "Odoo `res.partner.ref` β€” our internal reference for this vendor."
70
- - key: website
71
- label: "Website"
72
- type: url
73
- kind: data
74
- - key: street
75
- label: "Street"
76
- type: text
77
- kind: data
78
- - key: street2
79
- label: "Street 2"
80
- type: text
81
- kind: data
82
- - key: city
83
- label: "City"
84
- type: text
85
- kind: data
86
- - key: zip
87
- label: "ZIP"
88
- type: text
89
- kind: data
90
- - key: bills
91
- label: "Bills"
92
- type: link
93
- kind: link
94
- to_grid: ut_odoo_bills
95
- - key: refreshed
96
- label: "Refreshed"
97
- type: date
98
- kind: data
99
- means: "When this row was last reconciled against Odoo."
100
-
101
- ai_context: >
102
- 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)
103
- ⚠ 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.
 
1
+ # ⭐⭐ W33-T49 (owner item 13) β€” an ENTITY topic: the semantic layer can finally see
2
+ # the databases a person actually opens, not only the line and document grains.
3
+ #
4
+ # β›” THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
5
+ # and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
6
+ # field row: add the column to the grid contract and re-emit, or the agent is being
7
+ # trained on a schema the product does not have.
8
+ key: odoo_vendors
9
+ label: "Odoo vendors"
10
+ entity: res.partner
11
+ # The database this topic DESCRIBES β€” the same store key the nav opens (W33-T46).
12
+ grid: ut_odoo_vendors
13
+ subject: "odoo:res.partner.vendor"
14
+ grain: "one row per partner we have posted a vendor bill to"
15
+ scope:
16
+ population: "DERIVED FROM THE BILLS β€” a partner with no posted vendor bill has no payable history to show, so the bill is the population"
17
+ asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
18
+ overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
19
+ store:
20
+ table: res_partner
21
+ alias: p
22
+ # NO date_col β€” a registry is not a dated event stream. Stated rather than
23
+ # omitted, so its absence reads as a fact and not as an unfinished file.
24
+ dims:
25
+ country: {label: "Country"}
26
+
27
+ # key / label / type / kind, derived from the grid contract. `kind` says where the
28
+ # value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
29
+ # from another topic; a `link` points at another database.
30
+ fields:
31
+ - key: vendor
32
+ label: "Vendor"
33
+ type: text
34
+ kind: data
35
+ - key: odoo_id
36
+ label: "Odoo ID"
37
+ type: int
38
+ kind: data
39
+ means: "The `res.partner` id. Also this row's id."
40
+ - key: vendor_id
41
+ label: "Odoo vendor id"
42
+ type: int
43
+ kind: data
44
+ - key: country
45
+ label: "Country"
46
+ type: text
47
+ kind: data
48
+ - key: email
49
+ label: "Email"
50
+ type: text
51
+ kind: data
52
+ - key: phone
53
+ label: "Phone"
54
+ type: text
55
+ kind: data
56
+ - key: mobile
57
+ label: "Mobile"
58
+ type: text
59
+ kind: data
60
+ - key: vat
61
+ label: "Tax ID"
62
+ type: text
63
+ kind: data
64
+ means: "Odoo `vat` β€” the vendor's tax/VAT registration number."
65
+ - key: vendor_ref
66
+ label: "Vendor reference"
67
+ type: text
68
+ kind: data
69
+ means: "Odoo `res.partner.ref` β€” our internal reference for this vendor."
70
+ - key: website
71
+ label: "Website"
72
+ type: url
73
+ kind: data
74
+ - key: street
75
+ label: "Street"
76
+ type: text
77
+ kind: data
78
+ - key: street2
79
+ label: "Street 2"
80
+ type: text
81
+ kind: data
82
+ - key: city
83
+ label: "City"
84
+ type: text
85
+ kind: data
86
+ - key: zip
87
+ label: "ZIP"
88
+ type: text
89
+ kind: data
90
+ - key: bills
91
+ label: "Bills"
92
+ type: link
93
+ kind: link
94
+ to_grid: ut_odoo_bills
95
+ - key: refreshed
96
+ label: "Refreshed"
97
+ type: date
98
+ kind: data
99
+ means: "When this row was last reconciled against Odoo."
100
+
101
+ ai_context: >
102
+ 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)
103
+ ⚠ The contact columns are SPARSE by nature β€” measured 65/393 with an email, 13/393 with a tax id β€” so 'blank' means Odoo has no value, never that the sync failed.
platform/modules/agent.py CHANGED
@@ -1,385 +1,385 @@
1
- """Agent module β€” per-agent (res.partner.agent_ids) analytics.
2
-
3
- An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
4
- module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
5
- with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
6
- trend, returns, top SKUs (with profit/order) and the FULL customer list β€” INCLUDING inactive
7
- accounts (no recent orders) so a rep sees who they've stopped selling to.
8
-
9
- Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
10
- so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
11
- everything else is BU-filterable via team_id.
12
- """
13
- import sys
14
- import datetime as dt
15
- from pathlib import Path
16
- sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
17
- import core.odoo as O
18
- import core.periods as P
19
- import modules.sales as sales_mod
20
- import modules.customers as cust_mod
21
-
22
-
23
- def options(t=None, team_id=None):
24
- """Agent names with book activity β€” for the page/drawer picker."""
25
- return cust_mod.agent_options(t, team_id)
26
-
27
-
28
- def _book(name):
29
- """frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
30
- return cust_mod.agent_partner_ids(name)
31
-
32
-
33
- def _rev(date_from, date_to, team_id, book):
34
- return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
35
- 'amount_untaxed')
36
-
37
-
38
- def _orders(date_from, date_to, team_id, book):
39
- return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
40
-
41
-
42
- def _custs(date_from, date_to, team_id, book):
43
- return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
44
- 'partner_id')
45
-
46
-
47
- # ------------------------------------------------------------ period scorecard (custom dating)
48
- # Today / WTD / Last week / MTD / QTD / YTD β€” each carries its window so the UI can decompose it
49
- # and so "what did this agent sell this/last week" is a click, not a date-math exercise.
50
- _PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
51
- ('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
52
-
53
-
54
- def _window(key, t):
55
- if key == 'today':
56
- return P._d(t), P._d(t)
57
- if key == 'lwk': # the full prior Mon–Sun week
58
- f, _tt = P.wtd(t)
59
- start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
60
- return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
61
- return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
62
-
63
-
64
- def scorecard(name, t=None, team_id=None):
65
- """Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
66
- t = t or P.today()
67
- book = _book(name)
68
- out = []
69
- for label, key in _PERIODS:
70
- f, tt = _window(key, t)
71
- wk = key in ('today', 'wtd', 'lwk') # weekday-align the short windows' LY compare
72
- cf, ct = P.shift_year(f, tt, weeks=wk)
73
- rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
74
- out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
75
- 'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
76
- 'orders': _orders(f, tt, team_id, book)})
77
- return out
78
-
79
-
80
- def headline(name, date_from, date_to, team_id=None):
81
- """Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
82
- active customers, AOV and returns $ / return rate."""
83
- book = _book(name)
84
- cf, ct = P.shift_year(date_from, date_to, weeks=False)
85
- rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
86
- orders = _orders(date_from, date_to, team_id, book)
87
- ret = sales_mod._returns_amt(date_from, date_to, book)
88
- return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
89
- 'revenue': rev, 'revenue_ly': rev_ly,
90
- 'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
91
- 'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
92
- 'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
93
-
94
-
95
- # ------------------------------------------------------------ sales trend
96
- def _book_monthly_rev(book, date_from, date_to, team_id=None):
97
- g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
98
- ['amount_untaxed:sum'], ['date_order:month'], lazy=False)
99
- out = {}
100
- for r in g:
101
- ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
102
- if ym:
103
- out[ym] = r.get('amount_untaxed') or 0.0
104
- return out
105
-
106
-
107
- def monthly(name, n=13, t=None, team_id=None):
108
- """Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
109
- t = t or P.today()
110
- book = _book(name)
111
- mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
112
- rows = []
113
- for ym, _s, _e in P.month_starts(n, t):
114
- y, m = int(ym[:4]) - 1, int(ym[5:7])
115
- this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
116
- rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
117
- return rows
118
-
119
-
120
- # ------------------------------------------------------------ full customer book (incl. inactive)
121
- def customers(name, t=None, team_id=None):
122
- """EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) β€” those
123
- show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
124
- carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
125
- t = t or P.today()
126
- book = _book(name)
127
- yf, yt = P.ytd(t)
128
- lf, lt = P.ytd_last_year(t)
129
- this = cust_mod._cust_rev(yf, yt, team_id, book)
130
- last = cust_mod._cust_rev(lf, lt, team_id, book)
131
- lastord = cust_mod._last_order_dates(None, None, team_id, book) # all-time last order = recency
132
- ids = list(book) if book is not None else list(set(this) | set(last))
133
- attrs = cust_mod._partner_attrs(set(ids))
134
- namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
135
- rows = []
136
- for p in ids:
137
- tr = this.get(p, {}).get('rev', 0.0)
138
- lr = last.get(p, {}).get('rev', 0.0)
139
- a = attrs.get(p, {})
140
- lo = lastord.get(p, '')
141
- recency = (t - dt.date.fromisoformat(lo)).days if lo else None
142
- status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
143
- rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
144
- 'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
145
- 'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
146
- 'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
147
- 'agent': a.get('agent', name)})
148
- rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
149
- return rows
150
-
151
-
152
- # ------------------------------------------------------------ top SKUs (with profit/order)
153
- def top_skus(name, t=None, team_id=None, top=30):
154
- """The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
155
- t = t or P.today()
156
- book = _book(name)
157
- if book is not None and not book:
158
- return []
159
- yf, yt = P.ytd(t)
160
- lex = [('order_partner_id', 'in', list(book))] if book is not None else None
161
- return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
162
-
163
-
164
- # ------------------------------------------------------------ returns (book-scoped, consolidated)
165
- def returns_trend(name, n=13, t=None):
166
- return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
167
-
168
-
169
- def returns_headline(name, t=None):
170
- return sales_mod.returns_headline(t, partner_ids=_book(name))
171
-
172
-
173
- # ------------------------------------------------------------ all-agents rollup (the page table)
174
- def _returns_by_agent(t=None):
175
- """{agent_name: returns$ YTD} β€” credit notes mapped to each customer's agent."""
176
- by_p = sales_mod.returns_by_partner(t)
177
- attrs = cust_mod._partner_attrs(list(by_p))
178
- agg = {}
179
- for pid, amt in by_p.items():
180
- a = (attrs.get(pid) or {}).get('agent') or '(none)'
181
- agg[a] = agg.get(a, 0.0) + amt
182
- return agg
183
-
184
-
185
- def rollup(t=None, team_id=None):
186
- """Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
187
- rate. Reuses the Customers MECE agent rollup, so Ξ£(agents) == total YTD revenue."""
188
- rows = cust_mod.by_dimension('agent', t, team_id=team_id)
189
- ret = _returns_by_agent(t)
190
- for r in rows:
191
- r['agent'] = r['group']
192
- r['returns'] = ret.get(r['group'], 0.0)
193
- r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
194
- return rows
195
-
196
-
197
- # ------------------------------------------------------------ VALIDATION
198
- def validate(t=None, team_id=None):
199
- """Reconcile the agent rollup to Odoo. (1) Ξ£(agent book revenue) == total YTD revenue β€” the
200
- rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
201
- t = t or P.today()
202
- yf, yt = P.ytd(t)
203
- checks = []
204
- rows = rollup(t, team_id=team_id)
205
- agent_sum = sum(r['revenue'] for r in rows)
206
- total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
207
- checks.append({'check': 'YTD revenue: Ξ£(agent book) == total', 'a': round(agent_sum, 2),
208
- 'b': round(total, 2), 'gap': round(agent_sum - total, 2),
209
- 'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
210
- # sampled agent: scorecard YTD == headline YTD for the same window
211
- sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
212
- if sample:
213
- sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
214
- hl = headline(sample, yf, yt, team_id)['revenue']
215
- checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
216
- 'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
217
- checks.extend(validate_measures(t=t, team_id=team_id))
218
- return checks
219
-
220
-
221
- def validate_measures(t=None, team_id=None, days=90):
222
- """⭐⭐ W37-T12 β€” the minted PER-AGENT lookback columns, against a DIRECT Odoo aggregate.
223
-
224
- β›” WHICH AGENT SOURCE, AND THE TICKET REQUIRES IT SAID OUT LOUD: this reconciles ROUTE 1, the
225
- CUSTOMER-MASTER BOOK (`res.partner.agent_ids` -> the mirror's `res_partner.agent_id`, which is
226
- `sales_lines`' `agent` dim). It is NOT the OCA commission route below β€” measured 2026-08-19,
227
- 9 agents carry route-1 revenue against 12 on commission lines and 17 carrying the flag, so the
228
- two produce materially different rankings and a check that mixed them would be comparing two
229
- different questions and calling the gap an error.
230
-
231
- ⚠ THE ORACLE IS THE ORDER HEADER, not the mirror the columns are served from. `sale.order`
232
- grouped by `partner_id`, mapped to each customer's agent CLIENT-SIDE β€” a different model, a
233
- different grain and a different code path from `store_query`'s line-level sum, so agreement
234
- between them is evidence rather than tautology.
235
- ⚠ Windowed to the MIRROR'S newest order, like `product_data.validate_measures`, so the
236
- residual is about EDITS to a shared period and not about orders the mirror has never seen.
237
- """
238
- from harness import datastore as DS
239
- from harness import semantic as sem
240
-
241
- t = t or P.today()
242
- checks = []
243
- try:
244
- if not DS.ready():
245
- return [{'check': 'agent lookback measures reconcile to Odoo', 'a': 'no mirror',
246
- 'b': '-', 'ok': False,
247
- 'detail': 'the tenant store is not readable, so this is UNPROVEN, which standing rule '
248
- '8 does not accept as green'}]
249
- except Exception as e: # noqa: BLE001
250
- return [{'check': 'agent lookback measures reconcile to Odoo', 'a': type(e).__name__,
251
- 'b': '-', 'ok': False, 'detail': str(e)[:200]}]
252
-
253
- offer = sem.entity_measures('odoo_agents')
254
- checks.append({'check': 'the agent measure OFFER is non-empty and every key resolves '
255
- '(owner item 4 / R1)',
256
- 'a': len(offer), 'b': '>0', 'ok': bool(offer),
257
- 'detail': {'keys': [m['key'] for m in offer],
258
- 'refused': sem.entity_measure_refusals('odoo_agents')}})
259
- if not offer:
260
- return checks
261
-
262
- con = DS.ro_cursor()
263
- try:
264
- newest = con.execute('SELECT max(date_order) FROM sale_order').fetchone()
265
- finally:
266
- con.close()
267
- d_to = t - dt.timedelta(days=2)
268
- if newest and newest[0]:
269
- try:
270
- d_to = min(d_to, dt.date.fromisoformat(str(newest[0])[:10]) - dt.timedelta(days=1))
271
- except ValueError:
272
- pass
273
- d_from = d_to - dt.timedelta(days=days)
274
- DF, DT = d_from.isoformat(), d_to.isoformat()
275
-
276
- ours = sem.entity_measure_values('odoo_agents', ['revenue'], date_from=DF, date_to=DT,
277
- team_id=team_id, offer=offer)
278
- # THE ORACLE β€” order headers, grouped by customer, mapped to that customer's agent here.
279
- o = O.get_odoo()
280
- grp = o.read_group('sale.order', sales_mod.order_domain(DF, DT, team_id),
281
- ['partner_id', 'amount_untaxed:sum'], ['partner_id'], lazy=False)
282
- pids = sorted({r['partner_id'][0] for r in grp if r.get('partner_id')})
283
- agent_of = {}
284
- for i in range(0, len(pids), 500):
285
- for p in o.search_read('res.partner', [('id', 'in', pids[i:i + 500])],
286
- ['id', 'agent_ids']):
287
- ag = (p.get('agent_ids') or [])
288
- if ag:
289
- agent_of[p['id']] = ag[0] # the Customers-module convention: agent_ids[0]
290
- theirs = {}
291
- for r in grp:
292
- if not r.get('partner_id'):
293
- continue
294
- a = agent_of.get(r['partner_id'][0])
295
- if a is not None:
296
- theirs[a] = theirs.get(a, 0.0) + r['amount_untaxed']
297
-
298
- ours_tot = round(sum(c.get('revenue', 0) for c in ours.values()), 2)
299
- theirs_tot = round(sum(theirs.values()), 2)
300
- # ⚠ ORDER-HEADER vs LINE-SUM is a REAL basis difference (an order's untaxed total includes
301
- # lines this topic's service filter drops), so the tolerance is a stated 3% rather than a
302
- # cent β€” and the FIGURE is reported so a drift is readable instead of absorbed.
303
- gap = ours_tot - theirs_tot
304
- checks.append({
305
- 'check': 'per-agent revenue (BOOK route) vs an INDEPENDENT Odoo order-header aggregate '
306
- 'mapped through res.partner.agent_ids',
307
- 'a': ours_tot, 'b': theirs_tot, 'gap': round(gap, 2),
308
- 'ok': bool(theirs_tot) and abs(gap) <= 0.03 * theirs_tot,
309
- 'detail': {'window': [DF, DT], 'agents_ours': len(ours), 'agents_theirs': len(theirs),
310
- 'gap_pct': round(gap / theirs_tot * 100, 3) if theirs_tot else None,
311
- 'route': 'customer-master book (res.partner.agent_ids), NOT the OCA '
312
- 'commission table; the two name different people'}})
313
- # β›” AND PER AGENT, because a total can agree while every row is keyed wrong β€” the join-key
314
- # trap contract C1 names. Here the key is the `res.partner` id at both ends.
315
- off_by = sorted(((abs(ours.get(a, {}).get('revenue', 0.0) - v), a)
316
- for a, v in theirs.items() if v), reverse=True)
317
- bad = [(a, round(ours.get(a, {}).get('revenue', 0.0), 2), round(theirs[a], 2))
318
- for d, a in off_by if d > 0.03 * theirs[a]]
319
- checks.append({
320
- 'check': 'each agent\'s own figure ties (the C1 join-key test: a wrong key agrees in '
321
- 'total and disagrees on every row)',
322
- 'a': len(bad), 'b': 0, 'ok': not bad,
323
- 'detail': {'worst': [(a, ours_v, th_v) for a, ours_v, th_v in bad[:5]],
324
- 'agents_compared': len(theirs)}})
325
- return checks
326
-
327
-
328
- # ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
329
- # A SECOND agent source. Everything above this line attributes by BOOK β€” the customer's assigned
330
- # agent (res.partner.agent_ids) β€” over confirmed SALES ORDERS. This section attributes per INVOICE
331
- # LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
332
- # commission_lines). The two disagree on purpose and answer different questions:
333
- #
334
- # book -> "whose customer is this / who owns the relationship" (order basis)
335
- # invoice -> "what was actually credited to an agent on the billing" + the ONLY source that can
336
- # say what is NOT allocated to an agent (invoice basis)
337
- #
338
- # ⚠ A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT β€” `res.partner.agent` is the flag.
339
- # "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
340
- # dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
341
- # See [[invoice-line-agent-commission]].
342
-
343
- _ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
344
- 'none': 'Not allocated'}
345
-
346
-
347
- def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
348
- """Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
349
-
350
- Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
351
- 'unallocated': float, 'basis': str} β€” or {'error': msg} when the tenant store is not
352
- ready (this path is store-only; there is no live fallback that stays honest about the
353
- unallocated bucket).
354
- """
355
- import harness.semantic as S
356
- t = t or P.today()
357
- yf, yt = P.ytd(t)
358
- dim = 'commission_name' if include_salespeople else 'agent'
359
- try:
360
- by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
361
- date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
362
- alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
363
- date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
364
- tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
365
- team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
366
- except Exception as e: # store not ready / model error β€” say so, don't fake
367
- return {'error': str(e)}
368
- # store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
369
- # (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
370
- # returns None for every row and silently renders the whole table as "no agent".
371
- rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
372
- 'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
373
- rows.sort(key=lambda r: -r['revenue'])
374
- amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
375
- allocated = amap.get('agent', 0.0)
376
- return {
377
- 'by_agent': rows,
378
- 'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
379
- for k in ('agent', 'salesperson', 'none') if k in amap or True],
380
- 'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
381
- 'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
382
- 'window': (yf, yt),
383
- 'basis': ('invoice line Β· commission names incl. salespeople' if include_salespeople
384
- else 'invoice line Β· real agents only'),
385
- }
 
1
+ """Agent module β€” per-agent (res.partner.agent_ids) analytics.
2
+
3
+ An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
4
+ module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
5
+ with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
6
+ trend, returns, top SKUs (with profit/order) and the FULL customer list β€” INCLUDING inactive
7
+ accounts (no recent orders) so a rep sees who they've stopped selling to.
8
+
9
+ Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
10
+ so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
11
+ everything else is BU-filterable via team_id.
12
+ """
13
+ import sys
14
+ import datetime as dt
15
+ from pathlib import Path
16
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
17
+ import core.odoo as O
18
+ import core.periods as P
19
+ import modules.sales as sales_mod
20
+ import modules.customers as cust_mod
21
+
22
+
23
+ def options(t=None, team_id=None):
24
+ """Agent names with book activity β€” for the page/drawer picker."""
25
+ return cust_mod.agent_options(t, team_id)
26
+
27
+
28
+ def _book(name):
29
+ """frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
30
+ return cust_mod.agent_partner_ids(name)
31
+
32
+
33
+ def _rev(date_from, date_to, team_id, book):
34
+ return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
35
+ 'amount_untaxed')
36
+
37
+
38
+ def _orders(date_from, date_to, team_id, book):
39
+ return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
40
+
41
+
42
+ def _custs(date_from, date_to, team_id, book):
43
+ return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
44
+ 'partner_id')
45
+
46
+
47
+ # ------------------------------------------------------------ period scorecard (custom dating)
48
+ # Today / WTD / Last week / MTD / QTD / YTD β€” each carries its window so the UI can decompose it
49
+ # and so "what did this agent sell this/last week" is a click, not a date-math exercise.
50
+ _PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
51
+ ('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
52
+
53
+
54
+ def _window(key, t):
55
+ if key == 'today':
56
+ return P._d(t), P._d(t)
57
+ if key == 'lwk': # the full prior Mon–Sun week
58
+ f, _tt = P.wtd(t)
59
+ start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
60
+ return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
61
+ return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
62
+
63
+
64
+ def scorecard(name, t=None, team_id=None):
65
+ """Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
66
+ t = t or P.today()
67
+ book = _book(name)
68
+ out = []
69
+ for label, key in _PERIODS:
70
+ f, tt = _window(key, t)
71
+ wk = key in ('today', 'wtd', 'lwk') # weekday-align the short windows' LY compare
72
+ cf, ct = P.shift_year(f, tt, weeks=wk)
73
+ rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
74
+ out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
75
+ 'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
76
+ 'orders': _orders(f, tt, team_id, book)})
77
+ return out
78
+
79
+
80
+ def headline(name, date_from, date_to, team_id=None):
81
+ """Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
82
+ active customers, AOV and returns $ / return rate."""
83
+ book = _book(name)
84
+ cf, ct = P.shift_year(date_from, date_to, weeks=False)
85
+ rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
86
+ orders = _orders(date_from, date_to, team_id, book)
87
+ ret = sales_mod._returns_amt(date_from, date_to, book)
88
+ return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
89
+ 'revenue': rev, 'revenue_ly': rev_ly,
90
+ 'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
91
+ 'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
92
+ 'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
93
+
94
+
95
+ # ------------------------------------------------------------ sales trend
96
+ def _book_monthly_rev(book, date_from, date_to, team_id=None):
97
+ g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
98
+ ['amount_untaxed:sum'], ['date_order:month'], lazy=False)
99
+ out = {}
100
+ for r in g:
101
+ ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
102
+ if ym:
103
+ out[ym] = r.get('amount_untaxed') or 0.0
104
+ return out
105
+
106
+
107
+ def monthly(name, n=13, t=None, team_id=None):
108
+ """Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
109
+ t = t or P.today()
110
+ book = _book(name)
111
+ mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
112
+ rows = []
113
+ for ym, _s, _e in P.month_starts(n, t):
114
+ y, m = int(ym[:4]) - 1, int(ym[5:7])
115
+ this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
116
+ rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
117
+ return rows
118
+
119
+
120
+ # ------------------------------------------------------------ full customer book (incl. inactive)
121
+ def customers(name, t=None, team_id=None):
122
+ """EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) β€” those
123
+ show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
124
+ carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
125
+ t = t or P.today()
126
+ book = _book(name)
127
+ yf, yt = P.ytd(t)
128
+ lf, lt = P.ytd_last_year(t)
129
+ this = cust_mod._cust_rev(yf, yt, team_id, book)
130
+ last = cust_mod._cust_rev(lf, lt, team_id, book)
131
+ lastord = cust_mod._last_order_dates(None, None, team_id, book) # all-time last order = recency
132
+ ids = list(book) if book is not None else list(set(this) | set(last))
133
+ attrs = cust_mod._partner_attrs(set(ids))
134
+ namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
135
+ rows = []
136
+ for p in ids:
137
+ tr = this.get(p, {}).get('rev', 0.0)
138
+ lr = last.get(p, {}).get('rev', 0.0)
139
+ a = attrs.get(p, {})
140
+ lo = lastord.get(p, '')
141
+ recency = (t - dt.date.fromisoformat(lo)).days if lo else None
142
+ status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
143
+ rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
144
+ 'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
145
+ 'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
146
+ 'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
147
+ 'agent': a.get('agent', name)})
148
+ rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
149
+ return rows
150
+
151
+
152
+ # ------------------------------------------------------------ top SKUs (with profit/order)
153
+ def top_skus(name, t=None, team_id=None, top=30):
154
+ """The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
155
+ t = t or P.today()
156
+ book = _book(name)
157
+ if book is not None and not book:
158
+ return []
159
+ yf, yt = P.ytd(t)
160
+ lex = [('order_partner_id', 'in', list(book))] if book is not None else None
161
+ return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
162
+
163
+
164
+ # ------------------------------------------------------------ returns (book-scoped, consolidated)
165
+ def returns_trend(name, n=13, t=None):
166
+ return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
167
+
168
+
169
+ def returns_headline(name, t=None):
170
+ return sales_mod.returns_headline(t, partner_ids=_book(name))
171
+
172
+
173
+ # ------------------------------------------------------------ all-agents rollup (the page table)
174
+ def _returns_by_agent(t=None):
175
+ """{agent_name: returns$ YTD} β€” credit notes mapped to each customer's agent."""
176
+ by_p = sales_mod.returns_by_partner(t)
177
+ attrs = cust_mod._partner_attrs(list(by_p))
178
+ agg = {}
179
+ for pid, amt in by_p.items():
180
+ a = (attrs.get(pid) or {}).get('agent') or '(none)'
181
+ agg[a] = agg.get(a, 0.0) + amt
182
+ return agg
183
+
184
+
185
+ def rollup(t=None, team_id=None):
186
+ """Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
187
+ rate. Reuses the Customers MECE agent rollup, so Ξ£(agents) == total YTD revenue."""
188
+ rows = cust_mod.by_dimension('agent', t, team_id=team_id)
189
+ ret = _returns_by_agent(t)
190
+ for r in rows:
191
+ r['agent'] = r['group']
192
+ r['returns'] = ret.get(r['group'], 0.0)
193
+ r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
194
+ return rows
195
+
196
+
197
+ # ------------------------------------------------------------ VALIDATION
198
+ def validate(t=None, team_id=None):
199
+ """Reconcile the agent rollup to Odoo. (1) Ξ£(agent book revenue) == total YTD revenue β€” the
200
+ rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
201
+ t = t or P.today()
202
+ yf, yt = P.ytd(t)
203
+ checks = []
204
+ rows = rollup(t, team_id=team_id)
205
+ agent_sum = sum(r['revenue'] for r in rows)
206
+ total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
207
+ checks.append({'check': 'YTD revenue: Ξ£(agent book) == total', 'a': round(agent_sum, 2),
208
+ 'b': round(total, 2), 'gap': round(agent_sum - total, 2),
209
+ 'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
210
+ # sampled agent: scorecard YTD == headline YTD for the same window
211
+ sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
212
+ if sample:
213
+ sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
214
+ hl = headline(sample, yf, yt, team_id)['revenue']
215
+ checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
216
+ 'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
217
+ checks.extend(validate_measures(t=t, team_id=team_id))
218
+ return checks
219
+
220
+
221
+ def validate_measures(t=None, team_id=None, days=90):
222
+ """⭐⭐ W37-T12 β€” the minted PER-AGENT lookback columns, against a DIRECT Odoo aggregate.
223
+
224
+ β›” WHICH AGENT SOURCE, AND THE TICKET REQUIRES IT SAID OUT LOUD: this reconciles ROUTE 1, the
225
+ CUSTOMER-MASTER BOOK (`res.partner.agent_ids` -> the mirror's `res_partner.agent_id`, which is
226
+ `sales_lines`' `agent` dim). It is NOT the OCA commission route below β€” measured 2026-08-19,
227
+ 9 agents carry route-1 revenue against 12 on commission lines and 17 carrying the flag, so the
228
+ two produce materially different rankings and a check that mixed them would be comparing two
229
+ different questions and calling the gap an error.
230
+
231
+ ⚠ THE ORACLE IS THE ORDER HEADER, not the mirror the columns are served from. `sale.order`
232
+ grouped by `partner_id`, mapped to each customer's agent CLIENT-SIDE β€” a different model, a
233
+ different grain and a different code path from `store_query`'s line-level sum, so agreement
234
+ between them is evidence rather than tautology.
235
+ ⚠ Windowed to the MIRROR'S newest order, like `product_data.validate_measures`, so the
236
+ residual is about EDITS to a shared period and not about orders the mirror has never seen.
237
+ """
238
+ from harness import datastore as DS
239
+ from harness import semantic as sem
240
+
241
+ t = t or P.today()
242
+ checks = []
243
+ try:
244
+ if not DS.ready():
245
+ return [{'check': 'agent lookback measures reconcile to Odoo', 'a': 'no mirror',
246
+ 'b': '-', 'ok': False,
247
+ 'detail': 'the tenant store is not readable, so this is UNPROVEN, which standing rule '
248
+ '8 does not accept as green'}]
249
+ except Exception as e: # noqa: BLE001
250
+ return [{'check': 'agent lookback measures reconcile to Odoo', 'a': type(e).__name__,
251
+ 'b': '-', 'ok': False, 'detail': str(e)[:200]}]
252
+
253
+ offer = sem.entity_measures('odoo_agents')
254
+ checks.append({'check': 'the agent measure OFFER is non-empty and every key resolves '
255
+ '(owner item 4 / R1)',
256
+ 'a': len(offer), 'b': '>0', 'ok': bool(offer),
257
+ 'detail': {'keys': [m['key'] for m in offer],
258
+ 'refused': sem.entity_measure_refusals('odoo_agents')}})
259
+ if not offer:
260
+ return checks
261
+
262
+ con = DS.ro_cursor()
263
+ try:
264
+ newest = con.execute('SELECT max(date_order) FROM sale_order').fetchone()
265
+ finally:
266
+ con.close()
267
+ d_to = t - dt.timedelta(days=2)
268
+ if newest and newest[0]:
269
+ try:
270
+ d_to = min(d_to, dt.date.fromisoformat(str(newest[0])[:10]) - dt.timedelta(days=1))
271
+ except ValueError:
272
+ pass
273
+ d_from = d_to - dt.timedelta(days=days)
274
+ DF, DT = d_from.isoformat(), d_to.isoformat()
275
+
276
+ ours = sem.entity_measure_values('odoo_agents', ['revenue'], date_from=DF, date_to=DT,
277
+ team_id=team_id, offer=offer)
278
+ # THE ORACLE β€” order headers, grouped by customer, mapped to that customer's agent here.
279
+ o = O.get_odoo()
280
+ grp = o.read_group('sale.order', sales_mod.order_domain(DF, DT, team_id),
281
+ ['partner_id', 'amount_untaxed:sum'], ['partner_id'], lazy=False)
282
+ pids = sorted({r['partner_id'][0] for r in grp if r.get('partner_id')})
283
+ agent_of = {}
284
+ for i in range(0, len(pids), 500):
285
+ for p in o.search_read('res.partner', [('id', 'in', pids[i:i + 500])],
286
+ ['id', 'agent_ids']):
287
+ ag = (p.get('agent_ids') or [])
288
+ if ag:
289
+ agent_of[p['id']] = ag[0] # the Customers-module convention: agent_ids[0]
290
+ theirs = {}
291
+ for r in grp:
292
+ if not r.get('partner_id'):
293
+ continue
294
+ a = agent_of.get(r['partner_id'][0])
295
+ if a is not None:
296
+ theirs[a] = theirs.get(a, 0.0) + r['amount_untaxed']
297
+
298
+ ours_tot = round(sum(c.get('revenue', 0) for c in ours.values()), 2)
299
+ theirs_tot = round(sum(theirs.values()), 2)
300
+ # ⚠ ORDER-HEADER vs LINE-SUM is a REAL basis difference (an order's untaxed total includes
301
+ # lines this topic's service filter drops), so the tolerance is a stated 3% rather than a
302
+ # cent β€” and the FIGURE is reported so a drift is readable instead of absorbed.
303
+ gap = ours_tot - theirs_tot
304
+ checks.append({
305
+ 'check': 'per-agent revenue (BOOK route) vs an INDEPENDENT Odoo order-header aggregate '
306
+ 'mapped through res.partner.agent_ids',
307
+ 'a': ours_tot, 'b': theirs_tot, 'gap': round(gap, 2),
308
+ 'ok': bool(theirs_tot) and abs(gap) <= 0.03 * theirs_tot,
309
+ 'detail': {'window': [DF, DT], 'agents_ours': len(ours), 'agents_theirs': len(theirs),
310
+ 'gap_pct': round(gap / theirs_tot * 100, 3) if theirs_tot else None,
311
+ 'route': 'customer-master book (res.partner.agent_ids), NOT the OCA '
312
+ 'commission table; the two name different people'}})
313
+ # β›” AND PER AGENT, because a total can agree while every row is keyed wrong β€” the join-key
314
+ # trap contract C1 names. Here the key is the `res.partner` id at both ends.
315
+ off_by = sorted(((abs(ours.get(a, {}).get('revenue', 0.0) - v), a)
316
+ for a, v in theirs.items() if v), reverse=True)
317
+ bad = [(a, round(ours.get(a, {}).get('revenue', 0.0), 2), round(theirs[a], 2))
318
+ for d, a in off_by if d > 0.03 * theirs[a]]
319
+ checks.append({
320
+ 'check': 'each agent\'s own figure ties (the C1 join-key test: a wrong key agrees in '
321
+ 'total and disagrees on every row)',
322
+ 'a': len(bad), 'b': 0, 'ok': not bad,
323
+ 'detail': {'worst': [(a, ours_v, th_v) for a, ours_v, th_v in bad[:5]],
324
+ 'agents_compared': len(theirs)}})
325
+ return checks
326
+
327
+
328
+ # ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
329
+ # A SECOND agent source. Everything above this line attributes by BOOK β€” the customer's assigned
330
+ # agent (res.partner.agent_ids) β€” over confirmed SALES ORDERS. This section attributes per INVOICE
331
+ # LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
332
+ # commission_lines). The two disagree on purpose and answer different questions:
333
+ #
334
+ # book -> "whose customer is this / who owns the relationship" (order basis)
335
+ # invoice -> "what was actually credited to an agent on the billing" + the ONLY source that can
336
+ # say what is NOT allocated to an agent (invoice basis)
337
+ #
338
+ # ⚠ A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT β€” `res.partner.agent` is the flag.
339
+ # "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
340
+ # dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
341
+ # See [[invoice-line-agent-commission]].
342
+
343
+ _ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
344
+ 'none': 'Not allocated'}
345
+
346
+
347
+ def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
348
+ """Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
349
+
350
+ Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
351
+ 'unallocated': float, 'basis': str} β€” or {'error': msg} when the tenant store is not
352
+ ready (this path is store-only; there is no live fallback that stays honest about the
353
+ unallocated bucket).
354
+ """
355
+ import harness.semantic as S
356
+ t = t or P.today()
357
+ yf, yt = P.ytd(t)
358
+ dim = 'commission_name' if include_salespeople else 'agent'
359
+ try:
360
+ by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
361
+ date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
362
+ alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
363
+ date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
364
+ tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
365
+ team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
366
+ except Exception as e: # store not ready / model error β€” say so, don't fake
367
+ return {'error': str(e)}
368
+ # store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
369
+ # (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
370
+ # returns None for every row and silently renders the whole table as "no agent".
371
+ rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
372
+ 'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
373
+ rows.sort(key=lambda r: -r['revenue'])
374
+ amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
375
+ allocated = amap.get('agent', 0.0)
376
+ return {
377
+ 'by_agent': rows,
378
+ 'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
379
+ for k in ('agent', 'salesperson', 'none') if k in amap or True],
380
+ 'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
381
+ 'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
382
+ 'window': (yf, yt),
383
+ 'basis': ('invoice line Β· commission names incl. salespeople' if include_salespeople
384
+ else 'invoice line Β· real agents only'),
385
+ }
platform/modules/collections_send.py CHANGED
@@ -1,267 +1,267 @@
1
- """Collections statements β€” the send layer behind the Collections page's Statements section.
2
-
3
- Folded in from the standalone collections_app (2026-07-05). THE one sanctioned exception to the
4
- app's read-only-on-Odoo rule, unchanged from the standalone tool: WRITE is whitelisted to exactly
5
- one operation β€”
6
-
7
- create on mail.mail (queueing an outbound statement email)
8
-
9
- A mail.mail record with state='outgoing' is picked up by Odoo's "Mail: Email Queue Manager" cron
10
- (every ~15 min) and delivered through the company's Office 365 relay. Because we set model/res_id,
11
- each sent statement also appears in the customer's chatter in Odoo β€” the audit log lives where AR
12
- already works. This module has its OWN narrow XML-RPC client; the app-wide odoo_client stays
13
- hard-blocking on all writes. The UI gates the section to admin users; SAFE_MODE is enforced HERE
14
- in the data layer so the UI cannot bypass it.
15
-
16
- Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
17
- Optional: SAFE_MODE (default ON), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
18
- COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
19
- """
20
- import os
21
- import datetime as dt
22
- import xmlrpc.client
23
- from pathlib import Path
24
-
25
- try: # self-contained: load credentials from the app root .env if present (HF uses Secrets)
26
- from dotenv import load_dotenv
27
- load_dotenv(Path(__file__).resolve().parents[1] / '.env')
28
- except Exception:
29
- pass
30
-
31
- WRITE_WHITELIST = {('mail.mail', 'create')}
32
-
33
- EXCLUDE_NAMES = {'GIFTWARE DEALS'} # the Amazon channel β€” not part of Fisch or Royal collections
34
- DOMAIN = [('followup_reminder_type', '=', 'automatic'), ('credit', '>', 1)]
35
-
36
- COMPANY = os.environ.get('COMPANY_NAME', 'Royal Imports')
37
-
38
- # --- Sender identity (statements go out AS Royal Imports) ---
39
- # Odoo routes outbound mail to the matching ir.mail_server by from_filter, and the Office 365
40
- # relay only accepts sends as its authenticated address. The "Office 365 - Royal" server (id 2)
41
- # authenticates as contact@royalimports.com with from_filter='contact@royalimports.com' β€” so the
42
- # From MUST be that address for delivery to succeed. Friendly display name; replies routed to AR.
43
- SENDER_NAME = os.environ.get('SENDER_NAME', 'Royal Imports Accounts Receivable')
44
- SENDER_EMAIL = os.environ.get('SENDER_EMAIL', 'contact@royalimports.com')
45
- REPLY_TO = os.environ.get('REPLY_TO', 'accounting@royalimports.com')
46
- ROYAL_MAIL_SERVER_ID = int(os.environ.get('ROYAL_MAIL_SERVER_ID', '2'))
47
- ROYAL_AUTHOR_ID = int(os.environ.get('ROYAL_AUTHOR_ID', '8978')) # "Royal Imports" partner
48
-
49
- SENDER_DISPLAY = f'"{SENDER_NAME}" <{SENDER_EMAIL}>'
50
-
51
-
52
- class WriteBlocked(RuntimeError):
53
- pass
54
-
55
-
56
- class SafeModeBlocked(RuntimeError):
57
- pass
58
-
59
-
60
- # --- Testing guardrail -------------------------------------------------------
61
- # While SAFE_MODE is on, NO email can be queued to any address outside the allow-list β€” enforced
62
- # here in the data layer so the UI cannot bypass it. Default: ON. To go live for real customers,
63
- # set the Space secret SAFE_MODE=0.
64
- SAFE_MODE = os.environ.get('SAFE_MODE', '1').strip().lower() not in ('0', 'false', 'no', '')
65
- SAFE_RECIPIENTS = {a.strip().lower() for a in
66
- os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
67
- if a.strip()}
68
-
69
-
70
- def safe_recipient_ok(addr):
71
- return (not SAFE_MODE) or (str(addr or '').strip().lower() in SAFE_RECIPIENTS)
72
-
73
-
74
- class Odoo:
75
- """Narrow client: read anything, write ONLY the whitelisted mail.mail create."""
76
-
77
- def __init__(self):
78
- self.url = os.environ.get('ODOO_URL', '').rstrip('/')
79
- self.db = os.environ.get('ODOO_DB', '')
80
- self.user = os.environ.get('ODOO_USER', '')
81
- self.key = os.environ.get('ODOO_API_KEY', '')
82
- missing = [k for k, v in [('ODOO_URL', self.url), ('ODOO_DB', self.db),
83
- ('ODOO_USER', self.user), ('ODOO_API_KEY', self.key)] if not v]
84
- if missing:
85
- raise RuntimeError(f"Missing secrets: {', '.join(missing)}")
86
- common = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/common')
87
- self.uid = common.authenticate(self.db, self.user, self.key, {})
88
- if not self.uid:
89
- raise RuntimeError('Odoo authentication failed')
90
- self.models = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/object')
91
-
92
- def _exec(self, model, method, args, kwargs=None):
93
- mutating = method in ('write', 'create', 'unlink', 'copy') or \
94
- any(method.startswith(p) for p in ('action_', 'button_', 'do_', 'send_',
95
- 'set_', 'update_', 'process_'))
96
- if mutating and (model, method) not in WRITE_WHITELIST:
97
- raise WriteBlocked(f'{method} on {model} is not allowed from this app')
98
- return self.models.execute_kw(self.db, self.uid, self.key,
99
- model, method, args, kwargs or {})
100
-
101
- def search_read(self, model, domain=None, fields=None, limit=None, order=None):
102
- kw = {'fields': fields or []}
103
- if limit is not None:
104
- kw['limit'] = limit
105
- if order:
106
- kw['order'] = order
107
- return self._exec(model, 'search_read', [domain or []], kw)
108
-
109
- def queue_mail(self, payload):
110
- """The single allowed write: queue an outbound email."""
111
- return self._exec('mail.mail', 'create', [payload])
112
-
113
-
114
- # --------------------------------------------------------------- data builders
115
- def load_collection_list(odoo):
116
- """The saved follow-up filter (Reminders=Automatic, Receivable>$1), GIFTWARE excluded,
117
- with priority tiers."""
118
- partners = odoo.search_read('res.partner', DOMAIN,
119
- ['name', 'credit', 'total_overdue', 'followup_status',
120
- 'followup_next_action_date', 'followup_responsible_id',
121
- 'email', 'phone', 'mobile'])
122
- partners = [p for p in partners if (p['name'] or '').strip().upper() not in EXCLUDE_NAMES]
123
- pids = [p['id'] for p in partners]
124
-
125
- docs = odoo.search_read('account.move',
126
- [('move_type', 'in', ['out_invoice', 'out_refund']), ('state', '=', 'posted'),
127
- ('payment_state', 'in', ['not_paid', 'partial']), ('partner_id', 'in', pids)],
128
- ['name', 'partner_id', 'move_type', 'invoice_date', 'invoice_date_due',
129
- 'amount_total', 'amount_residual_signed'])
130
-
131
- today = dt.date.today()
132
- by_partner = {}
133
- for d in docs:
134
- pid = d['partner_id'][0]
135
- due = d.get('invoice_date_due')
136
- try:
137
- days = (today - dt.date.fromisoformat(due)).days if due else 0
138
- except Exception:
139
- days = 0
140
- d['days_overdue'] = max(days, 0)
141
- d['open_signed'] = d['amount_residual_signed']
142
- by_partner.setdefault(pid, []).append(d)
143
-
144
- rows = []
145
- for p in partners:
146
- pid = p['id']
147
- odoo_overdue = float(p.get('total_overdue') or 0)
148
- docs_p = sorted(by_partner.get(pid, []), key=lambda x: x.get('invoice_date_due') or '')
149
- inv_overdue = sum(d['open_signed'] for d in docs_p if d['days_overdue'] > 0)
150
- oldest = max((d['days_overdue'] for d in docs_p), default=0)
151
- gap = inv_overdue - odoo_overdue
152
- reconcile = abs(gap) > 50
153
-
154
- if odoo_overdue >= 5000 or (odoo_overdue > 0 and oldest > 90):
155
- tier = 'A-Urgent'
156
- elif odoo_overdue >= 1000 or (odoo_overdue > 0 and oldest > 30):
157
- tier = 'B-Active'
158
- elif odoo_overdue > 0:
159
- tier = 'C-Light'
160
- else:
161
- tier = 'Monitor'
162
-
163
- rows.append({
164
- 'partner_id': pid,
165
- 'Customer': p['name'],
166
- 'Tier': tier,
167
- 'Overdue': odoo_overdue,
168
- 'Receivable': float(p.get('credit') or 0),
169
- 'Oldest (days)': oldest,
170
- 'Open Docs': len(docs_p),
171
- 'Email': p.get('email') or '',
172
- 'Phone': p.get('phone') or p.get('mobile') or '',
173
- 'Status': (p.get('followup_status') or '').replace('_', ' '),
174
- 'Reconcile?': 'YES' if reconcile else '',
175
- '_docs': docs_p,
176
- })
177
- tier_rank = {'A-Urgent': 0, 'B-Active': 1, 'C-Light': 2, 'Monitor': 3}
178
- rows.sort(key=lambda r: (tier_rank[r['Tier']], -r['Overdue']))
179
- return rows
180
-
181
-
182
- # --------------------------------------------------------------- statement email
183
- # β›” STANDING RULE 2, AND THIS IS THE ONE STRING IN THE PRODUCT THAT LEAVES THE BUILDING.
184
- # Every other finding `web_prose` reports is copy on a screen somebody here opens; this is the
185
- # SUBJECT LINE of mail queued to a real debtor, over the single sanctioned Odoo write. It read
186
- # 'Statement of Account (em dash) {company} (em dash) {month}' until W36-T42.
187
- DEFAULT_SUBJECT = 'Statement of Account from {company}, {month}'
188
- DEFAULT_INTRO = (
189
- 'Dear {customer},<br><br>'
190
- 'Please find below your current statement of account with {company}. '
191
- 'According to our records, the following invoices remain open:'
192
- )
193
- DEFAULT_FOOTER = (
194
- 'If you have already sent payment, please disregard this notice, and thank you. '
195
- 'For any questions about an invoice, simply reply to this email.<br><br>'
196
- 'Thank you for your business,<br>{company}<br>Accounts Receivable'
197
- )
198
-
199
-
200
- def render_statement_html(row, intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER):
201
- month = dt.date.today().strftime('%B %Y')
202
- intro = intro_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
203
- footer = footer_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
204
-
205
- lines = []
206
- total_open = 0.0
207
- for d in row['_docs']:
208
- kind = 'Credit Note' if d['move_type'] == 'out_refund' else 'Invoice'
209
- amt = d['open_signed']
210
- total_open += amt
211
- overdue_txt = f"{d['days_overdue']}d overdue" if d['days_overdue'] > 0 else 'current'
212
- color = '#C0392B' if d['days_overdue'] > 0 else '#1F4E78'
213
- lines.append(
214
- f"<tr><td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d['name']} <span style='color:#888'>({kind})</span></td>"
215
- f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date') or ''}</td>"
216
- f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date_due') or ''}</td>"
217
- f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;color:{color}'>{overdue_txt}</td>"
218
- f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;text-align:right'>${amt:,.2f}</td></tr>")
219
-
220
- table = (
221
- "<table style='border-collapse:collapse;font-size:14px;margin:14px 0'>"
222
- "<tr style='background:#1F4E78;color:#fff'>"
223
- "<th style='padding:7px 10px;text-align:left'>Document</th>"
224
- "<th style='padding:7px 10px;text-align:left'>Date</th>"
225
- "<th style='padding:7px 10px;text-align:left'>Due</th>"
226
- "<th style='padding:7px 10px;text-align:left'>Status</th>"
227
- "<th style='padding:7px 10px;text-align:right'>Open Balance</th></tr>"
228
- + ''.join(lines) +
229
- f"<tr><td colspan='4' style='padding:8px 10px;font-weight:bold;text-align:right'>Total open</td>"
230
- f"<td style='padding:8px 10px;font-weight:bold;text-align:right'>${total_open:,.2f}</td></tr>"
231
- f"<tr><td colspan='4' style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>Of which overdue</td>"
232
- f"<td style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>${row['Overdue']:,.2f}</td></tr>"
233
- "</table>")
234
-
235
- return (f"<div style='font-family:Calibri,Arial,sans-serif;color:#1a1a1a;font-size:14px'>"
236
- f"{intro}{table}{footer}</div>")
237
-
238
-
239
- def queue_statement(odoo, row, subject_tpl=DEFAULT_SUBJECT,
240
- intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER,
241
- override_to=None):
242
- """Queue one statement email in Odoo. Returns mail.mail id.
243
- override_to: send to a different address (used by the test-send button)."""
244
- to = override_to or row['Email']
245
- if not to:
246
- raise ValueError(f"{row['Customer']} has no email address")
247
- # Hard guardrail β€” refuse any recipient outside the allow-list while SAFE_MODE is on.
248
- if not safe_recipient_ok(to):
249
- raise SafeModeBlocked(
250
- f"Guardrail ON: refusing to email {to}. Only {', '.join(sorted(SAFE_RECIPIENTS))} "
251
- f"is allowed right now. (Set SAFE_MODE=0 to send to real customers.)")
252
- month = dt.date.today().strftime('%B %Y')
253
- subject = subject_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
254
- payload = {
255
- 'subject': subject,
256
- 'body_html': render_statement_html(row, intro_tpl, footer_tpl),
257
- 'email_to': to,
258
- 'email_from': SENDER_DISPLAY, # From: Royal Imports
259
- 'reply_to': REPLY_TO, # replies -> AR
260
- 'mail_server_id': ROYAL_MAIL_SERVER_ID, # force Royal O365 relay
261
- 'author_id': ROYAL_AUTHOR_ID, # clean attribution in chatter
262
- 'state': 'outgoing',
263
- 'auto_delete': False,
264
- 'model': 'res.partner',
265
- 'res_id': row['partner_id'],
266
- }
267
- return odoo.queue_mail(payload)
 
1
+ """Collections statements β€” the send layer behind the Collections page's Statements section.
2
+
3
+ Folded in from the standalone collections_app (2026-07-05). THE one sanctioned exception to the
4
+ app's read-only-on-Odoo rule, unchanged from the standalone tool: WRITE is whitelisted to exactly
5
+ one operation β€”
6
+
7
+ create on mail.mail (queueing an outbound statement email)
8
+
9
+ A mail.mail record with state='outgoing' is picked up by Odoo's "Mail: Email Queue Manager" cron
10
+ (every ~15 min) and delivered through the company's Office 365 relay. Because we set model/res_id,
11
+ each sent statement also appears in the customer's chatter in Odoo β€” the audit log lives where AR
12
+ already works. This module has its OWN narrow XML-RPC client; the app-wide odoo_client stays
13
+ hard-blocking on all writes. The UI gates the section to admin users; SAFE_MODE is enforced HERE
14
+ in the data layer so the UI cannot bypass it.
15
+
16
+ Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
17
+ Optional: SAFE_MODE (default ON), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
18
+ COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
19
+ """
20
+ import os
21
+ import datetime as dt
22
+ import xmlrpc.client
23
+ from pathlib import Path
24
+
25
+ try: # self-contained: load credentials from the app root .env if present (HF uses Secrets)
26
+ from dotenv import load_dotenv
27
+ load_dotenv(Path(__file__).resolve().parents[1] / '.env')
28
+ except Exception:
29
+ pass
30
+
31
+ WRITE_WHITELIST = {('mail.mail', 'create')}
32
+
33
+ EXCLUDE_NAMES = {'GIFTWARE DEALS'} # the Amazon channel β€” not part of Fisch or Royal collections
34
+ DOMAIN = [('followup_reminder_type', '=', 'automatic'), ('credit', '>', 1)]
35
+
36
+ COMPANY = os.environ.get('COMPANY_NAME', 'Royal Imports')
37
+
38
+ # --- Sender identity (statements go out AS Royal Imports) ---
39
+ # Odoo routes outbound mail to the matching ir.mail_server by from_filter, and the Office 365
40
+ # relay only accepts sends as its authenticated address. The "Office 365 - Royal" server (id 2)
41
+ # authenticates as contact@royalimports.com with from_filter='contact@royalimports.com' β€” so the
42
+ # From MUST be that address for delivery to succeed. Friendly display name; replies routed to AR.
43
+ SENDER_NAME = os.environ.get('SENDER_NAME', 'Royal Imports Accounts Receivable')
44
+ SENDER_EMAIL = os.environ.get('SENDER_EMAIL', 'contact@royalimports.com')
45
+ REPLY_TO = os.environ.get('REPLY_TO', 'accounting@royalimports.com')
46
+ ROYAL_MAIL_SERVER_ID = int(os.environ.get('ROYAL_MAIL_SERVER_ID', '2'))
47
+ ROYAL_AUTHOR_ID = int(os.environ.get('ROYAL_AUTHOR_ID', '8978')) # "Royal Imports" partner
48
+
49
+ SENDER_DISPLAY = f'"{SENDER_NAME}" <{SENDER_EMAIL}>'
50
+
51
+
52
+ class WriteBlocked(RuntimeError):
53
+ pass
54
+
55
+
56
+ class SafeModeBlocked(RuntimeError):
57
+ pass
58
+
59
+
60
+ # --- Testing guardrail -------------------------------------------------------
61
+ # While SAFE_MODE is on, NO email can be queued to any address outside the allow-list β€” enforced
62
+ # here in the data layer so the UI cannot bypass it. Default: ON. To go live for real customers,
63
+ # set the Space secret SAFE_MODE=0.
64
+ SAFE_MODE = os.environ.get('SAFE_MODE', '1').strip().lower() not in ('0', 'false', 'no', '')
65
+ SAFE_RECIPIENTS = {a.strip().lower() for a in
66
+ os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
67
+ if a.strip()}
68
+
69
+
70
+ def safe_recipient_ok(addr):
71
+ return (not SAFE_MODE) or (str(addr or '').strip().lower() in SAFE_RECIPIENTS)
72
+
73
+
74
+ class Odoo:
75
+ """Narrow client: read anything, write ONLY the whitelisted mail.mail create."""
76
+
77
+ def __init__(self):
78
+ self.url = os.environ.get('ODOO_URL', '').rstrip('/')
79
+ self.db = os.environ.get('ODOO_DB', '')
80
+ self.user = os.environ.get('ODOO_USER', '')
81
+ self.key = os.environ.get('ODOO_API_KEY', '')
82
+ missing = [k for k, v in [('ODOO_URL', self.url), ('ODOO_DB', self.db),
83
+ ('ODOO_USER', self.user), ('ODOO_API_KEY', self.key)] if not v]
84
+ if missing:
85
+ raise RuntimeError(f"Missing secrets: {', '.join(missing)}")
86
+ common = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/common')
87
+ self.uid = common.authenticate(self.db, self.user, self.key, {})
88
+ if not self.uid:
89
+ raise RuntimeError('Odoo authentication failed')
90
+ self.models = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/object')
91
+
92
+ def _exec(self, model, method, args, kwargs=None):
93
+ mutating = method in ('write', 'create', 'unlink', 'copy') or \
94
+ any(method.startswith(p) for p in ('action_', 'button_', 'do_', 'send_',
95
+ 'set_', 'update_', 'process_'))
96
+ if mutating and (model, method) not in WRITE_WHITELIST:
97
+ raise WriteBlocked(f'{method} on {model} is not allowed from this app')
98
+ return self.models.execute_kw(self.db, self.uid, self.key,
99
+ model, method, args, kwargs or {})
100
+
101
+ def search_read(self, model, domain=None, fields=None, limit=None, order=None):
102
+ kw = {'fields': fields or []}
103
+ if limit is not None:
104
+ kw['limit'] = limit
105
+ if order:
106
+ kw['order'] = order
107
+ return self._exec(model, 'search_read', [domain or []], kw)
108
+
109
+ def queue_mail(self, payload):
110
+ """The single allowed write: queue an outbound email."""
111
+ return self._exec('mail.mail', 'create', [payload])
112
+
113
+
114
+ # --------------------------------------------------------------- data builders
115
+ def load_collection_list(odoo):
116
+ """The saved follow-up filter (Reminders=Automatic, Receivable>$1), GIFTWARE excluded,
117
+ with priority tiers."""
118
+ partners = odoo.search_read('res.partner', DOMAIN,
119
+ ['name', 'credit', 'total_overdue', 'followup_status',
120
+ 'followup_next_action_date', 'followup_responsible_id',
121
+ 'email', 'phone', 'mobile'])
122
+ partners = [p for p in partners if (p['name'] or '').strip().upper() not in EXCLUDE_NAMES]
123
+ pids = [p['id'] for p in partners]
124
+
125
+ docs = odoo.search_read('account.move',
126
+ [('move_type', 'in', ['out_invoice', 'out_refund']), ('state', '=', 'posted'),
127
+ ('payment_state', 'in', ['not_paid', 'partial']), ('partner_id', 'in', pids)],
128
+ ['name', 'partner_id', 'move_type', 'invoice_date', 'invoice_date_due',
129
+ 'amount_total', 'amount_residual_signed'])
130
+
131
+ today = dt.date.today()
132
+ by_partner = {}
133
+ for d in docs:
134
+ pid = d['partner_id'][0]
135
+ due = d.get('invoice_date_due')
136
+ try:
137
+ days = (today - dt.date.fromisoformat(due)).days if due else 0
138
+ except Exception:
139
+ days = 0
140
+ d['days_overdue'] = max(days, 0)
141
+ d['open_signed'] = d['amount_residual_signed']
142
+ by_partner.setdefault(pid, []).append(d)
143
+
144
+ rows = []
145
+ for p in partners:
146
+ pid = p['id']
147
+ odoo_overdue = float(p.get('total_overdue') or 0)
148
+ docs_p = sorted(by_partner.get(pid, []), key=lambda x: x.get('invoice_date_due') or '')
149
+ inv_overdue = sum(d['open_signed'] for d in docs_p if d['days_overdue'] > 0)
150
+ oldest = max((d['days_overdue'] for d in docs_p), default=0)
151
+ gap = inv_overdue - odoo_overdue
152
+ reconcile = abs(gap) > 50
153
+
154
+ if odoo_overdue >= 5000 or (odoo_overdue > 0 and oldest > 90):
155
+ tier = 'A-Urgent'
156
+ elif odoo_overdue >= 1000 or (odoo_overdue > 0 and oldest > 30):
157
+ tier = 'B-Active'
158
+ elif odoo_overdue > 0:
159
+ tier = 'C-Light'
160
+ else:
161
+ tier = 'Monitor'
162
+
163
+ rows.append({
164
+ 'partner_id': pid,
165
+ 'Customer': p['name'],
166
+ 'Tier': tier,
167
+ 'Overdue': odoo_overdue,
168
+ 'Receivable': float(p.get('credit') or 0),
169
+ 'Oldest (days)': oldest,
170
+ 'Open Docs': len(docs_p),
171
+ 'Email': p.get('email') or '',
172
+ 'Phone': p.get('phone') or p.get('mobile') or '',
173
+ 'Status': (p.get('followup_status') or '').replace('_', ' '),
174
+ 'Reconcile?': 'YES' if reconcile else '',
175
+ '_docs': docs_p,
176
+ })
177
+ tier_rank = {'A-Urgent': 0, 'B-Active': 1, 'C-Light': 2, 'Monitor': 3}
178
+ rows.sort(key=lambda r: (tier_rank[r['Tier']], -r['Overdue']))
179
+ return rows
180
+
181
+
182
+ # --------------------------------------------------------------- statement email
183
+ # β›” STANDING RULE 2, AND THIS IS THE ONE STRING IN THE PRODUCT THAT LEAVES THE BUILDING.
184
+ # Every other finding `web_prose` reports is copy on a screen somebody here opens; this is the
185
+ # SUBJECT LINE of mail queued to a real debtor, over the single sanctioned Odoo write. It read
186
+ # 'Statement of Account (em dash) {company} (em dash) {month}' until W36-T42.
187
+ DEFAULT_SUBJECT = 'Statement of Account from {company}, {month}'
188
+ DEFAULT_INTRO = (
189
+ 'Dear {customer},<br><br>'
190
+ 'Please find below your current statement of account with {company}. '
191
+ 'According to our records, the following invoices remain open:'
192
+ )
193
+ DEFAULT_FOOTER = (
194
+ 'If you have already sent payment, please disregard this notice, and thank you. '
195
+ 'For any questions about an invoice, simply reply to this email.<br><br>'
196
+ 'Thank you for your business,<br>{company}<br>Accounts Receivable'
197
+ )
198
+
199
+
200
+ def render_statement_html(row, intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER):
201
+ month = dt.date.today().strftime('%B %Y')
202
+ intro = intro_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
203
+ footer = footer_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
204
+
205
+ lines = []
206
+ total_open = 0.0
207
+ for d in row['_docs']:
208
+ kind = 'Credit Note' if d['move_type'] == 'out_refund' else 'Invoice'
209
+ amt = d['open_signed']
210
+ total_open += amt
211
+ overdue_txt = f"{d['days_overdue']}d overdue" if d['days_overdue'] > 0 else 'current'
212
+ color = '#C0392B' if d['days_overdue'] > 0 else '#1F4E78'
213
+ lines.append(
214
+ f"<tr><td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d['name']} <span style='color:#888'>({kind})</span></td>"
215
+ f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date') or ''}</td>"
216
+ f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date_due') or ''}</td>"
217
+ f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;color:{color}'>{overdue_txt}</td>"
218
+ f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;text-align:right'>${amt:,.2f}</td></tr>")
219
+
220
+ table = (
221
+ "<table style='border-collapse:collapse;font-size:14px;margin:14px 0'>"
222
+ "<tr style='background:#1F4E78;color:#fff'>"
223
+ "<th style='padding:7px 10px;text-align:left'>Document</th>"
224
+ "<th style='padding:7px 10px;text-align:left'>Date</th>"
225
+ "<th style='padding:7px 10px;text-align:left'>Due</th>"
226
+ "<th style='padding:7px 10px;text-align:left'>Status</th>"
227
+ "<th style='padding:7px 10px;text-align:right'>Open Balance</th></tr>"
228
+ + ''.join(lines) +
229
+ f"<tr><td colspan='4' style='padding:8px 10px;font-weight:bold;text-align:right'>Total open</td>"
230
+ f"<td style='padding:8px 10px;font-weight:bold;text-align:right'>${total_open:,.2f}</td></tr>"
231
+ f"<tr><td colspan='4' style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>Of which overdue</td>"
232
+ f"<td style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>${row['Overdue']:,.2f}</td></tr>"
233
+ "</table>")
234
+
235
+ return (f"<div style='font-family:Calibri,Arial,sans-serif;color:#1a1a1a;font-size:14px'>"
236
+ f"{intro}{table}{footer}</div>")
237
+
238
+
239
+ def queue_statement(odoo, row, subject_tpl=DEFAULT_SUBJECT,
240
+ intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER,
241
+ override_to=None):
242
+ """Queue one statement email in Odoo. Returns mail.mail id.
243
+ override_to: send to a different address (used by the test-send button)."""
244
+ to = override_to or row['Email']
245
+ if not to:
246
+ raise ValueError(f"{row['Customer']} has no email address")
247
+ # Hard guardrail β€” refuse any recipient outside the allow-list while SAFE_MODE is on.
248
+ if not safe_recipient_ok(to):
249
+ raise SafeModeBlocked(
250
+ f"Guardrail ON: refusing to email {to}. Only {', '.join(sorted(SAFE_RECIPIENTS))} "
251
+ f"is allowed right now. (Set SAFE_MODE=0 to send to real customers.)")
252
+ month = dt.date.today().strftime('%B %Y')
253
+ subject = subject_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
254
+ payload = {
255
+ 'subject': subject,
256
+ 'body_html': render_statement_html(row, intro_tpl, footer_tpl),
257
+ 'email_to': to,
258
+ 'email_from': SENDER_DISPLAY, # From: Royal Imports
259
+ 'reply_to': REPLY_TO, # replies -> AR
260
+ 'mail_server_id': ROYAL_MAIL_SERVER_ID, # force Royal O365 relay
261
+ 'author_id': ROYAL_AUTHOR_ID, # clean attribution in chatter
262
+ 'state': 'outgoing',
263
+ 'auto_delete': False,
264
+ 'model': 'res.partner',
265
+ 'res_id': row['partner_id'],
266
+ }
267
+ return odoo.queue_mail(payload)
requirements.txt CHANGED
@@ -1,55 +1,55 @@
1
- # AIOS web API β€” the FastAPI backend + the platform data-layer deps it reuses.
2
- #
3
- # β›” STREAMLIT IS GONE (EXIT-6, 2026-08-04) β€” do not add it back. The line here read
4
- # `streamlit==1.58.0` with the comment "included only because the shared modules/core may import
5
- # it at load; it is never served". That stopped being true when the shared layer was cleaned, and
6
- # it stayed in THIS file β€” the one the Dockerfile actually installs β€” while `api/requirements.txt`
7
- # had already dropped it and a gate reported the omission "verified". ~250 MB of image for a
8
- # package nothing imported.
9
- #
10
- # The lesson is the file, not the package: the PINNED intent and the SHIPPED manifest are two
11
- # different documents, and checking only the one you wrote is how the other rots.
12
- # `api/verify_no_streamlit.py` now checks BOTH, and proves the API imports with streamlit,
13
- # plotly, altair, openpyxl, reportlab and jinja2 all blocked at sys.meta_path.
14
- # No altair/plotly/reportlab either β€” those were Streamlit UI/export only. openpyxl RETURNED in
15
- # wave 21 (C5) as a LAZY dep of routes_uploads.py β€” the boot proof above still holds because the
16
- # import lives inside the handler, and the gate now asserts this line exists here.
17
- fastapi>=0.139
18
- uvicorn[standard]>=0.30
19
- python-dotenv>=1.0
20
- pandas>=2.0
21
- requests>=2.28
22
- huggingface_hub>=0.20
23
- duckdb>=1.0
24
- pyyaml>=6.0
25
- pillow>=10.0
26
- beautifulsoup4>=4.12
27
- lxml>=5.0
28
- cryptography>=42.0
29
- # ⭐ WAVE 20 (R1 / D-4) β€” THE POSTGRES DRIVER, AND IT IS LOAD-BEARING IN THIS FILE SPECIFICALLY.
30
- # `core/store_pg.py` is the store backend from this wave on, and it is deliberately FAIL-CLOSED:
31
- # `_pool()` raises rather than falling back to the HF file store, so a container that gets
32
- # `STORE_BACKEND=pg` without this line does not degrade β€” it refuses every request that touches
33
- # the store, which is every authenticated request.
34
- #
35
- # β›” AND THIS IS THE FILE THAT MATTERS: the Dockerfile does `COPY requirements.txt` from the
36
- # Space root, i.e. THIS manifest, not `api/requirements.txt`. That header's own streamlit story
37
- # is the same defect in the other direction β€” the pinned intent and the shipped manifest are two
38
- # documents. psycopg is now in BOTH, and `ops/verify_portability.py` gates the pair.
39
- psycopg[binary,pool]>=3.2
40
- # ⭐ WAVE 21 (item 11, C5) β€” .xlsx preview for Select-from-file; lazy-imported in
41
- # routes_uploads.py only. verify_no_streamlit asserts this line in BOTH manifests.
42
- openpyxl>=3.1
43
- # β›” AND ITS TRANSPORT, learned from a RUNTIME_ERROR on the first v6 boot: FastAPI demands
44
- # python-multipart AT IMPORT TIME for any route declaring File(...)/Form(...). Every local gate
45
- # was green because the dev box happens to have it for unrelated reasons β€” the container
46
- # installs exactly this file. The environment-parity twin of the streamlit lesson above.
47
- python-multipart>=0.0.20
48
- # ⭐ WAVE 37 (D-346, answering `ASK E-1`) β€” THE OFFICIAL ANTHROPIC SDK. `ai_review.py` called the
49
- # Messages API over raw `requests`, which meant re-implementing retries, streaming and error
50
- # taxonomy by hand and drifting from them silently. E ships the SDK behind a LAZY import with the
51
- # raw-HTTP call still there as the fallback, so the feature works with or without this line β€” what
52
- # the line does is turn the fallback into dead weight instead of the live path.
53
- # ⚠ BOTH MANIFESTS, NOT ONE. This file's own streamlit story at the top is exactly what pinning
54
- # one of them looks like a year later.
55
- anthropic>=0.96
 
1
+ # AIOS web API β€” the FastAPI backend + the platform data-layer deps it reuses.
2
+ #
3
+ # β›” STREAMLIT IS GONE (EXIT-6, 2026-08-04) β€” do not add it back. The line here read
4
+ # `streamlit==1.58.0` with the comment "included only because the shared modules/core may import
5
+ # it at load; it is never served". That stopped being true when the shared layer was cleaned, and
6
+ # it stayed in THIS file β€” the one the Dockerfile actually installs β€” while `api/requirements.txt`
7
+ # had already dropped it and a gate reported the omission "verified". ~250 MB of image for a
8
+ # package nothing imported.
9
+ #
10
+ # The lesson is the file, not the package: the PINNED intent and the SHIPPED manifest are two
11
+ # different documents, and checking only the one you wrote is how the other rots.
12
+ # `api/verify_no_streamlit.py` now checks BOTH, and proves the API imports with streamlit,
13
+ # plotly, altair, openpyxl, reportlab and jinja2 all blocked at sys.meta_path.
14
+ # No altair/plotly/reportlab either β€” those were Streamlit UI/export only. openpyxl RETURNED in
15
+ # wave 21 (C5) as a LAZY dep of routes_uploads.py β€” the boot proof above still holds because the
16
+ # import lives inside the handler, and the gate now asserts this line exists here.
17
+ fastapi>=0.139
18
+ uvicorn[standard]>=0.30
19
+ python-dotenv>=1.0
20
+ pandas>=2.0
21
+ requests>=2.28
22
+ huggingface_hub>=0.20
23
+ duckdb>=1.0
24
+ pyyaml>=6.0
25
+ pillow>=10.0
26
+ beautifulsoup4>=4.12
27
+ lxml>=5.0
28
+ cryptography>=42.0
29
+ # ⭐ WAVE 20 (R1 / D-4) β€” THE POSTGRES DRIVER, AND IT IS LOAD-BEARING IN THIS FILE SPECIFICALLY.
30
+ # `core/store_pg.py` is the store backend from this wave on, and it is deliberately FAIL-CLOSED:
31
+ # `_pool()` raises rather than falling back to the HF file store, so a container that gets
32
+ # `STORE_BACKEND=pg` without this line does not degrade β€” it refuses every request that touches
33
+ # the store, which is every authenticated request.
34
+ #
35
+ # β›” AND THIS IS THE FILE THAT MATTERS: the Dockerfile does `COPY requirements.txt` from the
36
+ # Space root, i.e. THIS manifest, not `api/requirements.txt`. That header's own streamlit story
37
+ # is the same defect in the other direction β€” the pinned intent and the shipped manifest are two
38
+ # documents. psycopg is now in BOTH, and `ops/verify_portability.py` gates the pair.
39
+ psycopg[binary,pool]>=3.2
40
+ # ⭐ WAVE 21 (item 11, C5) β€” .xlsx preview for Select-from-file; lazy-imported in
41
+ # routes_uploads.py only. verify_no_streamlit asserts this line in BOTH manifests.
42
+ openpyxl>=3.1
43
+ # β›” AND ITS TRANSPORT, learned from a RUNTIME_ERROR on the first v6 boot: FastAPI demands
44
+ # python-multipart AT IMPORT TIME for any route declaring File(...)/Form(...). Every local gate
45
+ # was green because the dev box happens to have it for unrelated reasons β€” the container
46
+ # installs exactly this file. The environment-parity twin of the streamlit lesson above.
47
+ python-multipart>=0.0.20
48
+ # ⭐ WAVE 37 (D-346, answering `ASK E-1`) β€” THE OFFICIAL ANTHROPIC SDK. `ai_review.py` called the
49
+ # Messages API over raw `requests`, which meant re-implementing retries, streaming and error
50
+ # taxonomy by hand and drifting from them silently. E ships the SDK behind a LAZY import with the
51
+ # raw-HTTP call still there as the fallback, so the feature works with or without this line β€” what
52
+ # the line does is turn the fallback into dead weight instead of the live path.
53
+ # ⚠ BOTH MANIFESTS, NOT ONE. This file's own streamlit story at the top is exactly what pinning
54
+ # one of them looks like a year later.
55
+ anthropic>=0.96
web/index.html CHANGED
@@ -1,46 +1,46 @@
1
- <!doctype html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8" />
5
- <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
6
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
- <title>Loopable</title>
8
- </head>
9
- <body>
10
- <!-- ⭐⭐ WAVE 37 Β· T48 β€” THE BOOT SKELETON, AND EVERY CHOICE HERE IS FORCED BY WHEN IT HAS TO
11
- PAINT. Measured on the deployed build (proto/P4-first-load.md Β§A.2): `#root` was EMPTY and
12
- the screen white for 6.0–8.0 s of an 11.6–16.0 s first open, while one 580 KB entry chunk
13
- downloaded and parsed. The `<body>` was two empty divs, so there was nothing to show.
14
-
15
- β›” INLINE STYLES, NOT A CLASS. `index.css` is its own ~324 KB render-blocking chunk that
16
- took 3.3 s in that same trace β€” a skeleton styled from it would wait for the exact asset
17
- whose arrival it exists to cover, and paint white until then. Inline is the only thing that
18
- can render from the HTML alone.
19
-
20
- β›” INSIDE `#root`, NOT BESIDE IT. `createRoot(...).render()` REPLACES the container's
21
- children, so this is removed by the mount itself. A skeleton outside `#root` needs JS to
22
- take it away, which is a second thing that can fail and a flash-of-two-uis if it does.
23
-
24
- ⚠ NO ANIMATION. A shimmer would be a keyframe the CSS chunk has not delivered yet, and a
25
- static block that never moves is honest about a page that is still downloading; a frozen
26
- shimmer would read as a hung app. `aria-hidden` + `role="presentation"`: a screen reader
27
- should hear the app, not its scaffolding. -->
28
- <div id="root"><div aria-hidden="true" role="presentation" style="height:100vh;display:flex;flex-direction:column;background:#ffffff">
29
- <div style="height:44px;flex:none;border-bottom:1px solid #e8e8ea;display:flex;align-items:center;padding:0 14px">
30
- <div style="width:22px;height:22px;border-radius:11px;background:#efedf9"></div>
31
- <div style="width:96px;height:12px;margin-left:10px;border-radius:3px;background:#efedf9"></div>
32
- </div>
33
- <div style="flex:1;display:flex;min-height:0">
34
- <div style="width:288px;flex:none;border-right:1px solid #e8e8ea;padding:14px 12px">
35
- <div style="height:11px;width:64%;border-radius:3px;background:#f1f0f4;margin-bottom:14px"></div>
36
- <div style="height:11px;width:78%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
37
- <div style="height:11px;width:54%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
38
- <div style="height:11px;width:70%;border-radius:3px;background:#f4f3f7"></div>
39
- </div>
40
- <div style="flex:1;background:#fafafb"></div>
41
- </div>
42
- </div></div>
43
- <div id="portal"></div>
44
- <script type="module" src="/src/main.tsx"></script>
45
- </body>
46
- </html>
 
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
6
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
+ <title>Loopable</title>
8
+ </head>
9
+ <body>
10
+ <!-- ⭐⭐ WAVE 37 Β· T48 β€” THE BOOT SKELETON, AND EVERY CHOICE HERE IS FORCED BY WHEN IT HAS TO
11
+ PAINT. Measured on the deployed build (proto/P4-first-load.md Β§A.2): `#root` was EMPTY and
12
+ the screen white for 6.0–8.0 s of an 11.6–16.0 s first open, while one 580 KB entry chunk
13
+ downloaded and parsed. The `<body>` was two empty divs, so there was nothing to show.
14
+
15
+ β›” INLINE STYLES, NOT A CLASS. `index.css` is its own ~324 KB render-blocking chunk that
16
+ took 3.3 s in that same trace β€” a skeleton styled from it would wait for the exact asset
17
+ whose arrival it exists to cover, and paint white until then. Inline is the only thing that
18
+ can render from the HTML alone.
19
+
20
+ β›” INSIDE `#root`, NOT BESIDE IT. `createRoot(...).render()` REPLACES the container's
21
+ children, so this is removed by the mount itself. A skeleton outside `#root` needs JS to
22
+ take it away, which is a second thing that can fail and a flash-of-two-uis if it does.
23
+
24
+ ⚠ NO ANIMATION. A shimmer would be a keyframe the CSS chunk has not delivered yet, and a
25
+ static block that never moves is honest about a page that is still downloading; a frozen
26
+ shimmer would read as a hung app. `aria-hidden` + `role="presentation"`: a screen reader
27
+ should hear the app, not its scaffolding. -->
28
+ <div id="root"><div aria-hidden="true" role="presentation" style="height:100vh;display:flex;flex-direction:column;background:#ffffff">
29
+ <div style="height:44px;flex:none;border-bottom:1px solid #e8e8ea;display:flex;align-items:center;padding:0 14px">
30
+ <div style="width:22px;height:22px;border-radius:11px;background:#efedf9"></div>
31
+ <div style="width:96px;height:12px;margin-left:10px;border-radius:3px;background:#efedf9"></div>
32
+ </div>
33
+ <div style="flex:1;display:flex;min-height:0">
34
+ <div style="width:288px;flex:none;border-right:1px solid #e8e8ea;padding:14px 12px">
35
+ <div style="height:11px;width:64%;border-radius:3px;background:#f1f0f4;margin-bottom:14px"></div>
36
+ <div style="height:11px;width:78%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
37
+ <div style="height:11px;width:54%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
38
+ <div style="height:11px;width:70%;border-radius:3px;background:#f4f3f7"></div>
39
+ </div>
40
+ <div style="flex:1;background:#fafafb"></div>
41
+ </div>
42
+ </div></div>
43
+ <div id="portal"></div>
44
+ <script type="module" src="/src/main.tsx"></script>
45
+ </body>
46
+ </html>
web/src/App.tsx CHANGED
@@ -1,41 +1,41 @@
1
- import { Suspense, lazy } from "react";
2
- // ⭐⭐ WAVE 37 Β· T48 β€” LAZY, AND IT IS THE LAST OF THE THREE EAGER IMPORTS. `CustomerGrid` (7,715
3
- // lines) plus glide-data-grid sat in the ENTRY chunk because these three files imported it at the
4
- // top level, while twelve other surfaces were already `lazy()`. Measured on the deployed build
5
- // (`proto/P4-first-load.md` Β§A.2): the entry chunk was 580,102 B on the wire and took 5.6-5.8 s,
6
- // during which `#root` was EMPTY and the screen was white β€” 6.0-8.0 s of the 11.6-16.0 s first open.
7
- // ⚠ THE EMBED PAYS THIS TOO, and it is the one path where the grid IS the page, so its fallback is
8
- // deliberately the same skeleton shape the shell uses rather than `null`: a blank iframe is
9
- // indistinguishable from a broken one.
10
- const CustomerGrid = lazy(() => import("./customer-grid/CustomerGrid"));
11
- import { OverlayProvider } from "./customer-grid/OverlaySurface";
12
- import { isStreamlitComponent } from "./customer-grid/hostBridge";
13
- import Shell from "./shell/Shell";
14
-
15
- // HOSTED = either Streamlit path (the component iframe, or the legacy injected
16
- // payload). There the surrounding app owns all chrome and this tree renders the
17
- // BARE grid, byte-for-byte the behavior the embed always had. Only the
18
- // standalone build gets the shell (wave 4, the strangler frame). Computed once
19
- // at module level, like useCustomerData's own mode constants β€” the host mode
20
- // cannot change within a page lifetime.
21
- // EXPORTED (EXIT wave 1): main.tsx needs the same answer to decide whether to
22
- // install the standalone event sink, and two copies of a mode predicate is how
23
- // the two halves of "standalone-only" end up disagreeing.
24
- export const HOSTED =
25
- isStreamlitComponent() ||
26
- typeof (window as unknown as { __AIOS_GRID__?: unknown }).__AIOS_GRID__ !== "undefined";
27
-
28
- export default function App() {
29
- if (HOSTED) {
30
- return (
31
- <div style={{ width: "100%", height: "100%", overflow: "hidden" }}>
32
- <OverlayProvider>
33
- <Suspense fallback={<div className="lp-boot" aria-hidden="true" />}>
34
- <CustomerGrid />
35
- </Suspense>
36
- </OverlayProvider>
37
- </div>
38
- );
39
- }
40
- return <Shell />;
41
- }
 
1
+ import { Suspense, lazy } from "react";
2
+ // ⭐⭐ WAVE 37 Β· T48 β€” LAZY, AND IT IS THE LAST OF THE THREE EAGER IMPORTS. `CustomerGrid` (7,715
3
+ // lines) plus glide-data-grid sat in the ENTRY chunk because these three files imported it at the
4
+ // top level, while twelve other surfaces were already `lazy()`. Measured on the deployed build
5
+ // (`proto/P4-first-load.md` Β§A.2): the entry chunk was 580,102 B on the wire and took 5.6-5.8 s,
6
+ // during which `#root` was EMPTY and the screen was white β€” 6.0-8.0 s of the 11.6-16.0 s first open.
7
+ // ⚠ THE EMBED PAYS THIS TOO, and it is the one path where the grid IS the page, so its fallback is
8
+ // deliberately the same skeleton shape the shell uses rather than `null`: a blank iframe is
9
+ // indistinguishable from a broken one.
10
+ const CustomerGrid = lazy(() => import("./customer-grid/CustomerGrid"));
11
+ import { OverlayProvider } from "./customer-grid/OverlaySurface";
12
+ import { isStreamlitComponent } from "./customer-grid/hostBridge";
13
+ import Shell from "./shell/Shell";
14
+
15
+ // HOSTED = either Streamlit path (the component iframe, or the legacy injected
16
+ // payload). There the surrounding app owns all chrome and this tree renders the
17
+ // BARE grid, byte-for-byte the behavior the embed always had. Only the
18
+ // standalone build gets the shell (wave 4, the strangler frame). Computed once
19
+ // at module level, like useCustomerData's own mode constants β€” the host mode
20
+ // cannot change within a page lifetime.
21
+ // EXPORTED (EXIT wave 1): main.tsx needs the same answer to decide whether to
22
+ // install the standalone event sink, and two copies of a mode predicate is how
23
+ // the two halves of "standalone-only" end up disagreeing.
24
+ export const HOSTED =
25
+ isStreamlitComponent() ||
26
+ typeof (window as unknown as { __AIOS_GRID__?: unknown }).__AIOS_GRID__ !== "undefined";
27
+
28
+ export default function App() {
29
+ if (HOSTED) {
30
+ return (
31
+ <div style={{ width: "100%", height: "100%", overflow: "hidden" }}>
32
+ <OverlayProvider>
33
+ <Suspense fallback={<div className="lp-boot" aria-hidden="true" />}>
34
+ <CustomerGrid />
35
+ </Suspense>
36
+ </OverlayProvider>
37
+ </div>
38
+ );
39
+ }
40
+ return <Shell />;
41
+ }
web/src/account/SubscriptionPage.tsx CHANGED
@@ -1,49 +1,49 @@
1
- // ---------------------------------------------------------------------------
2
- // account/SubscriptionPage.tsx β€” WAVE 35 Β· W35-T20 (owner item 13, contract C6).
3
- //
4
- // Owner item 13, verbatim: *"add below settings the following button: Feedback …,
5
- // Usage credits …, and a Subscription module … Specialized for the Royal Imports
6
- // tenant, do not show it."*
7
- // β›” "verbatim" IS THE POINT: W37-T02 renamed that surface to "Usage" and this quote KEEPS the
8
- // owner's own wording. A quote edited to match a later rename is no longer evidence of anything.
9
- //
10
- // This is the third of those three, and the only one with nothing behind it yet.
11
- // So it says so, in the words this app already uses for a boarded door
12
- // (`Shell.tsx`'s templates note: "Under construction. … will open here in a later
13
- // release."). One voice for one state β€” DESIGN.md 1's "variety is a defect".
14
- //
15
- // β›” THIS PAGE DOES NOT HIDE ITSELF, AND THAT IS THE TICKET'S OWN TRAP.
16
- // C6 puts the Royal Imports rule in TWO places that are both the frame's: the
17
- // account MENU does not draw the row, and the ROUTE refuses. A third opinion here
18
- // would be a third thing to keep in step, and the day they disagree the reader
19
- // gets a menu row that opens a page which says it does not exist. The page renders
20
- // the same for every tenant that can reach it, because reaching it IS the decision.
21
- //
22
- // β›” AND IT TAKES NO PROPS, WHICH IS ALSO A DECISION rather than an omission.
23
- // The wave's rule is that a prop must be REQUIRED, never optional β€” an optional one
24
- // degrades to "the page does not exist", which is indistinguishable from never
25
- // built. That rule constrains the props that EXIST; it does not ask for a prop that
26
- // carries nothing. There is nothing this page needs from the frame: it holds no
27
- // state, makes no call, and takes no decision the frame has already taken. A
28
- // `tenant` prop here would be exactly the second opinion the paragraph above
29
- // refuses. The mount is proven by A's `verify_wiring` row (W2), not by a signature.
30
- // ---------------------------------------------------------------------------
31
-
32
- import "./account.css";
33
-
34
- export default function SubscriptionPage() {
35
- return (
36
- <div className="acct-page">
37
- <h1 className="acct-title">Subscription</h1>
38
- <div className="acct-col">
39
- {/* ⚠ TWO SHORT SENTENCES AND NO TOUR (DESIGN.md 4 / wave-22 R13: the app does not
40
- narrate itself). The reader arrived here on purpose and wants one fact: is there
41
- anything to do? There is not, and every further word would be spent on someone
42
- who is already leaving. No feature list, no roadmap, no "in the meantime". */}
43
- <p className="acct-note">
44
- Under construction. Plans, billing and invoices will open here in a later release.
45
- </p>
46
- </div>
47
- </div>
48
- );
49
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // account/SubscriptionPage.tsx β€” WAVE 35 Β· W35-T20 (owner item 13, contract C6).
3
+ //
4
+ // Owner item 13, verbatim: *"add below settings the following button: Feedback …,
5
+ // Usage credits …, and a Subscription module … Specialized for the Royal Imports
6
+ // tenant, do not show it."*
7
+ // β›” "verbatim" IS THE POINT: W37-T02 renamed that surface to "Usage" and this quote KEEPS the
8
+ // owner's own wording. A quote edited to match a later rename is no longer evidence of anything.
9
+ //
10
+ // This is the third of those three, and the only one with nothing behind it yet.
11
+ // So it says so, in the words this app already uses for a boarded door
12
+ // (`Shell.tsx`'s templates note: "Under construction. … will open here in a later
13
+ // release."). One voice for one state β€” DESIGN.md 1's "variety is a defect".
14
+ //
15
+ // β›” THIS PAGE DOES NOT HIDE ITSELF, AND THAT IS THE TICKET'S OWN TRAP.
16
+ // C6 puts the Royal Imports rule in TWO places that are both the frame's: the
17
+ // account MENU does not draw the row, and the ROUTE refuses. A third opinion here
18
+ // would be a third thing to keep in step, and the day they disagree the reader
19
+ // gets a menu row that opens a page which says it does not exist. The page renders
20
+ // the same for every tenant that can reach it, because reaching it IS the decision.
21
+ //
22
+ // β›” AND IT TAKES NO PROPS, WHICH IS ALSO A DECISION rather than an omission.
23
+ // The wave's rule is that a prop must be REQUIRED, never optional β€” an optional one
24
+ // degrades to "the page does not exist", which is indistinguishable from never
25
+ // built. That rule constrains the props that EXIST; it does not ask for a prop that
26
+ // carries nothing. There is nothing this page needs from the frame: it holds no
27
+ // state, makes no call, and takes no decision the frame has already taken. A
28
+ // `tenant` prop here would be exactly the second opinion the paragraph above
29
+ // refuses. The mount is proven by A's `verify_wiring` row (W2), not by a signature.
30
+ // ---------------------------------------------------------------------------
31
+
32
+ import "./account.css";
33
+
34
+ export default function SubscriptionPage() {
35
+ return (
36
+ <div className="acct-page">
37
+ <h1 className="acct-title">Subscription</h1>
38
+ <div className="acct-col">
39
+ {/* ⚠ TWO SHORT SENTENCES AND NO TOUR (DESIGN.md 4 / wave-22 R13: the app does not
40
+ narrate itself). The reader arrived here on purpose and wants one fact: is there
41
+ anything to do? There is not, and every further word would be spent on someone
42
+ who is already leaving. No feature list, no roadmap, no "in the meantime". */}
43
+ <p className="acct-note">
44
+ Under construction. Plans, billing and invoices will open here in a later release.
45
+ </p>
46
+ </div>
47
+ </div>
48
+ );
49
+ }
web/src/account/UsagePage.tsx CHANGED
@@ -1,297 +1,297 @@
1
- // ---------------------------------------------------------------------------
2
- // account/UsagePage.tsx β€” WAVE 35 Β· W35-T19 (owner item 13, ruling R9, C6/C7).
3
- //
4
- // R9: ONE meter for every AI surface. It REPORTS weekly usage against an
5
- // allowance and does not cut anyone off this wave; over the allowance the
6
- // product still works and the bar is red.
7
- //
8
- // β›”β›” THIS PAGE MAY NOT INVENT A FIGURE, AND THAT IS THE WHOLE TICKET.
9
- // Every number here comes off `GET /usage` β€” the week, the reset date, the
10
- // allowance, each surface's tokens and calls. Nothing is derived from a clock,
11
- // nothing is estimated, and a surface with no ledger lines shows **0**, not a
12
- // blank and not an omission (E-9 guarantees all four surfaces are always
13
- // present, so there is no missing-row branch to get wrong).
14
- // [[no-unverifiable-aggregates]]
15
- //
16
- // β›” AND `unmeasured` IS RENDERED, NOT SWALLOWED. Those are real calls whose
17
- // provider declined to report a token count, so the total beside them is a
18
- // FLOOR. A page that hides them presents the floor as a complete figure, which
19
- // is the cost-surprise failure one step removed β€” the same reason
20
- // `usage_ledger` books an unmeasured call as unknown rather than as zero.
21
- //
22
- // ⚠ SURFACE/READ SPLIT, as on Home and Starred: `renderToStaticMarkup` runs no
23
- // effect, so a shot of the fetching component photographs only its spinner.
24
- // ---------------------------------------------------------------------------
25
-
26
- import { useCallback, useEffect, useRef, useState } from "react";
27
-
28
- import { fmt } from "../ui/fmt";
29
- import { loadUsage } from "./accountApi";
30
- import type { Usage, UsageSurface } from "./accountApi";
31
- import "./account.css";
32
-
33
- /**
34
- * The four surfaces C7 names, in the order R9 lists them.
35
- *
36
- * ⚠ AN UNKNOWN KEY IS HUMANISED, NEVER DROPPED. Dropping it would hide real usage from a meter
37
- * whose whole job is to account for it, and printing the raw key would put an internal identifier
38
- * on screen. The day a fifth LLM entry point lands (this product added two in one wave) it shows
39
- * up here as a readable name with the right number beside it, and somebody can then decide what
40
- * to call it.
41
- */
42
- const SURFACE_LABEL: Record<string, string> = {
43
- assistant: "Assistant",
44
- field_agent: "Field agents",
45
- ai_review: "Reviews",
46
- automation_draft: "Drafting",
47
- };
48
- const ORDER = ["assistant", "field_agent", "ai_review", "automation_draft"];
49
-
50
- export function surfaceLabel(key: string): string {
51
- const known = SURFACE_LABEL[key];
52
- if (known) return known;
53
- const words = key.replace(/[_-]+/g, " ").trim();
54
- return words ? words.charAt(0).toUpperCase() + words.slice(1) : key;
55
- }
56
-
57
- /** C7's order first, then anything the server added, alphabetically. */
58
- export function orderSurfaces(surfaces: UsageSurface[]): UsageSurface[] {
59
- const rank = (s: UsageSurface) => {
60
- const i = ORDER.indexOf(s.surface);
61
- return i === -1 ? ORDER.length : i;
62
- };
63
- return [...surfaces].sort(
64
- (a, b) => rank(a) - rank(b) || surfaceLabel(a.surface).localeCompare(surfaceLabel(b.surface))
65
- );
66
- }
67
-
68
- /**
69
- * The bar's fill, as a percentage, CLAMPED to 100.
70
- *
71
- * ⚠ The clamp is what keeps "over the allowance" a COLOUR rather than a bar that overflows its
72
- * own track and paints across the page. The number above the bar is unclamped and is where the
73
- * overage is actually read.
74
- * ⚠ An allowance of 0 (unset) yields 0 rather than a division by zero: no allowance means the
75
- * meter has nothing to measure against, and a full red bar would be an assertion nobody made.
76
- */
77
- export function barPct(value: number, of: number): number {
78
- if (!(of > 0)) return 0;
79
- return Math.max(0, Math.min(100, (value / of) * 100));
80
- }
81
-
82
- export type UsageLoad =
83
- | { phase: "loading" }
84
- | { phase: "ready"; usage: Usage }
85
- | { phase: "failed"; message: string };
86
-
87
- function Bar({ pct, over }: { pct: number; over: boolean }) {
88
- return (
89
- <span className="acct-bar" aria-hidden="true">
90
- <span className={"acct-bar-fill" + (over ? " is-over" : "")} style={{ width: `${pct}%` }} />
91
- </span>
92
- );
93
- }
94
-
95
- export function UsageSurfaceRows({ usage }: { usage: Usage }) {
96
- // ⚠ SCALED TO THE LARGEST SURFACE, NOT TO THE WEEK'S TOTAL, and the difference is legibility
97
- // rather than accuracy. `total` is the week's whole figure and can legitimately exceed the sum
98
- // of these four (unattributed calls are counted there and belong to nobody), so scaling to it
99
- // shrinks every bar by an amount the reader cannot see the cause of. Scaled to the biggest row,
100
- // the bars answer the question a row of bars is actually asked: which surface is spending most.
101
- // The absolute number sits beside each one, so nothing here is only readable as a shape.
102
- const biggest = usage.surfaces.reduce((m, s) => Math.max(m, s.tokens), 0);
103
- return (
104
- <div className="acct-rows">
105
- {orderSurfaces(usage.surfaces).map((s) => (
106
- <div key={s.surface} className="acct-row">
107
- <span className="acct-row-name">{surfaceLabel(s.surface)}</span>
108
- <Bar pct={barPct(s.tokens, biggest)} over={false} />
109
- <span className="acct-row-num">{fmt.int(s.tokens)}</span>
110
- <span className="acct-row-sub">
111
- {fmt.int(s.calls)} {s.calls === 1 ? "call" : "calls"}
112
- {/* β›” NOT HOVER-ONLY. A surface whose provider declined to report tokens has a
113
- token number that is a floor, and D-253 is a booked defect whose entire content
114
- is "the explanation was satisfied only on hover". */}
115
- {s.unmeasured > 0 ? `, ${fmt.int(s.unmeasured)} not measured` : ""}
116
- </span>
117
- </div>
118
- ))}
119
- </div>
120
- );
121
- }
122
-
123
- export function UsageView({
124
- load,
125
- scope,
126
- canSeeTenant,
127
- onScope,
128
- onRetry,
129
- }: {
130
- load: UsageLoad;
131
- scope: "me" | "tenant";
132
- /**
133
- * Whether the workspace view is reachable AT ALL for this account.
134
- *
135
- * β›” THE TOGGLE IS NOT DRAWN WHEN IT IS NOT, and that is R8's fake-affordance rule applied to a
136
- * permission: `?scope=tenant` is admin-only and 403s for everybody else, so an always-visible
137
- * control would be a button most accounts can only be refused by.
138
- */
139
- canSeeTenant: boolean;
140
- onScope: (scope: "me" | "tenant") => void;
141
- onRetry: () => void;
142
- }) {
143
- return (
144
- <div className="acct-page">
145
- <h1 className="acct-title">Usage</h1>
146
- <div className="acct-col">
147
- {canSeeTenant ? (
148
- <div className="acct-scope" role="group" aria-label="Whose usage">
149
- {(["me", "tenant"] as const).map((key) => (
150
- <button
151
- key={key}
152
- type="button"
153
- className={"acct-scope-btn" + (scope === key ? " is-on" : "")}
154
- aria-pressed={scope === key}
155
- onClick={() => onScope(key)}
156
- >
157
- {key === "me" ? "You" : "Workspace"}
158
- </button>
159
- ))}
160
- </div>
161
- ) : null}
162
- {load.phase === "loading" ? (
163
- <div className="acct-loading">
164
- <span className="lp-spin lp-spin--lg" role="status" aria-label="Loading" />
165
- </div>
166
- ) : load.phase === "failed" ? (
167
- // β›” NOT A ZERO METER. A failed read and a quiet week look identical on screen unless
168
- // this branch exists, and a meter reading zero is the most reassuring possible lie.
169
- <div className="acct-failed">
170
- <p className="acct-note">{load.message}</p>
171
- <button type="button" className="acct-retry" onClick={onRetry}>
172
- Try again
173
- </button>
174
- </div>
175
- ) : (
176
- <>
177
- <div className="acct-meter">
178
- {/* β›” THE METER SAYS WHOSE USAGE IT IS, IN WORDS, and that is not decoration. The
179
- allowance is a WORKSPACE number; the total beside it is this account's own
180
- unless the scope says otherwise. A meter that shows a personal figure against a
181
- shared limit without saying so is a ratio nobody can read correctly, and it is
182
- the one way this page can be wrong while every number on it is right. */}
183
- <div className="acct-meter-head">
184
- <span className="acct-meter-who">
185
- {load.usage.scope === "tenant" ? "This workspace" : "You"}, this week
186
- </span>
187
- </div>
188
- <div className="acct-meter-head">
189
- <span className={"acct-meter-value" + (load.usage.over ? " is-over" : "")}>
190
- {fmt.int(load.usage.total)}
191
- </span>
192
- <span className="acct-meter-of">
193
- of {fmt.int(load.usage.allowance)} tokens
194
- </span>
195
- </div>
196
- <Bar pct={barPct(load.usage.total, load.usage.allowance)} over={load.usage.over} />
197
- <div className="acct-meter-foot">
198
- {/* Both facts are the SERVER'S: the week it counted and the date it rolls over.
199
- A week boundary computed in the browser can disagree with the bucketing that
200
- produced the number above it, and then the page states a period nobody
201
- measured. */}
202
- <span>
203
- Week {load.usage.week}. Resets {fmt.date(load.usage.resets)}.
204
- </span>
205
- <span className="acct-meter-calls">
206
- {fmt.int(load.usage.calls)} {load.usage.calls === 1 ? "call" : "calls"}
207
- </span>
208
- </div>
209
- </div>
210
-
211
- {/* β›” R9's whole point, in one line: over the allowance it STILL WORKS. The bar is
212
- red, nothing is cut off, and the sentence says which of those two is true so
213
- nobody has to infer it from a colour. */}
214
- {load.usage.over ? (
215
- <p className="acct-error" role="status">
216
- This workspace is over its weekly allowance. Nothing is cut off; the AI surfaces
217
- keep working.
218
- </p>
219
- ) : null}
220
-
221
- {/* The server's own sentence, present only when something really was unmeasured. */}
222
- {load.usage.note ? <p className="acct-note acct-note--inline">{load.usage.note}</p> : null}
223
-
224
- <h2 className="acct-section">By surface</h2>
225
- <UsageSurfaceRows usage={load.usage} />
226
-
227
- {load.usage.unattributed > 0 ? (
228
- // ⚠ LABELLED A WIRING GAP, NOT USAGE (E-9). These are AI calls this container could
229
- // not attribute to an account. Folding them into somebody's total would be an
230
- // invented attribution, and leaving them out entirely would understate the week.
231
- <p className="acct-note acct-note--inline">
232
- {fmt.int(load.usage.unattributed)} tokens this week could not be attributed to an
233
- account. That is a wiring gap in the meter, not somebody's usage.
234
- </p>
235
- ) : null}
236
- </>
237
- )}
238
- </div>
239
- </div>
240
- );
241
- }
242
-
243
- export default function UsagePage() {
244
- const [load, setLoad] = useState<UsageLoad>({ phase: "loading" });
245
- const [scope, setScope] = useState<"me" | "tenant">("me");
246
- /**
247
- * Whether the workspace view exists for this account, ANSWERED BY ASKING ONCE.
248
- *
249
- * β›” WHY A PROBE RATHER THAN A ROLE CHECK. The frame knows the role, but these pages take no
250
- * props by contract (C6's trap: a page that decides its own visibility is a second opinion that
251
- * will one day disagree with the route). The route itself is the authority, so the page asks it
252
- * once: a 200 means the door is open and the toggle is real; a 403 means it is not and no
253
- * control is drawn. ⚠ That 403 is an ANSWER, not an error β€” it is never shown to the reader.
254
- * ⭐ AND IT IS WHAT GIVES `?scope=tenant` A DOOR. E built it admin-only; without this it would
255
- * be a finished capability with no caller, which is this repo's most-repeated failure
256
- * [[reachable-is-not-the-same-as-built]].
257
- */
258
- const [canSeeTenant, setCanSeeTenant] = useState(false);
259
- const gen = useRef(0);
260
-
261
- const read = useCallback((which: "me" | "tenant") => {
262
- const mine = gen.current + 1;
263
- gen.current = mine;
264
- setLoad({ phase: "loading" });
265
- void loadUsage(which === "tenant" ? "tenant" : undefined).then((r) => {
266
- if (gen.current !== mine) return;
267
- setLoad(r.ok ? { phase: "ready", usage: r.value } : { phase: "failed", message: r.message });
268
- });
269
- }, []);
270
-
271
- useEffect(() => {
272
- read(scope);
273
- return () => {
274
- gen.current += 1;
275
- };
276
- }, [read, scope]);
277
-
278
- useEffect(() => {
279
- let live = true;
280
- void loadUsage("tenant").then((r) => {
281
- if (live) setCanSeeTenant(r.ok);
282
- });
283
- return () => {
284
- live = false;
285
- };
286
- }, []);
287
-
288
- return (
289
- <UsageView
290
- load={load}
291
- scope={scope}
292
- canSeeTenant={canSeeTenant}
293
- onScope={setScope}
294
- onRetry={() => read(scope)}
295
- />
296
- );
297
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // account/UsagePage.tsx β€” WAVE 35 Β· W35-T19 (owner item 13, ruling R9, C6/C7).
3
+ //
4
+ // R9: ONE meter for every AI surface. It REPORTS weekly usage against an
5
+ // allowance and does not cut anyone off this wave; over the allowance the
6
+ // product still works and the bar is red.
7
+ //
8
+ // β›”β›” THIS PAGE MAY NOT INVENT A FIGURE, AND THAT IS THE WHOLE TICKET.
9
+ // Every number here comes off `GET /usage` β€” the week, the reset date, the
10
+ // allowance, each surface's tokens and calls. Nothing is derived from a clock,
11
+ // nothing is estimated, and a surface with no ledger lines shows **0**, not a
12
+ // blank and not an omission (E-9 guarantees all four surfaces are always
13
+ // present, so there is no missing-row branch to get wrong).
14
+ // [[no-unverifiable-aggregates]]
15
+ //
16
+ // β›” AND `unmeasured` IS RENDERED, NOT SWALLOWED. Those are real calls whose
17
+ // provider declined to report a token count, so the total beside them is a
18
+ // FLOOR. A page that hides them presents the floor as a complete figure, which
19
+ // is the cost-surprise failure one step removed β€” the same reason
20
+ // `usage_ledger` books an unmeasured call as unknown rather than as zero.
21
+ //
22
+ // ⚠ SURFACE/READ SPLIT, as on Home and Starred: `renderToStaticMarkup` runs no
23
+ // effect, so a shot of the fetching component photographs only its spinner.
24
+ // ---------------------------------------------------------------------------
25
+
26
+ import { useCallback, useEffect, useRef, useState } from "react";
27
+
28
+ import { fmt } from "../ui/fmt";
29
+ import { loadUsage } from "./accountApi";
30
+ import type { Usage, UsageSurface } from "./accountApi";
31
+ import "./account.css";
32
+
33
+ /**
34
+ * The four surfaces C7 names, in the order R9 lists them.
35
+ *
36
+ * ⚠ AN UNKNOWN KEY IS HUMANISED, NEVER DROPPED. Dropping it would hide real usage from a meter
37
+ * whose whole job is to account for it, and printing the raw key would put an internal identifier
38
+ * on screen. The day a fifth LLM entry point lands (this product added two in one wave) it shows
39
+ * up here as a readable name with the right number beside it, and somebody can then decide what
40
+ * to call it.
41
+ */
42
+ const SURFACE_LABEL: Record<string, string> = {
43
+ assistant: "Assistant",
44
+ field_agent: "Field agents",
45
+ ai_review: "Reviews",
46
+ automation_draft: "Drafting",
47
+ };
48
+ const ORDER = ["assistant", "field_agent", "ai_review", "automation_draft"];
49
+
50
+ export function surfaceLabel(key: string): string {
51
+ const known = SURFACE_LABEL[key];
52
+ if (known) return known;
53
+ const words = key.replace(/[_-]+/g, " ").trim();
54
+ return words ? words.charAt(0).toUpperCase() + words.slice(1) : key;
55
+ }
56
+
57
+ /** C7's order first, then anything the server added, alphabetically. */
58
+ export function orderSurfaces(surfaces: UsageSurface[]): UsageSurface[] {
59
+ const rank = (s: UsageSurface) => {
60
+ const i = ORDER.indexOf(s.surface);
61
+ return i === -1 ? ORDER.length : i;
62
+ };
63
+ return [...surfaces].sort(
64
+ (a, b) => rank(a) - rank(b) || surfaceLabel(a.surface).localeCompare(surfaceLabel(b.surface))
65
+ );
66
+ }
67
+
68
+ /**
69
+ * The bar's fill, as a percentage, CLAMPED to 100.
70
+ *
71
+ * ⚠ The clamp is what keeps "over the allowance" a COLOUR rather than a bar that overflows its
72
+ * own track and paints across the page. The number above the bar is unclamped and is where the
73
+ * overage is actually read.
74
+ * ⚠ An allowance of 0 (unset) yields 0 rather than a division by zero: no allowance means the
75
+ * meter has nothing to measure against, and a full red bar would be an assertion nobody made.
76
+ */
77
+ export function barPct(value: number, of: number): number {
78
+ if (!(of > 0)) return 0;
79
+ return Math.max(0, Math.min(100, (value / of) * 100));
80
+ }
81
+
82
+ export type UsageLoad =
83
+ | { phase: "loading" }
84
+ | { phase: "ready"; usage: Usage }
85
+ | { phase: "failed"; message: string };
86
+
87
+ function Bar({ pct, over }: { pct: number; over: boolean }) {
88
+ return (
89
+ <span className="acct-bar" aria-hidden="true">
90
+ <span className={"acct-bar-fill" + (over ? " is-over" : "")} style={{ width: `${pct}%` }} />
91
+ </span>
92
+ );
93
+ }
94
+
95
+ export function UsageSurfaceRows({ usage }: { usage: Usage }) {
96
+ // ⚠ SCALED TO THE LARGEST SURFACE, NOT TO THE WEEK'S TOTAL, and the difference is legibility
97
+ // rather than accuracy. `total` is the week's whole figure and can legitimately exceed the sum
98
+ // of these four (unattributed calls are counted there and belong to nobody), so scaling to it
99
+ // shrinks every bar by an amount the reader cannot see the cause of. Scaled to the biggest row,
100
+ // the bars answer the question a row of bars is actually asked: which surface is spending most.
101
+ // The absolute number sits beside each one, so nothing here is only readable as a shape.
102
+ const biggest = usage.surfaces.reduce((m, s) => Math.max(m, s.tokens), 0);
103
+ return (
104
+ <div className="acct-rows">
105
+ {orderSurfaces(usage.surfaces).map((s) => (
106
+ <div key={s.surface} className="acct-row">
107
+ <span className="acct-row-name">{surfaceLabel(s.surface)}</span>
108
+ <Bar pct={barPct(s.tokens, biggest)} over={false} />
109
+ <span className="acct-row-num">{fmt.int(s.tokens)}</span>
110
+ <span className="acct-row-sub">
111
+ {fmt.int(s.calls)} {s.calls === 1 ? "call" : "calls"}
112
+ {/* β›” NOT HOVER-ONLY. A surface whose provider declined to report tokens has a
113
+ token number that is a floor, and D-253 is a booked defect whose entire content
114
+ is "the explanation was satisfied only on hover". */}
115
+ {s.unmeasured > 0 ? `, ${fmt.int(s.unmeasured)} not measured` : ""}
116
+ </span>
117
+ </div>
118
+ ))}
119
+ </div>
120
+ );
121
+ }
122
+
123
+ export function UsageView({
124
+ load,
125
+ scope,
126
+ canSeeTenant,
127
+ onScope,
128
+ onRetry,
129
+ }: {
130
+ load: UsageLoad;
131
+ scope: "me" | "tenant";
132
+ /**
133
+ * Whether the workspace view is reachable AT ALL for this account.
134
+ *
135
+ * β›” THE TOGGLE IS NOT DRAWN WHEN IT IS NOT, and that is R8's fake-affordance rule applied to a
136
+ * permission: `?scope=tenant` is admin-only and 403s for everybody else, so an always-visible
137
+ * control would be a button most accounts can only be refused by.
138
+ */
139
+ canSeeTenant: boolean;
140
+ onScope: (scope: "me" | "tenant") => void;
141
+ onRetry: () => void;
142
+ }) {
143
+ return (
144
+ <div className="acct-page">
145
+ <h1 className="acct-title">Usage</h1>
146
+ <div className="acct-col">
147
+ {canSeeTenant ? (
148
+ <div className="acct-scope" role="group" aria-label="Whose usage">
149
+ {(["me", "tenant"] as const).map((key) => (
150
+ <button
151
+ key={key}
152
+ type="button"
153
+ className={"acct-scope-btn" + (scope === key ? " is-on" : "")}
154
+ aria-pressed={scope === key}
155
+ onClick={() => onScope(key)}
156
+ >
157
+ {key === "me" ? "You" : "Workspace"}
158
+ </button>
159
+ ))}
160
+ </div>
161
+ ) : null}
162
+ {load.phase === "loading" ? (
163
+ <div className="acct-loading">
164
+ <span className="lp-spin lp-spin--lg" role="status" aria-label="Loading" />
165
+ </div>
166
+ ) : load.phase === "failed" ? (
167
+ // β›” NOT A ZERO METER. A failed read and a quiet week look identical on screen unless
168
+ // this branch exists, and a meter reading zero is the most reassuring possible lie.
169
+ <div className="acct-failed">
170
+ <p className="acct-note">{load.message}</p>
171
+ <button type="button" className="acct-retry" onClick={onRetry}>
172
+ Try again
173
+ </button>
174
+ </div>
175
+ ) : (
176
+ <>
177
+ <div className="acct-meter">
178
+ {/* β›” THE METER SAYS WHOSE USAGE IT IS, IN WORDS, and that is not decoration. The
179
+ allowance is a WORKSPACE number; the total beside it is this account's own
180
+ unless the scope says otherwise. A meter that shows a personal figure against a
181
+ shared limit without saying so is a ratio nobody can read correctly, and it is
182
+ the one way this page can be wrong while every number on it is right. */}
183
+ <div className="acct-meter-head">
184
+ <span className="acct-meter-who">
185
+ {load.usage.scope === "tenant" ? "This workspace" : "You"}, this week
186
+ </span>
187
+ </div>
188
+ <div className="acct-meter-head">
189
+ <span className={"acct-meter-value" + (load.usage.over ? " is-over" : "")}>
190
+ {fmt.int(load.usage.total)}
191
+ </span>
192
+ <span className="acct-meter-of">
193
+ of {fmt.int(load.usage.allowance)} tokens
194
+ </span>
195
+ </div>
196
+ <Bar pct={barPct(load.usage.total, load.usage.allowance)} over={load.usage.over} />
197
+ <div className="acct-meter-foot">
198
+ {/* Both facts are the SERVER'S: the week it counted and the date it rolls over.
199
+ A week boundary computed in the browser can disagree with the bucketing that
200
+ produced the number above it, and then the page states a period nobody
201
+ measured. */}
202
+ <span>
203
+ Week {load.usage.week}. Resets {fmt.date(load.usage.resets)}.
204
+ </span>
205
+ <span className="acct-meter-calls">
206
+ {fmt.int(load.usage.calls)} {load.usage.calls === 1 ? "call" : "calls"}
207
+ </span>
208
+ </div>
209
+ </div>
210
+
211
+ {/* β›” R9's whole point, in one line: over the allowance it STILL WORKS. The bar is
212
+ red, nothing is cut off, and the sentence says which of those two is true so
213
+ nobody has to infer it from a colour. */}
214
+ {load.usage.over ? (
215
+ <p className="acct-error" role="status">
216
+ This workspace is over its weekly allowance. Nothing is cut off; the AI surfaces
217
+ keep working.
218
+ </p>
219
+ ) : null}
220
+
221
+ {/* The server's own sentence, present only when something really was unmeasured. */}
222
+ {load.usage.note ? <p className="acct-note acct-note--inline">{load.usage.note}</p> : null}
223
+
224
+ <h2 className="acct-section">By surface</h2>
225
+ <UsageSurfaceRows usage={load.usage} />
226
+
227
+ {load.usage.unattributed > 0 ? (
228
+ // ⚠ LABELLED A WIRING GAP, NOT USAGE (E-9). These are AI calls this container could
229
+ // not attribute to an account. Folding them into somebody's total would be an
230
+ // invented attribution, and leaving them out entirely would understate the week.
231
+ <p className="acct-note acct-note--inline">
232
+ {fmt.int(load.usage.unattributed)} tokens this week could not be attributed to an
233
+ account. That is a wiring gap in the meter, not somebody's usage.
234
+ </p>
235
+ ) : null}
236
+ </>
237
+ )}
238
+ </div>
239
+ </div>
240
+ );
241
+ }
242
+
243
+ export default function UsagePage() {
244
+ const [load, setLoad] = useState<UsageLoad>({ phase: "loading" });
245
+ const [scope, setScope] = useState<"me" | "tenant">("me");
246
+ /**
247
+ * Whether the workspace view exists for this account, ANSWERED BY ASKING ONCE.
248
+ *
249
+ * β›” WHY A PROBE RATHER THAN A ROLE CHECK. The frame knows the role, but these pages take no
250
+ * props by contract (C6's trap: a page that decides its own visibility is a second opinion that
251
+ * will one day disagree with the route). The route itself is the authority, so the page asks it
252
+ * once: a 200 means the door is open and the toggle is real; a 403 means it is not and no
253
+ * control is drawn. ⚠ That 403 is an ANSWER, not an error β€” it is never shown to the reader.
254
+ * ⭐ AND IT IS WHAT GIVES `?scope=tenant` A DOOR. E built it admin-only; without this it would
255
+ * be a finished capability with no caller, which is this repo's most-repeated failure
256
+ * [[reachable-is-not-the-same-as-built]].
257
+ */
258
+ const [canSeeTenant, setCanSeeTenant] = useState(false);
259
+ const gen = useRef(0);
260
+
261
+ const read = useCallback((which: "me" | "tenant") => {
262
+ const mine = gen.current + 1;
263
+ gen.current = mine;
264
+ setLoad({ phase: "loading" });
265
+ void loadUsage(which === "tenant" ? "tenant" : undefined).then((r) => {
266
+ if (gen.current !== mine) return;
267
+ setLoad(r.ok ? { phase: "ready", usage: r.value } : { phase: "failed", message: r.message });
268
+ });
269
+ }, []);
270
+
271
+ useEffect(() => {
272
+ read(scope);
273
+ return () => {
274
+ gen.current += 1;
275
+ };
276
+ }, [read, scope]);
277
+
278
+ useEffect(() => {
279
+ let live = true;
280
+ void loadUsage("tenant").then((r) => {
281
+ if (live) setCanSeeTenant(r.ok);
282
+ });
283
+ return () => {
284
+ live = false;
285
+ };
286
+ }, []);
287
+
288
+ return (
289
+ <UsageView
290
+ load={load}
291
+ scope={scope}
292
+ canSeeTenant={canSeeTenant}
293
+ onScope={setScope}
294
+ onRetry={() => read(scope)}
295
+ />
296
+ );
297
+ }
web/src/account/account.css CHANGED
@@ -1,372 +1,372 @@
1
- /* ─────────────────────────────────────────────────────────────────────────────────────────
2
- account/account.css β€” WAVE 35, owner item 13: the three surfaces that hang off the
3
- account button (Feedback, Usage, Subscription).
4
-
5
- β›” ITS OWN STYLESHEET, NOT index.css. That file belongs to the INTEGRATOR for the whole
6
- wave, and the wave's own rule is that a new surface brings its own sheet. Every selector
7
- here is .acct-*; nothing in this file redefines a .home-*, .shell-* or .cg-* rule, so
8
- nothing here can win or lose a source-order fight with the shared sheet.
9
-
10
- ⚠ .acct-page RESTATES .shell-home's five box declarations rather than reusing that class,
11
- and that is deliberate rather than lazy. .shell-home is Home's box by name and by its own
12
- region header; borrowing it would make every future Home layout change silently a change
13
- to three account pages. The VALUES are copied on purpose β€” DESIGN.md 2's sibling rule
14
- ("a panel matches its sibling's rendered values, not merely the scale") is what makes the
15
- account pages read as the same system as Home, and .shell-main is overflow:hidden, so a
16
- page that does not own its own scroll box simply loses everything below the fold.
17
-
18
- ⚠ EVERY font-size IS A --lp-fs-* TOKEN. verify_ui globs src/**.css (every stylesheet in
19
- the tree, not just index.css) and goes RED on a literal β€” wave-21 R5.
20
- ───────────────────────────────────────────────────────────────────────────────────────── */
21
-
22
- .acct-page {
23
- height: 100%;
24
- overflow-y: auto;
25
- padding: 34px 44px 56px;
26
- box-sizing: border-box;
27
- background: var(--lp-wash);
28
- }
29
-
30
- /* A short plain noun, same size and weight as .home-title, because it is the same role on a
31
- sibling surface. DESIGN.md 2: headers are 1 to 3 words, never a sentence. */
32
- .acct-title {
33
- margin: 0 0 20px;
34
- font-size: var(--lp-fs-lg);
35
- font-weight: 650;
36
- color: var(--lp-ink);
37
- }
38
-
39
- /* THE ONE COLUMN. Every account surface is a reading-width column, not a full-bleed page:
40
- a composer, a meter list and a note are all narrow objects, and stretching them to a
41
- 1600px window is how a page stops looking like it was designed. The reference the owner
42
- gave for the assistant uses the same centred column for the same reason. */
43
- .acct-col {
44
- max-width: 640px;
45
- }
46
-
47
- /* ── the honest note (Subscription today; any boarded account surface tomorrow) ─────────
48
- ONE containment layer: a hairline panel on the wash, no card inside a card, no shadow
49
- (DESIGN.md 4). It is a panel rather than a bare paragraph so the emptiness reads as
50
- deliberate instead of as a page that failed to load. */
51
- .acct-note {
52
- margin: 0;
53
- padding: 16px 18px;
54
- border: 1px solid var(--lp-line);
55
- border-radius: var(--lp-r-md);
56
- background: var(--lp-surface);
57
- font-size: var(--lp-fs-xs);
58
- line-height: var(--lp-lh);
59
- color: var(--lp-muted);
60
- }
61
-
62
- /* ── loading, and the way back from a failed read ─────────────────────────────────────────── */
63
- .acct-loading {
64
- display: flex;
65
- align-items: center;
66
- justify-content: center;
67
- min-height: 180px;
68
- }
69
- .acct-failed {
70
- display: flex;
71
- align-items: center;
72
- gap: 12px;
73
- }
74
- /* DESIGN.md 4's quiet button, with the UA chrome reset explicitly (the wave-19 "mystery outer
75
- lines and tinted fill" rule). */
76
- .acct-retry {
77
- flex: 0 0 auto;
78
- padding: 6px 12px;
79
- border: 1px solid var(--lp-line);
80
- border-radius: var(--lp-r-md);
81
- background: var(--lp-surface);
82
- color: var(--lp-ink);
83
- font: inherit;
84
- font-size: var(--lp-fs-2xs);
85
- font-weight: 600;
86
- cursor: pointer;
87
- }
88
- .acct-retry:hover {
89
- background: var(--lp-surface-2);
90
- border-color: var(--lp-blue-deep);
91
- }
92
-
93
- /* ── the two answers a write can give ─────────────────────────────────────────────────────
94
- Green = positive, red = negative: the fixed semantics (DESIGN.md 3), on the DEEP companions
95
- because a pastel on white is not a light aesthetic, it is an unreadable one. */
96
- .acct-ok,
97
- .acct-error {
98
- margin: 0 0 12px;
99
- padding: 9px 12px;
100
- border-radius: var(--lp-r-md);
101
- font-size: var(--lp-fs-2xs);
102
- line-height: var(--lp-lh);
103
- }
104
- .acct-ok {
105
- border: 1px solid var(--lp-green);
106
- background: var(--lp-green-tint);
107
- color: var(--lp-green-deep);
108
- }
109
- .acct-error {
110
- border: 1px solid var(--lp-red);
111
- background: var(--lp-red-tint);
112
- color: var(--lp-red-deep);
113
- }
114
-
115
- /* ── the composer ─────────────────────────────────────────────────────────────────────────
116
- The ASSISTANT'S anatomy in this module's own rules: one rounded field that contains its own
117
- control row, so the category and the send button read as part of the thing being written
118
- rather than as chrome around it. `assistant.css` is another session's file this wave and is
119
- deliberately not imported; the shape is borrowed, the rules are local.
120
- ⚠ The radius is smaller than the assistant's 22px pill on purpose: this field is a paragraph
121
- box, not a one-line prompt, and a heavily rounded tall box reads as a speech bubble. */
122
- .acct-field {
123
- border: 1px solid var(--lp-line);
124
- border-radius: var(--lp-r-lg);
125
- background: var(--lp-surface);
126
- padding: 12px 10px 10px 14px;
127
- }
128
- .acct-field:focus-within {
129
- border-color: var(--lp-blue-solid);
130
- }
131
- .acct-prompt {
132
- display: block;
133
- width: 100%;
134
- border: 0;
135
- outline: none;
136
- padding: 0 6px 0 0;
137
- background: transparent;
138
- color: var(--lp-ink);
139
- font: inherit;
140
- font-size: var(--lp-fs-sm);
141
- line-height: var(--lp-lh);
142
- resize: vertical;
143
- box-sizing: border-box;
144
- }
145
- .acct-prompt::placeholder {
146
- color: var(--lp-muted);
147
- }
148
- .acct-field-foot {
149
- display: flex;
150
- align-items: center;
151
- gap: 10px;
152
- margin-top: 10px;
153
- }
154
- .acct-pick {
155
- display: inline-flex;
156
- align-items: center;
157
- gap: 6px;
158
- min-width: 0;
159
- }
160
- .acct-pick-label {
161
- color: var(--lp-muted);
162
- font-size: var(--lp-fs-2xs);
163
- }
164
- .acct-select {
165
- max-width: 220px;
166
- padding: 4px 8px;
167
- border: 1px solid var(--lp-line);
168
- border-radius: var(--lp-r-sm);
169
- background: var(--lp-surface);
170
- color: var(--lp-ink);
171
- font: inherit;
172
- font-size: var(--lp-fs-2xs);
173
- cursor: pointer;
174
- }
175
- /* Tabular figures so the count does not jitter as it climbs. Red only once the limit is actually
176
- passed: a counter that warns before anything is wrong trains people to ignore it. */
177
- .acct-count {
178
- color: var(--lp-muted);
179
- font-size: var(--lp-fs-3xs);
180
- font-variant-numeric: tabular-nums;
181
- }
182
- .acct-count.is-over {
183
- color: var(--lp-red-deep);
184
- font-weight: 600;
185
- }
186
- /* The send button takes the ink fill when it can send and the wash when it cannot, which is the
187
- assistant's own rule: the control says whether there is anything to send before it is pressed. */
188
- .acct-send {
189
- flex: 0 0 auto;
190
- margin-left: auto;
191
- width: 30px;
192
- height: 30px;
193
- display: inline-flex;
194
- align-items: center;
195
- justify-content: center;
196
- border: 0;
197
- border-radius: var(--lp-r-pill);
198
- background: var(--lp-ink);
199
- color: var(--lp-surface);
200
- font: inherit;
201
- cursor: pointer;
202
- }
203
- .acct-send:disabled {
204
- background: var(--lp-surface-2);
205
- color: var(--lp-muted);
206
- cursor: default;
207
- }
208
- .acct-send-icon {
209
- fill: none;
210
- stroke: currentColor;
211
- stroke-width: 1.7;
212
- stroke-linecap: round;
213
- stroke-linejoin: round;
214
- }
215
-
216
- /* ── the usage meter (R9) ─────────────────────────────────────────────────────────────────
217
- One containment layer, hairline, no shadow. The bar is the only new SHAPE on these pages, and
218
- the ticket asks for it by name ("over the allowance the bar is red"). */
219
- .acct-note--inline {
220
- margin: 12px 0 0;
221
- padding: 9px 12px;
222
- font-size: var(--lp-fs-2xs);
223
- }
224
- .acct-scope {
225
- display: inline-flex;
226
- gap: 2px;
227
- margin-bottom: 14px;
228
- padding: 2px;
229
- border: 1px solid var(--lp-line);
230
- border-radius: var(--lp-r-md);
231
- background: var(--lp-surface);
232
- }
233
- /* Selection is TINT plus WEIGHT with the ink left alone, which is `.shell-nav-item.is-active`'s
234
- rule. ⚠ NOT `--lp-blue-deep` on `--lp-blue-tint`: that pair measures 2.96:1, under the 4.5:1
235
- text bar and under the 3:1 graphical one, and this control holds words. */
236
- .acct-scope-btn {
237
- padding: 4px 12px;
238
- border: 0;
239
- border-radius: var(--lp-r-sm);
240
- background: transparent;
241
- color: var(--lp-muted);
242
- font: inherit;
243
- font-size: var(--lp-fs-2xs);
244
- font-weight: 600;
245
- cursor: pointer;
246
- }
247
- .acct-scope-btn:hover {
248
- background: var(--lp-surface-2);
249
- }
250
- .acct-scope-btn.is-on {
251
- background: var(--lp-blue-tint);
252
- color: var(--lp-ink);
253
- }
254
-
255
- .acct-meter {
256
- padding: 16px 18px;
257
- border: 1px solid var(--lp-line);
258
- border-radius: var(--lp-r-md);
259
- background: var(--lp-surface);
260
- }
261
- .acct-meter-head {
262
- display: flex;
263
- align-items: baseline;
264
- gap: 8px;
265
- flex-wrap: wrap;
266
- }
267
- .acct-meter-who {
268
- font-size: var(--lp-fs-2xs);
269
- font-weight: 600;
270
- color: var(--lp-muted);
271
- margin-bottom: 4px;
272
- }
273
- /* Tabular figures on every financial-grade number (DESIGN.md 2), so a total that climbs does not
274
- make the label beside it dance. Weight 650, never a display weight. */
275
- .acct-meter-value {
276
- font-size: var(--lp-fs-xl);
277
- font-weight: 650;
278
- color: var(--lp-ink);
279
- font-variant-numeric: tabular-nums;
280
- }
281
- /* Red = negative/over, the fixed semantic, on the deep companion. */
282
- .acct-meter-value.is-over {
283
- color: var(--lp-red-deep);
284
- }
285
- .acct-meter-of {
286
- font-size: var(--lp-fs-xs);
287
- color: var(--lp-muted);
288
- font-variant-numeric: tabular-nums;
289
- }
290
- .acct-meter-foot {
291
- display: flex;
292
- align-items: baseline;
293
- justify-content: space-between;
294
- gap: 12px;
295
- margin-top: 8px;
296
- font-size: var(--lp-fs-2xs);
297
- color: var(--lp-muted);
298
- }
299
- .acct-meter-calls {
300
- flex: 0 0 auto;
301
- font-variant-numeric: tabular-nums;
302
- }
303
-
304
- /* The track is the wash so an empty meter still reads as a meter rather than as a missing
305
- element; the fill is the brand at rest and red once the allowance is passed. */
306
- .acct-bar {
307
- display: block;
308
- width: 100%;
309
- height: 8px;
310
- margin-top: 10px;
311
- border-radius: var(--lp-r-pill);
312
- background: var(--lp-wash);
313
- overflow: hidden;
314
- }
315
- .acct-bar-fill {
316
- display: block;
317
- height: 100%;
318
- border-radius: var(--lp-r-pill);
319
- background: var(--lp-primary);
320
- transition: width 0.18s var(--lp-fold-e);
321
- }
322
- .acct-bar-fill.is-over {
323
- background: var(--lp-red-deep);
324
- }
325
-
326
- /* A short plain noun, muted, sentence case, matching `.home-section-title` exactly: the same role
327
- on a sibling surface takes the same rendered values (DESIGN.md 2). */
328
- .acct-section {
329
- margin: 22px 0 9px;
330
- font-size: var(--lp-fs-2xs);
331
- font-weight: 600;
332
- color: var(--lp-muted);
333
- }
334
- .acct-rows {
335
- display: flex;
336
- flex-direction: column;
337
- gap: 2px;
338
- }
339
- /* One row per surface: name, share bar, tokens, calls. Fixed columns so the four numbers form a
340
- column a reader can scan rather than four numbers at four different left edges. */
341
- .acct-row {
342
- display: grid;
343
- grid-template-columns: 120px 1fr 92px 150px;
344
- align-items: center;
345
- gap: 12px;
346
- padding: 8px 2px;
347
- border-bottom: 1px solid var(--lp-line);
348
- }
349
- .acct-row:last-child {
350
- border-bottom: 0;
351
- }
352
- .acct-row-name {
353
- font-size: var(--lp-fs-xs);
354
- font-weight: 600;
355
- color: var(--lp-ink);
356
- }
357
- /* Numbers right-aligned, text left (DESIGN.md 2), tabular so the column lines up digit for digit. */
358
- .acct-row-num {
359
- text-align: right;
360
- font-size: var(--lp-fs-xs);
361
- color: var(--lp-ink);
362
- font-variant-numeric: tabular-nums;
363
- }
364
- .acct-row-sub {
365
- font-size: var(--lp-fs-2xs);
366
- color: var(--lp-muted);
367
- font-variant-numeric: tabular-nums;
368
- }
369
- .acct-row .acct-bar {
370
- margin-top: 0;
371
- height: 6px;
372
- }
 
1
+ /* ─────────────────────────────────────────────────────────────────────────────────────────
2
+ account/account.css β€” WAVE 35, owner item 13: the three surfaces that hang off the
3
+ account button (Feedback, Usage, Subscription).
4
+
5
+ β›” ITS OWN STYLESHEET, NOT index.css. That file belongs to the INTEGRATOR for the whole
6
+ wave, and the wave's own rule is that a new surface brings its own sheet. Every selector
7
+ here is .acct-*; nothing in this file redefines a .home-*, .shell-* or .cg-* rule, so
8
+ nothing here can win or lose a source-order fight with the shared sheet.
9
+
10
+ ⚠ .acct-page RESTATES .shell-home's five box declarations rather than reusing that class,
11
+ and that is deliberate rather than lazy. .shell-home is Home's box by name and by its own
12
+ region header; borrowing it would make every future Home layout change silently a change
13
+ to three account pages. The VALUES are copied on purpose β€” DESIGN.md 2's sibling rule
14
+ ("a panel matches its sibling's rendered values, not merely the scale") is what makes the
15
+ account pages read as the same system as Home, and .shell-main is overflow:hidden, so a
16
+ page that does not own its own scroll box simply loses everything below the fold.
17
+
18
+ ⚠ EVERY font-size IS A --lp-fs-* TOKEN. verify_ui globs src/**.css (every stylesheet in
19
+ the tree, not just index.css) and goes RED on a literal β€” wave-21 R5.
20
+ ───────────────────────────────────────────────────────────────────────────────────────── */
21
+
22
+ .acct-page {
23
+ height: 100%;
24
+ overflow-y: auto;
25
+ padding: 34px 44px 56px;
26
+ box-sizing: border-box;
27
+ background: var(--lp-wash);
28
+ }
29
+
30
+ /* A short plain noun, same size and weight as .home-title, because it is the same role on a
31
+ sibling surface. DESIGN.md 2: headers are 1 to 3 words, never a sentence. */
32
+ .acct-title {
33
+ margin: 0 0 20px;
34
+ font-size: var(--lp-fs-lg);
35
+ font-weight: 650;
36
+ color: var(--lp-ink);
37
+ }
38
+
39
+ /* THE ONE COLUMN. Every account surface is a reading-width column, not a full-bleed page:
40
+ a composer, a meter list and a note are all narrow objects, and stretching them to a
41
+ 1600px window is how a page stops looking like it was designed. The reference the owner
42
+ gave for the assistant uses the same centred column for the same reason. */
43
+ .acct-col {
44
+ max-width: 640px;
45
+ }
46
+
47
+ /* ── the honest note (Subscription today; any boarded account surface tomorrow) ─────────
48
+ ONE containment layer: a hairline panel on the wash, no card inside a card, no shadow
49
+ (DESIGN.md 4). It is a panel rather than a bare paragraph so the emptiness reads as
50
+ deliberate instead of as a page that failed to load. */
51
+ .acct-note {
52
+ margin: 0;
53
+ padding: 16px 18px;
54
+ border: 1px solid var(--lp-line);
55
+ border-radius: var(--lp-r-md);
56
+ background: var(--lp-surface);
57
+ font-size: var(--lp-fs-xs);
58
+ line-height: var(--lp-lh);
59
+ color: var(--lp-muted);
60
+ }
61
+
62
+ /* ── loading, and the way back from a failed read ─────────────────────────────────────────── */
63
+ .acct-loading {
64
+ display: flex;
65
+ align-items: center;
66
+ justify-content: center;
67
+ min-height: 180px;
68
+ }
69
+ .acct-failed {
70
+ display: flex;
71
+ align-items: center;
72
+ gap: 12px;
73
+ }
74
+ /* DESIGN.md 4's quiet button, with the UA chrome reset explicitly (the wave-19 "mystery outer
75
+ lines and tinted fill" rule). */
76
+ .acct-retry {
77
+ flex: 0 0 auto;
78
+ padding: 6px 12px;
79
+ border: 1px solid var(--lp-line);
80
+ border-radius: var(--lp-r-md);
81
+ background: var(--lp-surface);
82
+ color: var(--lp-ink);
83
+ font: inherit;
84
+ font-size: var(--lp-fs-2xs);
85
+ font-weight: 600;
86
+ cursor: pointer;
87
+ }
88
+ .acct-retry:hover {
89
+ background: var(--lp-surface-2);
90
+ border-color: var(--lp-blue-deep);
91
+ }
92
+
93
+ /* ── the two answers a write can give ─────────────────────────────────────────────────────
94
+ Green = positive, red = negative: the fixed semantics (DESIGN.md 3), on the DEEP companions
95
+ because a pastel on white is not a light aesthetic, it is an unreadable one. */
96
+ .acct-ok,
97
+ .acct-error {
98
+ margin: 0 0 12px;
99
+ padding: 9px 12px;
100
+ border-radius: var(--lp-r-md);
101
+ font-size: var(--lp-fs-2xs);
102
+ line-height: var(--lp-lh);
103
+ }
104
+ .acct-ok {
105
+ border: 1px solid var(--lp-green);
106
+ background: var(--lp-green-tint);
107
+ color: var(--lp-green-deep);
108
+ }
109
+ .acct-error {
110
+ border: 1px solid var(--lp-red);
111
+ background: var(--lp-red-tint);
112
+ color: var(--lp-red-deep);
113
+ }
114
+
115
+ /* ── the composer ─────────────────────────────────────────────────────────────────────────
116
+ The ASSISTANT'S anatomy in this module's own rules: one rounded field that contains its own
117
+ control row, so the category and the send button read as part of the thing being written
118
+ rather than as chrome around it. `assistant.css` is another session's file this wave and is
119
+ deliberately not imported; the shape is borrowed, the rules are local.
120
+ ⚠ The radius is smaller than the assistant's 22px pill on purpose: this field is a paragraph
121
+ box, not a one-line prompt, and a heavily rounded tall box reads as a speech bubble. */
122
+ .acct-field {
123
+ border: 1px solid var(--lp-line);
124
+ border-radius: var(--lp-r-lg);
125
+ background: var(--lp-surface);
126
+ padding: 12px 10px 10px 14px;
127
+ }
128
+ .acct-field:focus-within {
129
+ border-color: var(--lp-blue-solid);
130
+ }
131
+ .acct-prompt {
132
+ display: block;
133
+ width: 100%;
134
+ border: 0;
135
+ outline: none;
136
+ padding: 0 6px 0 0;
137
+ background: transparent;
138
+ color: var(--lp-ink);
139
+ font: inherit;
140
+ font-size: var(--lp-fs-sm);
141
+ line-height: var(--lp-lh);
142
+ resize: vertical;
143
+ box-sizing: border-box;
144
+ }
145
+ .acct-prompt::placeholder {
146
+ color: var(--lp-muted);
147
+ }
148
+ .acct-field-foot {
149
+ display: flex;
150
+ align-items: center;
151
+ gap: 10px;
152
+ margin-top: 10px;
153
+ }
154
+ .acct-pick {
155
+ display: inline-flex;
156
+ align-items: center;
157
+ gap: 6px;
158
+ min-width: 0;
159
+ }
160
+ .acct-pick-label {
161
+ color: var(--lp-muted);
162
+ font-size: var(--lp-fs-2xs);
163
+ }
164
+ .acct-select {
165
+ max-width: 220px;
166
+ padding: 4px 8px;
167
+ border: 1px solid var(--lp-line);
168
+ border-radius: var(--lp-r-sm);
169
+ background: var(--lp-surface);
170
+ color: var(--lp-ink);
171
+ font: inherit;
172
+ font-size: var(--lp-fs-2xs);
173
+ cursor: pointer;
174
+ }
175
+ /* Tabular figures so the count does not jitter as it climbs. Red only once the limit is actually
176
+ passed: a counter that warns before anything is wrong trains people to ignore it. */
177
+ .acct-count {
178
+ color: var(--lp-muted);
179
+ font-size: var(--lp-fs-3xs);
180
+ font-variant-numeric: tabular-nums;
181
+ }
182
+ .acct-count.is-over {
183
+ color: var(--lp-red-deep);
184
+ font-weight: 600;
185
+ }
186
+ /* The send button takes the ink fill when it can send and the wash when it cannot, which is the
187
+ assistant's own rule: the control says whether there is anything to send before it is pressed. */
188
+ .acct-send {
189
+ flex: 0 0 auto;
190
+ margin-left: auto;
191
+ width: 30px;
192
+ height: 30px;
193
+ display: inline-flex;
194
+ align-items: center;
195
+ justify-content: center;
196
+ border: 0;
197
+ border-radius: var(--lp-r-pill);
198
+ background: var(--lp-ink);
199
+ color: var(--lp-surface);
200
+ font: inherit;
201
+ cursor: pointer;
202
+ }
203
+ .acct-send:disabled {
204
+ background: var(--lp-surface-2);
205
+ color: var(--lp-muted);
206
+ cursor: default;
207
+ }
208
+ .acct-send-icon {
209
+ fill: none;
210
+ stroke: currentColor;
211
+ stroke-width: 1.7;
212
+ stroke-linecap: round;
213
+ stroke-linejoin: round;
214
+ }
215
+
216
+ /* ── the usage meter (R9) ─────────────────────────────────────────────────────────────────
217
+ One containment layer, hairline, no shadow. The bar is the only new SHAPE on these pages, and
218
+ the ticket asks for it by name ("over the allowance the bar is red"). */
219
+ .acct-note--inline {
220
+ margin: 12px 0 0;
221
+ padding: 9px 12px;
222
+ font-size: var(--lp-fs-2xs);
223
+ }
224
+ .acct-scope {
225
+ display: inline-flex;
226
+ gap: 2px;
227
+ margin-bottom: 14px;
228
+ padding: 2px;
229
+ border: 1px solid var(--lp-line);
230
+ border-radius: var(--lp-r-md);
231
+ background: var(--lp-surface);
232
+ }
233
+ /* Selection is TINT plus WEIGHT with the ink left alone, which is `.shell-nav-item.is-active`'s
234
+ rule. ⚠ NOT `--lp-blue-deep` on `--lp-blue-tint`: that pair measures 2.96:1, under the 4.5:1
235
+ text bar and under the 3:1 graphical one, and this control holds words. */
236
+ .acct-scope-btn {
237
+ padding: 4px 12px;
238
+ border: 0;
239
+ border-radius: var(--lp-r-sm);
240
+ background: transparent;
241
+ color: var(--lp-muted);
242
+ font: inherit;
243
+ font-size: var(--lp-fs-2xs);
244
+ font-weight: 600;
245
+ cursor: pointer;
246
+ }
247
+ .acct-scope-btn:hover {
248
+ background: var(--lp-surface-2);
249
+ }
250
+ .acct-scope-btn.is-on {
251
+ background: var(--lp-blue-tint);
252
+ color: var(--lp-ink);
253
+ }
254
+
255
+ .acct-meter {
256
+ padding: 16px 18px;
257
+ border: 1px solid var(--lp-line);
258
+ border-radius: var(--lp-r-md);
259
+ background: var(--lp-surface);
260
+ }
261
+ .acct-meter-head {
262
+ display: flex;
263
+ align-items: baseline;
264
+ gap: 8px;
265
+ flex-wrap: wrap;
266
+ }
267
+ .acct-meter-who {
268
+ font-size: var(--lp-fs-2xs);
269
+ font-weight: 600;
270
+ color: var(--lp-muted);
271
+ margin-bottom: 4px;
272
+ }
273
+ /* Tabular figures on every financial-grade number (DESIGN.md 2), so a total that climbs does not
274
+ make the label beside it dance. Weight 650, never a display weight. */
275
+ .acct-meter-value {
276
+ font-size: var(--lp-fs-xl);
277
+ font-weight: 650;
278
+ color: var(--lp-ink);
279
+ font-variant-numeric: tabular-nums;
280
+ }
281
+ /* Red = negative/over, the fixed semantic, on the deep companion. */
282
+ .acct-meter-value.is-over {
283
+ color: var(--lp-red-deep);
284
+ }
285
+ .acct-meter-of {
286
+ font-size: var(--lp-fs-xs);
287
+ color: var(--lp-muted);
288
+ font-variant-numeric: tabular-nums;
289
+ }
290
+ .acct-meter-foot {
291
+ display: flex;
292
+ align-items: baseline;
293
+ justify-content: space-between;
294
+ gap: 12px;
295
+ margin-top: 8px;
296
+ font-size: var(--lp-fs-2xs);
297
+ color: var(--lp-muted);
298
+ }
299
+ .acct-meter-calls {
300
+ flex: 0 0 auto;
301
+ font-variant-numeric: tabular-nums;
302
+ }
303
+
304
+ /* The track is the wash so an empty meter still reads as a meter rather than as a missing
305
+ element; the fill is the brand at rest and red once the allowance is passed. */
306
+ .acct-bar {
307
+ display: block;
308
+ width: 100%;
309
+ height: 8px;
310
+ margin-top: 10px;
311
+ border-radius: var(--lp-r-pill);
312
+ background: var(--lp-wash);
313
+ overflow: hidden;
314
+ }
315
+ .acct-bar-fill {
316
+ display: block;
317
+ height: 100%;
318
+ border-radius: var(--lp-r-pill);
319
+ background: var(--lp-primary);
320
+ transition: width 0.18s var(--lp-fold-e);
321
+ }
322
+ .acct-bar-fill.is-over {
323
+ background: var(--lp-red-deep);
324
+ }
325
+
326
+ /* A short plain noun, muted, sentence case, matching `.home-section-title` exactly: the same role
327
+ on a sibling surface takes the same rendered values (DESIGN.md 2). */
328
+ .acct-section {
329
+ margin: 22px 0 9px;
330
+ font-size: var(--lp-fs-2xs);
331
+ font-weight: 600;
332
+ color: var(--lp-muted);
333
+ }
334
+ .acct-rows {
335
+ display: flex;
336
+ flex-direction: column;
337
+ gap: 2px;
338
+ }
339
+ /* One row per surface: name, share bar, tokens, calls. Fixed columns so the four numbers form a
340
+ column a reader can scan rather than four numbers at four different left edges. */
341
+ .acct-row {
342
+ display: grid;
343
+ grid-template-columns: 120px 1fr 92px 150px;
344
+ align-items: center;
345
+ gap: 12px;
346
+ padding: 8px 2px;
347
+ border-bottom: 1px solid var(--lp-line);
348
+ }
349
+ .acct-row:last-child {
350
+ border-bottom: 0;
351
+ }
352
+ .acct-row-name {
353
+ font-size: var(--lp-fs-xs);
354
+ font-weight: 600;
355
+ color: var(--lp-ink);
356
+ }
357
+ /* Numbers right-aligned, text left (DESIGN.md 2), tabular so the column lines up digit for digit. */
358
+ .acct-row-num {
359
+ text-align: right;
360
+ font-size: var(--lp-fs-xs);
361
+ color: var(--lp-ink);
362
+ font-variant-numeric: tabular-nums;
363
+ }
364
+ .acct-row-sub {
365
+ font-size: var(--lp-fs-2xs);
366
+ color: var(--lp-muted);
367
+ font-variant-numeric: tabular-nums;
368
+ }
369
+ .acct-row .acct-bar {
370
+ margin-top: 0;
371
+ height: 6px;
372
+ }
web/src/account/accountApi.ts CHANGED
@@ -1,188 +1,188 @@
1
- // ---------------------------------------------------------------------------
2
- // account/accountApi.ts β€” WAVE 35, owner item 13: the wire behind the two account
3
- // surfaces that have one (Feedback, contract C6/R8; Usage, C7/R9).
4
- //
5
- // β›” THE CATEGORY VOCABULARY IS THE SERVER'S AND IS FETCHED, NOT DECLARED HERE.
6
- // That is a decision, not an omission: a client constant beside a server enum is
7
- // two lists that drift, and the day they do the dropdown offers a value the door
8
- // refuses. Asked and settled in mailbox B-1 / E-9 β€” the server serves the list,
9
- // this file renders it, and there is no local fallback to drift TO.
10
- //
11
- // β›” AND THERE IS NO TENANT-SIDE READ OF A SUBMISSION AT ALL (R8). No "my
12
- // feedback" list, no edit, no delete: the operator plane is the only reader. The
13
- // 201 is the receipt. If that ever feels like a gap, it is R8, not a missing
14
- // endpoint.
15
- //
16
- // ⚠ NOTHING ON THE USAGE SIDE IS COMPUTED HERE. The allowance, the week and the
17
- // reset date all ride the payload (E-9), because a week boundary computed in the
18
- // browser can disagree with the server's own bucketing β€” and then the page shows
19
- // a number that traces to no ledger line, which is exactly what R9's meter must
20
- // never do.
21
- // ---------------------------------------------------------------------------
22
-
23
- import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
24
-
25
- /** The same discriminated result the other feature modules use. */
26
- export type Result<T> =
27
- | { ok: true; value: T }
28
- | { ok: false; status: number; message: string };
29
-
30
- async function call<T>(
31
- path: string,
32
- init: RequestInit,
33
- read: (body: unknown) => T
34
- ): Promise<Result<T>> {
35
- let res: Response;
36
- try {
37
- res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init });
38
- } catch {
39
- return { ok: false, status: 0, message: "Cannot reach the server." };
40
- }
41
- if (checkTenant(res)) return { ok: false, status: 0, message: "Reloading." };
42
- if (res.status === 401) signal(UNAUTHORIZED_EVENT);
43
- const body = (await res.json().catch(() => null)) as unknown;
44
- if (!res.ok) {
45
- // ⚠ A 4xx MESSAGE IS POLICY AND IS SHOWN; a 5xx message is an internal detail and is not.
46
- // `session.ts` states the same rule for sign-in, and E names each 400 case ("unknown
47
- // category", "empty text", "over maxChars"), so the server's sentence is the useful one.
48
- const detail = (body as { error?: { message?: string } } | null)?.error?.message;
49
- return {
50
- ok: false,
51
- status: res.status,
52
- message:
53
- res.status >= 500 || !detail
54
- ? res.status >= 500
55
- ? "Something went wrong on our side. Try again in a moment."
56
- : `The server answered ${res.status}.`
57
- : detail,
58
- };
59
- }
60
- return { ok: true, value: read(body) };
61
- }
62
-
63
- const row = (v: unknown): Record<string, unknown> =>
64
- v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
65
- const str = (v: unknown): string => (typeof v === "string" ? v : "");
66
- const int = (v: unknown): number =>
67
- typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
68
-
69
- // ── FEEDBACK (R8, C6) ───────────────────────────────────────────────────────────────────────
70
-
71
- export interface FeedbackCategory {
72
- key: string;
73
- label: string;
74
- }
75
-
76
- export interface FeedbackForm {
77
- categories: FeedbackCategory[];
78
- maxChars: number;
79
- }
80
-
81
- /**
82
- * `GET /api/v1/feedback/form` β€” the category list and the length limit, both the server's.
83
- *
84
- * β›” A CATEGORY WITH NO LABEL IS DROPPED, never rendered as its key: an internal identifier in a
85
- * dropdown is the same defect `parsePages` refuses one layer up ("a nav row with no name is a
86
- * door with no sign on it"). And an EMPTY list is a real answer the caller must handle, not a
87
- * reason to invent one.
88
- */
89
- export function parseFeedbackForm(body: unknown): FeedbackForm {
90
- const r = row(body);
91
- const categories = (Array.isArray(r.categories) ? r.categories : [])
92
- .map(row)
93
- .filter((c) => str(c.key) !== "" && str(c.label) !== "")
94
- .map((c) => ({ key: str(c.key), label: str(c.label) }));
95
- return { categories, maxChars: int(r.maxChars) };
96
- }
97
-
98
- export function loadFeedbackForm(): Promise<Result<FeedbackForm>> {
99
- return call("/feedback/form", {}, parseFeedbackForm);
100
- }
101
-
102
- export function sendFeedback(category: string, text: string): Promise<Result<{ id: string }>> {
103
- return call(
104
- "/feedback",
105
- {
106
- method: "POST",
107
- headers: { "Content-Type": "application/json" },
108
- body: JSON.stringify({ category, text }),
109
- },
110
- (b) => ({ id: str(row(b).id) })
111
- );
112
- }
113
-
114
- // ── USAGE (R9, C7) ──────────────────────────────────────────────────────────────────────────
115
-
116
- /** One AI surface's week. Every surface is present at zero when unused (E-9), so nothing here
117
- * branches on a missing row. */
118
- export interface UsageSurface {
119
- surface: string;
120
- calls: number;
121
- tokens: number;
122
- tokensIn: number;
123
- tokensOut: number;
124
- /**
125
- * Calls whose provider declined to report a token count.
126
- *
127
- * β›” NOT ZERO-PADDING. These are real calls with an UNKNOWN cost, which is why the total beside
128
- * them is a FLOOR rather than a figure. A page that hides this presents the floor as complete,
129
- * and that is the cost-surprise failure one step removed.
130
- */
131
- unmeasured: number;
132
- }
133
-
134
- export interface Usage {
135
- /** ISO year-week, UTC. A string that sorts chronologically, so nothing here parses a date. */
136
- week: string;
137
- /** The UTC date the counters roll over, as the server states it. */
138
- resets: string;
139
- allowance: number;
140
- total: number;
141
- over: boolean;
142
- calls: number;
143
- unmeasured: number;
144
- /** `"me"` or `"tenant"`. Which question the numbers answer, decided by the server. */
145
- scope: string;
146
- surfaces: UsageSurface[];
147
- /** The server's own sentence about `unmeasured`. Empty when there is nothing unmeasured. */
148
- note: string;
149
- /**
150
- * Admin only: AI calls this container could not attribute to an account.
151
- *
152
- * ⚠ LABEL IT A WIRING GAP, NOT USAGE (E-9). It is the meter reporting on ITSELF, and folding it
153
- * into somebody's total would be an invented attribution.
154
- */
155
- unattributed: number;
156
- }
157
-
158
- export function parseUsage(body: unknown): Usage {
159
- const r = row(body);
160
- const surfaces = (Array.isArray(r.surfaces) ? r.surfaces : [])
161
- .map(row)
162
- .filter((s) => str(s.surface) !== "")
163
- .map((s) => ({
164
- surface: str(s.surface),
165
- calls: int(s.calls),
166
- tokens: int(s.tokens),
167
- tokensIn: int(s.tokens_in),
168
- tokensOut: int(s.tokens_out),
169
- unmeasured: int(s.unmeasured),
170
- }));
171
- return {
172
- week: str(r.week),
173
- resets: str(r.resets),
174
- allowance: int(r.allowance),
175
- total: int(r.total),
176
- over: r.over === true,
177
- calls: int(r.calls),
178
- unmeasured: int(r.unmeasured),
179
- scope: str(r.scope) || "me",
180
- surfaces,
181
- note: str(r.note),
182
- unattributed: int(r.unattributed),
183
- };
184
- }
185
-
186
- export function loadUsage(scope?: "tenant"): Promise<Result<Usage>> {
187
- return call(scope === "tenant" ? "/usage?scope=tenant" : "/usage", {}, parseUsage);
188
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // account/accountApi.ts β€” WAVE 35, owner item 13: the wire behind the two account
3
+ // surfaces that have one (Feedback, contract C6/R8; Usage, C7/R9).
4
+ //
5
+ // β›” THE CATEGORY VOCABULARY IS THE SERVER'S AND IS FETCHED, NOT DECLARED HERE.
6
+ // That is a decision, not an omission: a client constant beside a server enum is
7
+ // two lists that drift, and the day they do the dropdown offers a value the door
8
+ // refuses. Asked and settled in mailbox B-1 / E-9 β€” the server serves the list,
9
+ // this file renders it, and there is no local fallback to drift TO.
10
+ //
11
+ // β›” AND THERE IS NO TENANT-SIDE READ OF A SUBMISSION AT ALL (R8). No "my
12
+ // feedback" list, no edit, no delete: the operator plane is the only reader. The
13
+ // 201 is the receipt. If that ever feels like a gap, it is R8, not a missing
14
+ // endpoint.
15
+ //
16
+ // ⚠ NOTHING ON THE USAGE SIDE IS COMPUTED HERE. The allowance, the week and the
17
+ // reset date all ride the payload (E-9), because a week boundary computed in the
18
+ // browser can disagree with the server's own bucketing β€” and then the page shows
19
+ // a number that traces to no ledger line, which is exactly what R9's meter must
20
+ // never do.
21
+ // ---------------------------------------------------------------------------
22
+
23
+ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
24
+
25
+ /** The same discriminated result the other feature modules use. */
26
+ export type Result<T> =
27
+ | { ok: true; value: T }
28
+ | { ok: false; status: number; message: string };
29
+
30
+ async function call<T>(
31
+ path: string,
32
+ init: RequestInit,
33
+ read: (body: unknown) => T
34
+ ): Promise<Result<T>> {
35
+ let res: Response;
36
+ try {
37
+ res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init });
38
+ } catch {
39
+ return { ok: false, status: 0, message: "Cannot reach the server." };
40
+ }
41
+ if (checkTenant(res)) return { ok: false, status: 0, message: "Reloading." };
42
+ if (res.status === 401) signal(UNAUTHORIZED_EVENT);
43
+ const body = (await res.json().catch(() => null)) as unknown;
44
+ if (!res.ok) {
45
+ // ⚠ A 4xx MESSAGE IS POLICY AND IS SHOWN; a 5xx message is an internal detail and is not.
46
+ // `session.ts` states the same rule for sign-in, and E names each 400 case ("unknown
47
+ // category", "empty text", "over maxChars"), so the server's sentence is the useful one.
48
+ const detail = (body as { error?: { message?: string } } | null)?.error?.message;
49
+ return {
50
+ ok: false,
51
+ status: res.status,
52
+ message:
53
+ res.status >= 500 || !detail
54
+ ? res.status >= 500
55
+ ? "Something went wrong on our side. Try again in a moment."
56
+ : `The server answered ${res.status}.`
57
+ : detail,
58
+ };
59
+ }
60
+ return { ok: true, value: read(body) };
61
+ }
62
+
63
+ const row = (v: unknown): Record<string, unknown> =>
64
+ v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
65
+ const str = (v: unknown): string => (typeof v === "string" ? v : "");
66
+ const int = (v: unknown): number =>
67
+ typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
68
+
69
+ // ── FEEDBACK (R8, C6) ───────────────────────────────────────────────────────────────────────
70
+
71
+ export interface FeedbackCategory {
72
+ key: string;
73
+ label: string;
74
+ }
75
+
76
+ export interface FeedbackForm {
77
+ categories: FeedbackCategory[];
78
+ maxChars: number;
79
+ }
80
+
81
+ /**
82
+ * `GET /api/v1/feedback/form` β€” the category list and the length limit, both the server's.
83
+ *
84
+ * β›” A CATEGORY WITH NO LABEL IS DROPPED, never rendered as its key: an internal identifier in a
85
+ * dropdown is the same defect `parsePages` refuses one layer up ("a nav row with no name is a
86
+ * door with no sign on it"). And an EMPTY list is a real answer the caller must handle, not a
87
+ * reason to invent one.
88
+ */
89
+ export function parseFeedbackForm(body: unknown): FeedbackForm {
90
+ const r = row(body);
91
+ const categories = (Array.isArray(r.categories) ? r.categories : [])
92
+ .map(row)
93
+ .filter((c) => str(c.key) !== "" && str(c.label) !== "")
94
+ .map((c) => ({ key: str(c.key), label: str(c.label) }));
95
+ return { categories, maxChars: int(r.maxChars) };
96
+ }
97
+
98
+ export function loadFeedbackForm(): Promise<Result<FeedbackForm>> {
99
+ return call("/feedback/form", {}, parseFeedbackForm);
100
+ }
101
+
102
+ export function sendFeedback(category: string, text: string): Promise<Result<{ id: string }>> {
103
+ return call(
104
+ "/feedback",
105
+ {
106
+ method: "POST",
107
+ headers: { "Content-Type": "application/json" },
108
+ body: JSON.stringify({ category, text }),
109
+ },
110
+ (b) => ({ id: str(row(b).id) })
111
+ );
112
+ }
113
+
114
+ // ── USAGE (R9, C7) ──────────────────────────────────────────────────────────────────────────
115
+
116
+ /** One AI surface's week. Every surface is present at zero when unused (E-9), so nothing here
117
+ * branches on a missing row. */
118
+ export interface UsageSurface {
119
+ surface: string;
120
+ calls: number;
121
+ tokens: number;
122
+ tokensIn: number;
123
+ tokensOut: number;
124
+ /**
125
+ * Calls whose provider declined to report a token count.
126
+ *
127
+ * β›” NOT ZERO-PADDING. These are real calls with an UNKNOWN cost, which is why the total beside
128
+ * them is a FLOOR rather than a figure. A page that hides this presents the floor as complete,
129
+ * and that is the cost-surprise failure one step removed.
130
+ */
131
+ unmeasured: number;
132
+ }
133
+
134
+ export interface Usage {
135
+ /** ISO year-week, UTC. A string that sorts chronologically, so nothing here parses a date. */
136
+ week: string;
137
+ /** The UTC date the counters roll over, as the server states it. */
138
+ resets: string;
139
+ allowance: number;
140
+ total: number;
141
+ over: boolean;
142
+ calls: number;
143
+ unmeasured: number;
144
+ /** `"me"` or `"tenant"`. Which question the numbers answer, decided by the server. */
145
+ scope: string;
146
+ surfaces: UsageSurface[];
147
+ /** The server's own sentence about `unmeasured`. Empty when there is nothing unmeasured. */
148
+ note: string;
149
+ /**
150
+ * Admin only: AI calls this container could not attribute to an account.
151
+ *
152
+ * ⚠ LABEL IT A WIRING GAP, NOT USAGE (E-9). It is the meter reporting on ITSELF, and folding it
153
+ * into somebody's total would be an invented attribution.
154
+ */
155
+ unattributed: number;
156
+ }
157
+
158
+ export function parseUsage(body: unknown): Usage {
159
+ const r = row(body);
160
+ const surfaces = (Array.isArray(r.surfaces) ? r.surfaces : [])
161
+ .map(row)
162
+ .filter((s) => str(s.surface) !== "")
163
+ .map((s) => ({
164
+ surface: str(s.surface),
165
+ calls: int(s.calls),
166
+ tokens: int(s.tokens),
167
+ tokensIn: int(s.tokens_in),
168
+ tokensOut: int(s.tokens_out),
169
+ unmeasured: int(s.unmeasured),
170
+ }));
171
+ return {
172
+ week: str(r.week),
173
+ resets: str(r.resets),
174
+ allowance: int(r.allowance),
175
+ total: int(r.total),
176
+ over: r.over === true,
177
+ calls: int(r.calls),
178
+ unmeasured: int(r.unmeasured),
179
+ scope: str(r.scope) || "me",
180
+ surfaces,
181
+ note: str(r.note),
182
+ unattributed: int(r.unattributed),
183
+ };
184
+ }
185
+
186
+ export function loadUsage(scope?: "tenant"): Promise<Result<Usage>> {
187
+ return call(scope === "tenant" ? "/usage?scope=tenant" : "/usage", {}, parseUsage);
188
+ }
web/src/alerts/alertsModel.ts CHANGED
@@ -1,418 +1,418 @@
1
- // ---------------------------------------------------------------------------
2
- // alerts/alertsModel.ts β€” WAVE 20 item 25 (contract C-ALERT): the inbox's PURE
3
- // half. React-free and fetch-free, so `verify_alerts.py` runs it under node.
4
- //
5
- // An alert says "tell me when a record ENTERS this view". The client half is
6
- // small, and every part of it fails silently when it is wrong:
7
- //
8
- // Β· an unread count taken from `items.length` rather than from the server's
9
- // own `unread` disagrees with the badge the moment a page is capped or a
10
- // read lands in another tab β€” and a badge that says 3 when the list shows 9
11
- // teaches the reader to ignore the badge;
12
- // Β· a notification whose `viewId` no longer resolves must open NOTHING rather
13
- // than a wrong view β€” alerts outlive the views they were made from;
14
- // Β· `topic` is the surface's scope key ("customer", "product", "ut_…"), and
15
- // the ROUTE is a registry key ("customer_data") β€” mapping one to the other
16
- // by guesswork sends every click to a page that does not exist.
17
- // ---------------------------------------------------------------------------
18
-
19
- /**
20
- * ⭐⭐ WAVE 32 Β· T20 Β· CONTRACT C3 β€” WHERE AN INBOX ITEM OPENS.
21
- *
22
- * `module` is the destination surface (`"database"` or `"automation"`) and `id` is what to open
23
- * in it. `tab` is the SUB-SELECTION inside that module: the literal `"runs"` for an automation's
24
- * run log, or the VIEW ID to select on a database. One optional key, two destinations.
25
- *
26
- * β›” EVERY FIELD IS A PLAIN `string`, NEVER A UNION, and that is alertsModel's wave-9 law rather
27
- * than laziness: the vocabulary is the SERVER's, and a client union over it turns "the server grew
28
- * a module" into "the client silently drops the row". An unknown module is refused by the
29
- * FRAME's dispatcher, out loud, which is a different thing from never arriving.
30
- */
31
- export interface NotificationTarget {
32
- module: string;
33
- id: string;
34
- tab?: string;
35
- }
36
-
37
- /** C3's `kind` vocabulary, mirroring `routes_alerts.NOTIF_KIND_*`. Held as constants so the
38
- * Inbox's branch and the gate's fixtures cannot disagree about the word. */
39
- export const NOTIF_KIND_ALERT = "alert";
40
- export const NOTIF_KIND_AUTOMATION = "automation";
41
- export const NOTIF_KIND_SHARE = "share";
42
-
43
- /** C3's `target.module` vocabulary, and the automation sub-selection. */
44
- export const TARGET_MODULE_DATABASE = "database";
45
- export const TARGET_MODULE_AUTOMATION = "automation";
46
- export const TARGET_TAB_RUNS = "runs";
47
-
48
- /** One notification, as `GET /api/v1/notifications` sends it. */
49
- export interface Notification {
50
- id: string;
51
- alertId: string;
52
- viewId: string;
53
- topic: string;
54
- rowId: string;
55
- /** What entered β€” the record's own label. */
56
- label: string;
57
- /** What the alert is called, so a row reads without opening anything. */
58
- alertLabel: string;
59
- /** UTC WITH OFFSET (D-18). Kept as the server's STRING: re-formatting it here
60
- * would re-introduce the browser-clock drift the offset exists to remove. */
61
- at: string;
62
- read: boolean;
63
- /**
64
- * WAVE 23 (contract C6) β€” WHAT KIND of notification this is.
65
- *
66
- * Absent (and every notification written before this wave) means the original one: a record
67
- * ENTERED a watched view, routed by `topic` + `viewId`. `"automation_review"` means a card
68
- * arrived at a review stage and routes by `autoId` instead β€” a different destination reached
69
- * from the same list.
70
- *
71
- * β›” A STRING, NEVER A UNION, and that is the wave-9 law rather than laziness: the vocabulary
72
- * is the SERVER's, and a client union over it turns "the server grew a kind" into "the client
73
- * silently drops the row". Unknown kinds fall through to the view route, which is exactly what
74
- * they did before this field existed.
75
- */
76
- kind?: string;
77
- /** `automation_review` only: the automation whose review stage a card reached. Absent on
78
- * every other kind β€” and an `automation_review` row that arrives WITHOUT one opens nothing
79
- * rather than guessing, the same posture `viewId` gets. */
80
- autoId?: string;
81
- /** Advisory. A surface that does not scroll to a stage simply selects the automation. */
82
- stageId?: string;
83
- /** How many cards arrived in the batch. C6 queues ONE notification per run naming the count,
84
- * never one per record β€” so this is the number the row's own text is built from. */
85
- count?: number;
86
- /**
87
- * ⭐ WAVE 32 Β· C3 β€” THE HEADER LINE, so the Inbox can be laid out like mail.
88
- *
89
- * `subject` is what the item is ABOUT (the alert's name, the automation's name, the database
90
- * that was shared); `label` stays what HAPPENED (the record that entered, the run summary).
91
- * They were one field, which is why the pane could only ever render a sentence with no sender.
92
- * Absent on a server that predates this wave β€” {@link subjectOf} falls back rather than
93
- * rendering a blank header.
94
- */
95
- subject?: string;
96
- /**
97
- * ⭐⭐ WAVE 33 Β· W33-T28 β€” WHO IT IS FROM. Mail has a sender; this list did not.
98
- *
99
- * A `verifier` reading the finished wave-32 Inbox found the row's sender POSITION occupied by
100
- * `kindLabel(n.kind)` β€” the literals "Alert" / "Automation" / "Shared with you", a CATEGORY
101
- * standing where a who belongs β€” and no sender anywhere on the wire. Derived by the server
102
- * (`routes_alerts.notification_view`), never here: only it knows that a share has a person
103
- * behind it and an alert has a machine.
104
- * ⚠ Optional, so a payload from a server that predates this wave keeps today's shape;
105
- * {@link senderOf} falls back rather than rendering a blank From column.
106
- */
107
- sender?: string;
108
- /** ⭐ WAVE 32 Β· C3 β€” where clicking it goes. ABSENT when this product cannot resolve a
109
- * destination (an alert on a table this account can no longer route to), and that absence is
110
- * load-bearing: the Inbox renders such a row as plainly unclickable rather than as a click
111
- * that silently does nothing. */
112
- target?: NotificationTarget;
113
- }
114
-
115
- /** One alert, as `GET /api/v1/alerts` sends it. */
116
- export interface Alert {
117
- id: string;
118
- viewId: string;
119
- topic: string;
120
- owner: string;
121
- label: string;
122
- createdAt: string;
123
- /** How many records are in its remembered set right now. */
124
- matched: number;
125
- seeded: boolean;
126
- lastRunAt: string;
127
- lastError: string;
128
- }
129
-
130
- export interface Inbox {
131
- unread: number;
132
- items: Notification[];
133
- /**
134
- * ⭐⭐ WAVE 33 Β· W33-T28 / D-208 β€” THE SERVER'S CLOCK, so a stamp can be mail-shaped.
135
- *
136
- * β›” It exists so {@link stampText} never reads the BROWSER's clock, which is D-208's exit
137
- * condition word for word. `at` is UTC with its offset (D-18) precisely so every reader sees
138
- * the same instant; asking "is this today?" of a local clock would put the drift back.
139
- * ⚠ Optional: absent, `stampText` returns the old absolute string rather than guessing.
140
- */
141
- now?: string;
142
- }
143
-
144
- export const EMPTY_INBOX: Inbox = { unread: 0, items: [] };
145
-
146
- /**
147
- * ⭐⭐ WAVE 31 Β· T23 (owner item 1) β€” WHAT THE PANE IS ENTITLED TO SAY, AS A FUNCTION.
148
- *
149
- * Owner, verbatim: *"Alerts shows notification, but when clicked it says nothing, and it doesn't
150
- * remove the notification number."* Both halves are ONE mechanism. `AlertsPane` held its own
151
- * `inbox` seeded to {@link EMPTY_INBOX} and had no pending state, so between opening the panel
152
- * and `GET /notifications` answering β€” measured at **3,280 ms live** β€” and for ever after a
153
- * failed fetch:
154
- * Β· `items` was `[]`, so the pane printed **"Nothing new."** β€” a claim, not a wait;
155
- * Β· `unread` was `0`, so **"Mark all read" was `disabled`**, and the badge the frame had
156
- * already loaded could never be cleared.
157
- * A confident sentence about somebody's inbox, and the one control that would fix it, both
158
- * switched off by the same uninitialised state.
159
- *
160
- * β›” IT IS A FUNCTION BECAUSE THE PANE IS TSX AND TSX IS NOT UNDER TEST HERE. `verify_alerts`
161
- * compiles and RUNS this module under node; markup it cannot reach is markup no control can
162
- * mutate. Deciding here means the truth table is asserted and each branch is load-bearing.
163
- */
164
- export type PaneView = "pending" | "rows" | "empty" | "error";
165
-
166
- /**
167
- * `pending` while the first read is in flight Β· `error` when it failed and we have nothing to
168
- * show Β· `rows` when there is something Β· `empty` ONLY when a successful read returned nothing.
169
- *
170
- * ⚠ ROWS WIN OVER AN ERROR, and that is deliberate rather than lax: a refresh that fails while
171
- * the pane already holds notifications should not blank them β€” the reader loses real information
172
- * to a transient. The error still reaches them as the pane's message line.
173
- */
174
- export function paneView(
175
- phase: "pending" | "ready" | "error",
176
- rowCount: number,
177
- seededUnread = 0
178
- ): PaneView {
179
- if (rowCount > 0) return "rows";
180
- if (phase === "pending") return "pending";
181
- if (phase === "error") return "error";
182
- // ⚠ A SUCCESSFUL READ WITH NO ROWS AND A NON-ZERO COUNT IS NOT "nothing new". The badge says
183
- // there is something; the page we were given does not contain it. Saying "Nothing new" there
184
- // is the same false confidence in a different costume.
185
- return seededUnread > 0 ? "error" : "empty";
186
- }
187
-
188
- /**
189
- * May "Mark all read" be pressed?
190
- *
191
- * β›” NOT `unread === 0`, WHICH IS THE SHIPPED BUG. That test asked the PANE's own state β€” zero
192
- * until its fetch lands, zero for ever if the fetch fails β€” so the control was dead in exactly
193
- * the situations the owner hit. The question is about the ACCOUNT, so it is asked of the count
194
- * the frame already holds, and a failed read does not take the verb away: `POST /notifications/
195
- * read` with `ids: null` clears the account's inbox whether or not we managed to list it.
196
- */
197
- export function canMarkAll(unread: number, busy = false): boolean {
198
- return !busy && Math.max(0, Math.floor(unread)) > 0;
199
- }
200
-
201
- const str = (v: unknown): string => (typeof v === "string" ? v : "");
202
- const num = (v: unknown): number => (typeof v === "number" && isFinite(v) ? v : 0);
203
-
204
- /**
205
- * ⭐ WAVE 32 Β· C3 β€” one wire `target` β†’ a {@link NotificationTarget}, or `null`.
206
- *
207
- * β›” BOTH `module` AND `id` ARE REQUIRED, and dropping either test is the failure this guard is
208
- * for: a target with a module and no id dispatches an open request naming NOTHING β€” a click that
209
- * appears to work and silently does not, which is this repo's most-repeated shape. `null` is
210
- * rendered as an unclickable row, which a reader can SEE.
211
- */
212
- export function parseTarget(raw: unknown): NotificationTarget | null {
213
- if (!raw || typeof raw !== "object") return null;
214
- const t = raw as Record<string, unknown>;
215
- const module = str(t.module).trim();
216
- const id = str(t.id).trim();
217
- if (!module || !id) return null;
218
- const tab = str(t.tab).trim();
219
- return { module, id, ...(tab ? { tab } : {}) };
220
- }
221
-
222
- /**
223
- * `GET /notifications` β†’ the inbox, fail-closed.
224
- *
225
- * ⚠ `unread` COMES FROM THE SERVER, and is not recounted from `items`. The two
226
- * can legitimately differ β€” the list is what this page holds, the count is what
227
- * the account has β€” and recomputing it here would make the badge a function of
228
- * whatever the last fetch happened to include.
229
- */
230
- export function parseInbox(body: unknown): Inbox {
231
- const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
232
- const raw = Array.isArray(b.items) ? b.items : [];
233
- const items: Notification[] = [];
234
- for (const item of raw) {
235
- if (!item || typeof item !== "object") continue;
236
- const n = item as Record<string, unknown>;
237
- const id = str(n.id);
238
- // An id-less notification cannot be marked read, so it would sit unread for
239
- // ever and hold the badge up. Dropped, not rendered.
240
- if (!id) continue;
241
- items.push({
242
- id,
243
- alertId: str(n.alertId),
244
- viewId: str(n.viewId),
245
- topic: str(n.topic),
246
- rowId: String(n.rowId ?? ""),
247
- label: str(n.label) || String(n.rowId ?? ""),
248
- alertLabel: str(n.alertLabel),
249
- at: str(n.at),
250
- read: n.read === true,
251
- // WAVE 23 C6 β€” ADDITIVE and spread-conditional, exactly like `NavPage`'s flags: a payload
252
- // that predates this wave keeps today's shape rather than gaining four `undefined` keys,
253
- // and an `automation_review` row missing its `autoId` is left WITHOUT one rather than
254
- // with an empty string that would render as a real destination.
255
- ...(str(n.kind) ? { kind: str(n.kind) } : {}),
256
- ...(str(n.autoId) ? { autoId: str(n.autoId) } : {}),
257
- ...(str(n.stageId) ? { stageId: str(n.stageId) } : {}),
258
- ...(num(n.count) > 0 ? { count: num(n.count) } : {}),
259
- // ⭐ WAVE 32 Β· C3 β€” additive and spread-conditional, exactly like the four above.
260
- ...(str(n.subject) ? { subject: str(n.subject) } : {}),
261
- // ⭐ WAVE 33 Β· W33-T28 β€” additive and spread-conditional, like every flag above it.
262
- ...(str(n.sender) ? { sender: str(n.sender) } : {}),
263
- ...(parseTarget(n.target) ? { target: parseTarget(n.target)! } : {}),
264
- });
265
- }
266
- // ⭐ W33-T28 / D-208 β€” the server's clock rides through, spread-conditionally like every other
267
- // additive key here, so a server that predates this wave yields the same object it always did.
268
- return {
269
- unread: Math.max(0, num(b.unread)),
270
- items,
271
- ...(str(b.now) ? { now: str(b.now) } : {}),
272
- };
273
- }
274
-
275
- /** `GET /alerts` β†’ the alert list, fail-closed. */
276
- export function parseAlerts(body: unknown): Alert[] {
277
- const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
278
- const raw = Array.isArray(b.alerts) ? b.alerts : [];
279
- const out: Alert[] = [];
280
- for (const item of raw) {
281
- if (!item || typeof item !== "object") continue;
282
- const a = item as Record<string, unknown>;
283
- const id = str(a.id);
284
- if (!id) continue;
285
- out.push({
286
- id,
287
- viewId: str(a.viewId),
288
- topic: str(a.topic),
289
- owner: str(a.owner),
290
- label: str(a.label) || "Untitled alert",
291
- createdAt: str(a.createdAt),
292
- matched: num(a.matched),
293
- seeded: a.seeded === true,
294
- lastRunAt: str(a.lastRunAt),
295
- lastError: str(a.lastError),
296
- });
297
- }
298
- return out;
299
- }
300
-
301
- /**
302
- * A topic (the grid's scope key) β†’ the hash route that renders it.
303
- *
304
- * The two built-ins are the only pair that differ, and they differ because the
305
- * REGISTRY names the surface while the GRID names the scope; a user table is its
306
- * own key in both. `null` for anything else: a notification for a topic this
307
- * client cannot route to must do nothing, not navigate somewhere plausible.
308
- */
309
- export function routeForTopic(topic: string): string | null {
310
- const t = str(topic).trim();
311
- if (t === "customer") return "customer_data";
312
- if (t === "product") return "product_data";
313
- if (/^ut_[A-Za-z0-9_]+$/.test(t)) return t;
314
- return null;
315
- }
316
-
317
-
318
-
319
-
320
-
321
-
322
- /**
323
- * The stamp, made readable WITHOUT touching a clock.
324
- *
325
- * β›” NO `new Date()`, NO `toLocaleString()`, and that is the whole design. The
326
- * server sends UTC WITH ITS OFFSET (D-18) precisely so every reader sees the
327
- * same instant; parsing it into a browser Date and formatting it back would
328
- * re-introduce the drift the offset exists to remove β€” a tenant a day ahead
329
- * being told an event happened tomorrow ([[date-window-vocabulary]]). This is
330
- * STRING SURGERY: keep the date and the minutes, drop the seconds and the `T`.
331
- * Anything that does not look like an ISO stamp passes through untouched, so a
332
- * format this function has never seen is shown as sent rather than mangled.
333
- */
334
- const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
335
- "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
336
-
337
- export function stampText(at: string, now?: string): string {
338
- const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(str(at));
339
- if (!m) return str(at);
340
- const [, day, hhmm] = m;
341
- // ⭐⭐ W33-T28 / D-208 β€” MAIL-SHAPED, AND STILL STRING SURGERY.
342
- //
343
- // β›” `now` COMES FROM THE SERVER (`inbox.now`), NEVER FROM `new Date()`. That is D-208's exit
344
- // condition word for word β€” "without reading the browser clock" β€” and the reason is the same
345
- // one this function has always carried: `at` is sent as UTC WITH its offset (D-18) so every
346
- // reader sees the same instant, and deciding "is this today?" against a browser clock would
347
- // re-introduce exactly the drift the offset removes. Both operands are the server's.
348
- //
349
- // ⚠ AND WITHOUT `now` IT DEGRADES TO THE OLD FORMAT RATHER THAN GUESSING. A caller that has no
350
- // server clock gets `2026-08-13 09:41` β€” the pre-wave string, unambiguous and never wrong β€”
351
- // instead of a relative stamp computed from something we do not trust.
352
- const today = /^(\d{4}-\d{2}-\d{2})/.exec(str(now));
353
- if (!today) return `${day} ${hhmm}`;
354
- if (today[1] === day) return hhmm;
355
- const [y, mo, d] = day.split("-");
356
- const month = MONTHS[Number(mo) - 1] || mo;
357
- // The year only when it differs β€” a mail client does not print "2026" on a message from March.
358
- return today[1].slice(0, 4) === y
359
- ? `${month} ${Number(d)}`
360
- : `${month} ${Number(d)}, ${y}`;
361
- }
362
-
363
- /**
364
- * The badge's text. Never the raw number past 99: a nav row is 236px wide and a
365
- * four-digit badge pushes the label out of it.
366
- */
367
- export function badgeText(unread: number): string {
368
- const n = Math.max(0, Math.floor(unread));
369
- if (n <= 0) return "";
370
- return n > 99 ? "99+" : String(n);
371
- }
372
-
373
- /**
374
- * Apply a read/unread change LOCALLY, mirroring what the server just stored, and
375
- * return the new inbox with the count corrected.
376
- *
377
- * `ids === null` is "all of them" (the API's own convention for mark-all). The
378
- * count is derived from the ITEMS here β€” deliberately, and it is the one place
379
- * that is right to do so: the server's answer is in flight, and the alternative
380
- * is a badge that keeps its old number until the refetch lands.
381
- */
382
- export function applyRead(inbox: Inbox, ids: string[] | null, read: boolean): Inbox {
383
- const wanted = ids === null ? null : new Set(ids);
384
- const items = inbox.items.map((n) =>
385
- wanted === null || wanted.has(n.id) ? { ...n, read } : n
386
- );
387
- const seenUnread = items.filter((n) => !n.read).length;
388
- // A page can hold fewer notifications than the account has, so a partial read
389
- // must SUBTRACT from the server's count rather than replace it with this
390
- // page's tally β€” except when marking everything, where zero is the answer.
391
- if (wanted === null) return { unread: read ? 0 : items.length, items };
392
- const changed = inbox.items.filter(
393
- (n) => wanted.has(n.id) && n.read !== read
394
- ).length;
395
- const delta = read ? -changed : changed;
396
- return { unread: Math.max(seenUnread, inbox.unread + delta), items };
397
- }
398
-
399
- /**
400
- * The shell↔rail channel for "make an alert out of this view" β€” the view rail
401
- * raises it, the frame (which knows the current route, and therefore the topic)
402
- * answers. Same reason as C-SHARE's event: the rail is host-neutral and cannot
403
- * import the shell, and it does not know its own scope key.
404
- */
405
- export const ALERT_CREATE_EVENT = "aios:alert-create";
406
-
407
- export interface AlertCreateRequest {
408
- viewId: string;
409
- label: string;
410
- }
411
-
412
- export function parseAlertCreate(detail: unknown): AlertCreateRequest | null {
413
- if (!detail || typeof detail !== "object") return null;
414
- const d = detail as Record<string, unknown>;
415
- const viewId = str(d.viewId).trim();
416
- if (!viewId) return null;
417
- return { viewId, label: str(d.label).trim() || viewId };
418
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // alerts/alertsModel.ts β€” WAVE 20 item 25 (contract C-ALERT): the inbox's PURE
3
+ // half. React-free and fetch-free, so `verify_alerts.py` runs it under node.
4
+ //
5
+ // An alert says "tell me when a record ENTERS this view". The client half is
6
+ // small, and every part of it fails silently when it is wrong:
7
+ //
8
+ // Β· an unread count taken from `items.length` rather than from the server's
9
+ // own `unread` disagrees with the badge the moment a page is capped or a
10
+ // read lands in another tab β€” and a badge that says 3 when the list shows 9
11
+ // teaches the reader to ignore the badge;
12
+ // Β· a notification whose `viewId` no longer resolves must open NOTHING rather
13
+ // than a wrong view β€” alerts outlive the views they were made from;
14
+ // Β· `topic` is the surface's scope key ("customer", "product", "ut_…"), and
15
+ // the ROUTE is a registry key ("customer_data") β€” mapping one to the other
16
+ // by guesswork sends every click to a page that does not exist.
17
+ // ---------------------------------------------------------------------------
18
+
19
+ /**
20
+ * ⭐⭐ WAVE 32 Β· T20 Β· CONTRACT C3 β€” WHERE AN INBOX ITEM OPENS.
21
+ *
22
+ * `module` is the destination surface (`"database"` or `"automation"`) and `id` is what to open
23
+ * in it. `tab` is the SUB-SELECTION inside that module: the literal `"runs"` for an automation's
24
+ * run log, or the VIEW ID to select on a database. One optional key, two destinations.
25
+ *
26
+ * β›” EVERY FIELD IS A PLAIN `string`, NEVER A UNION, and that is alertsModel's wave-9 law rather
27
+ * than laziness: the vocabulary is the SERVER's, and a client union over it turns "the server grew
28
+ * a module" into "the client silently drops the row". An unknown module is refused by the
29
+ * FRAME's dispatcher, out loud, which is a different thing from never arriving.
30
+ */
31
+ export interface NotificationTarget {
32
+ module: string;
33
+ id: string;
34
+ tab?: string;
35
+ }
36
+
37
+ /** C3's `kind` vocabulary, mirroring `routes_alerts.NOTIF_KIND_*`. Held as constants so the
38
+ * Inbox's branch and the gate's fixtures cannot disagree about the word. */
39
+ export const NOTIF_KIND_ALERT = "alert";
40
+ export const NOTIF_KIND_AUTOMATION = "automation";
41
+ export const NOTIF_KIND_SHARE = "share";
42
+
43
+ /** C3's `target.module` vocabulary, and the automation sub-selection. */
44
+ export const TARGET_MODULE_DATABASE = "database";
45
+ export const TARGET_MODULE_AUTOMATION = "automation";
46
+ export const TARGET_TAB_RUNS = "runs";
47
+
48
+ /** One notification, as `GET /api/v1/notifications` sends it. */
49
+ export interface Notification {
50
+ id: string;
51
+ alertId: string;
52
+ viewId: string;
53
+ topic: string;
54
+ rowId: string;
55
+ /** What entered β€” the record's own label. */
56
+ label: string;
57
+ /** What the alert is called, so a row reads without opening anything. */
58
+ alertLabel: string;
59
+ /** UTC WITH OFFSET (D-18). Kept as the server's STRING: re-formatting it here
60
+ * would re-introduce the browser-clock drift the offset exists to remove. */
61
+ at: string;
62
+ read: boolean;
63
+ /**
64
+ * WAVE 23 (contract C6) β€” WHAT KIND of notification this is.
65
+ *
66
+ * Absent (and every notification written before this wave) means the original one: a record
67
+ * ENTERED a watched view, routed by `topic` + `viewId`. `"automation_review"` means a card
68
+ * arrived at a review stage and routes by `autoId` instead β€” a different destination reached
69
+ * from the same list.
70
+ *
71
+ * β›” A STRING, NEVER A UNION, and that is the wave-9 law rather than laziness: the vocabulary
72
+ * is the SERVER's, and a client union over it turns "the server grew a kind" into "the client
73
+ * silently drops the row". Unknown kinds fall through to the view route, which is exactly what
74
+ * they did before this field existed.
75
+ */
76
+ kind?: string;
77
+ /** `automation_review` only: the automation whose review stage a card reached. Absent on
78
+ * every other kind β€” and an `automation_review` row that arrives WITHOUT one opens nothing
79
+ * rather than guessing, the same posture `viewId` gets. */
80
+ autoId?: string;
81
+ /** Advisory. A surface that does not scroll to a stage simply selects the automation. */
82
+ stageId?: string;
83
+ /** How many cards arrived in the batch. C6 queues ONE notification per run naming the count,
84
+ * never one per record β€” so this is the number the row's own text is built from. */
85
+ count?: number;
86
+ /**
87
+ * ⭐ WAVE 32 Β· C3 β€” THE HEADER LINE, so the Inbox can be laid out like mail.
88
+ *
89
+ * `subject` is what the item is ABOUT (the alert's name, the automation's name, the database
90
+ * that was shared); `label` stays what HAPPENED (the record that entered, the run summary).
91
+ * They were one field, which is why the pane could only ever render a sentence with no sender.
92
+ * Absent on a server that predates this wave β€” {@link subjectOf} falls back rather than
93
+ * rendering a blank header.
94
+ */
95
+ subject?: string;
96
+ /**
97
+ * ⭐⭐ WAVE 33 Β· W33-T28 β€” WHO IT IS FROM. Mail has a sender; this list did not.
98
+ *
99
+ * A `verifier` reading the finished wave-32 Inbox found the row's sender POSITION occupied by
100
+ * `kindLabel(n.kind)` β€” the literals "Alert" / "Automation" / "Shared with you", a CATEGORY
101
+ * standing where a who belongs β€” and no sender anywhere on the wire. Derived by the server
102
+ * (`routes_alerts.notification_view`), never here: only it knows that a share has a person
103
+ * behind it and an alert has a machine.
104
+ * ⚠ Optional, so a payload from a server that predates this wave keeps today's shape;
105
+ * {@link senderOf} falls back rather than rendering a blank From column.
106
+ */
107
+ sender?: string;
108
+ /** ⭐ WAVE 32 Β· C3 β€” where clicking it goes. ABSENT when this product cannot resolve a
109
+ * destination (an alert on a table this account can no longer route to), and that absence is
110
+ * load-bearing: the Inbox renders such a row as plainly unclickable rather than as a click
111
+ * that silently does nothing. */
112
+ target?: NotificationTarget;
113
+ }
114
+
115
+ /** One alert, as `GET /api/v1/alerts` sends it. */
116
+ export interface Alert {
117
+ id: string;
118
+ viewId: string;
119
+ topic: string;
120
+ owner: string;
121
+ label: string;
122
+ createdAt: string;
123
+ /** How many records are in its remembered set right now. */
124
+ matched: number;
125
+ seeded: boolean;
126
+ lastRunAt: string;
127
+ lastError: string;
128
+ }
129
+
130
+ export interface Inbox {
131
+ unread: number;
132
+ items: Notification[];
133
+ /**
134
+ * ⭐⭐ WAVE 33 Β· W33-T28 / D-208 β€” THE SERVER'S CLOCK, so a stamp can be mail-shaped.
135
+ *
136
+ * β›” It exists so {@link stampText} never reads the BROWSER's clock, which is D-208's exit
137
+ * condition word for word. `at` is UTC with its offset (D-18) precisely so every reader sees
138
+ * the same instant; asking "is this today?" of a local clock would put the drift back.
139
+ * ⚠ Optional: absent, `stampText` returns the old absolute string rather than guessing.
140
+ */
141
+ now?: string;
142
+ }
143
+
144
+ export const EMPTY_INBOX: Inbox = { unread: 0, items: [] };
145
+
146
+ /**
147
+ * ⭐⭐ WAVE 31 Β· T23 (owner item 1) β€” WHAT THE PANE IS ENTITLED TO SAY, AS A FUNCTION.
148
+ *
149
+ * Owner, verbatim: *"Alerts shows notification, but when clicked it says nothing, and it doesn't
150
+ * remove the notification number."* Both halves are ONE mechanism. `AlertsPane` held its own
151
+ * `inbox` seeded to {@link EMPTY_INBOX} and had no pending state, so between opening the panel
152
+ * and `GET /notifications` answering β€” measured at **3,280 ms live** β€” and for ever after a
153
+ * failed fetch:
154
+ * Β· `items` was `[]`, so the pane printed **"Nothing new."** β€” a claim, not a wait;
155
+ * Β· `unread` was `0`, so **"Mark all read" was `disabled`**, and the badge the frame had
156
+ * already loaded could never be cleared.
157
+ * A confident sentence about somebody's inbox, and the one control that would fix it, both
158
+ * switched off by the same uninitialised state.
159
+ *
160
+ * β›” IT IS A FUNCTION BECAUSE THE PANE IS TSX AND TSX IS NOT UNDER TEST HERE. `verify_alerts`
161
+ * compiles and RUNS this module under node; markup it cannot reach is markup no control can
162
+ * mutate. Deciding here means the truth table is asserted and each branch is load-bearing.
163
+ */
164
+ export type PaneView = "pending" | "rows" | "empty" | "error";
165
+
166
+ /**
167
+ * `pending` while the first read is in flight Β· `error` when it failed and we have nothing to
168
+ * show Β· `rows` when there is something Β· `empty` ONLY when a successful read returned nothing.
169
+ *
170
+ * ⚠ ROWS WIN OVER AN ERROR, and that is deliberate rather than lax: a refresh that fails while
171
+ * the pane already holds notifications should not blank them β€” the reader loses real information
172
+ * to a transient. The error still reaches them as the pane's message line.
173
+ */
174
+ export function paneView(
175
+ phase: "pending" | "ready" | "error",
176
+ rowCount: number,
177
+ seededUnread = 0
178
+ ): PaneView {
179
+ if (rowCount > 0) return "rows";
180
+ if (phase === "pending") return "pending";
181
+ if (phase === "error") return "error";
182
+ // ⚠ A SUCCESSFUL READ WITH NO ROWS AND A NON-ZERO COUNT IS NOT "nothing new". The badge says
183
+ // there is something; the page we were given does not contain it. Saying "Nothing new" there
184
+ // is the same false confidence in a different costume.
185
+ return seededUnread > 0 ? "error" : "empty";
186
+ }
187
+
188
+ /**
189
+ * May "Mark all read" be pressed?
190
+ *
191
+ * β›” NOT `unread === 0`, WHICH IS THE SHIPPED BUG. That test asked the PANE's own state β€” zero
192
+ * until its fetch lands, zero for ever if the fetch fails β€” so the control was dead in exactly
193
+ * the situations the owner hit. The question is about the ACCOUNT, so it is asked of the count
194
+ * the frame already holds, and a failed read does not take the verb away: `POST /notifications/
195
+ * read` with `ids: null` clears the account's inbox whether or not we managed to list it.
196
+ */
197
+ export function canMarkAll(unread: number, busy = false): boolean {
198
+ return !busy && Math.max(0, Math.floor(unread)) > 0;
199
+ }
200
+
201
+ const str = (v: unknown): string => (typeof v === "string" ? v : "");
202
+ const num = (v: unknown): number => (typeof v === "number" && isFinite(v) ? v : 0);
203
+
204
+ /**
205
+ * ⭐ WAVE 32 Β· C3 β€” one wire `target` β†’ a {@link NotificationTarget}, or `null`.
206
+ *
207
+ * β›” BOTH `module` AND `id` ARE REQUIRED, and dropping either test is the failure this guard is
208
+ * for: a target with a module and no id dispatches an open request naming NOTHING β€” a click that
209
+ * appears to work and silently does not, which is this repo's most-repeated shape. `null` is
210
+ * rendered as an unclickable row, which a reader can SEE.
211
+ */
212
+ export function parseTarget(raw: unknown): NotificationTarget | null {
213
+ if (!raw || typeof raw !== "object") return null;
214
+ const t = raw as Record<string, unknown>;
215
+ const module = str(t.module).trim();
216
+ const id = str(t.id).trim();
217
+ if (!module || !id) return null;
218
+ const tab = str(t.tab).trim();
219
+ return { module, id, ...(tab ? { tab } : {}) };
220
+ }
221
+
222
+ /**
223
+ * `GET /notifications` β†’ the inbox, fail-closed.
224
+ *
225
+ * ⚠ `unread` COMES FROM THE SERVER, and is not recounted from `items`. The two
226
+ * can legitimately differ β€” the list is what this page holds, the count is what
227
+ * the account has β€” and recomputing it here would make the badge a function of
228
+ * whatever the last fetch happened to include.
229
+ */
230
+ export function parseInbox(body: unknown): Inbox {
231
+ const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
232
+ const raw = Array.isArray(b.items) ? b.items : [];
233
+ const items: Notification[] = [];
234
+ for (const item of raw) {
235
+ if (!item || typeof item !== "object") continue;
236
+ const n = item as Record<string, unknown>;
237
+ const id = str(n.id);
238
+ // An id-less notification cannot be marked read, so it would sit unread for
239
+ // ever and hold the badge up. Dropped, not rendered.
240
+ if (!id) continue;
241
+ items.push({
242
+ id,
243
+ alertId: str(n.alertId),
244
+ viewId: str(n.viewId),
245
+ topic: str(n.topic),
246
+ rowId: String(n.rowId ?? ""),
247
+ label: str(n.label) || String(n.rowId ?? ""),
248
+ alertLabel: str(n.alertLabel),
249
+ at: str(n.at),
250
+ read: n.read === true,
251
+ // WAVE 23 C6 β€” ADDITIVE and spread-conditional, exactly like `NavPage`'s flags: a payload
252
+ // that predates this wave keeps today's shape rather than gaining four `undefined` keys,
253
+ // and an `automation_review` row missing its `autoId` is left WITHOUT one rather than
254
+ // with an empty string that would render as a real destination.
255
+ ...(str(n.kind) ? { kind: str(n.kind) } : {}),
256
+ ...(str(n.autoId) ? { autoId: str(n.autoId) } : {}),
257
+ ...(str(n.stageId) ? { stageId: str(n.stageId) } : {}),
258
+ ...(num(n.count) > 0 ? { count: num(n.count) } : {}),
259
+ // ⭐ WAVE 32 Β· C3 β€” additive and spread-conditional, exactly like the four above.
260
+ ...(str(n.subject) ? { subject: str(n.subject) } : {}),
261
+ // ⭐ WAVE 33 Β· W33-T28 β€” additive and spread-conditional, like every flag above it.
262
+ ...(str(n.sender) ? { sender: str(n.sender) } : {}),
263
+ ...(parseTarget(n.target) ? { target: parseTarget(n.target)! } : {}),
264
+ });
265
+ }
266
+ // ⭐ W33-T28 / D-208 β€” the server's clock rides through, spread-conditionally like every other
267
+ // additive key here, so a server that predates this wave yields the same object it always did.
268
+ return {
269
+ unread: Math.max(0, num(b.unread)),
270
+ items,
271
+ ...(str(b.now) ? { now: str(b.now) } : {}),
272
+ };
273
+ }
274
+
275
+ /** `GET /alerts` β†’ the alert list, fail-closed. */
276
+ export function parseAlerts(body: unknown): Alert[] {
277
+ const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
278
+ const raw = Array.isArray(b.alerts) ? b.alerts : [];
279
+ const out: Alert[] = [];
280
+ for (const item of raw) {
281
+ if (!item || typeof item !== "object") continue;
282
+ const a = item as Record<string, unknown>;
283
+ const id = str(a.id);
284
+ if (!id) continue;
285
+ out.push({
286
+ id,
287
+ viewId: str(a.viewId),
288
+ topic: str(a.topic),
289
+ owner: str(a.owner),
290
+ label: str(a.label) || "Untitled alert",
291
+ createdAt: str(a.createdAt),
292
+ matched: num(a.matched),
293
+ seeded: a.seeded === true,
294
+ lastRunAt: str(a.lastRunAt),
295
+ lastError: str(a.lastError),
296
+ });
297
+ }
298
+ return out;
299
+ }
300
+
301
+ /**
302
+ * A topic (the grid's scope key) β†’ the hash route that renders it.
303
+ *
304
+ * The two built-ins are the only pair that differ, and they differ because the
305
+ * REGISTRY names the surface while the GRID names the scope; a user table is its
306
+ * own key in both. `null` for anything else: a notification for a topic this
307
+ * client cannot route to must do nothing, not navigate somewhere plausible.
308
+ */
309
+ export function routeForTopic(topic: string): string | null {
310
+ const t = str(topic).trim();
311
+ if (t === "customer") return "customer_data";
312
+ if (t === "product") return "product_data";
313
+ if (/^ut_[A-Za-z0-9_]+$/.test(t)) return t;
314
+ return null;
315
+ }
316
+
317
+
318
+
319
+
320
+
321
+
322
+ /**
323
+ * The stamp, made readable WITHOUT touching a clock.
324
+ *
325
+ * β›” NO `new Date()`, NO `toLocaleString()`, and that is the whole design. The
326
+ * server sends UTC WITH ITS OFFSET (D-18) precisely so every reader sees the
327
+ * same instant; parsing it into a browser Date and formatting it back would
328
+ * re-introduce the drift the offset exists to remove β€” a tenant a day ahead
329
+ * being told an event happened tomorrow ([[date-window-vocabulary]]). This is
330
+ * STRING SURGERY: keep the date and the minutes, drop the seconds and the `T`.
331
+ * Anything that does not look like an ISO stamp passes through untouched, so a
332
+ * format this function has never seen is shown as sent rather than mangled.
333
+ */
334
+ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
335
+ "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
336
+
337
+ export function stampText(at: string, now?: string): string {
338
+ const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(str(at));
339
+ if (!m) return str(at);
340
+ const [, day, hhmm] = m;
341
+ // ⭐⭐ W33-T28 / D-208 β€” MAIL-SHAPED, AND STILL STRING SURGERY.
342
+ //
343
+ // β›” `now` COMES FROM THE SERVER (`inbox.now`), NEVER FROM `new Date()`. That is D-208's exit
344
+ // condition word for word β€” "without reading the browser clock" β€” and the reason is the same
345
+ // one this function has always carried: `at` is sent as UTC WITH its offset (D-18) so every
346
+ // reader sees the same instant, and deciding "is this today?" against a browser clock would
347
+ // re-introduce exactly the drift the offset removes. Both operands are the server's.
348
+ //
349
+ // ⚠ AND WITHOUT `now` IT DEGRADES TO THE OLD FORMAT RATHER THAN GUESSING. A caller that has no
350
+ // server clock gets `2026-08-13 09:41` β€” the pre-wave string, unambiguous and never wrong β€”
351
+ // instead of a relative stamp computed from something we do not trust.
352
+ const today = /^(\d{4}-\d{2}-\d{2})/.exec(str(now));
353
+ if (!today) return `${day} ${hhmm}`;
354
+ if (today[1] === day) return hhmm;
355
+ const [y, mo, d] = day.split("-");
356
+ const month = MONTHS[Number(mo) - 1] || mo;
357
+ // The year only when it differs β€” a mail client does not print "2026" on a message from March.
358
+ return today[1].slice(0, 4) === y
359
+ ? `${month} ${Number(d)}`
360
+ : `${month} ${Number(d)}, ${y}`;
361
+ }
362
+
363
+ /**
364
+ * The badge's text. Never the raw number past 99: a nav row is 236px wide and a
365
+ * four-digit badge pushes the label out of it.
366
+ */
367
+ export function badgeText(unread: number): string {
368
+ const n = Math.max(0, Math.floor(unread));
369
+ if (n <= 0) return "";
370
+ return n > 99 ? "99+" : String(n);
371
+ }
372
+
373
+ /**
374
+ * Apply a read/unread change LOCALLY, mirroring what the server just stored, and
375
+ * return the new inbox with the count corrected.
376
+ *
377
+ * `ids === null` is "all of them" (the API's own convention for mark-all). The
378
+ * count is derived from the ITEMS here β€” deliberately, and it is the one place
379
+ * that is right to do so: the server's answer is in flight, and the alternative
380
+ * is a badge that keeps its old number until the refetch lands.
381
+ */
382
+ export function applyRead(inbox: Inbox, ids: string[] | null, read: boolean): Inbox {
383
+ const wanted = ids === null ? null : new Set(ids);
384
+ const items = inbox.items.map((n) =>
385
+ wanted === null || wanted.has(n.id) ? { ...n, read } : n
386
+ );
387
+ const seenUnread = items.filter((n) => !n.read).length;
388
+ // A page can hold fewer notifications than the account has, so a partial read
389
+ // must SUBTRACT from the server's count rather than replace it with this
390
+ // page's tally β€” except when marking everything, where zero is the answer.
391
+ if (wanted === null) return { unread: read ? 0 : items.length, items };
392
+ const changed = inbox.items.filter(
393
+ (n) => wanted.has(n.id) && n.read !== read
394
+ ).length;
395
+ const delta = read ? -changed : changed;
396
+ return { unread: Math.max(seenUnread, inbox.unread + delta), items };
397
+ }
398
+
399
+ /**
400
+ * The shell↔rail channel for "make an alert out of this view" β€” the view rail
401
+ * raises it, the frame (which knows the current route, and therefore the topic)
402
+ * answers. Same reason as C-SHARE's event: the rail is host-neutral and cannot
403
+ * import the shell, and it does not know its own scope key.
404
+ */
405
+ export const ALERT_CREATE_EVENT = "aios:alert-create";
406
+
407
+ export interface AlertCreateRequest {
408
+ viewId: string;
409
+ label: string;
410
+ }
411
+
412
+ export function parseAlertCreate(detail: unknown): AlertCreateRequest | null {
413
+ if (!detail || typeof detail !== "object") return null;
414
+ const d = detail as Record<string, unknown>;
415
+ const viewId = str(d.viewId).trim();
416
+ if (!viewId) return null;
417
+ return { viewId, label: str(d.label).trim() || viewId };
418
+ }
web/src/automation/AutomationFind.tsx CHANGED
@@ -1,893 +1,893 @@
1
- // ---------------------------------------------------------------------------
2
- // automation/AutomationFind.tsx β€” the discovery filter, as TOGGLES (owner item 6,
3
- // contract C4).
4
- //
5
- // WHAT CHANGED AND WHY. It was a condition BUILDER: an empty row, a field
6
- // dropdown listing 21 names, "Add a condition". That shape asks the user to
7
- // remember what is searchable before they can look, and it hid the only fact
8
- // that decides whether a search returns anything at all β€” which fields actually
9
- // carry values. The corpus is 620 million profiles and every run is billed, so
10
- // "I did not know I could filter on that" and "I filtered on a field that is
11
- // empty on every row" are both expensive mistakes made in silence.
12
- //
13
- // So every searchable field is ON SCREEN, off by default, and turning one on is
14
- // what creates its condition. The list leads with the fields MEASURED to carry
15
- // values; the rest are grouped under what is known about them, and neither group
16
- // is hidden β€” R3 already decided that "every filter" means the 21 we can stand
17
- // behind, so all 21 are visible.
18
- //
19
- // β›” THE VOCABULARY IS THE SERVER'S, ALL OF IT. Field names, operators, which
20
- // operators take no value, the record ceiling and (once C4 lands it) which
21
- // fields are populated and which narrow β€” every one of those rides on
22
- // `GET /automations`. This file holds no list of its own. The reason is the one
23
- // `automationApi.ts:11-15` gives for cron presets: the thing that ACCEPTS a
24
- // filter is Python, and a client copy of what it accepts is a copy that can
25
- // offer a search the server refuses.
26
- //
27
- // β›” AND IT DOES NOT RE-IMPLEMENT THE GUARD. `guard` carries the server's
28
- // numbers, so the rows can say which fields narrow β€” but the refusal is the
29
- // server's to make and this surface prints it VERBATIM when it comes back
30
- // (`DiscoverGuard`'s note). A client that predicts the refusal is a second copy
31
- // of the rule, free to disagree with the first, and when they disagree the user
32
- // gets a Save button that is disabled for a reason nobody can see.
33
- // ---------------------------------------------------------------------------
34
- import { useEffect, useState } from "react";
35
- // ⭐ WAVE 27 item 29 β€” the overlay layer the grid already owns, consumed rather than
36
- // re-implemented: it is a body portal (so it escapes `.auto-panel`'s 380px), and it brings
37
- // the dismiss/focus/placement behaviour every other popover on this product already has.
38
- import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
39
- import type { AnchorRect } from "../customer-grid/OverlaySurface";
40
-
41
- import type {
42
- DiscoverEstimate,
43
- DiscoverFieldMeta,
44
- DiscoverOperator,
45
- DiscoverVocab,
46
- Predicate,
47
- } from "./automationApi";
48
- import { discoverCategories } from "./automationApi";
49
-
50
- interface Props {
51
- /** The server-declared discovery vocabulary (absent until the list loads). */
52
- discover?: DiscoverVocab;
53
- recordsLimit: number;
54
- onRecordsLimit: (n: number) => void;
55
- joinOp: string;
56
- onJoinOp: (v: string) => void;
57
- preds: Predicate[];
58
- onPreds: (next: Predicate[]) => void;
59
- estimate: DiscoverEstimate | null;
60
- onEstimate: () => void;
61
- }
62
-
63
- /**
64
- * A FILTER FIELD'S ICON (owner item 5). Drawn, `currentColor`, never an emoji β€” and in the
65
- * existing `TriggerMark`/`ActionMark` language rather than a new one: same 16 viewBox, same 15px
66
- * box, same 1.4 stroke, so a row here and a card in the builder read as one product.
67
- *
68
- * ⚠ SHARED SHAPES WHERE THE FIELDS SHARE A MEANING, distinct everywhere else. `TriggerMark`'s
69
- * note settled the principle β€” a column of identical glyphs is decoration, the eye learns nothing
70
- * β€” but its converse matters just as much here: `bio_hashtags` and `post_hashtags` ARE both
71
- * hashtags, and drawing two different marks for them would invent a distinction the vendor does
72
- * not make. Twenty-one contrived glyphs would be twenty-one things to misread.
73
- *
74
- * β›” THE FALLBACK IS NOT A MEMBER OF THE SET, which is the `ActionMark` scar exactly: its default
75
- * used to BE the pencil, a real member, so every unmatched kind silently borrowed "edit" and a
76
- * fallback could not be told from a match. The vocabulary is the SERVER's β€” it can grow a field
77
- * tomorrow β€” so an unmatched name draws a neutral mark that is deliberately meaningless.
78
- */
79
- function FilterMark({ name }: { name: string }) {
80
- const common = {
81
- width: 15, height: 15, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor",
82
- strokeWidth: 1.4, strokeLinecap: "round" as const, strokeLinejoin: "round" as const,
83
- "aria-hidden": true,
84
- };
85
- // Audience size β€” two figures, one behind the other.
86
- if (name === "followers")
87
- return (
88
- <svg {...common}>
89
- <circle cx="6.2" cy="5.6" r="2.4" />
90
- <path d="M2.2 13c.5-2 2.1-3.2 4-3.2s3.5 1.2 4 3.2" />
91
- <path d="M10.6 3.6a2.4 2.4 0 0 1 0 4M11.4 9.9c1.4.4 2.4 1.5 2.8 3.1" />
92
- </svg>
93
- );
94
- // Who this account follows β€” a figure with an outbound arrow.
95
- if (name === "following")
96
- return (
97
- <svg {...common}>
98
- <circle cx="6" cy="5.6" r="2.4" />
99
- <path d="M1.8 13c.5-2 2.1-3.2 4.2-3.2 .6 0 1.2.1 1.7.3" />
100
- <path d="M9.8 10.6h4.2M12.2 8.8l1.8 1.8-1.8 1.8" />
101
- </svg>
102
- );
103
- if (name === "posts_count")
104
- return (
105
- <svg {...common}>
106
- <rect x="2.6" y="2.6" width="4.6" height="4.6" rx="1" />
107
- <rect x="8.8" y="2.6" width="4.6" height="4.6" rx="1" />
108
- <rect x="2.6" y="8.8" width="4.6" height="4.6" rx="1" />
109
- <rect x="8.8" y="8.8" width="4.6" height="4.6" rx="1" />
110
- </svg>
111
- );
112
- // A story highlight β€” the ring Instagram draws around one.
113
- if (name === "highlights_count")
114
- return (
115
- <svg {...common}>
116
- <circle cx="8" cy="8" r="5.6" strokeDasharray="2.6 1.8" />
117
- <circle cx="8" cy="8" r="2.2" />
118
- </svg>
119
- );
120
- if (name === "avg_engagement")
121
- return (
122
- <svg {...common}>
123
- <path d="M8 13.2 3.4 8.8a2.9 2.9 0 0 1 4.6-3.4 2.9 2.9 0 0 1 4.6 3.4z" />
124
- </svg>
125
- );
126
- if (name === "biography")
127
- return (
128
- <svg {...common}>
129
- <rect x="2.4" y="2.8" width="11.2" height="10.4" rx="1.6" />
130
- <path d="M4.8 6h6.4M4.8 8.4h6.4M4.8 10.8h3.6" />
131
- </svg>
132
- );
133
- if (name === "category_name" || name === "business_category_name")
134
- return (
135
- <svg {...common}>
136
- <path d="M8.4 2.6H13v4.6l-6.2 6.2-4.6-4.6z" />
137
- <circle cx="10.8" cy="5.2" r="0.9" />
138
- </svg>
139
- );
140
- if (name === "is_business_account" || name === "is_professional_account")
141
- return (
142
- <svg {...common}>
143
- <rect x="2.2" y="5" width="11.6" height="8.2" rx="1.6" />
144
- <path d="M6 5V3.6a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1V5" />
145
- </svg>
146
- );
147
- if (name === "is_verified")
148
- return (
149
- <svg {...common}>
150
- <path d="M8 2.2l1.7 1.2 2-.2.6 2 1.7 1.1-.9 1.9.9 1.9-1.7 1.1-.6 2-2-.2L8 14.2l-1.7-1.2-2 .2-.6-2L2 10.1l.9-1.9L2 6.3l1.7-1.1.6-2 2 .2z" />
151
- <path d="m5.8 8.1 1.5 1.5 3-3.1" />
152
- </svg>
153
- );
154
- // The handle, and the display name it is written under.
155
- if (name === "account" || name === "profile_name")
156
- return (
157
- <svg {...common}>
158
- <circle cx="8" cy="8" r="2.4" />
159
- <path d="M10.4 5.6v3.2a1.9 1.9 0 0 0 3.2 1.3A5.8 5.8 0 1 0 11 13.1" />
160
- </svg>
161
- );
162
- if (name === "full_name")
163
- return (
164
- <svg {...common}>
165
- <circle cx="8" cy="5.6" r="2.6" />
166
- <path d="M3 13.4c.7-2.3 2.6-3.6 5-3.6s4.3 1.3 5 3.6" />
167
- </svg>
168
- );
169
- if (name === "external_url" || name === "profile_url")
170
- return (
171
- <svg {...common}>
172
- <path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
173
- <path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
174
- <path d="M6.2 8h3.6" />
175
- </svg>
176
- );
177
- if (name === "bio_hashtags" || name === "post_hashtags")
178
- return (
179
- <svg {...common}>
180
- <path d="M6.2 2.8 4.8 13.2M11.2 2.8 9.8 13.2M2.8 6h10.4M2.2 10h10.4" />
181
- </svg>
182
- );
183
- if (name === "related_accounts")
184
- return (
185
- <svg {...common}>
186
- <circle cx="8" cy="3.6" r="1.8" />
187
- <circle cx="3.6" cy="12" r="1.8" />
188
- <circle cx="12.4" cy="12" r="1.8" />
189
- <path d="M6.8 5.2 4.6 10.4M9.2 5.2l2.2 5.2M5.4 12h5.2" />
190
- </svg>
191
- );
192
- // The vendor's own record keys β€” the thing you hold to open exactly one row.
193
- if (name === "id" || name === "fbid")
194
- return (
195
- <svg {...common}>
196
- <circle cx="5.4" cy="10.6" r="2.6" />
197
- <path d="M7.2 8.8 13 3M10.6 5.4l1.6 1.6M9.2 6.8l1.6 1.6" />
198
- </svg>
199
- );
200
- return (
201
- <svg {...common}>
202
- <rect x="3.2" y="3.2" width="9.6" height="9.6" rx="2.2" />
203
- <circle cx="8" cy="8" r="1.4" />
204
- </svg>
205
- );
206
- }
207
-
208
- /** One field's line in the list, with everything known about it. */
209
- interface FieldRow {
210
- name: string;
211
- /** What the row is CALLED. Falls back to the raw name only if the server sent none. */
212
- label: string;
213
- hint: string;
214
- kind: string;
215
- operators: DiscoverOperator[];
216
- options: { value: string; label: string }[];
217
- /** Every stored condition naming this field, with its index in the saved array. */
218
- at: number[];
219
- /** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
220
- populated: boolean | null;
221
- /** A condition here cuts the corpus down. `null` = not said. */
222
- narrowing: boolean | null;
223
- }
224
-
225
- /** A stored value β†’ what the text box shows. A list is the "any of" shape. */
226
- function valueText(v: Predicate["value"]): string {
227
- if (Array.isArray(v)) return v.join(", ");
228
- return v === undefined || v === null ? "" : String(v);
229
- }
230
-
231
- /**
232
- * What the user typed β†’ what is stored. Comma-separated becomes a LIST for the operators that
233
- * accept one, and stays a plain string for the ones that do not.
234
- *
235
- * ⚠ A single value stays a SCALAR rather than a one-element list β€” the server sends scalars
236
- * flat and lists as a nested OR group, and a one-element group is a shape nothing has been
237
- * billed against.
238
- */
239
- function parseValue(text: string, multi: boolean): Predicate["value"] {
240
- if (!multi) return text;
241
- const parts = text.split(",").map((s) => s.trim()).filter(Boolean);
242
- if (parts.length > 1) return parts;
243
- // Keep the RAW text while it is still being typed β€” trimming here would fight the cursor on
244
- // every keystroke, and the server trims anyway.
245
- return text;
246
- }
247
-
248
- /**
249
- * ⭐ WAVE 26 Β· DEBT D-69 β€” A THIRD VALUE COULD NOT BE TYPED, and the cause was one round trip
250
- * through this pair of functions.
251
- *
252
- * `parseValue` returns an ARRAY at 2+ values; `valueText` then renders that array as
253
- * `join(", ")` β€” which has NO TRAILING COMMA. So on a controlled input the separator was
254
- * normalised away between keystrokes: typing `,` onto `skincare, beauty` re-rendered as
255
- * `skincare, beauty`, and the next character landed as `skincare, beautym`. Two keywords
256
- * silently became one that matches nothing. ⚠ It hit the FIRST surface a new user meets (wave 24
257
- * made this panel the only door) and it hit precisely the 3+ keyword list the feature was built
258
- * for β€” the owner's *"if i want to include many keywords like floral, flower, beauty"*.
259
- *
260
- * β›” THE FIX IS THE ONE `parseValue`'s OWN COMMENT ALREADY DESCRIBES FOR THE 1-VALUE CASE:
261
- * keep the raw text while it is being typed. That comment was right and its scope was too narrow
262
- * β€” it protected the cursor at one value and handed the 2+ case to `join`. So the raw text is
263
- * held for whichever input is FOCUSED, and the stored value is still parsed on every keystroke
264
- * (so nothing depends on blur to save) and re-parsed on blur (so the display settles).
265
- *
266
- * ⚠ KEYED BY THE ROW'S REACT KEY, not by index alone: two conditions on the same field are
267
- * ordinary here ("Another condition on Bio"), and an index-only key would leak one row's draft
268
- * into its sibling on a removal.
269
- */
270
- interface Draft {
271
- key: string;
272
- text: string;
273
- }
274
-
275
- /**
276
- * The comparison a freshly toggled field starts with β€” ASKED FOR, never chosen here.
277
- *
278
- * β›” THE THIRD COSTUME OF ONE SCAR, and the reason this function no longer has an opinion.
279
- * Wave 21 made a new condition NULLARY (`is_not_null`) so it would be saveable without a
280
- * value, and called that "narrowing-in-the-right-direction". Wave 22 then wrote the narrowing
281
- * law server-side and `is_not_null` is not in it. From that moment, toggling ANY field on and
282
- * pressing Save returned "add at least one CONTENT condition…" β€” the error told the user to do
283
- * the exact thing they had just done. Wave 24 deleted the wizard and made this panel the only
284
- * door, so it stopped being a corner case and became the first thing a new user hits.
285
- *
286
- * The fix is not a better guess. It is that the module owning the guard also names the default
287
- * (`automation_engine.default_operator`, asserted against `predicate_narrows` in
288
- * `verify_automation.py`), and this file looks it up per FIELD. An absent one falls back to the
289
- * server's first operator β€” never to a nullary, which is the thing that could not narrow.
290
- */
291
- function firstOperator(v: DiscoverVocab | undefined, name: string): string {
292
- const meta = (v?.filterMeta || []).find((m) => m.name === name);
293
- return meta?.defaultOperator || (v?.operators || [])[0] || "";
294
- }
295
-
296
- /**
297
- * The rows, ordered: measured-populated first, then the rest.
298
- *
299
- * TWO SOURCES, AND THE FALLBACK IS NARROWER THAN THE REAL THING. With C4's
300
- * `filterMeta` the answer is per field and complete. Without it, `lead` names
301
- * the three fields seen carrying values and says NOTHING about the other
302
- * eighteen β€” so those come back `null`, not `false`, and the UI prints no claim
303
- * about them rather than an invented one.
304
- */
305
- function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
306
- const meta = new Map<string, DiscoverFieldMeta>(
307
- (v?.filterMeta || []).map((m) => [m.name, m])
308
- );
309
- const lead = new Set(v?.lead || []);
310
- const byName = new Map<string, number[]>();
311
- preds.forEach((p, i) => {
312
- const list = byName.get(p.name);
313
- if (list) list.push(i);
314
- else byName.set(p.name, [i]);
315
- });
316
-
317
- const rows = (v?.fields || []).map((name) => {
318
- const m = meta.get(name);
319
- return {
320
- name,
321
- label: m?.label || name,
322
- hint: m?.hint || "",
323
- kind: m?.kind || "text",
324
- // β›” NO FALLBACK TO THE GLOBAL OPERATOR LIST. An older server that sends no per-field list
325
- // gets a row with no comparisons rather than all fourteen on every field β€” visibly
326
- // unfinished beats quietly offering `at least` on a yes/no column.
327
- operators: m?.operators || [],
328
- options: m?.options || [],
329
- at: byName.get(name) || [],
330
- populated: m ? !!m.populated : lead.has(name) ? true : null,
331
- narrowing: m ? !!m.narrowing : null,
332
- };
333
- });
334
- // Stable partition, never a sort: the server's order inside each half is the
335
- // order the engine lists them in, and re-alphabetising it would be this file
336
- // having an opinion about a server list.
337
- return [...rows.filter((r) => r.populated === true), ...rows.filter((r) => r.populated !== true)];
338
- }
339
-
340
- export default function AutomationFind({
341
- discover,
342
- recordsLimit,
343
- onRecordsLimit,
344
- joinOp,
345
- onJoinOp,
346
- preds,
347
- onPreds,
348
- estimate,
349
- onEstimate,
350
- }: Props) {
351
- const rows = buildRows(preds, discover);
352
- const known = new Set(discover?.fields || []);
353
- // The GLOBAL operator list is gone from this component: comparisons are per field now
354
- // (`row.operators`). `nullary` survives for STRAYS only β€” a stored condition on a field the
355
- // vendor dropped has no per-field row to read from, and it still has to render to be removable.
356
- const nullary = new Set(discover?.nullaryOperators || []);
357
- const withValues = rows.filter((r) => r.populated === true);
358
- const rest = rows.filter((r) => r.populated !== true);
359
- const knownMeta = !!(discover?.filterMeta || []).length;
360
- // ⚠ THE STORED FILTER CAN NAME A FIELD THE LIST NO LONGER HAS β€” a vocabulary
361
- // that moved, an automation copied from elsewhere. It must stay VISIBLE and
362
- // REMOVABLE: a condition the user cannot see is one they cannot delete, and
363
- // every Save keeps sending it. Same defect as a `<select>` whose value matches
364
- // no option, one level up.
365
- const strays = preds
366
- .map((p, i) => ({ p, i }))
367
- .filter(({ p }) => !known.has(p.name));
368
-
369
- const maxRecords = discover?.guard?.maxRecords || discover?.maxRecords || 500;
370
-
371
- /** D-69 β€” the raw text of the input a person is typing in right now (see `Draft`). */
372
- const [draft, setDraft] = useState<Draft | null>(null);
373
-
374
- /**
375
- * ⭐ WAVE 27 Β· OWNER ITEM 29 β€” which condition's value is open in the BIG editor, if any.
376
- *
377
- * β›” THE TEXT IS HELD HERE, NOT WRITTEN THROUGH ON EVERY KEYSTROKE, and that is the one place
378
- * this differs from the rail input beside it. The rail input writes per keystroke on purpose
379
- * (a Save pressed straight from the field must not store the previous value β€” D-69's note).
380
- * A modal has its own Save, so per-keystroke writes would buy nothing and would make Cancel
381
- * a lie: the value would already be in the config by the time it was pressed.
382
- * ⚠ The ANCHOR is captured at click time and stored, because the button it came from is
383
- * inside a panel that scrolls β€” re-reading it later would place the overlay against a rect
384
- * that has moved.
385
- */
386
- const [big, setBig] = useState<{
387
- key: string;
388
- index: number;
389
- label: string;
390
- multi: boolean;
391
- text: string;
392
- anchor: AnchorRect;
393
- } | null>(null);
394
-
395
- /**
396
- * ⭐ ITEM 16 / D-71 β€” THE OBSERVED CATEGORY VALUES, fetched WHEN THIS PANEL OPENS.
397
- *
398
- * β›” ON MOUNT, ONCE, AND NEVER ON THE POLLED PAYLOAD. This component is rendered only while the
399
- * Find panel is open, so mounting IS the panel opening β€” and the server moved these off
400
- * `GET /automations` after measuring that deriving them reads two user tables plus the platform
401
- * master, i.e. a network round-trip per open tab every 2.5 s. Putting the request here is the
402
- * client half of that same decision, not an optimisation.
403
- *
404
- * ⚠ AN EMPTY LIST IS AN ANSWER AND IS RENDERED AS ONE. It means this deployment has not seen a
405
- * category value yet β€” which is TRUE for a fresh tenant β€” and the field keeps its free-text
406
- * input either way. It must never read as "loading forever", and it must never be filled in
407
- * with a guess: D-59 is explicit that an invented taxonomy is worse than no dropdown.
408
- */
409
- const [cats, setCats] = useState<{ value: string; count: number }[]>([]);
410
- useEffect(() => {
411
- const ac = new AbortController();
412
- discoverCategories(ac.signal)
413
- .then((r) => setCats(Array.isArray(r?.options) ? r.options : []))
414
- // Fail-quiet, on purpose: the picker is an ASSIST over a control that works without it.
415
- // An error banner here would report a broken panel when the only thing missing is a
416
- // convenience β€” and the free-text input beside it is unaffected.
417
- .catch(() => setCats([]));
418
- return () => ac.abort();
419
- }, []);
420
-
421
- const setAt = (i: number, patch: Partial<Predicate>) =>
422
- onPreds(preds.map((p, j) => (j === i ? { ...p, ...patch } : p)));
423
-
424
- const removeAt = (i: number) => onPreds(preds.filter((_p, j) => j !== i));
425
-
426
- const toggleField = (row: FieldRow) => {
427
- if (row.at.length) {
428
- onPreds(preds.filter((p) => p.name !== row.name));
429
- return;
430
- }
431
- onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }]);
432
- };
433
-
434
- /** One condition line β€” the comparison, its value, and a way out. */
435
- const condition = (i: number, label: string, row?: FieldRow) => {
436
- const p = preds[i];
437
- if (!p) return null;
438
- // The field's OWN comparisons. `row` is absent only for a stray (a stored condition on a
439
- // field the vendor no longer offers), which keeps the raw token so it stays removable.
440
- const ops = row?.operators || [];
441
- const cur = ops.find((o) => o.value === p.operator);
442
- const isNullary = cur ? cur.nullary : nullary.has(p.operator);
443
- const isMulti = !!cur?.multi;
444
- const options = row?.options || [];
445
- const rowKey = `${p.name}-${i}`;
446
- // D-69: the focused input shows what was TYPED; every other one shows the stored value.
447
- const shown = draft && draft.key === rowKey ? draft.text : valueText(p.value);
448
- /*
449
- * ⭐ ITEM 16 / D-71 β€” WHICH FIELDS GET THE OBSERVED-VALUES PICKER, DERIVED OFF THE WIRE.
450
- *
451
- * β›” NOT A CLIENT-SIDE LIST OF FIELD NAMES. Naming the vendor's two category columns here
452
- * would be the D-55 class verbatim β€” the wave-9 silent-drop shape, a client copy of a server
453
- * vocabulary that is free to drift the day the engine adds a third one. (Their literal keys
454
- * are deliberately not written anywhere in this file: the gate asserts the tokens are ABSENT,
455
- * and an absence check cannot tell a hard-coded list from the comment forbidding one.)
456
- * The server already publishes the answer twice over: `kind: "choice"` is its own declaration
457
- * (`BD_FIELD_KINDS`), and `filter_meta` deliberately ships `options: []` for those fields
458
- * because their vocabulary is OBSERVED rather than declared and arrives on its own route.
459
- * So the rule is exactly that: a choice-kind field with no declared options is one whose
460
- * values we can only have learned by seeing them. A new choice field inherits this for free.
461
- */
462
- const wantsObserved = row?.kind === "choice" && !options.length;
463
- /** D-71 β€” APPEND, never replace: the picker has to compose with the comma list. */
464
- const appendValue = (v: string) => {
465
- const has = shown
466
- .split(",")
467
- .map((s) => s.trim().toLowerCase())
468
- .filter(Boolean);
469
- // Picking the same value twice is a no-op rather than a duplicate: the server expands a
470
- // multi-value condition into an OR, and `beauty OR beauty` costs a slot to say nothing.
471
- if (has.includes(v.trim().toLowerCase())) return;
472
- const next = shown.trim() ? `${shown.replace(/[\s,]+$/, "")}, ${v}` : v;
473
- setDraft(null);
474
- setAt(i, { value: parseValue(next, isMulti) });
475
- };
476
- return (
477
- <div className="autob-cond" key={rowKey}>
478
- <select
479
- className="auto-input is-small"
480
- aria-label={`Comparison for ${label}`}
481
- value={p.operator}
482
- onChange={(e) => setAt(i, { operator: e.target.value })}
483
- >
484
- {/* The stored value is ALWAYS an option. A select whose value matches no
485
- option renders the FIRST one, and the next Save writes a comparison
486
- nobody chose β€” this codebase has paid for that twice. */}
487
- {p.operator && !ops.some((o) => o.value === p.operator) ? (
488
- <option value={p.operator}>{p.operator}</option>
489
- ) : null}
490
- {ops.map((o) => (
491
- <option key={o.value} value={o.value}>
492
- {o.label}
493
- </option>
494
- ))}
495
- </select>
496
- {isNullary ? null : options.length ? (
497
- // A fixed vocabulary gets a dropdown. Owner item 2: a yes/no column was a box you
498
- // typed `true` into, beside a comparison list that offered "at least".
499
- <select
500
- className="auto-input is-small"
501
- aria-label={`Value for ${label}`}
502
- value={valueText(p.value)}
503
- onChange={(e) => setAt(i, { value: e.target.value })}
504
- >
505
- <option value="">Choose…</option>
506
- {options.map((o) => (
507
- <option key={o.value} value={o.value}>
508
- {o.label}
509
- </option>
510
- ))}
511
- </select>
512
- ) : (
513
- <input
514
- className="auto-input is-small"
515
- type={row?.kind === "number" ? "number" : "text"}
516
- aria-label={`Value for ${label}`}
517
- // ⭐ OWNER ITEM 3. Several comma-separated values become an "any of" condition, which
518
- // the server sends as its own OR group β€” so it does NOT drag Followers into a union
519
- // the way the Match dropdown would.
520
- placeholder={isMulti ? "floral, flower, beauty" : ""}
521
- // D-69: `shown` is the RAW text while this input has focus, so a trailing comma
522
- // survives long enough to type the next value after it.
523
- value={shown}
524
- onFocus={() => setDraft({ key: rowKey, text: valueText(p.value) })}
525
- onChange={(e) => {
526
- setDraft({ key: rowKey, text: e.target.value });
527
- // The STORE still updates on every keystroke. Parsing only on blur would mean a
528
- // Save pressed straight from the field wrote the previous value β€” trading a typing
529
- // bug for a data-loss one.
530
- setAt(i, { value: parseValue(e.target.value, isMulti) });
531
- }}
532
- onBlur={(e) => {
533
- setDraft(null);
534
- setAt(i, { value: parseValue(e.target.value, isMulti) });
535
- }}
536
- />
537
- )}
538
- {/* ⭐ WAVE 27 Β· OWNER ITEM 29 β€” A WIDE EDITOR FOR THE VALUES THAT DO NOT FIT.
539
- β›” THE COMPLAINT IS GEOMETRY, and the geometry is a CHAIN nothing here can widen:
540
- `.auto-panel` is 380px, `.autob-cond .auto-input` divides what is left across three
541
- controls, and `.is-small` trims it again β€” so a bio phrase list ("floral, flower,
542
- wedding florist, event styling") is typed six characters at a time through a box
543
- that scrolls sideways. The panel cannot grow; the EDITOR can leave it, and an
544
- overlay is drawn in a body portal, so it is not bound by that chain at all.
545
- ⚠ ALWAYS OFFERED, never "appears once the text is long": a control that materialises
546
- at some threshold is one people do not know exists at the moment they need it.
547
- ⚠ NOT on a `<select>` value (a fixed vocabulary has nothing to expand) and not on a
548
- nullary comparison (which has no value at all). */}
549
- {!isNullary && !options.length ? (
550
- <button
551
- type="button"
552
- className="auto-input is-small autoc-expand"
553
- aria-label={`Open a bigger editor for ${label}`}
554
- title="Edit in a bigger box"
555
- onClick={(e) => {
556
- // ⚠ READ SYNCHRONOUSLY from the event. `currentTarget` is null by the time React
557
- // re-invokes a state updater, and a null rect here paints the overlay at 0,0 β€”
558
- // measured, in this repo, on a different control ([[react-event-currenttarget-updater]]).
559
- const r = e.currentTarget.getBoundingClientRect();
560
- setBig({
561
- key: rowKey,
562
- index: i,
563
- label,
564
- multi: isMulti,
565
- text: valueText(p.value),
566
- anchor: { left: r.left, top: r.top, right: r.right, bottom: r.bottom,
567
- width: r.width, height: r.height },
568
- });
569
- }}
570
- >
571
- {/* Drawn, never a glyph: the design constitution's "no emojis in the UI" covers
572
- the arrow characters too, and every other mark in this product is a path in the
573
- same 16x16 stroke vocabulary. Two corners pulling apart = "make this bigger". */}
574
- <svg viewBox="0 0 16 16" aria-hidden className="autoc-expand-icon">
575
- <path d="M9.5 2.5h4v4M13.5 2.5 9.6 6.4" />
576
- <path d="M6.5 13.5h-4v-4M2.5 13.5l3.9-3.9" />
577
- </svg>
578
- </button>
579
- ) : null}
580
- {/* ⭐ ITEM 16 / D-71 β€” THE APPEND-PICKER, BESIDE the input and never instead of it.
581
- Free text stays the primary control: these are the values this deployment has SEEN,
582
- not the values that exist, so the picker is a shortcut over a superset it cannot
583
- enumerate. Appending in code also sidesteps D-69 entirely β€” a picked value never has
584
- to survive a round trip through the text box. */}
585
- {wantsObserved && !isNullary ? (
586
- <select
587
- className="auto-input is-small autoc-catpick"
588
- aria-label={`Add a value seen before, to ${label}`}
589
- title={
590
- cats.length
591
- ? "Values this workspace has actually seen, most-seen first. Adds to the list."
592
- : "No category values have been seen in your data yet. Type one."
593
- }
594
- value=""
595
- disabled={!cats.length}
596
- onChange={(e) => {
597
- if (e.target.value) appendValue(e.target.value);
598
- }}
599
- >
600
- <option value="">{cats.length ? "Seen before…" : "None seen yet"}</option>
601
- {cats.map((c) => (
602
- // The COUNT is the honest half (D-59): a value seen once and one seen forty times
603
- // are different bets, and an alphabetical list of bare strings hides that.
604
- <option key={c.value} value={c.value}>
605
- {c.value} ({c.count.toLocaleString()})
606
- </option>
607
- ))}
608
- </select>
609
- ) : null}
610
- {isMulti && Array.isArray(p.value) && p.value.length > 1 ? (
611
- /*
612
- * ⭐ ITEM 16 / D-71 β€” HOW MANY VALUES THIS CONDITION CARRIES, and against what ceiling.
613
- *
614
- * The COUNT is ours and is always shown. The CEILING is the server's and is shown only
615
- * when the server sends one (`guard.maxValues` β€” an open `ASK ->A:`; `guard` ships
616
- * `{minNarrowing, maxRecords}` today).
617
- * β›” NO CLIENT-SIDE `4`. D-71's exit says "how many of D-68's 4 value slots" β€” but A
618
- * shipped `depth_refusal()`, which computes the depth of the shape actually emitted
619
- * rather than budgeting fixed slots, so the number 4 describes a model that no longer
620
- * exists. Printing it would be a client copy of a server rule that has already changed
621
- * once, which is the specific failure this file's header refuses to commit
622
- * ([[measure-the-real-call]]: a correct-looking answer about the wrong subject).
623
- */
624
- <span className="autob-cond-any" title="Any one of these is a match">
625
- any of {p.value.length}
626
- {discover?.guard?.maxValues ? ` of ${discover.guard.maxValues}` : ""}
627
- </span>
628
- ) : null}
629
- <button
630
- type="button"
631
- className="autob-cond-x"
632
- aria-label={`Remove this condition on ${label}`}
633
- title="Remove this condition"
634
- onClick={() => removeAt(i)}
635
- >
636
- <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
637
- <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
638
- </svg>
639
- </button>
640
- </div>
641
- );
642
- };
643
-
644
- const fieldRow = (row: FieldRow) => {
645
- const on = row.at.length > 0;
646
- return (
647
- <div className={"autob-tgl" + (on ? " is-on" : "")} key={row.name}>
648
- <div className="autob-tgl-head">
649
- <button
650
- type="button"
651
- className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
652
- aria-pressed={on}
653
- aria-label={`${on ? "Stop searching" : "Search"} on ${row.label}`}
654
- title={`${on ? "Stop searching" : "Search"} on ${row.label}`}
655
- onClick={() => toggleField(row)}
656
- >
657
- <span className="auto-step-switch-knob" />
658
- </button>
659
- <span className="autob-tgl-mark">
660
- <FilterMark name={row.name} />
661
- </span>
662
- {/* ⭐ THE HUMAN LABEL (owner item 1: "wtf is id/fbid").
663
- This used to render the vendor's own column name verbatim, and the comment
664
- defending it was RIGHT about the reason β€” a refusal names the field, and a label
665
- that reads differently makes the error unmatchable. So the label did not move
666
- alone: `field_label()` is what the SERVER's refusals use too, which is the only
667
- version of this change that does not trade one confusion for another. */}
668
- <span className="autob-tgl-name" title={row.hint || undefined}>
669
- {row.label}
670
- </span>
671
- {/*
672
- ⚠ ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
673
- non-narrowing field "broad" AND every unpopulated one "no values seen" β€”
674
- which put two chips on 18 of the 21 rows, and one of them repeated the group
675
- heading the row was already sitting under. A mark that is on almost every row
676
- stops being a mark. Read off the screenshot; no assertion could have said it.
677
-
678
- So: the group label carries POPULATED (it is what the groups ARE), and the
679
- chip carries NARROWING, inverted to mark the five that DO narrow. That is the
680
- actionable half β€” the server refuses a filter with no narrowing condition, so
681
- "these are the ones that satisfy it" is the sentence a user needs, and
682
- "this one does not" is not.
683
- */}
684
- {row.narrowing === true ? (
685
- <span
686
- className="autob-tgl-flag is-narrow"
687
- title="A search needs at least one condition like this."
688
- >
689
- narrows
690
- </span>
691
- ) : null}
692
- </div>
693
- {on ? (
694
- <div className="autob-tgl-body">
695
- {row.at.map((i) => condition(i, row.label, row))}
696
- {row.hint ? <p className="autob-tgl-hint">{row.hint}</p> : null}
697
- <button
698
- type="button"
699
- className="autob-cond-add"
700
- onClick={() =>
701
- onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
702
- }
703
- >
704
- Another condition on {row.label}
705
- </button>
706
- </div>
707
- ) : null}
708
- </div>
709
- );
710
- };
711
-
712
- return (
713
- <>
714
- <div className="auto-field">
715
- <label htmlFor="auto-records">How many profiles to fetch</label>
716
- <input
717
- id="auto-records"
718
- className="auto-input"
719
- type="number"
720
- min={1}
721
- max={maxRecords}
722
- value={recordsLimit}
723
- onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
724
- />
725
- </div>
726
- {/* Owner item 5: "Stop at the 'A search must be at most 500 profiles a run'". The two
727
- sentences that followed explained the vendor's billing model to somebody who wants a
728
- list of florists. */}
729
- <p className="auto-hint">At most {maxRecords.toLocaleString()} profiles a run.</p>
730
-
731
- <h3>Conditions</h3>
732
- <div className="auto-field autob-match">
733
- <label htmlFor="auto-joinop">Match</label>
734
- <select
735
- id="auto-joinop"
736
- className="auto-input"
737
- value={joinOp}
738
- onChange={(e) => onJoinOp(e.target.value)}
739
- >
740
- <option value="and">All of them</option>
741
- <option value="or">Any of them</option>
742
- </select>
743
- </div>
744
-
745
- {!rows.length ? (
746
- <p className="auto-note">
747
- The searchable fields have not loaded yet.
748
- </p>
749
- ) : null}
750
-
751
- {withValues.length ? (
752
- <div className="autob-tglgroup">
753
- <p
754
- className="autob-tglgroup-label"
755
- title="Most accounts have this filled in."
756
- >
757
- Usually filled in
758
- </p>
759
- {withValues.map(fieldRow)}
760
- </div>
761
- ) : null}
762
-
763
- {rest.length ? (
764
- <div className="autob-tglgroup">
765
- <p
766
- className="autob-tglgroup-label"
767
- title={
768
- knownMeta
769
- ? "Most accounts leave these blank, so a condition here can return nothing."
770
- : "We have not measured how often these are filled in."
771
- }
772
- >
773
- {knownMeta ? "Often blank" : "Not measured"}
774
- </p>
775
- {rest.map(fieldRow)}
776
- </div>
777
- ) : null}
778
-
779
- {strays.length ? (
780
- <div className="autob-tglgroup">
781
- <p className="autob-tglgroup-label">Not in the searchable list</p>
782
- {strays.map(({ p, i }) => (
783
- <div className="autob-tgl is-on is-stray" key={`stray-${i}`}>
784
- <div className="autob-tgl-head">
785
- {/* A stray gets a mark too β€” "every filter row" includes the ones the vendor no
786
- longer offers, and a row missing the icon its neighbours have would read as a
787
- different KIND of thing rather than as a field that fell out of the list. It
788
- draws the neutral fallback by construction: a stray is, by definition, not in
789
- the vocabulary this component has arms for. */}
790
- <span className="autob-tgl-mark">
791
- <FilterMark name={p.name} />
792
- </span>
793
- <span className="autob-tgl-name">{p.name}</span>
794
- <span className="autob-tgl-flag is-stray" title="The server will refuse this condition by name.">
795
- not searchable
796
- </span>
797
- </div>
798
- <div className="autob-tgl-body">{condition(i, p.name)}</div>
799
- </div>
800
- ))}
801
- </div>
802
- ) : null}
803
-
804
- {/* The consequence kept, the mechanism dropped: a condition on an often-blank field
805
- returning nothing is a thing that will happen to somebody and confuse them. Why the
806
- search is slow when broad is our problem, not theirs. */}
807
- <p className="auto-hint">
808
- Conditions on often-blank fields can come back with nothing.
809
- </p>
810
-
811
- <h3>What it costs</h3>
812
- <div className="auto-head-actions">
813
- <button type="button" className="auto-btn" onClick={onEstimate}>
814
- Estimate this search
815
- </button>
816
- </div>
817
- {estimate ? (
818
- <p className="auto-hint">
819
- About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
820
- {estimate.unitUsd} each.{" "}
821
- {/*
822
- THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run and this
823
- deployment cannot read its own balance, so presenting this as a billed figure
824
- would be inventing a measurement.
825
- */}
826
- <strong>This is an estimate</strong> β€” {estimate.note}.
827
- </p>
828
- ) : null}
829
-
830
- {/* ⭐ WAVE 27 Β· OWNER ITEM 29 β€” THE BIG EDITOR, rendered ONCE for the whole panel.
831
- β›” Not one overlay per condition row: `AnchoredOverlay` mounts a body portal and
832
- installs document-level dismiss/focus handlers, so N of them would be N listener
833
- stacks fighting over one Escape key. One overlay, told which row it is editing.
834
- ⚠ `role="dialog"`, not "menu": it holds a text field, and the menu layer's arrow-key
835
- handling would take the cursor keys away from the text being typed. */}
836
- {big ? (
837
- <AnchoredOverlay
838
- anchor={big.anchor}
839
- className="autoc-bigedit"
840
- placement="right-start"
841
- role="dialog"
842
- ariaLabel={`Value for ${big.label}`}
843
- onDismiss={() => setBig(null)}
844
- dataKind="find-value-editor"
845
- >
846
- <label htmlFor="autoc-bigedit-text">{big.label}</label>
847
- <textarea
848
- id="autoc-bigedit-text"
849
- className="autoc-bigedit-text"
850
- data-overlay-autofocus
851
- autoFocus
852
- rows={7}
853
- spellCheck={false}
854
- value={big.text}
855
- placeholder={big.multi ? "floral, flower, wedding florist, event styling" : ""}
856
- onChange={(e) => setBig((cur) => (cur ? { ...cur, text: e.target.value } : cur))}
857
- onKeyDown={(e) => {
858
- // Escape abandons; Ctrl/Cmd+Enter commits. A bare Enter types a NEWLINE, because
859
- // this is a textarea and the whole reason it exists is that the value is long.
860
- if (e.key === "Escape") setBig(null);
861
- if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
862
- setAt(big.index, { value: parseValue(big.text, big.multi) });
863
- setBig(null);
864
- }
865
- }}
866
- />
867
- {/* The same sentence the rail input's placeholder makes, said where there is room
868
- for it: a comma list is several values, and the server turns them into an OR. */}
869
- {big.multi ? (
870
- <p className="auto-hint">
871
- Separate values with commas. The search matches any of them.
872
- </p>
873
- ) : null}
874
- <div className="auto-head-actions">
875
- <button
876
- type="button"
877
- className="auto-btn auto-btn--primary"
878
- onClick={() => {
879
- setAt(big.index, { value: parseValue(big.text, big.multi) });
880
- setBig(null);
881
- }}
882
- >
883
- Done
884
- </button>
885
- <button type="button" className="auto-btn" onClick={() => setBig(null)}>
886
- Cancel
887
- </button>
888
- </div>
889
- </AnchoredOverlay>
890
- ) : null}
891
- </>
892
- );
893
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationFind.tsx β€” the discovery filter, as TOGGLES (owner item 6,
3
+ // contract C4).
4
+ //
5
+ // WHAT CHANGED AND WHY. It was a condition BUILDER: an empty row, a field
6
+ // dropdown listing 21 names, "Add a condition". That shape asks the user to
7
+ // remember what is searchable before they can look, and it hid the only fact
8
+ // that decides whether a search returns anything at all β€” which fields actually
9
+ // carry values. The corpus is 620 million profiles and every run is billed, so
10
+ // "I did not know I could filter on that" and "I filtered on a field that is
11
+ // empty on every row" are both expensive mistakes made in silence.
12
+ //
13
+ // So every searchable field is ON SCREEN, off by default, and turning one on is
14
+ // what creates its condition. The list leads with the fields MEASURED to carry
15
+ // values; the rest are grouped under what is known about them, and neither group
16
+ // is hidden β€” R3 already decided that "every filter" means the 21 we can stand
17
+ // behind, so all 21 are visible.
18
+ //
19
+ // β›” THE VOCABULARY IS THE SERVER'S, ALL OF IT. Field names, operators, which
20
+ // operators take no value, the record ceiling and (once C4 lands it) which
21
+ // fields are populated and which narrow β€” every one of those rides on
22
+ // `GET /automations`. This file holds no list of its own. The reason is the one
23
+ // `automationApi.ts:11-15` gives for cron presets: the thing that ACCEPTS a
24
+ // filter is Python, and a client copy of what it accepts is a copy that can
25
+ // offer a search the server refuses.
26
+ //
27
+ // β›” AND IT DOES NOT RE-IMPLEMENT THE GUARD. `guard` carries the server's
28
+ // numbers, so the rows can say which fields narrow β€” but the refusal is the
29
+ // server's to make and this surface prints it VERBATIM when it comes back
30
+ // (`DiscoverGuard`'s note). A client that predicts the refusal is a second copy
31
+ // of the rule, free to disagree with the first, and when they disagree the user
32
+ // gets a Save button that is disabled for a reason nobody can see.
33
+ // ---------------------------------------------------------------------------
34
+ import { useEffect, useState } from "react";
35
+ // ⭐ WAVE 27 item 29 β€” the overlay layer the grid already owns, consumed rather than
36
+ // re-implemented: it is a body portal (so it escapes `.auto-panel`'s 380px), and it brings
37
+ // the dismiss/focus/placement behaviour every other popover on this product already has.
38
+ import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
39
+ import type { AnchorRect } from "../customer-grid/OverlaySurface";
40
+
41
+ import type {
42
+ DiscoverEstimate,
43
+ DiscoverFieldMeta,
44
+ DiscoverOperator,
45
+ DiscoverVocab,
46
+ Predicate,
47
+ } from "./automationApi";
48
+ import { discoverCategories } from "./automationApi";
49
+
50
+ interface Props {
51
+ /** The server-declared discovery vocabulary (absent until the list loads). */
52
+ discover?: DiscoverVocab;
53
+ recordsLimit: number;
54
+ onRecordsLimit: (n: number) => void;
55
+ joinOp: string;
56
+ onJoinOp: (v: string) => void;
57
+ preds: Predicate[];
58
+ onPreds: (next: Predicate[]) => void;
59
+ estimate: DiscoverEstimate | null;
60
+ onEstimate: () => void;
61
+ }
62
+
63
+ /**
64
+ * A FILTER FIELD'S ICON (owner item 5). Drawn, `currentColor`, never an emoji β€” and in the
65
+ * existing `TriggerMark`/`ActionMark` language rather than a new one: same 16 viewBox, same 15px
66
+ * box, same 1.4 stroke, so a row here and a card in the builder read as one product.
67
+ *
68
+ * ⚠ SHARED SHAPES WHERE THE FIELDS SHARE A MEANING, distinct everywhere else. `TriggerMark`'s
69
+ * note settled the principle β€” a column of identical glyphs is decoration, the eye learns nothing
70
+ * β€” but its converse matters just as much here: `bio_hashtags` and `post_hashtags` ARE both
71
+ * hashtags, and drawing two different marks for them would invent a distinction the vendor does
72
+ * not make. Twenty-one contrived glyphs would be twenty-one things to misread.
73
+ *
74
+ * β›” THE FALLBACK IS NOT A MEMBER OF THE SET, which is the `ActionMark` scar exactly: its default
75
+ * used to BE the pencil, a real member, so every unmatched kind silently borrowed "edit" and a
76
+ * fallback could not be told from a match. The vocabulary is the SERVER's β€” it can grow a field
77
+ * tomorrow β€” so an unmatched name draws a neutral mark that is deliberately meaningless.
78
+ */
79
+ function FilterMark({ name }: { name: string }) {
80
+ const common = {
81
+ width: 15, height: 15, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor",
82
+ strokeWidth: 1.4, strokeLinecap: "round" as const, strokeLinejoin: "round" as const,
83
+ "aria-hidden": true,
84
+ };
85
+ // Audience size β€” two figures, one behind the other.
86
+ if (name === "followers")
87
+ return (
88
+ <svg {...common}>
89
+ <circle cx="6.2" cy="5.6" r="2.4" />
90
+ <path d="M2.2 13c.5-2 2.1-3.2 4-3.2s3.5 1.2 4 3.2" />
91
+ <path d="M10.6 3.6a2.4 2.4 0 0 1 0 4M11.4 9.9c1.4.4 2.4 1.5 2.8 3.1" />
92
+ </svg>
93
+ );
94
+ // Who this account follows β€” a figure with an outbound arrow.
95
+ if (name === "following")
96
+ return (
97
+ <svg {...common}>
98
+ <circle cx="6" cy="5.6" r="2.4" />
99
+ <path d="M1.8 13c.5-2 2.1-3.2 4.2-3.2 .6 0 1.2.1 1.7.3" />
100
+ <path d="M9.8 10.6h4.2M12.2 8.8l1.8 1.8-1.8 1.8" />
101
+ </svg>
102
+ );
103
+ if (name === "posts_count")
104
+ return (
105
+ <svg {...common}>
106
+ <rect x="2.6" y="2.6" width="4.6" height="4.6" rx="1" />
107
+ <rect x="8.8" y="2.6" width="4.6" height="4.6" rx="1" />
108
+ <rect x="2.6" y="8.8" width="4.6" height="4.6" rx="1" />
109
+ <rect x="8.8" y="8.8" width="4.6" height="4.6" rx="1" />
110
+ </svg>
111
+ );
112
+ // A story highlight β€” the ring Instagram draws around one.
113
+ if (name === "highlights_count")
114
+ return (
115
+ <svg {...common}>
116
+ <circle cx="8" cy="8" r="5.6" strokeDasharray="2.6 1.8" />
117
+ <circle cx="8" cy="8" r="2.2" />
118
+ </svg>
119
+ );
120
+ if (name === "avg_engagement")
121
+ return (
122
+ <svg {...common}>
123
+ <path d="M8 13.2 3.4 8.8a2.9 2.9 0 0 1 4.6-3.4 2.9 2.9 0 0 1 4.6 3.4z" />
124
+ </svg>
125
+ );
126
+ if (name === "biography")
127
+ return (
128
+ <svg {...common}>
129
+ <rect x="2.4" y="2.8" width="11.2" height="10.4" rx="1.6" />
130
+ <path d="M4.8 6h6.4M4.8 8.4h6.4M4.8 10.8h3.6" />
131
+ </svg>
132
+ );
133
+ if (name === "category_name" || name === "business_category_name")
134
+ return (
135
+ <svg {...common}>
136
+ <path d="M8.4 2.6H13v4.6l-6.2 6.2-4.6-4.6z" />
137
+ <circle cx="10.8" cy="5.2" r="0.9" />
138
+ </svg>
139
+ );
140
+ if (name === "is_business_account" || name === "is_professional_account")
141
+ return (
142
+ <svg {...common}>
143
+ <rect x="2.2" y="5" width="11.6" height="8.2" rx="1.6" />
144
+ <path d="M6 5V3.6a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1V5" />
145
+ </svg>
146
+ );
147
+ if (name === "is_verified")
148
+ return (
149
+ <svg {...common}>
150
+ <path d="M8 2.2l1.7 1.2 2-.2.6 2 1.7 1.1-.9 1.9.9 1.9-1.7 1.1-.6 2-2-.2L8 14.2l-1.7-1.2-2 .2-.6-2L2 10.1l.9-1.9L2 6.3l1.7-1.1.6-2 2 .2z" />
151
+ <path d="m5.8 8.1 1.5 1.5 3-3.1" />
152
+ </svg>
153
+ );
154
+ // The handle, and the display name it is written under.
155
+ if (name === "account" || name === "profile_name")
156
+ return (
157
+ <svg {...common}>
158
+ <circle cx="8" cy="8" r="2.4" />
159
+ <path d="M10.4 5.6v3.2a1.9 1.9 0 0 0 3.2 1.3A5.8 5.8 0 1 0 11 13.1" />
160
+ </svg>
161
+ );
162
+ if (name === "full_name")
163
+ return (
164
+ <svg {...common}>
165
+ <circle cx="8" cy="5.6" r="2.6" />
166
+ <path d="M3 13.4c.7-2.3 2.6-3.6 5-3.6s4.3 1.3 5 3.6" />
167
+ </svg>
168
+ );
169
+ if (name === "external_url" || name === "profile_url")
170
+ return (
171
+ <svg {...common}>
172
+ <path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
173
+ <path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
174
+ <path d="M6.2 8h3.6" />
175
+ </svg>
176
+ );
177
+ if (name === "bio_hashtags" || name === "post_hashtags")
178
+ return (
179
+ <svg {...common}>
180
+ <path d="M6.2 2.8 4.8 13.2M11.2 2.8 9.8 13.2M2.8 6h10.4M2.2 10h10.4" />
181
+ </svg>
182
+ );
183
+ if (name === "related_accounts")
184
+ return (
185
+ <svg {...common}>
186
+ <circle cx="8" cy="3.6" r="1.8" />
187
+ <circle cx="3.6" cy="12" r="1.8" />
188
+ <circle cx="12.4" cy="12" r="1.8" />
189
+ <path d="M6.8 5.2 4.6 10.4M9.2 5.2l2.2 5.2M5.4 12h5.2" />
190
+ </svg>
191
+ );
192
+ // The vendor's own record keys β€” the thing you hold to open exactly one row.
193
+ if (name === "id" || name === "fbid")
194
+ return (
195
+ <svg {...common}>
196
+ <circle cx="5.4" cy="10.6" r="2.6" />
197
+ <path d="M7.2 8.8 13 3M10.6 5.4l1.6 1.6M9.2 6.8l1.6 1.6" />
198
+ </svg>
199
+ );
200
+ return (
201
+ <svg {...common}>
202
+ <rect x="3.2" y="3.2" width="9.6" height="9.6" rx="2.2" />
203
+ <circle cx="8" cy="8" r="1.4" />
204
+ </svg>
205
+ );
206
+ }
207
+
208
+ /** One field's line in the list, with everything known about it. */
209
+ interface FieldRow {
210
+ name: string;
211
+ /** What the row is CALLED. Falls back to the raw name only if the server sent none. */
212
+ label: string;
213
+ hint: string;
214
+ kind: string;
215
+ operators: DiscoverOperator[];
216
+ options: { value: string; label: string }[];
217
+ /** Every stored condition naming this field, with its index in the saved array. */
218
+ at: number[];
219
+ /** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
220
+ populated: boolean | null;
221
+ /** A condition here cuts the corpus down. `null` = not said. */
222
+ narrowing: boolean | null;
223
+ }
224
+
225
+ /** A stored value β†’ what the text box shows. A list is the "any of" shape. */
226
+ function valueText(v: Predicate["value"]): string {
227
+ if (Array.isArray(v)) return v.join(", ");
228
+ return v === undefined || v === null ? "" : String(v);
229
+ }
230
+
231
+ /**
232
+ * What the user typed β†’ what is stored. Comma-separated becomes a LIST for the operators that
233
+ * accept one, and stays a plain string for the ones that do not.
234
+ *
235
+ * ⚠ A single value stays a SCALAR rather than a one-element list β€” the server sends scalars
236
+ * flat and lists as a nested OR group, and a one-element group is a shape nothing has been
237
+ * billed against.
238
+ */
239
+ function parseValue(text: string, multi: boolean): Predicate["value"] {
240
+ if (!multi) return text;
241
+ const parts = text.split(",").map((s) => s.trim()).filter(Boolean);
242
+ if (parts.length > 1) return parts;
243
+ // Keep the RAW text while it is still being typed β€” trimming here would fight the cursor on
244
+ // every keystroke, and the server trims anyway.
245
+ return text;
246
+ }
247
+
248
+ /**
249
+ * ⭐ WAVE 26 Β· DEBT D-69 β€” A THIRD VALUE COULD NOT BE TYPED, and the cause was one round trip
250
+ * through this pair of functions.
251
+ *
252
+ * `parseValue` returns an ARRAY at 2+ values; `valueText` then renders that array as
253
+ * `join(", ")` β€” which has NO TRAILING COMMA. So on a controlled input the separator was
254
+ * normalised away between keystrokes: typing `,` onto `skincare, beauty` re-rendered as
255
+ * `skincare, beauty`, and the next character landed as `skincare, beautym`. Two keywords
256
+ * silently became one that matches nothing. ⚠ It hit the FIRST surface a new user meets (wave 24
257
+ * made this panel the only door) and it hit precisely the 3+ keyword list the feature was built
258
+ * for β€” the owner's *"if i want to include many keywords like floral, flower, beauty"*.
259
+ *
260
+ * β›” THE FIX IS THE ONE `parseValue`'s OWN COMMENT ALREADY DESCRIBES FOR THE 1-VALUE CASE:
261
+ * keep the raw text while it is being typed. That comment was right and its scope was too narrow
262
+ * β€” it protected the cursor at one value and handed the 2+ case to `join`. So the raw text is
263
+ * held for whichever input is FOCUSED, and the stored value is still parsed on every keystroke
264
+ * (so nothing depends on blur to save) and re-parsed on blur (so the display settles).
265
+ *
266
+ * ⚠ KEYED BY THE ROW'S REACT KEY, not by index alone: two conditions on the same field are
267
+ * ordinary here ("Another condition on Bio"), and an index-only key would leak one row's draft
268
+ * into its sibling on a removal.
269
+ */
270
+ interface Draft {
271
+ key: string;
272
+ text: string;
273
+ }
274
+
275
+ /**
276
+ * The comparison a freshly toggled field starts with β€” ASKED FOR, never chosen here.
277
+ *
278
+ * β›” THE THIRD COSTUME OF ONE SCAR, and the reason this function no longer has an opinion.
279
+ * Wave 21 made a new condition NULLARY (`is_not_null`) so it would be saveable without a
280
+ * value, and called that "narrowing-in-the-right-direction". Wave 22 then wrote the narrowing
281
+ * law server-side and `is_not_null` is not in it. From that moment, toggling ANY field on and
282
+ * pressing Save returned "add at least one CONTENT condition…" β€” the error told the user to do
283
+ * the exact thing they had just done. Wave 24 deleted the wizard and made this panel the only
284
+ * door, so it stopped being a corner case and became the first thing a new user hits.
285
+ *
286
+ * The fix is not a better guess. It is that the module owning the guard also names the default
287
+ * (`automation_engine.default_operator`, asserted against `predicate_narrows` in
288
+ * `verify_automation.py`), and this file looks it up per FIELD. An absent one falls back to the
289
+ * server's first operator β€” never to a nullary, which is the thing that could not narrow.
290
+ */
291
+ function firstOperator(v: DiscoverVocab | undefined, name: string): string {
292
+ const meta = (v?.filterMeta || []).find((m) => m.name === name);
293
+ return meta?.defaultOperator || (v?.operators || [])[0] || "";
294
+ }
295
+
296
+ /**
297
+ * The rows, ordered: measured-populated first, then the rest.
298
+ *
299
+ * TWO SOURCES, AND THE FALLBACK IS NARROWER THAN THE REAL THING. With C4's
300
+ * `filterMeta` the answer is per field and complete. Without it, `lead` names
301
+ * the three fields seen carrying values and says NOTHING about the other
302
+ * eighteen β€” so those come back `null`, not `false`, and the UI prints no claim
303
+ * about them rather than an invented one.
304
+ */
305
+ function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
306
+ const meta = new Map<string, DiscoverFieldMeta>(
307
+ (v?.filterMeta || []).map((m) => [m.name, m])
308
+ );
309
+ const lead = new Set(v?.lead || []);
310
+ const byName = new Map<string, number[]>();
311
+ preds.forEach((p, i) => {
312
+ const list = byName.get(p.name);
313
+ if (list) list.push(i);
314
+ else byName.set(p.name, [i]);
315
+ });
316
+
317
+ const rows = (v?.fields || []).map((name) => {
318
+ const m = meta.get(name);
319
+ return {
320
+ name,
321
+ label: m?.label || name,
322
+ hint: m?.hint || "",
323
+ kind: m?.kind || "text",
324
+ // β›” NO FALLBACK TO THE GLOBAL OPERATOR LIST. An older server that sends no per-field list
325
+ // gets a row with no comparisons rather than all fourteen on every field β€” visibly
326
+ // unfinished beats quietly offering `at least` on a yes/no column.
327
+ operators: m?.operators || [],
328
+ options: m?.options || [],
329
+ at: byName.get(name) || [],
330
+ populated: m ? !!m.populated : lead.has(name) ? true : null,
331
+ narrowing: m ? !!m.narrowing : null,
332
+ };
333
+ });
334
+ // Stable partition, never a sort: the server's order inside each half is the
335
+ // order the engine lists them in, and re-alphabetising it would be this file
336
+ // having an opinion about a server list.
337
+ return [...rows.filter((r) => r.populated === true), ...rows.filter((r) => r.populated !== true)];
338
+ }
339
+
340
+ export default function AutomationFind({
341
+ discover,
342
+ recordsLimit,
343
+ onRecordsLimit,
344
+ joinOp,
345
+ onJoinOp,
346
+ preds,
347
+ onPreds,
348
+ estimate,
349
+ onEstimate,
350
+ }: Props) {
351
+ const rows = buildRows(preds, discover);
352
+ const known = new Set(discover?.fields || []);
353
+ // The GLOBAL operator list is gone from this component: comparisons are per field now
354
+ // (`row.operators`). `nullary` survives for STRAYS only β€” a stored condition on a field the
355
+ // vendor dropped has no per-field row to read from, and it still has to render to be removable.
356
+ const nullary = new Set(discover?.nullaryOperators || []);
357
+ const withValues = rows.filter((r) => r.populated === true);
358
+ const rest = rows.filter((r) => r.populated !== true);
359
+ const knownMeta = !!(discover?.filterMeta || []).length;
360
+ // ⚠ THE STORED FILTER CAN NAME A FIELD THE LIST NO LONGER HAS β€” a vocabulary
361
+ // that moved, an automation copied from elsewhere. It must stay VISIBLE and
362
+ // REMOVABLE: a condition the user cannot see is one they cannot delete, and
363
+ // every Save keeps sending it. Same defect as a `<select>` whose value matches
364
+ // no option, one level up.
365
+ const strays = preds
366
+ .map((p, i) => ({ p, i }))
367
+ .filter(({ p }) => !known.has(p.name));
368
+
369
+ const maxRecords = discover?.guard?.maxRecords || discover?.maxRecords || 500;
370
+
371
+ /** D-69 β€” the raw text of the input a person is typing in right now (see `Draft`). */
372
+ const [draft, setDraft] = useState<Draft | null>(null);
373
+
374
+ /**
375
+ * ⭐ WAVE 27 Β· OWNER ITEM 29 β€” which condition's value is open in the BIG editor, if any.
376
+ *
377
+ * β›” THE TEXT IS HELD HERE, NOT WRITTEN THROUGH ON EVERY KEYSTROKE, and that is the one place
378
+ * this differs from the rail input beside it. The rail input writes per keystroke on purpose
379
+ * (a Save pressed straight from the field must not store the previous value β€” D-69's note).
380
+ * A modal has its own Save, so per-keystroke writes would buy nothing and would make Cancel
381
+ * a lie: the value would already be in the config by the time it was pressed.
382
+ * ⚠ The ANCHOR is captured at click time and stored, because the button it came from is
383
+ * inside a panel that scrolls β€” re-reading it later would place the overlay against a rect
384
+ * that has moved.
385
+ */
386
+ const [big, setBig] = useState<{
387
+ key: string;
388
+ index: number;
389
+ label: string;
390
+ multi: boolean;
391
+ text: string;
392
+ anchor: AnchorRect;
393
+ } | null>(null);
394
+
395
+ /**
396
+ * ⭐ ITEM 16 / D-71 β€” THE OBSERVED CATEGORY VALUES, fetched WHEN THIS PANEL OPENS.
397
+ *
398
+ * β›” ON MOUNT, ONCE, AND NEVER ON THE POLLED PAYLOAD. This component is rendered only while the
399
+ * Find panel is open, so mounting IS the panel opening β€” and the server moved these off
400
+ * `GET /automations` after measuring that deriving them reads two user tables plus the platform
401
+ * master, i.e. a network round-trip per open tab every 2.5 s. Putting the request here is the
402
+ * client half of that same decision, not an optimisation.
403
+ *
404
+ * ⚠ AN EMPTY LIST IS AN ANSWER AND IS RENDERED AS ONE. It means this deployment has not seen a
405
+ * category value yet β€” which is TRUE for a fresh tenant β€” and the field keeps its free-text
406
+ * input either way. It must never read as "loading forever", and it must never be filled in
407
+ * with a guess: D-59 is explicit that an invented taxonomy is worse than no dropdown.
408
+ */
409
+ const [cats, setCats] = useState<{ value: string; count: number }[]>([]);
410
+ useEffect(() => {
411
+ const ac = new AbortController();
412
+ discoverCategories(ac.signal)
413
+ .then((r) => setCats(Array.isArray(r?.options) ? r.options : []))
414
+ // Fail-quiet, on purpose: the picker is an ASSIST over a control that works without it.
415
+ // An error banner here would report a broken panel when the only thing missing is a
416
+ // convenience β€” and the free-text input beside it is unaffected.
417
+ .catch(() => setCats([]));
418
+ return () => ac.abort();
419
+ }, []);
420
+
421
+ const setAt = (i: number, patch: Partial<Predicate>) =>
422
+ onPreds(preds.map((p, j) => (j === i ? { ...p, ...patch } : p)));
423
+
424
+ const removeAt = (i: number) => onPreds(preds.filter((_p, j) => j !== i));
425
+
426
+ const toggleField = (row: FieldRow) => {
427
+ if (row.at.length) {
428
+ onPreds(preds.filter((p) => p.name !== row.name));
429
+ return;
430
+ }
431
+ onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }]);
432
+ };
433
+
434
+ /** One condition line β€” the comparison, its value, and a way out. */
435
+ const condition = (i: number, label: string, row?: FieldRow) => {
436
+ const p = preds[i];
437
+ if (!p) return null;
438
+ // The field's OWN comparisons. `row` is absent only for a stray (a stored condition on a
439
+ // field the vendor no longer offers), which keeps the raw token so it stays removable.
440
+ const ops = row?.operators || [];
441
+ const cur = ops.find((o) => o.value === p.operator);
442
+ const isNullary = cur ? cur.nullary : nullary.has(p.operator);
443
+ const isMulti = !!cur?.multi;
444
+ const options = row?.options || [];
445
+ const rowKey = `${p.name}-${i}`;
446
+ // D-69: the focused input shows what was TYPED; every other one shows the stored value.
447
+ const shown = draft && draft.key === rowKey ? draft.text : valueText(p.value);
448
+ /*
449
+ * ⭐ ITEM 16 / D-71 β€” WHICH FIELDS GET THE OBSERVED-VALUES PICKER, DERIVED OFF THE WIRE.
450
+ *
451
+ * β›” NOT A CLIENT-SIDE LIST OF FIELD NAMES. Naming the vendor's two category columns here
452
+ * would be the D-55 class verbatim β€” the wave-9 silent-drop shape, a client copy of a server
453
+ * vocabulary that is free to drift the day the engine adds a third one. (Their literal keys
454
+ * are deliberately not written anywhere in this file: the gate asserts the tokens are ABSENT,
455
+ * and an absence check cannot tell a hard-coded list from the comment forbidding one.)
456
+ * The server already publishes the answer twice over: `kind: "choice"` is its own declaration
457
+ * (`BD_FIELD_KINDS`), and `filter_meta` deliberately ships `options: []` for those fields
458
+ * because their vocabulary is OBSERVED rather than declared and arrives on its own route.
459
+ * So the rule is exactly that: a choice-kind field with no declared options is one whose
460
+ * values we can only have learned by seeing them. A new choice field inherits this for free.
461
+ */
462
+ const wantsObserved = row?.kind === "choice" && !options.length;
463
+ /** D-71 β€” APPEND, never replace: the picker has to compose with the comma list. */
464
+ const appendValue = (v: string) => {
465
+ const has = shown
466
+ .split(",")
467
+ .map((s) => s.trim().toLowerCase())
468
+ .filter(Boolean);
469
+ // Picking the same value twice is a no-op rather than a duplicate: the server expands a
470
+ // multi-value condition into an OR, and `beauty OR beauty` costs a slot to say nothing.
471
+ if (has.includes(v.trim().toLowerCase())) return;
472
+ const next = shown.trim() ? `${shown.replace(/[\s,]+$/, "")}, ${v}` : v;
473
+ setDraft(null);
474
+ setAt(i, { value: parseValue(next, isMulti) });
475
+ };
476
+ return (
477
+ <div className="autob-cond" key={rowKey}>
478
+ <select
479
+ className="auto-input is-small"
480
+ aria-label={`Comparison for ${label}`}
481
+ value={p.operator}
482
+ onChange={(e) => setAt(i, { operator: e.target.value })}
483
+ >
484
+ {/* The stored value is ALWAYS an option. A select whose value matches no
485
+ option renders the FIRST one, and the next Save writes a comparison
486
+ nobody chose β€” this codebase has paid for that twice. */}
487
+ {p.operator && !ops.some((o) => o.value === p.operator) ? (
488
+ <option value={p.operator}>{p.operator}</option>
489
+ ) : null}
490
+ {ops.map((o) => (
491
+ <option key={o.value} value={o.value}>
492
+ {o.label}
493
+ </option>
494
+ ))}
495
+ </select>
496
+ {isNullary ? null : options.length ? (
497
+ // A fixed vocabulary gets a dropdown. Owner item 2: a yes/no column was a box you
498
+ // typed `true` into, beside a comparison list that offered "at least".
499
+ <select
500
+ className="auto-input is-small"
501
+ aria-label={`Value for ${label}`}
502
+ value={valueText(p.value)}
503
+ onChange={(e) => setAt(i, { value: e.target.value })}
504
+ >
505
+ <option value="">Choose…</option>
506
+ {options.map((o) => (
507
+ <option key={o.value} value={o.value}>
508
+ {o.label}
509
+ </option>
510
+ ))}
511
+ </select>
512
+ ) : (
513
+ <input
514
+ className="auto-input is-small"
515
+ type={row?.kind === "number" ? "number" : "text"}
516
+ aria-label={`Value for ${label}`}
517
+ // ⭐ OWNER ITEM 3. Several comma-separated values become an "any of" condition, which
518
+ // the server sends as its own OR group β€” so it does NOT drag Followers into a union
519
+ // the way the Match dropdown would.
520
+ placeholder={isMulti ? "floral, flower, beauty" : ""}
521
+ // D-69: `shown` is the RAW text while this input has focus, so a trailing comma
522
+ // survives long enough to type the next value after it.
523
+ value={shown}
524
+ onFocus={() => setDraft({ key: rowKey, text: valueText(p.value) })}
525
+ onChange={(e) => {
526
+ setDraft({ key: rowKey, text: e.target.value });
527
+ // The STORE still updates on every keystroke. Parsing only on blur would mean a
528
+ // Save pressed straight from the field wrote the previous value β€” trading a typing
529
+ // bug for a data-loss one.
530
+ setAt(i, { value: parseValue(e.target.value, isMulti) });
531
+ }}
532
+ onBlur={(e) => {
533
+ setDraft(null);
534
+ setAt(i, { value: parseValue(e.target.value, isMulti) });
535
+ }}
536
+ />
537
+ )}
538
+ {/* ⭐ WAVE 27 Β· OWNER ITEM 29 β€” A WIDE EDITOR FOR THE VALUES THAT DO NOT FIT.
539
+ β›” THE COMPLAINT IS GEOMETRY, and the geometry is a CHAIN nothing here can widen:
540
+ `.auto-panel` is 380px, `.autob-cond .auto-input` divides what is left across three
541
+ controls, and `.is-small` trims it again β€” so a bio phrase list ("floral, flower,
542
+ wedding florist, event styling") is typed six characters at a time through a box
543
+ that scrolls sideways. The panel cannot grow; the EDITOR can leave it, and an
544
+ overlay is drawn in a body portal, so it is not bound by that chain at all.
545
+ ⚠ ALWAYS OFFERED, never "appears once the text is long": a control that materialises
546
+ at some threshold is one people do not know exists at the moment they need it.
547
+ ⚠ NOT on a `<select>` value (a fixed vocabulary has nothing to expand) and not on a
548
+ nullary comparison (which has no value at all). */}
549
+ {!isNullary && !options.length ? (
550
+ <button
551
+ type="button"
552
+ className="auto-input is-small autoc-expand"
553
+ aria-label={`Open a bigger editor for ${label}`}
554
+ title="Edit in a bigger box"
555
+ onClick={(e) => {
556
+ // ⚠ READ SYNCHRONOUSLY from the event. `currentTarget` is null by the time React
557
+ // re-invokes a state updater, and a null rect here paints the overlay at 0,0 β€”
558
+ // measured, in this repo, on a different control ([[react-event-currenttarget-updater]]).
559
+ const r = e.currentTarget.getBoundingClientRect();
560
+ setBig({
561
+ key: rowKey,
562
+ index: i,
563
+ label,
564
+ multi: isMulti,
565
+ text: valueText(p.value),
566
+ anchor: { left: r.left, top: r.top, right: r.right, bottom: r.bottom,
567
+ width: r.width, height: r.height },
568
+ });
569
+ }}
570
+ >
571
+ {/* Drawn, never a glyph: the design constitution's "no emojis in the UI" covers
572
+ the arrow characters too, and every other mark in this product is a path in the
573
+ same 16x16 stroke vocabulary. Two corners pulling apart = "make this bigger". */}
574
+ <svg viewBox="0 0 16 16" aria-hidden className="autoc-expand-icon">
575
+ <path d="M9.5 2.5h4v4M13.5 2.5 9.6 6.4" />
576
+ <path d="M6.5 13.5h-4v-4M2.5 13.5l3.9-3.9" />
577
+ </svg>
578
+ </button>
579
+ ) : null}
580
+ {/* ⭐ ITEM 16 / D-71 β€” THE APPEND-PICKER, BESIDE the input and never instead of it.
581
+ Free text stays the primary control: these are the values this deployment has SEEN,
582
+ not the values that exist, so the picker is a shortcut over a superset it cannot
583
+ enumerate. Appending in code also sidesteps D-69 entirely β€” a picked value never has
584
+ to survive a round trip through the text box. */}
585
+ {wantsObserved && !isNullary ? (
586
+ <select
587
+ className="auto-input is-small autoc-catpick"
588
+ aria-label={`Add a value seen before, to ${label}`}
589
+ title={
590
+ cats.length
591
+ ? "Values this workspace has actually seen, most-seen first. Adds to the list."
592
+ : "No category values have been seen in your data yet. Type one."
593
+ }
594
+ value=""
595
+ disabled={!cats.length}
596
+ onChange={(e) => {
597
+ if (e.target.value) appendValue(e.target.value);
598
+ }}
599
+ >
600
+ <option value="">{cats.length ? "Seen before…" : "None seen yet"}</option>
601
+ {cats.map((c) => (
602
+ // The COUNT is the honest half (D-59): a value seen once and one seen forty times
603
+ // are different bets, and an alphabetical list of bare strings hides that.
604
+ <option key={c.value} value={c.value}>
605
+ {c.value} ({c.count.toLocaleString()})
606
+ </option>
607
+ ))}
608
+ </select>
609
+ ) : null}
610
+ {isMulti && Array.isArray(p.value) && p.value.length > 1 ? (
611
+ /*
612
+ * ⭐ ITEM 16 / D-71 β€” HOW MANY VALUES THIS CONDITION CARRIES, and against what ceiling.
613
+ *
614
+ * The COUNT is ours and is always shown. The CEILING is the server's and is shown only
615
+ * when the server sends one (`guard.maxValues` β€” an open `ASK ->A:`; `guard` ships
616
+ * `{minNarrowing, maxRecords}` today).
617
+ * β›” NO CLIENT-SIDE `4`. D-71's exit says "how many of D-68's 4 value slots" β€” but A
618
+ * shipped `depth_refusal()`, which computes the depth of the shape actually emitted
619
+ * rather than budgeting fixed slots, so the number 4 describes a model that no longer
620
+ * exists. Printing it would be a client copy of a server rule that has already changed
621
+ * once, which is the specific failure this file's header refuses to commit
622
+ * ([[measure-the-real-call]]: a correct-looking answer about the wrong subject).
623
+ */
624
+ <span className="autob-cond-any" title="Any one of these is a match">
625
+ any of {p.value.length}
626
+ {discover?.guard?.maxValues ? ` of ${discover.guard.maxValues}` : ""}
627
+ </span>
628
+ ) : null}
629
+ <button
630
+ type="button"
631
+ className="autob-cond-x"
632
+ aria-label={`Remove this condition on ${label}`}
633
+ title="Remove this condition"
634
+ onClick={() => removeAt(i)}
635
+ >
636
+ <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
637
+ <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
638
+ </svg>
639
+ </button>
640
+ </div>
641
+ );
642
+ };
643
+
644
+ const fieldRow = (row: FieldRow) => {
645
+ const on = row.at.length > 0;
646
+ return (
647
+ <div className={"autob-tgl" + (on ? " is-on" : "")} key={row.name}>
648
+ <div className="autob-tgl-head">
649
+ <button
650
+ type="button"
651
+ className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
652
+ aria-pressed={on}
653
+ aria-label={`${on ? "Stop searching" : "Search"} on ${row.label}`}
654
+ title={`${on ? "Stop searching" : "Search"} on ${row.label}`}
655
+ onClick={() => toggleField(row)}
656
+ >
657
+ <span className="auto-step-switch-knob" />
658
+ </button>
659
+ <span className="autob-tgl-mark">
660
+ <FilterMark name={row.name} />
661
+ </span>
662
+ {/* ⭐ THE HUMAN LABEL (owner item 1: "wtf is id/fbid").
663
+ This used to render the vendor's own column name verbatim, and the comment
664
+ defending it was RIGHT about the reason β€” a refusal names the field, and a label
665
+ that reads differently makes the error unmatchable. So the label did not move
666
+ alone: `field_label()` is what the SERVER's refusals use too, which is the only
667
+ version of this change that does not trade one confusion for another. */}
668
+ <span className="autob-tgl-name" title={row.hint || undefined}>
669
+ {row.label}
670
+ </span>
671
+ {/*
672
+ ⚠ ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
673
+ non-narrowing field "broad" AND every unpopulated one "no values seen" β€”
674
+ which put two chips on 18 of the 21 rows, and one of them repeated the group
675
+ heading the row was already sitting under. A mark that is on almost every row
676
+ stops being a mark. Read off the screenshot; no assertion could have said it.
677
+
678
+ So: the group label carries POPULATED (it is what the groups ARE), and the
679
+ chip carries NARROWING, inverted to mark the five that DO narrow. That is the
680
+ actionable half β€” the server refuses a filter with no narrowing condition, so
681
+ "these are the ones that satisfy it" is the sentence a user needs, and
682
+ "this one does not" is not.
683
+ */}
684
+ {row.narrowing === true ? (
685
+ <span
686
+ className="autob-tgl-flag is-narrow"
687
+ title="A search needs at least one condition like this."
688
+ >
689
+ narrows
690
+ </span>
691
+ ) : null}
692
+ </div>
693
+ {on ? (
694
+ <div className="autob-tgl-body">
695
+ {row.at.map((i) => condition(i, row.label, row))}
696
+ {row.hint ? <p className="autob-tgl-hint">{row.hint}</p> : null}
697
+ <button
698
+ type="button"
699
+ className="autob-cond-add"
700
+ onClick={() =>
701
+ onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
702
+ }
703
+ >
704
+ Another condition on {row.label}
705
+ </button>
706
+ </div>
707
+ ) : null}
708
+ </div>
709
+ );
710
+ };
711
+
712
+ return (
713
+ <>
714
+ <div className="auto-field">
715
+ <label htmlFor="auto-records">How many profiles to fetch</label>
716
+ <input
717
+ id="auto-records"
718
+ className="auto-input"
719
+ type="number"
720
+ min={1}
721
+ max={maxRecords}
722
+ value={recordsLimit}
723
+ onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
724
+ />
725
+ </div>
726
+ {/* Owner item 5: "Stop at the 'A search must be at most 500 profiles a run'". The two
727
+ sentences that followed explained the vendor's billing model to somebody who wants a
728
+ list of florists. */}
729
+ <p className="auto-hint">At most {maxRecords.toLocaleString()} profiles a run.</p>
730
+
731
+ <h3>Conditions</h3>
732
+ <div className="auto-field autob-match">
733
+ <label htmlFor="auto-joinop">Match</label>
734
+ <select
735
+ id="auto-joinop"
736
+ className="auto-input"
737
+ value={joinOp}
738
+ onChange={(e) => onJoinOp(e.target.value)}
739
+ >
740
+ <option value="and">All of them</option>
741
+ <option value="or">Any of them</option>
742
+ </select>
743
+ </div>
744
+
745
+ {!rows.length ? (
746
+ <p className="auto-note">
747
+ The searchable fields have not loaded yet.
748
+ </p>
749
+ ) : null}
750
+
751
+ {withValues.length ? (
752
+ <div className="autob-tglgroup">
753
+ <p
754
+ className="autob-tglgroup-label"
755
+ title="Most accounts have this filled in."
756
+ >
757
+ Usually filled in
758
+ </p>
759
+ {withValues.map(fieldRow)}
760
+ </div>
761
+ ) : null}
762
+
763
+ {rest.length ? (
764
+ <div className="autob-tglgroup">
765
+ <p
766
+ className="autob-tglgroup-label"
767
+ title={
768
+ knownMeta
769
+ ? "Most accounts leave these blank, so a condition here can return nothing."
770
+ : "We have not measured how often these are filled in."
771
+ }
772
+ >
773
+ {knownMeta ? "Often blank" : "Not measured"}
774
+ </p>
775
+ {rest.map(fieldRow)}
776
+ </div>
777
+ ) : null}
778
+
779
+ {strays.length ? (
780
+ <div className="autob-tglgroup">
781
+ <p className="autob-tglgroup-label">Not in the searchable list</p>
782
+ {strays.map(({ p, i }) => (
783
+ <div className="autob-tgl is-on is-stray" key={`stray-${i}`}>
784
+ <div className="autob-tgl-head">
785
+ {/* A stray gets a mark too β€” "every filter row" includes the ones the vendor no
786
+ longer offers, and a row missing the icon its neighbours have would read as a
787
+ different KIND of thing rather than as a field that fell out of the list. It
788
+ draws the neutral fallback by construction: a stray is, by definition, not in
789
+ the vocabulary this component has arms for. */}
790
+ <span className="autob-tgl-mark">
791
+ <FilterMark name={p.name} />
792
+ </span>
793
+ <span className="autob-tgl-name">{p.name}</span>
794
+ <span className="autob-tgl-flag is-stray" title="The server will refuse this condition by name.">
795
+ not searchable
796
+ </span>
797
+ </div>
798
+ <div className="autob-tgl-body">{condition(i, p.name)}</div>
799
+ </div>
800
+ ))}
801
+ </div>
802
+ ) : null}
803
+
804
+ {/* The consequence kept, the mechanism dropped: a condition on an often-blank field
805
+ returning nothing is a thing that will happen to somebody and confuse them. Why the
806
+ search is slow when broad is our problem, not theirs. */}
807
+ <p className="auto-hint">
808
+ Conditions on often-blank fields can come back with nothing.
809
+ </p>
810
+
811
+ <h3>What it costs</h3>
812
+ <div className="auto-head-actions">
813
+ <button type="button" className="auto-btn" onClick={onEstimate}>
814
+ Estimate this search
815
+ </button>
816
+ </div>
817
+ {estimate ? (
818
+ <p className="auto-hint">
819
+ About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
820
+ {estimate.unitUsd} each.{" "}
821
+ {/*
822
+ THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run and this
823
+ deployment cannot read its own balance, so presenting this as a billed figure
824
+ would be inventing a measurement.
825
+ */}
826
+ <strong>This is an estimate</strong> β€” {estimate.note}.
827
+ </p>
828
+ ) : null}
829
+
830
+ {/* ⭐ WAVE 27 Β· OWNER ITEM 29 β€” THE BIG EDITOR, rendered ONCE for the whole panel.
831
+ β›” Not one overlay per condition row: `AnchoredOverlay` mounts a body portal and
832
+ installs document-level dismiss/focus handlers, so N of them would be N listener
833
+ stacks fighting over one Escape key. One overlay, told which row it is editing.
834
+ ⚠ `role="dialog"`, not "menu": it holds a text field, and the menu layer's arrow-key
835
+ handling would take the cursor keys away from the text being typed. */}
836
+ {big ? (
837
+ <AnchoredOverlay
838
+ anchor={big.anchor}
839
+ className="autoc-bigedit"
840
+ placement="right-start"
841
+ role="dialog"
842
+ ariaLabel={`Value for ${big.label}`}
843
+ onDismiss={() => setBig(null)}
844
+ dataKind="find-value-editor"
845
+ >
846
+ <label htmlFor="autoc-bigedit-text">{big.label}</label>
847
+ <textarea
848
+ id="autoc-bigedit-text"
849
+ className="autoc-bigedit-text"
850
+ data-overlay-autofocus
851
+ autoFocus
852
+ rows={7}
853
+ spellCheck={false}
854
+ value={big.text}
855
+ placeholder={big.multi ? "floral, flower, wedding florist, event styling" : ""}
856
+ onChange={(e) => setBig((cur) => (cur ? { ...cur, text: e.target.value } : cur))}
857
+ onKeyDown={(e) => {
858
+ // Escape abandons; Ctrl/Cmd+Enter commits. A bare Enter types a NEWLINE, because
859
+ // this is a textarea and the whole reason it exists is that the value is long.
860
+ if (e.key === "Escape") setBig(null);
861
+ if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
862
+ setAt(big.index, { value: parseValue(big.text, big.multi) });
863
+ setBig(null);
864
+ }
865
+ }}
866
+ />
867
+ {/* The same sentence the rail input's placeholder makes, said where there is room
868
+ for it: a comma list is several values, and the server turns them into an OR. */}
869
+ {big.multi ? (
870
+ <p className="auto-hint">
871
+ Separate values with commas. The search matches any of them.
872
+ </p>
873
+ ) : null}
874
+ <div className="auto-head-actions">
875
+ <button
876
+ type="button"
877
+ className="auto-btn auto-btn--primary"
878
+ onClick={() => {
879
+ setAt(big.index, { value: parseValue(big.text, big.multi) });
880
+ setBig(null);
881
+ }}
882
+ >
883
+ Done
884
+ </button>
885
+ <button type="button" className="auto-btn" onClick={() => setBig(null)}>
886
+ Cancel
887
+ </button>
888
+ </div>
889
+ </AnchoredOverlay>
890
+ ) : null}
891
+ </>
892
+ );
893
+ }
web/src/automation/HarnessPanel.tsx CHANGED
@@ -1,413 +1,413 @@
1
- // ---------------------------------------------------------------------------
2
- // automation/HarnessPanel.tsx β€” the HARNESS tab (owner item 3, rulings R7/R8,
3
- // contract C4 Β· W36-T31).
4
- //
5
- // Owner, verbatim (2026-08-18): *"For each of the tenant's Agent, I think we need
6
- // another tab beside Properties/Run history. This new module under agent is
7
- // supposed to host any file pertaining to the agent skills, router etc. So we
8
- // build a user can build a custom harness for each agent through the chat
9
- // interface."*
10
- //
11
- // β›”β›” R8 IS THE WHOLE SHAPE AND IT IS ENFORCED ON THE SERVER, NOT HERE. Every save
12
- // APPENDS a version; there is no overwrite door and no edit-in-place. A ROLL-BACK
13
- // IS A WRITE OF AN OLDER BODY, never a delete β€” so "restore v1" produces v4 whose
14
- // `restoredFrom` is 1, and the history keeps v2 and v3 saying what actually
15
- // happened rather than what somebody last wanted it to look like. This panel
16
- // paints that model; it does not implement it, and it must never offer a control
17
- // whose name implies otherwise ("Replace", "Overwrite", "Discard v2").
18
- //
19
- // β›” R8 IS DELIBERATELY NOT R9, and the two sit one screen apart. An agent-authored
20
- // ACTION's config is agent-only (item 8); a harness file is editable by BOTH the
21
- // user and the agent. Do not copy either posture onto the other.
22
- //
23
- // ⚠ THIS PANEL IS THE ONE PLACE THE CAPS ARE VISIBLE. `limits` rides every C4
24
- // payload precisely so a control can say "this file is full" BEFORE a write fails,
25
- // and `trimmed` reports the one cap that acts WITHOUT refusing β€” history older than
26
- // `maxVersions` is gone, and a reader who cannot see that would infer the file was
27
- // only ever saved twice. Both are rendered, never inferred.
28
- // ---------------------------------------------------------------------------
29
- import { useCallback, useEffect, useRef, useState } from "react";
30
-
31
- import type { HarnessDoc, HarnessFile, HarnessLimits } from "./automationApi";
32
- import {
33
- AutomationError, deleteHarness, listHarness, readHarness, writeHarness,
34
- } from "./automationApi";
35
- import "./automation.css";
36
-
37
- /** The files a fresh agent is offered, as NAMES only. Nothing is created until somebody saves. */
38
- const SUGGESTED_PATHS = ["skills/router.md", "skills/agent.md"];
39
-
40
- function kb(bytes: number): string {
41
- if (bytes < 1024) return `${bytes} bytes`;
42
- return `${(bytes / 1024).toFixed(bytes < 10240 ? 1 : 0)} KB`;
43
- }
44
-
45
- /**
46
- * `2026-08-18T14:50:09Z` as something a person reads. ⚠ Falls back to the raw string rather than
47
- * to an empty cell: an unparseable stamp is still evidence of WHEN, and a blank reads as "never".
48
- */
49
- function when(iso: string): string {
50
- if (!iso) return "";
51
- const d = new Date(iso);
52
- if (Number.isNaN(d.getTime())) return iso;
53
- return d.toLocaleString(undefined, {
54
- year: "numeric", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit",
55
- });
56
- }
57
-
58
- /** Who wrote it, in words. R8's point is that BOTH may, so the answer is always stated. */
59
- const byline = (author: string, kind: string) =>
60
- `${kind === "agent" ? "the agent" : author || "a person"}`;
61
-
62
- export default function HarnessPanel({ agentId }: { agentId: string }) {
63
- const [files, setFiles] = useState<HarnessFile[] | null>(null);
64
- const [limits, setLimits] = useState<HarnessLimits | null>(null);
65
- const [listErr, setListErr] = useState("");
66
- const [open, setOpen] = useState<HarnessDoc | null>(null);
67
- const [openErr, setOpenErr] = useState("");
68
- const [draft, setDraft] = useState("");
69
- const [busy, setBusy] = useState<"" | "open" | "save" | "delete">("");
70
- const [newPath, setNewPath] = useState("");
71
- const [note, setNote] = useState("");
72
- /** Which older version is being previewed, or 0 for the current one. */
73
- const [at, setAt] = useState(0);
74
- const dirty = useRef(false);
75
- /**
76
- * β›” THE OPEN THAT WOULD THROW AWAY TYPING, HELD UNTIL IT IS CONFIRMED.
77
- *
78
- * Every other control here is safe to misclick: R8 means nothing is ever destroyed on the
79
- * server. The ONE thing that can be lost is a body somebody has typed and not saved, and it is
80
- * lost by the most inviting click on the panel (a version in the history, one row from Save).
81
- * ⚠ Deliberately NOT `window.confirm`. A native dialog blocks the whole tab, cannot be styled,
82
- * and reads as a browser error rather than as this panel asking a question.
83
- */
84
- const [holdOpen, setHoldOpen] = useState<{ path: string; version: number } | null>(null);
85
-
86
- const refresh = useCallback(async (signal?: AbortSignal) => {
87
- try {
88
- const r = await listHarness(agentId, signal);
89
- if (signal?.aborted) return;
90
- setFiles(r.files || []);
91
- setLimits(r.limits || null);
92
- setListErr("");
93
- } catch (e: unknown) {
94
- if (signal?.aborted) return;
95
- setFiles([]);
96
- setListErr(e instanceof AutomationError ? e.message : "the harness could not be read");
97
- }
98
- }, [agentId]);
99
-
100
- useEffect(() => {
101
- const ac = new AbortController();
102
- void refresh(ac.signal);
103
- return () => ac.abort();
104
- }, [refresh]);
105
-
106
- /**
107
- * Open one file at one version.
108
- * ⚠ THE DRAFT IS ONLY ADOPTED WHEN IT IS SAFE TO. Reading an OLDER version fills the editor with
109
- * that body on purpose β€” that is how a roll-back is composed, and the save button says so β€” but
110
- * it must not silently throw away something half-typed, so an unsaved edit is confirmed in words
111
- * by the caller rather than by a browser dialog this panel cannot style.
112
- */
113
- const openFile = useCallback(async (path: string, version = 0, force = false) => {
114
- // The guard fires only when something WOULD be lost: a typed body, going somewhere else.
115
- if (!force && dirty.current && !(open?.path === path && (at || 0) === version)) {
116
- setHoldOpen({ path, version });
117
- return;
118
- }
119
- setHoldOpen(null);
120
- setBusy("open");
121
- setOpenErr("");
122
- setNote("");
123
- try {
124
- const doc = await readHarness(agentId, path, version || undefined);
125
- setOpen(doc);
126
- setDraft(doc.body);
127
- setAt(version || 0);
128
- dirty.current = false;
129
- } catch (e: unknown) {
130
- // β›” THE SERVER'S OWN SENTENCE. A trimmed version answers 410 with a sentence naming the cap;
131
- // replacing it with "could not open" throws away the only part a person can act on.
132
- setOpenErr(e instanceof AutomationError ? e.message : "that file could not be opened");
133
- } finally {
134
- setBusy("");
135
- }
136
- }, [agentId, open, at]);
137
-
138
- const save = useCallback(async (restoredFrom?: number) => {
139
- if (!open) return;
140
- setBusy("save");
141
- setNote("");
142
- try {
143
- const doc = await writeHarness(agentId, {
144
- path: open.path,
145
- body: draft,
146
- // β›” `user`, ALWAYS, from this panel. `authorKind` is a claim about who DRAFTED the body,
147
- // and everything typed here was typed by the person at the keyboard. The agent's own
148
- // writes go through `record_version()` on the server with no session at all; a client
149
- // that stamped "agent" on a hand-typed file would make the history a record of nothing.
150
- authorKind: "user",
151
- ...(restoredFrom ? { restoredFrom } : {}),
152
- });
153
- setOpen(doc);
154
- setDraft(doc.body);
155
- setAt(0);
156
- dirty.current = false;
157
- setNote(restoredFrom
158
- ? `Version ${restoredFrom} is back, saved as version ${doc.atVersion}. Nothing was deleted.`
159
- : `Saved as version ${doc.atVersion}.`);
160
- await refresh();
161
- } catch (e: unknown) {
162
- setNote(e instanceof AutomationError ? e.message : "that file could not be saved");
163
- } finally {
164
- setBusy("");
165
- }
166
- }, [agentId, open, draft, refresh]);
167
-
168
- const create = useCallback(async () => {
169
- const path = newPath.trim();
170
- if (!path) return;
171
- setBusy("save");
172
- setNote("");
173
- try {
174
- const doc = await writeHarness(agentId, { path, body: "", authorKind: "user" });
175
- setNewPath("");
176
- setOpen(doc);
177
- setDraft(doc.body);
178
- setAt(0);
179
- dirty.current = false;
180
- await refresh();
181
- } catch (e: unknown) {
182
- setNote(e instanceof AutomationError ? e.message : "that file could not be created");
183
- } finally {
184
- setBusy("");
185
- }
186
- }, [agentId, newPath, refresh]);
187
-
188
- const drop = useCallback(async (path: string) => {
189
- setBusy("delete");
190
- setNote("");
191
- try {
192
- await deleteHarness(agentId, path);
193
- if (open?.path === path) {
194
- setOpen(null);
195
- setDraft("");
196
- }
197
- await refresh();
198
- } catch (e: unknown) {
199
- setNote(e instanceof AutomationError ? e.message : "that file could not be deleted");
200
- } finally {
201
- setBusy("");
202
- }
203
- }, [agentId, open, refresh]);
204
-
205
- const full = !!(limits && files && files.length >= limits.maxFiles);
206
- const tooBig = !!(limits && new TextEncoder().encode(draft).length > limits.maxBodyBytes);
207
-
208
- if (files === null) {
209
- return <p className="auto-note">Reading this agent&apos;s harness files.</p>;
210
- }
211
-
212
- return (
213
- <div className="autoh-wrap">
214
- {listErr ? <p className="auto-note">{listErr}</p> : null}
215
-
216
- {/* ── the file list ─────────────────────────────────────────────────────────────────── */}
217
- {!files.length && !listErr ? (
218
- <p className="auto-hint">
219
- This agent has no harness files yet. A harness file is what the agent is instructed to
220
- do: its router, its skills, anything it should read before it acts. Both you and the
221
- agent can write them, and every save keeps the version before it.
222
- </p>
223
- ) : null}
224
-
225
- <ul className="autoh-files">
226
- {files.map((f) => (
227
- <li key={f.path} className={"autoh-file" + (open?.path === f.path ? " is-on" : "")}>
228
- <button
229
- type="button"
230
- className="autoh-open"
231
- disabled={busy !== ""}
232
- onClick={() => void openFile(f.path)}
233
- >
234
- <span className="autoh-path">{f.path}</span>
235
- <span className="autoh-meta">
236
- v{f.version}, {kb(f.bytes)}, {when(f.updated)} by {byline(f.author, f.authorKind)}
237
- </span>
238
- </button>
239
- {/* ⚠ DELETING A FILE IS NOT THE THING R8 FORBIDS. R8 forbids a roll-back implemented as
240
- a delete. Removing a file is a person deciding it should not exist, which is a
241
- different act and gets a different, quieter control. */}
242
- <button
243
- type="button"
244
- className="auto-btn is-danger autoh-drop"
245
- disabled={busy !== ""}
246
- aria-label={`Delete ${f.path}`}
247
- onClick={() => void drop(f.path)}
248
- >
249
- Delete
250
- </button>
251
- </li>
252
- ))}
253
- </ul>
254
-
255
- {/* ── add a file ────────────────────────────────────────────────────────────────────── */}
256
- <div className="auto-field">
257
- <label htmlFor="autoh-new">Add a file</label>
258
- <div className="autoh-newrow">
259
- <input
260
- id="autoh-new"
261
- className="auto-input"
262
- value={newPath}
263
- placeholder={SUGGESTED_PATHS[0]}
264
- maxLength={limits?.maxPath || 200}
265
- disabled={busy !== "" || full}
266
- onChange={(e) => setNewPath(e.target.value)}
267
- onKeyDown={(e) => {
268
- if (e.key === "Enter") {
269
- e.preventDefault();
270
- void create();
271
- }
272
- }}
273
- />
274
- <button
275
- type="button"
276
- className="auto-btn"
277
- disabled={busy !== "" || full || !newPath.trim()}
278
- onClick={() => void create()}
279
- >
280
- Add
281
- </button>
282
- </div>
283
- {/* β›” THE CAP IS SAID BEFORE IT BITES, not after. `limits` rides the payload for exactly
284
- this; a ceiling a person meets as a refusal is a ceiling nobody could plan around. */}
285
- <p className="auto-hint">
286
- {full
287
- ? `This agent already has the maximum of ${limits?.maxFiles} harness files. `
288
- + "Delete one to add another."
289
- : `A path like ${SUGGESTED_PATHS.join(" or ")}. `
290
- + (limits ? `Up to ${limits.maxFiles} files, ${kb(limits.maxBodyBytes)} each.` : "")}
291
- </p>
292
- </div>
293
-
294
- {openErr ? <p className="auto-note">{openErr}</p> : null}
295
-
296
- {holdOpen ? (
297
- <div className="autoh-hold">
298
- <p className="auto-note">
299
- The changes you typed into {open?.path} have not been saved, and opening{" "}
300
- {holdOpen.version ? `version ${holdOpen.version}` : holdOpen.path} would replace them.
301
- </p>
302
- <div className="autoh-actions">
303
- <button
304
- type="button"
305
- className="auto-btn"
306
- onClick={() => void openFile(holdOpen.path, holdOpen.version, true)}
307
- >
308
- Discard them and open
309
- </button>
310
- <button type="button" className="auto-btn" onClick={() => setHoldOpen(null)}>
311
- Keep editing
312
- </button>
313
- </div>
314
- </div>
315
- ) : null}
316
-
317
- {/* ── the editor ────────────────────────────────────────────────────────────────────── */}
318
- {open ? (
319
- <>
320
- <h3>{open.path}</h3>
321
- {at ? (
322
- /* β›” AN OLDER BODY IS LABELLED AS ONE, LOUDLY. Without this the editor shows an old
323
- body in the same frame as the current one, and Save then looks like an ordinary
324
- save rather than a roll-back. Naming it is what makes the next click honest. */
325
- <p className="auto-note">
326
- You are reading version {at} of {open.versions + open.trimmed}. Saving it writes a
327
- NEW version that restores this one. Nothing in between is deleted.
328
- </p>
329
- ) : null}
330
- <div className="auto-field">
331
- <label htmlFor="autoh-body">
332
- {at ? `Version ${at}` : `Current body, version ${open.atVersion}`}
333
- </label>
334
- <textarea
335
- id="autoh-body"
336
- className="auto-input is-mono autoh-body"
337
- rows={14}
338
- value={draft}
339
- disabled={busy === "save"}
340
- onChange={(e) => {
341
- setDraft(e.target.value);
342
- dirty.current = true;
343
- }}
344
- />
345
- <p className="auto-hint">
346
- {tooBig
347
- ? `This is larger than the ${kb(limits?.maxBodyBytes || 0)} a harness file may be, `
348
- + "so it will be refused. Shorten it."
349
- : `${kb(new TextEncoder().encode(draft).length)} of `
350
- + `${kb(limits?.maxBodyBytes || 0)}.`}
351
- </p>
352
- </div>
353
- <div className="autoh-actions">
354
- <button
355
- type="button"
356
- className="auto-btn is-primary"
357
- disabled={busy !== "" || tooBig}
358
- onClick={() => void save(at || undefined)}
359
- >
360
- {busy === "save"
361
- ? "Saving"
362
- : at
363
- ? `Restore version ${at}`
364
- : "Save a new version"}
365
- </button>
366
- {at ? (
367
- <button
368
- type="button"
369
- className="auto-btn"
370
- disabled={busy !== ""}
371
- onClick={() => void openFile(open.path)}
372
- >
373
- Back to current
374
- </button>
375
- ) : null}
376
- </div>
377
- {note ? <p className="auto-note">{note}</p> : null}
378
-
379
- {/* ── the history ─────────────────────────────────────────────────────────────── */}
380
- <h3>Version history</h3>
381
- <ol className="autoh-history">
382
- {open.history.map((v) => (
383
- <li key={v.version} className={v.version === (at || open.atVersion) ? "is-on" : ""}>
384
- <button
385
- type="button"
386
- className="autoh-version"
387
- disabled={busy !== ""}
388
- onClick={() => void openFile(open.path, v.version)}
389
- >
390
- <span className="autoh-vnum">v{v.version}</span>
391
- <span className="autoh-meta">
392
- {when(v.created)} by {byline(v.author, v.authorKind)}, {kb(v.bytes)}
393
- {v.restoredFrom ? `, restored version ${v.restoredFrom}` : ""}
394
- </span>
395
- </button>
396
- </li>
397
- ))}
398
- </ol>
399
- {/* β›” THE CAP THAT ACTS WITHOUT REFUSING. Past `maxVersions` the OLDEST bodies are
400
- dropped, and a history that simply started at v14 would read as a file first saved
401
- at v14. R6's second sentence: a limit that bites is REPORTED. */}
402
- {open.trimmed ? (
403
- <p className="auto-hint">
404
- The {open.trimmed} oldest version{open.trimmed === 1 ? "" : "s"} of this file
405
- {open.trimmed === 1 ? " has" : " have"} been dropped, because only the newest{" "}
406
- {limits?.maxVersions} are kept. What they said is gone; that they existed is not.
407
- </p>
408
- ) : null}
409
- </>
410
- ) : null}
411
- </div>
412
- );
413
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/HarnessPanel.tsx β€” the HARNESS tab (owner item 3, rulings R7/R8,
3
+ // contract C4 Β· W36-T31).
4
+ //
5
+ // Owner, verbatim (2026-08-18): *"For each of the tenant's Agent, I think we need
6
+ // another tab beside Properties/Run history. This new module under agent is
7
+ // supposed to host any file pertaining to the agent skills, router etc. So we
8
+ // build a user can build a custom harness for each agent through the chat
9
+ // interface."*
10
+ //
11
+ // β›”β›” R8 IS THE WHOLE SHAPE AND IT IS ENFORCED ON THE SERVER, NOT HERE. Every save
12
+ // APPENDS a version; there is no overwrite door and no edit-in-place. A ROLL-BACK
13
+ // IS A WRITE OF AN OLDER BODY, never a delete β€” so "restore v1" produces v4 whose
14
+ // `restoredFrom` is 1, and the history keeps v2 and v3 saying what actually
15
+ // happened rather than what somebody last wanted it to look like. This panel
16
+ // paints that model; it does not implement it, and it must never offer a control
17
+ // whose name implies otherwise ("Replace", "Overwrite", "Discard v2").
18
+ //
19
+ // β›” R8 IS DELIBERATELY NOT R9, and the two sit one screen apart. An agent-authored
20
+ // ACTION's config is agent-only (item 8); a harness file is editable by BOTH the
21
+ // user and the agent. Do not copy either posture onto the other.
22
+ //
23
+ // ⚠ THIS PANEL IS THE ONE PLACE THE CAPS ARE VISIBLE. `limits` rides every C4
24
+ // payload precisely so a control can say "this file is full" BEFORE a write fails,
25
+ // and `trimmed` reports the one cap that acts WITHOUT refusing β€” history older than
26
+ // `maxVersions` is gone, and a reader who cannot see that would infer the file was
27
+ // only ever saved twice. Both are rendered, never inferred.
28
+ // ---------------------------------------------------------------------------
29
+ import { useCallback, useEffect, useRef, useState } from "react";
30
+
31
+ import type { HarnessDoc, HarnessFile, HarnessLimits } from "./automationApi";
32
+ import {
33
+ AutomationError, deleteHarness, listHarness, readHarness, writeHarness,
34
+ } from "./automationApi";
35
+ import "./automation.css";
36
+
37
+ /** The files a fresh agent is offered, as NAMES only. Nothing is created until somebody saves. */
38
+ const SUGGESTED_PATHS = ["skills/router.md", "skills/agent.md"];
39
+
40
+ function kb(bytes: number): string {
41
+ if (bytes < 1024) return `${bytes} bytes`;
42
+ return `${(bytes / 1024).toFixed(bytes < 10240 ? 1 : 0)} KB`;
43
+ }
44
+
45
+ /**
46
+ * `2026-08-18T14:50:09Z` as something a person reads. ⚠ Falls back to the raw string rather than
47
+ * to an empty cell: an unparseable stamp is still evidence of WHEN, and a blank reads as "never".
48
+ */
49
+ function when(iso: string): string {
50
+ if (!iso) return "";
51
+ const d = new Date(iso);
52
+ if (Number.isNaN(d.getTime())) return iso;
53
+ return d.toLocaleString(undefined, {
54
+ year: "numeric", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit",
55
+ });
56
+ }
57
+
58
+ /** Who wrote it, in words. R8's point is that BOTH may, so the answer is always stated. */
59
+ const byline = (author: string, kind: string) =>
60
+ `${kind === "agent" ? "the agent" : author || "a person"}`;
61
+
62
+ export default function HarnessPanel({ agentId }: { agentId: string }) {
63
+ const [files, setFiles] = useState<HarnessFile[] | null>(null);
64
+ const [limits, setLimits] = useState<HarnessLimits | null>(null);
65
+ const [listErr, setListErr] = useState("");
66
+ const [open, setOpen] = useState<HarnessDoc | null>(null);
67
+ const [openErr, setOpenErr] = useState("");
68
+ const [draft, setDraft] = useState("");
69
+ const [busy, setBusy] = useState<"" | "open" | "save" | "delete">("");
70
+ const [newPath, setNewPath] = useState("");
71
+ const [note, setNote] = useState("");
72
+ /** Which older version is being previewed, or 0 for the current one. */
73
+ const [at, setAt] = useState(0);
74
+ const dirty = useRef(false);
75
+ /**
76
+ * β›” THE OPEN THAT WOULD THROW AWAY TYPING, HELD UNTIL IT IS CONFIRMED.
77
+ *
78
+ * Every other control here is safe to misclick: R8 means nothing is ever destroyed on the
79
+ * server. The ONE thing that can be lost is a body somebody has typed and not saved, and it is
80
+ * lost by the most inviting click on the panel (a version in the history, one row from Save).
81
+ * ⚠ Deliberately NOT `window.confirm`. A native dialog blocks the whole tab, cannot be styled,
82
+ * and reads as a browser error rather than as this panel asking a question.
83
+ */
84
+ const [holdOpen, setHoldOpen] = useState<{ path: string; version: number } | null>(null);
85
+
86
+ const refresh = useCallback(async (signal?: AbortSignal) => {
87
+ try {
88
+ const r = await listHarness(agentId, signal);
89
+ if (signal?.aborted) return;
90
+ setFiles(r.files || []);
91
+ setLimits(r.limits || null);
92
+ setListErr("");
93
+ } catch (e: unknown) {
94
+ if (signal?.aborted) return;
95
+ setFiles([]);
96
+ setListErr(e instanceof AutomationError ? e.message : "the harness could not be read");
97
+ }
98
+ }, [agentId]);
99
+
100
+ useEffect(() => {
101
+ const ac = new AbortController();
102
+ void refresh(ac.signal);
103
+ return () => ac.abort();
104
+ }, [refresh]);
105
+
106
+ /**
107
+ * Open one file at one version.
108
+ * ⚠ THE DRAFT IS ONLY ADOPTED WHEN IT IS SAFE TO. Reading an OLDER version fills the editor with
109
+ * that body on purpose β€” that is how a roll-back is composed, and the save button says so β€” but
110
+ * it must not silently throw away something half-typed, so an unsaved edit is confirmed in words
111
+ * by the caller rather than by a browser dialog this panel cannot style.
112
+ */
113
+ const openFile = useCallback(async (path: string, version = 0, force = false) => {
114
+ // The guard fires only when something WOULD be lost: a typed body, going somewhere else.
115
+ if (!force && dirty.current && !(open?.path === path && (at || 0) === version)) {
116
+ setHoldOpen({ path, version });
117
+ return;
118
+ }
119
+ setHoldOpen(null);
120
+ setBusy("open");
121
+ setOpenErr("");
122
+ setNote("");
123
+ try {
124
+ const doc = await readHarness(agentId, path, version || undefined);
125
+ setOpen(doc);
126
+ setDraft(doc.body);
127
+ setAt(version || 0);
128
+ dirty.current = false;
129
+ } catch (e: unknown) {
130
+ // β›” THE SERVER'S OWN SENTENCE. A trimmed version answers 410 with a sentence naming the cap;
131
+ // replacing it with "could not open" throws away the only part a person can act on.
132
+ setOpenErr(e instanceof AutomationError ? e.message : "that file could not be opened");
133
+ } finally {
134
+ setBusy("");
135
+ }
136
+ }, [agentId, open, at]);
137
+
138
+ const save = useCallback(async (restoredFrom?: number) => {
139
+ if (!open) return;
140
+ setBusy("save");
141
+ setNote("");
142
+ try {
143
+ const doc = await writeHarness(agentId, {
144
+ path: open.path,
145
+ body: draft,
146
+ // β›” `user`, ALWAYS, from this panel. `authorKind` is a claim about who DRAFTED the body,
147
+ // and everything typed here was typed by the person at the keyboard. The agent's own
148
+ // writes go through `record_version()` on the server with no session at all; a client
149
+ // that stamped "agent" on a hand-typed file would make the history a record of nothing.
150
+ authorKind: "user",
151
+ ...(restoredFrom ? { restoredFrom } : {}),
152
+ });
153
+ setOpen(doc);
154
+ setDraft(doc.body);
155
+ setAt(0);
156
+ dirty.current = false;
157
+ setNote(restoredFrom
158
+ ? `Version ${restoredFrom} is back, saved as version ${doc.atVersion}. Nothing was deleted.`
159
+ : `Saved as version ${doc.atVersion}.`);
160
+ await refresh();
161
+ } catch (e: unknown) {
162
+ setNote(e instanceof AutomationError ? e.message : "that file could not be saved");
163
+ } finally {
164
+ setBusy("");
165
+ }
166
+ }, [agentId, open, draft, refresh]);
167
+
168
+ const create = useCallback(async () => {
169
+ const path = newPath.trim();
170
+ if (!path) return;
171
+ setBusy("save");
172
+ setNote("");
173
+ try {
174
+ const doc = await writeHarness(agentId, { path, body: "", authorKind: "user" });
175
+ setNewPath("");
176
+ setOpen(doc);
177
+ setDraft(doc.body);
178
+ setAt(0);
179
+ dirty.current = false;
180
+ await refresh();
181
+ } catch (e: unknown) {
182
+ setNote(e instanceof AutomationError ? e.message : "that file could not be created");
183
+ } finally {
184
+ setBusy("");
185
+ }
186
+ }, [agentId, newPath, refresh]);
187
+
188
+ const drop = useCallback(async (path: string) => {
189
+ setBusy("delete");
190
+ setNote("");
191
+ try {
192
+ await deleteHarness(agentId, path);
193
+ if (open?.path === path) {
194
+ setOpen(null);
195
+ setDraft("");
196
+ }
197
+ await refresh();
198
+ } catch (e: unknown) {
199
+ setNote(e instanceof AutomationError ? e.message : "that file could not be deleted");
200
+ } finally {
201
+ setBusy("");
202
+ }
203
+ }, [agentId, open, refresh]);
204
+
205
+ const full = !!(limits && files && files.length >= limits.maxFiles);
206
+ const tooBig = !!(limits && new TextEncoder().encode(draft).length > limits.maxBodyBytes);
207
+
208
+ if (files === null) {
209
+ return <p className="auto-note">Reading this agent&apos;s harness files.</p>;
210
+ }
211
+
212
+ return (
213
+ <div className="autoh-wrap">
214
+ {listErr ? <p className="auto-note">{listErr}</p> : null}
215
+
216
+ {/* ── the file list ─────────────────────────────────────────────────────────────────── */}
217
+ {!files.length && !listErr ? (
218
+ <p className="auto-hint">
219
+ This agent has no harness files yet. A harness file is what the agent is instructed to
220
+ do: its router, its skills, anything it should read before it acts. Both you and the
221
+ agent can write them, and every save keeps the version before it.
222
+ </p>
223
+ ) : null}
224
+
225
+ <ul className="autoh-files">
226
+ {files.map((f) => (
227
+ <li key={f.path} className={"autoh-file" + (open?.path === f.path ? " is-on" : "")}>
228
+ <button
229
+ type="button"
230
+ className="autoh-open"
231
+ disabled={busy !== ""}
232
+ onClick={() => void openFile(f.path)}
233
+ >
234
+ <span className="autoh-path">{f.path}</span>
235
+ <span className="autoh-meta">
236
+ v{f.version}, {kb(f.bytes)}, {when(f.updated)} by {byline(f.author, f.authorKind)}
237
+ </span>
238
+ </button>
239
+ {/* ⚠ DELETING A FILE IS NOT THE THING R8 FORBIDS. R8 forbids a roll-back implemented as
240
+ a delete. Removing a file is a person deciding it should not exist, which is a
241
+ different act and gets a different, quieter control. */}
242
+ <button
243
+ type="button"
244
+ className="auto-btn is-danger autoh-drop"
245
+ disabled={busy !== ""}
246
+ aria-label={`Delete ${f.path}`}
247
+ onClick={() => void drop(f.path)}
248
+ >
249
+ Delete
250
+ </button>
251
+ </li>
252
+ ))}
253
+ </ul>
254
+
255
+ {/* ── add a file ────────────────────────────────────────────────────────────────────── */}
256
+ <div className="auto-field">
257
+ <label htmlFor="autoh-new">Add a file</label>
258
+ <div className="autoh-newrow">
259
+ <input
260
+ id="autoh-new"
261
+ className="auto-input"
262
+ value={newPath}
263
+ placeholder={SUGGESTED_PATHS[0]}
264
+ maxLength={limits?.maxPath || 200}
265
+ disabled={busy !== "" || full}
266
+ onChange={(e) => setNewPath(e.target.value)}
267
+ onKeyDown={(e) => {
268
+ if (e.key === "Enter") {
269
+ e.preventDefault();
270
+ void create();
271
+ }
272
+ }}
273
+ />
274
+ <button
275
+ type="button"
276
+ className="auto-btn"
277
+ disabled={busy !== "" || full || !newPath.trim()}
278
+ onClick={() => void create()}
279
+ >
280
+ Add
281
+ </button>
282
+ </div>
283
+ {/* β›” THE CAP IS SAID BEFORE IT BITES, not after. `limits` rides the payload for exactly
284
+ this; a ceiling a person meets as a refusal is a ceiling nobody could plan around. */}
285
+ <p className="auto-hint">
286
+ {full
287
+ ? `This agent already has the maximum of ${limits?.maxFiles} harness files. `
288
+ + "Delete one to add another."
289
+ : `A path like ${SUGGESTED_PATHS.join(" or ")}. `
290
+ + (limits ? `Up to ${limits.maxFiles} files, ${kb(limits.maxBodyBytes)} each.` : "")}
291
+ </p>
292
+ </div>
293
+
294
+ {openErr ? <p className="auto-note">{openErr}</p> : null}
295
+
296
+ {holdOpen ? (
297
+ <div className="autoh-hold">
298
+ <p className="auto-note">
299
+ The changes you typed into {open?.path} have not been saved, and opening{" "}
300
+ {holdOpen.version ? `version ${holdOpen.version}` : holdOpen.path} would replace them.
301
+ </p>
302
+ <div className="autoh-actions">
303
+ <button
304
+ type="button"
305
+ className="auto-btn"
306
+ onClick={() => void openFile(holdOpen.path, holdOpen.version, true)}
307
+ >
308
+ Discard them and open
309
+ </button>
310
+ <button type="button" className="auto-btn" onClick={() => setHoldOpen(null)}>
311
+ Keep editing
312
+ </button>
313
+ </div>
314
+ </div>
315
+ ) : null}
316
+
317
+ {/* ── the editor ────────────────────────────────────────────────────────────────────── */}
318
+ {open ? (
319
+ <>
320
+ <h3>{open.path}</h3>
321
+ {at ? (
322
+ /* β›” AN OLDER BODY IS LABELLED AS ONE, LOUDLY. Without this the editor shows an old
323
+ body in the same frame as the current one, and Save then looks like an ordinary
324
+ save rather than a roll-back. Naming it is what makes the next click honest. */
325
+ <p className="auto-note">
326
+ You are reading version {at} of {open.versions + open.trimmed}. Saving it writes a
327
+ NEW version that restores this one. Nothing in between is deleted.
328
+ </p>
329
+ ) : null}
330
+ <div className="auto-field">
331
+ <label htmlFor="autoh-body">
332
+ {at ? `Version ${at}` : `Current body, version ${open.atVersion}`}
333
+ </label>
334
+ <textarea
335
+ id="autoh-body"
336
+ className="auto-input is-mono autoh-body"
337
+ rows={14}
338
+ value={draft}
339
+ disabled={busy === "save"}
340
+ onChange={(e) => {
341
+ setDraft(e.target.value);
342
+ dirty.current = true;
343
+ }}
344
+ />
345
+ <p className="auto-hint">
346
+ {tooBig
347
+ ? `This is larger than the ${kb(limits?.maxBodyBytes || 0)} a harness file may be, `
348
+ + "so it will be refused. Shorten it."
349
+ : `${kb(new TextEncoder().encode(draft).length)} of `
350
+ + `${kb(limits?.maxBodyBytes || 0)}.`}
351
+ </p>
352
+ </div>
353
+ <div className="autoh-actions">
354
+ <button
355
+ type="button"
356
+ className="auto-btn is-primary"
357
+ disabled={busy !== "" || tooBig}
358
+ onClick={() => void save(at || undefined)}
359
+ >
360
+ {busy === "save"
361
+ ? "Saving"
362
+ : at
363
+ ? `Restore version ${at}`
364
+ : "Save a new version"}
365
+ </button>
366
+ {at ? (
367
+ <button
368
+ type="button"
369
+ className="auto-btn"
370
+ disabled={busy !== ""}
371
+ onClick={() => void openFile(open.path)}
372
+ >
373
+ Back to current
374
+ </button>
375
+ ) : null}
376
+ </div>
377
+ {note ? <p className="auto-note">{note}</p> : null}
378
+
379
+ {/* ── the history ─────────────────────────────────────────────────────────────── */}
380
+ <h3>Version history</h3>
381
+ <ol className="autoh-history">
382
+ {open.history.map((v) => (
383
+ <li key={v.version} className={v.version === (at || open.atVersion) ? "is-on" : ""}>
384
+ <button
385
+ type="button"
386
+ className="autoh-version"
387
+ disabled={busy !== ""}
388
+ onClick={() => void openFile(open.path, v.version)}
389
+ >
390
+ <span className="autoh-vnum">v{v.version}</span>
391
+ <span className="autoh-meta">
392
+ {when(v.created)} by {byline(v.author, v.authorKind)}, {kb(v.bytes)}
393
+ {v.restoredFrom ? `, restored version ${v.restoredFrom}` : ""}
394
+ </span>
395
+ </button>
396
+ </li>
397
+ ))}
398
+ </ol>
399
+ {/* β›” THE CAP THAT ACTS WITHOUT REFUSING. Past `maxVersions` the OLDEST bodies are
400
+ dropped, and a history that simply started at v14 would read as a file first saved
401
+ at v14. R6's second sentence: a limit that bites is REPORTED. */}
402
+ {open.trimmed ? (
403
+ <p className="auto-hint">
404
+ The {open.trimmed} oldest version{open.trimmed === 1 ? "" : "s"} of this file
405
+ {open.trimmed === 1 ? " has" : " have"} been dropped, because only the newest{" "}
406
+ {limits?.maxVersions} are kept. What they said is gone; that they existed is not.
407
+ </p>
408
+ ) : null}
409
+ </>
410
+ ) : null}
411
+ </div>
412
+ );
413
+ }
web/src/automation/PresetPlan.tsx CHANGED
@@ -1,122 +1,122 @@
1
- // ---------------------------------------------------------------------------
2
- // automation/PresetPlan.tsx β€” WAVE 25 item 4 (ruling R2b, contract C1):
3
- // WHICH COLUMNS THIS WILL USE, AND WHICH IT WILL CREATE.
4
- //
5
- // The owner's words: *"since this is a global fields all tenant use its really
6
- // just appending it and adding it to the custom database"* β€” so the Create
7
- // record action's configuration has to SHOW the two lists before anything is
8
- // spent, on whatever database that action names, including a hand-made one.
9
- //
10
- // β›” IT RENDERS THE SERVER'S ANSWER AND COMPUTES NOTHING (C1: "the client
11
- // renders this; it does not compute it"). Diffing the preset set against a
12
- // table's columns here would be a second implementation of `ut_ensure`'s merge
13
- // rule β€” and it would be wrong exactly when the two lists differ, which is the
14
- // only case this panel exists to answer.
15
- //
16
- // ⚠ ITS OWN FILE, AND THAT IS THE BUILDER'S LAW BEING KEPT RATHER THAN BENT.
17
- // `AutomationBuilder` renders SYNCHRONOUSLY from what it was handed (C14 leg 1
18
- // β€” the ghost fix: a view that can be in two shapes shows you the wrong one).
19
- // This panel genuinely needs a fetch, so it owns one, keeps a FIXED-SHAPE
20
- // skeleton while it is in flight, and never changes the shape of anything above
21
- // it. Exactly the split the Board already makes.
22
- // ---------------------------------------------------------------------------
23
- import { useEffect, useState } from "react";
24
-
25
- import { getPresetPlan } from "./automationApi";
26
- import type { PresetPlan as Plan } from "./automationApi";
27
-
28
- type Load =
29
- | { phase: "idle" }
30
- | { phase: "loading" }
31
- | { phase: "ready"; plan: Plan }
32
- | { phase: "error" };
33
-
34
- /**
35
- * ⚠ ONE LINE PER LIST, NOT A TOUR (DESIGN.md 4 / R13). The panel says what will happen and shows
36
- * the column names; it does not explain what a preset is, why the set is shared across tenants,
37
- * or what enrichment does. Each of those has a home β€” the action's own `detail`, the field's grey
38
- * machine-owned mark, the run log β€” and repeating them here is the paragraph nobody reads.
39
- */
40
- function List({ title, fields }: { title: string; fields: Plan["fields"] }) {
41
- if (!fields.length) return null;
42
- return (
43
- <div className="autox-preset-list">
44
- <p className="autox-preset-head">
45
- {title} <span className="autox-preset-n">{fields.length}</span>
46
- </p>
47
- <div className="autox-preset-chips">
48
- {fields.map((f) => (
49
- <span className="autox-preset-chip" key={f.key} title={`${f.key} Β· ${f.type}`}>
50
- {f.label}
51
- </span>
52
- ))}
53
- </div>
54
- </div>
55
- );
56
- }
57
-
58
- export default function PresetPlan({ table }: { table: string }) {
59
- const [load, setLoad] = useState<Load>({ phase: "idle" });
60
-
61
- useEffect(() => {
62
- if (!table) {
63
- setLoad({ phase: "idle" });
64
- return;
65
- }
66
- const ac = new AbortController();
67
- setLoad({ phase: "loading" });
68
- getPresetPlan(table, ac.signal)
69
- .then((plan) => setLoad({ phase: "ready", plan }))
70
- .catch((e) => {
71
- if ((e as Error)?.name === "AbortError") return;
72
- setLoad({ phase: "error" });
73
- });
74
- return () => ac.abort();
75
- }, [table]);
76
-
77
- // β›” NO DATABASE, NO CLAIM. With nothing chosen there is no question to answer, so this renders
78
- // nothing at all rather than an empty heading β€” a heading over nothing says "there should be
79
- // something here", which is a different and false statement (R13, and the same reasoning R14
80
- // applies to the whole Configuration section).
81
- if (!table || load.phase === "idle") return null;
82
-
83
- if (load.phase === "loading") {
84
- return (
85
- <p className="auto-note" role="status">
86
- <span className="lp-spin" aria-label="Loading" />
87
- </p>
88
- );
89
- }
90
-
91
- // ⚠ HONEST, AND IT DOES NOT GUESS. A failed fetch is not "no columns will be created" β€” that
92
- // would be a specific, checkable claim about the user's database, invented to keep a panel
93
- // tidy ([[no-unverifiable-aggregates]]). It says the server did not answer.
94
- if (load.phase === "error") {
95
- return <p className="auto-note">Could not read this database's columns just now.</p>;
96
- }
97
-
98
- const { plan } = load;
99
- return (
100
- <div className="autox-preset">
101
- {/*
102
- ⚠ THREE STATES, AND THE FIRST TWO ARE DIFFERENT FACTS. A database that does not exist yet
103
- (R10's spawn-on-save moment β€” the action names a table nobody has made) is not the same as
104
- one that exists and shares none of the columns, even though both render an empty "already
105
- here" list. The server answers `exists` precisely so this line does not have to infer it
106
- from a length.
107
- */}
108
- {!plan.exists ? (
109
- <p className="auto-hint">
110
- This database does not exist yet. Saving makes it, with these columns.
111
- </p>
112
- ) : null}
113
- <List title="Already in this database" fields={plan.willUse} />
114
- <List title="Will be created" fields={plan.willCreate} />
115
- {/* Both lists empty on a table that DOES exist means the server offered no preset set at
116
- all. Saying nothing here would leave the panel looking like it failed to load. */}
117
- {plan.exists && !plan.willUse.length && !plan.willCreate.length ? (
118
- <p className="auto-note">This server offered no preset columns.</p>
119
- ) : null}
120
- </div>
121
- );
122
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/PresetPlan.tsx β€” WAVE 25 item 4 (ruling R2b, contract C1):
3
+ // WHICH COLUMNS THIS WILL USE, AND WHICH IT WILL CREATE.
4
+ //
5
+ // The owner's words: *"since this is a global fields all tenant use its really
6
+ // just appending it and adding it to the custom database"* β€” so the Create
7
+ // record action's configuration has to SHOW the two lists before anything is
8
+ // spent, on whatever database that action names, including a hand-made one.
9
+ //
10
+ // β›” IT RENDERS THE SERVER'S ANSWER AND COMPUTES NOTHING (C1: "the client
11
+ // renders this; it does not compute it"). Diffing the preset set against a
12
+ // table's columns here would be a second implementation of `ut_ensure`'s merge
13
+ // rule β€” and it would be wrong exactly when the two lists differ, which is the
14
+ // only case this panel exists to answer.
15
+ //
16
+ // ⚠ ITS OWN FILE, AND THAT IS THE BUILDER'S LAW BEING KEPT RATHER THAN BENT.
17
+ // `AutomationBuilder` renders SYNCHRONOUSLY from what it was handed (C14 leg 1
18
+ // β€” the ghost fix: a view that can be in two shapes shows you the wrong one).
19
+ // This panel genuinely needs a fetch, so it owns one, keeps a FIXED-SHAPE
20
+ // skeleton while it is in flight, and never changes the shape of anything above
21
+ // it. Exactly the split the Board already makes.
22
+ // ---------------------------------------------------------------------------
23
+ import { useEffect, useState } from "react";
24
+
25
+ import { getPresetPlan } from "./automationApi";
26
+ import type { PresetPlan as Plan } from "./automationApi";
27
+
28
+ type Load =
29
+ | { phase: "idle" }
30
+ | { phase: "loading" }
31
+ | { phase: "ready"; plan: Plan }
32
+ | { phase: "error" };
33
+
34
+ /**
35
+ * ⚠ ONE LINE PER LIST, NOT A TOUR (DESIGN.md 4 / R13). The panel says what will happen and shows
36
+ * the column names; it does not explain what a preset is, why the set is shared across tenants,
37
+ * or what enrichment does. Each of those has a home β€” the action's own `detail`, the field's grey
38
+ * machine-owned mark, the run log β€” and repeating them here is the paragraph nobody reads.
39
+ */
40
+ function List({ title, fields }: { title: string; fields: Plan["fields"] }) {
41
+ if (!fields.length) return null;
42
+ return (
43
+ <div className="autox-preset-list">
44
+ <p className="autox-preset-head">
45
+ {title} <span className="autox-preset-n">{fields.length}</span>
46
+ </p>
47
+ <div className="autox-preset-chips">
48
+ {fields.map((f) => (
49
+ <span className="autox-preset-chip" key={f.key} title={`${f.key} Β· ${f.type}`}>
50
+ {f.label}
51
+ </span>
52
+ ))}
53
+ </div>
54
+ </div>
55
+ );
56
+ }
57
+
58
+ export default function PresetPlan({ table }: { table: string }) {
59
+ const [load, setLoad] = useState<Load>({ phase: "idle" });
60
+
61
+ useEffect(() => {
62
+ if (!table) {
63
+ setLoad({ phase: "idle" });
64
+ return;
65
+ }
66
+ const ac = new AbortController();
67
+ setLoad({ phase: "loading" });
68
+ getPresetPlan(table, ac.signal)
69
+ .then((plan) => setLoad({ phase: "ready", plan }))
70
+ .catch((e) => {
71
+ if ((e as Error)?.name === "AbortError") return;
72
+ setLoad({ phase: "error" });
73
+ });
74
+ return () => ac.abort();
75
+ }, [table]);
76
+
77
+ // β›” NO DATABASE, NO CLAIM. With nothing chosen there is no question to answer, so this renders
78
+ // nothing at all rather than an empty heading β€” a heading over nothing says "there should be
79
+ // something here", which is a different and false statement (R13, and the same reasoning R14
80
+ // applies to the whole Configuration section).
81
+ if (!table || load.phase === "idle") return null;
82
+
83
+ if (load.phase === "loading") {
84
+ return (
85
+ <p className="auto-note" role="status">
86
+ <span className="lp-spin" aria-label="Loading" />
87
+ </p>
88
+ );
89
+ }
90
+
91
+ // ⚠ HONEST, AND IT DOES NOT GUESS. A failed fetch is not "no columns will be created" β€” that
92
+ // would be a specific, checkable claim about the user's database, invented to keep a panel
93
+ // tidy ([[no-unverifiable-aggregates]]). It says the server did not answer.
94
+ if (load.phase === "error") {
95
+ return <p className="auto-note">Could not read this database's columns just now.</p>;
96
+ }
97
+
98
+ const { plan } = load;
99
+ return (
100
+ <div className="autox-preset">
101
+ {/*
102
+ ⚠ THREE STATES, AND THE FIRST TWO ARE DIFFERENT FACTS. A database that does not exist yet
103
+ (R10's spawn-on-save moment β€” the action names a table nobody has made) is not the same as
104
+ one that exists and shares none of the columns, even though both render an empty "already
105
+ here" list. The server answers `exists` precisely so this line does not have to infer it
106
+ from a length.
107
+ */}
108
+ {!plan.exists ? (
109
+ <p className="auto-hint">
110
+ This database does not exist yet. Saving makes it, with these columns.
111
+ </p>
112
+ ) : null}
113
+ <List title="Already in this database" fields={plan.willUse} />
114
+ <List title="Will be created" fields={plan.willCreate} />
115
+ {/* Both lists empty on a table that DOES exist means the server offered no preset set at
116
+ all. Saying nothing here would leave the panel looking like it failed to load. */}
117
+ {plan.exists && !plan.willUse.length && !plan.willCreate.length ? (
118
+ <p className="auto-note">This server offered no preset columns.</p>
119
+ ) : null}
120
+ </div>
121
+ );
122
+ }
web/src/automation/automation.css CHANGED
@@ -1,559 +1,559 @@
1
- /* ---------------------------------------------------------------------------
2
- automation/automation.css β€” the Agent module's OWN stylesheet.
3
-
4
- ⭐⭐ WAVE 34 Β· W34-T41 β€” THIS FILE IS NEW, AND ITS EXISTENCE IS THE POINT.
5
-
6
- Until today this module had NO scoped CSS at all: every `auto-*`, `autob-*` and `autox-*` rule
7
- lived in the shared global `src/index.css`, which the wave PRD assigns to session C. That made
8
- any new rule here a cross-fence ask, for styling nobody else can see β€” the PRD's own remedy is
9
- "put NEW rules in your own module stylesheet (`automation/*.css`)", and this is that file.
10
-
11
- β›” WHAT DOES NOT BELONG HERE: an edit to an existing `auto-*` rule. Those still live in
12
- `index.css` and are still C's. This file holds rules that did not exist before, so the two can
13
- never disagree about one selector.
14
-
15
- ⚠ EVERY COLOUR IS A TOKEN. No literal hex, for the reason the palette block in `index.css`
16
- records: a hand-copied brand value silently paints last wave's brand while a comment asserts
17
- parity. Light and dark both come free that way.
18
- --------------------------------------------------------------------------- */
19
-
20
- /* ── the Chat view (R17) ──────────────────────────────────────────────────── */
21
-
22
- /* Mirrors `.autox-flow`'s box so switching Canvas <-> Chat does not move the frame around it:
23
- same flex growth, same min-height:0 (without which a scrolling child of a flex parent grows
24
- the parent instead of scrolling), same scroll ownership. */
25
- .autoc-chat {
26
- flex: 1 1 auto;
27
- min-width: 0;
28
- min-height: 0;
29
- display: flex;
30
- flex-direction: column;
31
- }
32
-
33
- .autoc-log {
34
- flex: 1 1 auto;
35
- min-height: 0;
36
- overflow-y: auto;
37
- padding: 20px 24px 12px;
38
- display: flex;
39
- flex-direction: column;
40
- gap: 14px;
41
- }
42
-
43
- /* β›” `.autoc-empty` STOOD HERE AND WAS DELETED WITH ITS ONLY USER (W36-T30, owner item 4). A rule
44
- whose class no longer appears in any .tsx is dead weight the next reader has to prove is dead,
45
- which is why the tombstone is cheaper than the rule. W36-T33's rebuilt empty state gets its own. */
46
-
47
- .autoc-msg {
48
- max-width: 60ch;
49
- padding: 10px 14px;
50
- border-radius: var(--lp-r-md);
51
- font-size: var(--lp-fs-sm);
52
- line-height: 1.5;
53
- white-space: pre-wrap;
54
- overflow-wrap: anywhere;
55
- }
56
- .autoc-msg.is-you {
57
- align-self: flex-end;
58
- background: var(--lp-surface-2);
59
- color: var(--lp-ink);
60
- }
61
- .autoc-msg.is-agent {
62
- align-self: flex-start;
63
- border: 1px solid var(--lp-line);
64
- color: var(--lp-ink);
65
- }
66
- /* β›” A FAILED TURN IS A MESSAGE, NOT A TOAST. A toast is gone before a reader has finished the
67
- sentence, and this surface's failures are things you act on (rephrase, pick a database).
68
- ⚠ `--lp-red-deep` / `--lp-red-tint`, CHECKED AGAINST THE PALETTE, not typed from memory: the
69
- first draft of this rule used `--lp-danger` and `--lp-danger-line`, and NEITHER EXISTS. A ghost
70
- custom property does not fail loudly β€” it falls back or inherits β€” so the error message would
71
- have painted in ordinary ink and looked like an answer. Same defect T14 caught on
72
- `--lp-ink-muted` in the same wave; the palette is the only source worth trusting. */
73
- .autoc-msg.is-error {
74
- align-self: flex-start;
75
- border: 1px solid var(--lp-red);
76
- background: var(--lp-red-tint);
77
- color: var(--lp-red-deep);
78
- }
79
-
80
- /* What the model asked for and the validator would not keep. ⚠ It renders as ORDINARY content,
81
- not as a warning ornament: R6's standing rule is that a limit must be REPORTED, and a report
82
- nobody reads because it looks like chrome is the same as no report. */
83
- .autoc-dropped {
84
- align-self: flex-start;
85
- max-width: 60ch;
86
- margin: 0;
87
- padding: 8px 12px;
88
- border-left: 2px solid var(--lp-line);
89
- color: var(--lp-muted);
90
- font-size: var(--lp-fs-xs);
91
- line-height: 1.5;
92
- }
93
- .autoc-dropped ul { margin: 4px 0 0; padding-left: 18px; }
94
-
95
- /* ⭐⭐ W36-T33 β€” THE COMPOSER IS THE ASSISTANT'S, IN THIS MODULE'S NAMES.
96
- Owner: *"Just as good as the Assistant module."* The done-when is a comparison, so these rules
97
- mirror `assistant/assistant.css`'s `.as-field` / `.as-prompt` / `.as-field-foot` / `.as-send`
98
- on the SAME TOKENS. Not `@extend`, not a shared class: `.as-*` belongs to the Assistant's
99
- stylesheet and reaching into it would make one surface's restyle silently repaint the other.
100
- β›” WHAT MUST NOT DRIFT is the pair of numbers that carry the shape β€” the 22px pill radius and
101
- the field's shadow β€” because those are what the eye compares. Both are matched BY VALUE from
102
- `.as-field`, and the shadow is a literal because THIS PRODUCT HAS NO SHADOW TOKEN: `index.css`
103
- records that finding in as many words beside `.autoc-bigedit`, where naming a shadow token that
104
- does not exist would have quietly rendered its own fallback while looking like a token was
105
- being honoured.
106
- ⚠ AND THAT SENTENCE USED TO NAME THE TOKEN, WHICH BROKE THE GATE THAT READS THIS FILE. R17's
107
- "every token the new stylesheet uses is DEFINED in the palette" scans the raw text, comments
108
- included, so quoting `var(--…)` in prose counts as USING it: the citation reddened the check
109
- [[prose-that-becomes-its-own-marker]]. Describe a token you are NOT using; never spell it. */
110
-
111
- /* β›” NO HAIRLINE ON THE BAND ANY MORE. The card below has its own border, and a rule across the
112
- pane above it made two edges 12px apart β€” the "still so ugly" the owner reported is mostly
113
- this kind of doubling. What separates the composer from the transcript now is whitespace. */
114
- .autoc-compose {
115
- flex: 0 0 auto;
116
- padding: 8px 24px 20px;
117
- }
118
- .autoc-field {
119
- /* ONE measure for the conversation and the empty state, so the composer does not change width
120
- when the first message lands. `.as-opening .as-composer` caps at the same 700px. */
121
- max-width: 700px;
122
- margin: 0 auto;
123
- border: 1px solid var(--lp-line);
124
- border-radius: 22px;
125
- background: var(--lp-surface);
126
- padding: 10px 8px 8px 16px;
127
- box-shadow: 0 1px 2px rgba(20, 24, 40, 0.05);
128
- box-sizing: border-box;
129
- }
130
- .autoc-field:focus-within { border-color: var(--lp-blue-solid); }
131
-
132
- /* ⚠ `rows={1}` PLUS `max-height`, which is `.as-prompt`'s shape and not the two-row box that was
133
- here. A composer that starts tall claims space before anybody has typed; the Assistant's grows
134
- into the sentence instead. */
135
- .autoc-input {
136
- display: block;
137
- width: 100%;
138
- max-height: 180px;
139
- border: 0;
140
- outline: none;
141
- padding: 0 8px 0 0;
142
- background: transparent;
143
- color: var(--lp-ink);
144
- font: inherit;
145
- font-size: var(--lp-fs-sm);
146
- line-height: var(--lp-lh);
147
- resize: none;
148
- box-sizing: border-box;
149
- }
150
- .autoc-input::placeholder { color: var(--lp-muted); }
151
-
152
- /* The row BELOW the input and INSIDE the card β€” the reference screenshot's arrangement, and the
153
- slot W36-T34's model toggle drops into beside the send. */
154
- .autoc-foot {
155
- display: flex;
156
- align-items: center;
157
- gap: 12px;
158
- margin-top: 8px;
159
- }
160
-
161
- .autoc-send {
162
- flex: 0 0 auto;
163
- margin-left: auto;
164
- width: 30px;
165
- height: 30px;
166
- display: inline-flex;
167
- align-items: center;
168
- justify-content: center;
169
- border: 0;
170
- border-radius: 999px;
171
- background: var(--lp-ink);
172
- color: var(--lp-surface);
173
- cursor: pointer;
174
- }
175
- .autoc-send svg {
176
- fill: none;
177
- stroke: currentColor;
178
- stroke-width: 1.7;
179
- stroke-linecap: round;
180
- stroke-linejoin: round;
181
- }
182
- .autoc-send:disabled { background: var(--lp-surface-2); color: var(--lp-muted); cursor: default; }
183
- .autoc-send:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 1px; }
184
-
185
- /* ── the empty state (mirrors `.as-opening`) ──────────────────────────────── */
186
-
187
- .autoc-opening {
188
- flex: 1 1 auto;
189
- min-height: 0;
190
- display: flex;
191
- flex-direction: column;
192
- align-items: center;
193
- justify-content: center;
194
- padding: 24px;
195
- box-sizing: border-box;
196
- text-align: center;
197
- }
198
- .autoc-opening-h {
199
- margin: 0 0 6px;
200
- color: var(--lp-ink);
201
- font-size: var(--lp-fs-lg);
202
- font-weight: 650;
203
- }
204
- .autoc-opening-p {
205
- max-width: 52ch;
206
- margin: 0 0 20px;
207
- color: var(--lp-muted);
208
- font-size: var(--lp-fs-sm);
209
- line-height: var(--lp-lh);
210
- }
211
- /* The composer is left-aligned inside a centred column, exactly as the Assistant's is: centred
212
- placeholder text in a wide field reads as a search box, not as somewhere to write a sentence. */
213
- .autoc-opening .autoc-field { width: 100%; text-align: left; }
214
-
215
- /* The pending row. ⚠ It uses `.lp-spin`, the ONE loading mark app-wide (purple as of this wave's
216
- T24) β€” a second spinner vocabulary in a new surface is how an app stops having one. */
217
- .autoc-pending {
218
- display: flex;
219
- align-items: center;
220
- gap: 8px;
221
- align-self: flex-start;
222
- color: var(--lp-muted);
223
- font-size: var(--lp-fs-sm);
224
- }
225
-
226
- /* The accept bar. It is deliberately NOT inside the transcript: accepting is an act on the
227
- AUTOMATION, not a reply in the conversation, and putting it in the log would make it scroll
228
- away from the thing it acts on. */
229
- .autoc-accept {
230
- flex: 0 0 auto;
231
- display: flex;
232
- align-items: center;
233
- gap: 10px;
234
- padding: 10px 24px;
235
- border-top: 1px solid var(--lp-line);
236
- background: var(--lp-surface-2);
237
- font-size: var(--lp-fs-sm);
238
- }
239
- .autoc-accept-note { color: var(--lp-muted); margin-right: auto; }
240
-
241
- /* ── the run log's note disclosure (R21 / W34-T45) ────────────────────────── */
242
-
243
- /* ⭐ WAVE 34 · W34-T45. `notes` is up to 300 chars x 25 entries per run and was rendered
244
- unconditionally over 20 runs; that is the "too wordy" the owner reported. It is still
245
- unconditional for a run that FAILED or hit a cap (R6: a limit must be REPORTED) and behind this
246
- disclosure otherwise.
247
- ⚠ The list INSIDE stays `.auto-run-notes`, which is C's existing rule in `index.css`. Only the
248
- wrapper is new, so the notes themselves cannot start looking different depending on which
249
- branch rendered them. */
250
- .autor-notes {
251
- margin: 2px 0 0;
252
- }
253
- .autor-notes-toggle {
254
- cursor: pointer;
255
- color: var(--lp-muted);
256
- font-size: var(--lp-fs-2xs);
257
- /* The default triangle is the affordance; no custom marker, because a disclosure that does not
258
- look like one is how a person decides there is nothing behind it. */
259
- list-style: revert;
260
- }
261
- .autor-notes-toggle:hover { color: var(--lp-ink); }
262
- .autor-notes-toggle:focus-visible {
263
- outline: 2px solid var(--lp-blue-deep);
264
- outline-offset: 1px;
265
- }
266
-
267
- /* ── the parked statements batch (W35-T36 / owner ruling R10) ─────────────── */
268
-
269
- /* ⭐⭐ "N STATEMENTS ARE READY", with the ONLY Send control in the product.
270
- It sits above `.auto-work`, in the banner band, because it is the one thing on this agent that
271
- needs a person β€” R10's whole shape is that the run assembles and PARKS, and somebody releases.
272
-
273
- ⚠ IT IS DELIBERATELY NOT A WARNING COLOUR. A parked batch is the system working as designed, and
274
- painting it amber would teach people to dismiss the panel that guards a real mail send. It is
275
- the blue tint every other "here is something to look at" surface uses. */
276
- .auto-batch {
277
- flex: 0 0 auto;
278
- margin: 12px 24px 0;
279
- padding: 12px 14px;
280
- border: 1px solid var(--lp-blue);
281
- border-radius: var(--lp-r-md);
282
- background: var(--lp-blue-tint);
283
- font-size: var(--lp-fs-sm);
284
- }
285
- .auto-batch-head {
286
- display: flex;
287
- align-items: baseline;
288
- flex-wrap: wrap;
289
- gap: 4px 10px;
290
- }
291
- .auto-batch-count {
292
- font-weight: 650;
293
- color: var(--lp-ink);
294
- }
295
- .auto-batch-note { color: var(--lp-muted); }
296
-
297
- /* The guardrail line. Same size as a note, because it IS one: the data layer decides, this
298
- reports (R6's second sentence). */
299
- .auto-batch-safe,
300
- .auto-batch-line {
301
- margin: 6px 0 0;
302
- color: var(--lp-muted);
303
- font-size: var(--lp-fs-xs);
304
- line-height: 1.5;
305
- max-width: 70ch;
306
- }
307
-
308
- /* Who is about to be emailed. ⚠ Bounded in the MARKUP at 8 rows with an "and N more" line rather
309
- than scrolled here: a 200-row list inside a banner pushes the work area off the screen, and the
310
- panel's job is to say who and how many, not to be the worklist. */
311
- .auto-batch-list {
312
- margin: 8px 0 0;
313
- padding: 0;
314
- list-style: none;
315
- display: flex;
316
- flex-direction: column;
317
- gap: 2px;
318
- font-size: var(--lp-fs-xs);
319
- }
320
- .auto-batch-list li {
321
- display: flex;
322
- gap: 10px;
323
- align-items: baseline;
324
- }
325
- .auto-batch-cust { color: var(--lp-ink); }
326
- .auto-batch-to { color: var(--lp-muted); overflow-wrap: anywhere; }
327
- .auto-batch-more { color: var(--lp-muted); }
328
-
329
- .auto-batch-actions {
330
- margin-top: 10px;
331
- display: flex;
332
- gap: 8px;
333
- }
334
-
335
- /* ── W36-T44 (D-316 + D-299): the statements step's config panel ───────────── */
336
-
337
- /* NEW rules only, in this module's own stylesheet. Every `auto-*` rule the panel reuses
338
- (`auto-field`, `auto-input`, `auto-hint`, `auto-note`, `auto-btn`) still lives in the shared
339
- `index.css` and is still another lane's, so nothing here redefines one. */
340
-
341
- /* The two action rows (Preview, Send one test). A row rather than a bare button so the two read
342
- as the same kind of control at the same left edge as every field above them. */
343
- .autox-stmt-row {
344
- display: flex;
345
- gap: 8px;
346
- margin: 0 0 14px;
347
- }
348
-
349
- .autox-stmt-shot {
350
- margin: 0 0 14px;
351
- border: 1px solid var(--lp-line);
352
- border-radius: var(--lp-r-md);
353
- padding: 10px 12px;
354
- background: var(--lp-surface-2);
355
- }
356
- .autox-stmt-shot .auto-hint {
357
- margin: 0 0 8px;
358
- overflow-wrap: anywhere;
359
- }
360
-
361
- /* ⚠ A FIXED HEIGHT, AND IT SCROLLS INSIDE ITSELF. A statement for a customer with forty open
362
- invoices is a long document, and a preview that grows to its content pushes the test-send
363
- control below it off the panel: the one thing somebody must reach after reading a preview.
364
-
365
- β›” AND THE LITERAL WHITE IS THE ONE DELIBERATE EXCEPTION TO THIS FILE'S "every colour is a
366
- token" RULE, booked here rather than left to read as an oversight. What is inside this frame is
367
- not our chrome, it is the EMAIL: `render_statement_html` hard-codes #1F4E78 headers, #e3e8ef
368
- rules and near-black body text against an assumed white page, and the recipient's mail client
369
- will paint it on white whatever this app's theme is. A surface token would go dark in dark mode
370
- and render the real mail's dark text on a dark ground, so the preview would stop showing what
371
- goes out at exactly the moment somebody is checking what goes out. */
372
- .autox-stmt-frame {
373
- display: block;
374
- width: 100%;
375
- height: 260px;
376
- border: 1px solid var(--lp-line);
377
- border-radius: var(--lp-r-sm);
378
- background: #fff;
379
- }
380
-
381
- /* ── W36-T31 (owner item 3, R7/R8, contract C4): the Harness tab ───────────── */
382
-
383
- /* NEW rules only. Everything shared (`auto-field`, `auto-input`, `auto-btn`, `auto-note`,
384
- `auto-hint`, `auto-paneltab*`) still lives in `index.css` and is still another lane's. */
385
-
386
- .autoh-wrap {
387
- display: flex;
388
- flex-direction: column;
389
- gap: 4px;
390
- }
391
-
392
- .autoh-files {
393
- margin: 0 0 14px;
394
- padding: 0;
395
- list-style: none;
396
- display: flex;
397
- flex-direction: column;
398
- gap: 2px;
399
- }
400
- .autoh-file {
401
- display: flex;
402
- align-items: center;
403
- gap: 6px;
404
- border-radius: var(--lp-r-sm);
405
- }
406
- .autoh-file.is-on { background: var(--lp-blue-tint); }
407
-
408
- /* The row is a BUTTON, so the whole line opens the file. A path that is only clickable on its
409
- own glyph-width is a target people miss and then decide is not clickable at all. */
410
- .autoh-open {
411
- flex: 1 1 auto;
412
- min-width: 0;
413
- display: flex;
414
- flex-direction: column;
415
- gap: 1px;
416
- padding: 5px 8px;
417
- border: 0;
418
- border-radius: var(--lp-r-sm);
419
- background: transparent;
420
- color: var(--lp-ink);
421
- font: inherit;
422
- text-align: left;
423
- cursor: pointer;
424
- }
425
- .autoh-open:hover:not(:disabled) { background: var(--lp-surface-2); }
426
- .autoh-open:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
427
- .autoh-open:disabled { cursor: default; }
428
-
429
- /* ⚠ `anywhere`, not `ellipsis`: a harness path is `skills/router.md`, and the half that
430
- identifies it is the END. Truncating from the right hides exactly the distinguishing part. */
431
- .autoh-path {
432
- font-size: var(--lp-fs-sm);
433
- font-weight: 600;
434
- overflow-wrap: anywhere;
435
- }
436
- .autoh-meta {
437
- color: var(--lp-muted);
438
- font-size: var(--lp-fs-2xs);
439
- overflow-wrap: anywhere;
440
- }
441
-
442
- /* Quiet until reached for. Deleting a file is a real act (it takes the history with it), so it is
443
- present and honest rather than hidden, but it does not compete with opening one. */
444
- .autoh-drop {
445
- flex: 0 0 auto;
446
- opacity: 0.55;
447
- }
448
- .autoh-file:hover .autoh-drop,
449
- .autoh-drop:focus-visible { opacity: 1; }
450
-
451
- .autoh-newrow {
452
- display: flex;
453
- gap: 6px;
454
- align-items: center;
455
- }
456
-
457
- /* Monospace, because a harness file is a router or a skill: its indentation carries meaning and a
458
- proportional font makes a misaligned block look aligned.
459
- β›” THE FACE COMES FROM `.auto-input.is-mono`, WHICH THE TEXTAREA ALSO CARRIES, and this rule sets
460
- no `font-family` at all. `index.css:12591` records why in as many words: there IS no `--lp-mono`
461
- token, six sites spell the stack out, and a seventh copy here would put the product's mono face
462
- in two places that can drift. `WebActionConfig` reaches for the same class. */
463
- .autoh-body {
464
- font-size: var(--lp-fs-xs);
465
- line-height: 1.55;
466
- resize: vertical;
467
- }
468
-
469
- .autoh-actions {
470
- display: flex;
471
- gap: 8px;
472
- margin: 0 0 14px;
473
- }
474
-
475
- .autoh-history {
476
- margin: 0 0 8px;
477
- padding: 0;
478
- list-style: none;
479
- display: flex;
480
- flex-direction: column;
481
- gap: 1px;
482
- }
483
- .autoh-history li { border-radius: var(--lp-r-sm); }
484
- .autoh-history li.is-on { background: var(--lp-blue-tint); }
485
- .autoh-version {
486
- width: 100%;
487
- display: flex;
488
- gap: 8px;
489
- align-items: baseline;
490
- padding: 4px 8px;
491
- border: 0;
492
- border-radius: var(--lp-r-sm);
493
- background: transparent;
494
- color: var(--lp-ink);
495
- font: inherit;
496
- text-align: left;
497
- cursor: pointer;
498
- }
499
- .autoh-version:hover:not(:disabled) { background: var(--lp-surface-2); }
500
- .autoh-version:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
501
- .autoh-version:disabled { cursor: default; }
502
- .autoh-vnum {
503
- flex: 0 0 auto;
504
- font-size: var(--lp-fs-xs);
505
- font-weight: 650;
506
- }
507
-
508
- /* The unsaved-edit hold. A bordered block rather than a tint, because it is a QUESTION waiting on
509
- an answer and the two buttons under it are the answer; a tinted note reads as commentary. */
510
- .autoh-hold {
511
- margin: 0 0 14px;
512
- padding: 10px 12px;
513
- border: 1px solid var(--lp-line);
514
- border-radius: var(--lp-r-md);
515
- background: var(--lp-surface-2);
516
- }
517
- .autoh-hold .auto-note { margin-top: 0; }
518
-
519
- /* ── W36-T32 (owner item 3, R7): the right rail folds behind a "III" ───────── */
520
-
521
- /* β›” THE FOLD SITS AT THE RAIL'S OWN LEFT EDGE, AND `flex-start` IS ONLY HALF OF WHY.
522
- W35-T11 put the left rails' fold at their left edge; this rail is on the RIGHT, so its left
523
- edge is the one facing the chat it widens. `.auto-panel-head` is `space-between` and lives in
524
- `index.css` (another lane's), so this wrapper is what keeps the fold and the tabs together
525
- instead of flung to the panel's two edges.
526
- β›”β›” AND NOTHING IN HERE MAY EVER CARRY `margin-left: auto`. W35-T28's real finding was that a
527
- sibling's auto margin ate the free space BEFORE `justify-content` applied, so one control sat
528
- left on one database and right on another: one control, two positions, decided by data. */
529
- .autod-head {
530
- flex: 1 1 auto;
531
- min-width: 0;
532
- display: flex;
533
- align-items: center;
534
- justify-content: flex-start;
535
- gap: 10px;
536
- }
537
-
538
- /* The collapsed rail. Same width token and the same idea as `.auto-rail.is-collapsed` on the
539
- left of this screen: folding a rail leaves a strip, never a gap, because the strip is where the
540
- way back lives. */
541
- .autod-shut {
542
- flex: 0 0 auto;
543
- width: var(--lp-rail-min);
544
- display: flex;
545
- justify-content: center;
546
- padding: 14px 6px 0;
547
- border-left: 1px solid var(--lp-line);
548
- background: var(--lp-surface);
549
- }
550
-
551
- /* β›” THE FOLD, IN ONE PLACE. Every `.auto-panel` in the work area goes at once β€” Properties (a
552
- child of AutomationBuilder), Harness and Run history (children of AutomationDetail) β€” so a
553
- panel added later folds without being told to. `display: none` also removes them from the
554
- accessibility tree, which is the property `hidden` was giving us and the reason a `visibility`
555
- or `width: 0` treatment would be a regression a screen reader would meet and nobody would see. */
556
- .autod-folded .auto-panel { display: none; }
557
 
558
  /* ── W36-T34 (owner item 3, R4, contract C5): the model toggle ─────────────── */
559
 
 
1
+ /* ---------------------------------------------------------------------------
2
+ automation/automation.css β€” the Agent module's OWN stylesheet.
3
+
4
+ ⭐⭐ WAVE 34 Β· W34-T41 β€” THIS FILE IS NEW, AND ITS EXISTENCE IS THE POINT.
5
+
6
+ Until today this module had NO scoped CSS at all: every `auto-*`, `autob-*` and `autox-*` rule
7
+ lived in the shared global `src/index.css`, which the wave PRD assigns to session C. That made
8
+ any new rule here a cross-fence ask, for styling nobody else can see β€” the PRD's own remedy is
9
+ "put NEW rules in your own module stylesheet (`automation/*.css`)", and this is that file.
10
+
11
+ β›” WHAT DOES NOT BELONG HERE: an edit to an existing `auto-*` rule. Those still live in
12
+ `index.css` and are still C's. This file holds rules that did not exist before, so the two can
13
+ never disagree about one selector.
14
+
15
+ ⚠ EVERY COLOUR IS A TOKEN. No literal hex, for the reason the palette block in `index.css`
16
+ records: a hand-copied brand value silently paints last wave's brand while a comment asserts
17
+ parity. Light and dark both come free that way.
18
+ --------------------------------------------------------------------------- */
19
+
20
+ /* ── the Chat view (R17) ──────────────────────────────────────────────────── */
21
+
22
+ /* Mirrors `.autox-flow`'s box so switching Canvas <-> Chat does not move the frame around it:
23
+ same flex growth, same min-height:0 (without which a scrolling child of a flex parent grows
24
+ the parent instead of scrolling), same scroll ownership. */
25
+ .autoc-chat {
26
+ flex: 1 1 auto;
27
+ min-width: 0;
28
+ min-height: 0;
29
+ display: flex;
30
+ flex-direction: column;
31
+ }
32
+
33
+ .autoc-log {
34
+ flex: 1 1 auto;
35
+ min-height: 0;
36
+ overflow-y: auto;
37
+ padding: 20px 24px 12px;
38
+ display: flex;
39
+ flex-direction: column;
40
+ gap: 14px;
41
+ }
42
+
43
+ /* β›” `.autoc-empty` STOOD HERE AND WAS DELETED WITH ITS ONLY USER (W36-T30, owner item 4). A rule
44
+ whose class no longer appears in any .tsx is dead weight the next reader has to prove is dead,
45
+ which is why the tombstone is cheaper than the rule. W36-T33's rebuilt empty state gets its own. */
46
+
47
+ .autoc-msg {
48
+ max-width: 60ch;
49
+ padding: 10px 14px;
50
+ border-radius: var(--lp-r-md);
51
+ font-size: var(--lp-fs-sm);
52
+ line-height: 1.5;
53
+ white-space: pre-wrap;
54
+ overflow-wrap: anywhere;
55
+ }
56
+ .autoc-msg.is-you {
57
+ align-self: flex-end;
58
+ background: var(--lp-surface-2);
59
+ color: var(--lp-ink);
60
+ }
61
+ .autoc-msg.is-agent {
62
+ align-self: flex-start;
63
+ border: 1px solid var(--lp-line);
64
+ color: var(--lp-ink);
65
+ }
66
+ /* β›” A FAILED TURN IS A MESSAGE, NOT A TOAST. A toast is gone before a reader has finished the
67
+ sentence, and this surface's failures are things you act on (rephrase, pick a database).
68
+ ⚠ `--lp-red-deep` / `--lp-red-tint`, CHECKED AGAINST THE PALETTE, not typed from memory: the
69
+ first draft of this rule used `--lp-danger` and `--lp-danger-line`, and NEITHER EXISTS. A ghost
70
+ custom property does not fail loudly β€” it falls back or inherits β€” so the error message would
71
+ have painted in ordinary ink and looked like an answer. Same defect T14 caught on
72
+ `--lp-ink-muted` in the same wave; the palette is the only source worth trusting. */
73
+ .autoc-msg.is-error {
74
+ align-self: flex-start;
75
+ border: 1px solid var(--lp-red);
76
+ background: var(--lp-red-tint);
77
+ color: var(--lp-red-deep);
78
+ }
79
+
80
+ /* What the model asked for and the validator would not keep. ⚠ It renders as ORDINARY content,
81
+ not as a warning ornament: R6's standing rule is that a limit must be REPORTED, and a report
82
+ nobody reads because it looks like chrome is the same as no report. */
83
+ .autoc-dropped {
84
+ align-self: flex-start;
85
+ max-width: 60ch;
86
+ margin: 0;
87
+ padding: 8px 12px;
88
+ border-left: 2px solid var(--lp-line);
89
+ color: var(--lp-muted);
90
+ font-size: var(--lp-fs-xs);
91
+ line-height: 1.5;
92
+ }
93
+ .autoc-dropped ul { margin: 4px 0 0; padding-left: 18px; }
94
+
95
+ /* ⭐⭐ W36-T33 β€” THE COMPOSER IS THE ASSISTANT'S, IN THIS MODULE'S NAMES.
96
+ Owner: *"Just as good as the Assistant module."* The done-when is a comparison, so these rules
97
+ mirror `assistant/assistant.css`'s `.as-field` / `.as-prompt` / `.as-field-foot` / `.as-send`
98
+ on the SAME TOKENS. Not `@extend`, not a shared class: `.as-*` belongs to the Assistant's
99
+ stylesheet and reaching into it would make one surface's restyle silently repaint the other.
100
+ β›” WHAT MUST NOT DRIFT is the pair of numbers that carry the shape β€” the 22px pill radius and
101
+ the field's shadow β€” because those are what the eye compares. Both are matched BY VALUE from
102
+ `.as-field`, and the shadow is a literal because THIS PRODUCT HAS NO SHADOW TOKEN: `index.css`
103
+ records that finding in as many words beside `.autoc-bigedit`, where naming a shadow token that
104
+ does not exist would have quietly rendered its own fallback while looking like a token was
105
+ being honoured.
106
+ ⚠ AND THAT SENTENCE USED TO NAME THE TOKEN, WHICH BROKE THE GATE THAT READS THIS FILE. R17's
107
+ "every token the new stylesheet uses is DEFINED in the palette" scans the raw text, comments
108
+ included, so quoting `var(--…)` in prose counts as USING it: the citation reddened the check
109
+ [[prose-that-becomes-its-own-marker]]. Describe a token you are NOT using; never spell it. */
110
+
111
+ /* β›” NO HAIRLINE ON THE BAND ANY MORE. The card below has its own border, and a rule across the
112
+ pane above it made two edges 12px apart β€” the "still so ugly" the owner reported is mostly
113
+ this kind of doubling. What separates the composer from the transcript now is whitespace. */
114
+ .autoc-compose {
115
+ flex: 0 0 auto;
116
+ padding: 8px 24px 20px;
117
+ }
118
+ .autoc-field {
119
+ /* ONE measure for the conversation and the empty state, so the composer does not change width
120
+ when the first message lands. `.as-opening .as-composer` caps at the same 700px. */
121
+ max-width: 700px;
122
+ margin: 0 auto;
123
+ border: 1px solid var(--lp-line);
124
+ border-radius: 22px;
125
+ background: var(--lp-surface);
126
+ padding: 10px 8px 8px 16px;
127
+ box-shadow: 0 1px 2px rgba(20, 24, 40, 0.05);
128
+ box-sizing: border-box;
129
+ }
130
+ .autoc-field:focus-within { border-color: var(--lp-blue-solid); }
131
+
132
+ /* ⚠ `rows={1}` PLUS `max-height`, which is `.as-prompt`'s shape and not the two-row box that was
133
+ here. A composer that starts tall claims space before anybody has typed; the Assistant's grows
134
+ into the sentence instead. */
135
+ .autoc-input {
136
+ display: block;
137
+ width: 100%;
138
+ max-height: 180px;
139
+ border: 0;
140
+ outline: none;
141
+ padding: 0 8px 0 0;
142
+ background: transparent;
143
+ color: var(--lp-ink);
144
+ font: inherit;
145
+ font-size: var(--lp-fs-sm);
146
+ line-height: var(--lp-lh);
147
+ resize: none;
148
+ box-sizing: border-box;
149
+ }
150
+ .autoc-input::placeholder { color: var(--lp-muted); }
151
+
152
+ /* The row BELOW the input and INSIDE the card β€” the reference screenshot's arrangement, and the
153
+ slot W36-T34's model toggle drops into beside the send. */
154
+ .autoc-foot {
155
+ display: flex;
156
+ align-items: center;
157
+ gap: 12px;
158
+ margin-top: 8px;
159
+ }
160
+
161
+ .autoc-send {
162
+ flex: 0 0 auto;
163
+ margin-left: auto;
164
+ width: 30px;
165
+ height: 30px;
166
+ display: inline-flex;
167
+ align-items: center;
168
+ justify-content: center;
169
+ border: 0;
170
+ border-radius: 999px;
171
+ background: var(--lp-ink);
172
+ color: var(--lp-surface);
173
+ cursor: pointer;
174
+ }
175
+ .autoc-send svg {
176
+ fill: none;
177
+ stroke: currentColor;
178
+ stroke-width: 1.7;
179
+ stroke-linecap: round;
180
+ stroke-linejoin: round;
181
+ }
182
+ .autoc-send:disabled { background: var(--lp-surface-2); color: var(--lp-muted); cursor: default; }
183
+ .autoc-send:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 1px; }
184
+
185
+ /* ── the empty state (mirrors `.as-opening`) ──────────────────────────────── */
186
+
187
+ .autoc-opening {
188
+ flex: 1 1 auto;
189
+ min-height: 0;
190
+ display: flex;
191
+ flex-direction: column;
192
+ align-items: center;
193
+ justify-content: center;
194
+ padding: 24px;
195
+ box-sizing: border-box;
196
+ text-align: center;
197
+ }
198
+ .autoc-opening-h {
199
+ margin: 0 0 6px;
200
+ color: var(--lp-ink);
201
+ font-size: var(--lp-fs-lg);
202
+ font-weight: 650;
203
+ }
204
+ .autoc-opening-p {
205
+ max-width: 52ch;
206
+ margin: 0 0 20px;
207
+ color: var(--lp-muted);
208
+ font-size: var(--lp-fs-sm);
209
+ line-height: var(--lp-lh);
210
+ }
211
+ /* The composer is left-aligned inside a centred column, exactly as the Assistant's is: centred
212
+ placeholder text in a wide field reads as a search box, not as somewhere to write a sentence. */
213
+ .autoc-opening .autoc-field { width: 100%; text-align: left; }
214
+
215
+ /* The pending row. ⚠ It uses `.lp-spin`, the ONE loading mark app-wide (purple as of this wave's
216
+ T24) β€” a second spinner vocabulary in a new surface is how an app stops having one. */
217
+ .autoc-pending {
218
+ display: flex;
219
+ align-items: center;
220
+ gap: 8px;
221
+ align-self: flex-start;
222
+ color: var(--lp-muted);
223
+ font-size: var(--lp-fs-sm);
224
+ }
225
+
226
+ /* The accept bar. It is deliberately NOT inside the transcript: accepting is an act on the
227
+ AUTOMATION, not a reply in the conversation, and putting it in the log would make it scroll
228
+ away from the thing it acts on. */
229
+ .autoc-accept {
230
+ flex: 0 0 auto;
231
+ display: flex;
232
+ align-items: center;
233
+ gap: 10px;
234
+ padding: 10px 24px;
235
+ border-top: 1px solid var(--lp-line);
236
+ background: var(--lp-surface-2);
237
+ font-size: var(--lp-fs-sm);
238
+ }
239
+ .autoc-accept-note { color: var(--lp-muted); margin-right: auto; }
240
+
241
+ /* ── the run log's note disclosure (R21 / W34-T45) ────────────────────────── */
242
+
243
+ /* ⭐ WAVE 34 · W34-T45. `notes` is up to 300 chars x 25 entries per run and was rendered
244
+ unconditionally over 20 runs; that is the "too wordy" the owner reported. It is still
245
+ unconditional for a run that FAILED or hit a cap (R6: a limit must be REPORTED) and behind this
246
+ disclosure otherwise.
247
+ ⚠ The list INSIDE stays `.auto-run-notes`, which is C's existing rule in `index.css`. Only the
248
+ wrapper is new, so the notes themselves cannot start looking different depending on which
249
+ branch rendered them. */
250
+ .autor-notes {
251
+ margin: 2px 0 0;
252
+ }
253
+ .autor-notes-toggle {
254
+ cursor: pointer;
255
+ color: var(--lp-muted);
256
+ font-size: var(--lp-fs-2xs);
257
+ /* The default triangle is the affordance; no custom marker, because a disclosure that does not
258
+ look like one is how a person decides there is nothing behind it. */
259
+ list-style: revert;
260
+ }
261
+ .autor-notes-toggle:hover { color: var(--lp-ink); }
262
+ .autor-notes-toggle:focus-visible {
263
+ outline: 2px solid var(--lp-blue-deep);
264
+ outline-offset: 1px;
265
+ }
266
+
267
+ /* ── the parked statements batch (W35-T36 / owner ruling R10) ─────────────── */
268
+
269
+ /* ⭐⭐ "N STATEMENTS ARE READY", with the ONLY Send control in the product.
270
+ It sits above `.auto-work`, in the banner band, because it is the one thing on this agent that
271
+ needs a person β€” R10's whole shape is that the run assembles and PARKS, and somebody releases.
272
+
273
+ ⚠ IT IS DELIBERATELY NOT A WARNING COLOUR. A parked batch is the system working as designed, and
274
+ painting it amber would teach people to dismiss the panel that guards a real mail send. It is
275
+ the blue tint every other "here is something to look at" surface uses. */
276
+ .auto-batch {
277
+ flex: 0 0 auto;
278
+ margin: 12px 24px 0;
279
+ padding: 12px 14px;
280
+ border: 1px solid var(--lp-blue);
281
+ border-radius: var(--lp-r-md);
282
+ background: var(--lp-blue-tint);
283
+ font-size: var(--lp-fs-sm);
284
+ }
285
+ .auto-batch-head {
286
+ display: flex;
287
+ align-items: baseline;
288
+ flex-wrap: wrap;
289
+ gap: 4px 10px;
290
+ }
291
+ .auto-batch-count {
292
+ font-weight: 650;
293
+ color: var(--lp-ink);
294
+ }
295
+ .auto-batch-note { color: var(--lp-muted); }
296
+
297
+ /* The guardrail line. Same size as a note, because it IS one: the data layer decides, this
298
+ reports (R6's second sentence). */
299
+ .auto-batch-safe,
300
+ .auto-batch-line {
301
+ margin: 6px 0 0;
302
+ color: var(--lp-muted);
303
+ font-size: var(--lp-fs-xs);
304
+ line-height: 1.5;
305
+ max-width: 70ch;
306
+ }
307
+
308
+ /* Who is about to be emailed. ⚠ Bounded in the MARKUP at 8 rows with an "and N more" line rather
309
+ than scrolled here: a 200-row list inside a banner pushes the work area off the screen, and the
310
+ panel's job is to say who and how many, not to be the worklist. */
311
+ .auto-batch-list {
312
+ margin: 8px 0 0;
313
+ padding: 0;
314
+ list-style: none;
315
+ display: flex;
316
+ flex-direction: column;
317
+ gap: 2px;
318
+ font-size: var(--lp-fs-xs);
319
+ }
320
+ .auto-batch-list li {
321
+ display: flex;
322
+ gap: 10px;
323
+ align-items: baseline;
324
+ }
325
+ .auto-batch-cust { color: var(--lp-ink); }
326
+ .auto-batch-to { color: var(--lp-muted); overflow-wrap: anywhere; }
327
+ .auto-batch-more { color: var(--lp-muted); }
328
+
329
+ .auto-batch-actions {
330
+ margin-top: 10px;
331
+ display: flex;
332
+ gap: 8px;
333
+ }
334
+
335
+ /* ── W36-T44 (D-316 + D-299): the statements step's config panel ───────────── */
336
+
337
+ /* NEW rules only, in this module's own stylesheet. Every `auto-*` rule the panel reuses
338
+ (`auto-field`, `auto-input`, `auto-hint`, `auto-note`, `auto-btn`) still lives in the shared
339
+ `index.css` and is still another lane's, so nothing here redefines one. */
340
+
341
+ /* The two action rows (Preview, Send one test). A row rather than a bare button so the two read
342
+ as the same kind of control at the same left edge as every field above them. */
343
+ .autox-stmt-row {
344
+ display: flex;
345
+ gap: 8px;
346
+ margin: 0 0 14px;
347
+ }
348
+
349
+ .autox-stmt-shot {
350
+ margin: 0 0 14px;
351
+ border: 1px solid var(--lp-line);
352
+ border-radius: var(--lp-r-md);
353
+ padding: 10px 12px;
354
+ background: var(--lp-surface-2);
355
+ }
356
+ .autox-stmt-shot .auto-hint {
357
+ margin: 0 0 8px;
358
+ overflow-wrap: anywhere;
359
+ }
360
+
361
+ /* ⚠ A FIXED HEIGHT, AND IT SCROLLS INSIDE ITSELF. A statement for a customer with forty open
362
+ invoices is a long document, and a preview that grows to its content pushes the test-send
363
+ control below it off the panel: the one thing somebody must reach after reading a preview.
364
+
365
+ β›” AND THE LITERAL WHITE IS THE ONE DELIBERATE EXCEPTION TO THIS FILE'S "every colour is a
366
+ token" RULE, booked here rather than left to read as an oversight. What is inside this frame is
367
+ not our chrome, it is the EMAIL: `render_statement_html` hard-codes #1F4E78 headers, #e3e8ef
368
+ rules and near-black body text against an assumed white page, and the recipient's mail client
369
+ will paint it on white whatever this app's theme is. A surface token would go dark in dark mode
370
+ and render the real mail's dark text on a dark ground, so the preview would stop showing what
371
+ goes out at exactly the moment somebody is checking what goes out. */
372
+ .autox-stmt-frame {
373
+ display: block;
374
+ width: 100%;
375
+ height: 260px;
376
+ border: 1px solid var(--lp-line);
377
+ border-radius: var(--lp-r-sm);
378
+ background: #fff;
379
+ }
380
+
381
+ /* ── W36-T31 (owner item 3, R7/R8, contract C4): the Harness tab ───────────── */
382
+
383
+ /* NEW rules only. Everything shared (`auto-field`, `auto-input`, `auto-btn`, `auto-note`,
384
+ `auto-hint`, `auto-paneltab*`) still lives in `index.css` and is still another lane's. */
385
+
386
+ .autoh-wrap {
387
+ display: flex;
388
+ flex-direction: column;
389
+ gap: 4px;
390
+ }
391
+
392
+ .autoh-files {
393
+ margin: 0 0 14px;
394
+ padding: 0;
395
+ list-style: none;
396
+ display: flex;
397
+ flex-direction: column;
398
+ gap: 2px;
399
+ }
400
+ .autoh-file {
401
+ display: flex;
402
+ align-items: center;
403
+ gap: 6px;
404
+ border-radius: var(--lp-r-sm);
405
+ }
406
+ .autoh-file.is-on { background: var(--lp-blue-tint); }
407
+
408
+ /* The row is a BUTTON, so the whole line opens the file. A path that is only clickable on its
409
+ own glyph-width is a target people miss and then decide is not clickable at all. */
410
+ .autoh-open {
411
+ flex: 1 1 auto;
412
+ min-width: 0;
413
+ display: flex;
414
+ flex-direction: column;
415
+ gap: 1px;
416
+ padding: 5px 8px;
417
+ border: 0;
418
+ border-radius: var(--lp-r-sm);
419
+ background: transparent;
420
+ color: var(--lp-ink);
421
+ font: inherit;
422
+ text-align: left;
423
+ cursor: pointer;
424
+ }
425
+ .autoh-open:hover:not(:disabled) { background: var(--lp-surface-2); }
426
+ .autoh-open:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
427
+ .autoh-open:disabled { cursor: default; }
428
+
429
+ /* ⚠ `anywhere`, not `ellipsis`: a harness path is `skills/router.md`, and the half that
430
+ identifies it is the END. Truncating from the right hides exactly the distinguishing part. */
431
+ .autoh-path {
432
+ font-size: var(--lp-fs-sm);
433
+ font-weight: 600;
434
+ overflow-wrap: anywhere;
435
+ }
436
+ .autoh-meta {
437
+ color: var(--lp-muted);
438
+ font-size: var(--lp-fs-2xs);
439
+ overflow-wrap: anywhere;
440
+ }
441
+
442
+ /* Quiet until reached for. Deleting a file is a real act (it takes the history with it), so it is
443
+ present and honest rather than hidden, but it does not compete with opening one. */
444
+ .autoh-drop {
445
+ flex: 0 0 auto;
446
+ opacity: 0.55;
447
+ }
448
+ .autoh-file:hover .autoh-drop,
449
+ .autoh-drop:focus-visible { opacity: 1; }
450
+
451
+ .autoh-newrow {
452
+ display: flex;
453
+ gap: 6px;
454
+ align-items: center;
455
+ }
456
+
457
+ /* Monospace, because a harness file is a router or a skill: its indentation carries meaning and a
458
+ proportional font makes a misaligned block look aligned.
459
+ β›” THE FACE COMES FROM `.auto-input.is-mono`, WHICH THE TEXTAREA ALSO CARRIES, and this rule sets
460
+ no `font-family` at all. `index.css:12591` records why in as many words: there IS no `--lp-mono`
461
+ token, six sites spell the stack out, and a seventh copy here would put the product's mono face
462
+ in two places that can drift. `WebActionConfig` reaches for the same class. */
463
+ .autoh-body {
464
+ font-size: var(--lp-fs-xs);
465
+ line-height: 1.55;
466
+ resize: vertical;
467
+ }
468
+
469
+ .autoh-actions {
470
+ display: flex;
471
+ gap: 8px;
472
+ margin: 0 0 14px;
473
+ }
474
+
475
+ .autoh-history {
476
+ margin: 0 0 8px;
477
+ padding: 0;
478
+ list-style: none;
479
+ display: flex;
480
+ flex-direction: column;
481
+ gap: 1px;
482
+ }
483
+ .autoh-history li { border-radius: var(--lp-r-sm); }
484
+ .autoh-history li.is-on { background: var(--lp-blue-tint); }
485
+ .autoh-version {
486
+ width: 100%;
487
+ display: flex;
488
+ gap: 8px;
489
+ align-items: baseline;
490
+ padding: 4px 8px;
491
+ border: 0;
492
+ border-radius: var(--lp-r-sm);
493
+ background: transparent;
494
+ color: var(--lp-ink);
495
+ font: inherit;
496
+ text-align: left;
497
+ cursor: pointer;
498
+ }
499
+ .autoh-version:hover:not(:disabled) { background: var(--lp-surface-2); }
500
+ .autoh-version:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
501
+ .autoh-version:disabled { cursor: default; }
502
+ .autoh-vnum {
503
+ flex: 0 0 auto;
504
+ font-size: var(--lp-fs-xs);
505
+ font-weight: 650;
506
+ }
507
+
508
+ /* The unsaved-edit hold. A bordered block rather than a tint, because it is a QUESTION waiting on
509
+ an answer and the two buttons under it are the answer; a tinted note reads as commentary. */
510
+ .autoh-hold {
511
+ margin: 0 0 14px;
512
+ padding: 10px 12px;
513
+ border: 1px solid var(--lp-line);
514
+ border-radius: var(--lp-r-md);
515
+ background: var(--lp-surface-2);
516
+ }
517
+ .autoh-hold .auto-note { margin-top: 0; }
518
+
519
+ /* ── W36-T32 (owner item 3, R7): the right rail folds behind a "III" ───────── */
520
+
521
+ /* β›” THE FOLD SITS AT THE RAIL'S OWN LEFT EDGE, AND `flex-start` IS ONLY HALF OF WHY.
522
+ W35-T11 put the left rails' fold at their left edge; this rail is on the RIGHT, so its left
523
+ edge is the one facing the chat it widens. `.auto-panel-head` is `space-between` and lives in
524
+ `index.css` (another lane's), so this wrapper is what keeps the fold and the tabs together
525
+ instead of flung to the panel's two edges.
526
+ β›”β›” AND NOTHING IN HERE MAY EVER CARRY `margin-left: auto`. W35-T28's real finding was that a
527
+ sibling's auto margin ate the free space BEFORE `justify-content` applied, so one control sat
528
+ left on one database and right on another: one control, two positions, decided by data. */
529
+ .autod-head {
530
+ flex: 1 1 auto;
531
+ min-width: 0;
532
+ display: flex;
533
+ align-items: center;
534
+ justify-content: flex-start;
535
+ gap: 10px;
536
+ }
537
+
538
+ /* The collapsed rail. Same width token and the same idea as `.auto-rail.is-collapsed` on the
539
+ left of this screen: folding a rail leaves a strip, never a gap, because the strip is where the
540
+ way back lives. */
541
+ .autod-shut {
542
+ flex: 0 0 auto;
543
+ width: var(--lp-rail-min);
544
+ display: flex;
545
+ justify-content: center;
546
+ padding: 14px 6px 0;
547
+ border-left: 1px solid var(--lp-line);
548
+ background: var(--lp-surface);
549
+ }
550
+
551
+ /* β›” THE FOLD, IN ONE PLACE. Every `.auto-panel` in the work area goes at once β€” Properties (a
552
+ child of AutomationBuilder), Harness and Run history (children of AutomationDetail) β€” so a
553
+ panel added later folds without being told to. `display: none` also removes them from the
554
+ accessibility tree, which is the property `hidden` was giving us and the reason a `visibility`
555
+ or `width: 0` treatment would be a regression a screen reader would meet and nobody would see. */
556
+ .autod-folded .auto-panel { display: none; }
557
 
558
  /* ── W36-T34 (owner item 3, R4, contract C5): the model toggle ─────────────── */
559
 
web/src/connectors/brandMarks.tsx CHANGED
@@ -1,413 +1,413 @@
1
- // ---------------------------------------------------------------------------
2
- // connectors/brandMarks.tsx β€” WAVE 30, owner item 7 (rulings R3 + R4):
3
- // THE ONE PLACE A CONNECTOR'S IDENTITY IS DRAWN.
4
- //
5
- // The owner, verbatim and for the third time: *"their Instagram and Tiktok logo
6
- // to be fucking displayed, same with all logos under the Connectors module."*
7
- //
8
- // β›” THIS SUPERSEDES A RULE THAT WAS STILL SHIPPING. Wave-23 R8 said connector
9
- // identity is a two-letter monogram in the chip family, and it was enforced β€”
10
- // `verify_home.py:section_connectors` asserted a real mark could not appear.
11
- // R4 replaces it FOR CONNECTOR IDENTITY ONLY. Everything else the design
12
- // constitution says is untouched: no emojis anywhere, and no decorative
13
- // third-party imagery outside this file's purpose, which is telling a person
14
- // which company a row is about.
15
- //
16
- // β›”β›” WAVE 33 Β· OWNER ITEM 6 / RULING R4 β€” THE PARAGRAPH BELOW IS SUPERSEDED FOR
17
- // A COMPANY'S MARK, AND IT IS KEPT BECAUSE IT IS STILL RIGHT ABOUT WHAT IT WAS
18
- // ACTUALLY DEFENDING. It read:
19
- //
20
- // "INLINE SVG, NEVER A FILE AND NEVER A REMOTE URL. There is no `assets/` or
21
- // `icons/` directory in this app and there is not going to be one … A remote
22
- // logo would work today (no CSP header is set) and would be the one thing on
23
- // the page that can be taken away by somebody else's outage."
24
- //
25
- // ⭐ THE RULE IT WAS PROTECTING IS **NO THIRD-PARTY ORIGIN**, and that rule is
26
- // untouched: `/api/v1/brand/<name>` is OUR door, same-origin, session-gated,
27
- // served off bytes that ship inside the image (`web/public/brand/`). Nobody
28
- // else's outage can take it away, and there is still no `assets/` directory β€”
29
- // there is a brand directory, which is a different thing with a route in front
30
- // of it.
31
- // β›” WHAT DID CHANGE IS THE OWNER'S VERDICT ON THE ARTWORK, twice now. Wave 30's
32
- // R4 replaced wave 23's two-letter monogram with these hand-drawn marks; wave
33
- // 33's R4 replaces the hand-drawn marks with each vendor's OFFICIAL artwork,
34
- // because the honest sentence three paragraphs down β€” *"recognisable
35
- // SIMPLIFICATIONS … not the trademarked artwork"* β€” is exactly what the owner
36
- // saw: *"Do not generate your own logo for Connectors, they look really uncanny
37
- // /browse them the PNG, cut appropriately for our needs, verify visually."*
38
- // A ruling that supersedes a rule leaves that rule's gates green
39
- // ([[two-gates-can-assert-opposite-things]]); see `mailbox/G.md` G-2/G-3 for the
40
- // four legs in `verify_automation_ui` / `picker_render.test.tsx` this moves.
41
- //
42
- // ⚠ THE HAND-DRAWN SET IS NOT DELETED. Every arm below still exists and is what
43
- // renders when the door does not answer, so a 404, a 401 or a container without
44
- // the files degrades to the wave-30 mark rather than to a broken-image glyph.
45
- // Two of the arms are not fallbacks at all: `webhooks` and `scraper` are OURS,
46
- // there is no vendor artwork to fetch, and they stay inline permanently.
47
- //
48
- // β›” ONE MODULE FOR THREE SURFACES, and that is the whole design. The trigger
49
- // picker, the action menu and the Connectors directory all answer "which
50
- // company is this?" β€” three copies of a logo set is three chances to add a
51
- // platform in two places and forget the third, which is precisely the defect
52
- // wave 30 exists to fix on the server side of the same question.
53
- //
54
- // ⚠ WHAT THESE ARE, HONESTLY: recognisable SIMPLIFICATIONS drawn from each
55
- // brand's published silhouette and brand colour, at 16px, not the trademarked
56
- // artwork. That is the right call at this size β€” the real Google `G` is a
57
- // 500-byte path that renders as mush in a 15px box β€” and it is stated here so
58
- // nobody "upgrades" them by pasting a vendor's asset file into a repo that has
59
- // no place to put one.
60
- //
61
- // ⚠ THEME. Marks are brand-coloured and must survive BOTH themes, so no mark
62
- // relies on pure black or pure white for its silhouette: TikTok's note is
63
- // `currentColor` with its two brand offsets behind it, which is also how the
64
- // real mark is constructed.
65
- // ---------------------------------------------------------------------------
66
- import type { ReactElement } from "react";
67
- import { useId, useState } from "react";
68
-
69
- import { API_V1 } from "../apiContract";
70
-
71
- /**
72
- * The canonical brand names this module can draw. Deliberately NOT the same
73
- * strings as the connector keys or the trigger kinds: three vocabularies point
74
- * AT this one, and folding them together would make a rename in any of the
75
- * three a silent loss of an icon.
76
- */
77
- export type BrandName =
78
- | "instagram"
79
- | "tiktok"
80
- | "odoo"
81
- | "google"
82
- | "gmail"
83
- | "stripe"
84
- | "shopify"
85
- | "webhooks"
86
- | "scraper"
87
- | "slack"
88
- | "meta";
89
-
90
- /**
91
- * Trigger and action KIND -> brand.
92
- *
93
- * β›” KEYED ON THE KIND AND NOT ON THE CONNECTOR, and the reason is R3 itself:
94
- * after this wave Instagram and TikTok share `connector.key === "scraper"`, so
95
- * the connector can no longer tell them apart. The kind is the only thing that
96
- * still distinguishes the two products, which is exactly why the picker's own
97
- * `TriggerMark` has always been keyed this way.
98
- *
99
- * ⚠ An unmapped kind returns null and the caller draws its existing glyph β€” a
100
- * trigger the engine adds tomorrow renders plainly rather than not at all.
101
- */
102
- export const BRAND_OF_KIND: Record<string, BrandName> = {
103
- ig_profile_match: "instagram",
104
- tiktok_profile_match: "tiktok",
105
- enrich_instagram: "instagram",
106
- enrich_tiktok: "tiktok",
107
- field_instagram: "instagram",
108
- };
109
-
110
- /**
111
- * Connector/provider KEY -> brand, for the Connectors directory and for the
112
- * collapsed connector nests in both automation menus.
113
- *
114
- * ⚠ `scraper` and `webhooks` are OURS, not brands β€” they get house glyphs in
115
- * `currentColor` so they sit in the chip family the way they always have. They
116
- * are in this map rather than special-cased at the call site so that "what mark
117
- * does this row wear" has ONE answer, whoever is asking.
118
- */
119
- export const BRAND_OF_CONNECTOR: Record<string, BrandName> = {
120
- odoo: "odoo",
121
- // β›”β›” WAVE 32 Β· OWNER ITEM 12 / R6 β€” THESE TWO MARKS ARE CURRENTLY UNREACHABLE, AND KEPT.
122
- // `oauth_connect.offered("google")` is False, so the directory serves no `google` row and this
123
- // map is never asked for either of these. They stay for the reason the ruling is worded as
124
- // *"HIDDEN until they are real"* rather than "removed": the blocker is money, not code (D-45 β€”
125
- // Google's CASA verification, ~$540–1,800/yr, for the `gmail.readonly` scope). The day that is
126
- // paid for, ONE key flips server-side and the card comes back wearing its own logo. Deleting
127
- // the art would turn a one-key restore into a re-draw, and would leave the next reader
128
- // wondering where Gmail's mark went as well as where Gmail went.
129
- google: "google",
130
- gmail: "gmail",
131
- stripe: "stripe",
132
- shopify: "shopify",
133
- scraper: "scraper",
134
- webhooks: "webhooks",
135
- instagram: "instagram",
136
- tiktok: "tiktok",
137
- // ⭐ WAVE 31 Β· R7 β€” the Nango breadth play's first two marks. `meta_ads` is the KEYCHAIN
138
- // connector (a token an admin pastes today); `meta` would be the delegated-OAuth door the same
139
- // company owns, so BOTH keys point at one mark rather than the map growing a near-duplicate.
140
- slack: "slack",
141
- meta: "meta",
142
- meta_ads: "meta",
143
- };
144
-
145
- /** The house frame every mark is drawn in. 16Γ—16 user units, sized by the caller. */
146
- function frame(size: number) {
147
- return { width: size, height: size, viewBox: "0 0 16 16", "aria-hidden": true } as const;
148
- }
149
-
150
- /**
151
- * ⚠ TIKTOK'S NOTE, DRAWN THREE TIMES. The real mark is one glyph offset in
152
- * cyan and magenta behind a solid copy; drawing only the solid copy loses the
153
- * brand entirely at this size, and drawing the offsets in black loses it in
154
- * dark mode. The solid copy is `currentColor` so it inherits the row.
155
- */
156
- const TT_NOTE =
157
- "M9.05 1.9h2.02c.13 1.2.87 2.13 2.03 2.3v2.03c-.78 0-1.53-.2-2.18-.58v3.98"
158
- + "a3.62 3.62 0 1 1-3.62-3.62c.16 0 .32.01.48.03v2.06a1.6 1.6 0 1 0 1.27 1.56z";
159
-
160
- /**
161
- * Brands we hold OFFICIAL artwork for, i.e. the ones `/api/v1/brand/<name>`
162
- * answers 200 on. β›” Derived from one place β€” the server's own directory listing
163
- * would be a round trip on every chip, and a hardcoded list here would drift the
164
- * moment a file is added, so `verify_meta::section_brand_door` pins this set
165
- * against the files on disk in BOTH directions. Adding a mark is: drop the PNG
166
- * in `web/public/brand/`, add its SOURCES.md row, add the key here.
167
- *
168
- * ⚠ `webhooks` and `scraper` are ABSENT ON PURPOSE and must stay absent: they are
169
- * house glyphs in `currentColor`, there is no vendor and no artwork to fetch, and
170
- * asking the door for one would be a guaranteed 404 on every render.
171
- */
172
- const OFFICIAL: ReadonlySet<BrandName> = new Set<BrandName>([
173
- "instagram", "tiktok", "odoo", "google", "gmail", "slack", "meta",
174
- "stripe", "shopify",
175
- ]);
176
-
177
- /** The door R4 mandates. Relative, so it is same-origin by construction β€” the
178
- * one property the superseded "never a remote URL" rule was really protecting. */
179
- export function brandSrc(name: BrandName): string {
180
- return `${API_V1}/brand/${name}`;
181
- }
182
-
183
- export function BrandMark({
184
- name,
185
- size = 15,
186
- }: {
187
- name: BrandName;
188
- size?: number;
189
- }): ReactElement | null {
190
- const f = frame(size);
191
- // ⭐⭐ WAVE 33 Β· R4 β€” THE OFFICIAL MARK, FROM OUR OWN DOOR, WITH THE WAVE-30 ART
192
- // BEHIND IT. `useState` rather than a bare `<img>` because a door that cannot
193
- // answer must degrade to a mark and never to a browser's broken-image glyph β€”
194
- // which is the one outcome worse than the hand-drawn logo the owner complained
195
- // about. `onError` fires for a 404, a 401 after a session expires, and a
196
- // container built without `web/public/brand/`, and each of those falls through
197
- // to the arms below.
198
- // ⚠ Hooks run for EVERY name, including the two house glyphs, because a hook
199
- // cannot sit behind a conditional return β€” same reason `useId` is unconditional.
200
- const [failed, setFailed] = useState(false);
201
- // Per-instance, for the reason spelled out at the `<defs>` below. It must also run BEFORE
202
- // the official-image return: `failed` flips on `onError`, and a hook first reached on that
203
- // re-render is one more hook than the previous render β€” React #310 on the exact fallback
204
- // path this component exists to provide.
205
- const gradId = `aios-brand-ig-${useId()}`;
206
- if (OFFICIAL.has(name) && !failed)
207
- return (
208
- <img
209
- src={brandSrc(name)}
210
- width={size}
211
- height={size}
212
- alt=""
213
- aria-hidden="true"
214
- // ⚠ `block` kills the inline-baseline gap that would make a 15px logo sit
215
- // a pixel lower than the 15px SVG beside it in the same chip row.
216
- style={{ display: "block", width: size, height: size }}
217
- onError={() => setFailed(true)}
218
- />
219
- );
220
- if (name === "instagram")
221
- return (
222
- <svg {...f} fill="none">
223
- {/*
224
- β›”β›” THE GRADIENT ID IS PER-INSTANCE, AND THE FIXED ONE WAS A REAL BUG β€” FOUND BY A
225
- PICTURE, NOT BY A GATE. It shipped for an hour as the constant `aios-brand-ig`, on the
226
- reasoning that duplicate ids resolve to the FIRST definition and every definition is
227
- byte-identical, so it cannot matter. MEASURED in the connectors shot: the Scraper card
228
- holds an Instagram mark inside a COLLAPSED `<details>`, a second card below holds a
229
- visible one β€” and the visible one painted NOTHING. A closed `<details>` is
230
- `content-visibility: hidden`, its subtree is not rendered, and a paint server defined
231
- inside a skipped subtree does not resolve for a user outside it. "The first definition
232
- wins" IS the failure: whichever copy happens to be hidden decides for all of them.
233
- ⚠ Nothing about `<details>` is special β€” `display:none` does the same. Any page holding
234
- two of this mark with the first one hidden loses the second.
235
- ⚠ `useId` rather than a module counter, so the markup stays DETERMINISTIC for a given
236
- tree β€” the render gates could not assert against a random id β€” and stable across a
237
- server render and its hydration.
238
- ⚠ Every check that looks for this mark matches the PREFIX `url(#aios-brand-ig`.
239
- */}
240
- <defs>
241
- {/* ⚠ `userSpaceOnUse` IS LOAD-BEARING AND ITS ABSENCE LOOKED FINE. The default is
242
- `objectBoundingBox`, where the coordinates are FRACTIONS of the shape's box β€” so
243
- `1,15 β†’ 15,1` put the whole gradient vector far outside every path and each one
244
- painted a single clamped stop. The mark still rendered, still read as Instagram,
245
- and was simply flat pink: a defect only a picture catches, which is why one was
246
- taken ([[ui-invisible-to-assertions]]). In user space the numbers mean viewBox
247
- units, which is what they were written as. */}
248
- <linearGradient
249
- id={gradId} gradientUnits="userSpaceOnUse"
250
- x1="2" y1="14" x2="14" y2="2"
251
- >
252
- <stop offset="0" stopColor="#FEDA75" />
253
- <stop offset="0.32" stopColor="#FA7E1E" />
254
- <stop offset="0.62" stopColor="#D62976" />
255
- <stop offset="1" stopColor="#962FBF" />
256
- </linearGradient>
257
- </defs>
258
- <rect
259
- x="1.7" y="1.7" width="12.6" height="12.6" rx="3.7"
260
- stroke={`url(#${gradId})`} strokeWidth="1.5"
261
- />
262
- <circle cx="8" cy="8" r="3" stroke={`url(#${gradId})`} strokeWidth="1.5" />
263
- <circle cx="11.6" cy="4.4" r="0.95" fill={`url(#${gradId})`} />
264
- </svg>
265
- );
266
- if (name === "tiktok")
267
- return (
268
- <svg {...f}>
269
- <path d={TT_NOTE} fill="#25F4EE" transform="translate(-0.9 -0.5)" />
270
- <path d={TT_NOTE} fill="#FE2C55" transform="translate(0.9 0.5)" />
271
- <path d={TT_NOTE} fill="currentColor" />
272
- </svg>
273
- );
274
- if (name === "odoo")
275
- return (
276
- <svg {...f}>
277
- {/* Odoo's brand purple, and its wordmark's twin `o`s β€” the part of that
278
- wordmark that survives being shrunk to 15px. */}
279
- <rect x="1" y="1" width="14" height="14" rx="3.4" fill="#714B67" />
280
- <circle cx="5.7" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
281
- <circle cx="10.4" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
282
- </svg>
283
- );
284
- if (name === "google")
285
- return (
286
- <svg {...f} fill="none" strokeWidth="2.3">
287
- {/* The four-arc G. Each arc is one brand colour, and the bar into the
288
- centre is what makes it a G rather than a ring. */}
289
- <path d="M4.46 4.46A5 5 0 0 1 11.54 4.46" stroke="#EA4335" strokeLinecap="round" />
290
- <path d="M4.46 4.46A5 5 0 0 0 4.46 11.54" stroke="#FBBC05" strokeLinecap="round" />
291
- <path d="M4.46 11.54A5 5 0 0 0 11.54 11.54" stroke="#34A853" strokeLinecap="round" />
292
- <path d="M11.54 11.54A5 5 0 0 0 13 8" stroke="#4285F4" strokeLinecap="round" />
293
- <path d="M13 8H8.4" stroke="#4285F4" />
294
- </svg>
295
- );
296
- if (name === "gmail")
297
- return (
298
- <svg {...f} fill="none" stroke="#EA4335" strokeWidth="1.5" strokeLinejoin="round">
299
- <rect x="1.6" y="3.6" width="12.8" height="9" rx="1.6" />
300
- <path d="m2 4.4 6 4.6 6-4.6" />
301
- </svg>
302
- );
303
- // ⭐ WAVE 31 · R7. Slack's mark is FOUR bars in four brand colours, drawn as rounded rects
304
- // rather than the true interlocking glyph: at 15px the real lozenges collapse into mud, and a
305
- // mark nobody can identify is worse than a two-letter tile. Colours are Slack's own.
306
- if (name === "slack")
307
- return (
308
- <svg {...f}>
309
- <rect x="2" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#36C5F0" />
310
- <rect x="8.6" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#2EB67D" />
311
- <rect x="6.6" y="2" width="2.8" height="5.4" rx="1.4" fill="#ECB22E" />
312
- <rect x="6.6" y="8.6" width="2.8" height="5.4" rx="1.4" fill="#E01E5A" />
313
- </svg>
314
- );
315
- // Meta's infinity loop, as two overlapping strokes in the brand blue. ⚠ `fill="none"` with a
316
- // round cap: filled, the two lobes merge into a blob at this size.
317
- if (name === "meta")
318
- return (
319
- <svg {...f} fill="none">
320
- <path
321
- d="M2.2 10.4c0-3 1.5-5.2 3.3-5.2 1.2 0 2 .8 3 2.4l1 1.6c.9 1.4 1.5 2.1 2.2 2.1.8 0
322
- 1.3-.8 1.3-2.1 0-1.6-.7-3.4-2-3.4-.9 0-1.7.7-2.6 2"
323
- stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
324
- />
325
- <path
326
- d="M2.2 10.4c0 1.3.6 2 1.5 2 .8 0 1.4-.5 2.5-2.2l3-4.6"
327
- stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
328
- />
329
- </svg>
330
- );
331
- if (name === "stripe")
332
- return (
333
- <svg {...f}>
334
- <rect x="1" y="1" width="14" height="14" rx="3.4" fill="#635BFF" />
335
- <path
336
- d="M10.5 5.6a2.3 2.3 0 0 0-3.6 1.2c0 2.1 4.1 1.5 4.1 3.5a2.4 2.4 0 0 1-3.7 1.3"
337
- fill="none" stroke="#FFFFFF" strokeWidth="1.5" strokeLinecap="round"
338
- />
339
- </svg>
340
- );
341
- if (name === "shopify")
342
- return (
343
- <svg {...f}>
344
- {/* The bag, in Shopify's two greens: the darker one is the handle, which
345
- is the part that reads as a bag rather than as a box. */}
346
- <path d="M3.5 5.2h9l-.75 8.4a.9.9 0 0 1-.9.8H5.15a.9.9 0 0 1-.9-.8z" fill="#95BF47" />
347
- <path
348
- d="M6.1 6.4V4.5a1.9 1.9 0 0 1 3.8 0v1.9"
349
- fill="none" stroke="#5E8E3E" strokeWidth="1.4" strokeLinecap="round"
350
- />
351
- </svg>
352
- );
353
- /*
354
- ⚠ THE LAST TWO ARE OURS, NOT BRANDS β€” `currentColor`, house stroke weight,
355
- so they sit in the chip family beside the coloured logos rather than
356
- pretending to be a company. Keeping them here is what lets every caller ask
357
- one question instead of two.
358
- */
359
- if (name === "webhooks")
360
- return (
361
- <svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
362
- strokeLinecap="round" strokeLinejoin="round">
363
- <path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
364
- <path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
365
- <path d="M6.2 8h3.6" />
366
- </svg>
367
- );
368
- if (name === "scraper")
369
- return (
370
- <svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
371
- strokeLinecap="round" strokeLinejoin="round">
372
- {/* A magnifier over a grid of rows: it reads a catalogue of profiles and
373
- makes records out of what matches β€” which is what the bucket does,
374
- and it is deliberately NOT either platform's mark, because the whole
375
- point of R3 is that the bucket is neither one of them. */}
376
- <path d="M2.6 3.4h10.8M2.6 6.2h5.2M2.6 9h3.4" />
377
- <circle cx="10.4" cy="10.2" r="3" />
378
- <path d="m12.6 12.4 1.6 1.6" />
379
- </svg>
380
- );
381
- return null;
382
- }
383
-
384
- /**
385
- * Does this kind wear a LOGO rather than a house glyph?
386
- *
387
- * β›” IT EXISTS BECAUSE THE TILE HAS TO CHANGE TOO, and forgetting that would have shipped the
388
- * defect quietly: `.autox-card-mark` paints a blue tint and sets `color: var(--lp-blue-deep)`,
389
- * so TikTok's note β€” which is `currentColor` by design, so it survives dark mode β€” would have
390
- * rendered BLUE, and Instagram's gradient would have sat on a coloured chip. The caller adds
391
- * `is-brand`, which neutralises both. One predicate, so the mark and its tile cannot disagree
392
- * about whether a row is branded.
393
- */
394
- export function hasBrandKind(kind: string): boolean {
395
- return Boolean(BRAND_OF_KIND[kind]);
396
- }
397
-
398
- /** The connector-key twin of `hasBrandKind`, for the directory's tiles. */
399
- export function hasBrandConnector(key: string): boolean {
400
- return Boolean(BRAND_OF_CONNECTOR[key]);
401
- }
402
-
403
- /** The mark for a trigger or action KIND, or null when it is not a branded one. */
404
- export function brandForKind(kind: string, size = 15): ReactElement | null {
405
- const name = BRAND_OF_KIND[kind];
406
- return name ? <BrandMark name={name} size={size} /> : null;
407
- }
408
-
409
- /** The mark for a connector/provider KEY, or null when we have no logo for it. */
410
- export function brandForConnector(key: string, size = 15): ReactElement | null {
411
- const name = BRAND_OF_CONNECTOR[key];
412
- return name ? <BrandMark name={name} size={size} /> : null;
413
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // connectors/brandMarks.tsx β€” WAVE 30, owner item 7 (rulings R3 + R4):
3
+ // THE ONE PLACE A CONNECTOR'S IDENTITY IS DRAWN.
4
+ //
5
+ // The owner, verbatim and for the third time: *"their Instagram and Tiktok logo
6
+ // to be fucking displayed, same with all logos under the Connectors module."*
7
+ //
8
+ // β›” THIS SUPERSEDES A RULE THAT WAS STILL SHIPPING. Wave-23 R8 said connector
9
+ // identity is a two-letter monogram in the chip family, and it was enforced β€”
10
+ // `verify_home.py:section_connectors` asserted a real mark could not appear.
11
+ // R4 replaces it FOR CONNECTOR IDENTITY ONLY. Everything else the design
12
+ // constitution says is untouched: no emojis anywhere, and no decorative
13
+ // third-party imagery outside this file's purpose, which is telling a person
14
+ // which company a row is about.
15
+ //
16
+ // β›”β›” WAVE 33 Β· OWNER ITEM 6 / RULING R4 β€” THE PARAGRAPH BELOW IS SUPERSEDED FOR
17
+ // A COMPANY'S MARK, AND IT IS KEPT BECAUSE IT IS STILL RIGHT ABOUT WHAT IT WAS
18
+ // ACTUALLY DEFENDING. It read:
19
+ //
20
+ // "INLINE SVG, NEVER A FILE AND NEVER A REMOTE URL. There is no `assets/` or
21
+ // `icons/` directory in this app and there is not going to be one … A remote
22
+ // logo would work today (no CSP header is set) and would be the one thing on
23
+ // the page that can be taken away by somebody else's outage."
24
+ //
25
+ // ⭐ THE RULE IT WAS PROTECTING IS **NO THIRD-PARTY ORIGIN**, and that rule is
26
+ // untouched: `/api/v1/brand/<name>` is OUR door, same-origin, session-gated,
27
+ // served off bytes that ship inside the image (`web/public/brand/`). Nobody
28
+ // else's outage can take it away, and there is still no `assets/` directory β€”
29
+ // there is a brand directory, which is a different thing with a route in front
30
+ // of it.
31
+ // β›” WHAT DID CHANGE IS THE OWNER'S VERDICT ON THE ARTWORK, twice now. Wave 30's
32
+ // R4 replaced wave 23's two-letter monogram with these hand-drawn marks; wave
33
+ // 33's R4 replaces the hand-drawn marks with each vendor's OFFICIAL artwork,
34
+ // because the honest sentence three paragraphs down β€” *"recognisable
35
+ // SIMPLIFICATIONS … not the trademarked artwork"* β€” is exactly what the owner
36
+ // saw: *"Do not generate your own logo for Connectors, they look really uncanny
37
+ // /browse them the PNG, cut appropriately for our needs, verify visually."*
38
+ // A ruling that supersedes a rule leaves that rule's gates green
39
+ // ([[two-gates-can-assert-opposite-things]]); see `mailbox/G.md` G-2/G-3 for the
40
+ // four legs in `verify_automation_ui` / `picker_render.test.tsx` this moves.
41
+ //
42
+ // ⚠ THE HAND-DRAWN SET IS NOT DELETED. Every arm below still exists and is what
43
+ // renders when the door does not answer, so a 404, a 401 or a container without
44
+ // the files degrades to the wave-30 mark rather than to a broken-image glyph.
45
+ // Two of the arms are not fallbacks at all: `webhooks` and `scraper` are OURS,
46
+ // there is no vendor artwork to fetch, and they stay inline permanently.
47
+ //
48
+ // β›” ONE MODULE FOR THREE SURFACES, and that is the whole design. The trigger
49
+ // picker, the action menu and the Connectors directory all answer "which
50
+ // company is this?" β€” three copies of a logo set is three chances to add a
51
+ // platform in two places and forget the third, which is precisely the defect
52
+ // wave 30 exists to fix on the server side of the same question.
53
+ //
54
+ // ⚠ WHAT THESE ARE, HONESTLY: recognisable SIMPLIFICATIONS drawn from each
55
+ // brand's published silhouette and brand colour, at 16px, not the trademarked
56
+ // artwork. That is the right call at this size β€” the real Google `G` is a
57
+ // 500-byte path that renders as mush in a 15px box β€” and it is stated here so
58
+ // nobody "upgrades" them by pasting a vendor's asset file into a repo that has
59
+ // no place to put one.
60
+ //
61
+ // ⚠ THEME. Marks are brand-coloured and must survive BOTH themes, so no mark
62
+ // relies on pure black or pure white for its silhouette: TikTok's note is
63
+ // `currentColor` with its two brand offsets behind it, which is also how the
64
+ // real mark is constructed.
65
+ // ---------------------------------------------------------------------------
66
+ import type { ReactElement } from "react";
67
+ import { useId, useState } from "react";
68
+
69
+ import { API_V1 } from "../apiContract";
70
+
71
+ /**
72
+ * The canonical brand names this module can draw. Deliberately NOT the same
73
+ * strings as the connector keys or the trigger kinds: three vocabularies point
74
+ * AT this one, and folding them together would make a rename in any of the
75
+ * three a silent loss of an icon.
76
+ */
77
+ export type BrandName =
78
+ | "instagram"
79
+ | "tiktok"
80
+ | "odoo"
81
+ | "google"
82
+ | "gmail"
83
+ | "stripe"
84
+ | "shopify"
85
+ | "webhooks"
86
+ | "scraper"
87
+ | "slack"
88
+ | "meta";
89
+
90
+ /**
91
+ * Trigger and action KIND -> brand.
92
+ *
93
+ * β›” KEYED ON THE KIND AND NOT ON THE CONNECTOR, and the reason is R3 itself:
94
+ * after this wave Instagram and TikTok share `connector.key === "scraper"`, so
95
+ * the connector can no longer tell them apart. The kind is the only thing that
96
+ * still distinguishes the two products, which is exactly why the picker's own
97
+ * `TriggerMark` has always been keyed this way.
98
+ *
99
+ * ⚠ An unmapped kind returns null and the caller draws its existing glyph β€” a
100
+ * trigger the engine adds tomorrow renders plainly rather than not at all.
101
+ */
102
+ export const BRAND_OF_KIND: Record<string, BrandName> = {
103
+ ig_profile_match: "instagram",
104
+ tiktok_profile_match: "tiktok",
105
+ enrich_instagram: "instagram",
106
+ enrich_tiktok: "tiktok",
107
+ field_instagram: "instagram",
108
+ };
109
+
110
+ /**
111
+ * Connector/provider KEY -> brand, for the Connectors directory and for the
112
+ * collapsed connector nests in both automation menus.
113
+ *
114
+ * ⚠ `scraper` and `webhooks` are OURS, not brands β€” they get house glyphs in
115
+ * `currentColor` so they sit in the chip family the way they always have. They
116
+ * are in this map rather than special-cased at the call site so that "what mark
117
+ * does this row wear" has ONE answer, whoever is asking.
118
+ */
119
+ export const BRAND_OF_CONNECTOR: Record<string, BrandName> = {
120
+ odoo: "odoo",
121
+ // β›”β›” WAVE 32 Β· OWNER ITEM 12 / R6 β€” THESE TWO MARKS ARE CURRENTLY UNREACHABLE, AND KEPT.
122
+ // `oauth_connect.offered("google")` is False, so the directory serves no `google` row and this
123
+ // map is never asked for either of these. They stay for the reason the ruling is worded as
124
+ // *"HIDDEN until they are real"* rather than "removed": the blocker is money, not code (D-45 β€”
125
+ // Google's CASA verification, ~$540–1,800/yr, for the `gmail.readonly` scope). The day that is
126
+ // paid for, ONE key flips server-side and the card comes back wearing its own logo. Deleting
127
+ // the art would turn a one-key restore into a re-draw, and would leave the next reader
128
+ // wondering where Gmail's mark went as well as where Gmail went.
129
+ google: "google",
130
+ gmail: "gmail",
131
+ stripe: "stripe",
132
+ shopify: "shopify",
133
+ scraper: "scraper",
134
+ webhooks: "webhooks",
135
+ instagram: "instagram",
136
+ tiktok: "tiktok",
137
+ // ⭐ WAVE 31 Β· R7 β€” the Nango breadth play's first two marks. `meta_ads` is the KEYCHAIN
138
+ // connector (a token an admin pastes today); `meta` would be the delegated-OAuth door the same
139
+ // company owns, so BOTH keys point at one mark rather than the map growing a near-duplicate.
140
+ slack: "slack",
141
+ meta: "meta",
142
+ meta_ads: "meta",
143
+ };
144
+
145
+ /** The house frame every mark is drawn in. 16Γ—16 user units, sized by the caller. */
146
+ function frame(size: number) {
147
+ return { width: size, height: size, viewBox: "0 0 16 16", "aria-hidden": true } as const;
148
+ }
149
+
150
+ /**
151
+ * ⚠ TIKTOK'S NOTE, DRAWN THREE TIMES. The real mark is one glyph offset in
152
+ * cyan and magenta behind a solid copy; drawing only the solid copy loses the
153
+ * brand entirely at this size, and drawing the offsets in black loses it in
154
+ * dark mode. The solid copy is `currentColor` so it inherits the row.
155
+ */
156
+ const TT_NOTE =
157
+ "M9.05 1.9h2.02c.13 1.2.87 2.13 2.03 2.3v2.03c-.78 0-1.53-.2-2.18-.58v3.98"
158
+ + "a3.62 3.62 0 1 1-3.62-3.62c.16 0 .32.01.48.03v2.06a1.6 1.6 0 1 0 1.27 1.56z";
159
+
160
+ /**
161
+ * Brands we hold OFFICIAL artwork for, i.e. the ones `/api/v1/brand/<name>`
162
+ * answers 200 on. β›” Derived from one place β€” the server's own directory listing
163
+ * would be a round trip on every chip, and a hardcoded list here would drift the
164
+ * moment a file is added, so `verify_meta::section_brand_door` pins this set
165
+ * against the files on disk in BOTH directions. Adding a mark is: drop the PNG
166
+ * in `web/public/brand/`, add its SOURCES.md row, add the key here.
167
+ *
168
+ * ⚠ `webhooks` and `scraper` are ABSENT ON PURPOSE and must stay absent: they are
169
+ * house glyphs in `currentColor`, there is no vendor and no artwork to fetch, and
170
+ * asking the door for one would be a guaranteed 404 on every render.
171
+ */
172
+ const OFFICIAL: ReadonlySet<BrandName> = new Set<BrandName>([
173
+ "instagram", "tiktok", "odoo", "google", "gmail", "slack", "meta",
174
+ "stripe", "shopify",
175
+ ]);
176
+
177
+ /** The door R4 mandates. Relative, so it is same-origin by construction β€” the
178
+ * one property the superseded "never a remote URL" rule was really protecting. */
179
+ export function brandSrc(name: BrandName): string {
180
+ return `${API_V1}/brand/${name}`;
181
+ }
182
+
183
+ export function BrandMark({
184
+ name,
185
+ size = 15,
186
+ }: {
187
+ name: BrandName;
188
+ size?: number;
189
+ }): ReactElement | null {
190
+ const f = frame(size);
191
+ // ⭐⭐ WAVE 33 Β· R4 β€” THE OFFICIAL MARK, FROM OUR OWN DOOR, WITH THE WAVE-30 ART
192
+ // BEHIND IT. `useState` rather than a bare `<img>` because a door that cannot
193
+ // answer must degrade to a mark and never to a browser's broken-image glyph β€”
194
+ // which is the one outcome worse than the hand-drawn logo the owner complained
195
+ // about. `onError` fires for a 404, a 401 after a session expires, and a
196
+ // container built without `web/public/brand/`, and each of those falls through
197
+ // to the arms below.
198
+ // ⚠ Hooks run for EVERY name, including the two house glyphs, because a hook
199
+ // cannot sit behind a conditional return β€” same reason `useId` is unconditional.
200
+ const [failed, setFailed] = useState(false);
201
+ // Per-instance, for the reason spelled out at the `<defs>` below. It must also run BEFORE
202
+ // the official-image return: `failed` flips on `onError`, and a hook first reached on that
203
+ // re-render is one more hook than the previous render β€” React #310 on the exact fallback
204
+ // path this component exists to provide.
205
+ const gradId = `aios-brand-ig-${useId()}`;
206
+ if (OFFICIAL.has(name) && !failed)
207
+ return (
208
+ <img
209
+ src={brandSrc(name)}
210
+ width={size}
211
+ height={size}
212
+ alt=""
213
+ aria-hidden="true"
214
+ // ⚠ `block` kills the inline-baseline gap that would make a 15px logo sit
215
+ // a pixel lower than the 15px SVG beside it in the same chip row.
216
+ style={{ display: "block", width: size, height: size }}
217
+ onError={() => setFailed(true)}
218
+ />
219
+ );
220
+ if (name === "instagram")
221
+ return (
222
+ <svg {...f} fill="none">
223
+ {/*
224
+ β›”β›” THE GRADIENT ID IS PER-INSTANCE, AND THE FIXED ONE WAS A REAL BUG β€” FOUND BY A
225
+ PICTURE, NOT BY A GATE. It shipped for an hour as the constant `aios-brand-ig`, on the
226
+ reasoning that duplicate ids resolve to the FIRST definition and every definition is
227
+ byte-identical, so it cannot matter. MEASURED in the connectors shot: the Scraper card
228
+ holds an Instagram mark inside a COLLAPSED `<details>`, a second card below holds a
229
+ visible one β€” and the visible one painted NOTHING. A closed `<details>` is
230
+ `content-visibility: hidden`, its subtree is not rendered, and a paint server defined
231
+ inside a skipped subtree does not resolve for a user outside it. "The first definition
232
+ wins" IS the failure: whichever copy happens to be hidden decides for all of them.
233
+ ⚠ Nothing about `<details>` is special β€” `display:none` does the same. Any page holding
234
+ two of this mark with the first one hidden loses the second.
235
+ ⚠ `useId` rather than a module counter, so the markup stays DETERMINISTIC for a given
236
+ tree β€” the render gates could not assert against a random id β€” and stable across a
237
+ server render and its hydration.
238
+ ⚠ Every check that looks for this mark matches the PREFIX `url(#aios-brand-ig`.
239
+ */}
240
+ <defs>
241
+ {/* ⚠ `userSpaceOnUse` IS LOAD-BEARING AND ITS ABSENCE LOOKED FINE. The default is
242
+ `objectBoundingBox`, where the coordinates are FRACTIONS of the shape's box β€” so
243
+ `1,15 β†’ 15,1` put the whole gradient vector far outside every path and each one
244
+ painted a single clamped stop. The mark still rendered, still read as Instagram,
245
+ and was simply flat pink: a defect only a picture catches, which is why one was
246
+ taken ([[ui-invisible-to-assertions]]). In user space the numbers mean viewBox
247
+ units, which is what they were written as. */}
248
+ <linearGradient
249
+ id={gradId} gradientUnits="userSpaceOnUse"
250
+ x1="2" y1="14" x2="14" y2="2"
251
+ >
252
+ <stop offset="0" stopColor="#FEDA75" />
253
+ <stop offset="0.32" stopColor="#FA7E1E" />
254
+ <stop offset="0.62" stopColor="#D62976" />
255
+ <stop offset="1" stopColor="#962FBF" />
256
+ </linearGradient>
257
+ </defs>
258
+ <rect
259
+ x="1.7" y="1.7" width="12.6" height="12.6" rx="3.7"
260
+ stroke={`url(#${gradId})`} strokeWidth="1.5"
261
+ />
262
+ <circle cx="8" cy="8" r="3" stroke={`url(#${gradId})`} strokeWidth="1.5" />
263
+ <circle cx="11.6" cy="4.4" r="0.95" fill={`url(#${gradId})`} />
264
+ </svg>
265
+ );
266
+ if (name === "tiktok")
267
+ return (
268
+ <svg {...f}>
269
+ <path d={TT_NOTE} fill="#25F4EE" transform="translate(-0.9 -0.5)" />
270
+ <path d={TT_NOTE} fill="#FE2C55" transform="translate(0.9 0.5)" />
271
+ <path d={TT_NOTE} fill="currentColor" />
272
+ </svg>
273
+ );
274
+ if (name === "odoo")
275
+ return (
276
+ <svg {...f}>
277
+ {/* Odoo's brand purple, and its wordmark's twin `o`s β€” the part of that
278
+ wordmark that survives being shrunk to 15px. */}
279
+ <rect x="1" y="1" width="14" height="14" rx="3.4" fill="#714B67" />
280
+ <circle cx="5.7" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
281
+ <circle cx="10.4" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
282
+ </svg>
283
+ );
284
+ if (name === "google")
285
+ return (
286
+ <svg {...f} fill="none" strokeWidth="2.3">
287
+ {/* The four-arc G. Each arc is one brand colour, and the bar into the
288
+ centre is what makes it a G rather than a ring. */}
289
+ <path d="M4.46 4.46A5 5 0 0 1 11.54 4.46" stroke="#EA4335" strokeLinecap="round" />
290
+ <path d="M4.46 4.46A5 5 0 0 0 4.46 11.54" stroke="#FBBC05" strokeLinecap="round" />
291
+ <path d="M4.46 11.54A5 5 0 0 0 11.54 11.54" stroke="#34A853" strokeLinecap="round" />
292
+ <path d="M11.54 11.54A5 5 0 0 0 13 8" stroke="#4285F4" strokeLinecap="round" />
293
+ <path d="M13 8H8.4" stroke="#4285F4" />
294
+ </svg>
295
+ );
296
+ if (name === "gmail")
297
+ return (
298
+ <svg {...f} fill="none" stroke="#EA4335" strokeWidth="1.5" strokeLinejoin="round">
299
+ <rect x="1.6" y="3.6" width="12.8" height="9" rx="1.6" />
300
+ <path d="m2 4.4 6 4.6 6-4.6" />
301
+ </svg>
302
+ );
303
+ // ⭐ WAVE 31 · R7. Slack's mark is FOUR bars in four brand colours, drawn as rounded rects
304
+ // rather than the true interlocking glyph: at 15px the real lozenges collapse into mud, and a
305
+ // mark nobody can identify is worse than a two-letter tile. Colours are Slack's own.
306
+ if (name === "slack")
307
+ return (
308
+ <svg {...f}>
309
+ <rect x="2" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#36C5F0" />
310
+ <rect x="8.6" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#2EB67D" />
311
+ <rect x="6.6" y="2" width="2.8" height="5.4" rx="1.4" fill="#ECB22E" />
312
+ <rect x="6.6" y="8.6" width="2.8" height="5.4" rx="1.4" fill="#E01E5A" />
313
+ </svg>
314
+ );
315
+ // Meta's infinity loop, as two overlapping strokes in the brand blue. ⚠ `fill="none"` with a
316
+ // round cap: filled, the two lobes merge into a blob at this size.
317
+ if (name === "meta")
318
+ return (
319
+ <svg {...f} fill="none">
320
+ <path
321
+ d="M2.2 10.4c0-3 1.5-5.2 3.3-5.2 1.2 0 2 .8 3 2.4l1 1.6c.9 1.4 1.5 2.1 2.2 2.1.8 0
322
+ 1.3-.8 1.3-2.1 0-1.6-.7-3.4-2-3.4-.9 0-1.7.7-2.6 2"
323
+ stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
324
+ />
325
+ <path
326
+ d="M2.2 10.4c0 1.3.6 2 1.5 2 .8 0 1.4-.5 2.5-2.2l3-4.6"
327
+ stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
328
+ />
329
+ </svg>
330
+ );
331
+ if (name === "stripe")
332
+ return (
333
+ <svg {...f}>
334
+ <rect x="1" y="1" width="14" height="14" rx="3.4" fill="#635BFF" />
335
+ <path
336
+ d="M10.5 5.6a2.3 2.3 0 0 0-3.6 1.2c0 2.1 4.1 1.5 4.1 3.5a2.4 2.4 0 0 1-3.7 1.3"
337
+ fill="none" stroke="#FFFFFF" strokeWidth="1.5" strokeLinecap="round"
338
+ />
339
+ </svg>
340
+ );
341
+ if (name === "shopify")
342
+ return (
343
+ <svg {...f}>
344
+ {/* The bag, in Shopify's two greens: the darker one is the handle, which
345
+ is the part that reads as a bag rather than as a box. */}
346
+ <path d="M3.5 5.2h9l-.75 8.4a.9.9 0 0 1-.9.8H5.15a.9.9 0 0 1-.9-.8z" fill="#95BF47" />
347
+ <path
348
+ d="M6.1 6.4V4.5a1.9 1.9 0 0 1 3.8 0v1.9"
349
+ fill="none" stroke="#5E8E3E" strokeWidth="1.4" strokeLinecap="round"
350
+ />
351
+ </svg>
352
+ );
353
+ /*
354
+ ⚠ THE LAST TWO ARE OURS, NOT BRANDS β€” `currentColor`, house stroke weight,
355
+ so they sit in the chip family beside the coloured logos rather than
356
+ pretending to be a company. Keeping them here is what lets every caller ask
357
+ one question instead of two.
358
+ */
359
+ if (name === "webhooks")
360
+ return (
361
+ <svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
362
+ strokeLinecap="round" strokeLinejoin="round">
363
+ <path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
364
+ <path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
365
+ <path d="M6.2 8h3.6" />
366
+ </svg>
367
+ );
368
+ if (name === "scraper")
369
+ return (
370
+ <svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
371
+ strokeLinecap="round" strokeLinejoin="round">
372
+ {/* A magnifier over a grid of rows: it reads a catalogue of profiles and
373
+ makes records out of what matches β€” which is what the bucket does,
374
+ and it is deliberately NOT either platform's mark, because the whole
375
+ point of R3 is that the bucket is neither one of them. */}
376
+ <path d="M2.6 3.4h10.8M2.6 6.2h5.2M2.6 9h3.4" />
377
+ <circle cx="10.4" cy="10.2" r="3" />
378
+ <path d="m12.6 12.4 1.6 1.6" />
379
+ </svg>
380
+ );
381
+ return null;
382
+ }
383
+
384
+ /**
385
+ * Does this kind wear a LOGO rather than a house glyph?
386
+ *
387
+ * β›” IT EXISTS BECAUSE THE TILE HAS TO CHANGE TOO, and forgetting that would have shipped the
388
+ * defect quietly: `.autox-card-mark` paints a blue tint and sets `color: var(--lp-blue-deep)`,
389
+ * so TikTok's note β€” which is `currentColor` by design, so it survives dark mode β€” would have
390
+ * rendered BLUE, and Instagram's gradient would have sat on a coloured chip. The caller adds
391
+ * `is-brand`, which neutralises both. One predicate, so the mark and its tile cannot disagree
392
+ * about whether a row is branded.
393
+ */
394
+ export function hasBrandKind(kind: string): boolean {
395
+ return Boolean(BRAND_OF_KIND[kind]);
396
+ }
397
+
398
+ /** The connector-key twin of `hasBrandKind`, for the directory's tiles. */
399
+ export function hasBrandConnector(key: string): boolean {
400
+ return Boolean(BRAND_OF_CONNECTOR[key]);
401
+ }
402
+
403
+ /** The mark for a trigger or action KIND, or null when it is not a branded one. */
404
+ export function brandForKind(kind: string, size = 15): ReactElement | null {
405
+ const name = BRAND_OF_KIND[kind];
406
+ return name ? <BrandMark name={name} size={size} /> : null;
407
+ }
408
+
409
+ /** The mark for a connector/provider KEY, or null when we have no logo for it. */
410
+ export function brandForConnector(key: string, size = 15): ReactElement | null {
411
+ const name = BRAND_OF_CONNECTOR[key];
412
+ return name ? <BrandMark name={name} size={size} /> : null;
413
+ }
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -166,7 +166,7 @@ import { AnchoredOverlay, BodyPortal, useOverlayLayer } from "./OverlaySurface";
166
  import type { AnchorRect } from "./OverlaySurface";
167
  import { StarIcon } from "./Stars";
168
  import { ALL_VIEW_ID, MAX_CALENDAR_METRICS, allViewName,
169
- MAX_FROZEN, choiceOptions, choiceVocabulary, clampFrozenCount, cleanDisplay, formulaOf,
170
  topicForScope,
171
  isDateFamilyType, isFilterGroup, isGroupableField,
172
  isDerivedLink, isUserSchemaField, isBlankValue, TOTAL_GROUP_KEY,
@@ -191,6 +191,7 @@ import { ALL_VIEW_ID, MAX_CALENDAR_METRICS, allViewName,
191
  import { buildPivotRequest, cleanSecondaryView, emptyViewConfig, PIVOT_PATH, PIVOT_WINDOW_LABELS,
192
  pivotRefusalFromBody, pivotResponse, relationalTargets } from "./types";
193
  import type {
 
194
  DisplayMode,
195
  DisplaySpec,
196
  Field,
@@ -453,6 +454,19 @@ function sameConfig(a: ViewConfig, b: ViewConfig): boolean {
453
  return JSON.stringify(a) === JSON.stringify(b);
454
  }
455
 
 
 
 
 
 
 
 
 
 
 
 
 
 
456
  /** C3 locks are present on the server projection, while the long-lived shared type remains
457
  * deliberately backward-compatible. Keep that wire detail additive here rather than widening a
458
  * cross-lane contract just to paint one property. */
@@ -554,6 +568,9 @@ function normalizeConfig(config: Partial<ViewConfig> | undefined, fields: Field[
554
  // a legacy view is byte-identical to itself after a round trip. W13 (C4 as
555
  // amended): cleanDisplay keeps grid-carried field picks.
556
  display: cleanDisplay(config?.display),
 
 
 
557
  frozenCount: clampFrozenCount(config?.frozenCount),
558
  /**
559
  * ⭐⭐ W41-T42 Β· CONTRACT C6 β€” the saved pivot, VALIDATED rather than merely carried.
@@ -1557,6 +1574,58 @@ function CustomerGridSurface({
1557
  const configRef = useRef(config);
1558
  const [workspaceReady, setWorkspaceReady] = useState(false);
1559
  const [saveState, setSaveState] = useState<"saved" | "saving">("saved");
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1560
  /**
1561
  * W45-T14 / C5: the workspace component is deliberately not keyed by database because its
1562
  * shell and View rail must survive a switch. That makes these state cells long-lived too, so
@@ -2168,10 +2237,27 @@ function CustomerGridSurface({
2168
  signal(TOAST_EVENT, refuseQueryMutation(queryBinding, "update").message);
2169
  return;
2170
  }
2171
- if (next.groupBy !== config.groupBy) setCollapsed(new Set());
2172
- setConfig(next);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2173
  },
2174
- [config.groupBy, isQueryPreview, queryBinding]
2175
  );
2176
  /** C2 returns the entire state so it can prove it did not rewrite user clauses. B consumes
2177
  * exactly its managed addition/removal; filters, conjunction, user membership and every other
@@ -2565,7 +2651,7 @@ function CustomerGridSurface({
2565
  // Wave-6 item 10 β€” how this view displays. A WINDOWED table is always the grid: list/
2566
  // calendar/kanban compute over the whole matched set, and one page is not it (CG-3's rule,
2567
  // the same reason grouping is off there).
2568
- const displaySpec = cleanDisplay(config.display);
2569
  const displayMode: DisplayMode = serverWindowed ? "grid" : displaySpec?.mode ?? "grid";
2570
  const [routePanelOpen, setRoutePanelOpen] = useState(false);
2571
  useEffect(() => {
@@ -2573,12 +2659,12 @@ function CustomerGridSurface({
2573
  const detail = (event as CustomEvent<{ routeId?: string; forwarded?: boolean }>).detail;
2574
  if (!detail?.routeId || detail.forwarded) return;
2575
  setRoutePanelOpen(true);
2576
- setConfig((current) => ({ ...current, display: { ...(current.display ?? {}), mode: "map" } } as ViewConfig));
2577
  window.setTimeout(() => signal("aios:route-open", { routeId: detail.routeId, forwarded: true }), 60);
2578
  };
2579
  window.addEventListener("aios:route-open", openRoute);
2580
  return () => window.removeEventListener("aios:route-open", openRoute);
2581
- }, []);
2582
  useEffect(() => {
2583
  if (displayMode !== "map") setRoutePanelOpen(false);
2584
  }, [displayMode]);
@@ -3408,27 +3494,22 @@ function CustomerGridSurface({
3408
  const embeddedSelectedKey = [...embeddedSelectedIds].sort((a, b) => a - b).join(",");
3409
  const selectedPidKey = [...selectedPids].sort((a, b) => a - b).join(",");
3410
  const [workspaceDrawer, setWorkspaceDrawer] = useState<"notes" | "history" | null>(null);
3411
- type SavedApplication = { id: string; type: "chart" | "route" | "map" | "timeseries"; name: string; config?: Record<string, unknown>; starred?: boolean; semanticRoleBindings?: Record<string, string>; capabilities?: Record<string, boolean>; compatibleDatabases?: string[]; openTarget?: { database?: string } };
3412
  const [applicationRailOpen, setApplicationRailOpen] = useState(false);
3413
  const [applications, setApplications] = useState<SavedApplication[]>([]);
3414
- const [applicationError, setApplicationError] = useState("");
3415
- // Application permissions and compatibility use the canonical database key, never the grid's
3416
- // transport scope (`customer`/`product`). Home and Starred publish this same key in their URL.
3417
- const applicationDatabase = activeDatabaseKey ?? dataPath?.database ?? topic.key;
3418
  const applicationKind = displayMode === "chart" ? "chart" : displayMode === "timeseries" ? "timeseries" : displayMode === "map" ? "map" : null;
3419
  const applySavedApplication = useCallback((application: SavedApplication): boolean => {
3420
- if (!application.id) return false;
3421
- const stored = application.config ?? {};
3422
- const storedDisplay = stored.display && typeof stored.display === "object"
3423
- ? stored.display as Record<string, unknown>
3424
- : stored;
3425
- updateConfig({ ...config, display: {
3426
- ...(config.display ?? { mode: displayMode }),
3427
- ...storedDisplay,
3428
- applicationId: application.id,
3429
- } } as ViewConfig);
3430
  return true;
3431
- }, [config, displayMode, updateConfig]);
3432
  const loadApplications = useCallback(async (signal?: AbortSignal) => {
3433
  if (!applicationRailOpen) return;
3434
  try {
@@ -3486,8 +3567,7 @@ function CustomerGridSurface({
3486
  useEffect(() => {
3487
  // An explicit deep link is authoritative. A missing, revoked, or incompatible id must leave
3488
  // the View untouched; it must never silently turn into that database's default Application.
3489
- if (dataPath?.application || !applicationKind ||
3490
- (config.display as (DisplaySpec & { applicationId?: string }) | undefined)?.applicationId) return;
3491
  const controller = new AbortController();
3492
  void fetch(`${API_V1}/applications/defaults/${encodeURIComponent(applicationDatabase)}/${applicationKind}`, { credentials: CREDENTIALS, signal: controller.signal })
3493
  .then(async (response) => response.ok ? response.json() : null)
@@ -3497,7 +3577,7 @@ function CustomerGridSurface({
3497
  applySavedApplication(application as SavedApplication);
3498
  }).catch(() => undefined);
3499
  return () => controller.abort();
3500
- }, [applicationDatabase, applicationKind, applySavedApplication, config.display, dataPath?.application]);
3501
  const [drawerBusy, setDrawerBusy] = useState(false);
3502
  const [drawerError, setDrawerError] = useState("");
3503
  const [sharedNote, setSharedNote] = useState("");
@@ -3510,9 +3590,14 @@ function CustomerGridSurface({
3510
  const controller = new AbortController();
3511
  setDrawerBusy(true); setDrawerError("");
3512
  const noteViewQuery = notesMode === "view" ? `&viewId=${encodeURIComponent(activeViewId)}` : "";
 
 
 
 
 
3513
  const url = workspaceDrawer === "notes"
3514
  ? `${API_V1}/grid/shared-note?scope=${encodeURIComponent(scope)}${noteViewQuery}`
3515
- : `${API_V1}/tables/${encodeURIComponent(scope)}/history?rowId=${encodeURIComponent(String(historyPid ?? ""))}&retentionDays=${historyRetention}`;
3516
  void fetch(url, { credentials: CREDENTIALS, signal: controller.signal }).then(async (response) => {
3517
  const body = await response.json().catch(() => ({}));
3518
  if (!response.ok) throw new Error(String(body?.detail?.message ?? body?.detail ?? "Could not load drawer"));
@@ -3747,10 +3832,10 @@ function CustomerGridSurface({
3747
  nothing about colour, and reading that omission as "turn colour off" would have the
3748
  assistant undoing a pick the person made by hand. */
3749
  if (spec.colorBy && fieldByKey.has(spec.colorBy))
3750
- next = withColorField(next, spec.colorBy);
3751
  updateConfig(next);
3752
  },
3753
- [config, fieldByKey, updateConfig]
3754
  );
3755
  const onChatUndoView = useCallback(() => {
3756
  const prior = chatUndoRef.current;
@@ -7348,7 +7433,7 @@ function CustomerGridSurface({
7348
  // callback is declared above it.)
7349
  const av = views.find((v) => v.id === activeViewId);
7350
  if (av && isModeFrozen(av)) return;
7351
- const spec = cleanDisplay(config.display);
7352
  if (m === "grid") {
7353
  updateConfig({
7354
  ...config,
@@ -7358,13 +7443,13 @@ function CustomerGridSurface({
7358
  }
7359
  updateConfig({ ...config, display: { ...(spec ?? {}), mode: m } });
7360
  },
7361
- [config, updateConfig, views, activeViewId]
7362
  );
7363
  // C4 (amended): the pick is written INTO display and the selects are FED from the
7364
  // view def (`display.<field>`), never from component state that dies on unmount.
7365
  const setDisplayField = useCallback(
7366
  (k: "dateField" | "stackField" | "colorField" | "sizeField", key: string) => {
7367
- const spec = cleanDisplay(config.display);
7368
  if (!spec) return;
7369
  // Wave-8 I3/I5: colour/size are OPTIONAL encodings, so "" is a real choice
7370
  // (none) and must delete the ref rather than store an empty key that no
@@ -7373,7 +7458,7 @@ function CustomerGridSurface({
7373
  if (!key) delete (next as Record<string, unknown>)[k];
7374
  updateConfig({ ...config, display: next });
7375
  },
7376
- [config, updateConfig]
7377
  );
7378
  /**
7379
  * Item 3 (C-DISP) β€” the kanban card clamp.
@@ -7385,14 +7470,14 @@ function CustomerGridSurface({
7385
  */
7386
  const setKanbanClamp = useCallback(
7387
  (next: false | undefined) => {
7388
- const spec = cleanDisplay(config.display);
7389
  if (!spec) return;
7390
  const display = { ...spec };
7391
  if (next === false) display.kanbanClamp = false;
7392
  else delete (display as Record<string, unknown>).kanbanClamp;
7393
  updateConfig({ ...config, display });
7394
  },
7395
- [config, updateConfig]
7396
  );
7397
  /**
7398
  * ⭐ WAVE-27 item 8 (owner ruling R2, contract C3) β€” the swipe BINDING.
@@ -7404,14 +7489,14 @@ function CustomerGridSurface({
7404
  */
7405
  const setSwipeSpec = useCallback(
7406
  (next: SwipeSpec | undefined) => {
7407
- const spec = cleanDisplay(config.display);
7408
  if (!spec) return;
7409
  const display = { ...spec };
7410
  if (next) display.swipe = next;
7411
  else delete (display as Record<string, unknown>).swipe;
7412
  updateConfig({ ...config, display });
7413
  },
7414
- [config, updateConfig]
7415
  );
7416
  /**
7417
  * ⭐⭐ WAVE-29 C4 / T29 (owner R7) β€” the FORM spec's writer, shaped exactly like `setSwipeSpec`
@@ -7422,14 +7507,14 @@ function CustomerGridSurface({
7422
  */
7423
  const setFormSpec = useCallback(
7424
  (next: FormSpec | null) => {
7425
- const spec = cleanDisplay(config.display);
7426
  if (!spec) return;
7427
  const display = { ...spec };
7428
  if (next) display.form = next;
7429
  else delete (display as Record<string, unknown>).form;
7430
  updateConfig({ ...config, display });
7431
  },
7432
- [config, updateConfig]
7433
  );
7434
  /**
7435
  * Item 4 (C-DISP) β€” the per-day totals. An EMPTY list deletes the key rather than storing
@@ -7439,7 +7524,7 @@ function CustomerGridSurface({
7439
  */
7440
  const setCalendarMetrics = useCallback(
7441
  (next: { id: string; field: string; agg: string }[]) => {
7442
- const spec = cleanDisplay(config.display);
7443
  if (!spec) return;
7444
  const display = { ...spec };
7445
  const capped = next.slice(0, MAX_CALENDAR_METRICS);
@@ -7447,19 +7532,19 @@ function CustomerGridSurface({
7447
  else delete (display as Record<string, unknown>).calendarMetrics;
7448
  updateConfig({ ...config, display });
7449
  },
7450
- [config, updateConfig]
7451
  );
7452
  /** Item 4 (C-DISP) β€” records vs summaries. `records` is the default, so it deletes the key. */
7453
  const setCalendarMode = useCallback(
7454
  (next: "records" | "summary") => {
7455
- const spec = cleanDisplay(config.display);
7456
  if (!spec) return;
7457
  const display = { ...spec };
7458
  if (next === "summary") display.calendarMode = "summary";
7459
  else delete (display as Record<string, unknown>).calendarMode;
7460
  updateConfig({ ...config, display });
7461
  },
7462
- [config, updateConfig]
7463
  );
7464
  // The calendar's date field: the view's pick when it is still a real date-family field,
7465
  // else `last_order`, else the first date-family field. The kanban's stack field: status or
@@ -7494,13 +7579,13 @@ function CustomerGridSurface({
7494
  );
7495
  const setCharts = useCallback(
7496
  (next: ChartSpec[]) => {
7497
- const spec = cleanDisplay(config.display);
7498
  if (!spec) return;
7499
  const display = { ...spec, charts: next };
7500
  if (!next.length) delete (display as Record<string, unknown>).charts;
7501
  updateConfig({ ...config, display });
7502
  },
7503
- [config, updateConfig]
7504
  );
7505
  const colorFieldChoices = useMemo(
7506
  () => fields.filter((f) => f.type === "status" || f.type === "select"),
@@ -7556,14 +7641,14 @@ function CustomerGridSurface({
7556
  */
7557
  const onPickCoordField = useCallback(
7558
  (key: string) => {
7559
- const spec = cleanDisplay(config.display);
7560
  if (!spec) return;
7561
  const next: DisplaySpec = { ...spec };
7562
  if (key) next.coordField = key;
7563
  else delete next.coordField;
7564
  updateConfig({ ...config, display: next });
7565
  },
7566
- [config, updateConfig]
7567
  );
7568
  /**
7569
  * β›”β›” AN ADAPTER, AND IT EXISTS BECAUSE THE STORED SHAPE IS DECLARED TWICE (reported as
@@ -7593,10 +7678,10 @@ function CustomerGridSurface({
7593
  /** R5 β€” the per-view catalog picks, persisted the way every other display key rides. */
7594
  const onCatalogSpec = useCallback(
7595
  (next: { imageField?: string; titleField?: string }) => {
7596
- const spec = cleanDisplay(config.display) ?? { mode: "catalog" as const };
7597
  updateConfig({ ...config, display: { ...spec, catalog: { ...spec.catalog, ...next } } });
7598
  },
7599
- [config, updateConfig]
7600
  );
7601
  const mapColorField = displaySpec?.colorField
7602
  ? colorFieldChoices.find((f) => f.key === displaySpec.colorField)
@@ -7777,19 +7862,19 @@ function CustomerGridSurface({
7777
  );
7778
  const onCatalogs = useCallback(
7779
  (next: CatalogSpec[]) => {
7780
- const spec = cleanDisplay(config.display) ?? { mode: "catalog" as const };
7781
  updateConfig({ ...config, display: { ...spec, catalogs: next } });
7782
  },
7783
- [config, updateConfig]
7784
  );
7785
  /* ═══ end W18-C CATALOG ═══ */
7786
  /** Persist a bucket/span/metric pick onto the view, the way every other display key rides. */
7787
  const onTimeseriesDisplay = useCallback(
7788
  (next: Partial<DisplaySpec>) => {
7789
- const spec = cleanDisplay(config.display) ?? { mode: "timeseries" as const };
7790
  updateConfig({ ...config, display: { ...spec, ...next } });
7791
  },
7792
- [config, updateConfig]
7793
  );
7794
  const kanbanCanMove =
7795
  !!kanbanField && kanbanField.type === "select" && canEditField(kanbanField);
@@ -8642,7 +8727,7 @@ function CustomerGridSurface({
8642
  the rail. `.cg-shell` is a horizontal flex row, so this needs no positioning of its own.
8643
  ⚠ NOT on an embedded or Query surface: neither has a database of its own for the chat to
8644
  be about, which is the same condition the script projections already carry. */}
8645
- {applicationRailOpen && <aside className="cg-application-rail" aria-label="Applications"><header><strong>Applications</strong><button type="button" className="cg-icon-button" aria-label="Close Applications" onClick={() => setApplicationRailOpen(false)}>Γ—</button></header><p className="cg-application-context">Reusable {applicationKind ?? "Chart, Route, Map, and Time Series"} assets for this database</p>{applicationError && <p role="alert">{applicationError}</p>}<div className="cg-application-list">{applications.map((application) => <article key={application.id} className="cg-application-card"><button type="button" className="cg-application-open" onClick={() => { const roles = Object.entries(application.semanticRoleBindings ?? {}); if (roles.length && !window.confirm(`Use ${application.name} with these semantic roles?\n${roles.map(([role, mappedField]) => `${role}: ${mappedField}`).join("\n")}`)) return; applySavedApplication(application); }}><span>{application.name}</span><small>{application.type}</small></button><div className="cg-application-actions">{application.capabilities?.star === true && <button type="button" className="cg-icon-button" aria-label={`${application.starred ? "Unstar" : "Star"} ${application.name}`} onClick={async () => { await fetch(`${API_V1}/applications/${encodeURIComponent(application.id)}`, { method: "PATCH", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ starred: !application.starred }) }); void loadApplications(); }}>{application.starred ? "β˜…" : "β˜†"}</button>}<button type="button" className="cg-link-btn" onClick={async () => { await fetch(`${API_V1}/applications/defaults/${encodeURIComponent(applicationDatabase)}/${application.type}`, { method: "PUT", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ applicationId: application.id }) }); }}>Make default</button>{application.capabilities?.delete === true && <button type="button" className="cg-link-btn is-danger" onClick={async () => { if (!window.confirm(`Delete Application β€œ${application.name}”? Views using it will keep their own saved configuration.`)) return; await fetch(`${API_V1}/applications/${encodeURIComponent(application.id)}`, { method: "DELETE", credentials: CREDENTIALS }); void loadApplications(); }}>Delete…</button>}</div></article>)}{!applicationError && applications.length === 0 && <p>No compatible saved Applications yet.</p>}</div></aside>}
8646
  {!embedded && !queryBinding && (
8647
  chatOpen ? (
8648
  <div className="cg-chat-dock">
@@ -8742,7 +8827,7 @@ function CustomerGridSurface({
8742
  (`colorFieldChoices`), so "what can carry a colour" has a single definition. */
8743
  colorField={config.colorBy}
8744
  colorChoices={colorFieldChoices}
8745
- onColorField={(key) => updateConfig(withColorField(config, key))}
8746
  rowHeightMode={config.rowHeightMode}
8747
  onRowHeightMode={(rowHeightMode) => updateConfig({ ...config, rowHeightMode })}
8748
  filters={config.filters}
@@ -8831,7 +8916,7 @@ function CustomerGridSurface({
8831
  not be wired yet: absent beats present-and-inert. A control row over a database whose
8832
  columns never arrived would offer Hide fields, Filter, Sort and Group on nothing. */}
8833
  {secondaryToolbar}
8834
- {workspaceDrawer && <aside className="cg-workspace-drawer" aria-label={workspaceDrawer === "notes" ? "Notes" : "History"}><header><strong>{workspaceDrawer === "notes" ? "Notes" : "History"}</strong><button type="button" className="cg-icon-button" aria-label="Close drawer" onClick={() => setWorkspaceDrawer(null)}>Γ—</button></header>{drawerBusy && <p role="status">Loading…</p>}{drawerError && <p role="alert">{drawerError}</p>}{workspaceDrawer === "notes" ? <><div className="cg-segmented" role="group" aria-label="Notes scope"><button type="button" aria-pressed={notesMode === "database"} onClick={() => setNotesMode("database")}>Database note</button><button type="button" aria-pressed={notesMode === "view"} onClick={() => setNotesMode("view")}>View note</button></div><textarea className="cg-input" aria-label={notesMode === "view" ? "Shared View note" : "Shared Database note"} value={sharedNote} onChange={(event) => setSharedNote(event.target.value)} /><button type="button" className="cg-btn" disabled={drawerBusy} onClick={() => void saveSharedNote()}>Save note</button></> : <><label>Retention<select className="cg-select" value={historyRetention} onChange={(event) => setHistoryRetention(Number(event.target.value) as 30 | 90)}><option value={30}>30 days</option><option value={90}>90 days Β· platform admin</option></select></label>{historyPid == null ? <p>Select one record to inspect its history.</p> : historyRows.length === 0 && !drawerBusy ? <p>No retained changes.</p> : <ol className="cg-history-list">{historyRows.map((event, index) => <li key={String(event.id ?? index)}><strong>{String(event.field ?? event.fieldKey ?? "Record")}</strong><span>{String(event.updatedAt ?? event.at ?? "")}</span><button type="button" className="cg-link-btn" onClick={async () => { if (!window.confirm("Restore this recorded value? This writes a new auditable change and does not erase history.")) return; const id = String(event.id ?? ""); const response = await fetch(`${API_V1}/tables/${encodeURIComponent(scope)}/history/${encodeURIComponent(id)}/restore`, { method: "POST", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ rowId: historyPid, field: event.field ?? event.fieldKey, retentionDays: historyRetention }) }); if (!response.ok) setDrawerError("Restore was refused. Your current value was not changed."); else setWorkspaceDrawer(null); }}>Restore…</button></li>)}</ol>}</>}</aside>}
8835
  {displayMode === "map" && !pivotOn && (
8836
  <MapSettings
8837
  coordField={mapCoordField}
@@ -8928,8 +9013,8 @@ function CustomerGridSurface({
8928
  )}
8929
 
8930
  {pivot.status === "loading" && (
8931
- /* wave17 GRID item 3 / owner R6: one small bare rotating icon, NO WORDS. This
8932
- said "Loading the related records…" and `verify_icons` R6 caught it, which is
8933
  the regression that rule exists for: a new load surface is exactly where a
8934
  session writes the sentence without knowing the rule. `aria-label` is not a
8935
  word on screen and stays -- `.lp-spin` is an empty span, so the wait would
 
166
  import type { AnchorRect } from "./OverlaySurface";
167
  import { StarIcon } from "./Stars";
168
  import { ALL_VIEW_ID, MAX_CALENDAR_METRICS, allViewName,
169
+ MAX_FROZEN, choiceOptions, choiceVocabulary, clampFrozenCount, cleanApplicationRef, cleanDisplay, formulaOf,
170
  topicForScope,
171
  isDateFamilyType, isFilterGroup, isGroupableField,
172
  isDerivedLink, isUserSchemaField, isBlankValue, TOTAL_GROUP_KEY,
 
191
  import { buildPivotRequest, cleanSecondaryView, emptyViewConfig, PIVOT_PATH, PIVOT_WINDOW_LABELS,
192
  pivotRefusalFromBody, pivotResponse, relationalTargets } from "./types";
193
  import type {
194
+ ApplicationType,
195
  DisplayMode,
196
  DisplaySpec,
197
  Field,
 
454
  return JSON.stringify(a) === JSON.stringify(b);
455
  }
456
 
457
+ type SavedApplication = {
458
+ id: string;
459
+ type: ApplicationType;
460
+ name: string;
461
+ revision?: number;
462
+ config?: { schemaVersion?: number; display?: Record<string, unknown> };
463
+ starred?: boolean;
464
+ semanticRoleBindings?: Record<string, unknown>;
465
+ capabilities?: Record<string, boolean>;
466
+ compatibleDatabases?: string[];
467
+ openTarget?: { database?: string };
468
+ };
469
+
470
  /** C3 locks are present on the server projection, while the long-lived shared type remains
471
  * deliberately backward-compatible. Keep that wire detail additive here rather than widening a
472
  * cross-lane contract just to paint one property. */
 
568
  // a legacy view is byte-identical to itself after a round trip. W13 (C4 as
569
  // amended): cleanDisplay keeps grid-carried field picks.
570
  display: cleanDisplay(config?.display),
571
+ // W45 C3: a View carries only Application identity/revision. The selected asset's typed
572
+ // config is resolved from the registry at render time and never normalized into this object.
573
+ application: cleanApplicationRef(config?.application),
574
  frozenCount: clampFrozenCount(config?.frozenCount),
575
  /**
576
  * ⭐⭐ W41-T42 Β· CONTRACT C6 β€” the saved pivot, VALIDATED rather than merely carried.
 
1574
  const configRef = useRef(config);
1575
  const [workspaceReady, setWorkspaceReady] = useState(false);
1576
  const [saveState, setSaveState] = useState<"saved" | "saving">("saved");
1577
+ // W45 C3: the View stores only this asset reference. Resolve the current Application record
1578
+ // independently so editing one registry asset updates every View that points at it.
1579
+ const applicationDatabase = activeDatabaseKey ?? dataPath?.database ?? topic.key;
1580
+ const [resolvedApplication, setResolvedApplication] = useState<SavedApplication | null>(null);
1581
+ const [applicationError, setApplicationError] = useState("");
1582
+ const applicationRef = cleanApplicationRef(config.application);
1583
+ const applicationRefKey = applicationRef
1584
+ ? `${applicationDatabase}::${applicationRef.type}::${applicationRef.id}`
1585
+ : "";
1586
+ useEffect(() => {
1587
+ if (!applicationRef || !workspaceReady) {
1588
+ setResolvedApplication(null);
1589
+ return;
1590
+ }
1591
+ const controller = new AbortController();
1592
+ void fetch(
1593
+ `${API_V1}/applications?database=${encodeURIComponent(applicationDatabase)}` +
1594
+ `&type=${encodeURIComponent(applicationRef.type)}`,
1595
+ { credentials: CREDENTIALS, signal: controller.signal },
1596
+ ).then(async (response) => {
1597
+ const body = await response.json().catch(() => ({}));
1598
+ if (!response.ok) throw new Error(String(
1599
+ body?.detail?.message ?? body?.detail ?? "Could not resolve this Application",
1600
+ ));
1601
+ const listed = Array.isArray(body?.applications) ? body.applications as SavedApplication[] : [];
1602
+ const application = listed.find((candidate) =>
1603
+ candidate.id === applicationRef.id && candidate.type === applicationRef.type &&
1604
+ (candidate.openTarget?.database === applicationDatabase ||
1605
+ candidate.compatibleDatabases?.includes(applicationDatabase) === true));
1606
+ if (!application) throw new Error("This View's Application is no longer available.");
1607
+ if (!controller.signal.aborted) {
1608
+ setResolvedApplication(application);
1609
+ setApplicationError("");
1610
+ }
1611
+ }).catch((error: unknown) => {
1612
+ if (!controller.signal.aborted) {
1613
+ setResolvedApplication(null);
1614
+ setApplicationError(error instanceof Error ? error.message : "Could not resolve this Application");
1615
+ }
1616
+ });
1617
+ return () => controller.abort();
1618
+ // The scalar key is the whole lookup identity; revision is provenance, while registry reads
1619
+ // intentionally resolve the latest config for every View sharing that identity.
1620
+ // eslint-disable-next-line react-hooks/exhaustive-deps
1621
+ }, [applicationRefKey, workspaceReady]);
1622
+ const resolvedApplicationMatches = !!applicationRef &&
1623
+ resolvedApplication?.id === applicationRef.id && resolvedApplication.type === applicationRef.type;
1624
+ const resolvedDisplaySpec = cleanDisplay(
1625
+ applicationRef
1626
+ ? resolvedApplicationMatches ? resolvedApplication?.config?.display : undefined
1627
+ : config.display,
1628
+ );
1629
  /**
1630
  * W45-T14 / C5: the workspace component is deliberately not keyed by database because its
1631
  * shell and View rail must survive a switch. That makes these state cells long-lived too, so
 
2237
  signal(TOAST_EVENT, refuseQueryMutation(queryBinding, "update").message);
2238
  return;
2239
  }
2240
+ let accepted = next;
2241
+ const currentApplication = cleanApplicationRef(config.application);
2242
+ const nextApplication = cleanApplicationRef(next.application);
2243
+ const sameApplication = !!currentApplication && !!nextApplication &&
2244
+ currentApplication.id === nextApplication.id &&
2245
+ currentApplication.type === nextApplication.type &&
2246
+ currentApplication.revision === nextApplication.revision;
2247
+ const displayChanged = JSON.stringify(next.display ?? null) !==
2248
+ JSON.stringify(config.display ?? null);
2249
+ if (sameApplication && displayChanged) {
2250
+ // A manual display edit is an explicit detach. Keeping the reference as well would make
2251
+ // the registry and the View two owners of the same config, with whichever rendered last
2252
+ // silently winning.
2253
+ accepted = { ...next };
2254
+ delete accepted.application;
2255
+ setResolvedApplication(null);
2256
+ }
2257
+ if (accepted.groupBy !== config.groupBy) setCollapsed(new Set());
2258
+ setConfig(accepted);
2259
  },
2260
+ [config.application, config.display, config.groupBy, isQueryPreview, queryBinding]
2261
  );
2262
  /** C2 returns the entire state so it can prove it did not rewrite user clauses. B consumes
2263
  * exactly its managed addition/removal; filters, conjunction, user membership and every other
 
2651
  // Wave-6 item 10 β€” how this view displays. A WINDOWED table is always the grid: list/
2652
  // calendar/kanban compute over the whole matched set, and one page is not it (CG-3's rule,
2653
  // the same reason grouping is off there).
2654
+ const displaySpec = resolvedDisplaySpec;
2655
  const displayMode: DisplayMode = serverWindowed ? "grid" : displaySpec?.mode ?? "grid";
2656
  const [routePanelOpen, setRoutePanelOpen] = useState(false);
2657
  useEffect(() => {
 
2659
  const detail = (event as CustomEvent<{ routeId?: string; forwarded?: boolean }>).detail;
2660
  if (!detail?.routeId || detail.forwarded) return;
2661
  setRoutePanelOpen(true);
2662
+ updateConfig({ ...config, display: { ...(displaySpec ?? {}), mode: "map" } });
2663
  window.setTimeout(() => signal("aios:route-open", { routeId: detail.routeId, forwarded: true }), 60);
2664
  };
2665
  window.addEventListener("aios:route-open", openRoute);
2666
  return () => window.removeEventListener("aios:route-open", openRoute);
2667
+ }, [config, displaySpec, updateConfig]);
2668
  useEffect(() => {
2669
  if (displayMode !== "map") setRoutePanelOpen(false);
2670
  }, [displayMode]);
 
3494
  const embeddedSelectedKey = [...embeddedSelectedIds].sort((a, b) => a - b).join(",");
3495
  const selectedPidKey = [...selectedPids].sort((a, b) => a - b).join(",");
3496
  const [workspaceDrawer, setWorkspaceDrawer] = useState<"notes" | "history" | null>(null);
 
3497
  const [applicationRailOpen, setApplicationRailOpen] = useState(false);
3498
  const [applications, setApplications] = useState<SavedApplication[]>([]);
 
 
 
 
3499
  const applicationKind = displayMode === "chart" ? "chart" : displayMode === "timeseries" ? "timeseries" : displayMode === "map" ? "map" : null;
3500
  const applySavedApplication = useCallback((application: SavedApplication): boolean => {
3501
+ const reference = cleanApplicationRef({
3502
+ id: application.id,
3503
+ type: application.type,
3504
+ revision: Number.isInteger(application.revision) ? application.revision : 0,
3505
+ });
3506
+ if (!reference || !cleanDisplay(application.config?.display)) return false;
3507
+ const next: ViewConfig = { ...config, application: reference };
3508
+ delete next.display;
3509
+ setResolvedApplication(application);
3510
+ updateConfig(next);
3511
  return true;
3512
+ }, [config, updateConfig]);
3513
  const loadApplications = useCallback(async (signal?: AbortSignal) => {
3514
  if (!applicationRailOpen) return;
3515
  try {
 
3567
  useEffect(() => {
3568
  // An explicit deep link is authoritative. A missing, revoked, or incompatible id must leave
3569
  // the View untouched; it must never silently turn into that database's default Application.
3570
+ if (dataPath?.application || !applicationKind || cleanApplicationRef(config.application)) return;
 
3571
  const controller = new AbortController();
3572
  void fetch(`${API_V1}/applications/defaults/${encodeURIComponent(applicationDatabase)}/${applicationKind}`, { credentials: CREDENTIALS, signal: controller.signal })
3573
  .then(async (response) => response.ok ? response.json() : null)
 
3577
  applySavedApplication(application as SavedApplication);
3578
  }).catch(() => undefined);
3579
  return () => controller.abort();
3580
+ }, [applicationDatabase, applicationKind, applySavedApplication, config.application, dataPath?.application]);
3581
  const [drawerBusy, setDrawerBusy] = useState(false);
3582
  const [drawerError, setDrawerError] = useState("");
3583
  const [sharedNote, setSharedNote] = useState("");
 
3590
  const controller = new AbortController();
3591
  setDrawerBusy(true); setDrawerError("");
3592
  const noteViewQuery = notesMode === "view" ? `&viewId=${encodeURIComponent(activeViewId)}` : "";
3593
+ const userTableHistory = scope.startsWith("ut_");
3594
+ const historyBase = userTableHistory
3595
+ ? `${API_V1}/tables/${encodeURIComponent(scope)}/history`
3596
+ : `${API_V1}/grid/history`;
3597
+ const historyScopeQuery = userTableHistory ? "" : `scope=${encodeURIComponent(scope)}&`;
3598
  const url = workspaceDrawer === "notes"
3599
  ? `${API_V1}/grid/shared-note?scope=${encodeURIComponent(scope)}${noteViewQuery}`
3600
+ : `${historyBase}?${historyScopeQuery}rowId=${encodeURIComponent(String(historyPid ?? ""))}&retentionDays=${historyRetention}`;
3601
  void fetch(url, { credentials: CREDENTIALS, signal: controller.signal }).then(async (response) => {
3602
  const body = await response.json().catch(() => ({}));
3603
  if (!response.ok) throw new Error(String(body?.detail?.message ?? body?.detail ?? "Could not load drawer"));
 
3832
  nothing about colour, and reading that omission as "turn colour off" would have the
3833
  assistant undoing a pick the person made by hand. */
3834
  if (spec.colorBy && fieldByKey.has(spec.colorBy))
3835
+ next = withColorField({ ...next, display: displaySpec }, spec.colorBy);
3836
  updateConfig(next);
3837
  },
3838
+ [config, displaySpec, fieldByKey, updateConfig]
3839
  );
3840
  const onChatUndoView = useCallback(() => {
3841
  const prior = chatUndoRef.current;
 
7433
  // callback is declared above it.)
7434
  const av = views.find((v) => v.id === activeViewId);
7435
  if (av && isModeFrozen(av)) return;
7436
+ const spec = displaySpec;
7437
  if (m === "grid") {
7438
  updateConfig({
7439
  ...config,
 
7443
  }
7444
  updateConfig({ ...config, display: { ...(spec ?? {}), mode: m } });
7445
  },
7446
+ [config, displaySpec, updateConfig, views, activeViewId]
7447
  );
7448
  // C4 (amended): the pick is written INTO display and the selects are FED from the
7449
  // view def (`display.<field>`), never from component state that dies on unmount.
7450
  const setDisplayField = useCallback(
7451
  (k: "dateField" | "stackField" | "colorField" | "sizeField", key: string) => {
7452
+ const spec = displaySpec;
7453
  if (!spec) return;
7454
  // Wave-8 I3/I5: colour/size are OPTIONAL encodings, so "" is a real choice
7455
  // (none) and must delete the ref rather than store an empty key that no
 
7458
  if (!key) delete (next as Record<string, unknown>)[k];
7459
  updateConfig({ ...config, display: next });
7460
  },
7461
+ [config, displaySpec, updateConfig]
7462
  );
7463
  /**
7464
  * Item 3 (C-DISP) β€” the kanban card clamp.
 
7470
  */
7471
  const setKanbanClamp = useCallback(
7472
  (next: false | undefined) => {
7473
+ const spec = displaySpec;
7474
  if (!spec) return;
7475
  const display = { ...spec };
7476
  if (next === false) display.kanbanClamp = false;
7477
  else delete (display as Record<string, unknown>).kanbanClamp;
7478
  updateConfig({ ...config, display });
7479
  },
7480
+ [config, displaySpec, updateConfig]
7481
  );
7482
  /**
7483
  * ⭐ WAVE-27 item 8 (owner ruling R2, contract C3) β€” the swipe BINDING.
 
7489
  */
7490
  const setSwipeSpec = useCallback(
7491
  (next: SwipeSpec | undefined) => {
7492
+ const spec = displaySpec;
7493
  if (!spec) return;
7494
  const display = { ...spec };
7495
  if (next) display.swipe = next;
7496
  else delete (display as Record<string, unknown>).swipe;
7497
  updateConfig({ ...config, display });
7498
  },
7499
+ [config, displaySpec, updateConfig]
7500
  );
7501
  /**
7502
  * ⭐⭐ WAVE-29 C4 / T29 (owner R7) β€” the FORM spec's writer, shaped exactly like `setSwipeSpec`
 
7507
  */
7508
  const setFormSpec = useCallback(
7509
  (next: FormSpec | null) => {
7510
+ const spec = displaySpec;
7511
  if (!spec) return;
7512
  const display = { ...spec };
7513
  if (next) display.form = next;
7514
  else delete (display as Record<string, unknown>).form;
7515
  updateConfig({ ...config, display });
7516
  },
7517
+ [config, displaySpec, updateConfig]
7518
  );
7519
  /**
7520
  * Item 4 (C-DISP) β€” the per-day totals. An EMPTY list deletes the key rather than storing
 
7524
  */
7525
  const setCalendarMetrics = useCallback(
7526
  (next: { id: string; field: string; agg: string }[]) => {
7527
+ const spec = displaySpec;
7528
  if (!spec) return;
7529
  const display = { ...spec };
7530
  const capped = next.slice(0, MAX_CALENDAR_METRICS);
 
7532
  else delete (display as Record<string, unknown>).calendarMetrics;
7533
  updateConfig({ ...config, display });
7534
  },
7535
+ [config, displaySpec, updateConfig]
7536
  );
7537
  /** Item 4 (C-DISP) β€” records vs summaries. `records` is the default, so it deletes the key. */
7538
  const setCalendarMode = useCallback(
7539
  (next: "records" | "summary") => {
7540
+ const spec = displaySpec;
7541
  if (!spec) return;
7542
  const display = { ...spec };
7543
  if (next === "summary") display.calendarMode = "summary";
7544
  else delete (display as Record<string, unknown>).calendarMode;
7545
  updateConfig({ ...config, display });
7546
  },
7547
+ [config, displaySpec, updateConfig]
7548
  );
7549
  // The calendar's date field: the view's pick when it is still a real date-family field,
7550
  // else `last_order`, else the first date-family field. The kanban's stack field: status or
 
7579
  );
7580
  const setCharts = useCallback(
7581
  (next: ChartSpec[]) => {
7582
+ const spec = displaySpec;
7583
  if (!spec) return;
7584
  const display = { ...spec, charts: next };
7585
  if (!next.length) delete (display as Record<string, unknown>).charts;
7586
  updateConfig({ ...config, display });
7587
  },
7588
+ [config, displaySpec, updateConfig]
7589
  );
7590
  const colorFieldChoices = useMemo(
7591
  () => fields.filter((f) => f.type === "status" || f.type === "select"),
 
7641
  */
7642
  const onPickCoordField = useCallback(
7643
  (key: string) => {
7644
+ const spec = displaySpec;
7645
  if (!spec) return;
7646
  const next: DisplaySpec = { ...spec };
7647
  if (key) next.coordField = key;
7648
  else delete next.coordField;
7649
  updateConfig({ ...config, display: next });
7650
  },
7651
+ [config, displaySpec, updateConfig]
7652
  );
7653
  /**
7654
  * β›”β›” AN ADAPTER, AND IT EXISTS BECAUSE THE STORED SHAPE IS DECLARED TWICE (reported as
 
7678
  /** R5 β€” the per-view catalog picks, persisted the way every other display key rides. */
7679
  const onCatalogSpec = useCallback(
7680
  (next: { imageField?: string; titleField?: string }) => {
7681
+ const spec = displaySpec ?? { mode: "catalog" as const };
7682
  updateConfig({ ...config, display: { ...spec, catalog: { ...spec.catalog, ...next } } });
7683
  },
7684
+ [config, displaySpec, updateConfig]
7685
  );
7686
  const mapColorField = displaySpec?.colorField
7687
  ? colorFieldChoices.find((f) => f.key === displaySpec.colorField)
 
7862
  );
7863
  const onCatalogs = useCallback(
7864
  (next: CatalogSpec[]) => {
7865
+ const spec = displaySpec ?? { mode: "catalog" as const };
7866
  updateConfig({ ...config, display: { ...spec, catalogs: next } });
7867
  },
7868
+ [config, displaySpec, updateConfig]
7869
  );
7870
  /* ═══ end W18-C CATALOG ═══ */
7871
  /** Persist a bucket/span/metric pick onto the view, the way every other display key rides. */
7872
  const onTimeseriesDisplay = useCallback(
7873
  (next: Partial<DisplaySpec>) => {
7874
+ const spec = displaySpec ?? { mode: "timeseries" as const };
7875
  updateConfig({ ...config, display: { ...spec, ...next } });
7876
  },
7877
+ [config, displaySpec, updateConfig]
7878
  );
7879
  const kanbanCanMove =
7880
  !!kanbanField && kanbanField.type === "select" && canEditField(kanbanField);
 
8727
  the rail. `.cg-shell` is a horizontal flex row, so this needs no positioning of its own.
8728
  ⚠ NOT on an embedded or Query surface: neither has a database of its own for the chat to
8729
  be about, which is the same condition the script projections already carry. */}
8730
+ {applicationRailOpen && <aside className="cg-application-rail" aria-label="Applications"><header><strong>Applications</strong><button type="button" className="cg-icon-button" aria-label="Close Applications" onClick={() => setApplicationRailOpen(false)}>Γ—</button></header><p className="cg-application-context">Reusable {applicationKind ?? "Chart, Route, Map, and Time Series"} assets for this database</p>{applicationError && <p role="alert">{applicationError}</p>}<div className="cg-application-list">{applications.map((application) => <article key={application.id} className="cg-application-card"><button type="button" className="cg-application-open" onClick={() => { const roles = Object.entries(application.semanticRoleBindings ?? {}); if (roles.length && !window.confirm(`Use ${application.name} with these semantic roles?\n${roles.map(([role, mappedField]) => `${role}: ${String(mappedField)}`).join("\n")}`)) return; applySavedApplication(application); }}><span>{application.name}</span><small>{application.type}</small></button><div className="cg-application-actions">{application.capabilities?.star === true && <button type="button" className="cg-icon-button" aria-label={`${application.starred ? "Unstar" : "Star"} ${application.name}`} onClick={async () => { await fetch(`${API_V1}/applications/${encodeURIComponent(application.id)}`, { method: "PATCH", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ starred: !application.starred }) }); void loadApplications(); }}>{application.starred ? "β˜…" : "β˜†"}</button>}<button type="button" className="cg-link-btn" onClick={async () => { await fetch(`${API_V1}/applications/defaults/${encodeURIComponent(applicationDatabase)}/${application.type}`, { method: "PUT", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ applicationId: application.id }) }); }}>Make default</button>{application.capabilities?.delete === true && <button type="button" className="cg-link-btn is-danger" onClick={async () => { if (!window.confirm(`Delete Application β€œ${application.name}”? Views using it will no longer display that Application.`)) return; await fetch(`${API_V1}/applications/${encodeURIComponent(application.id)}`, { method: "DELETE", credentials: CREDENTIALS }); if (cleanApplicationRef(config.application)?.id === application.id) setResolvedApplication(null); void loadApplications(); }}>Delete…</button>}</div></article>)}{!applicationError && applications.length === 0 && <p>No compatible saved Applications yet.</p>}</div></aside>}
8731
  {!embedded && !queryBinding && (
8732
  chatOpen ? (
8733
  <div className="cg-chat-dock">
 
8827
  (`colorFieldChoices`), so "what can carry a colour" has a single definition. */
8828
  colorField={config.colorBy}
8829
  colorChoices={colorFieldChoices}
8830
+ onColorField={(key) => updateConfig(withColorField({ ...config, display: displaySpec }, key))}
8831
  rowHeightMode={config.rowHeightMode}
8832
  onRowHeightMode={(rowHeightMode) => updateConfig({ ...config, rowHeightMode })}
8833
  filters={config.filters}
 
8916
  not be wired yet: absent beats present-and-inert. A control row over a database whose
8917
  columns never arrived would offer Hide fields, Filter, Sort and Group on nothing. */}
8918
  {secondaryToolbar}
8919
+ {workspaceDrawer && <aside className="cg-workspace-drawer" aria-label={workspaceDrawer === "notes" ? "Notes" : "History"}><header><strong>{workspaceDrawer === "notes" ? "Notes" : "History"}</strong><button type="button" className="cg-icon-button" aria-label="Close drawer" onClick={() => setWorkspaceDrawer(null)}>Γ—</button></header>{drawerBusy && <span className="lp-spin" role="status" aria-label="Loading" />}{drawerError && <p role="alert">{drawerError}</p>}{workspaceDrawer === "notes" ? <><div className="cg-segmented" role="group" aria-label="Notes scope"><button type="button" aria-pressed={notesMode === "database"} onClick={() => setNotesMode("database")}>Database note</button><button type="button" aria-pressed={notesMode === "view"} onClick={() => setNotesMode("view")}>View note</button></div><textarea className="cg-input" aria-label={notesMode === "view" ? "Shared View note" : "Shared Database note"} value={sharedNote} onChange={(event) => setSharedNote(event.target.value)} /><button type="button" className="cg-btn" disabled={drawerBusy} onClick={() => void saveSharedNote()}>Save note</button></> : <><label>Retention<select className="cg-select" value={historyRetention} onChange={(event) => setHistoryRetention(Number(event.target.value) as 30 | 90)}><option value={30}>30 days</option><option value={90}>90 days Β· platform admin</option></select></label>{historyPid == null ? <p>Select one record to inspect its history.</p> : historyRows.length === 0 && !drawerBusy ? <p>No retained changes.</p> : <ol className="cg-history-list">{historyRows.map((event, index) => <li key={String(event.id ?? index)}><strong>{String(event.field ?? event.fieldKey ?? "Record")}</strong><span>{String(event.updatedAt ?? event.at ?? "")}</span><button type="button" className="cg-link-btn" onClick={async () => { if (!window.confirm("Restore this recorded value? This writes a new auditable change and does not erase history.")) return; const id = String(event.id ?? ""); const restoreUrl = scope.startsWith("ut_") ? `${API_V1}/tables/${encodeURIComponent(scope)}/history/${encodeURIComponent(id)}/restore` : `${API_V1}/grid/history/${encodeURIComponent(id)}/restore?scope=${encodeURIComponent(scope)}`; const response = await fetch(restoreUrl, { method: "POST", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ rowId: historyPid, field: event.field ?? event.fieldKey, retentionDays: historyRetention }) }); if (!response.ok) setDrawerError("Restore was refused. Your current value was not changed."); else setWorkspaceDrawer(null); }}>Restore…</button></li>)}</ol>}</>}</aside>}
8920
  {displayMode === "map" && !pivotOn && (
8921
  <MapSettings
8922
  coordField={mapCoordField}
 
9013
  )}
9014
 
9015
  {pivot.status === "loading" && (
9016
+ /* wave17 GRID item 3 / owner R6: one small bare rotating icon, NO WORDS. The
9017
+ former progress sentence was removed after `verify_icons` R6 caught it, which is
9018
  the regression that rule exists for: a new load surface is exactly where a
9019
  session writes the sentence without knowing the rule. `aria-label` is not a
9020
  word on screen and stays -- `.lp-spin` is an empty span, so the wait would
web/src/customer-grid/GridChat.tsx CHANGED
@@ -1,512 +1,512 @@
1
- // ---------------------------------------------------------------------------
2
- // customer-grid / GridChat.tsx β€” the docked chat for ANY database view (W37-T40, R2, R10, C6).
3
- //
4
- // Owner items 10 and 11 are ONE feature (ruling R2): the chat IS the builder. This is its shell β€”
5
- // the conversation surface every later ticket in the lane hangs a power off. T42 gives it the
6
- // schema to answer from, T43 the view controls, T44 the Custom View's code, T45 the confirmed
7
- // record edit.
8
- //
9
- // β›”β›” IT REACHES INTO NOTHING. Contract C6: every action is a callback the host supplies, and
10
- // EVERY PROP IS REQUIRED. An optional prop is how a panel ships mounted-but-inert β€” the feature is
11
- // whole, the gate is green, and the one line that would have passed the callback was never
12
- // written. This repo shipped five of those in a single wave. A required prop makes the omission a
13
- // compile error in the mounting file, which is where a person can see it.
14
- //
15
- // ⚠ THE SHAPE IS THE ONE THIS PRODUCT ALREADY HAS, not a third chat look. `AutomationChat` and
16
- // `AssistantPage` both render a centred opening while the transcript is empty, then a log with the
17
- // SAME composer moved to the foot; `FieldAgentChat` reuses the same composer classes rather than
18
- // drawing a second one. Copying that is not laziness, it is the reason the owner cannot tell which
19
- // surface was built by whom.
20
- //
21
- // ⚠ NO `import.meta.env` ANYWHERE IN THIS FILE'S GRAPH, and the constraint is load-bearing rather
22
- // than stylistic: the gate renders this component from a CommonJS build, and `import.meta` cannot
23
- // be required from one. `AutomationChat`'s own header records that exact crash. The imports below
24
- // are `react` + `./gridChat` + the stylesheet, and nothing else.
25
- // ---------------------------------------------------------------------------
26
-
27
- import { useCallback, useEffect, useRef, useState } from "react";
28
-
29
- import {
30
- answered,
31
- asked,
32
- composerHint,
33
- editSummary,
34
- emptyChat,
35
- failed,
36
- isBusy,
37
- noted,
38
- proposedEdits,
39
- readIntent,
40
- runSentence,
41
- wrote,
42
- } from "./gridChat";
43
- import type {
44
- GridChatAnswer,
45
- GridChatEdit,
46
- GridChatField,
47
- GridChatRunResult,
48
- GridChatState,
49
- GridChatTurn,
50
- } from "./gridChat";
51
- import "./gridChat.css";
52
-
53
- // ⭐ RE-EXPORTED SO THE MOUNTING FILE TAKES ONE IMPORT. The types live in `gridChat.ts` (they have
54
- // to: the state machine is typed by them and that module must stay React-free), but a host that
55
- // had to import the component from here and its types from there would be one refactor away from
56
- // the two drifting. Published to C in mailbox E-4 as a single import line.
57
- export type {
58
- GridChatAnswer,
59
- GridChatEdit,
60
- GridChatField,
61
- GridChatRunResult,
62
- GridChatState,
63
- GridChatTurn,
64
- };
65
-
66
- /**
67
- * What the host asks the chat to do about the view. ⚠ DELIBERATELY NARROW: this is the vocabulary
68
- * `assistant build_view` already speaks, minus what it cannot express. There is no `rhs` in that
69
- * tool schema, so a field-versus-field condition is not sayable
70
- * [[assistant-build-view-is-a-subset]] β€” W37-T43 has to SAY it cannot rather than fail quietly.
71
- */
72
- export interface GridChatViewSpec {
73
- /**
74
- * ⚠ RESERVED AND DELIBERATELY NOT POPULATED BY `readIntent` YET. The panel understands
75
- * sort/group/colour from a sentence; a real FILTER needs the condition vocabulary the host owns,
76
- * so this is the slot C fills rather than a field the panel quietly leaves empty. Named here so
77
- * it reads as a contract with a known gap instead of a channel nobody noticed was dead
78
- * [[flag-shipped-without-its-writer]].
79
- */
80
- filter?: unknown;
81
- sortBy?: string;
82
- groupBy?: string;
83
- colorBy?: string;
84
- }
85
-
86
- export interface GridChatProps {
87
- /** The host owns the toggle. The panel never closes itself except through `onClose`. */
88
- open: boolean;
89
- onClose: () => void;
90
- /** What this chat is reading, in the person's words. Appears in the header and the placeholder. */
91
- databaseLabel: string;
92
- /** The columns the chat may reason about. The host decides; the chat never discovers. */
93
- schema: GridChatField[];
94
- rowCount: number;
95
- /**
96
- * β›” R10's BOUND, EXPRESSED AS AN AFFORDANCE. `false` means the edit power is not OFFERED, not
97
- * that it is offered and then refused. The chat is not a privilege escalation: a caller whose
98
- * own permissions would refuse the write must not be invited to compose one
99
- * [[permitted-is-not-answerable]].
100
- */
101
- canEdit: boolean;
102
- /** (a) answer a question about this database. */
103
- onDescribe: (question: string) => Promise<GridChatAnswer>;
104
- /** (b) change filter, sort, group or colour on the ACTIVE view. */
105
- onApplyView: (spec: GridChatViewSpec) => void;
106
- /** (b, undo half) put the view back the way it was. */
107
- onUndoView: () => void;
108
- /** (d) write the cells the person just confirmed. β›” Reached only from the confirm control. */
109
- onWriteCells: (edits: GridChatEdit[]) => Promise<void>;
110
- /** (c) run the Custom View's code and report what happened. */
111
- onRunScript: (code: string) => Promise<GridChatRunResult>;
112
- }
113
-
114
- /** The send mark. β›” The Assistant's own path, point for point: a second arrow drawn slightly
115
- * differently is precisely how two surfaces stop looking like one product. */
116
- function SendMark() {
117
- return (
118
- <svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true" fill="none">
119
- <path d="M8 13V3.6M4 7.4 8 3.4l4 4" stroke="currentColor" strokeWidth="1.5"
120
- strokeLinecap="round" strokeLinejoin="round" />
121
- </svg>
122
- );
123
- }
124
-
125
- export default function GridChat(props: GridChatProps) {
126
- const {
127
- open, onClose, databaseLabel, schema, rowCount, canEdit,
128
- onDescribe, onApplyView, onUndoView, onWriteCells, onRunScript,
129
- } = props;
130
-
131
- const [state, setState] = useState<GridChatState>(emptyChat);
132
- const [draft, setDraft] = useState("");
133
- const [writing, setWriting] = useState(false);
134
- const logRef = useRef<HTMLDivElement | null>(null);
135
- const busy = isBusy(state);
136
-
137
- // ⚠ THE UNUSED-POWER GUARD. `onApplyView`, `onUndoView` and `onRunScript` are wired by W37-T43
138
- // and W37-T44; naming them here keeps them REQUIRED props from the first mount, so C's wiring
139
- // lands with the shell rather than being remembered two tickets later. `void` is the honest
140
- // spelling of "held, not yet called" and it survives `noUnusedLocals`.
141
- // ⚠ WHERE EACH CALLBACK IS ACTUALLY REACHED, because saying so is the only thing that stops a
142
- // required prop becoming a decorative one: `onApplyView` from `send` (T43), `onUndoView` from the
143
- // Undo control in the foot row, `onRunScript` from `runScript` below, which `send` calls when the
144
- // host returns generated code (T44), `onWriteCells` from the confirm and the undo (T45, R10).
145
-
146
- // The transcript follows the newest turn. Guarded on the ref because the log is not rendered at
147
- // all while the conversation is empty (see the opening below).
148
- useEffect(() => {
149
- const log = logRef.current;
150
- if (log) log.scrollTop = log.scrollHeight;
151
- }, [state.turns.length, busy]);
152
-
153
- // β›” DECLARED BEFORE `send`, AND THE ORDER IS LOAD-BEARING RATHER THAN TIDY. `send`'s
154
- // dependency array names `runScript`, and a dependency array is evaluated AT RENDER, not
155
- // when the callback fires. With `runScript` declared after `send` that array reads a `const`
156
- // in its temporal dead zone and the panel throws `Cannot access 'runScript' before
157
- // initialization` on its FIRST paint. ⚠ `tsc` does not catch it: it is a runtime TDZ, and
158
- // the build was green with the crash in it.
159
- /**
160
- * ⭐ W37-T44 β€” THE CHAT WRITES THE CUSTOM VIEW'S CODE AND RUNS IT.
161
- * β›” THE SANDBOX IS NOT WIDENED TO MAKE A GENERATED SCRIPT WORK. `onRunScript` is the host's
162
- * ordinary run door, the same one a hand-typed script goes through, so a script the chat wrote
163
- * has exactly the powers a person's own script has and no more. A failure is REPORTED and the
164
- * code is left in the editor to be fixed by hand, never blanked.
165
- */
166
- const runScript = useCallback((code: string) => {
167
- void (async () => {
168
- try {
169
- const result = await onRunScript(code);
170
- setState((s) => noted(s, runSentence(result)));
171
- } catch (err) {
172
- const why = err instanceof Error && err.message ? err.message : "";
173
- setState((s) => noted(s, runSentence({ ok: false, error: why })));
174
- }
175
- })();
176
- }, [onRunScript]);
177
-
178
- const send = useCallback(() => {
179
- const said = draft.trim();
180
- if (!said || busy) return;
181
- setState((s) => asked(s, said));
182
- setDraft("");
183
-
184
- // ⭐⭐ W37-T42/T43/T44 β€” READ THE SENTENCE BEFORE SPENDING ANYTHING ON IT.
185
- // β›” THE REFUSAL BRANCH IS THE POINT OF T42 AND IT COSTS NOTHING. D-339's defect is an agent
186
- // that cannot read the database answering from words alone and inventing a number. The panel
187
- // HOLDS the schema, so a question naming a field this database does not have is answered here,
188
- // truthfully, without a model call that could only guess.
189
- const intent = readIntent(schema, databaseLabel, said);
190
- if (intent.refusal) {
191
- setState((s) => answered(s, said, { text: intent.refusal!, unanswerable: true }));
192
- return;
193
- }
194
- // ⚠ ...and a question the panel already knows the answer to is not a paid round trip either.
195
- if (intent.localAnswer) {
196
- setState((s) => answered(s, said, { text: intent.localAnswer! }));
197
- return;
198
- }
199
- if (intent.kind === "view") {
200
- // T43: the VIEW changes through the host's callback (C6), and what could NOT be expressed is
201
- // named rather than dropped [[assistant-build-view-is-a-subset]].
202
- if (intent.view) onApplyView(intent.view);
203
- const applied = intent.view
204
- ? "The view has been changed. Ask again or press Undo to put it back."
205
- : "I could not tell which field you meant, so the view is unchanged.";
206
- setState((s) => answered(s, said, {
207
- text: intent.cannot ? `${applied} ${intent.cannot}` : applied,
208
- }));
209
- return;
210
- }
211
-
212
- void (async () => {
213
- try {
214
- const answer = await onDescribe(said);
215
- // β›” THE PROPOSAL BRANCH IS HERE AND NOT IN THE HOST. A host that returned edits and also
216
- // wrote them would make the confirm cosmetic; the panel decides that edits mean "show the
217
- // person first", so there is exactly one place that decision can be got wrong.
218
- // ⚠ NO CAST. `GridChatAnswer.edits` is a declared part of the contract now, so the host
219
- // reads the same channel this line does; it used to be an `as` and the two could drift.
220
- const edits = answer?.edits;
221
- setState((s) => (canEdit && Array.isArray(edits) && edits.length
222
- ? proposedEdits(s, said, answer.text, edits)
223
- : answered(s, said, answer)));
224
- // β›” W37-T44 β€” AND THIS BRANCH IS THE WHOLE POINT OF THE TICKET. The first draft classified
225
- // a build request correctly and then had nothing consume the classification: `runScript`
226
- // was defined and `void`ed, so `onRunScript` was unreachable from every path while the
227
- // ticket claimed it routed. That is [[reachable-is-not-the-same-as-built]], and `void` is
228
- // what hid it from tsc. The host authors the code; the panel runs it and reports.
229
- if (typeof answer?.script === "string" && answer.script.trim())
230
- runScript(answer.script);
231
- } catch (err) {
232
- const sentence = err instanceof Error ? err.message : "";
233
- setState((s) => failed(s, said, sentence));
234
- }
235
- })();
236
- }, [draft, busy, canEdit, onDescribe, onApplyView, runScript, schema, databaseLabel]);
237
-
238
- const confirmWrite = useCallback((edits: GridChatEdit[]) => {
239
- if (writing) return;
240
- setWriting(true);
241
- void (async () => {
242
- try {
243
- await onWriteCells(edits);
244
- // β›” `wrote` rather than `noted`: the note it appends CARRIES THE INVERSE, built from the
245
- // `before` values the person confirmed. An undo assembled after the write would have
246
- // nothing left to read [[capture-the-inverse-before-the-write]].
247
- setState((s) => wrote(s, edits));
248
- } catch (err) {
249
- const sentence = err instanceof Error && err.message
250
- ? err.message
251
- : "That write was refused, so nothing changed.";
252
- setState((s) => noted(s, sentence));
253
- } finally {
254
- setWriting(false);
255
- }
256
- })();
257
- }, [onWriteCells, writing]);
258
-
259
- if (!open) return null;
260
- return (
261
- <GridChatView
262
- state={state}
263
- draft={draft}
264
- writing={writing}
265
- databaseLabel={databaseLabel}
266
- schema={schema}
267
- rowCount={rowCount}
268
- canEdit={canEdit}
269
- logRef={logRef}
270
- onClose={onClose}
271
- onDraft={setDraft}
272
- onSend={send}
273
- onUndoView={onUndoView}
274
- onConfirmWrite={confirmWrite}
275
- onDeclineWrite={() => setState((s) => noted(s, "Nothing was written."))}
276
- />
277
- );
278
- }
279
-
280
- /**
281
- * ⭐⭐ THE PRESENTATIONAL HALF, AND IT IS SPLIT OUT FOR A REASON A GATE CAN USE.
282
- *
283
- * `<GridChat>` owns the state; this owns the pixels and takes the state as a prop. That split is
284
- * what makes T40's `done-when` observable at all: the only renderer available in this repo is
285
- * `react-dom/server`, which fires no events and runs no effects, so a gate can never DRIVE a
286
- * stateful component into its in-flight or error state. It can render THIS one into any state it
287
- * likes, because the state is an argument.
288
- *
289
- * β›” THE HOST NEVER IMPORTS THIS. `GridChat` is the default export and the contract C6 describes;
290
- * every prop on it is required, and nothing here weakens that. Splitting the render out is the
291
- * opposite of an optional prop: it adds a seam for the gate without adding a way for a mount to
292
- * be silently inert.
293
- */
294
- export function GridChatView(props: {
295
- state: GridChatState;
296
- draft: string;
297
- writing: boolean;
298
- databaseLabel: string;
299
- schema: GridChatField[];
300
- rowCount: number;
301
- canEdit: boolean;
302
- // ⚠ Typed exactly as `useRef<HTMLDivElement | null>(null)` produces it, and OPTIONAL only
303
- // here: a server render has no DOM to scroll, so the gate omits it. The stateful shell
304
- // above always passes one.
305
- logRef?: React.Ref<HTMLDivElement>;
306
- onClose: () => void;
307
- onDraft: (text: string) => void;
308
- onSend: () => void;
309
- onUndoView: () => void;
310
- onConfirmWrite: (edits: GridChatEdit[]) => void;
311
- onDeclineWrite: () => void;
312
- }) {
313
- const {
314
- state, draft, writing, databaseLabel, schema, rowCount, canEdit, logRef,
315
- onClose, onDraft, onSend, onUndoView, onConfirmWrite, onDeclineWrite,
316
- } = props;
317
- const busy = isBusy(state);
318
- const hint = composerHint(databaseLabel, canEdit);
319
-
320
- const composer = (
321
- <div className="cg-chat-composer">
322
- <textarea
323
- className="cg-chat-input"
324
- value={draft}
325
- rows={2}
326
- placeholder={hint}
327
- aria-label={hint}
328
- disabled={busy}
329
- onChange={(e) => onDraft(e.target.value)}
330
- onKeyDown={(e) => {
331
- if (e.key === "Enter" && !e.shiftKey) {
332
- e.preventDefault();
333
- onSend();
334
- }
335
- }}
336
- />
337
- <div className="cg-chat-composer-foot">
338
- {/* ⚠ THE SCOPE LINE, NOT A DISCLAIMER. It says what the chat is reading, which is the one
339
- thing a person cannot tell by looking at a docked panel. */}
340
- <span className="cg-chat-scope">
341
- {rowCount === 1 ? "1 record" : `${rowCount} records`}
342
- {schema.length ? `, ${schema.length === 1 ? "1 field" : `${schema.length} fields`}` : ""}
343
- </span>
344
- <span className="cg-chat-spacer" />
345
- {/* ⭐ W37-T43's "and the change is undoable", as a control rather than a promise. It sits
346
- beside Send because that is where the person is after asking for a view change, and it
347
- calls the host's own undo so there is one place a view can be put back. */}
348
- <button
349
- type="button"
350
- className="cg-chat-ghost"
351
- onClick={onUndoView}
352
- title="Put the view back the way it was"
353
- >
354
- Undo view
355
- </button>
356
- <button
357
- type="button"
358
- className="cg-chat-send"
359
- onClick={onSend}
360
- disabled={busy || draft.trim() === ""}
361
- aria-label="Send"
362
- title="Send"
363
- >
364
- <SendMark />
365
- </button>
366
- </div>
367
- </div>
368
- );
369
-
370
- return (
371
- <aside className="cg-chat" aria-label={`Chat about ${databaseLabel}`}>
372
- <header className="cg-chat-head">
373
- <span className="cg-chat-title">{databaseLabel}</span>
374
- <button
375
- type="button"
376
- className="cg-chat-close"
377
- onClick={onClose}
378
- aria-label="Close the chat"
379
- title="Close the chat"
380
- >
381
- <svg viewBox="0 0 16 16" width="13" height="13" aria-hidden="true" fill="none">
382
- <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5"
383
- strokeLinecap="round" />
384
- </svg>
385
- </button>
386
- </header>
387
-
388
- {/* β›” THE LOG IS NOT RENDERED AT ALL WHEN EMPTY, and `hidden` would be the bug. `.cg-chat-log`
389
- sets `display: flex`, and an author rule beats the user-agent `[hidden] { display: none }`
390
- whatever its specificity. `hidden` would take the log out of the accessibility tree and
391
- leave it PAINTED: an empty flex band shoving the centred opening off centre. That exact
392
- defect was found and written down one wave ago in `AutomationChat`, and it is invisible to
393
- any assertion that reads markup as text [[ui-invisible-to-assertions]]. */}
394
- {state.turns.length ? (
395
- <div className="cg-chat-log" ref={logRef}>
396
- {state.turns.map((turn, i) => (
397
- <div className="cg-chat-turn" key={i}>
398
- <div
399
- className={
400
- "cg-chat-msg " +
401
- (turn.error ? "is-error" : turn.who === "you" ? "is-you"
402
- : turn.who === "note" ? "is-note" : "is-assistant")
403
- }
404
- >
405
- {turn.text}
406
- </div>
407
-
408
- {/* ⭐ UNDO, OFFERED FROM THE TRANSCRIPT. R10 says the person confirms before a write;
409
- this is the other half of taking them seriously. A confirmed write they did not
410
- mean stays reversible in the place they are already looking, rather than behind a
411
- toast that faded while they read the result.
412
- β›” IT ROUTES THROUGH THE SAME `onWriteCells` the original went through, so the
413
- undo passes the caller's permission wall exactly as the write did. An undo with
414
- its own door would be a second write path, and the one nobody tested. */}
415
- {canEdit && turn.undo?.length ? (
416
- <div className="cg-chat-undo">
417
- <button
418
- type="button"
419
- className="cg-chat-ghost"
420
- disabled={writing}
421
- onClick={() => onConfirmWrite(turn.undo || [])}
422
- >
423
- Put it back
424
- </button>
425
- </div>
426
- ) : null}
427
-
428
- {/* β›”β›” R10 ON SCREEN: EXACTLY WHAT WILL BE WRITTEN, BEFORE ANYTHING IS. Not a count,
429
- not a summary of a summary. The person sees the record, the field, the old value
430
- and the new one, and nothing reaches `onWriteCells` until they press Write. */}
431
- {/* β›”β›” `canEdit` IS CHECKED HERE, IN THE VIEW, AND NOT ONLY WHERE THE PROPOSAL IS
432
- BUILT. The stateful shell already refuses to build a proposal for a caller who
433
- may not write, so this looked redundant and was left out of the first draft; the
434
- gate caught it. The wall has to sit where the CONTROL is drawn, because the view
435
- renders whatever state it is handed and a second caller, a replayed transcript or
436
- a permission that changed mid-session would otherwise paint a Write button for
437
- somebody the store is going to refuse [[permitted-is-not-answerable]]. A wall
438
- that depends on its caller's discipline is not a wall. */}
439
- {canEdit && turn.edits?.length ? (
440
- <div className="cg-chat-edits">
441
- <p className="cg-chat-edits-head">{editSummary(turn.edits)}</p>
442
- <table className="cg-chat-edits-table">
443
- <thead>
444
- <tr><th>Record</th><th>Field</th><th>Now</th><th>Would become</th></tr>
445
- </thead>
446
- <tbody>
447
- {turn.edits.map((edit, j) => (
448
- <tr key={j}>
449
- <td>{edit.rowLabel || edit.rowId}</td>
450
- <td>{edit.fieldLabel || edit.field}</td>
451
- <td className="cg-chat-before">{edit.before || "empty"}</td>
452
- <td className="cg-chat-after">{edit.after || "empty"}</td>
453
- </tr>
454
- ))}
455
- </tbody>
456
- </table>
457
- <div className="cg-chat-edits-act">
458
- <button
459
- type="button"
460
- className="cg-chat-ghost"
461
- disabled={writing}
462
- onClick={onDeclineWrite}
463
- >
464
- Leave it
465
- </button>
466
- <button
467
- type="button"
468
- className="cg-chat-go"
469
- disabled={writing}
470
- onClick={() => onConfirmWrite(turn.edits || [])}
471
- >
472
- {writing ? "Writing" : "Write these"}
473
- </button>
474
- </div>
475
- </div>
476
- ) : null}
477
- </div>
478
- ))}
479
-
480
- {/* ⚠ `.lp-spin` is the ONE loading mark in this application. A second spinner vocabulary
481
- in a new surface is how an app stops having one. */}
482
- {busy ? (
483
- <div className="cg-chat-pending" role="status">
484
- <span className="lp-spin" aria-hidden="true" />
485
- Reading {databaseLabel}
486
- </div>
487
- ) : null}
488
- </div>
489
- ) : null}
490
-
491
- {/* The centred opening, exactly the shape `AssistantPage` and `AutomationChat` already use.
492
- ⚠ NO DECORATIVE MARK: the reference image has a soft dot ring, and neither of this
493
- product's two existing chat surfaces does. A mark on the third one is the difference the
494
- owner would notice. */}
495
- {state.turns.length ? null : (
496
- <div className="cg-chat-opening">
497
- <h2 className="cg-chat-opening-h">How can I help?</h2>
498
- <p className="cg-chat-opening-p">
499
- {canEdit
500
- ? "Ask about the records in front of you, change what the view shows, or say what to change. Nothing is written until you confirm it."
501
- : "Ask about the records in front of you, or change what the view shows."}
502
- </p>
503
- {composer}
504
- </div>
505
- )}
506
-
507
- {/* ⚠ ONE composer const, rendered in exactly one place at a time. Two on screen at once is
508
- the defect this pattern exists to make impossible. */}
509
- {state.turns.length ? <div className="cg-chat-foot">{composer}</div> : null}
510
- </aside>
511
- );
512
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // customer-grid / GridChat.tsx β€” the docked chat for ANY database view (W37-T40, R2, R10, C6).
3
+ //
4
+ // Owner items 10 and 11 are ONE feature (ruling R2): the chat IS the builder. This is its shell β€”
5
+ // the conversation surface every later ticket in the lane hangs a power off. T42 gives it the
6
+ // schema to answer from, T43 the view controls, T44 the Custom View's code, T45 the confirmed
7
+ // record edit.
8
+ //
9
+ // β›”β›” IT REACHES INTO NOTHING. Contract C6: every action is a callback the host supplies, and
10
+ // EVERY PROP IS REQUIRED. An optional prop is how a panel ships mounted-but-inert β€” the feature is
11
+ // whole, the gate is green, and the one line that would have passed the callback was never
12
+ // written. This repo shipped five of those in a single wave. A required prop makes the omission a
13
+ // compile error in the mounting file, which is where a person can see it.
14
+ //
15
+ // ⚠ THE SHAPE IS THE ONE THIS PRODUCT ALREADY HAS, not a third chat look. `AutomationChat` and
16
+ // `AssistantPage` both render a centred opening while the transcript is empty, then a log with the
17
+ // SAME composer moved to the foot; `FieldAgentChat` reuses the same composer classes rather than
18
+ // drawing a second one. Copying that is not laziness, it is the reason the owner cannot tell which
19
+ // surface was built by whom.
20
+ //
21
+ // ⚠ NO `import.meta.env` ANYWHERE IN THIS FILE'S GRAPH, and the constraint is load-bearing rather
22
+ // than stylistic: the gate renders this component from a CommonJS build, and `import.meta` cannot
23
+ // be required from one. `AutomationChat`'s own header records that exact crash. The imports below
24
+ // are `react` + `./gridChat` + the stylesheet, and nothing else.
25
+ // ---------------------------------------------------------------------------
26
+
27
+ import { useCallback, useEffect, useRef, useState } from "react";
28
+
29
+ import {
30
+ answered,
31
+ asked,
32
+ composerHint,
33
+ editSummary,
34
+ emptyChat,
35
+ failed,
36
+ isBusy,
37
+ noted,
38
+ proposedEdits,
39
+ readIntent,
40
+ runSentence,
41
+ wrote,
42
+ } from "./gridChat";
43
+ import type {
44
+ GridChatAnswer,
45
+ GridChatEdit,
46
+ GridChatField,
47
+ GridChatRunResult,
48
+ GridChatState,
49
+ GridChatTurn,
50
+ } from "./gridChat";
51
+ import "./gridChat.css";
52
+
53
+ // ⭐ RE-EXPORTED SO THE MOUNTING FILE TAKES ONE IMPORT. The types live in `gridChat.ts` (they have
54
+ // to: the state machine is typed by them and that module must stay React-free), but a host that
55
+ // had to import the component from here and its types from there would be one refactor away from
56
+ // the two drifting. Published to C in mailbox E-4 as a single import line.
57
+ export type {
58
+ GridChatAnswer,
59
+ GridChatEdit,
60
+ GridChatField,
61
+ GridChatRunResult,
62
+ GridChatState,
63
+ GridChatTurn,
64
+ };
65
+
66
+ /**
67
+ * What the host asks the chat to do about the view. ⚠ DELIBERATELY NARROW: this is the vocabulary
68
+ * `assistant build_view` already speaks, minus what it cannot express. There is no `rhs` in that
69
+ * tool schema, so a field-versus-field condition is not sayable
70
+ * [[assistant-build-view-is-a-subset]] β€” W37-T43 has to SAY it cannot rather than fail quietly.
71
+ */
72
+ export interface GridChatViewSpec {
73
+ /**
74
+ * ⚠ RESERVED AND DELIBERATELY NOT POPULATED BY `readIntent` YET. The panel understands
75
+ * sort/group/colour from a sentence; a real FILTER needs the condition vocabulary the host owns,
76
+ * so this is the slot C fills rather than a field the panel quietly leaves empty. Named here so
77
+ * it reads as a contract with a known gap instead of a channel nobody noticed was dead
78
+ * [[flag-shipped-without-its-writer]].
79
+ */
80
+ filter?: unknown;
81
+ sortBy?: string;
82
+ groupBy?: string;
83
+ colorBy?: string;
84
+ }
85
+
86
+ export interface GridChatProps {
87
+ /** The host owns the toggle. The panel never closes itself except through `onClose`. */
88
+ open: boolean;
89
+ onClose: () => void;
90
+ /** What this chat is reading, in the person's words. Appears in the header and the placeholder. */
91
+ databaseLabel: string;
92
+ /** The columns the chat may reason about. The host decides; the chat never discovers. */
93
+ schema: GridChatField[];
94
+ rowCount: number;
95
+ /**
96
+ * β›” R10's BOUND, EXPRESSED AS AN AFFORDANCE. `false` means the edit power is not OFFERED, not
97
+ * that it is offered and then refused. The chat is not a privilege escalation: a caller whose
98
+ * own permissions would refuse the write must not be invited to compose one
99
+ * [[permitted-is-not-answerable]].
100
+ */
101
+ canEdit: boolean;
102
+ /** (a) answer a question about this database. */
103
+ onDescribe: (question: string) => Promise<GridChatAnswer>;
104
+ /** (b) change filter, sort, group or colour on the ACTIVE view. */
105
+ onApplyView: (spec: GridChatViewSpec) => void;
106
+ /** (b, undo half) put the view back the way it was. */
107
+ onUndoView: () => void;
108
+ /** (d) write the cells the person just confirmed. β›” Reached only from the confirm control. */
109
+ onWriteCells: (edits: GridChatEdit[]) => Promise<void>;
110
+ /** (c) run the Custom View's code and report what happened. */
111
+ onRunScript: (code: string) => Promise<GridChatRunResult>;
112
+ }
113
+
114
+ /** The send mark. β›” The Assistant's own path, point for point: a second arrow drawn slightly
115
+ * differently is precisely how two surfaces stop looking like one product. */
116
+ function SendMark() {
117
+ return (
118
+ <svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true" fill="none">
119
+ <path d="M8 13V3.6M4 7.4 8 3.4l4 4" stroke="currentColor" strokeWidth="1.5"
120
+ strokeLinecap="round" strokeLinejoin="round" />
121
+ </svg>
122
+ );
123
+ }
124
+
125
+ export default function GridChat(props: GridChatProps) {
126
+ const {
127
+ open, onClose, databaseLabel, schema, rowCount, canEdit,
128
+ onDescribe, onApplyView, onUndoView, onWriteCells, onRunScript,
129
+ } = props;
130
+
131
+ const [state, setState] = useState<GridChatState>(emptyChat);
132
+ const [draft, setDraft] = useState("");
133
+ const [writing, setWriting] = useState(false);
134
+ const logRef = useRef<HTMLDivElement | null>(null);
135
+ const busy = isBusy(state);
136
+
137
+ // ⚠ THE UNUSED-POWER GUARD. `onApplyView`, `onUndoView` and `onRunScript` are wired by W37-T43
138
+ // and W37-T44; naming them here keeps them REQUIRED props from the first mount, so C's wiring
139
+ // lands with the shell rather than being remembered two tickets later. `void` is the honest
140
+ // spelling of "held, not yet called" and it survives `noUnusedLocals`.
141
+ // ⚠ WHERE EACH CALLBACK IS ACTUALLY REACHED, because saying so is the only thing that stops a
142
+ // required prop becoming a decorative one: `onApplyView` from `send` (T43), `onUndoView` from the
143
+ // Undo control in the foot row, `onRunScript` from `runScript` below, which `send` calls when the
144
+ // host returns generated code (T44), `onWriteCells` from the confirm and the undo (T45, R10).
145
+
146
+ // The transcript follows the newest turn. Guarded on the ref because the log is not rendered at
147
+ // all while the conversation is empty (see the opening below).
148
+ useEffect(() => {
149
+ const log = logRef.current;
150
+ if (log) log.scrollTop = log.scrollHeight;
151
+ }, [state.turns.length, busy]);
152
+
153
+ // β›” DECLARED BEFORE `send`, AND THE ORDER IS LOAD-BEARING RATHER THAN TIDY. `send`'s
154
+ // dependency array names `runScript`, and a dependency array is evaluated AT RENDER, not
155
+ // when the callback fires. With `runScript` declared after `send` that array reads a `const`
156
+ // in its temporal dead zone and the panel throws `Cannot access 'runScript' before
157
+ // initialization` on its FIRST paint. ⚠ `tsc` does not catch it: it is a runtime TDZ, and
158
+ // the build was green with the crash in it.
159
+ /**
160
+ * ⭐ W37-T44 β€” THE CHAT WRITES THE CUSTOM VIEW'S CODE AND RUNS IT.
161
+ * β›” THE SANDBOX IS NOT WIDENED TO MAKE A GENERATED SCRIPT WORK. `onRunScript` is the host's
162
+ * ordinary run door, the same one a hand-typed script goes through, so a script the chat wrote
163
+ * has exactly the powers a person's own script has and no more. A failure is REPORTED and the
164
+ * code is left in the editor to be fixed by hand, never blanked.
165
+ */
166
+ const runScript = useCallback((code: string) => {
167
+ void (async () => {
168
+ try {
169
+ const result = await onRunScript(code);
170
+ setState((s) => noted(s, runSentence(result)));
171
+ } catch (err) {
172
+ const why = err instanceof Error && err.message ? err.message : "";
173
+ setState((s) => noted(s, runSentence({ ok: false, error: why })));
174
+ }
175
+ })();
176
+ }, [onRunScript]);
177
+
178
+ const send = useCallback(() => {
179
+ const said = draft.trim();
180
+ if (!said || busy) return;
181
+ setState((s) => asked(s, said));
182
+ setDraft("");
183
+
184
+ // ⭐⭐ W37-T42/T43/T44 β€” READ THE SENTENCE BEFORE SPENDING ANYTHING ON IT.
185
+ // β›” THE REFUSAL BRANCH IS THE POINT OF T42 AND IT COSTS NOTHING. D-339's defect is an agent
186
+ // that cannot read the database answering from words alone and inventing a number. The panel
187
+ // HOLDS the schema, so a question naming a field this database does not have is answered here,
188
+ // truthfully, without a model call that could only guess.
189
+ const intent = readIntent(schema, databaseLabel, said);
190
+ if (intent.refusal) {
191
+ setState((s) => answered(s, said, { text: intent.refusal!, unanswerable: true }));
192
+ return;
193
+ }
194
+ // ⚠ ...and a question the panel already knows the answer to is not a paid round trip either.
195
+ if (intent.localAnswer) {
196
+ setState((s) => answered(s, said, { text: intent.localAnswer! }));
197
+ return;
198
+ }
199
+ if (intent.kind === "view") {
200
+ // T43: the VIEW changes through the host's callback (C6), and what could NOT be expressed is
201
+ // named rather than dropped [[assistant-build-view-is-a-subset]].
202
+ if (intent.view) onApplyView(intent.view);
203
+ const applied = intent.view
204
+ ? "The view has been changed. Ask again or press Undo to put it back."
205
+ : "I could not tell which field you meant, so the view is unchanged.";
206
+ setState((s) => answered(s, said, {
207
+ text: intent.cannot ? `${applied} ${intent.cannot}` : applied,
208
+ }));
209
+ return;
210
+ }
211
+
212
+ void (async () => {
213
+ try {
214
+ const answer = await onDescribe(said);
215
+ // β›” THE PROPOSAL BRANCH IS HERE AND NOT IN THE HOST. A host that returned edits and also
216
+ // wrote them would make the confirm cosmetic; the panel decides that edits mean "show the
217
+ // person first", so there is exactly one place that decision can be got wrong.
218
+ // ⚠ NO CAST. `GridChatAnswer.edits` is a declared part of the contract now, so the host
219
+ // reads the same channel this line does; it used to be an `as` and the two could drift.
220
+ const edits = answer?.edits;
221
+ setState((s) => (canEdit && Array.isArray(edits) && edits.length
222
+ ? proposedEdits(s, said, answer.text, edits)
223
+ : answered(s, said, answer)));
224
+ // β›” W37-T44 β€” AND THIS BRANCH IS THE WHOLE POINT OF THE TICKET. The first draft classified
225
+ // a build request correctly and then had nothing consume the classification: `runScript`
226
+ // was defined and `void`ed, so `onRunScript` was unreachable from every path while the
227
+ // ticket claimed it routed. That is [[reachable-is-not-the-same-as-built]], and `void` is
228
+ // what hid it from tsc. The host authors the code; the panel runs it and reports.
229
+ if (typeof answer?.script === "string" && answer.script.trim())
230
+ runScript(answer.script);
231
+ } catch (err) {
232
+ const sentence = err instanceof Error ? err.message : "";
233
+ setState((s) => failed(s, said, sentence));
234
+ }
235
+ })();
236
+ }, [draft, busy, canEdit, onDescribe, onApplyView, runScript, schema, databaseLabel]);
237
+
238
+ const confirmWrite = useCallback((edits: GridChatEdit[]) => {
239
+ if (writing) return;
240
+ setWriting(true);
241
+ void (async () => {
242
+ try {
243
+ await onWriteCells(edits);
244
+ // β›” `wrote` rather than `noted`: the note it appends CARRIES THE INVERSE, built from the
245
+ // `before` values the person confirmed. An undo assembled after the write would have
246
+ // nothing left to read [[capture-the-inverse-before-the-write]].
247
+ setState((s) => wrote(s, edits));
248
+ } catch (err) {
249
+ const sentence = err instanceof Error && err.message
250
+ ? err.message
251
+ : "That write was refused, so nothing changed.";
252
+ setState((s) => noted(s, sentence));
253
+ } finally {
254
+ setWriting(false);
255
+ }
256
+ })();
257
+ }, [onWriteCells, writing]);
258
+
259
+ if (!open) return null;
260
+ return (
261
+ <GridChatView
262
+ state={state}
263
+ draft={draft}
264
+ writing={writing}
265
+ databaseLabel={databaseLabel}
266
+ schema={schema}
267
+ rowCount={rowCount}
268
+ canEdit={canEdit}
269
+ logRef={logRef}
270
+ onClose={onClose}
271
+ onDraft={setDraft}
272
+ onSend={send}
273
+ onUndoView={onUndoView}
274
+ onConfirmWrite={confirmWrite}
275
+ onDeclineWrite={() => setState((s) => noted(s, "Nothing was written."))}
276
+ />
277
+ );
278
+ }
279
+
280
+ /**
281
+ * ⭐⭐ THE PRESENTATIONAL HALF, AND IT IS SPLIT OUT FOR A REASON A GATE CAN USE.
282
+ *
283
+ * `<GridChat>` owns the state; this owns the pixels and takes the state as a prop. That split is
284
+ * what makes T40's `done-when` observable at all: the only renderer available in this repo is
285
+ * `react-dom/server`, which fires no events and runs no effects, so a gate can never DRIVE a
286
+ * stateful component into its in-flight or error state. It can render THIS one into any state it
287
+ * likes, because the state is an argument.
288
+ *
289
+ * β›” THE HOST NEVER IMPORTS THIS. `GridChat` is the default export and the contract C6 describes;
290
+ * every prop on it is required, and nothing here weakens that. Splitting the render out is the
291
+ * opposite of an optional prop: it adds a seam for the gate without adding a way for a mount to
292
+ * be silently inert.
293
+ */
294
+ export function GridChatView(props: {
295
+ state: GridChatState;
296
+ draft: string;
297
+ writing: boolean;
298
+ databaseLabel: string;
299
+ schema: GridChatField[];
300
+ rowCount: number;
301
+ canEdit: boolean;
302
+ // ⚠ Typed exactly as `useRef<HTMLDivElement | null>(null)` produces it, and OPTIONAL only
303
+ // here: a server render has no DOM to scroll, so the gate omits it. The stateful shell
304
+ // above always passes one.
305
+ logRef?: React.Ref<HTMLDivElement>;
306
+ onClose: () => void;
307
+ onDraft: (text: string) => void;
308
+ onSend: () => void;
309
+ onUndoView: () => void;
310
+ onConfirmWrite: (edits: GridChatEdit[]) => void;
311
+ onDeclineWrite: () => void;
312
+ }) {
313
+ const {
314
+ state, draft, writing, databaseLabel, schema, rowCount, canEdit, logRef,
315
+ onClose, onDraft, onSend, onUndoView, onConfirmWrite, onDeclineWrite,
316
+ } = props;
317
+ const busy = isBusy(state);
318
+ const hint = composerHint(databaseLabel, canEdit);
319
+
320
+ const composer = (
321
+ <div className="cg-chat-composer">
322
+ <textarea
323
+ className="cg-chat-input"
324
+ value={draft}
325
+ rows={2}
326
+ placeholder={hint}
327
+ aria-label={hint}
328
+ disabled={busy}
329
+ onChange={(e) => onDraft(e.target.value)}
330
+ onKeyDown={(e) => {
331
+ if (e.key === "Enter" && !e.shiftKey) {
332
+ e.preventDefault();
333
+ onSend();
334
+ }
335
+ }}
336
+ />
337
+ <div className="cg-chat-composer-foot">
338
+ {/* ⚠ THE SCOPE LINE, NOT A DISCLAIMER. It says what the chat is reading, which is the one
339
+ thing a person cannot tell by looking at a docked panel. */}
340
+ <span className="cg-chat-scope">
341
+ {rowCount === 1 ? "1 record" : `${rowCount} records`}
342
+ {schema.length ? `, ${schema.length === 1 ? "1 field" : `${schema.length} fields`}` : ""}
343
+ </span>
344
+ <span className="cg-chat-spacer" />
345
+ {/* ⭐ W37-T43's "and the change is undoable", as a control rather than a promise. It sits
346
+ beside Send because that is where the person is after asking for a view change, and it
347
+ calls the host's own undo so there is one place a view can be put back. */}
348
+ <button
349
+ type="button"
350
+ className="cg-chat-ghost"
351
+ onClick={onUndoView}
352
+ title="Put the view back the way it was"
353
+ >
354
+ Undo view
355
+ </button>
356
+ <button
357
+ type="button"
358
+ className="cg-chat-send"
359
+ onClick={onSend}
360
+ disabled={busy || draft.trim() === ""}
361
+ aria-label="Send"
362
+ title="Send"
363
+ >
364
+ <SendMark />
365
+ </button>
366
+ </div>
367
+ </div>
368
+ );
369
+
370
+ return (
371
+ <aside className="cg-chat" aria-label={`Chat about ${databaseLabel}`}>
372
+ <header className="cg-chat-head">
373
+ <span className="cg-chat-title">{databaseLabel}</span>
374
+ <button
375
+ type="button"
376
+ className="cg-chat-close"
377
+ onClick={onClose}
378
+ aria-label="Close the chat"
379
+ title="Close the chat"
380
+ >
381
+ <svg viewBox="0 0 16 16" width="13" height="13" aria-hidden="true" fill="none">
382
+ <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5"
383
+ strokeLinecap="round" />
384
+ </svg>
385
+ </button>
386
+ </header>
387
+
388
+ {/* β›” THE LOG IS NOT RENDERED AT ALL WHEN EMPTY, and `hidden` would be the bug. `.cg-chat-log`
389
+ sets `display: flex`, and an author rule beats the user-agent `[hidden] { display: none }`
390
+ whatever its specificity. `hidden` would take the log out of the accessibility tree and
391
+ leave it PAINTED: an empty flex band shoving the centred opening off centre. That exact
392
+ defect was found and written down one wave ago in `AutomationChat`, and it is invisible to
393
+ any assertion that reads markup as text [[ui-invisible-to-assertions]]. */}
394
+ {state.turns.length ? (
395
+ <div className="cg-chat-log" ref={logRef}>
396
+ {state.turns.map((turn, i) => (
397
+ <div className="cg-chat-turn" key={i}>
398
+ <div
399
+ className={
400
+ "cg-chat-msg " +
401
+ (turn.error ? "is-error" : turn.who === "you" ? "is-you"
402
+ : turn.who === "note" ? "is-note" : "is-assistant")
403
+ }
404
+ >
405
+ {turn.text}
406
+ </div>
407
+
408
+ {/* ⭐ UNDO, OFFERED FROM THE TRANSCRIPT. R10 says the person confirms before a write;
409
+ this is the other half of taking them seriously. A confirmed write they did not
410
+ mean stays reversible in the place they are already looking, rather than behind a
411
+ toast that faded while they read the result.
412
+ β›” IT ROUTES THROUGH THE SAME `onWriteCells` the original went through, so the
413
+ undo passes the caller's permission wall exactly as the write did. An undo with
414
+ its own door would be a second write path, and the one nobody tested. */}
415
+ {canEdit && turn.undo?.length ? (
416
+ <div className="cg-chat-undo">
417
+ <button
418
+ type="button"
419
+ className="cg-chat-ghost"
420
+ disabled={writing}
421
+ onClick={() => onConfirmWrite(turn.undo || [])}
422
+ >
423
+ Put it back
424
+ </button>
425
+ </div>
426
+ ) : null}
427
+
428
+ {/* β›”β›” R10 ON SCREEN: EXACTLY WHAT WILL BE WRITTEN, BEFORE ANYTHING IS. Not a count,
429
+ not a summary of a summary. The person sees the record, the field, the old value
430
+ and the new one, and nothing reaches `onWriteCells` until they press Write. */}
431
+ {/* β›”β›” `canEdit` IS CHECKED HERE, IN THE VIEW, AND NOT ONLY WHERE THE PROPOSAL IS
432
+ BUILT. The stateful shell already refuses to build a proposal for a caller who
433
+ may not write, so this looked redundant and was left out of the first draft; the
434
+ gate caught it. The wall has to sit where the CONTROL is drawn, because the view
435
+ renders whatever state it is handed and a second caller, a replayed transcript or
436
+ a permission that changed mid-session would otherwise paint a Write button for
437
+ somebody the store is going to refuse [[permitted-is-not-answerable]]. A wall
438
+ that depends on its caller's discipline is not a wall. */}
439
+ {canEdit && turn.edits?.length ? (
440
+ <div className="cg-chat-edits">
441
+ <p className="cg-chat-edits-head">{editSummary(turn.edits)}</p>
442
+ <table className="cg-chat-edits-table">
443
+ <thead>
444
+ <tr><th>Record</th><th>Field</th><th>Now</th><th>Would become</th></tr>
445
+ </thead>
446
+ <tbody>
447
+ {turn.edits.map((edit, j) => (
448
+ <tr key={j}>
449
+ <td>{edit.rowLabel || edit.rowId}</td>
450
+ <td>{edit.fieldLabel || edit.field}</td>
451
+ <td className="cg-chat-before">{edit.before || "empty"}</td>
452
+ <td className="cg-chat-after">{edit.after || "empty"}</td>
453
+ </tr>
454
+ ))}
455
+ </tbody>
456
+ </table>
457
+ <div className="cg-chat-edits-act">
458
+ <button
459
+ type="button"
460
+ className="cg-chat-ghost"
461
+ disabled={writing}
462
+ onClick={onDeclineWrite}
463
+ >
464
+ Leave it
465
+ </button>
466
+ <button
467
+ type="button"
468
+ className="cg-chat-go"
469
+ disabled={writing}
470
+ onClick={() => onConfirmWrite(turn.edits || [])}
471
+ >
472
+ {writing ? "Writing" : "Write these"}
473
+ </button>
474
+ </div>
475
+ </div>
476
+ ) : null}
477
+ </div>
478
+ ))}
479
+
480
+ {/* ⚠ `.lp-spin` is the ONE loading mark in this application. A second spinner vocabulary
481
+ in a new surface is how an app stops having one. */}
482
+ {busy ? (
483
+ <div className="cg-chat-pending" role="status">
484
+ <span className="lp-spin" aria-hidden="true" />
485
+ Reading {databaseLabel}
486
+ </div>
487
+ ) : null}
488
+ </div>
489
+ ) : null}
490
+
491
+ {/* The centred opening, exactly the shape `AssistantPage` and `AutomationChat` already use.
492
+ ⚠ NO DECORATIVE MARK: the reference image has a soft dot ring, and neither of this
493
+ product's two existing chat surfaces does. A mark on the third one is the difference the
494
+ owner would notice. */}
495
+ {state.turns.length ? null : (
496
+ <div className="cg-chat-opening">
497
+ <h2 className="cg-chat-opening-h">How can I help?</h2>
498
+ <p className="cg-chat-opening-p">
499
+ {canEdit
500
+ ? "Ask about the records in front of you, change what the view shows, or say what to change. Nothing is written until you confirm it."
501
+ : "Ask about the records in front of you, or change what the view shows."}
502
+ </p>
503
+ {composer}
504
+ </div>
505
+ )}
506
+
507
+ {/* ⚠ ONE composer const, rendered in exactly one place at a time. Two on screen at once is
508
+ the defect this pattern exists to make impossible. */}
509
+ {state.turns.length ? <div className="cg-chat-foot">{composer}</div> : null}
510
+ </aside>
511
+ );
512
+ }
web/src/customer-grid/ImportDialog.css CHANGED
@@ -1,154 +1,154 @@
1
- /* customer-grid / ImportDialog.css β€” WAVE-29 T25 (owner item 6).
2
- Tokens only (`--lp-*`): this file may not invent a colour, and `index.css` is another
3
- session's fence, so the dialog's own styles live beside its component. */
4
-
5
- .cg-import-scrim {
6
- position: fixed;
7
- inset: 0;
8
- z-index: 60;
9
- display: flex;
10
- align-items: center;
11
- justify-content: center;
12
- background: rgba(32, 36, 51, 0.28);
13
- padding: 24px;
14
- }
15
-
16
- .cg-import {
17
- display: flex;
18
- flex-direction: column;
19
- width: min(560px, 100%);
20
- max-height: min(80vh, 720px);
21
- background: var(--lp-bg);
22
- border: 1px solid var(--lp-line);
23
- border-radius: var(--lp-r-lg);
24
- box-shadow: 0 12px 32px rgba(32, 36, 51, 0.18);
25
- overflow: hidden;
26
- }
27
-
28
- .cg-import-head {
29
- display: flex;
30
- align-items: center;
31
- justify-content: space-between;
32
- gap: 12px;
33
- padding: 14px 16px;
34
- border-bottom: 1px solid var(--lp-line);
35
- }
36
-
37
- .cg-import-head h2 {
38
- margin: 0;
39
- font-size: var(--lp-fs-md);
40
- font-weight: 600;
41
- color: var(--lp-ink);
42
- }
43
-
44
- .cg-import-x {
45
- border: 0;
46
- background: none;
47
- color: var(--lp-muted);
48
- font-size: var(--lp-fs-lg);
49
- line-height: 1;
50
- cursor: pointer;
51
- padding: 2px 6px;
52
- }
53
-
54
- .cg-import-x:hover {
55
- color: var(--lp-ink);
56
- }
57
-
58
- .cg-import-body {
59
- padding: 14px 16px;
60
- overflow: auto;
61
- }
62
-
63
- .cg-import-lede {
64
- margin: 0 0 8px;
65
- font-size: var(--lp-fs-sm);
66
- color: var(--lp-ink);
67
- }
68
-
69
- .cg-import-note {
70
- margin: 0 0 12px;
71
- font-size: var(--lp-fs-xs);
72
- color: var(--lp-muted);
73
- }
74
-
75
- .cg-import-file {
76
- font-size: var(--lp-fs-sm);
77
- }
78
-
79
- /* The mapping list: the spreadsheet's column on the left, this database's field on the right,
80
- so the eye reads it as "this becomes that" rather than as a form. */
81
- .cg-import-map {
82
- display: flex;
83
- flex-direction: column;
84
- gap: 6px;
85
- }
86
-
87
- .cg-import-row {
88
- display: grid;
89
- grid-template-columns: 1fr 200px;
90
- align-items: center;
91
- gap: 10px;
92
- }
93
-
94
- .cg-import-col {
95
- font-size: var(--lp-fs-sm);
96
- color: var(--lp-ink);
97
- overflow: hidden;
98
- text-overflow: ellipsis;
99
- white-space: nowrap;
100
- }
101
-
102
- .cg-import-row select {
103
- font-family: inherit;
104
- font-size: var(--lp-fs-xs);
105
- padding: 4px 6px;
106
- border: 1px solid var(--lp-line);
107
- border-radius: var(--lp-r-sm);
108
- background: var(--lp-bg);
109
- color: var(--lp-ink);
110
- }
111
-
112
- /* A refusal is not an error state to be styled red-alert; it is a list of things to fix, so it
113
- takes the yellow tint the rest of the product uses for "look at this before continuing". */
114
- .cg-import-problems {
115
- margin-top: 12px;
116
- padding: 10px 12px;
117
- border: 1px solid var(--lp-yellow);
118
- border-radius: var(--lp-r-sm);
119
- background: var(--lp-yellow-tint);
120
- color: var(--lp-yellow-deep);
121
- font-size: var(--lp-fs-xs);
122
- }
123
-
124
- .cg-import-problems ul {
125
- margin: 6px 0;
126
- padding-left: 18px;
127
- }
128
-
129
- .cg-import-problems p {
130
- margin: 6px 0 0;
131
- }
132
-
133
- .cg-import-error {
134
- margin: 0;
135
- padding: 10px 16px;
136
- background: var(--lp-red-tint);
137
- color: var(--lp-red-deep);
138
- font-size: var(--lp-fs-xs);
139
- }
140
-
141
- .cg-import-foot {
142
- display: flex;
143
- align-items: center;
144
- justify-content: flex-end;
145
- gap: 8px;
146
- padding: 12px 16px;
147
- border-top: 1px solid var(--lp-line);
148
- }
149
-
150
- .cg-import-count {
151
- margin-right: auto;
152
- font-size: var(--lp-fs-xs);
153
- color: var(--lp-muted);
154
- }
 
1
+ /* customer-grid / ImportDialog.css β€” WAVE-29 T25 (owner item 6).
2
+ Tokens only (`--lp-*`): this file may not invent a colour, and `index.css` is another
3
+ session's fence, so the dialog's own styles live beside its component. */
4
+
5
+ .cg-import-scrim {
6
+ position: fixed;
7
+ inset: 0;
8
+ z-index: 60;
9
+ display: flex;
10
+ align-items: center;
11
+ justify-content: center;
12
+ background: rgba(32, 36, 51, 0.28);
13
+ padding: 24px;
14
+ }
15
+
16
+ .cg-import {
17
+ display: flex;
18
+ flex-direction: column;
19
+ width: min(560px, 100%);
20
+ max-height: min(80vh, 720px);
21
+ background: var(--lp-bg);
22
+ border: 1px solid var(--lp-line);
23
+ border-radius: var(--lp-r-lg);
24
+ box-shadow: 0 12px 32px rgba(32, 36, 51, 0.18);
25
+ overflow: hidden;
26
+ }
27
+
28
+ .cg-import-head {
29
+ display: flex;
30
+ align-items: center;
31
+ justify-content: space-between;
32
+ gap: 12px;
33
+ padding: 14px 16px;
34
+ border-bottom: 1px solid var(--lp-line);
35
+ }
36
+
37
+ .cg-import-head h2 {
38
+ margin: 0;
39
+ font-size: var(--lp-fs-md);
40
+ font-weight: 600;
41
+ color: var(--lp-ink);
42
+ }
43
+
44
+ .cg-import-x {
45
+ border: 0;
46
+ background: none;
47
+ color: var(--lp-muted);
48
+ font-size: var(--lp-fs-lg);
49
+ line-height: 1;
50
+ cursor: pointer;
51
+ padding: 2px 6px;
52
+ }
53
+
54
+ .cg-import-x:hover {
55
+ color: var(--lp-ink);
56
+ }
57
+
58
+ .cg-import-body {
59
+ padding: 14px 16px;
60
+ overflow: auto;
61
+ }
62
+
63
+ .cg-import-lede {
64
+ margin: 0 0 8px;
65
+ font-size: var(--lp-fs-sm);
66
+ color: var(--lp-ink);
67
+ }
68
+
69
+ .cg-import-note {
70
+ margin: 0 0 12px;
71
+ font-size: var(--lp-fs-xs);
72
+ color: var(--lp-muted);
73
+ }
74
+
75
+ .cg-import-file {
76
+ font-size: var(--lp-fs-sm);
77
+ }
78
+
79
+ /* The mapping list: the spreadsheet's column on the left, this database's field on the right,
80
+ so the eye reads it as "this becomes that" rather than as a form. */
81
+ .cg-import-map {
82
+ display: flex;
83
+ flex-direction: column;
84
+ gap: 6px;
85
+ }
86
+
87
+ .cg-import-row {
88
+ display: grid;
89
+ grid-template-columns: 1fr 200px;
90
+ align-items: center;
91
+ gap: 10px;
92
+ }
93
+
94
+ .cg-import-col {
95
+ font-size: var(--lp-fs-sm);
96
+ color: var(--lp-ink);
97
+ overflow: hidden;
98
+ text-overflow: ellipsis;
99
+ white-space: nowrap;
100
+ }
101
+
102
+ .cg-import-row select {
103
+ font-family: inherit;
104
+ font-size: var(--lp-fs-xs);
105
+ padding: 4px 6px;
106
+ border: 1px solid var(--lp-line);
107
+ border-radius: var(--lp-r-sm);
108
+ background: var(--lp-bg);
109
+ color: var(--lp-ink);
110
+ }
111
+
112
+ /* A refusal is not an error state to be styled red-alert; it is a list of things to fix, so it
113
+ takes the yellow tint the rest of the product uses for "look at this before continuing". */
114
+ .cg-import-problems {
115
+ margin-top: 12px;
116
+ padding: 10px 12px;
117
+ border: 1px solid var(--lp-yellow);
118
+ border-radius: var(--lp-r-sm);
119
+ background: var(--lp-yellow-tint);
120
+ color: var(--lp-yellow-deep);
121
+ font-size: var(--lp-fs-xs);
122
+ }
123
+
124
+ .cg-import-problems ul {
125
+ margin: 6px 0;
126
+ padding-left: 18px;
127
+ }
128
+
129
+ .cg-import-problems p {
130
+ margin: 6px 0 0;
131
+ }
132
+
133
+ .cg-import-error {
134
+ margin: 0;
135
+ padding: 10px 16px;
136
+ background: var(--lp-red-tint);
137
+ color: var(--lp-red-deep);
138
+ font-size: var(--lp-fs-xs);
139
+ }
140
+
141
+ .cg-import-foot {
142
+ display: flex;
143
+ align-items: center;
144
+ justify-content: flex-end;
145
+ gap: 8px;
146
+ padding: 12px 16px;
147
+ border-top: 1px solid var(--lp-line);
148
+ }
149
+
150
+ .cg-import-count {
151
+ margin-right: auto;
152
+ font-size: var(--lp-fs-xs);
153
+ color: var(--lp-muted);
154
+ }
web/src/customer-grid/ImportDialog.tsx CHANGED
@@ -1,299 +1,299 @@
1
- // ---------------------------------------------------------------------------
2
- // customer-grid / ImportDialog.tsx
3
- //
4
- // ⭐⭐ WAVE-29 T25 (owner item 6) β€” IMPORT A SPREADSHEET INTO A USER DATABASE.
5
- //
6
- // Three steps in one window, because each answers the question the last one raised:
7
- // 1. pick a file -> the server parses it and says which columns it found
8
- // 2. map its columns -> to fields, or to nothing; unmapped is the default
9
- // 3. check + import -> every value coerced FIRST, the problems named BEFORE anything writes
10
- //
11
- // β›” APPEND-ONLY IN V1, AND THE DIALOG SAYS SO. Nothing is matched, nothing is overwritten β€” every
12
- // row becomes a new record. The only bulk-merge primitive in the product is upsert-BY-KEY shaped,
13
- // and choosing a key on the user's behalf is how an import quietly rewrites rows somebody edited.
14
- // The sentence is on screen rather than in a doc, because that is where the decision is made.
15
- //
16
- // β›” REUSE, NOT A SECOND COERCER. `clipboard.coerceClipboardValue` is THE client answer to "can
17
- // this text be this field's value" (it is what a paste already goes through), and
18
- // `POST /api/v1/uploads/tabular` is the parser that already exists β€” 5 MB / 20,000 rows, xlsx AND
19
- // csv, and it never writes a row. A second copy of either is a second set of rules for one
20
- // question ([[one-evaluator-per-question]]).
21
- //
22
- // ⚠ THE SERVER IS THE WALL, not this dialog. It refuses computed columns BY NAME and refuses the
23
- // whole batch if it would pass the row cap. What happens here is the part a person needs before
24
- // they press the button: which column goes where, and what will not survive the trip.
25
- // ---------------------------------------------------------------------------
26
-
27
- import { useMemo, useRef, useState } from "react";
28
- // ⚠ From `apiContract`, which is where these two are DECLARED β€” not re-exported from
29
- // `apiBridge`, which does not export them and is another session's fence this wave.
30
- import { API_V1, CREDENTIALS } from "../apiContract";
31
- import { isImportTarget } from "./types";
32
- import type { Field } from "./types";
33
- // ⭐ W29-T76 β€” the plan lives in a pure module so a test can EXECUTE it against the server's real
34
- // payload. This file holds the WINDOW; `importPlan.ts` holds what would be written.
35
- import { buildImportPlan } from "./importPlan";
36
- import type { ImportMapping, ParsedUpload } from "./importPlan";
37
- import "./ImportDialog.css";
38
-
39
- /** The one header a JSON POST needs. `apiBridge` keeps its own module-local copy; this is a
40
- * literal rather than an import because that constant is not exported and that file is not
41
- * this session's to change. */
42
- const JSON_HEADERS = { "Content-Type": "application/json" };
43
-
44
- /** The upload door's answer (`routes_uploads.tabular`) β€” declared in `importPlan.ts`, beside the
45
- * only code that reads its shape. β›” It is COLUMN-MAJOR; the copy that used to live here said
46
- * `string[][]` and that one wrong word is why nothing ever imported. */
47
- type Parsed = ParsedUpload;
48
-
49
- export interface ImportDialogProps {
50
- /** The target database's fields β€” the mapping targets, before this file filters them. */
51
- fields: Field[];
52
- /** `ut_*` table key; the import door is per-table. */
53
- scope: string;
54
- /** How the database calls itself, for the sentence that says where rows are going. */
55
- tableName: string;
56
- /** Fired after a successful import so the host can re-read its rows. */
57
- onImported: (count: number) => void;
58
- onClose: () => void;
59
- }
60
-
61
- const NONE = "";
62
-
63
- export default function ImportDialog({
64
- fields,
65
- scope,
66
- tableName,
67
- onImported,
68
- onClose,
69
- }: ImportDialogProps): React.ReactElement {
70
- const [parsed, setParsed] = useState<Parsed | null>(null);
71
- const [mapping, setMapping] = useState<ImportMapping>({});
72
- const [busy, setBusy] = useState(false);
73
- const [error, setError] = useState("");
74
- const fileRef = useRef<HTMLInputElement | null>(null);
75
-
76
- const targets = useMemo(() => fields.filter(isImportTarget), [fields]);
77
-
78
- /**
79
- * The parse. `FormData` and NO `Content-Type` header: the browser has to set the multipart
80
- * boundary itself, and spelling the header by hand is the classic way to make a working upload
81
- * 400 with a message about a missing part.
82
- */
83
- async function pick(file: File): Promise<void> {
84
- setBusy(true);
85
- setError("");
86
- try {
87
- const form = new FormData();
88
- form.append("file", file);
89
- const res = await fetch(`${API_V1}/uploads/tabular`, {
90
- method: "POST",
91
- credentials: CREDENTIALS,
92
- body: form,
93
- });
94
- const body = (await res.json().catch(() => null)) as
95
- | (Parsed & { error?: { message?: string } })
96
- | null;
97
- if (!res.ok || !body) {
98
- setError(
99
- body?.error?.message ??
100
- `That file could not be read (the server answered ${res.status}).`
101
- );
102
- return;
103
- }
104
- setParsed(body);
105
- // ⭐ AUTO-MAP BY NAME, case- and space-insensitively, because the overwhelmingly common
106
- // case is a sheet exported from this very grid. Every guess is VISIBLE in a picker the
107
- // user can change β€” a silent auto-map is only dangerous when it is also invisible.
108
- const byName = new Map(
109
- targets.map((f) => [f.label.trim().toLowerCase(), f.key] as const)
110
- );
111
- const guess: ImportMapping = {};
112
- (body.columns ?? []).forEach((name, i) => {
113
- const hit = byName.get(String(name).trim().toLowerCase());
114
- if (hit) guess[i] = hit;
115
- });
116
- setMapping(guess);
117
- } catch {
118
- setError("That file could not be read.");
119
- } finally {
120
- setBusy(false);
121
- }
122
- }
123
-
124
- /**
125
- * What would be written, and what cannot be. The work is `importPlan.buildImportPlan` β€” a pure
126
- * module, so the node suite executes it against the server's real payload rather than grepping
127
- * this file for the shape of a loop.
128
- */
129
- const plan = useMemo(
130
- () => buildImportPlan(parsed, mapping, targets),
131
- [parsed, mapping, targets]
132
- );
133
-
134
- async function run(): Promise<void> {
135
- setBusy(true);
136
- setError("");
137
- try {
138
- const res = await fetch(
139
- `${API_V1}/tables/${encodeURIComponent(scope)}/rows/import`,
140
- {
141
- method: "POST",
142
- credentials: CREDENTIALS,
143
- headers: JSON_HEADERS,
144
- body: JSON.stringify({ rows: plan.rows }),
145
- }
146
- );
147
- const body = (await res.json().catch(() => null)) as
148
- | { imported?: number; error?: { message?: string } }
149
- | null;
150
- if (!res.ok) {
151
- // The server's sentence beats anything invented here: it names the column, or the cap.
152
- setError(body?.error?.message ?? `The server answered ${res.status}.`);
153
- return;
154
- }
155
- onImported(body?.imported ?? plan.rows.length);
156
- onClose();
157
- } catch {
158
- setError("Nothing was imported β€” the request did not complete.");
159
- } finally {
160
- setBusy(false);
161
- }
162
- }
163
-
164
- const mappedCount = Object.values(mapping).filter((k) => k !== NONE).length;
165
-
166
- return (
167
- <div className="cg-import-scrim" role="presentation" onClick={onClose}>
168
- <div
169
- className="cg-import"
170
- role="dialog"
171
- aria-modal="true"
172
- aria-label={`Import records into ${tableName}`}
173
- onClick={(event) => event.stopPropagation()}
174
- >
175
- <div className="cg-import-head">
176
- <h2>Import records</h2>
177
- <button type="button" className="cg-import-x" aria-label="Close" onClick={onClose}>
178
- Γ—
179
- </button>
180
- </div>
181
-
182
- {!parsed ? (
183
- <div className="cg-import-body">
184
- <p className="cg-import-lede">
185
- Add records to <strong>{tableName}</strong> from a spreadsheet. Excel
186
- (<code>.xlsx</code>) or <code>.csv</code>, up to 5&nbsp;MB.
187
- </p>
188
- <p className="cg-import-note">
189
- Every row becomes a <strong>new record</strong>. Nothing already in this database is
190
- matched or overwritten.
191
- </p>
192
- <input
193
- ref={fileRef}
194
- type="file"
195
- accept=".xlsx,.csv"
196
- className="cg-import-file"
197
- onChange={(event) => {
198
- const file = event.currentTarget.files?.[0];
199
- if (file) void pick(file);
200
- }}
201
- />
202
- </div>
203
- ) : (
204
- <div className="cg-import-body">
205
- <p className="cg-import-lede">
206
- {parsed.rows.toLocaleString()} row{parsed.rows === 1 ? "" : "s"} read
207
- {parsed.truncated ? " (the first 20,000 β€” the rest were not read)" : ""}. Choose
208
- where each column goes.
209
- </p>
210
- <div className="cg-import-map" role="list">
211
- {parsed.columns.map((name, i) => (
212
- <label className="cg-import-row" role="listitem" key={`${name}:${i}`}>
213
- <span className="cg-import-col" title={name}>
214
- {name || `Column ${i + 1}`}
215
- </span>
216
- <select
217
- value={mapping[i] ?? NONE}
218
- onChange={(event) => {
219
- const next = event.target.value;
220
- setMapping((cur) => ({ ...cur, [i]: next }));
221
- }}
222
- >
223
- <option value={NONE}>Don&rsquo;t import</option>
224
- {targets.map((f) => (
225
- <option key={f.key} value={f.key}>
226
- {f.label}
227
- </option>
228
- ))}
229
- </select>
230
- </label>
231
- ))}
232
- </div>
233
- {plan.problems.length > 0 && (
234
- <div className="cg-import-problems" role="alert">
235
- <strong>
236
- {plan.problems.length.toLocaleString()} value
237
- {plan.problems.length === 1 ? "" : "s"} cannot go in the column
238
- {plan.problems.length === 1 ? "" : "s"} chosen for them
239
- </strong>
240
- <ul>
241
- {plan.problems.slice(0, 5).map((p, i) => (
242
- <li key={i}>
243
- Row {p.row}, {p.column}: {p.value ? `β€œ${p.value}”` : "(blank)"} is not a
244
- valid {p.field}
245
- </li>
246
- ))}
247
- </ul>
248
- {plan.problems.length > 5 && (
249
- <p>…and {(plan.problems.length - 5).toLocaleString()} more.</p>
250
- )}
251
- <p>
252
- Fix them in the file, or point that column somewhere else β€” nothing has been
253
- imported yet.
254
- </p>
255
- </div>
256
- )}
257
- </div>
258
- )}
259
-
260
- {error && (
261
- <p className="cg-import-error" role="alert">
262
- {error}
263
- </p>
264
- )}
265
-
266
- <div className="cg-import-foot">
267
- {parsed && (
268
- <span className="cg-import-count">
269
- {mappedCount === 0
270
- ? "No columns chosen yet"
271
- : `${plan.rows.length.toLocaleString()} record${
272
- plan.rows.length === 1 ? "" : "s"
273
- } from ${mappedCount} column${mappedCount === 1 ? "" : "s"}`}
274
- </span>
275
- )}
276
- <button type="button" className="cg-btn" onClick={onClose}>
277
- Cancel
278
- </button>
279
- {parsed && (
280
- <button
281
- type="button"
282
- className="cg-btn cg-btn--primary"
283
- /* β›” DISABLED WHILE ANY VALUE IS REFUSED. The alternative β€” import the good rows and
284
- report the rest β€” leaves somebody reconciling a spreadsheet against a table by
285
- hand, and neither existing write door demonstrates a partial policy. Refusing
286
- whole is recoverable in one edit; a half-import is not. */
287
- disabled={busy || plan.rows.length === 0 || plan.problems.length > 0}
288
- onClick={() => void run()}
289
- >
290
- {busy ? "Importing…" : `Import ${plan.rows.length.toLocaleString()} record${
291
- plan.rows.length === 1 ? "" : "s"
292
- }`}
293
- </button>
294
- )}
295
- </div>
296
- </div>
297
- </div>
298
- );
299
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // customer-grid / ImportDialog.tsx
3
+ //
4
+ // ⭐⭐ WAVE-29 T25 (owner item 6) β€” IMPORT A SPREADSHEET INTO A USER DATABASE.
5
+ //
6
+ // Three steps in one window, because each answers the question the last one raised:
7
+ // 1. pick a file -> the server parses it and says which columns it found
8
+ // 2. map its columns -> to fields, or to nothing; unmapped is the default
9
+ // 3. check + import -> every value coerced FIRST, the problems named BEFORE anything writes
10
+ //
11
+ // β›” APPEND-ONLY IN V1, AND THE DIALOG SAYS SO. Nothing is matched, nothing is overwritten β€” every
12
+ // row becomes a new record. The only bulk-merge primitive in the product is upsert-BY-KEY shaped,
13
+ // and choosing a key on the user's behalf is how an import quietly rewrites rows somebody edited.
14
+ // The sentence is on screen rather than in a doc, because that is where the decision is made.
15
+ //
16
+ // β›” REUSE, NOT A SECOND COERCER. `clipboard.coerceClipboardValue` is THE client answer to "can
17
+ // this text be this field's value" (it is what a paste already goes through), and
18
+ // `POST /api/v1/uploads/tabular` is the parser that already exists β€” 5 MB / 20,000 rows, xlsx AND
19
+ // csv, and it never writes a row. A second copy of either is a second set of rules for one
20
+ // question ([[one-evaluator-per-question]]).
21
+ //
22
+ // ⚠ THE SERVER IS THE WALL, not this dialog. It refuses computed columns BY NAME and refuses the
23
+ // whole batch if it would pass the row cap. What happens here is the part a person needs before
24
+ // they press the button: which column goes where, and what will not survive the trip.
25
+ // ---------------------------------------------------------------------------
26
+
27
+ import { useMemo, useRef, useState } from "react";
28
+ // ⚠ From `apiContract`, which is where these two are DECLARED β€” not re-exported from
29
+ // `apiBridge`, which does not export them and is another session's fence this wave.
30
+ import { API_V1, CREDENTIALS } from "../apiContract";
31
+ import { isImportTarget } from "./types";
32
+ import type { Field } from "./types";
33
+ // ⭐ W29-T76 β€” the plan lives in a pure module so a test can EXECUTE it against the server's real
34
+ // payload. This file holds the WINDOW; `importPlan.ts` holds what would be written.
35
+ import { buildImportPlan } from "./importPlan";
36
+ import type { ImportMapping, ParsedUpload } from "./importPlan";
37
+ import "./ImportDialog.css";
38
+
39
+ /** The one header a JSON POST needs. `apiBridge` keeps its own module-local copy; this is a
40
+ * literal rather than an import because that constant is not exported and that file is not
41
+ * this session's to change. */
42
+ const JSON_HEADERS = { "Content-Type": "application/json" };
43
+
44
+ /** The upload door's answer (`routes_uploads.tabular`) β€” declared in `importPlan.ts`, beside the
45
+ * only code that reads its shape. β›” It is COLUMN-MAJOR; the copy that used to live here said
46
+ * `string[][]` and that one wrong word is why nothing ever imported. */
47
+ type Parsed = ParsedUpload;
48
+
49
+ export interface ImportDialogProps {
50
+ /** The target database's fields β€” the mapping targets, before this file filters them. */
51
+ fields: Field[];
52
+ /** `ut_*` table key; the import door is per-table. */
53
+ scope: string;
54
+ /** How the database calls itself, for the sentence that says where rows are going. */
55
+ tableName: string;
56
+ /** Fired after a successful import so the host can re-read its rows. */
57
+ onImported: (count: number) => void;
58
+ onClose: () => void;
59
+ }
60
+
61
+ const NONE = "";
62
+
63
+ export default function ImportDialog({
64
+ fields,
65
+ scope,
66
+ tableName,
67
+ onImported,
68
+ onClose,
69
+ }: ImportDialogProps): React.ReactElement {
70
+ const [parsed, setParsed] = useState<Parsed | null>(null);
71
+ const [mapping, setMapping] = useState<ImportMapping>({});
72
+ const [busy, setBusy] = useState(false);
73
+ const [error, setError] = useState("");
74
+ const fileRef = useRef<HTMLInputElement | null>(null);
75
+
76
+ const targets = useMemo(() => fields.filter(isImportTarget), [fields]);
77
+
78
+ /**
79
+ * The parse. `FormData` and NO `Content-Type` header: the browser has to set the multipart
80
+ * boundary itself, and spelling the header by hand is the classic way to make a working upload
81
+ * 400 with a message about a missing part.
82
+ */
83
+ async function pick(file: File): Promise<void> {
84
+ setBusy(true);
85
+ setError("");
86
+ try {
87
+ const form = new FormData();
88
+ form.append("file", file);
89
+ const res = await fetch(`${API_V1}/uploads/tabular`, {
90
+ method: "POST",
91
+ credentials: CREDENTIALS,
92
+ body: form,
93
+ });
94
+ const body = (await res.json().catch(() => null)) as
95
+ | (Parsed & { error?: { message?: string } })
96
+ | null;
97
+ if (!res.ok || !body) {
98
+ setError(
99
+ body?.error?.message ??
100
+ `That file could not be read (the server answered ${res.status}).`
101
+ );
102
+ return;
103
+ }
104
+ setParsed(body);
105
+ // ⭐ AUTO-MAP BY NAME, case- and space-insensitively, because the overwhelmingly common
106
+ // case is a sheet exported from this very grid. Every guess is VISIBLE in a picker the
107
+ // user can change β€” a silent auto-map is only dangerous when it is also invisible.
108
+ const byName = new Map(
109
+ targets.map((f) => [f.label.trim().toLowerCase(), f.key] as const)
110
+ );
111
+ const guess: ImportMapping = {};
112
+ (body.columns ?? []).forEach((name, i) => {
113
+ const hit = byName.get(String(name).trim().toLowerCase());
114
+ if (hit) guess[i] = hit;
115
+ });
116
+ setMapping(guess);
117
+ } catch {
118
+ setError("That file could not be read.");
119
+ } finally {
120
+ setBusy(false);
121
+ }
122
+ }
123
+
124
+ /**
125
+ * What would be written, and what cannot be. The work is `importPlan.buildImportPlan` β€” a pure
126
+ * module, so the node suite executes it against the server's real payload rather than grepping
127
+ * this file for the shape of a loop.
128
+ */
129
+ const plan = useMemo(
130
+ () => buildImportPlan(parsed, mapping, targets),
131
+ [parsed, mapping, targets]
132
+ );
133
+
134
+ async function run(): Promise<void> {
135
+ setBusy(true);
136
+ setError("");
137
+ try {
138
+ const res = await fetch(
139
+ `${API_V1}/tables/${encodeURIComponent(scope)}/rows/import`,
140
+ {
141
+ method: "POST",
142
+ credentials: CREDENTIALS,
143
+ headers: JSON_HEADERS,
144
+ body: JSON.stringify({ rows: plan.rows }),
145
+ }
146
+ );
147
+ const body = (await res.json().catch(() => null)) as
148
+ | { imported?: number; error?: { message?: string } }
149
+ | null;
150
+ if (!res.ok) {
151
+ // The server's sentence beats anything invented here: it names the column, or the cap.
152
+ setError(body?.error?.message ?? `The server answered ${res.status}.`);
153
+ return;
154
+ }
155
+ onImported(body?.imported ?? plan.rows.length);
156
+ onClose();
157
+ } catch {
158
+ setError("Nothing was imported β€” the request did not complete.");
159
+ } finally {
160
+ setBusy(false);
161
+ }
162
+ }
163
+
164
+ const mappedCount = Object.values(mapping).filter((k) => k !== NONE).length;
165
+
166
+ return (
167
+ <div className="cg-import-scrim" role="presentation" onClick={onClose}>
168
+ <div
169
+ className="cg-import"
170
+ role="dialog"
171
+ aria-modal="true"
172
+ aria-label={`Import records into ${tableName}`}
173
+ onClick={(event) => event.stopPropagation()}
174
+ >
175
+ <div className="cg-import-head">
176
+ <h2>Import records</h2>
177
+ <button type="button" className="cg-import-x" aria-label="Close" onClick={onClose}>
178
+ Γ—
179
+ </button>
180
+ </div>
181
+
182
+ {!parsed ? (
183
+ <div className="cg-import-body">
184
+ <p className="cg-import-lede">
185
+ Add records to <strong>{tableName}</strong> from a spreadsheet. Excel
186
+ (<code>.xlsx</code>) or <code>.csv</code>, up to 5&nbsp;MB.
187
+ </p>
188
+ <p className="cg-import-note">
189
+ Every row becomes a <strong>new record</strong>. Nothing already in this database is
190
+ matched or overwritten.
191
+ </p>
192
+ <input
193
+ ref={fileRef}
194
+ type="file"
195
+ accept=".xlsx,.csv"
196
+ className="cg-import-file"
197
+ onChange={(event) => {
198
+ const file = event.currentTarget.files?.[0];
199
+ if (file) void pick(file);
200
+ }}
201
+ />
202
+ </div>
203
+ ) : (
204
+ <div className="cg-import-body">
205
+ <p className="cg-import-lede">
206
+ {parsed.rows.toLocaleString()} row{parsed.rows === 1 ? "" : "s"} read
207
+ {parsed.truncated ? " (the first 20,000 β€” the rest were not read)" : ""}. Choose
208
+ where each column goes.
209
+ </p>
210
+ <div className="cg-import-map" role="list">
211
+ {parsed.columns.map((name, i) => (
212
+ <label className="cg-import-row" role="listitem" key={`${name}:${i}`}>
213
+ <span className="cg-import-col" title={name}>
214
+ {name || `Column ${i + 1}`}
215
+ </span>
216
+ <select
217
+ value={mapping[i] ?? NONE}
218
+ onChange={(event) => {
219
+ const next = event.target.value;
220
+ setMapping((cur) => ({ ...cur, [i]: next }));
221
+ }}
222
+ >
223
+ <option value={NONE}>Don&rsquo;t import</option>
224
+ {targets.map((f) => (
225
+ <option key={f.key} value={f.key}>
226
+ {f.label}
227
+ </option>
228
+ ))}
229
+ </select>
230
+ </label>
231
+ ))}
232
+ </div>
233
+ {plan.problems.length > 0 && (
234
+ <div className="cg-import-problems" role="alert">
235
+ <strong>
236
+ {plan.problems.length.toLocaleString()} value
237
+ {plan.problems.length === 1 ? "" : "s"} cannot go in the column
238
+ {plan.problems.length === 1 ? "" : "s"} chosen for them
239
+ </strong>
240
+ <ul>
241
+ {plan.problems.slice(0, 5).map((p, i) => (
242
+ <li key={i}>
243
+ Row {p.row}, {p.column}: {p.value ? `β€œ${p.value}”` : "(blank)"} is not a
244
+ valid {p.field}
245
+ </li>
246
+ ))}
247
+ </ul>
248
+ {plan.problems.length > 5 && (
249
+ <p>…and {(plan.problems.length - 5).toLocaleString()} more.</p>
250
+ )}
251
+ <p>
252
+ Fix them in the file, or point that column somewhere else β€” nothing has been
253
+ imported yet.
254
+ </p>
255
+ </div>
256
+ )}
257
+ </div>
258
+ )}
259
+
260
+ {error && (
261
+ <p className="cg-import-error" role="alert">
262
+ {error}
263
+ </p>
264
+ )}
265
+
266
+ <div className="cg-import-foot">
267
+ {parsed && (
268
+ <span className="cg-import-count">
269
+ {mappedCount === 0
270
+ ? "No columns chosen yet"
271
+ : `${plan.rows.length.toLocaleString()} record${
272
+ plan.rows.length === 1 ? "" : "s"
273
+ } from ${mappedCount} column${mappedCount === 1 ? "" : "s"}`}
274
+ </span>
275
+ )}
276
+ <button type="button" className="cg-btn" onClick={onClose}>
277
+ Cancel
278
+ </button>
279
+ {parsed && (
280
+ <button
281
+ type="button"
282
+ className="cg-btn cg-btn--primary"
283
+ /* β›” DISABLED WHILE ANY VALUE IS REFUSED. The alternative β€” import the good rows and
284
+ report the rest β€” leaves somebody reconciling a spreadsheet against a table by
285
+ hand, and neither existing write door demonstrates a partial policy. Refusing
286
+ whole is recoverable in one edit; a half-import is not. */
287
+ disabled={busy || plan.rows.length === 0 || plan.problems.length > 0}
288
+ onClick={() => void run()}
289
+ >
290
+ {busy ? "Importing…" : `Import ${plan.rows.length.toLocaleString()} record${
291
+ plan.rows.length === 1 ? "" : "s"
292
+ }`}
293
+ </button>
294
+ )}
295
+ </div>
296
+ </div>
297
+ </div>
298
+ );
299
+ }
web/src/customer-grid/SwipeView.tsx CHANGED
@@ -1,586 +1,586 @@
1
- // ---------------------------------------------------------------------------
2
- // customer-grid / SwipeView.tsx
3
- // ⭐ WAVE-27 item 8 (owner ruling R2, contract C3) β€” the SWIPE deck.
4
- //
5
- // One record at a time, decided left or right into two options of ONE
6
- // single-select. R2 fixes the shape and it is narrow on purpose:
7
- // Β· SINGLE-SELECT ONLY, one field, two of its options. No checkbox binding.
8
- // Β· the deck holds only the records whose bound field is EMPTY β€” a record
9
- // that already has a value has been decided, and re-asking is not triage.
10
- // Β· a swipe writes through the NORMAL cell door (`onSwipe`, which the host
11
- // maps to the same `patchAndRecord` a kanban card move uses), so undo,
12
- // echo-suppression and the permission wall all hold without being
13
- // re-implemented here.
14
- //
15
- // Honesty rules carried from the other modes:
16
- // Β· nothing is silently hidden β€” the deck states what is left, and the
17
- // empty state names the bound field rather than saying "all done".
18
- // Β· a lost binding is SHOWN, never repaired by guessing. `_clean_display`
19
- // validates that `fieldKey` names a field the table HAS and stops there;
20
- // it cannot know the field is still a select, or that the two options are
21
- // still in its vocabulary (its docstring draws that line explicitly). So
22
- // those three losses land here, and each one says what happened and
23
- // re-opens the picker β€” the `viewModes.tsx:190-194` rule, which exists
24
- // because the wave-7 trap was a picker silently falling back to its first
25
- // option.
26
- // ---------------------------------------------------------------------------
27
-
28
- import { useCallback, useEffect, useMemo, useRef, useState } from "react";
29
- // ⭐⭐ W41-T48 (owner instruction 22) β€” opening a record from the swipe deck folds the shell's
30
- // navigation rail exactly as a grid cell click does. Guard rationale: `MapView.tsx:2755`.
31
- import { NAV_MINIMIZE_EVENT, signal } from "../apiContract";
32
- import { choiceOptions } from "./types";
33
- import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
34
- // ⚠ `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
35
- // loaded here) β€” the same import `RecordComments` takes for the same prop.
36
- import type { SurfaceScope } from "./apiBridge";
37
- import RecordComments from "./RecordComments";
38
- import { Documents } from "./Documents";
39
- import { formatDisplay } from "./cells";
40
- import { actionHref } from "./display";
41
- import { optionTint } from "./choiceColors";
42
- import { ModeIcon } from "./icons";
43
- // ⭐ W29-T73 β€” the line its three siblings all have, and the one this file shipped without.
44
- // `SwipeView.css` had ZERO references anywhere in `src/`, so T26's two new sections rendered
45
- // unstyled while `.cg-swipe-card` (which lives in `index.css`) kept the card looking right β€”
46
- // a partially-styled surface reads as a design choice, which is why nobody reported it and no
47
- // gate could see it: a side-effect import references no symbol ([[artifact-with-no-importer]]).
48
- import "./SwipeView.css";
49
-
50
- export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
51
-
52
- /** The three ways a stored binding can rot that the host cannot see (see the header note). */
53
- type BindingFault =
54
- | { kind: "unbound" }
55
- | { kind: "field-gone"; fieldKey: string }
56
- | { kind: "not-select"; field: Field }
57
- | { kind: "option-gone"; field: Field; missing: string[] };
58
-
59
- function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
60
- { ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
61
- if (!spec) return { ok: false, fault: { kind: "unbound" } };
62
- const field = fieldByKey.get(spec.fieldKey);
63
- if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
64
- // R2 β€” SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
65
- // so "write this option" would mean append-or-replace, and a triage gesture that sometimes
66
- // adds and sometimes overwrites is two gestures wearing one button.
67
- if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
68
- const options = choiceOptions(field);
69
- const has = new Set(options.map((o) => o.toLowerCase()));
70
- const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
71
- if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
72
- return { ok: true, field, spec };
73
- }
74
-
75
- /** The bound cell is EMPTY β€” the one predicate that decides deck membership (R2). */
76
- const isUndecided = (row: Row, key: string): boolean =>
77
- String(row[key] ?? "").trim() === "";
78
-
79
- export function SwipeView({
80
- rows,
81
- fields,
82
- fieldByKey,
83
- spec,
84
- cardKeys,
85
- detailKeys,
86
- scope,
87
- viewer,
88
- docs,
89
- docPayload,
90
- onDocAdd,
91
- onDocFetch,
92
- onDocDelete,
93
- titleKey,
94
- canWrite,
95
- readOnlyReason,
96
- canBind,
97
- onSpec,
98
- onSwipe,
99
- onOpen,
100
- }: {
101
- /** DISTINCT data rows from the full pipeline, overlay edits layered β€” the kanban's contract.
102
- * The deck re-derives from these, so a written record leaves it as soon as the optimistic
103
- * patch lands; there is no local cursor to drift out of step with the data. */
104
- rows: Row[];
105
- /** Every field, for the picker's field list. */
106
- fields: Field[];
107
- fieldByKey: Map<string, Field>;
108
- /** The stored binding, or undefined for a deck nobody has configured yet. */
109
- spec: SwipeSpec | undefined;
110
- /** The handful of visible fields the card lists under its title. */
111
- cardKeys: string[];
112
- titleKey: string;
113
- /** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
114
- canWrite: boolean;
115
- /** Stated when the deck cannot be decided β€” permissions, or a computed column. */
116
- readOnlyReason: string | null;
117
- /** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
118
- * view-editing permission and NOT `canWrite` β€” conflating the two is
119
- * [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
120
- * nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
121
- canBind: boolean;
122
- /** `undefined` DELETES the binding β€” absent is the honest unconfigured state, and storing a
123
- * half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
124
- onSpec: (next: SwipeSpec | undefined) => void;
125
- onSwipe: (pid: number, value: string) => void;
126
- onOpen: (pid: number) => void;
127
- /**
128
- * ⭐⭐ WAVE-29 T26 (owner R9) β€” WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.
129
- *
130
- * R9: *"the swipe CARD itself renders the record detail inline β€” fields, comments and
131
- * attachments β€” so a reviewer decides without leaving the deck."* Everything below is that,
132
- * and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply
133
- * different amounts. A card must render with none of them rather than throw β€” the standalone
134
- * embed has no `scope`, and a deployment with no document storage serves no handlers.
135
- */
136
- /** Every field the VIEW shows, in its order β€” not the three-key card summary. */
137
- detailKeys?: string[];
138
- /** The surface these records live on. Comments are keyed by it; absent β‡’ no comments section,
139
- * which is the pre-existing precondition `RecordDetail` already carries. */
140
- scope?: SurfaceScope;
141
- viewer?: Viewer;
142
- /** This record's attachments, and the plumbing. Handlers absent β‡’ the section is not rendered
143
- * at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app
144
- * cannot keep). */
145
- /** Keyed by pid, because a deck shows many records β€” `RecordDetail` takes ONE record's list
146
- * and that shape cannot serve a deck. */
147
- docs?: Record<string, CustomerDoc[]>;
148
- docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };
149
- /** ⚠ EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE
150
- * open record. A deck paints many records at once, so a handler bound to a single pid would
151
- * attach every reviewer's upload to whichever card happened to be open. */
152
- onDocAdd?: (
153
- pid: number,
154
- file: { name: string; mime: string; size: number; data_b64: string }
155
- ) => void;
156
- onDocFetch?: (pid: number, docId: string) => void;
157
- onDocDelete?: (pid: number, docId: string) => void;
158
- }) {
159
- // "Later" β€” session-only, never stored. A deck with no way past a record you cannot decide
160
- // blocks on that record forever, so this is navigation WITHIN the deck rather than a third
161
- // gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
162
- // state rather than quietly shrinking the deck (rule 8b).
163
- const [later, setLater] = useState<Set<number>>(new Set());
164
- const deckRef = useRef<HTMLDivElement>(null);
165
-
166
- const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
167
- const boundKey = binding.ok ? binding.field.key : null;
168
-
169
- const undecided = useMemo(
170
- () => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
171
- [rows, boundKey]
172
- );
173
- const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
174
- const card = deck[0];
175
-
176
- // A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β€”
177
- // otherwise the disclosed skip count drifts away from what is actually on the deck.
178
- useEffect(() => {
179
- setLater((prev) => {
180
- if (prev.size === 0) return prev;
181
- const live = new Set(undecided.map((r) => r.pid));
182
- const next = new Set([...prev].filter((pid) => live.has(pid)));
183
- return next.size === prev.size ? prev : next;
184
- });
185
- }, [undecided]);
186
-
187
- const decide = useCallback(
188
- (value: string) => {
189
- if (!card || !canWrite) return;
190
- onSwipe(card.pid, value);
191
- },
192
- [card, canWrite, onSwipe]
193
- );
194
-
195
- // οΏ½οΏ½ / β†’ decide, and they are the SAME two actions the buttons are rather than a second code
196
- // path: the whole point of the mode is that one hand can clear a queue.
197
- useEffect(() => {
198
- if (!binding.ok || !canWrite || !card) return;
199
- const onKey = (e: KeyboardEvent) => {
200
- if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
201
- const el = document.activeElement as HTMLElement | null;
202
- // Never steal an arrow key from a text field or a native control the user is inside.
203
- if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
204
- return;
205
- if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
206
- e.preventDefault();
207
- decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
208
- };
209
- window.addEventListener("keydown", onKey);
210
- return () => window.removeEventListener("keydown", onKey);
211
- }, [binding, canWrite, card, decide]);
212
-
213
- if (!binding.ok) {
214
- return (
215
- <div className="cg-swipe" ref={deckRef}>
216
- <SwipeBinder
217
- fault={binding.fault}
218
- fields={fields}
219
- fieldByKey={fieldByKey}
220
- spec={spec}
221
- canBind={canBind}
222
- onSpec={onSpec}
223
- />
224
- </div>
225
- );
226
- }
227
-
228
- const { field } = binding;
229
- const leftTint = optionTint(field, binding.spec.leftOption);
230
- const rightTint = optionTint(field, binding.spec.rightOption);
231
-
232
- return (
233
- <div className="cg-swipe" ref={deckRef} tabIndex={-1}>
234
- <div className="cg-swipe-bar">
235
- <span className="cg-swipe-bound">
236
- <ModeIcon mode="swipe" />
237
- Sorting into <strong>{field.label}</strong>
238
- </span>
239
- <span className="cg-swipe-left">
240
- {deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
241
- </span>
242
- {canBind && (
243
- <button
244
- type="button"
245
- className="cg-link-btn"
246
- onClick={() => onSpec(undefined)}
247
- title="Choose a different field or different options for this deck"
248
- >
249
- Change
250
- </button>
251
- )}
252
- </div>
253
- {readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
254
- {card ? (
255
- <div className="cg-swipe-deck">
256
- <button
257
- type="button"
258
- className="cg-swipe-side cg-swipe-side--left"
259
- disabled={!canWrite}
260
- style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
261
- onClick={() => decide(binding.spec.leftOption)}
262
- title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
263
- >
264
- <span aria-hidden className="cg-swipe-arrow">
265
- <svg width="16" height="16" viewBox="0 0 16 16">
266
- <path
267
- d="M11 3.2 6.2 8l4.8 4.8"
268
- fill="none"
269
- stroke="currentColor"
270
- strokeWidth="1.6"
271
- strokeLinecap="round"
272
- strokeLinejoin="round"
273
- />
274
- </svg>
275
- </span>
276
- {binding.spec.leftOption}
277
- </button>
278
- <article
279
- className="cg-swipe-card"
280
- role="button"
281
- tabIndex={0}
282
- onClick={(e) => {
283
- // ⭐ W41-T48 β€” the card IS the deck's record open, so it folds the rail.
284
- // ⚠ Nothing that is NOT an open can reach this line: every control inside the
285
- // card (a url cell, the comments box, the document tray) already stops its own
286
- // click, and the left/right decision buttons are siblings of the card, not
287
- // children of it. The deck also has no pointer drag to disambiguate β€” its swipe
288
- // is the two buttons and the arrow keys, neither of which opens anything.
289
- // ⚠ `<article role="button">`, not a native button, so a keyboard activation
290
- // never arrives here as a synthetic click; the keydown path below is the whole
291
- // keyboard story and the two cannot both fire for one gesture.
292
- if (e.detail <= 1) signal(NAV_MINIMIZE_EVENT);
293
- onOpen(card.pid);
294
- }}
295
- onKeyDown={(e) => {
296
- if (e.key !== "Enter" && e.key !== " ") return;
297
- e.preventDefault();
298
- // W41-T48 β€” `!e.repeat` is this path's `e.detail <= 1`: a HELD Enter or Space
299
- // auto-repeats keydown, and every one of those repeats is the SAME gesture.
300
- if (!e.repeat) signal(NAV_MINIMIZE_EVENT);
301
- onOpen(card.pid);
302
- }}
303
- >
304
- <h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
305
- <div className="cg-swipe-cells">
306
- {/* ⭐ WAVE-29 T26 (R9) β€” the RECORD's visible fields, not the three-key summary the
307
- kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not
308
- been widened yet renders exactly what it rendered before. */}
309
- {(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {
310
- const f = fieldByKey.get(k);
311
- if (!f) return null;
312
- const text = formatDisplay(f, card[k]);
313
- if (!text) return null;
314
- // A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
315
- // scheme guard β€” and every gesture that reaches it must be stopped from also
316
- // reaching the card, which is a button (the kanban card's note, same trap).
317
- const href = actionHref(f, card[k]);
318
- return (
319
- <div key={k} className="cg-swipe-cell">
320
- <span className="cg-lv-k">{f.label}</span>
321
- {href ? (
322
- <a
323
- className="cg-lv-v"
324
- href={href}
325
- target="_blank"
326
- rel="noopener noreferrer"
327
- title={text}
328
- onClick={(e) => e.stopPropagation()}
329
- onKeyDown={(e) => e.stopPropagation()}
330
- >
331
- {text}
332
- </a>
333
- ) : (
334
- <span className="cg-lv-v">{text}</span>
335
- )}
336
- </div>
337
- );
338
- })}
339
- </div>
340
- {/* ⭐ R9's other two thirds. Both stop their own events: the card is a `role="button"`
341
- that opens the record, and a click on a comment box or an upload control must not
342
- also open the modal it exists to make unnecessary (the kanban card's link trap,
343
- one surface over). */}
344
- {onDocAdd && onDocFetch && onDocDelete && (
345
- <div
346
- className="cg-swipe-docs"
347
- onClick={(e) => e.stopPropagation()}
348
- onKeyDown={(e) => e.stopPropagation()}
349
- role="presentation"
350
- >
351
- <Documents
352
- pid={Number(card.pid)}
353
- docs={docs?.[String(card.pid)] ?? []}
354
- docPayload={docPayload}
355
- onAdd={(file) => onDocAdd(card.pid, file)}
356
- onFetch={(docId) => onDocFetch(card.pid, docId)}
357
- onDelete={(docId) => onDocDelete(card.pid, docId)}
358
- />
359
- </div>
360
- )}
361
- {scope != null && (
362
- <div
363
- className="cg-swipe-comments"
364
- onClick={(e) => e.stopPropagation()}
365
- onKeyDown={(e) => e.stopPropagation()}
366
- role="presentation"
367
- >
368
- {/* ⚠ KEYED ON scope+pid, the same key `RecordDetail` uses: without it React
369
- reuses the mounted instance across a card change and paints one record's
370
- comments under another's name until the fetch returns. */}
371
- <RecordComments
372
- key={`${scope}:${Number(card.pid)}`}
373
- scope={scope}
374
- pid={Number(card.pid)}
375
- viewer={viewer}
376
- />
377
- </div>
378
- )}
379
- {canWrite && (
380
- <button
381
- type="button"
382
- className="cg-link-btn cg-swipe-later"
383
- onClick={(e) => {
384
- e.stopPropagation();
385
- setLater((prev) => new Set(prev).add(card.pid));
386
- }}
387
- >
388
- Decide later
389
- </button>
390
- )}
391
- </article>
392
- <button
393
- type="button"
394
- className="cg-swipe-side cg-swipe-side--right"
395
- disabled={!canWrite}
396
- style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
397
- onClick={() => decide(binding.spec.rightOption)}
398
- title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
399
- >
400
- {binding.spec.rightOption}
401
- <span aria-hidden className="cg-swipe-arrow">
402
- <svg width="16" height="16" viewBox="0 0 16 16">
403
- <path
404
- d="M5 3.2 9.8 8 5 12.8"
405
- fill="none"
406
- stroke="currentColor"
407
- strokeWidth="1.6"
408
- strokeLinecap="round"
409
- strokeLinejoin="round"
410
- />
411
- </svg>
412
- </span>
413
- </button>
414
- </div>
415
- ) : (
416
- // The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
417
- // between "the deck is finished" and "the filter hid everything", and the two want
418
- // different next actions. `later` is disclosed rather than quietly subtracted.
419
- <div className="cg-mode-empty cg-swipe-empty">
420
- {later.size > 0 ? (
421
- <>
422
- <p>
423
- {later.size.toLocaleString()}{" "}
424
- {later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
425
- in this view is missing a <strong>{field.label}</strong>.
426
- </p>
427
- <button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
428
- Bring them back
429
- </button>
430
- </>
431
- ) : (
432
- <p>
433
- Every record in this view already has a <strong>{field.label}</strong>. Widen the
434
- view's filters to sort more.
435
- </p>
436
- )}
437
- </div>
438
- )}
439
- </div>
440
- );
441
- }
442
-
443
- /**
444
- * The binding picker: field + two options. It is also the surface every LOST binding lands on,
445
- * with the loss stated above it β€” one place that answers "what is this deck for", rather than an
446
- * error screen beside a separate setup screen.
447
- */
448
- function SwipeBinder({
449
- fault,
450
- fields,
451
- fieldByKey,
452
- spec,
453
- canBind,
454
- onSpec,
455
- }: {
456
- fault: BindingFault;
457
- fields: Field[];
458
- fieldByKey: Map<string, Field>;
459
- spec: SwipeSpec | undefined;
460
- canBind: boolean;
461
- onSpec: (next: SwipeSpec | undefined) => void;
462
- }) {
463
- const selects = useMemo(
464
- () => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
465
- [fields]
466
- );
467
- const [fieldKey, setFieldKey] = useState<string>(() => {
468
- if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
469
- return selects[0]?.key ?? "";
470
- });
471
- const chosen = fieldByKey.get(fieldKey);
472
- const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
473
- const [left, setLeft] = useState<string>("");
474
- const [right, setRight] = useState<string>("");
475
-
476
- // The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
477
- // pick survives re-renders, and reset whenever the field changes β€” carrying an option from the
478
- // previous field would offer a value the new field cannot hold.
479
- useEffect(() => {
480
- setLeft(options[0] ?? "");
481
- setRight(options.find((o) => o !== options[0]) ?? "");
482
- }, [options]);
483
-
484
- const message = ((): string => {
485
- switch (fault.kind) {
486
- case "field-gone":
487
- return "The field this deck sorted into has been deleted. Pick another one.";
488
- case "not-select":
489
- return `β€œ${fault.field.label}” is no longer a single-select, so it has no options to`
490
- + " sort into. Pick another field.";
491
- case "option-gone":
492
- return `${fault.missing.map((m) => `β€œ${m}”`).join(" and ")} ${
493
- fault.missing.length === 1 ? "is" : "are"
494
- } no longer ${fault.missing.length === 1 ? "an option" : "options"} on β€œ${
495
- fault.field.label
496
- }”. Pick the sides again.`;
497
- default:
498
- return "Sort records one at a time into two options of a single-select field.";
499
- }
500
- })();
501
-
502
- if (!canBind) {
503
- return (
504
- <div className="cg-mode-empty">
505
- <p>{message}</p>
506
- <p>Its creator or an admin can set this view up.</p>
507
- </div>
508
- );
509
- }
510
- if (selects.length === 0) {
511
- // Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
512
- // requirement is what turns a dead end into a next action.
513
- return (
514
- <div className="cg-mode-empty">
515
- <p>
516
- A swipe deck sorts into a single-select field with at least two options. This database
517
- does not have one yet β€” add a single-select column, then come back.
518
- </p>
519
- </div>
520
- );
521
- }
522
- const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
523
- return (
524
- <div className="cg-swipe-setup">
525
- <p className="cg-swipe-setup-note">{message}</p>
526
- <label className="cg-swipe-setup-row">
527
- <span>Sort into</span>
528
- <select
529
- className="cg-select"
530
- value={fieldKey}
531
- onChange={(e) => setFieldKey(e.target.value)}
532
- >
533
- {/* Every option carries an explicit `value`: a <select> whose value names nothing
534
- renders its FIRST option and reports a choice the user never made
535
- ([[cg-condition-builder-items]]). */}
536
- {selects.map((f) => (
537
- <option key={f.key} value={f.key}>
538
- {f.label}
539
- </option>
540
- ))}
541
- </select>
542
- </label>
543
- <div className="cg-swipe-setup-sides">
544
- <label className="cg-swipe-setup-row">
545
- <span>Swipe left</span>
546
- <select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
547
- {options.map((o) => (
548
- <option key={o} value={o}>
549
- {o}
550
- </option>
551
- ))}
552
- </select>
553
- </label>
554
- <label className="cg-swipe-setup-row">
555
- <span>Swipe right</span>
556
- <select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
557
- {options.map((o) => (
558
- <option key={o} value={o}>
559
- {o}
560
- </option>
561
- ))}
562
- </select>
563
- </label>
564
- </div>
565
- {!ready && left && right && (
566
- // Stated, not silently refused: both engines DROP a binding whose sides are the same
567
- // option, so a Save that looked like it worked would simply not persist.
568
- <p className="cg-swipe-setup-warn">
569
- The two sides must be different options β€” otherwise both gestures do the same thing.
570
- </p>
571
- )}
572
- <button
573
- type="button"
574
- className="cg-btn cg-btn--primary"
575
- disabled={!ready}
576
- onClick={() =>
577
- chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
578
- }
579
- >
580
- Start sorting
581
- </button>
582
- </div>
583
- );
584
- }
585
-
586
- export default SwipeView;
 
1
+ // ---------------------------------------------------------------------------
2
+ // customer-grid / SwipeView.tsx
3
+ // ⭐ WAVE-27 item 8 (owner ruling R2, contract C3) β€” the SWIPE deck.
4
+ //
5
+ // One record at a time, decided left or right into two options of ONE
6
+ // single-select. R2 fixes the shape and it is narrow on purpose:
7
+ // Β· SINGLE-SELECT ONLY, one field, two of its options. No checkbox binding.
8
+ // Β· the deck holds only the records whose bound field is EMPTY β€” a record
9
+ // that already has a value has been decided, and re-asking is not triage.
10
+ // Β· a swipe writes through the NORMAL cell door (`onSwipe`, which the host
11
+ // maps to the same `patchAndRecord` a kanban card move uses), so undo,
12
+ // echo-suppression and the permission wall all hold without being
13
+ // re-implemented here.
14
+ //
15
+ // Honesty rules carried from the other modes:
16
+ // Β· nothing is silently hidden β€” the deck states what is left, and the
17
+ // empty state names the bound field rather than saying "all done".
18
+ // Β· a lost binding is SHOWN, never repaired by guessing. `_clean_display`
19
+ // validates that `fieldKey` names a field the table HAS and stops there;
20
+ // it cannot know the field is still a select, or that the two options are
21
+ // still in its vocabulary (its docstring draws that line explicitly). So
22
+ // those three losses land here, and each one says what happened and
23
+ // re-opens the picker β€” the `viewModes.tsx:190-194` rule, which exists
24
+ // because the wave-7 trap was a picker silently falling back to its first
25
+ // option.
26
+ // ---------------------------------------------------------------------------
27
+
28
+ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
29
+ // ⭐⭐ W41-T48 (owner instruction 22) β€” opening a record from the swipe deck folds the shell's
30
+ // navigation rail exactly as a grid cell click does. Guard rationale: `MapView.tsx:2755`.
31
+ import { NAV_MINIMIZE_EVENT, signal } from "../apiContract";
32
+ import { choiceOptions } from "./types";
33
+ import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
34
+ // ⚠ `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
35
+ // loaded here) β€” the same import `RecordComments` takes for the same prop.
36
+ import type { SurfaceScope } from "./apiBridge";
37
+ import RecordComments from "./RecordComments";
38
+ import { Documents } from "./Documents";
39
+ import { formatDisplay } from "./cells";
40
+ import { actionHref } from "./display";
41
+ import { optionTint } from "./choiceColors";
42
+ import { ModeIcon } from "./icons";
43
+ // ⭐ W29-T73 β€” the line its three siblings all have, and the one this file shipped without.
44
+ // `SwipeView.css` had ZERO references anywhere in `src/`, so T26's two new sections rendered
45
+ // unstyled while `.cg-swipe-card` (which lives in `index.css`) kept the card looking right β€”
46
+ // a partially-styled surface reads as a design choice, which is why nobody reported it and no
47
+ // gate could see it: a side-effect import references no symbol ([[artifact-with-no-importer]]).
48
+ import "./SwipeView.css";
49
+
50
+ export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
51
+
52
+ /** The three ways a stored binding can rot that the host cannot see (see the header note). */
53
+ type BindingFault =
54
+ | { kind: "unbound" }
55
+ | { kind: "field-gone"; fieldKey: string }
56
+ | { kind: "not-select"; field: Field }
57
+ | { kind: "option-gone"; field: Field; missing: string[] };
58
+
59
+ function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
60
+ { ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
61
+ if (!spec) return { ok: false, fault: { kind: "unbound" } };
62
+ const field = fieldByKey.get(spec.fieldKey);
63
+ if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
64
+ // R2 β€” SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
65
+ // so "write this option" would mean append-or-replace, and a triage gesture that sometimes
66
+ // adds and sometimes overwrites is two gestures wearing one button.
67
+ if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
68
+ const options = choiceOptions(field);
69
+ const has = new Set(options.map((o) => o.toLowerCase()));
70
+ const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
71
+ if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
72
+ return { ok: true, field, spec };
73
+ }
74
+
75
+ /** The bound cell is EMPTY β€” the one predicate that decides deck membership (R2). */
76
+ const isUndecided = (row: Row, key: string): boolean =>
77
+ String(row[key] ?? "").trim() === "";
78
+
79
+ export function SwipeView({
80
+ rows,
81
+ fields,
82
+ fieldByKey,
83
+ spec,
84
+ cardKeys,
85
+ detailKeys,
86
+ scope,
87
+ viewer,
88
+ docs,
89
+ docPayload,
90
+ onDocAdd,
91
+ onDocFetch,
92
+ onDocDelete,
93
+ titleKey,
94
+ canWrite,
95
+ readOnlyReason,
96
+ canBind,
97
+ onSpec,
98
+ onSwipe,
99
+ onOpen,
100
+ }: {
101
+ /** DISTINCT data rows from the full pipeline, overlay edits layered β€” the kanban's contract.
102
+ * The deck re-derives from these, so a written record leaves it as soon as the optimistic
103
+ * patch lands; there is no local cursor to drift out of step with the data. */
104
+ rows: Row[];
105
+ /** Every field, for the picker's field list. */
106
+ fields: Field[];
107
+ fieldByKey: Map<string, Field>;
108
+ /** The stored binding, or undefined for a deck nobody has configured yet. */
109
+ spec: SwipeSpec | undefined;
110
+ /** The handful of visible fields the card lists under its title. */
111
+ cardKeys: string[];
112
+ titleKey: string;
113
+ /** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
114
+ canWrite: boolean;
115
+ /** Stated when the deck cannot be decided β€” permissions, or a computed column. */
116
+ readOnlyReason: string | null;
117
+ /** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
118
+ * view-editing permission and NOT `canWrite` β€” conflating the two is
119
+ * [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
120
+ * nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
121
+ canBind: boolean;
122
+ /** `undefined` DELETES the binding β€” absent is the honest unconfigured state, and storing a
123
+ * half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
124
+ onSpec: (next: SwipeSpec | undefined) => void;
125
+ onSwipe: (pid: number, value: string) => void;
126
+ onOpen: (pid: number) => void;
127
+ /**
128
+ * ⭐⭐ WAVE-29 T26 (owner R9) β€” WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.
129
+ *
130
+ * R9: *"the swipe CARD itself renders the record detail inline β€” fields, comments and
131
+ * attachments β€” so a reviewer decides without leaving the deck."* Everything below is that,
132
+ * and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply
133
+ * different amounts. A card must render with none of them rather than throw β€” the standalone
134
+ * embed has no `scope`, and a deployment with no document storage serves no handlers.
135
+ */
136
+ /** Every field the VIEW shows, in its order β€” not the three-key card summary. */
137
+ detailKeys?: string[];
138
+ /** The surface these records live on. Comments are keyed by it; absent β‡’ no comments section,
139
+ * which is the pre-existing precondition `RecordDetail` already carries. */
140
+ scope?: SurfaceScope;
141
+ viewer?: Viewer;
142
+ /** This record's attachments, and the plumbing. Handlers absent β‡’ the section is not rendered
143
+ * at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app
144
+ * cannot keep). */
145
+ /** Keyed by pid, because a deck shows many records β€” `RecordDetail` takes ONE record's list
146
+ * and that shape cannot serve a deck. */
147
+ docs?: Record<string, CustomerDoc[]>;
148
+ docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };
149
+ /** ⚠ EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE
150
+ * open record. A deck paints many records at once, so a handler bound to a single pid would
151
+ * attach every reviewer's upload to whichever card happened to be open. */
152
+ onDocAdd?: (
153
+ pid: number,
154
+ file: { name: string; mime: string; size: number; data_b64: string }
155
+ ) => void;
156
+ onDocFetch?: (pid: number, docId: string) => void;
157
+ onDocDelete?: (pid: number, docId: string) => void;
158
+ }) {
159
+ // "Later" β€” session-only, never stored. A deck with no way past a record you cannot decide
160
+ // blocks on that record forever, so this is navigation WITHIN the deck rather than a third
161
+ // gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
162
+ // state rather than quietly shrinking the deck (rule 8b).
163
+ const [later, setLater] = useState<Set<number>>(new Set());
164
+ const deckRef = useRef<HTMLDivElement>(null);
165
+
166
+ const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
167
+ const boundKey = binding.ok ? binding.field.key : null;
168
+
169
+ const undecided = useMemo(
170
+ () => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
171
+ [rows, boundKey]
172
+ );
173
+ const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
174
+ const card = deck[0];
175
+
176
+ // A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β€”
177
+ // otherwise the disclosed skip count drifts away from what is actually on the deck.
178
+ useEffect(() => {
179
+ setLater((prev) => {
180
+ if (prev.size === 0) return prev;
181
+ const live = new Set(undecided.map((r) => r.pid));
182
+ const next = new Set([...prev].filter((pid) => live.has(pid)));
183
+ return next.size === prev.size ? prev : next;
184
+ });
185
+ }, [undecided]);
186
+
187
+ const decide = useCallback(
188
+ (value: string) => {
189
+ if (!card || !canWrite) return;
190
+ onSwipe(card.pid, value);
191
+ },
192
+ [card, canWrite, onSwipe]
193
+ );
194
+
195
+ // ← / β†’ decide, and they are the SAME two actions the buttons are rather than a second code
196
+ // path: the whole point of the mode is that one hand can clear a queue.
197
+ useEffect(() => {
198
+ if (!binding.ok || !canWrite || !card) return;
199
+ const onKey = (e: KeyboardEvent) => {
200
+ if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
201
+ const el = document.activeElement as HTMLElement | null;
202
+ // Never steal an arrow key from a text field or a native control the user is inside.
203
+ if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
204
+ return;
205
+ if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
206
+ e.preventDefault();
207
+ decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
208
+ };
209
+ window.addEventListener("keydown", onKey);
210
+ return () => window.removeEventListener("keydown", onKey);
211
+ }, [binding, canWrite, card, decide]);
212
+
213
+ if (!binding.ok) {
214
+ return (
215
+ <div className="cg-swipe" ref={deckRef}>
216
+ <SwipeBinder
217
+ fault={binding.fault}
218
+ fields={fields}
219
+ fieldByKey={fieldByKey}
220
+ spec={spec}
221
+ canBind={canBind}
222
+ onSpec={onSpec}
223
+ />
224
+ </div>
225
+ );
226
+ }
227
+
228
+ const { field } = binding;
229
+ const leftTint = optionTint(field, binding.spec.leftOption);
230
+ const rightTint = optionTint(field, binding.spec.rightOption);
231
+
232
+ return (
233
+ <div className="cg-swipe" ref={deckRef} tabIndex={-1}>
234
+ <div className="cg-swipe-bar">
235
+ <span className="cg-swipe-bound">
236
+ <ModeIcon mode="swipe" />
237
+ Sorting into <strong>{field.label}</strong>
238
+ </span>
239
+ <span className="cg-swipe-left">
240
+ {deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
241
+ </span>
242
+ {canBind && (
243
+ <button
244
+ type="button"
245
+ className="cg-link-btn"
246
+ onClick={() => onSpec(undefined)}
247
+ title="Choose a different field or different options for this deck"
248
+ >
249
+ Change
250
+ </button>
251
+ )}
252
+ </div>
253
+ {readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
254
+ {card ? (
255
+ <div className="cg-swipe-deck">
256
+ <button
257
+ type="button"
258
+ className="cg-swipe-side cg-swipe-side--left"
259
+ disabled={!canWrite}
260
+ style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
261
+ onClick={() => decide(binding.spec.leftOption)}
262
+ title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
263
+ >
264
+ <span aria-hidden className="cg-swipe-arrow">
265
+ <svg width="16" height="16" viewBox="0 0 16 16">
266
+ <path
267
+ d="M11 3.2 6.2 8l4.8 4.8"
268
+ fill="none"
269
+ stroke="currentColor"
270
+ strokeWidth="1.6"
271
+ strokeLinecap="round"
272
+ strokeLinejoin="round"
273
+ />
274
+ </svg>
275
+ </span>
276
+ {binding.spec.leftOption}
277
+ </button>
278
+ <article
279
+ className="cg-swipe-card"
280
+ role="button"
281
+ tabIndex={0}
282
+ onClick={(e) => {
283
+ // ⭐ W41-T48 β€” the card IS the deck's record open, so it folds the rail.
284
+ // ⚠ Nothing that is NOT an open can reach this line: every control inside the
285
+ // card (a url cell, the comments box, the document tray) already stops its own
286
+ // click, and the left/right decision buttons are siblings of the card, not
287
+ // children of it. The deck also has no pointer drag to disambiguate β€” its swipe
288
+ // is the two buttons and the arrow keys, neither of which opens anything.
289
+ // ⚠ `<article role="button">`, not a native button, so a keyboard activation
290
+ // never arrives here as a synthetic click; the keydown path below is the whole
291
+ // keyboard story and the two cannot both fire for one gesture.
292
+ if (e.detail <= 1) signal(NAV_MINIMIZE_EVENT);
293
+ onOpen(card.pid);
294
+ }}
295
+ onKeyDown={(e) => {
296
+ if (e.key !== "Enter" && e.key !== " ") return;
297
+ e.preventDefault();
298
+ // W41-T48 β€” `!e.repeat` is this path's `e.detail <= 1`: a HELD Enter or Space
299
+ // auto-repeats keydown, and every one of those repeats is the SAME gesture.
300
+ if (!e.repeat) signal(NAV_MINIMIZE_EVENT);
301
+ onOpen(card.pid);
302
+ }}
303
+ >
304
+ <h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
305
+ <div className="cg-swipe-cells">
306
+ {/* ⭐ WAVE-29 T26 (R9) β€” the RECORD's visible fields, not the three-key summary the
307
+ kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not
308
+ been widened yet renders exactly what it rendered before. */}
309
+ {(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {
310
+ const f = fieldByKey.get(k);
311
+ if (!f) return null;
312
+ const text = formatDisplay(f, card[k]);
313
+ if (!text) return null;
314
+ // A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
315
+ // scheme guard β€” and every gesture that reaches it must be stopped from also
316
+ // reaching the card, which is a button (the kanban card's note, same trap).
317
+ const href = actionHref(f, card[k]);
318
+ return (
319
+ <div key={k} className="cg-swipe-cell">
320
+ <span className="cg-lv-k">{f.label}</span>
321
+ {href ? (
322
+ <a
323
+ className="cg-lv-v"
324
+ href={href}
325
+ target="_blank"
326
+ rel="noopener noreferrer"
327
+ title={text}
328
+ onClick={(e) => e.stopPropagation()}
329
+ onKeyDown={(e) => e.stopPropagation()}
330
+ >
331
+ {text}
332
+ </a>
333
+ ) : (
334
+ <span className="cg-lv-v">{text}</span>
335
+ )}
336
+ </div>
337
+ );
338
+ })}
339
+ </div>
340
+ {/* ⭐ R9's other two thirds. Both stop their own events: the card is a `role="button"`
341
+ that opens the record, and a click on a comment box or an upload control must not
342
+ also open the modal it exists to make unnecessary (the kanban card's link trap,
343
+ one surface over). */}
344
+ {onDocAdd && onDocFetch && onDocDelete && (
345
+ <div
346
+ className="cg-swipe-docs"
347
+ onClick={(e) => e.stopPropagation()}
348
+ onKeyDown={(e) => e.stopPropagation()}
349
+ role="presentation"
350
+ >
351
+ <Documents
352
+ pid={Number(card.pid)}
353
+ docs={docs?.[String(card.pid)] ?? []}
354
+ docPayload={docPayload}
355
+ onAdd={(file) => onDocAdd(card.pid, file)}
356
+ onFetch={(docId) => onDocFetch(card.pid, docId)}
357
+ onDelete={(docId) => onDocDelete(card.pid, docId)}
358
+ />
359
+ </div>
360
+ )}
361
+ {scope != null && (
362
+ <div
363
+ className="cg-swipe-comments"
364
+ onClick={(e) => e.stopPropagation()}
365
+ onKeyDown={(e) => e.stopPropagation()}
366
+ role="presentation"
367
+ >
368
+ {/* ⚠ KEYED ON scope+pid, the same key `RecordDetail` uses: without it React
369
+ reuses the mounted instance across a card change and paints one record's
370
+ comments under another's name until the fetch returns. */}
371
+ <RecordComments
372
+ key={`${scope}:${Number(card.pid)}`}
373
+ scope={scope}
374
+ pid={Number(card.pid)}
375
+ viewer={viewer}
376
+ />
377
+ </div>
378
+ )}
379
+ {canWrite && (
380
+ <button
381
+ type="button"
382
+ className="cg-link-btn cg-swipe-later"
383
+ onClick={(e) => {
384
+ e.stopPropagation();
385
+ setLater((prev) => new Set(prev).add(card.pid));
386
+ }}
387
+ >
388
+ Decide later
389
+ </button>
390
+ )}
391
+ </article>
392
+ <button
393
+ type="button"
394
+ className="cg-swipe-side cg-swipe-side--right"
395
+ disabled={!canWrite}
396
+ style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
397
+ onClick={() => decide(binding.spec.rightOption)}
398
+ title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
399
+ >
400
+ {binding.spec.rightOption}
401
+ <span aria-hidden className="cg-swipe-arrow">
402
+ <svg width="16" height="16" viewBox="0 0 16 16">
403
+ <path
404
+ d="M5 3.2 9.8 8 5 12.8"
405
+ fill="none"
406
+ stroke="currentColor"
407
+ strokeWidth="1.6"
408
+ strokeLinecap="round"
409
+ strokeLinejoin="round"
410
+ />
411
+ </svg>
412
+ </span>
413
+ </button>
414
+ </div>
415
+ ) : (
416
+ // The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
417
+ // between "the deck is finished" and "the filter hid everything", and the two want
418
+ // different next actions. `later` is disclosed rather than quietly subtracted.
419
+ <div className="cg-mode-empty cg-swipe-empty">
420
+ {later.size > 0 ? (
421
+ <>
422
+ <p>
423
+ {later.size.toLocaleString()}{" "}
424
+ {later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
425
+ in this view is missing a <strong>{field.label}</strong>.
426
+ </p>
427
+ <button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
428
+ Bring them back
429
+ </button>
430
+ </>
431
+ ) : (
432
+ <p>
433
+ Every record in this view already has a <strong>{field.label}</strong>. Widen the
434
+ view's filters to sort more.
435
+ </p>
436
+ )}
437
+ </div>
438
+ )}
439
+ </div>
440
+ );
441
+ }
442
+
443
+ /**
444
+ * The binding picker: field + two options. It is also the surface every LOST binding lands on,
445
+ * with the loss stated above it β€” one place that answers "what is this deck for", rather than an
446
+ * error screen beside a separate setup screen.
447
+ */
448
+ function SwipeBinder({
449
+ fault,
450
+ fields,
451
+ fieldByKey,
452
+ spec,
453
+ canBind,
454
+ onSpec,
455
+ }: {
456
+ fault: BindingFault;
457
+ fields: Field[];
458
+ fieldByKey: Map<string, Field>;
459
+ spec: SwipeSpec | undefined;
460
+ canBind: boolean;
461
+ onSpec: (next: SwipeSpec | undefined) => void;
462
+ }) {
463
+ const selects = useMemo(
464
+ () => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
465
+ [fields]
466
+ );
467
+ const [fieldKey, setFieldKey] = useState<string>(() => {
468
+ if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
469
+ return selects[0]?.key ?? "";
470
+ });
471
+ const chosen = fieldByKey.get(fieldKey);
472
+ const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
473
+ const [left, setLeft] = useState<string>("");
474
+ const [right, setRight] = useState<string>("");
475
+
476
+ // The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
477
+ // pick survives re-renders, and reset whenever the field changes β€” carrying an option from the
478
+ // previous field would offer a value the new field cannot hold.
479
+ useEffect(() => {
480
+ setLeft(options[0] ?? "");
481
+ setRight(options.find((o) => o !== options[0]) ?? "");
482
+ }, [options]);
483
+
484
+ const message = ((): string => {
485
+ switch (fault.kind) {
486
+ case "field-gone":
487
+ return "The field this deck sorted into has been deleted. Pick another one.";
488
+ case "not-select":
489
+ return `β€œ${fault.field.label}” is no longer a single-select, so it has no options to`
490
+ + " sort into. Pick another field.";
491
+ case "option-gone":
492
+ return `${fault.missing.map((m) => `β€œ${m}”`).join(" and ")} ${
493
+ fault.missing.length === 1 ? "is" : "are"
494
+ } no longer ${fault.missing.length === 1 ? "an option" : "options"} on β€œ${
495
+ fault.field.label
496
+ }”. Pick the sides again.`;
497
+ default:
498
+ return "Sort records one at a time into two options of a single-select field.";
499
+ }
500
+ })();
501
+
502
+ if (!canBind) {
503
+ return (
504
+ <div className="cg-mode-empty">
505
+ <p>{message}</p>
506
+ <p>Its creator or an admin can set this view up.</p>
507
+ </div>
508
+ );
509
+ }
510
+ if (selects.length === 0) {
511
+ // Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
512
+ // requirement is what turns a dead end into a next action.
513
+ return (
514
+ <div className="cg-mode-empty">
515
+ <p>
516
+ A swipe deck sorts into a single-select field with at least two options. This database
517
+ does not have one yet β€” add a single-select column, then come back.
518
+ </p>
519
+ </div>
520
+ );
521
+ }
522
+ const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
523
+ return (
524
+ <div className="cg-swipe-setup">
525
+ <p className="cg-swipe-setup-note">{message}</p>
526
+ <label className="cg-swipe-setup-row">
527
+ <span>Sort into</span>
528
+ <select
529
+ className="cg-select"
530
+ value={fieldKey}
531
+ onChange={(e) => setFieldKey(e.target.value)}
532
+ >
533
+ {/* Every option carries an explicit `value`: a <select> whose value names nothing
534
+ renders its FIRST option and reports a choice the user never made
535
+ ([[cg-condition-builder-items]]). */}
536
+ {selects.map((f) => (
537
+ <option key={f.key} value={f.key}>
538
+ {f.label}
539
+ </option>
540
+ ))}
541
+ </select>
542
+ </label>
543
+ <div className="cg-swipe-setup-sides">
544
+ <label className="cg-swipe-setup-row">
545
+ <span>Swipe left</span>
546
+ <select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
547
+ {options.map((o) => (
548
+ <option key={o} value={o}>
549
+ {o}
550
+ </option>
551
+ ))}
552
+ </select>
553
+ </label>
554
+ <label className="cg-swipe-setup-row">
555
+ <span>Swipe right</span>
556
+ <select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
557
+ {options.map((o) => (
558
+ <option key={o} value={o}>
559
+ {o}
560
+ </option>
561
+ ))}
562
+ </select>
563
+ </label>
564
+ </div>
565
+ {!ready && left && right && (
566
+ // Stated, not silently refused: both engines DROP a binding whose sides are the same
567
+ // option, so a Save that looked like it worked would simply not persist.
568
+ <p className="cg-swipe-setup-warn">
569
+ The two sides must be different options β€” otherwise both gestures do the same thing.
570
+ </p>
571
+ )}
572
+ <button
573
+ type="button"
574
+ className="cg-btn cg-btn--primary"
575
+ disabled={!ready}
576
+ onClick={() =>
577
+ chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
578
+ }
579
+ >
580
+ Start sorting
581
+ </button>
582
+ </div>
583
+ );
584
+ }
585
+
586
+ export default SwipeView;
web/src/customer-grid/chatDock.css CHANGED
@@ -1,48 +1,48 @@
1
- /* customer-grid/chatDock.css β€” W37-T29 (contract C6 + C8): the chat's DOCK and its LAUNCHER.
2
- *
3
- * β›” A SEPARATE SHEET FROM E's `gridChat.css` ON PURPOSE, and the split is the contract rather
4
- * than taste. C8 hands `index.css` to lane A alone and tells every other lane to add styles in its
5
- * own per-surface sheet; E owns how the PANEL looks and this file owns where the HOST puts it and
6
- * how a person opens it. Two lanes editing one sheet is the collision C8 exists to prevent.
7
- *
8
- * β›”β›” THE LAUNCHER IS THE WHOLE REASON THIS FILE EXISTS. A panel with no control that opens it is
9
- * mounted-but-never-offered, which is this repo's most repeated defect: one wave shipped five whole,
10
- * correct, unreachable features past every gate. E's sheet cannot carry the launcher, because the
11
- * launcher is not part of the panel.
12
- * ⚠ Tokens only, never fresh hexes (DESIGN.md: navy #1F4E78 + gold #C8A24B). No emojis, no
13
- * ALL-CAPS chrome.
14
- */
15
-
16
- /* The dock: a flex child of `.cg-shell`, seated between the views rail and the grid, so the panel
17
- reads as part of the workspace rather than as an overlay floating on top of it. E's `.cg-chat`
18
- brings its own width floor, ceiling and left border; this wrapper only owns the seat. */
19
- .cg-chat-dock {
20
- display: flex;
21
- min-height: 0;
22
- align-self: stretch;
23
- }
24
-
25
- /* ⭐⭐ THE LAUNCHER, MOVED 2026-08-19 ON THE OWNER'S INSTRUCTION.
26
- It was `.cg-chat-open`: a text pill reading "Ask about this data", floating in the gap between
27
- the views rail and the grid with a `margin: 8px 0 0 8px`. The owner called it *"ugly as hell"*
28
- and said where it belongs β€” *"the same Navigation as the View navigation just beside its
29
- minimize icon"*. It is now a 26px icon button INSIDE `.cg-views-top`, and these rules match
30
- `.cg-agent-open` (scriptView.css) exactly, because the two controls sit side by side in one
31
- 26px strip and a launcher that is 2px taller than its neighbour is what reads as bolted on.
32
- ⚠ The old class is GONE rather than left orphaned: a dead rule for a removed node is how a
33
- later reader concludes the feature still has two entry points. */
34
- .cg-chat-toggle {
35
- display: inline-flex;
36
- align-items: center;
37
- justify-content: center;
38
- width: 26px;
39
- height: 26px;
40
- border: 0;
41
- border-radius: 6px;
42
- background: transparent;
43
- color: var(--lp-text-muted, #667085);
44
- cursor: pointer;
45
- }
46
- .cg-chat-toggle:hover { background: var(--lp-surface-sunken, #f2f4f7); }
47
- .cg-chat-toggle.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
48
- .cg-chat-toggle:focus-visible { outline: 2px solid var(--lp-gold, #c8a24b); outline-offset: 1px; }
 
1
+ /* customer-grid/chatDock.css β€” W37-T29 (contract C6 + C8): the chat's DOCK and its LAUNCHER.
2
+ *
3
+ * β›” A SEPARATE SHEET FROM E's `gridChat.css` ON PURPOSE, and the split is the contract rather
4
+ * than taste. C8 hands `index.css` to lane A alone and tells every other lane to add styles in its
5
+ * own per-surface sheet; E owns how the PANEL looks and this file owns where the HOST puts it and
6
+ * how a person opens it. Two lanes editing one sheet is the collision C8 exists to prevent.
7
+ *
8
+ * β›”β›” THE LAUNCHER IS THE WHOLE REASON THIS FILE EXISTS. A panel with no control that opens it is
9
+ * mounted-but-never-offered, which is this repo's most repeated defect: one wave shipped five whole,
10
+ * correct, unreachable features past every gate. E's sheet cannot carry the launcher, because the
11
+ * launcher is not part of the panel.
12
+ * ⚠ Tokens only, never fresh hexes (DESIGN.md: navy #1F4E78 + gold #C8A24B). No emojis, no
13
+ * ALL-CAPS chrome.
14
+ */
15
+
16
+ /* The dock: a flex child of `.cg-shell`, seated between the views rail and the grid, so the panel
17
+ reads as part of the workspace rather than as an overlay floating on top of it. E's `.cg-chat`
18
+ brings its own width floor, ceiling and left border; this wrapper only owns the seat. */
19
+ .cg-chat-dock {
20
+ display: flex;
21
+ min-height: 0;
22
+ align-self: stretch;
23
+ }
24
+
25
+ /* ⭐⭐ THE LAUNCHER, MOVED 2026-08-19 ON THE OWNER'S INSTRUCTION.
26
+ It was `.cg-chat-open`: a text pill reading "Ask about this data", floating in the gap between
27
+ the views rail and the grid with a `margin: 8px 0 0 8px`. The owner called it *"ugly as hell"*
28
+ and said where it belongs β€” *"the same Navigation as the View navigation just beside its
29
+ minimize icon"*. It is now a 26px icon button INSIDE `.cg-views-top`, and these rules match
30
+ `.cg-agent-open` (scriptView.css) exactly, because the two controls sit side by side in one
31
+ 26px strip and a launcher that is 2px taller than its neighbour is what reads as bolted on.
32
+ ⚠ The old class is GONE rather than left orphaned: a dead rule for a removed node is how a
33
+ later reader concludes the feature still has two entry points. */
34
+ .cg-chat-toggle {
35
+ display: inline-flex;
36
+ align-items: center;
37
+ justify-content: center;
38
+ width: 26px;
39
+ height: 26px;
40
+ border: 0;
41
+ border-radius: 6px;
42
+ background: transparent;
43
+ color: var(--lp-text-muted, #667085);
44
+ cursor: pointer;
45
+ }
46
+ .cg-chat-toggle:hover { background: var(--lp-surface-sunken, #f2f4f7); }
47
+ .cg-chat-toggle.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
48
+ .cg-chat-toggle:focus-visible { outline: 2px solid var(--lp-gold, #c8a24b); outline-offset: 1px; }