fsanyoto commited on
Commit
dcdb685
Β·
verified Β·
1 Parent(s): 30d8096

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/automation_engine.py +0 -0
  4. api/connectors_tt.py +293 -0
  5. api/main.py +545 -532
  6. api/odoo_relational.py +41 -8
  7. api/providers.py +31 -0
  8. api/routes_automation.py +58 -6
  9. api/routes_changes.py +159 -0
  10. api/routes_forms.py +253 -30
  11. api/routes_oauth.py +12 -1
  12. api/routes_products.py +11 -0
  13. api/routes_tables.py +62 -5
  14. platform/aios_grid.py +139 -2
  15. platform/core/shared_overlay.py +264 -0
  16. platform/core/store.py +75 -0
  17. platform/core/store_backend.py +15 -1
  18. platform/core/store_pg.py +34 -0
  19. platform/core/user_tables.py +270 -21
  20. platform/harness/datastore.py +25 -2
  21. platform/modules/product_data.py +128 -20
  22. platform/modules/products.py +56 -0
  23. web/src/automation/AutomationBuilder.tsx +89 -0
  24. web/src/automation/AutomationSurface.tsx +16 -2
  25. web/src/automation/TriggerPicker.tsx +7 -2
  26. web/src/automation/automationApi.ts +12 -0
  27. web/src/customer-grid/ColumnMenu.tsx +78 -2
  28. web/src/customer-grid/CustomerGrid.tsx +0 -0
  29. web/src/customer-grid/FormInterface.css +269 -0
  30. web/src/customer-grid/FormInterface.tsx +504 -0
  31. web/src/customer-grid/ImportDialog.css +154 -0
  32. web/src/customer-grid/ImportDialog.tsx +325 -0
  33. web/src/customer-grid/MapView.tsx +103 -16
  34. web/src/customer-grid/RecordDetail.tsx +45 -1
  35. web/src/customer-grid/SwipeView.css +25 -0
  36. web/src/customer-grid/SwipeView.tsx +562 -476
  37. web/src/customer-grid/ViewSidebar.tsx +0 -0
  38. web/src/customer-grid/aggregations.ts +92 -24
  39. web/src/customer-grid/apiBridge.ts +130 -0
  40. web/src/customer-grid/display.ts +24 -1
  41. web/src/customer-grid/export.ts +188 -5
  42. web/src/customer-grid/iconShapes.ts +118 -1
  43. web/src/customer-grid/liveWorkspace.ts +125 -0
  44. web/src/customer-grid/mapProjection.ts +94 -0
  45. web/src/customer-grid/theme.ts +27 -25
  46. web/src/customer-grid/types.ts +0 -0
  47. web/src/customer-grid/useCustomerData.ts +105 -32
  48. web/src/customer-grid/useGetCellContent.ts +4 -0
  49. web/src/customer-grid/useGridColumns.ts +8 -0
  50. web/src/customer-grid/useVisibleRows.ts +64 -0
RELEASES.json CHANGED
@@ -1,5 +1,5 @@
1
  {
2
- "current": "7269240",
3
  "releases": [
4
  {
5
  "version": "v24",
 
1
  {
2
+ "current": "bac40c2",
3
  "releases": [
4
  {
5
  "version": "v24",
VERSION CHANGED
@@ -1 +1 @@
1
- 7269240
 
1
+ bac40c2
api/automation_engine.py CHANGED
The diff for this file is too large to render. See raw diff
 
api/connectors_tt.py ADDED
@@ -0,0 +1,293 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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/research/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 BORROWED FROM `connectors_ig`, ON PURPOSE.** `bd_call`, `bd_scrape` and
20
+ `bd_filter_start` take the dataset id as a PARAMETER β€” they are Bright Data's wire, not
21
+ Instagram's β€” so re-implementing them here would be a second copy of the deferral handling, the
22
+ truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
23
+ The name is wrong and the code is right; extracting a `connectors_bd` transport module is booked
24
+ as a PENDING line in B's mailbox rather than done mid-wave, because moving those functions would
25
+ land in the middle of three other tickets' diffs.
26
+
27
+ ⚠ **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
28
+ 1. the real ROW shape β€” `/metadata` describes a DATASET, and Instagram's rows carry undeclared
29
+ envelope keys (`timestamp`, `input`) that no metadata call mentions;
30
+ 2. that a declared field POPULATES β€” Bright Data's Instagram Reels *declares* `views: number`
31
+ and delivers an account-grain wrong number (Β§4e). **Declared is not delivered**, and the one
32
+ TikTok claim that matters most (`play_count`) is exactly a declaration.
33
+ """
34
+ from __future__ import annotations
35
+
36
+ import automation_engine as engine
37
+ from connectors_ig import ( # noqa: F401 (bd_call/bd_scrape are re-exported for the runners)
38
+ _bd_first_url,
39
+ _bd_flag,
40
+ _bd_list,
41
+ _bd_source_payload,
42
+ _first,
43
+ _ig_int,
44
+ bd_call,
45
+ bd_filter_start,
46
+ bd_key,
47
+ bd_ready,
48
+ bd_scrape,
49
+ )
50
+
51
+ # ---------------------------------------------------------------------------------------------
52
+ # THE DATASETS
53
+ # ---------------------------------------------------------------------------------------------
54
+ # ⚠ CATALOGUE PRESENCE IS NOT ENTITLEMENT β€” the same finding Instagram produced. `GET
55
+ # /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
56
+ # full field list, and the two DISCOVERY halves answer **404 for our key**:
57
+ # `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
58
+ # β‡’ TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
59
+ # does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
60
+ TT_DS_PROFILES = "gd_l1villgoiiidt09ci" # TikTok - Profiles. 40 fields, 152,000,000 records
61
+ TT_DS_POSTS = "gd_lu702nij2f790tmv9h" # TikTok - Posts. 43 fields
62
+ TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k" # TikTok - Comments. 17 fields
63
+
64
+ #: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
65
+ #: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
66
+ TT_POST_TYPE_VIDEO = "video"
67
+ TT_POST_TYPE_CONTENT = "content"
68
+
69
+ #: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
70
+ #: beside the dataset ids because it is the same class of vendor fact.
71
+ #: ⚠ ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
72
+ #: string from `_PROFILE_RULES` (contract C2, E's half) β€” this exists for the connector's own
73
+ #: batch calls, and the gate asserts the two agree rather than trusting that they do.
74
+ TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
75
+
76
+
77
+ def tt_profile_url(handle):
78
+ """`nurilab` β†’ `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
79
+ h = str(handle or "").strip().lstrip("@")
80
+ return TT_PROFILE_URL.format(handle=h) if h else ""
81
+
82
+
83
+ # ---------------------------------------------------------------------------------------------
84
+ # THE FIELD MAPS
85
+ # ---------------------------------------------------------------------------------------------
86
+ # Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
87
+ # in `automation_engine`. The rules they all obey, stated once:
88
+ #
89
+ # * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
90
+ # so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
91
+ # returns `None` (never 0) when nothing matches, which is what makes that possible.
92
+ # * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
93
+ # rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
94
+ # * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
95
+ # vendor's side is preserved rather than silently discarded while our column model catches up.
96
+ # * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
97
+ # (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
98
+ # ride in `source_payload` where they make no claim.
99
+
100
+
101
+ def _tt_str(node, *names):
102
+ """The first non-empty string among `names`, or None when the vendor sent nothing.
103
+
104
+ β›” `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest β€”
105
+ an empty string written into a cell claims "we looked and it is empty".
106
+ """
107
+ v = _first(node, *names)
108
+ if v is None:
109
+ return None
110
+ s = str(v).strip()
111
+ return s or None
112
+
113
+
114
+ def _tt_pct(node, *names):
115
+ """A vendor 0–1 engagement fraction β†’ our stored 0–100 percentage, or None.
116
+
117
+ β›” THE Γ—100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
118
+ the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` β€”
119
+ measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
120
+ """
121
+ v = _first(node, *names)
122
+ if v is None:
123
+ return None
124
+ out = engine._pct100(v)
125
+ return out or None
126
+
127
+
128
+ def _tt_day(node, *names):
129
+ """A vendor stamp β†’ `YYYY-MM-DD`, or None. Our `date` columns store a day."""
130
+ v = _first(node, *names)
131
+ if v is None:
132
+ return None
133
+ return engine._day(v) or None
134
+
135
+
136
+ def _drop_blanks(row):
137
+ """The one place a mapped row loses its `None`s β€” see the BLANK MEANS NOT READ rule above."""
138
+ return {k: v for k, v in row.items() if v is not None and v != ""}
139
+
140
+
141
+ def normalize_profile(node, handle=""):
142
+ """A TikTok Profiles row β†’ the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
143
+
144
+ ⚠ TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
145
+ * `biography` is PRIMARY and `signature` the FALLBACK β€” the probe measured `signature`
146
+ populated on 85% of rows and they carry the same text;
147
+ * `region` is PRIMARY and `country` the FALLBACK β€” `region` is the one with a documented
148
+ two-letter-ISO description, `country` has no description at all.
149
+ ⚠ `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
150
+ `ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
151
+ only count of its kind the dataset offers.
152
+ """
153
+ node = node if isinstance(node, dict) else {}
154
+ account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
155
+ return _drop_blanks({
156
+ "platform": engine.PLATFORM_TIKTOK,
157
+ "handle": account,
158
+ "full_name": _tt_str(node, "nickname"),
159
+ "tt_id": _tt_str(node, "id"),
160
+ "profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
161
+ "bio": _tt_str(node, "biography", "signature"),
162
+ "external_url": _bd_first_url(_first(node, "bio_link")),
163
+ "verified": _bd_flag(node, "is_verified"),
164
+ "is_private": _bd_flag(node, "is_private"),
165
+ # ⚠ APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
166
+ # on their own description. It is the closest thing TikTok has to Instagram's
167
+ # `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent β€” so
168
+ # the approximation only ever fills a cell the vendor actually answered.
169
+ "is_business": _bd_flag(node, "is_commerce_user"),
170
+ "followers": _ig_int(_first(node, "followers")),
171
+ "following": _ig_int(_first(node, "following")),
172
+ "posts_count": _ig_int(_first(node, "videos_count")),
173
+ # ⚠ `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
174
+ # nulls). It is not a post-level number and it is not our `likes` column, which is why it
175
+ # is stored under a different name.
176
+ "likes_received": _ig_int(_first(node, "likes")),
177
+ "avg_engagement": _tt_pct(node, "awg_engagement_rate"),
178
+ "like_engagement": _tt_pct(node, "like_engagement_rate"),
179
+ "comment_engagement": _tt_pct(node, "comment_engagement_rate"),
180
+ "country_code": _tt_str(node, "region", "country"),
181
+ "region": _tt_str(node, "region"),
182
+ "predicted_lang": _tt_str(node, "predicted_lang"),
183
+ # ⚠ ACCOUNT AGE, NOT A MEASUREMENT STAMP β€” `create_time` on a profile is when the ACCOUNT
184
+ # was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
185
+ # which is why the append law dates a snapshot by when WE read it.
186
+ "account_created_at": _tt_day(node, "create_time"),
187
+ "source_payload": _bd_source_payload(node),
188
+ })
189
+
190
+
191
+ def tt_post_type(node):
192
+ """A TikTok post row β†’ one of OUR three type options, or None.
193
+
194
+ β›” THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
195
+ `"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
196
+ vendor's token would fail `_clean_field`'s option check on the way in and would put an
197
+ untranslated API word in front of a user on the way out.
198
+
199
+ So: `video` is `video`, and `content` β€” TikTok's photo-mode post β€” is `image`, EXCEPT when the
200
+ row carries more than one `carousel_images` entry, which is what a carousel IS on either
201
+ network. ⚠ The multi-image branch is decided from the IMAGES, never from the type token: the
202
+ token cannot express it, so inferring `carousel` from the word would be inventing a fact.
203
+ ⚠ An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
204
+ that is exactly what would make the wrong default invisible).
205
+ """
206
+ raw = str((node or {}).get("post_type") or "").strip().lower()
207
+ if raw == TT_POST_TYPE_VIDEO:
208
+ return "video"
209
+ if raw != TT_POST_TYPE_CONTENT:
210
+ return None
211
+ images = (node or {}).get("carousel_images")
212
+ return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
213
+
214
+
215
+ def normalize_post(node):
216
+ """A TikTok Posts row β†’ the `ut_tt_posts` cell shape. None when it carries no identity.
217
+
218
+ β›” THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
219
+ Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
220
+ fact β€” `play_count` IS the count TikTok displays under a video β€” so it maps to `views` and
221
+ `ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
222
+ manufacture a second measurement that a rollup could average or double-count, which is a worse
223
+ outcome than the missing column it would paper over.
224
+
225
+ ⚠ `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
226
+ the probe measured them as the same shape. That equality is what lets the comments→posts link
227
+ join with NO normaliser, which the Instagram side never had.
228
+ ⚠ `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
229
+ ⚠ `commerce_info` is a business/commerce LOCATION per its own description β€” cities and
230
+ countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
231
+ no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
232
+ """
233
+ node = node if isinstance(node, dict) else {}
234
+ shortcode = _tt_str(node, "shortcode", "post_id")
235
+ if not shortcode:
236
+ return None
237
+ return _drop_blanks({
238
+ "platform": engine.PLATFORM_TIKTOK,
239
+ "shortcode": shortcode,
240
+ "influencer_key": _tt_str(node, "profile_username"),
241
+ "posted_at": _tt_day(node, "create_time"),
242
+ "type": tt_post_type(node),
243
+ "caption": _tt_str(node, "description"),
244
+ "url": _tt_str(node, "url"),
245
+ "hashtags": _bd_list(node, "hashtags"),
246
+ "tagged_location": _tt_str(node, "commerce_info"),
247
+ "views": _ig_int(_first(node, "play_count")),
248
+ "likes": _ig_int(_first(node, "digg_count")),
249
+ "comments": _ig_int(_first(node, "comment_count")),
250
+ "shares": _ig_int(_first(node, "num_share_count")),
251
+ "saves": _ig_int(_first(node, "collect_count")),
252
+ "video_duration": _ig_int(_first(node, "video_duration")),
253
+ "source_payload": _bd_source_payload(node),
254
+ })
255
+
256
+
257
+ def normalize_comment(node):
258
+ """A TikTok Comments row β†’ the `ut_tt_comments` cell shape. None without a comment id.
259
+
260
+ ⚠ THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
261
+ `replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
262
+ `source_payload`. Reading the array's length instead would be a second, disagreeing answer to
263
+ a question the vendor already answers β€” and it would disagree, because a page of replies is not
264
+ all of them.
265
+ ⚠ `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
266
+ text and needs defensive parsing. It still goes through `_tt_day` β€” one date path, so a vendor
267
+ that changes its mind cannot change ours.
268
+ ⚠ The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
269
+ PII) stay in `source_payload` and are promoted to no column, which is the same posture the
270
+ Instagram comment schema takes for the same D-24 reason.
271
+ """
272
+ node = node if isinstance(node, dict) else {}
273
+ comment_key = _tt_str(node, "comment_id")
274
+ if not comment_key:
275
+ return None
276
+ return _drop_blanks({
277
+ "platform": engine.PLATFORM_TIKTOK,
278
+ "comment_key": comment_key,
279
+ "shortcode": _tt_str(node, "post_id"),
280
+ "commented_at": _tt_day(node, "date_created"),
281
+ "likes": _ig_int(_first(node, "num_likes")),
282
+ "replies": _ig_int(_first(node, "num_replies")),
283
+ "source_payload": _bd_source_payload(node),
284
+ })
285
+
286
+
287
+ #: ⭐ The three maps, addressable by name β€” so a gate (and the runners in T04-T06) can walk them
288
+ #: rather than naming three functions, and so adding a fourth dataset is one entry.
289
+ TT_NORMALIZERS = {
290
+ "tt_profile": normalize_profile,
291
+ "tt_post_metrics": normalize_post,
292
+ "tt_comments": normalize_comment,
293
+ }
api/main.py CHANGED
@@ -1,532 +1,545 @@
1
- """AIOS web API β€” the ONE shared, stateless process the Streamlit exit is aimed at.
2
-
3
- It REUSES the `platform/` data layer verbatim (nothing re-implemented): the canonical,
4
- reconciled Odoo model stays server-side and the browser only ever sees derived JSON. Serves the
5
- JSON API under `/api/*` and the built React bundle (`aios-web/web/dist`) at `/`.
6
-
7
- WHAT CHANGED IN EXIT WAVE 1 (2026-07-30) β€” three things, all of them load-bearing:
8
-
9
- * **Real sessions replace HTTP Basic.** The whole app used to sit behind one shared
10
- `APP_PASSWORD` with the browser's native Basic prompt, which means every caller was the same
11
- anonymous principal and no route could scope anything. Now a signed stateless cookie carries
12
- a real `core/users` identity (X3), and every v1 route resolves BU + own-book scope from the
13
- user RECORD. `/api/health` stays unauthenticated (liveness only).
14
- * **The overlay fork is deleted.** `aios-web/api/data/overlay.json` was a second writable home
15
- for user-owned fields the Streamlit app keeps in the tenant store. ONE store now (C1c).
16
- * **The SSL shim is env-gated.** It used to run at import, unconditionally.
17
-
18
- ⚠ TENANT RESOLUTION IS PER REQUEST (X7). Nothing tenant-shaped is held at module level; the
19
- session's tenant claim resolves through `harness.runtime.get_runtime`, which is LRU-bounded. This
20
- is the rule the ~30–80 MB/tenant target depends on β€” EXIT-0 measured the alternative at a ~0.6 GB
21
- commit FLOOR per tenant, duplicated within 2% per tenant, nothing shared.
22
- """
23
- import os
24
- import sys
25
- from pathlib import Path
26
-
27
- # --- the local Odoo SSL quirk, now BEHIND A GATE -------------------------------------------------
28
- # The Windows trust store reports the (valid) Odoo cert as expired, so local runs need an
29
- # unverified default context; the HF Space and the container are unaffected. This used to run
30
- # unconditionally at import β€” i.e. the shipped container disabled TLS verification for every
31
- # outbound HTTPS call it ever made, to Odoo and to everything else, forever. That is a
32
- # man-in-the-middle away from being someone else's data. It is now opt-in, must be set
33
- # deliberately, and is never on by default.
34
- # β›” NEVER set AIOS_INSECURE_SSL in a deployed environment. It exists for one developer laptop.
35
- if os.environ.get("AIOS_INSECURE_SSL") == "1":
36
- import ssl
37
- ssl._create_default_https_context = ssl._create_unverified_context # noqa: S323
38
-
39
- # --- reuse the tenant #0 data layer verbatim. RI_DIR overrides the location in the container
40
- # (where the layout differs from the local sibling-dir default). ---
41
- _HERE = Path(__file__).resolve()
42
- _RI = Path(os.environ.get("RI_DIR") or (_HERE.parents[2] / "platform"))
43
- for _p in (str(_RI), str(_HERE.parent)):
44
- if _p not in sys.path:
45
- sys.path.insert(0, _p)
46
-
47
- from dotenv import load_dotenv # noqa: E402
48
- load_dotenv(_RI / ".env") # Odoo creds + APP_PASSWORD, git-ignored, never committed/printed
49
-
50
- from fastapi import Body, Depends, FastAPI, Request # noqa: E402
51
- from fastapi.middleware.gzip import GZipMiddleware # noqa: E402
52
- from fastapi.responses import JSONResponse # noqa: E402
53
- from fastapi.staticfiles import StaticFiles # noqa: E402
54
- from starlette.exceptions import HTTPException as StarletteHTTPException # noqa: E402
55
-
56
- import aios_session # noqa: E402
57
- import routes_admin # noqa: E402
58
- import routes_alerts # noqa: E402 (wave 20 item 25 β€” the Alerts inbox)
59
- import routes_assets # noqa: E402 (wave 18 C2-ASSET β€” catalog product imagery)
60
- import routes_auth # noqa: E402
61
- import routes_automation # noqa: E402 (wave 18 C4-AUTO β€” SESSION D's router, mounted by A)
62
- import routes_customers # noqa: E402
63
- import routes_grid # noqa: E402
64
- import routes_keychain # noqa: E402 (wave 18 C7 β€” keychain + connectors admin surfaces)
65
- import routes_statements # noqa: E402 (EXIT-6 β€” the statement sender, off Streamlit)
66
- import routes_nav # noqa: E402
67
- import routes_pages # noqa: E402
68
- import routes_platform_admin # noqa: E402 (wave 19 R3/R4 β€” the Loopable cross-tenant plane)
69
- import routes_products # noqa: E402 (wave 15 C-TOPIC β€” gated, not yet in the nav)
70
- import routes_records # noqa: E402
71
- import routes_shares # noqa: E402 (wave 20 R10 β€” grants for views, folders and databases)
72
- import routes_uploads # noqa: E402 (wave 21 C5 β€” tabular preview for Select-from-file)
73
- import routes_tables # noqa: E402 (wave 18 C3-UT β€” user-created databases over the wire)
74
- import routes_connectors # noqa: E402 (wave 23 C11 β€” the connectors directory; SESSION A's router)
75
- import routes_forms # noqa: E402 (wave 23 C9 β€” the PUBLIC form door; SESSION D's router)
76
- import routes_templates # noqa: E402 (wave 23 C12 β€” template apply doors; SESSION E's router)
77
- import routes_odoo_tables # noqa: E402 (wave 27 item 17 β€” Odoo relational; SESSION E's router)
78
- from core import grid_events # noqa: E402
79
- from deps import Session, module_gate # noqa: E402
80
-
81
- _WEB_DIST = _HERE.parents[1] / "web" / "dist"
82
-
83
- # --- THE CANONICAL FIELD CONTRACT: a startup assertion, and the referee gate's subject ----------
84
- # Every field tags its semantic TYPE and its SOURCE. `source='odoo'` is READ-ONLY (Odoo is never
85
- # written); `source='overlay'` is the editable stratum that lives OUTSIDE Odoo. Loaded from the
86
- # ONE canonical file shared with the embedded host (`platform/aios_grid_fields.json`), so
87
- # embed == standalone by construction.
88
- #
89
- # TWO REASONS THIS IS HERE and not folded into the routes:
90
- # 1. It FAILS LOUDLY at import when the file is missing β€” which means the deploy or the RI_DIR
91
- # layout is broken, and discovering that from a 500 on the first customer request instead of
92
- # at startup costs a debugging session. (The pre-wave main.py had this guard; the EXIT-2a
93
- # rewrite dropped it and this restores it.)
94
- # 2. `aios-web/verify_fields_contract.py` β€” the cross-side REFEREE β€” reads `FIELDS` and
95
- # `_PASSTHROUGH_KEYS` from this module to prove the canonical file, `aios_grid.py` and this
96
- # API have not drifted. The rewrite removed them and the referee went red; retargeting the
97
- # gate would have been the wrong repair ([[gate-can-report-green-on-nothing]]: retarget, do
98
- # not delete β€” but only when the subject genuinely moved. Here it should not have moved).
99
- #
100
- # ⚠ THE ROUTES SERVE A SUPERSET OF THIS. `routes_customers._payload` derives its field list from
101
- # `aios_grid.fields_from_workspace(ws)`, which is `FIELDS` PLUS the session user's own custom_ and
102
- # measure_ columns β€” the same list the Streamlit host renders. That is the point: the standalone
103
- # shell now sees the user's own columns instead of the bare base contract. `FIELDS` is the
104
- # canonical FLOOR, asserted below to be exactly what `aios_grid` starts from.
105
- import json as _json_contract # noqa: E402
106
- _FIELDS_PATH = _RI / "aios_grid_fields.json"
107
- if not _FIELDS_PATH.is_file():
108
- raise FileNotFoundError(
109
- f"AIOS web API: canonical field contract missing at {_FIELDS_PATH}. Set RI_DIR to the "
110
- "platform root (it also carries the data layer this API imports)."
111
- )
112
- _contract = _json_contract.loads(_FIELDS_PATH.read_text(encoding="utf-8"))
113
- FIELDS = _contract["fields"] if isinstance(_contract, dict) else _contract
114
- # text/status/select/date pass through untouched; every OTHER odoo field is numeric -> rounded.
115
- # Derived from field TYPE (not a hand-kept key list) so a new text/date field can never be
116
- # wrongly rounded. `select` joined 2026-08-02 (dba) β€” a choice label rounded would be garbage.
117
- _PASSTHROUGH_KEYS = {f["key"] for f in FIELDS
118
- if f["source"] == "odoo" and f["type"] in ("text", "status", "select",
119
- "date")}
120
-
121
- app = FastAPI(title="AIOS web API")
122
-
123
- # The customers payload measured 1.15 MB of JSON on the live Space, shipped UNCOMPRESSED β€” with
124
- # the 754 KB bundle behind it, most of "the app is slow" was bytes on the wire. gzip takes the
125
- # payload to ~10–15% of that. minimum_size spares the tiny acks the overhead.
126
- app.add_middleware(GZipMiddleware, minimum_size=1024)
127
-
128
-
129
- @app.exception_handler(StarletteHTTPException)
130
- def _error_shape(request: Request, exc: StarletteHTTPException):
131
- """ONE error shape for every non-2xx (X2): `{"error": {"code", "message"}}`.
132
-
133
- `deps.err` already raises detail in that shape; anything FastAPI raises on its own (a 404, a
134
- 422 from a malformed path param) is wrapped here so a client never has to branch on two
135
- different error bodies.
136
- """
137
- detail = exc.detail
138
- if isinstance(detail, dict) and "error" in detail:
139
- body = detail
140
- else:
141
- body = {"error": {"code": f"http_{exc.status_code}", "message": str(detail)}}
142
- return JSONResponse(body, status_code=exc.status_code,
143
- headers=getattr(exc, "headers", None))
144
-
145
-
146
- @app.exception_handler(grid_events.StoreUnavailable)
147
- def _store_unavailable(request: Request, exc: grid_events.StoreUnavailable):
148
- """THE SAFETY NET for "the store is down" β†’ 503, from anywhere.
149
-
150
- ⚠ WHY THIS IS APP-LEVEL AND NOT A `try` PER ROUTE. It was a try per route first, and a
151
- `StoreUnavailable` raised while BUILDING THE PAYLOAD β€” before the route reached its own
152
- try/except β€” surfaced as a 500. A store outage is a normal operational state and every route
153
- here touches the store at least twice (the workspace read, then the write), so "remember to
154
- wrap it" is a rule that gets forgotten once and then reports the wrong thing. One handler
155
- means a store outage can only ever be a 503, whichever call raised it.
156
-
157
- The seam raises this only when the caller passed no `fallback_ws` β€” i.e. exactly on this
158
- adapter, which has no durable session dict to degrade into. A 200 over a write that
159
- evaporated is the failure the whole rule exists to prevent.
160
- """
161
- return JSONResponse(
162
- {"error": {"code": "store_unavailable",
163
- "message": "the tenant store is unavailable β€” no change was saved"}},
164
- status_code=503)
165
-
166
-
167
- @app.get("/api/health")
168
- def health():
169
- """Unauthenticated LIVENESS only β€” it must answer before anyone can sign in, so it may not
170
- reveal anything about the deployment beyond "the process is up". No version, no tenant list,
171
- no config: a health endpoint is the one URL every scanner finds first.
172
-
173
- β›” THE VERSION DOES NOT GO HERE, and it was asked to (2026-08-04, when LIVE became a pinned
174
- release and "what is LIVE running" needed an answer). A build identifier tells an unauthenticated
175
- caller exactly which commit's known issues apply. It rides `GET /api/v1/settings` instead, behind
176
- a session β€” and the authoritative copy is the `VERSION` file in the Space repo, which
177
- `deploy_web.space_version()` reads without needing the app to be up at all."""
178
- return {"ok": True}
179
-
180
-
181
- app.include_router(routes_auth.router)
182
- app.include_router(routes_nav.router)
183
- app.include_router(routes_customers.router)
184
- app.include_router(routes_products.router)
185
- app.include_router(routes_assets.router)
186
- app.include_router(routes_tables.router)
187
- app.include_router(routes_grid.router)
188
- app.include_router(routes_records.router)
189
- # EXIT wave 2: the Y1 page-data envelope (one route for every ported dashboard) and Y4's user
190
- # administration. `routes_pages` imports `pages`, which lazily imports each `pages_*` builder β€” so
191
- # a new page is a builder module plus one registry line, and nothing here changes.
192
- app.include_router(routes_pages.router)
193
- app.include_router(routes_admin.router)
194
- app.include_router(routes_automation.router)
195
- app.include_router(routes_keychain.router)
196
- app.include_router(routes_statements.router)
197
- # Wave 19 (owner item 13, R3): the LOOPABLE admin plane β€” the platform's own cross-tenant view.
198
- # Its own prefix (`/api/v1/platform-admin`), never nested under `/admin`, so there is no path
199
- # ambiguity with `routes_admin`'s `{username}` params and no chance of a tenant-admin route and a
200
- # platform-operator route ever shadowing each other. Every path it declares is gated by
201
- # `core.platform_admin.is_platform_admin`, and `verify_api` enumerates this router to prove it.
202
- app.include_router(routes_platform_admin.router)
203
- # Wave 20 (owner items 25 + 18/23/26): the Alerts inbox and the manage-access surface. Both are
204
- # session-gated rather than admin-gated β€” an alert is a person's own subscription, and sharing is
205
- # something every user does with their own views/folders/databases.
206
- app.include_router(routes_alerts.router)
207
- app.include_router(routes_shares.router)
208
- app.include_router(routes_uploads.router)
209
- # ⭐ WAVE 23 β€” THE THREE NEW ROUTERS. Mounted here, above the static catch-all at the bottom of this
210
- # file, because `app.mount("/", _AppStatic(...), html=True)` swallows everything it is reached by:
211
- # a router included AFTER it answers 404 forever while importing fine, type-checking fine and
212
- # passing its own gate. That is the wave-20 declared-but-unmounted shape with a different cause.
213
- #
214
- # β›” ALL THREE EXISTED, COMPLETE AND GATED, WITH NO MOUNT until the close-out audit β€” three finished
215
- # features that would have shipped dead. The workers each posted a mount ask and said they would
216
- # signal "ready" first; C waited for a signal that never came while the files landed anyway. **The
217
- # lesson is not "read the mailbox harder": `verify_api`'s enumeration is what caught it, so the
218
- # control is that the enumeration must NAME every router in this file.**
219
- app.include_router(routes_templates.router) # item 7 / C12 β€” template registry, session-gated
220
- app.include_router(routes_connectors.router) # item 10 / C11 β€” the connectors directory
221
- # ⚠ routes_forms is the FIRST NEW PUBLIC DOOR since the `_DEV_FIXTURES` scar (see :257 below). Its
222
- # two paths are DELIBERATELY unauthenticated β€” a form is filled in by someone with no account β€” so
223
- # it joins `/api/health`, the automation hook and the tick on the exempt list. It resolves a token
224
- # by scanning tenants with a constant-time compare and answers a uniform 403, so a bad token cannot
225
- # distinguish "no such form" from "not yours", and it never echoes a tenant, table or slug.
226
- app.include_router(routes_forms.router) # item 8 / C9 β€” the PUBLIC form door
227
- # WAVE 27 item 17 β€” E's Odoo relational doors. Mounted in the SAME change that E's module landed,
228
- # because the wave-23 scar is exactly this: three finished routers shipped with no include_router
229
- # line β€” complete, gated, type-clean and 404 for every caller. `verify_api.section_mounts` walks
230
- # `main.app.routes` and pins these two paths by NAME, so an unmounted router now goes RED.
231
- app.include_router(routes_odoo_tables.router)
232
-
233
-
234
- # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)
235
- # They are the v1 handlers with the v1 session requirement β€” NOT the old unauthenticated Basic
236
- # behavior. An alias that kept the old auth would be a bypass of everything above it.
237
- _GATE = module_gate(routes_customers.MODULE)
238
-
239
-
240
- @app.get("/api/customers", deprecated=True)
241
- def _customers_alias(session: Session = Depends(_GATE)):
242
- return routes_customers._payload(session)
243
-
244
-
245
- @app.patch("/api/customers/{pid}", deprecated=True)
246
- def _patch_alias(pid: int, body: dict = Body(default=None),
247
- session: Session = Depends(_GATE)):
248
- return routes_customers.patch_customer(pid, body, session)
249
-
250
-
251
- def _assert_contract_floor():
252
- """The canonical FIELDS must be exactly what `aios_grid` starts an empty workspace from.
253
-
254
- This is what stops `FIELDS` becoming a constant that exists only to satisfy a gate. If the
255
- canonical JSON and `aios_grid.fields_from_workspace({})` ever disagree, the standalone API and
256
- the embedded host are serving two different schemas and the grid's own contract has forked β€”
257
- the exact drift `verify_fields_contract.py` was written to catch, now also caught at startup
258
- on whatever machine is actually running.
259
- """
260
- import aios_grid
261
- base = [f for f in aios_grid.fields_from_workspace({}) if not f.get("custom")]
262
- if [f["key"] for f in base] != [f["key"] for f in FIELDS]:
263
- raise RuntimeError(
264
- "AIOS web API: the canonical field contract and aios_grid.fields_from_workspace({}) "
265
- "disagree on the base field set β€” embed and standalone would serve different schemas. "
266
- "Run aios-web/verify_fields_contract.py.")
267
-
268
-
269
- def _startup_notes():
270
- """Say the two things an operator must know, once, at import β€” never in a response body."""
271
- if aios_session.EPHEMERAL_SECRET:
272
- print("[aios-api] AIOS_SESSION_SECRET is not set β€” signing with a random per-process "
273
- "key. Sessions will not survive a restart and will not work across workers. "
274
- "Set it in production.")
275
- if os.environ.get("AIOS_INSECURE_SSL") == "1":
276
- print("[aios-api] AIOS_INSECURE_SSL=1 β€” TLS verification is DISABLED for outbound "
277
- "requests. Local development only; never in a deployed environment.")
278
-
279
-
280
- _assert_contract_floor()
281
- _startup_notes()
282
-
283
-
284
- # β›” THE STATIC MOUNT IS NOW UNAUTHENTICATED, and that is a change this wave made on purpose.
285
- # Before EXIT-3a, `BasicAuth` middleware gated the WHOLE app including this mount. A branded login
286
- # page cannot live behind a password prompt, so the shell's own assets must be public β€” which they
287
- # are: `index.html`, the JS/CSS bundle and the favicon reveal nothing.
288
- #
289
- # ⚠ WHAT THAT SILENTLY DE-GATED, caught in review rather than in production. `web/dist/` also
290
- # carries `sample_customers.json`, a DEV FIXTURE copied from `web/public/`. Its 8 customers are
291
- # synthetic, but the `agent` column holds REAL EMPLOYEE NAMES, and it went from Basic-gated to
292
- # publicly fetchable in this commit. Nothing needs it: both the API bridge and `useCustomerData`
293
- # deleted their sample fallback on purpose ("NOTHING HERE FALLS BACK TO sample_customers.json"),
294
- # and it survives only because it sits in `web/public/`. So it is refused here β€” 404, the same
295
- # answer as any other path that is not part of the app.
296
- #
297
- # The right long-term fix is deleting it from `web/public/` (S2's lane β€” flagged in the mailbox);
298
- # this guard is what makes the API safe regardless of what the bundle happens to contain.
299
- _DEV_FIXTURES = {"sample_customers.json"}
300
-
301
-
302
- class _AppStatic(StaticFiles):
303
- async def get_response(self, path, scope):
304
- if Path(path).name in _DEV_FIXTURES:
305
- raise StarletteHTTPException(status_code=404, detail="Not Found")
306
- resp = await super().get_response(path, scope)
307
- # Vite content-hashes everything under assets/ (a change is a NEW url), so those are
308
- # immutable β€” a repeat visit re-downloads zero bytes instead of the whole 750 KB bundle.
309
- # index.html must stay revalidated or a deploy would strand returning browsers on the old
310
- # bundle; ETag/304 makes that revalidation a header exchange, not a transfer.
311
- # ⚠ Normalised first: on a Windows host StaticFiles hands this path with backslashes,
312
- # and `startswith("assets/")` silently skipped every asset (measured on the local probe).
313
- if path.replace("\\", "/").lstrip("/").startswith("assets/"):
314
- resp.headers["Cache-Control"] = "public, max-age=31536000, immutable"
315
- else:
316
- resp.headers["Cache-Control"] = "no-cache"
317
- return resp
318
-
319
-
320
- # static bundle LAST so /api/* wins; html=True serves index.html at / plus the built assets
321
- if _WEB_DIST.is_dir():
322
- app.mount("/", _AppStatic(directory=str(_WEB_DIST), html=True), name="web")
323
-
324
-
325
- # --- boot prewarm (AIOS_PREWARM=1 β€” set by the Dockerfile, never by tests) -----------------------
326
- # Without this, the first visitor after every deploy/restart pays the full Odoo pool build in
327
- # their request. The thread warms the CONSOLIDATED scope (None, None) + every registered page's
328
- # default envelope; scoped users still pay their own scope's first build, once.
329
- # Env-gated rather than a startup event so importing `api.main` in a gate (verify_api and friends
330
- # run against fakes) can never fire a live Odoo pull.
331
- def _seed_and_sync_store():
332
- """Bring the analytical store (harness.datastore) LIVE for this container β€” the app.py
333
- bootstrap, mirrored (2026-07-31, owner item 1).
334
-
335
- `harness.datastore` powers every measure column/condition, and ONLY app.py used to call
336
- `ensure_seed()` β€” so on a fresh Space disk this container resolved measures against a store
337
- that never existed and every measure cell served blank. Seeding alone was NOT enough either,
338
- and that was measured live the same day: "datastore seeded in 1.7s" followed by an endless
339
- `api:measure-column: ModelError the data cache is still warming up` β€” `ready()` demands
340
- EVERY entity at phase 'live', and a seed that predates a newer entity leaves it un-synced
341
- forever in a process with no sync loop. The SYNC SPRINT after the seed is what closes the
342
- write_date gap and backfills anything the seed lacks (app.py:7779's exact pattern, bounded
343
- passes). Fail-quiet throughout: no seed/token/Odoo β†’ the columns stay blank, the rows still
344
- serve.
345
- """
346
- import time as _t
347
- t0 = _t.time()
348
- try:
349
- from harness import datastore as _ds
350
- if _ds.ensure_seed():
351
- print(f"[aios-api] datastore seeded in {_t.time() - t0:.1f}s")
352
- # DEDICATED Odoo connection for this thread (the W6 postmortem rule): the sync's
353
- # search_reads must never interleave on the shared client's xmlrpc transport.
354
- import core.odoo as _odoo
355
- try:
356
- _odoo._tlocal.client = _odoo.OdooClient()
357
- except Exception:
358
- pass
359
- res = {}
360
- for i in range(12):
361
- res = _ds.sync_all(log=lambda *a, **k: None)
362
- print(f"[aios-api] datastore sync pass {i + 1}: "
363
- + ", ".join(f"{k}={v.get('phase')}" for k, v in sorted(res.items())))
364
- if all(v.get("phase") == "live" for v in res.values()):
365
- break
366
- # ⭐ Wave 21 (item 2, "make sure the metrics are correct"): a cursor sync can never see
367
- # a HARD DELETE, and the downloaded seed carries whatever was deleted since it was cut β€”
368
- # one reconcile pass at boot removes both classes of phantom row before the first
369
- # measure is served. MEASURED 2026-08-05: five deleted sale_order_line rows = $284.25 of
370
- # phantom YTD revenue, stable across re-syncs, zero the moment reconcile ran.
371
- try:
372
- _ds.reconcile_deletes(log=lambda *a, **k: None)
373
- except Exception:
374
- pass
375
- print(f"[aios-api] datastore sync done in {_t.time() - t0:.1f}s "
376
- f"(ready={_ds.ready()})")
377
- # ⭐⭐ 2026-08-09 (wave 28, D-107) β€” THE RELATIONAL REBUILD RUNS AT BOOT, HERE.
378
- #
379
- # β›” IT DID NOT BEFORE, AND NOTHING SAID SO. The rebuild lived only inside
380
- # `_store_resync_loop`, whose very first statement is `sleep(1800)` β€” so the earliest a
381
- # freshly booted container could spawn the four locked databases was T+30 MINUTES. The
382
- # symptom was read as "the boot path is silent": `/odoo-tables/status` polled every 30 s
383
- # across a ~20-minute window over two boots returned the pre-wave schema on all 20
384
- # samples. It was not silent, it had not been asked yet. Both halves of D-107 were like
385
- # this β€” a thing that never ran, mistaken for a thing that ran and failed.
386
- #
387
- # ⚠ WHY HERE AND NOT IN `_prewarm`: the tables are DERIVED FROM THE MIRROR, and this is
388
- # the exact line where the mirror has finished advancing β€” seed, up to twelve sync passes,
389
- # then the delete reconcile. Calling it from the other thread would race the seed and hit
390
- # either `ro_con()`'s "still warming" RuntimeError or, worse, a HALF-SYNCED mirror, which
391
- # is D-107's own hypothesis 3: a partial population trips `MAX_SHRINK` and the rebuild
392
- # refuses β€” correctly, but for a reason that reads like a data loss scare.
393
- # ⚠ Same thread on purpose: it is already a daemon and nothing serves requests behind it.
394
- _rebuild_odoo_relational("boot")
395
- except Exception as e: # noqa: BLE001
396
- print(f"[aios-api] datastore seed/sync skipped: {e}")
397
-
398
-
399
- def _rebuild_odoo_relational(why):
400
- """Spawn/refresh the four locked Odoo databases, then compute their cells. `why` is 'boot' or
401
- 'resync' and rides every log line, because "it failed" and "it failed at boot, before anyone
402
- could have asked" are different diagnoses.
403
-
404
- ⭐ THE SUCCESS LINE IS NOT DECORATION β€” it is the control this path lacked. D-107 was chased
405
- for a day on the strength of *absent* log markers, which cannot distinguish "the rebuild ran
406
- and was fine" from "the rebuild was never reached". Three failure markers and no success
407
- marker means silence is ambiguous; now it is not.
408
-
409
- ⚠ SCOPED TO ROYAL-IMPORTS, deliberately, and it is NOT the D-29 shortcut it resembles. The
410
- caller has just advanced whichever DuckDB file this process holds open β€” tenant #0's β€” and
411
- royal is the only tenant with an Odoo mirror to derive from (R1). Iterating tenants here walks
412
- straight into D-29's documented hazard: `harness/datastore` is a ONE-FILE-AT-A-TIME
413
- process-global, and rebinding it in a daemon thread under live readers can serve one tenant's
414
- rows to another with nothing raised. `is_royal` stays the authority on which slugs qualify.
415
- """
416
- try:
417
- import odoo_relational as _rel
418
- from harness import runtime as _runtime
419
- if not _rel.is_royal("royal-imports"):
420
- return
421
- _rt = _runtime.get_runtime("royal-imports")
422
- counts = _rel.refresh(_rt, "royal-imports")
423
- # ⭐⭐ AND THEN COMPUTE THE CELLS, which `refresh` does NOT do.
424
- #
425
- # β›” THE FAILURE THIS CLOSES IS THE WORST-LOOKING KIND. `refresh` writes rows and field
426
- # DEFINITIONS; every Link and Rollup cell comes from a separate pass. Those passes used to
427
- # live only on the automation `tick`, which fires from an EXTERNAL EventBridge cron β€” so a
428
- # fresh boot landed 71,954 rows with eleven fully-configured relational columns and every
429
- # one of them BLANK until an unrelated scheduler happened to run. Nothing errors; the
430
- # tables simply look finished and answer nothing.
431
- #
432
- # ⚠ `refresh_relations`, NOT `compute_relation_cells`. The latter computes a change count
433
- # over a blob it was handed and PERSISTS NOTHING; the former walks the tenant and writes.
434
- # Calling the inner one here would return a plausible number and change no cell.
435
- #
436
- # ⚠ ONE try/except PER PASS, for the reason `tick` states at its own copies: a source
437
- # rollup REFUSES loudly on a truncated group set, and a shared block would let that honest
438
- # refusal silently cancel a relational pass that had already succeeded.
439
- try:
440
- import automation_engine as _engine
441
- _engine.refresh_relations(_rt, log=lambda *_a: None)
442
- except Exception as e: # noqa: BLE001
443
- print(f"[aios-api] odoo relation cells failed ({why}): {type(e).__name__}: {e}")
444
- try:
445
- import rollup_sql as _rollup
446
- for _b, _key, _l, _f in _rel.TABLES:
447
- _rollup.compute(_rt, _key)
448
- except Exception as e: # noqa: BLE001
449
- print(f"[aios-api] odoo source rollups failed ({why}): {type(e).__name__}: {e}")
450
- print(f"[aios-api] odoo relational rebuild done ({why}): "
451
- + ", ".join(f"{k}={v}" for k, v in sorted((counts or {}).items())))
452
- except Exception as e: # noqa: BLE001
453
- # ⚠ The TYPE is named here as it is in the two inner handlers. The original printed only
454
- # `{e}`, and a bare message is exactly what made D-107 unreadable from the outside: a
455
- # `BinderException` about a missing column is a different action from a timeout or an auth
456
- # failure, and the text alone often does not say which it was.
457
- print(f"[aios-api] odoo relational rebuild failed ({why}): {type(e).__name__}: {e}")
458
-
459
-
460
- def _store_resync_loop():
461
- """Keep the analytical mirror current β€” the API-process stand-in for the re-sync the
462
- Streamlit app piggybacks on page renders. Measure memos key on the pool stamp, so a
463
- refreshed pool re-reads the freshly synced store."""
464
- import time as _t
465
- passes = 0
466
- while True:
467
- _t.sleep(1800)
468
- passes += 1
469
- try:
470
- from harness import datastore as _ds
471
- import core.odoo as _odoo
472
- try:
473
- _odoo._tlocal.client = _odoo.OdooClient()
474
- except Exception:
475
- pass
476
- _ds.sync_all(log=lambda *a, **k: None)
477
- # Wave 21 β€” every 4th pass (~2h): purge hard-deleted rows the cursor sync cannot
478
- # see (the boot pass's comment has the measured case). Cheap id-sweep per entity;
479
- # without it deleted Odoo lines inflate every sum on the mirror FOREVER.
480
- if passes % 4 == 0:
481
- _ds.reconcile_deletes(log=lambda *a, **k: None)
482
- except Exception as e: # noqa: BLE001
483
- print(f"[aios-api] store resync failed: {e}")
484
- # ⭐ WAVE 27 item 17 (E's ASK ->A, resolved): the Odoo RELATIONAL tables are rebuilt
485
- # AFTER the mirror they are derived from, in the same pass and in that order β€” deriving
486
- # from a mirror this loop is about to advance would publish a worklist one cycle stale
487
- # every single time.
488
- #
489
- # β›” OUTSIDE the try/except above, NOT folded into it. A failing relational rebuild must
490
- # not swallow the sync's error message, and β€” worse the other way β€” a sync failure must
491
- # not skip a rebuild that had nothing wrong with it. Two independent failures, two
492
- # independent logs. (`_rebuild_odoo_relational` carries its own handlers.)
493
- #
494
- # ⚠ THE REBUILD IS NOT THE FRESHNESS GUARANTEE β€” the rows carry a visible `_refreshed`
495
- # stamp for that. This loop is a daemon thread whose failure path is a `print` (D-29), so
496
- # "the wiring exists" and "the data is current" are different claims and only the stamp
497
- # can tell a user which one they are looking at.
498
- #
499
- # ⭐ ONE IMPLEMENTATION, TWO CALLERS (wave 28). This block used to be the only copy, which
500
- # is what made the boot path silent for 30 minutes after every restart; it is now the
501
- # SECOND caller of the same function `_seed_and_sync_store` calls at boot. A copy here
502
- # would be a second thing to keep in step, and the two would answer differently on the
503
- # next ruling β€” the exact shape the Views top-up was just fixed for on the other side of
504
- # this wave.
505
- _rebuild_odoo_relational("resync")
506
-
507
-
508
- def _prewarm():
509
- import time as _t
510
- t0 = _t.time()
511
- # ⚠ The store sync runs in its OWN thread, never ahead of the pool warm: a stale seed can
512
- # take many minutes of XML-RPC to close, and the first live probe of this arrangement
513
- # showed the pool warm (42s) silently queued behind it β€” the whole app cold for every
514
- # visitor while a background column channel caught up. Measure cells retry via the
515
- # transient rule until the sync lands; nothing else waits on it.
516
- import threading as _th
517
- _th.Thread(target=_seed_and_sync_store, daemon=True, name="store-seed-sync").start()
518
- try:
519
- from harness import runtime as _runtime
520
- rt = _runtime.get_runtime("royal-imports")
521
- routes_customers.warm_default(rt)
522
- import pages as _pages
523
- _pages.warm_default(rt)
524
- print(f"[aios-api] prewarm done in {_t.time() - t0:.1f}s")
525
- except Exception as e: # noqa: BLE001 β€” boot must not die on a warm-up
526
- print(f"[aios-api] prewarm skipped: {e}")
527
-
528
-
529
- if os.environ.get("AIOS_PREWARM") == "1":
530
- import threading as _threading
531
- _threading.Thread(target=_prewarm, daemon=True, name="prewarm").start()
532
- _threading.Thread(target=_store_resync_loop, daemon=True, name="store-resync").start()
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """AIOS web API β€” the ONE shared, stateless process the Streamlit exit is aimed at.
2
+
3
+ It REUSES the `platform/` data layer verbatim (nothing re-implemented): the canonical,
4
+ reconciled Odoo model stays server-side and the browser only ever sees derived JSON. Serves the
5
+ JSON API under `/api/*` and the built React bundle (`aios-web/web/dist`) at `/`.
6
+
7
+ WHAT CHANGED IN EXIT WAVE 1 (2026-07-30) β€” three things, all of them load-bearing:
8
+
9
+ * **Real sessions replace HTTP Basic.** The whole app used to sit behind one shared
10
+ `APP_PASSWORD` with the browser's native Basic prompt, which means every caller was the same
11
+ anonymous principal and no route could scope anything. Now a signed stateless cookie carries
12
+ a real `core/users` identity (X3), and every v1 route resolves BU + own-book scope from the
13
+ user RECORD. `/api/health` stays unauthenticated (liveness only).
14
+ * **The overlay fork is deleted.** `aios-web/api/data/overlay.json` was a second writable home
15
+ for user-owned fields the Streamlit app keeps in the tenant store. ONE store now (C1c).
16
+ * **The SSL shim is env-gated.** It used to run at import, unconditionally.
17
+
18
+ ⚠ TENANT RESOLUTION IS PER REQUEST (X7). Nothing tenant-shaped is held at module level; the
19
+ session's tenant claim resolves through `harness.runtime.get_runtime`, which is LRU-bounded. This
20
+ is the rule the ~30–80 MB/tenant target depends on β€” EXIT-0 measured the alternative at a ~0.6 GB
21
+ commit FLOOR per tenant, duplicated within 2% per tenant, nothing shared.
22
+ """
23
+ import os
24
+ import sys
25
+ from pathlib import Path
26
+
27
+ # --- the local Odoo SSL quirk, now BEHIND A GATE -------------------------------------------------
28
+ # The Windows trust store reports the (valid) Odoo cert as expired, so local runs need an
29
+ # unverified default context; the HF Space and the container are unaffected. This used to run
30
+ # unconditionally at import β€” i.e. the shipped container disabled TLS verification for every
31
+ # outbound HTTPS call it ever made, to Odoo and to everything else, forever. That is a
32
+ # man-in-the-middle away from being someone else's data. It is now opt-in, must be set
33
+ # deliberately, and is never on by default.
34
+ # β›” NEVER set AIOS_INSECURE_SSL in a deployed environment. It exists for one developer laptop.
35
+ if os.environ.get("AIOS_INSECURE_SSL") == "1":
36
+ import ssl
37
+ ssl._create_default_https_context = ssl._create_unverified_context # noqa: S323
38
+
39
+ # --- reuse the tenant #0 data layer verbatim. RI_DIR overrides the location in the container
40
+ # (where the layout differs from the local sibling-dir default). ---
41
+ _HERE = Path(__file__).resolve()
42
+ _RI = Path(os.environ.get("RI_DIR") or (_HERE.parents[2] / "platform"))
43
+ for _p in (str(_RI), str(_HERE.parent)):
44
+ if _p not in sys.path:
45
+ sys.path.insert(0, _p)
46
+
47
+ from dotenv import load_dotenv # noqa: E402
48
+ load_dotenv(_RI / ".env") # Odoo creds + APP_PASSWORD, git-ignored, never committed/printed
49
+
50
+ from fastapi import Body, Depends, FastAPI, Request # noqa: E402
51
+ from fastapi.middleware.gzip import GZipMiddleware # noqa: E402
52
+ from fastapi.responses import JSONResponse # noqa: E402
53
+ from fastapi.staticfiles import StaticFiles # noqa: E402
54
+ from starlette.exceptions import HTTPException as StarletteHTTPException # noqa: E402
55
+
56
+ import aios_session # noqa: E402
57
+ import routes_admin # noqa: E402
58
+ import routes_alerts # noqa: E402 (wave 20 item 25 β€” the Alerts inbox)
59
+ import routes_assets # noqa: E402 (wave 18 C2-ASSET β€” catalog product imagery)
60
+ import routes_auth # noqa: E402
61
+ import routes_automation # noqa: E402 (wave 18 C4-AUTO β€” SESSION D's router, mounted by A)
62
+ import routes_changes # noqa: E402 (wave 29 item 20 / C6 β€” F's change token, mounted by A)
63
+ import routes_customers # noqa: E402
64
+ import routes_grid # noqa: E402
65
+ import routes_keychain # noqa: E402 (wave 18 C7 β€” keychain + connectors admin surfaces)
66
+ import routes_statements # noqa: E402 (EXIT-6 β€” the statement sender, off Streamlit)
67
+ import routes_nav # noqa: E402
68
+ import routes_pages # noqa: E402
69
+ import routes_platform_admin # noqa: E402 (wave 19 R3/R4 β€” the Loopable cross-tenant plane)
70
+ import routes_products # noqa: E402 (wave 15 C-TOPIC β€” gated, not yet in the nav)
71
+ import routes_records # noqa: E402
72
+ import routes_shares # noqa: E402 (wave 20 R10 β€” grants for views, folders and databases)
73
+ import routes_uploads # noqa: E402 (wave 21 C5 β€” tabular preview for Select-from-file)
74
+ import routes_tables # noqa: E402 (wave 18 C3-UT β€” user-created databases over the wire)
75
+ import routes_connectors # noqa: E402 (wave 23 C11 β€” the connectors directory; SESSION A's router)
76
+ import routes_forms # noqa: E402 (wave 23 C9 β€” the PUBLIC form door; SESSION D's router)
77
+ import routes_templates # noqa: E402 (wave 23 C12 β€” template apply doors; SESSION E's router)
78
+ import routes_odoo_tables # noqa: E402 (wave 27 item 17 β€” Odoo relational; SESSION E's router)
79
+ from core import grid_events # noqa: E402
80
+ from deps import Session, module_gate # noqa: E402
81
+
82
+ _WEB_DIST = _HERE.parents[1] / "web" / "dist"
83
+
84
+ # --- THE CANONICAL FIELD CONTRACT: a startup assertion, and the referee gate's subject ----------
85
+ # Every field tags its semantic TYPE and its SOURCE. `source='odoo'` is READ-ONLY (Odoo is never
86
+ # written); `source='overlay'` is the editable stratum that lives OUTSIDE Odoo. Loaded from the
87
+ # ONE canonical file shared with the embedded host (`platform/aios_grid_fields.json`), so
88
+ # embed == standalone by construction.
89
+ #
90
+ # TWO REASONS THIS IS HERE and not folded into the routes:
91
+ # 1. It FAILS LOUDLY at import when the file is missing β€” which means the deploy or the RI_DIR
92
+ # layout is broken, and discovering that from a 500 on the first customer request instead of
93
+ # at startup costs a debugging session. (The pre-wave main.py had this guard; the EXIT-2a
94
+ # rewrite dropped it and this restores it.)
95
+ # 2. `aios-web/verify_fields_contract.py` β€” the cross-side REFEREE β€” reads `FIELDS` and
96
+ # `_PASSTHROUGH_KEYS` from this module to prove the canonical file, `aios_grid.py` and this
97
+ # API have not drifted. The rewrite removed them and the referee went red; retargeting the
98
+ # gate would have been the wrong repair ([[gate-can-report-green-on-nothing]]: retarget, do
99
+ # not delete β€” but only when the subject genuinely moved. Here it should not have moved).
100
+ #
101
+ # ⚠ THE ROUTES SERVE A SUPERSET OF THIS. `routes_customers._payload` derives its field list from
102
+ # `aios_grid.fields_from_workspace(ws)`, which is `FIELDS` PLUS the session user's own custom_ and
103
+ # measure_ columns β€” the same list the Streamlit host renders. That is the point: the standalone
104
+ # shell now sees the user's own columns instead of the bare base contract. `FIELDS` is the
105
+ # canonical FLOOR, asserted below to be exactly what `aios_grid` starts from.
106
+ import json as _json_contract # noqa: E402
107
+ _FIELDS_PATH = _RI / "aios_grid_fields.json"
108
+ if not _FIELDS_PATH.is_file():
109
+ raise FileNotFoundError(
110
+ f"AIOS web API: canonical field contract missing at {_FIELDS_PATH}. Set RI_DIR to the "
111
+ "platform root (it also carries the data layer this API imports)."
112
+ )
113
+ _contract = _json_contract.loads(_FIELDS_PATH.read_text(encoding="utf-8"))
114
+ FIELDS = _contract["fields"] if isinstance(_contract, dict) else _contract
115
+ # text/status/select/date pass through untouched; every OTHER odoo field is numeric -> rounded.
116
+ # Derived from field TYPE (not a hand-kept key list) so a new text/date field can never be
117
+ # wrongly rounded. `select` joined 2026-08-02 (dba) β€” a choice label rounded would be garbage.
118
+ _PASSTHROUGH_KEYS = {f["key"] for f in FIELDS
119
+ if f["source"] == "odoo" and f["type"] in ("text", "status", "select",
120
+ "date")}
121
+
122
+ app = FastAPI(title="AIOS web API")
123
+
124
+ # The customers payload measured 1.15 MB of JSON on the live Space, shipped UNCOMPRESSED β€” with
125
+ # the 754 KB bundle behind it, most of "the app is slow" was bytes on the wire. gzip takes the
126
+ # payload to ~10–15% of that. minimum_size spares the tiny acks the overhead.
127
+ app.add_middleware(GZipMiddleware, minimum_size=1024)
128
+
129
+
130
+ @app.exception_handler(StarletteHTTPException)
131
+ def _error_shape(request: Request, exc: StarletteHTTPException):
132
+ """ONE error shape for every non-2xx (X2): `{"error": {"code", "message"}}`.
133
+
134
+ `deps.err` already raises detail in that shape; anything FastAPI raises on its own (a 404, a
135
+ 422 from a malformed path param) is wrapped here so a client never has to branch on two
136
+ different error bodies.
137
+ """
138
+ detail = exc.detail
139
+ if isinstance(detail, dict) and "error" in detail:
140
+ body = detail
141
+ else:
142
+ body = {"error": {"code": f"http_{exc.status_code}", "message": str(detail)}}
143
+ return JSONResponse(body, status_code=exc.status_code,
144
+ headers=getattr(exc, "headers", None))
145
+
146
+
147
+ @app.exception_handler(grid_events.StoreUnavailable)
148
+ def _store_unavailable(request: Request, exc: grid_events.StoreUnavailable):
149
+ """THE SAFETY NET for "the store is down" β†’ 503, from anywhere.
150
+
151
+ ⚠ WHY THIS IS APP-LEVEL AND NOT A `try` PER ROUTE. It was a try per route first, and a
152
+ `StoreUnavailable` raised while BUILDING THE PAYLOAD β€” before the route reached its own
153
+ try/except β€” surfaced as a 500. A store outage is a normal operational state and every route
154
+ here touches the store at least twice (the workspace read, then the write), so "remember to
155
+ wrap it" is a rule that gets forgotten once and then reports the wrong thing. One handler
156
+ means a store outage can only ever be a 503, whichever call raised it.
157
+
158
+ The seam raises this only when the caller passed no `fallback_ws` β€” i.e. exactly on this
159
+ adapter, which has no durable session dict to degrade into. A 200 over a write that
160
+ evaporated is the failure the whole rule exists to prevent.
161
+ """
162
+ return JSONResponse(
163
+ {"error": {"code": "store_unavailable",
164
+ "message": "the tenant store is unavailable β€” no change was saved"}},
165
+ status_code=503)
166
+
167
+
168
+ @app.get("/api/health")
169
+ def health():
170
+ """Unauthenticated LIVENESS only β€” it must answer before anyone can sign in, so it may not
171
+ reveal anything about the deployment beyond "the process is up". No version, no tenant list,
172
+ no config: a health endpoint is the one URL every scanner finds first.
173
+
174
+ β›” THE VERSION DOES NOT GO HERE, and it was asked to (2026-08-04, when LIVE became a pinned
175
+ release and "what is LIVE running" needed an answer). A build identifier tells an unauthenticated
176
+ caller exactly which commit's known issues apply. It rides `GET /api/v1/settings` instead, behind
177
+ a session β€” and the authoritative copy is the `VERSION` file in the Space repo, which
178
+ `deploy_web.space_version()` reads without needing the app to be up at all."""
179
+ return {"ok": True}
180
+
181
+
182
+ app.include_router(routes_auth.router)
183
+ app.include_router(routes_nav.router)
184
+ app.include_router(routes_customers.router)
185
+ app.include_router(routes_products.router)
186
+ app.include_router(routes_assets.router)
187
+ app.include_router(routes_tables.router)
188
+ app.include_router(routes_grid.router)
189
+ app.include_router(routes_records.router)
190
+ # EXIT wave 2: the Y1 page-data envelope (one route for every ported dashboard) and Y4's user
191
+ # administration. `routes_pages` imports `pages`, which lazily imports each `pages_*` builder β€” so
192
+ # a new page is a builder module plus one registry line, and nothing here changes.
193
+ app.include_router(routes_pages.router)
194
+ app.include_router(routes_admin.router)
195
+ app.include_router(routes_automation.router)
196
+ app.include_router(routes_keychain.router)
197
+ app.include_router(routes_statements.router)
198
+ # Wave 19 (owner item 13, R3): the LOOPABLE admin plane β€” the platform's own cross-tenant view.
199
+ # Its own prefix (`/api/v1/platform-admin`), never nested under `/admin`, so there is no path
200
+ # ambiguity with `routes_admin`'s `{username}` params and no chance of a tenant-admin route and a
201
+ # platform-operator route ever shadowing each other. Every path it declares is gated by
202
+ # `core.platform_admin.is_platform_admin`, and `verify_api` enumerates this router to prove it.
203
+ app.include_router(routes_platform_admin.router)
204
+ # Wave 20 (owner items 25 + 18/23/26): the Alerts inbox and the manage-access surface. Both are
205
+ # session-gated rather than admin-gated β€” an alert is a person's own subscription, and sharing is
206
+ # something every user does with their own views/folders/databases.
207
+ app.include_router(routes_alerts.router)
208
+ app.include_router(routes_shares.router)
209
+ app.include_router(routes_uploads.router)
210
+ # ⭐ WAVE 23 β€” THE THREE NEW ROUTERS. Mounted here, above the static catch-all at the bottom of this
211
+ # file, because `app.mount("/", _AppStatic(...), html=True)` swallows everything it is reached by:
212
+ # a router included AFTER it answers 404 forever while importing fine, type-checking fine and
213
+ # passing its own gate. That is the wave-20 declared-but-unmounted shape with a different cause.
214
+ #
215
+ # β›” ALL THREE EXISTED, COMPLETE AND GATED, WITH NO MOUNT until the close-out audit β€” three finished
216
+ # features that would have shipped dead. The workers each posted a mount ask and said they would
217
+ # signal "ready" first; C waited for a signal that never came while the files landed anyway. **The
218
+ # lesson is not "read the mailbox harder": `verify_api`'s enumeration is what caught it, so the
219
+ # control is that the enumeration must NAME every router in this file.**
220
+ app.include_router(routes_templates.router) # item 7 / C12 β€” template registry, session-gated
221
+ app.include_router(routes_connectors.router) # item 10 / C11 β€” the connectors directory
222
+ # ⚠ routes_forms is the FIRST NEW PUBLIC DOOR since the `_DEV_FIXTURES` scar (see :257 below). Its
223
+ # two paths are DELIBERATELY unauthenticated β€” a form is filled in by someone with no account β€” so
224
+ # it joins `/api/health`, the automation hook and the tick on the exempt list. It resolves a token
225
+ # by scanning tenants with a constant-time compare and answers a uniform 403, so a bad token cannot
226
+ # distinguish "no such form" from "not yours", and it never echoes a tenant, table or slug.
227
+ app.include_router(routes_forms.router) # item 8 / C9 β€” the PUBLIC form door
228
+ # WAVE 27 item 17 β€” E's Odoo relational doors. Mounted in the SAME change that E's module landed,
229
+ # because the wave-23 scar is exactly this: three finished routers shipped with no include_router
230
+ # line β€” complete, gated, type-clean and 404 for every caller. `verify_api.section_mounts` walks
231
+ # `main.app.routes` and pins these two paths by NAME, so an unmounted router now goes RED.
232
+ app.include_router(routes_odoo_tables.router)
233
+ # ⭐⭐ WAVE 29, item 20 / R11 / contract C6 β€” F's CHANGE TOKEN. `GET /api/v1/changes?scope=<scope>`
234
+ # answers "did this bucket change" for ~zero cost (an in-memory counter; ZERO `store.get()` deep
235
+ # copies), which is what lets a filtered view pick up a row created in another tab, by an automation
236
+ # or by a connector sync without re-downloading the world.
237
+ # β›” THIS LINE IS THE ARTIFACT THIS PROTOCOL LOSES MOST RELIABLY, AND IT WAS ALREADY LOST ONCE HERE:
238
+ # F's router and the CLIENT half both shipped complete, so the poller was calling `/api/v1/changes`
239
+ # six times a minute and taking a 404 while every one of F's own gates was green. `verify_api`'s D-48
240
+ # leg caught it (`unmatched: [('/api/v1/changes', 'apiBridge.ts')]`) β€” a client fetch path with no
241
+ # mounted route β€” which is precisely the control the wave-23 scar above was written to install.
242
+ # ⚠ Mounted is NOT callable: `section_changes_callable` in `verify_api.py` SIGNS IN and CALLS this
243
+ # route, because a route can be mounted and still raise before its own `try:` (D-107's plain-text 500).
244
+ app.include_router(routes_changes.router) # item 20 / C6 β€” F's router, A's line
245
+
246
+
247
+ # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)
248
+ # They are the v1 handlers with the v1 session requirement β€” NOT the old unauthenticated Basic
249
+ # behavior. An alias that kept the old auth would be a bypass of everything above it.
250
+ _GATE = module_gate(routes_customers.MODULE)
251
+
252
+
253
+ @app.get("/api/customers", deprecated=True)
254
+ def _customers_alias(session: Session = Depends(_GATE)):
255
+ return routes_customers._payload(session)
256
+
257
+
258
+ @app.patch("/api/customers/{pid}", deprecated=True)
259
+ def _patch_alias(pid: int, body: dict = Body(default=None),
260
+ session: Session = Depends(_GATE)):
261
+ return routes_customers.patch_customer(pid, body, session)
262
+
263
+
264
+ def _assert_contract_floor():
265
+ """The canonical FIELDS must be exactly what `aios_grid` starts an empty workspace from.
266
+
267
+ This is what stops `FIELDS` becoming a constant that exists only to satisfy a gate. If the
268
+ canonical JSON and `aios_grid.fields_from_workspace({})` ever disagree, the standalone API and
269
+ the embedded host are serving two different schemas and the grid's own contract has forked β€”
270
+ the exact drift `verify_fields_contract.py` was written to catch, now also caught at startup
271
+ on whatever machine is actually running.
272
+ """
273
+ import aios_grid
274
+ base = [f for f in aios_grid.fields_from_workspace({}) if not f.get("custom")]
275
+ if [f["key"] for f in base] != [f["key"] for f in FIELDS]:
276
+ raise RuntimeError(
277
+ "AIOS web API: the canonical field contract and aios_grid.fields_from_workspace({}) "
278
+ "disagree on the base field set β€” embed and standalone would serve different schemas. "
279
+ "Run aios-web/verify_fields_contract.py.")
280
+
281
+
282
+ def _startup_notes():
283
+ """Say the two things an operator must know, once, at import β€” never in a response body."""
284
+ if aios_session.EPHEMERAL_SECRET:
285
+ print("[aios-api] AIOS_SESSION_SECRET is not set β€” signing with a random per-process "
286
+ "key. Sessions will not survive a restart and will not work across workers. "
287
+ "Set it in production.")
288
+ if os.environ.get("AIOS_INSECURE_SSL") == "1":
289
+ print("[aios-api] AIOS_INSECURE_SSL=1 β€” TLS verification is DISABLED for outbound "
290
+ "requests. Local development only; never in a deployed environment.")
291
+
292
+
293
+ _assert_contract_floor()
294
+ _startup_notes()
295
+
296
+
297
+ # β›” THE STATIC MOUNT IS NOW UNAUTHENTICATED, and that is a change this wave made on purpose.
298
+ # Before EXIT-3a, `BasicAuth` middleware gated the WHOLE app including this mount. A branded login
299
+ # page cannot live behind a password prompt, so the shell's own assets must be public β€” which they
300
+ # are: `index.html`, the JS/CSS bundle and the favicon reveal nothing.
301
+ #
302
+ # ⚠ WHAT THAT SILENTLY DE-GATED, caught in review rather than in production. `web/dist/` also
303
+ # carries `sample_customers.json`, a DEV FIXTURE copied from `web/public/`. Its 8 customers are
304
+ # synthetic, but the `agent` column holds REAL EMPLOYEE NAMES, and it went from Basic-gated to
305
+ # publicly fetchable in this commit. Nothing needs it: both the API bridge and `useCustomerData`
306
+ # deleted their sample fallback on purpose ("NOTHING HERE FALLS BACK TO sample_customers.json"),
307
+ # and it survives only because it sits in `web/public/`. So it is refused here β€” 404, the same
308
+ # answer as any other path that is not part of the app.
309
+ #
310
+ # The right long-term fix is deleting it from `web/public/` (S2's lane β€” flagged in the mailbox);
311
+ # this guard is what makes the API safe regardless of what the bundle happens to contain.
312
+ _DEV_FIXTURES = {"sample_customers.json"}
313
+
314
+
315
+ class _AppStatic(StaticFiles):
316
+ async def get_response(self, path, scope):
317
+ if Path(path).name in _DEV_FIXTURES:
318
+ raise StarletteHTTPException(status_code=404, detail="Not Found")
319
+ resp = await super().get_response(path, scope)
320
+ # Vite content-hashes everything under assets/ (a change is a NEW url), so those are
321
+ # immutable β€” a repeat visit re-downloads zero bytes instead of the whole 750 KB bundle.
322
+ # index.html must stay revalidated or a deploy would strand returning browsers on the old
323
+ # bundle; ETag/304 makes that revalidation a header exchange, not a transfer.
324
+ # ⚠ Normalised first: on a Windows host StaticFiles hands this path with backslashes,
325
+ # and `startswith("assets/")` silently skipped every asset (measured on the local probe).
326
+ if path.replace("\\", "/").lstrip("/").startswith("assets/"):
327
+ resp.headers["Cache-Control"] = "public, max-age=31536000, immutable"
328
+ else:
329
+ resp.headers["Cache-Control"] = "no-cache"
330
+ return resp
331
+
332
+
333
+ # static bundle LAST so /api/* wins; html=True serves index.html at / plus the built assets
334
+ if _WEB_DIST.is_dir():
335
+ app.mount("/", _AppStatic(directory=str(_WEB_DIST), html=True), name="web")
336
+
337
+
338
+ # --- boot prewarm (AIOS_PREWARM=1 β€” set by the Dockerfile, never by tests) -----------------------
339
+ # Without this, the first visitor after every deploy/restart pays the full Odoo pool build in
340
+ # their request. The thread warms the CONSOLIDATED scope (None, None) + every registered page's
341
+ # default envelope; scoped users still pay their own scope's first build, once.
342
+ # Env-gated rather than a startup event so importing `api.main` in a gate (verify_api and friends
343
+ # run against fakes) can never fire a live Odoo pull.
344
+ def _seed_and_sync_store():
345
+ """Bring the analytical store (harness.datastore) LIVE for this container β€” the app.py
346
+ bootstrap, mirrored (2026-07-31, owner item 1).
347
+
348
+ `harness.datastore` powers every measure column/condition, and ONLY app.py used to call
349
+ `ensure_seed()` β€” so on a fresh Space disk this container resolved measures against a store
350
+ that never existed and every measure cell served blank. Seeding alone was NOT enough either,
351
+ and that was measured live the same day: "datastore seeded in 1.7s" followed by an endless
352
+ `api:measure-column: ModelError the data cache is still warming up` β€” `ready()` demands
353
+ EVERY entity at phase 'live', and a seed that predates a newer entity leaves it un-synced
354
+ forever in a process with no sync loop. The SYNC SPRINT after the seed is what closes the
355
+ write_date gap and backfills anything the seed lacks (app.py:7779's exact pattern, bounded
356
+ passes). Fail-quiet throughout: no seed/token/Odoo β†’ the columns stay blank, the rows still
357
+ serve.
358
+ """
359
+ import time as _t
360
+ t0 = _t.time()
361
+ try:
362
+ from harness import datastore as _ds
363
+ if _ds.ensure_seed():
364
+ print(f"[aios-api] datastore seeded in {_t.time() - t0:.1f}s")
365
+ # DEDICATED Odoo connection for this thread (the W6 postmortem rule): the sync's
366
+ # search_reads must never interleave on the shared client's xmlrpc transport.
367
+ import core.odoo as _odoo
368
+ try:
369
+ _odoo._tlocal.client = _odoo.OdooClient()
370
+ except Exception:
371
+ pass
372
+ res = {}
373
+ for i in range(12):
374
+ res = _ds.sync_all(log=lambda *a, **k: None)
375
+ print(f"[aios-api] datastore sync pass {i + 1}: "
376
+ + ", ".join(f"{k}={v.get('phase')}" for k, v in sorted(res.items())))
377
+ if all(v.get("phase") == "live" for v in res.values()):
378
+ break
379
+ # ⭐ Wave 21 (item 2, "make sure the metrics are correct"): a cursor sync can never see
380
+ # a HARD DELETE, and the downloaded seed carries whatever was deleted since it was cut β€”
381
+ # one reconcile pass at boot removes both classes of phantom row before the first
382
+ # measure is served. MEASURED 2026-08-05: five deleted sale_order_line rows = $284.25 of
383
+ # phantom YTD revenue, stable across re-syncs, zero the moment reconcile ran.
384
+ try:
385
+ _ds.reconcile_deletes(log=lambda *a, **k: None)
386
+ except Exception:
387
+ pass
388
+ print(f"[aios-api] datastore sync done in {_t.time() - t0:.1f}s "
389
+ f"(ready={_ds.ready()})")
390
+ # ⭐⭐ 2026-08-09 (wave 28, D-107) β€” THE RELATIONAL REBUILD RUNS AT BOOT, HERE.
391
+ #
392
+ # β›” IT DID NOT BEFORE, AND NOTHING SAID SO. The rebuild lived only inside
393
+ # `_store_resync_loop`, whose very first statement is `sleep(1800)` β€” so the earliest a
394
+ # freshly booted container could spawn the four locked databases was T+30 MINUTES. The
395
+ # symptom was read as "the boot path is silent": `/odoo-tables/status` polled every 30 s
396
+ # across a ~20-minute window over two boots returned the pre-wave schema on all 20
397
+ # samples. It was not silent, it had not been asked yet. Both halves of D-107 were like
398
+ # this β€” a thing that never ran, mistaken for a thing that ran and failed.
399
+ #
400
+ # ⚠ WHY HERE AND NOT IN `_prewarm`: the tables are DERIVED FROM THE MIRROR, and this is
401
+ # the exact line where the mirror has finished advancing β€” seed, up to twelve sync passes,
402
+ # then the delete reconcile. Calling it from the other thread would race the seed and hit
403
+ # either `ro_con()`'s "still warming" RuntimeError or, worse, a HALF-SYNCED mirror, which
404
+ # is D-107's own hypothesis 3: a partial population trips `MAX_SHRINK` and the rebuild
405
+ # refuses β€” correctly, but for a reason that reads like a data loss scare.
406
+ # ⚠ Same thread on purpose: it is already a daemon and nothing serves requests behind it.
407
+ _rebuild_odoo_relational("boot")
408
+ except Exception as e: # noqa: BLE001
409
+ print(f"[aios-api] datastore seed/sync skipped: {e}")
410
+
411
+
412
+ def _rebuild_odoo_relational(why):
413
+ """Spawn/refresh the four locked Odoo databases, then compute their cells. `why` is 'boot' or
414
+ 'resync' and rides every log line, because "it failed" and "it failed at boot, before anyone
415
+ could have asked" are different diagnoses.
416
+
417
+ ⭐ THE SUCCESS LINE IS NOT DECORATION β€” it is the control this path lacked. D-107 was chased
418
+ for a day on the strength of *absent* log markers, which cannot distinguish "the rebuild ran
419
+ and was fine" from "the rebuild was never reached". Three failure markers and no success
420
+ marker means silence is ambiguous; now it is not.
421
+
422
+ ⚠ SCOPED TO ROYAL-IMPORTS, deliberately, and it is NOT the D-29 shortcut it resembles. The
423
+ caller has just advanced whichever DuckDB file this process holds open β€” tenant #0's β€” and
424
+ royal is the only tenant with an Odoo mirror to derive from (R1). Iterating tenants here walks
425
+ straight into D-29's documented hazard: `harness/datastore` is a ONE-FILE-AT-A-TIME
426
+ process-global, and rebinding it in a daemon thread under live readers can serve one tenant's
427
+ rows to another with nothing raised. `is_royal` stays the authority on which slugs qualify.
428
+ """
429
+ try:
430
+ import odoo_relational as _rel
431
+ from harness import runtime as _runtime
432
+ if not _rel.is_royal("royal-imports"):
433
+ return
434
+ _rt = _runtime.get_runtime("royal-imports")
435
+ counts = _rel.refresh(_rt, "royal-imports")
436
+ # ⭐⭐ AND THEN COMPUTE THE CELLS, which `refresh` does NOT do.
437
+ #
438
+ # β›” THE FAILURE THIS CLOSES IS THE WORST-LOOKING KIND. `refresh` writes rows and field
439
+ # DEFINITIONS; every Link and Rollup cell comes from a separate pass. Those passes used to
440
+ # live only on the automation `tick`, which fires from an EXTERNAL EventBridge cron β€” so a
441
+ # fresh boot landed 71,954 rows with eleven fully-configured relational columns and every
442
+ # one of them BLANK until an unrelated scheduler happened to run. Nothing errors; the
443
+ # tables simply look finished and answer nothing.
444
+ #
445
+ # ⚠ `refresh_relations`, NOT `compute_relation_cells`. The latter computes a change count
446
+ # over a blob it was handed and PERSISTS NOTHING; the former walks the tenant and writes.
447
+ # Calling the inner one here would return a plausible number and change no cell.
448
+ #
449
+ # ⚠ ONE try/except PER PASS, for the reason `tick` states at its own copies: a source
450
+ # rollup REFUSES loudly on a truncated group set, and a shared block would let that honest
451
+ # refusal silently cancel a relational pass that had already succeeded.
452
+ try:
453
+ import automation_engine as _engine
454
+ _engine.refresh_relations(_rt, log=lambda *_a: None)
455
+ except Exception as e: # noqa: BLE001
456
+ print(f"[aios-api] odoo relation cells failed ({why}): {type(e).__name__}: {e}")
457
+ try:
458
+ import rollup_sql as _rollup
459
+ for _b, _key, _l, _f in _rel.TABLES:
460
+ _rollup.compute(_rt, _key)
461
+ except Exception as e: # noqa: BLE001
462
+ print(f"[aios-api] odoo source rollups failed ({why}): {type(e).__name__}: {e}")
463
+ print(f"[aios-api] odoo relational rebuild done ({why}): "
464
+ + ", ".join(f"{k}={v}" for k, v in sorted((counts or {}).items())))
465
+ except Exception as e: # noqa: BLE001
466
+ # ⚠ The TYPE is named here as it is in the two inner handlers. The original printed only
467
+ # `{e}`, and a bare message is exactly what made D-107 unreadable from the outside: a
468
+ # `BinderException` about a missing column is a different action from a timeout or an auth
469
+ # failure, and the text alone often does not say which it was.
470
+ print(f"[aios-api] odoo relational rebuild failed ({why}): {type(e).__name__}: {e}")
471
+
472
+
473
+ def _store_resync_loop():
474
+ """Keep the analytical mirror current β€” the API-process stand-in for the re-sync the
475
+ Streamlit app piggybacks on page renders. Measure memos key on the pool stamp, so a
476
+ refreshed pool re-reads the freshly synced store."""
477
+ import time as _t
478
+ passes = 0
479
+ while True:
480
+ _t.sleep(1800)
481
+ passes += 1
482
+ try:
483
+ from harness import datastore as _ds
484
+ import core.odoo as _odoo
485
+ try:
486
+ _odoo._tlocal.client = _odoo.OdooClient()
487
+ except Exception:
488
+ pass
489
+ _ds.sync_all(log=lambda *a, **k: None)
490
+ # Wave 21 β€” every 4th pass (~2h): purge hard-deleted rows the cursor sync cannot
491
+ # see (the boot pass's comment has the measured case). Cheap id-sweep per entity;
492
+ # without it deleted Odoo lines inflate every sum on the mirror FOREVER.
493
+ if passes % 4 == 0:
494
+ _ds.reconcile_deletes(log=lambda *a, **k: None)
495
+ except Exception as e: # noqa: BLE001
496
+ print(f"[aios-api] store resync failed: {e}")
497
+ # ⭐ WAVE 27 item 17 (E's ASK ->A, resolved): the Odoo RELATIONAL tables are rebuilt
498
+ # AFTER the mirror they are derived from, in the same pass and in that order β€” deriving
499
+ # from a mirror this loop is about to advance would publish a worklist one cycle stale
500
+ # every single time.
501
+ #
502
+ # β›” OUTSIDE the try/except above, NOT folded into it. A failing relational rebuild must
503
+ # not swallow the sync's error message, and β€” worse the other way β€” a sync failure must
504
+ # not skip a rebuild that had nothing wrong with it. Two independent failures, two
505
+ # independent logs. (`_rebuild_odoo_relational` carries its own handlers.)
506
+ #
507
+ # ⚠ THE REBUILD IS NOT THE FRESHNESS GUARANTEE β€” the rows carry a visible `_refreshed`
508
+ # stamp for that. This loop is a daemon thread whose failure path is a `print` (D-29), so
509
+ # "the wiring exists" and "the data is current" are different claims and only the stamp
510
+ # can tell a user which one they are looking at.
511
+ #
512
+ # ⭐ ONE IMPLEMENTATION, TWO CALLERS (wave 28). This block used to be the only copy, which
513
+ # is what made the boot path silent for 30 minutes after every restart; it is now the
514
+ # SECOND caller of the same function `_seed_and_sync_store` calls at boot. A copy here
515
+ # would be a second thing to keep in step, and the two would answer differently on the
516
+ # next ruling β€” the exact shape the Views top-up was just fixed for on the other side of
517
+ # this wave.
518
+ _rebuild_odoo_relational("resync")
519
+
520
+
521
+ def _prewarm():
522
+ import time as _t
523
+ t0 = _t.time()
524
+ # ⚠ The store sync runs in its OWN thread, never ahead of the pool warm: a stale seed can
525
+ # take many minutes of XML-RPC to close, and the first live probe of this arrangement
526
+ # showed the pool warm (42s) silently queued behind it β€” the whole app cold for every
527
+ # visitor while a background column channel caught up. Measure cells retry via the
528
+ # transient rule until the sync lands; nothing else waits on it.
529
+ import threading as _th
530
+ _th.Thread(target=_seed_and_sync_store, daemon=True, name="store-seed-sync").start()
531
+ try:
532
+ from harness import runtime as _runtime
533
+ rt = _runtime.get_runtime("royal-imports")
534
+ routes_customers.warm_default(rt)
535
+ import pages as _pages
536
+ _pages.warm_default(rt)
537
+ print(f"[aios-api] prewarm done in {_t.time() - t0:.1f}s")
538
+ except Exception as e: # noqa: BLE001 β€” boot must not die on a warm-up
539
+ print(f"[aios-api] prewarm skipped: {e}")
540
+
541
+
542
+ if os.environ.get("AIOS_PREWARM") == "1":
543
+ import threading as _threading
544
+ _threading.Thread(target=_prewarm, daemon=True, name="prewarm").start()
545
+ _threading.Thread(target=_store_resync_loop, daemon=True, name="store-resync").start()
api/odoo_relational.py CHANGED
@@ -713,13 +713,40 @@ def read_products(cur):
713
 
714
 
715
  def read_customers(cur, excluded=None):
716
- """[(row dict)] β€” every partner Odoo has TRANSACTED with, keyed on the `res.partner` id.
717
-
718
- ⭐ THE POPULATION IS THE UNION OF THE TWO DOCUMENT UNIVERSES, and both legs are load-bearing:
719
- Amazon books as direct invoices with no sale order (the `odoo-api` gotcha), so a sale-order
720
- leg alone would silently drop a real customer. Partners with no document at all are left out
721
- on purpose β€” a row that can never appear in any topic has nothing to roll up and would render
722
- as an all-blank line.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
723
 
724
  β›” NOT DERIVED FROM THE INVOICE ROWS. `customers_from` did that when the table WAS the open-AR
725
  partners; sourcing a customer registry from its own receivables is what kept most Odoo ids
@@ -732,6 +759,11 @@ def read_customers(cur, excluded=None):
732
  agent = ("ag.name" if "agent_id" in have else "NULL")
733
  agent_id_col = ("p.agent_id" if "agent_id" in have else "NULL")
734
  join = ("LEFT JOIN res_partner ag ON ag.id = p.agent_id " if "agent_id" in have else "")
 
 
 
 
 
735
  sql = (f"SELECT p.id, p.name, {_col(have, 'p.city')}, {_col(have, 'p.state_name')}, "
736
  f" {_col(have, 'p.country_name')}, {agent}, {agent_id_col} "
737
  "FROM res_partner p "
@@ -740,7 +772,8 @@ def read_customers(cur, excluded=None):
740
  f" SELECT partner_id FROM sale_order WHERE {_CONFIRMED} AND partner_id IS NOT NULL "
741
  " UNION "
742
  " SELECT partner_id FROM account_move "
743
- f" WHERE {_POSTED_DOCS} AND partner_id IS NOT NULL)")
 
744
  out = []
745
  for r in cur.execute(sql).fetchall():
746
  (pid, name, city, state, country, agent, agent_id) = r
 
713
 
714
 
715
  def read_customers(cur, excluded=None):
716
+ """[(row dict)] β€” every CUSTOMER partner, keyed on the `res.partner` id.
717
+
718
+ ⭐ THE POPULATION IS A UNION OF THREE LEGS, and every one of them is load-bearing.
719
+
720
+ The two DOCUMENT legs are the original pair: Amazon books as direct invoices with no sale
721
+ order (the `odoo-api` gotcha), so a sale-order leg alone would silently drop a real customer.
722
+
723
+ ⭐⭐ THE THIRD IS `customer_rank > 0 AND active` (wave 29, item 22 / R12 via finding F2 β€”
724
+ the owner's *"never an arbitrary limit… applies to ALL connected database"*). The old
725
+ docstring said partners with no document are *"left out on purpose β€” a row that can never
726
+ appear in any topic has nothing to roll up"*; that reasoning is RETIRED. It is the same
727
+ join-drop class as the Product grid's 2,717, and it dropped **~1,149 real customer records**
728
+ (MEASURED 2026-08-11: `rank>0 active` = 3,617 against a document union of ~2,000). A customer
729
+ a salesperson has not sold to yet is exactly the row a prospecting view needs.
730
+
731
+ β›” IT IS A UNION AND NOT A REPLACEMENT, AND THAT IS MEASURED, NOT TIDINESS. Swapping the
732
+ document legs for the rank leg would drop **16 partners that hold posted documents** (7
733
+ archived, 9 active with rank <= 0), and `ut_odoo_invoices` / `ut_odoo_orders` rows carry
734
+ `partner_id` LINKS straight back here β€” so those links would dangle with nothing reporting
735
+ it. When other tables point AT a population, a widening must be a SUPERSET.
736
+
737
+ ⚠ THE RANK LEG IS SKIPPED WHEN THE MIRROR HAS NO `customer_rank` COLUMN, which is the same
738
+ `columns()`/`_col` discipline every other optional column here uses β€” but note the difference
739
+ honestly: an absent `agent_id` blanks a CELL, while an absent `customer_rank` narrows the
740
+ POPULATION back to the document union. It degrades to today's behaviour rather than to an
741
+ empty or a wrong table, and `verify_odoo_relational` carries a check that goes RED while the
742
+ column is missing so the narrowing can never pass for done.
743
+
744
+ β›” NOT FROM LIVE ODOO, THOUGH `customer_rank` IS TRIVIAL TO ASK IT. `excluded_ids` above
745
+ states the rule for this module and it applies with more force to a POPULATION than to a name
746
+ list: a live call makes the spawn fail whenever Odoo is unreachable, and a Space hydrates its
747
+ mirror from a SNAPSHOT at boot. The population would then be "whichever source answered this
748
+ time" β€” swinging ~45% against `MAX_SHRINK`'s 50% refusal, deleting and re-adding rows on the
749
+ weather. One source, always present at spawn time: the mirror.
750
 
751
  β›” NOT DERIVED FROM THE INVOICE ROWS. `customers_from` did that when the table WAS the open-AR
752
  partners; sourcing a customer registry from its own receivables is what kept most Odoo ids
 
759
  agent = ("ag.name" if "agent_id" in have else "NULL")
760
  agent_id_col = ("p.agent_id" if "agent_id" in have else "NULL")
761
  join = ("LEFT JOIN res_partner ag ON ag.id = p.agent_id " if "agent_id" in have else "")
762
+ # ⚠ BOTH columns must be present, not just `customer_rank`: `active` is what keeps an
763
+ # archived prospect out, and a rank test without it would re-admit the 47 archived partners
764
+ # the mirror carries. Absent β‡’ the leg is dropped WHOLE, exactly like the agent join above.
765
+ rank_leg = (" OR (p.customer_rank > 0 AND p.active) "
766
+ if {"customer_rank", "active"} <= have else "")
767
  sql = (f"SELECT p.id, p.name, {_col(have, 'p.city')}, {_col(have, 'p.state_name')}, "
768
  f" {_col(have, 'p.country_name')}, {agent}, {agent_id_col} "
769
  "FROM res_partner p "
 
772
  f" SELECT partner_id FROM sale_order WHERE {_CONFIRMED} AND partner_id IS NOT NULL "
773
  " UNION "
774
  " SELECT partner_id FROM account_move "
775
+ f" WHERE {_POSTED_DOCS} AND partner_id IS NOT NULL)"
776
+ f"{rank_leg}")
777
  out = []
778
  for r in cur.execute(sql).fetchall():
779
  (pid, name, city, state, country, agent, agent_id) = r
api/providers.py CHANGED
@@ -100,6 +100,26 @@ PROVIDERS: dict[str, Provider] = {
100
  "creator (identical for two shortcodes in one call, ticking upward between "
101
  "calls) and never populates video_play_count. Their own documented example "
102
  "account no longer reproduces it."),
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
103
  }),
104
  "apify": Provider(
105
  key="apify", label="Apify", key_env="AIOS_APIFY_KEY",
@@ -121,6 +141,17 @@ DEFAULT_CHAINS: dict[str, tuple] = {
121
  # would be a lie that costs a wasted call on every single post.
122
  "ig_post_views": ("apify",),
123
  "ig_comments": ("brightdata",),
 
 
 
 
 
 
 
 
 
 
 
124
  }
125
 
126
 
 
100
  "creator (identical for two shortcodes in one call, ticking upward between "
101
  "calls) and never populates video_play_count. Their own documented example "
102
  "account no longer reproduces it."),
103
+ # ⭐⭐ WAVE 29 (item 7 / D-9 / R1) β€” TIKTOK. Three datasets, all reachable with our
104
+ # existing key, all schema-probed for $0.00 (40/43/17 fields with the vendor's own
105
+ # types): `gd_l1villgoiiidt09ci` Β· `gd_lu702nij2f790tmv9h` Β· `gd_lkf2st302ap89utw5k`.
106
+ "tt_profile": Capability(True, _COST_BRIGHTDATA,
107
+ "40 fields incl. bio/engagement rates/region"),
108
+ # β›” THERE IS NO `tt_post_views` CAPABILITY, AND ITS ABSENCE IS THE CLAIM.
109
+ # `TikTok - Posts` declares `play_count: number` and the vendor's own sample says
110
+ # "no empty values or zeros" β€” so on TikTok the view count arrives INSIDE the post
111
+ # record and a separate view rung would be a second bill for a number we already have.
112
+ # ⚠ DECLARED, NOT MEASURED, and that distinction is the whole scar tissue of §4e:
113
+ # Bright Data's Instagram Reels also DECLARES `views: number` and delivers an
114
+ # account-grain wrong one. One live pull settles it (W29-T06, spend-gated). If it
115
+ # fails, the honest repair is a `tt_post_views` capability routed elsewhere β€” never a
116
+ # quiet fallback bolted onto this one.
117
+ "tt_post_metrics": Capability(
118
+ True, _COST_BRIGHTDATA,
119
+ "likes + comments + shares + saves, and play_count inline (DECLARED "
120
+ "no-empties-or-zeros, UNPROVEN until one live pull)"),
121
+ "tt_comments": Capability(True, _COST_BRIGHTDATA,
122
+ "separate paid dataset, opt-in β€” 17 fields"),
123
  }),
124
  "apify": Provider(
125
  key="apify", label="Apify", key_env="AIOS_APIFY_KEY",
 
141
  # would be a lie that costs a wasted call on every single post.
142
  "ig_post_views": ("apify",),
143
  "ig_comments": ("brightdata",),
144
+ # ⭐ WAVE 29 β€” TikTok, and every chain is deliberately SINGLE-PROVIDER.
145
+ # β›” A MULTI-PROVIDER CHAIN IS A PROMISE SOMETHING WALKS IT. `ig_post_metrics` has declared a
146
+ # two-provider fallback since wave 28 and NOTHING reaches the second name: if Bright Data
147
+ # answers with the likes blank, Apify is never asked. `verify_automation`'s E2b pins that gap
148
+ # BY NAME so a third unwalked chain turns it red β€” which is exactly what a second name here
149
+ # would be today. Apify does sell TikTok (`clockworks/tiktok-profile-scraper`, $0.003/result,
150
+ # 0.7% 30-day failure rate β€” measured from its own store record), so the fallback is buildable;
151
+ # it is not declared until a runner walks it.
152
+ "tt_profile": ("brightdata",),
153
+ "tt_post_metrics": ("brightdata",),
154
+ "tt_comments": ("brightdata",),
155
  }
156
 
157
 
api/routes_automation.py CHANGED
@@ -127,6 +127,12 @@ def _triggers_vocab(session):
127
  # still ACCEPTS it either way β€” readiness is a deployment fact, not a validity one, which
128
  # is the same split `email` already makes.
129
  "ig_profile_match": (engine.bd_ready(), "" if engine.bd_ready() else "configure_brightdata"),
 
 
 
 
 
 
130
  }
131
  #: ⭐ WAVE 24 β€” the server's own one-line description per trigger. C-TYPES: the picker renders
132
  #: THIS under the option, because a CLIENT paraphrase of a server vocabulary is a second copy
@@ -212,6 +218,14 @@ def _tick_state():
212
  "source": "in-process" if inproc else ("external" if ext else "")}
213
 
214
 
 
 
 
 
 
 
 
 
215
  @router.get("/automations")
216
  def list_automations(session: Session = Depends(_GATE)):
217
  """`{automations: [...], kinds: [...], cronPresets: [...]}` β€” the rail's whole payload.
@@ -219,10 +233,29 @@ def list_automations(session: Session = Depends(_GATE)):
219
  The vocabularies ride WITH the list rather than sitting in a client constant: the cron
220
  presets and the kind list are the server's, and a client copy of either is a thing that goes
221
  stale silently (the editor would offer a preset the parser rejects)."""
222
- # Idempotent Board retirement removes only engine-marked stage fields and legacy Board state.
223
- # User-created Status/Stage columns remain intact.
224
- if session.runtime.available():
225
- engine.retire_automation_board_state(session.runtime)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
226
  defs = engine.all_definitions(session.runtime)
227
  items = [_wire(d, session.tenant) for _, d in
228
  sorted(defs.items(), key=lambda kv: (kv[1].get("name") or "").lower())]
@@ -272,6 +305,13 @@ def list_automations(session: Session = Depends(_GATE)):
272
  # validator refuses.
273
  "seedSources": list(engine.SEED_SOURCES),
274
  "seedMaxRows": engine.SEED_MAX_ROWS,
 
 
 
 
 
 
 
275
  # 2026-08-10 β€” the OFFER must name the table the SAVE will actually use.
276
  # This was the bare `DISCOVER_TABLE` constant while `create`/`patch` now
277
  # resolve a targetless discovery flow to the profile database the tenant
@@ -279,7 +319,7 @@ def list_automations(session: Session = Depends(_GATE)):
279
  # save would have written somewhere else β€” a default that disagrees with
280
  # itself across two panels, which is the shape wave 25's R2 fixed for
281
  # `targetTable` vs the action's `table`.
282
- "table": (engine.discover_default_table(session.runtime)
283
  or engine.DISCOVER_TABLE)},
284
  "storeAvailable": bool(session.runtime.available()),
285
  # Wave 22 C3 β€” the trigger vocabulary, session-scoped because email readiness is a
@@ -299,7 +339,19 @@ def list_automations(session: Session = Depends(_GATE)):
299
  "maxCondDepth": engine.MAX_COND_DEPTH,
300
  "maxCondChildren": engine.MAX_COND_CHILDREN,
301
  "maxGroupDepth": engine.MAX_GROUP_DEPTH,
302
- "maxActions": engine.MAX_ACTIONS},
 
 
 
 
 
 
 
 
 
 
 
 
303
  # Wave 21 C6-A1: {"enabled": bool, "source": "in-process"|"external"|""} β€” see
304
  # `_tick_state` for why one boolean off AIOS_AUTOMATIONS alone would lie.
305
  "tick": _tick_state()}
 
127
  # still ACCEPTS it either way β€” readiness is a deployment fact, not a validity one, which
128
  # is the same split `email` already makes.
129
  "ig_profile_match": (engine.bd_ready(), "" if engine.bd_ready() else "configure_brightdata"),
130
+ # ⭐ WAVE 29 (D-9 / R1) β€” TikTok, live. β›” IT NEEDS ITS OWN ROW EVEN THOUGH THE ANSWER IS
131
+ # IDENTICAL, and the reason is the `.get(k, (True, ""))` default below: a trigger this dict
132
+ # forgets is reported READY, so a deployment with no vendor key would offer TikTok search
133
+ # as configured and the search would find nothing. Same key, same readiness bit, stated.
134
+ "tiktok_profile_match": (engine.bd_ready(),
135
+ "" if engine.bd_ready() else "configure_brightdata"),
136
  }
137
  #: ⭐ WAVE 24 β€” the server's own one-line description per trigger. C-TYPES: the picker renders
138
  #: THIS under the option, because a CLIENT paraphrase of a server vocabulary is a second copy
 
218
  "source": "in-process" if inproc else ("external" if ext else "")}
219
 
220
 
221
+ #: W29-T01 β€” the Board retirement ran, per tenant, this process. Same shape and same reasoning as
222
+ #: `_C8_MIGRATED` below: a one-way cleanup of data no living code path creates any more, whose
223
+ #: cost is a full walk of every row-cell in the tenant and whose result on pass 2..N is always
224
+ #: "nothing to do". ⚠ A module-global keyed by tenant is deliberately NOT reset by a table create
225
+ #: or delete β€” a new database cannot contain the legacy stage cells this retires.
226
+ _BOARD_RETIRED = set()
227
+
228
+
229
  @router.get("/automations")
230
  def list_automations(session: Session = Depends(_GATE)):
231
  """`{automations: [...], kinds: [...], cronPresets: [...]}` β€” the rail's whole payload.
 
233
  The vocabularies ride WITH the list rather than sitting in a client constant: the cron
234
  presets and the kind list are the server's, and a client copy of either is a thing that goes
235
  stale silently (the editor would offer a preset the parser rejects)."""
236
+ # ⭐⭐ WAVE 29 (W29-T01, owner item 5: "Automation takes a while to appear"). THE COMPLAINT WAS
237
+ # THIS ROUTE, and the cost was never the automations: it read the whole `user_tables` bucket
238
+ # THREE TIMES per call β€” once for the stage-field retirement scan, twice more inside
239
+ # `discover_default_table`. That bucket's documented ceiling is 35.8 MB / ~1.4 s to serialize
240
+ # (`automation_engine.py` header) and `core/store.py` re-serializes on EVERY `.get()`, hit or
241
+ # miss, UNDER THE STORE LOCK β€” so the reads also serialize behind each other. ~4 s of deep
242
+ # copying to render a rail that shows a name and a toggle.
243
+ #
244
+ # Now: ONE read, lent to both callers. And the retirement SCAN β€” O(all row-cells in the
245
+ # tenant), which hits its own `if not stage_keys: return` only AFTER walking every row of
246
+ # every table β€” runs once per tenant per process, mirroring the `_C8_MIGRATED` guard below.
247
+ #
248
+ # β›” WHY SKIPPING THE SCAN ON CALLS 2..N IS SAFE, and it is not "because it is idempotent":
249
+ # `all_definitions` STRIPS retired board state on every read (`automation_engine.py`'s
250
+ # `_without_retired_board`), so the persist step is hygiene, not correctness. No client can
251
+ # ever be shown state this skip left behind. Nothing writes new `stage_auto_` cells either β€”
252
+ # wave 26's R6 deleted the board that made them.
253
+ tables = engine.ut_all(session.runtime) if session.runtime.available() else None
254
+ if tables is not None and session.tenant not in _BOARD_RETIRED:
255
+ _BOARD_RETIRED.add(session.tenant)
256
+ # Idempotent Board retirement removes only engine-marked stage fields and legacy Board
257
+ # state. User-created Status/Stage columns remain intact.
258
+ engine.retire_automation_board_state(session.runtime, tables=tables)
259
  defs = engine.all_definitions(session.runtime)
260
  items = [_wire(d, session.tenant) for _, d in
261
  sorted(defs.items(), key=lambda kv: (kv[1].get("name") or "").lower())]
 
305
  # validator refuses.
306
  "seedSources": list(engine.SEED_SOURCES),
307
  "seedMaxRows": engine.SEED_MAX_ROWS,
308
+ # W29-T01: `tables` is the snapshot read once at the top of this handler.
309
+ # ⚠ IT WAS TAKEN BEFORE THE RETIREMENT WROTE, and that is deliberate and
310
+ # harmless: retirement only removes `stage_auto_*` FIELDS and pops those
311
+ # same keys off rows, and the election reads the preset-profile vocabulary
312
+ # (`handle` + N preset keys) and whether a table has ANY rows. A stage key
313
+ # is in neither set, and no row is ever deleted β€” so the pre-write
314
+ # snapshot and the post-write bucket cannot elect different tables.
315
  # 2026-08-10 β€” the OFFER must name the table the SAVE will actually use.
316
  # This was the bare `DISCOVER_TABLE` constant while `create`/`patch` now
317
  # resolve a targetless discovery flow to the profile database the tenant
 
319
  # save would have written somewhere else β€” a default that disagrees with
320
  # itself across two panels, which is the shape wave 25's R2 fixed for
321
  # `targetTable` vs the action's `table`.
322
+ "table": (engine.discover_default_table(session.runtime, tables=tables)
323
  or engine.DISCOVER_TABLE)},
324
  "storeAvailable": bool(session.runtime.available()),
325
  # Wave 22 C3 β€” the trigger vocabulary, session-scoped because email readiness is a
 
339
  "maxCondDepth": engine.MAX_COND_DEPTH,
340
  "maxCondChildren": engine.MAX_COND_CHILDREN,
341
  "maxGroupDepth": engine.MAX_GROUP_DEPTH,
342
+ "maxActions": engine.MAX_ACTIONS,
343
+ # ⭐ W29-T09 (owner item 11) β€” THE POST-GROUP VOCABULARY, on the wire for the
344
+ # same reason `cronPresets` is: `clean_post_groups` REFUSES a type it does
345
+ # not know, so a client that invented one would build a config the save door
346
+ # rejects with a sentence about a word the person never typed. Both halves
347
+ # ride β€” the stored key and the label a person reads β€” because a client-side
348
+ # translation of `video` into "Reels" is a second copy of this list.
349
+ "postTypes": [{"key": t, "label": engine.POST_TYPE_LABELS.get(t, t)}
350
+ for t in engine.POST_TYPES],
351
+ # The ceiling a group's limit is judged against. `clean_post_groups` bounds a
352
+ # group by the action's OWN `maxPosts`, not by a constant, so the control can
353
+ # only warn honestly if it reads the same number the validator uses.
354
+ "maxPostsPerPull": engine.MAX_POSTS_PER_PULL},
355
  # Wave 21 C6-A1: {"enabled": bool, "source": "in-process"|"external"|""} β€” see
356
  # `_tick_state` for why one boolean off AIOS_AUTOMATIONS alone would lie.
357
  "tick": _tick_state()}
api/routes_changes.py ADDED
@@ -0,0 +1,159 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """routes_changes.py β€” THE CHANGE TOKEN (wave 29, item 20 / ruling R11, contract C6).
2
+
3
+ GET /api/v1/changes?scope=<scope>
4
+ -> {"scope": "ut_leads",
5
+ "tokens": {"rows": "b3f1c9:14", "overlay": "b3f1c9:3"},
6
+ "backend": "hf"}
7
+
8
+ The owner's report: *a record created in another tab, by an automation, or by a connector sync
9
+ does not appear in a filtered view until you reload.* The client had no way to ask whether
10
+ anything had changed except to re-download everything, so it never asked.
11
+
12
+ β›” WHY THIS ROUTE EXISTS INSTEAD OF THE OBVIOUS "JUST POLL THE ROWS ENDPOINT", and the arithmetic
13
+ is the whole argument. `GET /tables/{key}/rows` costs THREE full-tenant deep copies under ONE
14
+ lock, on ONE uvicorn process (the container runs no `--workers`), against a documented ceiling of
15
+ 35.8 MB / ~1.4 s per bucket β‡’ roughly 4.2 s of lock-held CPU per poll, so TWO TABS SATURATE THE
16
+ SERVER and every unrelated write queues behind them. This handler performs ZERO `store.get()`
17
+ calls: `revision_of` below reads an in-memory counter that `Store.put`/`Store.update` bump at the
18
+ moment a write is accepted. `verify_live_workspace.py`'s server half counts
19
+ `get`/`_read_strict`/`_download` on this path and goes RED at one β€” because a token endpoint that
20
+ deep-copies pays the identical 1.4 s and wins nothing.
21
+
22
+ ⭐ IT REACHES ALL THREE WRITERS THE OWNER NAMED, and that is a property of the QUESTION, not of
23
+ the plumbing: it asks *"did this bucket change"*, never *"did somebody emit an event"*. The event
24
+ seam (`user_tables.ROW_HOOKS`) fires only from HUMAN write doors by construction β€” the automation
25
+ engine's own writer deliberately stays silent, and `verify_automation.py` has a negative control
26
+ enforcing that silence. A push channel could therefore only ever carry 1 of the 3 writers. A
27
+ counter on the store sees the automation and the connector sync for free, and the loop-prevention
28
+ law is untouched.
29
+
30
+ WHAT WALLS THIS, and why it is not `may_open`:
31
+
32
+ * The TENANT is the wall, and it is structural. Every bucket name is namespaced through the
33
+ session's OWN runtime (`TenantRuntime.store_key`), so a scope naming another tenant's table
34
+ resolves to a bucket this tenant does not have and reads 0. There is no cross-tenant answer
35
+ to give.
36
+ * A per-table `may_open` check would cost the very deep copy this route exists to avoid β€”
37
+ `user_tables.get()` reads the whole `user_tables` bucket to answer it.
38
+ * ⭐ And it would protect nothing, because `user_tables.STORE_KEY` is ONE bucket holding EVERY
39
+ `ut_*` table in the tenant: the rows token for `ut_a` and `ut_b` is literally the same
40
+ number. There is no per-table fact here to withhold. (Which also means a write to any one of
41
+ them invites every open tab to re-read its own table β€” over-signalling, i.e. the safe
42
+ direction: the cost is one extra fetch, never a missed change.)
43
+
44
+ So: a valid session, a scope sanitised to a bucket-safe shape, and nothing else.
45
+ """
46
+ from fastapi import APIRouter, Depends
47
+
48
+ import core.shared_overlay as shared_overlay
49
+ import core.store as store
50
+ import core.user_tables as user_tables
51
+ import modules.customer_data as customer_data
52
+ import modules.product_data as product_data
53
+
54
+ from deps import Session, err, require_session
55
+
56
+ router = APIRouter(prefix="/api/v1")
57
+
58
+ #: A scope reaches a STORE KEY, so it is sanitised as strictly as one: lowercase, digits and
59
+ #: underscores only. Not paranoia about SQL β€” `Store` addresses files and `PgStore` binds
60
+ #: parameters β€” but a scope is user-supplied text that becomes part of a path in the HF backend,
61
+ #: and "it cannot escape today" is a property of the current backend rather than of this route.
62
+ _SCOPE_MAX = 64
63
+
64
+
65
+ def revision_of(handle, name):
66
+ """`{'rev','updated_at','token'}` for bucket `name` as THIS caller addresses it β€” or None.
67
+
68
+ ⭐ ONE resolver, and the gate calls the HANDLER rather than reproducing this dance, so the
69
+ route and its control cannot disagree about which physical key was read. A control that
70
+ re-derives the address is how a gate ends up certifying a key nobody serves.
71
+
72
+ `handle` is whatever the caller holds β€” a tenant runtime, a `Store`, or `core.store` itself.
73
+ The runtime is recognised DUCK-TYPED (`store_key` + `store_handle`) rather than imported:
74
+ `store_key()` is the ONE place a tenant's namespace prefix is applied, and applying it here a
75
+ second time is how one tenant reads another's counter.
76
+
77
+ β›” None β€” never a fabricated token β€” when the active backend publishes no revision. `PgStore`
78
+ maintains `rev` in `store_kv` and does not yet expose it, so under `STORE_BACKEND=pg` this
79
+ answers None, the client stops polling, and the app behaves exactly as it does today. A token
80
+ frozen at 0 would instead promise liveness the backend is not delivering.
81
+ """
82
+ target, key = handle, str(name)
83
+ namespaced = getattr(handle, "store_key", None)
84
+ if callable(namespaced): # a tenant runtime owns the namespace prefix
85
+ key = namespaced(name)
86
+ bound = getattr(handle, "store_handle", None)
87
+ target = bound if bound is not None else store._d()
88
+ fn = getattr(target, "revision", None)
89
+ if not callable(fn):
90
+ return None
91
+ try:
92
+ return fn(key)
93
+ except Exception:
94
+ # A backend that raises here must not take the poll down with it: the caller degrades to
95
+ # "no token for this bucket", which is the same honest null the pg path returns.
96
+ return None
97
+
98
+
99
+ def _clean_scope(raw):
100
+ s = str(raw or "").strip().lower()
101
+ if not s or len(s) > _SCOPE_MAX or any(c not in "abcdefghijklmnopqrstuvwxyz0123456789_"
102
+ for c in s):
103
+ return ""
104
+ return s
105
+
106
+
107
+ def buckets_for(scope):
108
+ """`{label: store bucket}` for one topic scope β€” the map the CLIENT never gets to write.
109
+
110
+ β›” Every value is imported from the module that WRITES it, never re-spelled here.
111
+ `user_tables.STORE_KEY`, `customer_data.TABLE_KEY` and `product_data.TABLE_KEY` are the
112
+ literal keys those modules read and update, so a rename moves this map with it. A hand-copied
113
+ `'customer_table_workspace'` would keep answering 200 with a token for a bucket nobody writes
114
+ β€” a poll that costs nothing, changes never, and looks exactly like "there were no changes".
115
+
116
+ An absent label means "no store residency": `customer` and `product` rows come from Odoo
117
+ through a 15-minute server cache, which R11 deliberately leaves alone. The client reads a
118
+ missing/null token as "do not poll this", never as "unchanged".
119
+ """
120
+ s = _clean_scope(scope)
121
+ if not s:
122
+ return None
123
+ #: The shared stratum's bucket is asked FOR rather than spelled, so C5's `BUCKET_SUFFIX` has
124
+ #: exactly one definition and a rename cannot leave the poller watching a dead key.
125
+ if s.startswith(user_tables.KEY_PREFIX):
126
+ workspace = f"{s}_table_workspace"
127
+ elif s == "customer":
128
+ workspace = customer_data.TABLE_KEY
129
+ elif s == "product":
130
+ workspace = product_data.TABLE_KEY
131
+ else:
132
+ return {}
133
+ names = {"overlay": workspace, "shared": shared_overlay.bucket(workspace)}
134
+ if s.startswith(user_tables.KEY_PREFIX):
135
+ names["rows"] = user_tables.STORE_KEY
136
+ return names
137
+
138
+
139
+ @router.get("/changes")
140
+ def changes(scope: str = "", session: Session = Depends(require_session)):
141
+ """One tiny read per tab per interval. The response is small, uncacheable and boring."""
142
+ names = buckets_for(scope)
143
+ if names is None:
144
+ raise err(400, "bad_scope", "name the table you are watching, e.g. ?scope=customer")
145
+ if not names:
146
+ # β›” A well-formed scope this map does not know is a 404, NOT an empty `tokens` object.
147
+ # An empty map is indistinguishable from "nothing here ever changes", so a topic added
148
+ # later would poll forever against silence and read as a working live view that never
149
+ # updates. Loud beats plausible.
150
+ raise err(404, "unknown_scope", f"nothing here watches {_clean_scope(scope)!r}")
151
+ tokens = {}
152
+ for label, bucket in names.items():
153
+ rev = revision_of(session.runtime, bucket)
154
+ # β›” A NULL IS AN ANSWER, not an omission. The pg backend maintains `rev` in `store_kv`
155
+ # and does not yet expose it, so after D-4 flips this reads None until `PgStore` grows a
156
+ # `revision()`. Sending null and letting the client stop polling is the honest failure;
157
+ # a token frozen at 0 would promise liveness the backend is not delivering.
158
+ tokens[label] = rev.get("token") if isinstance(rev, dict) else None
159
+ return {"scope": _clean_scope(scope), "tokens": tokens, "backend": store.backend()}
api/routes_forms.py CHANGED
@@ -32,15 +32,32 @@ bypassed. Booked as DEBT rather than described as a guarantee β€” a rate limit t
32
  being one is worse than none.
33
  """
34
  import hmac
 
35
  import secrets
36
  import time
37
 
38
- from fastapi import APIRouter, Request
39
 
40
- from deps import err
41
 
42
  router = APIRouter(prefix="/api/v1")
43
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
44
  #: The mint. 24 bytes url-safe = 32 characters, 192 bits β€” the same shape the automation hook's
45
  #: per-automation token uses, so there is ONE token strength in the product rather than two.
46
  TOKEN_BYTES = 24
@@ -126,35 +143,40 @@ def _same(a: str, b: str) -> bool:
126
  # index becomes worth its risk when either number grows.
127
 
128
 
129
- def _iter_form_views(rt):
130
- """Yield `(table_key, view_id, form_spec)` for every form-enabled view in one tenant.
131
 
132
- A form spec lives at `view.config.display.form` and carries the token β€” see W23-C9. Reads
133
- only; nothing here writes, so a malformed stratum is skipped rather than repaired.
134
  """
135
- import core.user_tables as user_tables
136
-
137
  try:
138
- tables = user_tables.all_tables(st=rt) or {}
139
  except Exception: # noqa: BLE001
140
- return
141
- for key in list(tables):
142
- try:
143
- bucket = rt.get(f"{key}_table_workspace") or {}
144
- except Exception: # noqa: BLE001
145
- continue
146
- if not isinstance(bucket, dict):
147
  continue
148
- for ws in bucket.values():
149
- if not isinstance(ws, dict):
150
- continue
151
- for view_id, view in (ws.get("views") or {}).items():
152
- if not isinstance(view, dict):
153
- continue
154
- display = ((view.get("config") or {}).get("display") or {})
155
- spec = display.get("form")
156
- if isinstance(spec, dict) and spec.get("token"):
157
- yield str(key), str(view_id), spec
 
 
 
 
 
 
 
 
 
158
 
159
 
160
  def _resolve(token: str):
@@ -164,6 +186,12 @@ def _resolve(token: str):
164
  tenant whose store answered would make "the third tenant's form" depend on the first two
165
  being healthy, and a form that stops working because somebody else's store blipped is the
166
  kind of failure nobody can reproduce.
 
 
 
 
 
 
167
  """
168
  from harness import runtime as _rt
169
 
@@ -174,9 +202,17 @@ def _resolve(token: str):
174
  rt = _rt.get_runtime(slug)
175
  except Exception: # noqa: BLE001
176
  continue
177
- for table_key, _view_id, spec in _iter_form_views(rt):
178
- if _same(str(spec.get("token") or ""), token):
179
- return rt, slug, table_key, spec
 
 
 
 
 
 
 
 
180
  return None
181
 
182
 
@@ -192,6 +228,7 @@ def _public_form(rt, table_key: str, spec: dict) -> dict:
192
  somebody arrange these questions, and re-deriving the order from the schema would silently
193
  rearrange a form every time a column was added.
194
  """
 
195
  import core.user_tables as user_tables
196
 
197
  defn = user_tables.get(table_key, st=rt) or {}
@@ -204,6 +241,24 @@ def _public_form(rt, table_key: str, spec: dict) -> dict:
204
  # and never an error: losing one column must not take a live form offline.
205
  if not f or f.get("source") not in (None, "overlay"):
206
  continue
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
207
  row = {"key": str(f.get("key")), "label": str(f.get("label") or f.get("key")),
208
  "type": str(f.get("type") or "text"), "required": str(key) in required}
209
  options = f.get("options")
@@ -218,9 +273,32 @@ def _public_form(rt, table_key: str, spec: dict) -> dict:
218
  "submitLabel": str(spec.get("submitLabel") or "")[:60] or "Submit",
219
  "fields": out,
220
  "honeypot": HONEYPOT_FIELD,
 
 
 
 
 
 
221
  }
222
 
223
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
224
  # --- validation -------------------------------------------------------------------------------
225
 
226
 
@@ -290,6 +368,135 @@ def _clean_values(fields: list, raw: dict):
290
  # --- the routes -------------------------------------------------------------------------------
291
 
292
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
293
  @router.get("/forms/{token}")
294
  def get_form(token: str, request: Request):
295
  """Render-time payload for a public form. Rate-limited like the POST: an unauthenticated GET
@@ -363,6 +570,19 @@ async def submit_form(token: str, request: Request):
363
  form = _public_form(rt, table_key, spec)
364
  if not form["fields"]:
365
  raise _refuse()
 
 
 
 
 
 
 
 
 
 
 
 
 
366
  clean, problem = _clean_values(form["fields"], values)
367
  if problem:
368
  raise err(400, "invalid_submission", problem)
@@ -384,7 +604,10 @@ async def submit_form(token: str, request: Request):
384
  # `record_created` row event, so every trigger and audit downstream sees `form:<prefix>`
385
  # rather than a blank actor. Booked as a dated amendment in the split doc; a persistent
386
  # per-row stamp needs `add_row` to grow one, which is SESSION A's file.
387
- actor = f"form:{token[:8]}"
 
 
 
388
  row_id = user_tables.add_row(table_key, clean, username=actor, st=rt)
389
  if not row_id:
390
  raise err(409, "not_accepted", "that submission could not be saved β€” try again later")
 
32
  being one is worse than none.
33
  """
34
  import hmac
35
+ import os
36
  import secrets
37
  import time
38
 
39
+ from fastapi import APIRouter, Depends, Request
40
 
41
+ from deps import Session, err, require_session
42
 
43
  router = APIRouter(prefix="/api/v1")
44
 
45
+ #: ⭐⭐ WAVE-29 R7 β€” THE TOKEN INDEX, one bucket per tenant: `{token: {table, view}}`.
46
+ #:
47
+ #: β›” WHY THE TOKEN IS NOT IN THE FORM SPEC, which is where wave 23 assumed it would live. The spec
48
+ #: rides `view.config.display.form`, which a BROWSER writes β€” so a token stored beside it is a
49
+ #: token a browser can choose. `_resolve` walks tenants and answers with the FIRST match, so a
50
+ #: tenant that set its token to a value it had seen elsewhere would quietly receive another
51
+ #: tenant's submissions. Nothing about that is exotic: it needs one `PATCH` and a token somebody
52
+ #: pasted into a chat. Minting server-side into a bucket the client cannot write closes it by
53
+ #: construction rather than by validation, and `aios_grid._clean_form` drops a wire `token`.
54
+ #:
55
+ #: ⭐ It is also FASTER than what it replaces. The old resolution walked every table's workspace,
56
+ #: every user's stratum and every view of every tenant looking for a matching token β€” booked in
57
+ #: this file's own header as "a FULL SCAN, deliberately, and its cost is BOOKED". Now it is one
58
+ #: small dict read per tenant, and the view is loaded ONCE, after the token has already matched.
59
+ TOKENS_KEY = "form_tokens"
60
+
61
  #: The mint. 24 bytes url-safe = 32 characters, 192 bits β€” the same shape the automation hook's
62
  #: per-automation token uses, so there is ONE token strength in the product rather than two.
63
  TOKEN_BYTES = 24
 
143
  # index becomes worth its risk when either number grows.
144
 
145
 
146
+ def _find_view(rt, table_key: str, view_id: str):
147
+ """`(view, owner_username)` for one view in one table's workspace, or `(None, None)`.
148
 
149
+ The bucket is `{username: {views: {id: view}}}` β€” one stratum per user plus the shared one β€”
150
+ and a view id is unique across them, so the first match is the view.
151
  """
 
 
152
  try:
153
+ bucket = rt.get(f"{table_key}_table_workspace") or {}
154
  except Exception: # noqa: BLE001
155
+ return None, None
156
+ if not isinstance(bucket, dict):
157
+ return None, None
158
+ for owner, ws in bucket.items():
159
+ if not isinstance(ws, dict):
 
 
160
  continue
161
+ view = (ws.get("views") or {}).get(view_id)
162
+ if isinstance(view, dict):
163
+ return view, str(owner)
164
+ return None, None
165
+
166
+
167
+ def _spec_of(view) -> dict:
168
+ """The form spec on a view, or `{}`. One place knows the key path."""
169
+ spec = (((view or {}).get("config") or {}).get("display") or {}).get("form")
170
+ return spec if isinstance(spec, dict) else {}
171
+
172
+
173
+ def _tokens(rt) -> dict:
174
+ """This tenant's `{token: {table, view}}` index, always a dict."""
175
+ try:
176
+ found = rt.get(TOKENS_KEY) or {}
177
+ except Exception: # noqa: BLE001
178
+ return {}
179
+ return found if isinstance(found, dict) else {}
180
 
181
 
182
  def _resolve(token: str):
 
186
  tenant whose store answered would make "the third tenant's form" depend on the first two
187
  being healthy, and a form that stops working because somebody else's store blipped is the
188
  kind of failure nobody can reproduce.
189
+
190
+ β›” THE INDEX IS A POINTER, NEVER A PERMISSION. A token that resolves to a view which has since
191
+ been DELETED, or whose form spec has been removed, answers the same 403 as a token that never
192
+ existed β€” the index is written by the mint route and nothing deletes the tenant's views on its
193
+ behalf, so "the row is in the index" cannot be allowed to mean "the form is live". A stale
194
+ pointer outliving its view is exactly how a door that was closed stays open.
195
  """
196
  from harness import runtime as _rt
197
 
 
202
  rt = _rt.get_runtime(slug)
203
  except Exception: # noqa: BLE001
204
  continue
205
+ for stored, where in _tokens(rt).items():
206
+ if not _same(str(stored), token) or not isinstance(where, dict):
207
+ continue
208
+ table_key = str(where.get("table") or "")
209
+ view, _owner = _find_view(rt, table_key, str(where.get("view") or ""))
210
+ spec = _spec_of(view)
211
+ # No view, no questions, no form. Checked HERE rather than by the caller so every
212
+ # public route inherits it from one place.
213
+ if not table_key or not spec.get("fields"):
214
+ return None
215
+ return rt, slug, table_key, spec
216
  return None
217
 
218
 
 
228
  somebody arrange these questions, and re-deriving the order from the schema would silently
229
  rearrange a form every time a column was added.
230
  """
231
+ import aios_grid
232
  import core.user_tables as user_tables
233
 
234
  defn = user_tables.get(table_key, st=rt) or {}
 
241
  # and never an error: losing one column must not take a live form offline.
242
  if not f or f.get("source") not in (None, "overlay"):
243
  continue
244
+ # ⭐ WAVE-29 R7 β€” TWO WALLS, AND NEITHER IS REDUNDANT.
245
+ #
246
+ # (1) The TYPE allow-list: a form may only ask questions this door can answer honestly.
247
+ # `_clean_values` below coerces twelve types and passes everything else through as
248
+ # text, so an `image`, a `json` document or a `link` reached through a form would be
249
+ # a string typed into a column that means something else.
250
+ # (2) `is_computed_cell`: the SERVER owns that number. And it catches what the type list
251
+ # structurally cannot β€” a METRIC bag rides an ordinary `int`, so a machine-computed
252
+ # column passes the allow-list by type and must still be refused.
253
+ #
254
+ # ⚠ Enforced HERE rather than only in the builder, because the builder is a courtesy and
255
+ # this is the wall: the spec is a stored bag, and a field can become computed (a formula,
256
+ # a rollup, a metric binding) long after it was added to a live form
257
+ # ([[schema-role-is-not-a-value-wall]]).
258
+ if str(f.get("type") or "text") not in aios_grid.FORM_FIELD_TYPES:
259
+ continue
260
+ if user_tables.is_computed_cell(f):
261
+ continue
262
  row = {"key": str(f.get("key")), "label": str(f.get("label") or f.get("key")),
263
  "type": str(f.get("type") or "text"), "required": str(key) in required}
264
  options = f.get("options")
 
273
  "submitLabel": str(spec.get("submitLabel") or "")[:60] or "Submit",
274
  "fields": out,
275
  "honeypot": HONEYPOT_FIELD,
276
+ # β›” THE FLAG, NEVER THE LIST. `requireEmail` tells the page to ask for an address; the
277
+ # ADDRESSES stay server-side. Returning them would hand an unauthenticated caller the
278
+ # guest list β€” every colleague's work email, to anyone who has the link β€” which is a
279
+ # worse leak than the door this restriction exists to close. It is also the only reason
280
+ # this key can be computed here rather than shipped as `spec['emails']`.
281
+ "requireEmail": spec.get("access") == "emails",
282
  }
283
 
284
 
285
+ def _invited(spec: dict, email: str) -> bool:
286
+ """May this address submit? Case- and space-insensitive against the stored list.
287
+
288
+ ⚠ **IDENTIFICATION, NOT AUTHENTICATION, and the honest boundary is stated rather than
289
+ implied** (this file's header does the same for the token). Nothing here proves the submitter
290
+ owns the address they typed: anyone holding the link who knows an invited address can pass.
291
+ What it buys is real but bounded β€” a link forwarded outside the invited group stops working
292
+ for whoever cannot name a member of it, and every submission carries the address it claimed.
293
+ A per-recipient link, which WOULD prove possession, is booked rather than half-built.
294
+ """
295
+ if spec.get("access") != "emails":
296
+ return True
297
+ wanted = str(email or "").strip().lower()
298
+ return bool(wanted) and wanted in {str(e).strip().lower()
299
+ for e in (spec.get("emails") or [])}
300
+
301
+
302
  # --- validation -------------------------------------------------------------------------------
303
 
304
 
 
368
  # --- the routes -------------------------------------------------------------------------------
369
 
370
 
371
+ # --- the AUTHENTICATED half: minting, reading and revoking a form's share link ----------------
372
+ #
373
+ # ⚠ PATH: `/form-link`, NOT `/forms/link`. The public routes are `/forms/{token}`, and a literal
374
+ # segment beside a path parameter is decided by declaration ORDER β€” a reader (or a later
375
+ # refactor that moves a decorator) would have to know that to know which handler answers. A
376
+ # different noun cannot be shadowed by a token somebody chooses.
377
+
378
+
379
+ def _public_base() -> str:
380
+ """The origin a share link is built on. Empty = the client builds it from its own location.
381
+
382
+ `AIOS_PUBLIC_BASE` is the same variable the OAuth callback resolves against, so a domain move
383
+ takes the form links with it. Absent, we return a PATH rather than guessing a hostname:
384
+ a link with the wrong origin looks right, gets pasted into an email and 404s for the reader.
385
+ """
386
+ return (os.environ.get("AIOS_PUBLIC_BASE") or os.environ.get("APP_BASE_URL") or "").rstrip("/")
387
+
388
+
389
+ def _link_of(token: str) -> str:
390
+ return f"{_public_base()}/#/form/{token}"
391
+
392
+
393
+ def _may_administer_view(session: Session, table_key: str, view_id: str):
394
+ """`(view, spec)` when this caller may publish THIS view, else raises.
395
+
396
+ ⭐ `_may_administer`, deliberately, not `_may_edit`. Minting a public link is a PERMISSIONS
397
+ act β€” it opens a write door onto the tenant's table for anybody holding the URL β€” and
398
+ `table_store` already draws that line for views: a collaborator may edit a shared view, only
399
+ its creator or an admin may change who reaches it. Publishing is the strongest form of that
400
+ question, so it takes the narrower answer.
401
+ ⚠ A view sitting in the caller's OWN stratum is theirs even with no `createdBy` stamp (a
402
+ personal view predating the stamp has none), which `_may_administer` alone would refuse.
403
+ """
404
+ import core.table_store as table_store
405
+
406
+ if not table_key.startswith("ut_"):
407
+ # `add_row` is the only write a form can perform and it is a `ut_*` door; an Odoo-backed
408
+ # grid has no such door, so a link over one could never be anything but a 500 later.
409
+ raise err(400, "not_a_database", "forms collect into your own databases only")
410
+ view, owner = _find_view(session.runtime, table_key, view_id)
411
+ if not isinstance(view, dict):
412
+ raise err(404, "no_such_view", "that view no longer exists")
413
+ # β›” `uname` / `admin`, NOT `username` / `is_admin`. `Session` has no such attributes, and
414
+ # reading one raises OUTSIDE any handler's own try: β€” which is exactly D-107, where four
415
+ # finished Odoo routes were mounted, uncallable, and answered a bare plain-text 500 for a day
416
+ # ([[mounted-is-not-callable]]). Written wrong here first; caught by this file's own gate.
417
+ if not (owner == session.uname
418
+ or table_store._may_administer(view, session.uname, session.admin)):
419
+ raise err(403, "not_yours", "only this view's creator or an admin can publish it")
420
+ return view, _spec_of(view)
421
+
422
+
423
+ @router.get("/form-link")
424
+ def read_form_link(topic: str, view: str, session: Session = Depends(require_session)):
425
+ """This form's current share link, or `{"token": null}` β€” never a mint.
426
+
427
+ β›” A GET MUST NOT MINT. The builder reads this every time the panel opens, and a route that
428
+ created a token on read would publish a form the moment somebody looked at the tab.
429
+ """
430
+ _v, spec = _may_administer_view(session, topic, view)
431
+ token = ""
432
+ for stored, where in _tokens(session.runtime).items():
433
+ if isinstance(where, dict) and where.get("table") == topic and where.get("view") == view:
434
+ token = str(stored)
435
+ break
436
+ return {
437
+ "token": token or None,
438
+ "url": _link_of(token) if token else None,
439
+ # ⭐ THE SERVER'S OWN VIEW OF THE SPEC, and it exists to make ONE failure visible rather
440
+ # than silent: the builder's `spec` prop comes from the client's `cleanDisplay`, so if the
441
+ # client ever stops carrying `display.form`, the panel would render an empty form over a
442
+ # stored one and the next save would erase real questions. Reporting what the SERVER holds
443
+ # lets the panel say so instead ([[read-path-cannot-witness-write-path]]).
444
+ "stored": ({"fields": len(spec.get("fields") or []),
445
+ "access": spec.get("access") or "public",
446
+ "title": str(spec.get("title") or "")[:120]} if spec else None),
447
+ }
448
+
449
+
450
+ @router.post("/form-link")
451
+ def mint_form_link(body: dict, session: Session = Depends(require_session)):
452
+ """Mint (or regenerate) this view's share link. `{topic, view, regenerate?}`.
453
+
454
+ Idempotent without `regenerate`: opening the panel twice must not invalidate the link
455
+ somebody already emailed. With it, the previous token is DROPPED in the same write β€” a
456
+ "regenerate" that leaves the old link alive has revoked nothing.
457
+ """
458
+ topic, view = str((body or {}).get("topic") or ""), str((body or {}).get("view") or "")
459
+ _v, spec = _may_administer_view(session, topic, view)
460
+ if not spec.get("fields"):
461
+ raise err(400, "empty_form", "add at least one question before sharing this form")
462
+ fresh = secrets.token_urlsafe(TOKEN_BYTES)
463
+ keep = not (body or {}).get("regenerate")
464
+
465
+ minted = {"token": fresh}
466
+
467
+ def _set(cur):
468
+ cur = dict(cur or {})
469
+ for stored, where in list(cur.items()):
470
+ if isinstance(where, dict) and where.get("table") == topic and where.get("view") == view:
471
+ if keep:
472
+ minted["token"] = str(stored)
473
+ return cur
474
+ cur.pop(stored, None) # regenerate: the old link dies in this same write
475
+ cur[fresh] = {"table": topic, "view": view}
476
+ return cur
477
+
478
+ # `sync`: a share link the user is about to paste into an email must be durable before the
479
+ # response says it exists. This is not a hot path.
480
+ session.runtime.update(TOKENS_KEY, _set, flush="sync")
481
+ return {"token": minted["token"], "url": _link_of(minted["token"])}
482
+
483
+
484
+ @router.delete("/form-link")
485
+ def revoke_form_link(topic: str, view: str, session: Session = Depends(require_session)):
486
+ """Turn the link off. The form spec stays; only the door closes."""
487
+ _may_administer_view(session, topic, view)
488
+
489
+ def _drop(cur):
490
+ cur = dict(cur or {})
491
+ for stored, where in list(cur.items()):
492
+ if isinstance(where, dict) and where.get("table") == topic and where.get("view") == view:
493
+ cur.pop(stored, None)
494
+ return cur
495
+
496
+ session.runtime.update(TOKENS_KEY, _drop, flush="sync")
497
+ return {"ok": True}
498
+
499
+
500
  @router.get("/forms/{token}")
501
  def get_form(token: str, request: Request):
502
  """Render-time payload for a public form. Rate-limited like the POST: an unauthenticated GET
 
570
  form = _public_form(rt, table_key, spec)
571
  if not form["fields"]:
572
  raise _refuse()
573
+
574
+ # ⭐ WAVE-29 R7 β€” the authorized-by-email door. Checked BEFORE `_clean_values` so an
575
+ # uninvited caller learns nothing about the form's questions from the shape of its refusal,
576
+ # and before the daily cap so strangers cannot spend a live form's allowance.
577
+ # ⚠ NOT `_refuse()`: this one is deliberately a DIFFERENT answer. `_refuse` exists so a wrong
578
+ # token cannot be told apart from a missing form; here the caller already holds a valid link
579
+ # and the only useful thing we can say is "not with that address" β€” telling them nothing
580
+ # would leave a colleague staring at a form that silently does nothing.
581
+ submitter = str((body or {}).get("email") or "").strip().lower()[:254]
582
+ if not _invited(spec, submitter):
583
+ raise err(403, "not_invited",
584
+ "this form only accepts submissions from invited email addresses")
585
+
586
  clean, problem = _clean_values(form["fields"], values)
587
  if problem:
588
  raise err(400, "invalid_submission", problem)
 
604
  # `record_created` row event, so every trigger and audit downstream sees `form:<prefix>`
605
  # rather than a blank actor. Booked as a dated amendment in the split doc; a persistent
606
  # per-row stamp needs `add_row` to grow one, which is SESSION A's file.
607
+ # ⭐ WAVE-29 β€” an invited submitter is stamped BY ADDRESS rather than by token prefix: on an
608
+ # email-restricted form the address is the most identifying thing we honestly have, and it is
609
+ # what makes `record_created` legible in a run log ("form:ana@…" beats "form:Kx2p9Lm4").
610
+ actor = f"form:{submitter or token[:8]}"[:120]
611
  row_id = user_tables.add_row(table_key, clean, username=actor, st=rt)
612
  if not row_id:
613
  raise err(409, "not_accepted", "that submission could not be saved β€” try again later")
api/routes_oauth.py CHANGED
@@ -32,7 +32,18 @@ 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
  base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
37
  if not base:
38
  base = f"{request.url.scheme}://{request.url.netloc}"
 
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}"
api/routes_products.py CHANGED
@@ -63,6 +63,17 @@ def _pool_for(rt, team_id):
63
  # naming the pause when there is none. Minting a product snapshot here would be a new
64
  # persistence format at a wave tail; refusing with a sentence is the answer the user can act
65
  # on, and it is the same 503 the customer path already gives for an unsnapshotted scope.
 
 
 
 
 
 
 
 
 
 
 
66
  import routes_keychain
67
  if routes_keychain.odoo_paused(rt):
68
  hit = rt.pool_cache.get(key)
 
63
  # naming the pause when there is none. Minting a product snapshot here would be a new
64
  # persistence format at a wave tail; refusing with a sentence is the answer the user can act
65
  # on, and it is the same 503 the customer path already gives for an unsnapshotted scope.
66
+ # ⭐ WAVE 29 / R12 β€” THE POOL IS THE CATALOGUE NOW (5,875 active products, not the 2,717 that
67
+ # happened to sell in a revenue window). Two consequences that land HERE rather than in
68
+ # `product_data`:
69
+ # Β· the 503 below now also covers a TRUNCATED catalogue read. `modules.product_data.
70
+ # _catalogue_by_code` RAISES instead of degrading, precisely so a short pull arrives as a
71
+ # refusal a user can act on rather than as a plausible smaller grid nobody questions;
72
+ # `pool_unavailable` names the cause in its message.
73
+ # Β· the first build for a scope got slower (MEASURED 2026-08-11: ~44 s consolidated, of
74
+ # which the catalogue read is ~3 s; a BU-scoped build is ~9 s). Only a scope's FIRST-ever
75
+ # build blocks β€” the stale-while-refresh discipline above is what keeps that off the
76
+ # request path afterwards.
77
  import routes_keychain
78
  if routes_keychain.odoo_paused(rt):
79
  hit = rt.pool_cache.get(key)
api/routes_tables.py CHANGED
@@ -684,6 +684,56 @@ def add_row(table_key: str, body: dict = Body(default=None),
684
  return {"rid": rid, "pid": int(rid)}
685
 
686
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
687
  # ---------------------------------------------------------------------------------------------
688
  # THE SHARED FIELD SCHEMA (contract C-FIELD, owner ruling R2)
689
  # ---------------------------------------------------------------------------------------------
@@ -897,11 +947,18 @@ def patch_row(table_key: str, pid: int, body: dict = Body(default=None),
897
  except grid_events.StoreUnavailable:
898
  raise err(503, "store_unavailable",
899
  "the tenant store is unavailable β€” your change was not saved")
900
- # ⚠ THE READ-BACK SPANS BOTH STRATA, and it has to (wave 25, C3-A1). An ordinary cell lands
901
- # in this user's OVERLAY; a PROFILE cell writes THROUGH to the shared DEFINITION row. Reading
902
- # only the overlay β€” which is what this did β€” reports a perfectly accepted profile write as
903
- # `refused`, because the key is simply not in the bucket it looked in. Same merge order the
904
- # rows envelope uses (`table_rows`): definition under, overlay over.
 
 
 
 
 
 
 
905
  stored = dict(((_ut().get(table_key, st=session.runtime) or {}).get("rows") or {})
906
  .get(str(pid)) or {})
907
  accepted = {k: stored.get(k) for k in updates if k in stored}
 
684
  return {"rid": rid, "pid": int(rid)}
685
 
686
 
687
+ @router.post("/tables/{table_key}/rows/import", status_code=201)
688
+ def import_rows(table_key: str, body: dict = Body(default=None),
689
+ session: Session = Depends(require_session)):
690
+ """⭐⭐ WAVE-29 T25 (owner item 6) β€” the IMPORT door: N mapped rows, ONE store write.
691
+
692
+ Body: `{"rows": [{fieldKey: value, ...}, ...]}` β€” already MAPPED by the client's dialog, so a
693
+ spreadsheet column name never reaches the store. APPEND-ONLY in v1: every row is a new record,
694
+ nothing is matched or overwritten, and the dialog says so before the button is pressed.
695
+
696
+ β›” COMPUTED COLUMNS ARE REFUSED HERE, NOT FILTERED. `is_computed_cell` is the same predicate
697
+ the cell wall uses (one evaluator for one question), and a rollup or formula key arriving in
698
+ an import is not a stray to be tidied away β€” it means the client offered a target it should
699
+ not have, and silently dropping it would leave the user looking for a column of values that
700
+ never arrived. The refusal names the column.
701
+
702
+ β›” ATOMIC. `add_rows` writes nothing unless the whole batch fits under `MAX_ROWS` and every
703
+ profile cell validates, because a half-imported file is the worst outcome available: the user
704
+ cannot tell which rows landed without reconciling the spreadsheet by hand.
705
+ """
706
+ _records_or_refuse(session, table_key)
707
+ ut = _ut()
708
+ rows_in = (body or {}).get("rows")
709
+ if not isinstance(rows_in, list) or not rows_in:
710
+ raise err(400, "bad_rows", "rows must be a non-empty array of {fieldKey: value} objects")
711
+ if any(not isinstance(r, dict) for r in rows_in):
712
+ raise err(400, "bad_rows", "every row must be an object of {fieldKey: value}")
713
+ defn = _defn_or_refuse(session, table_key)
714
+ by_key = {f["key"]: f for f in (defn.get("fields") or [])}
715
+ asked = {k for r in rows_in for k in r}
716
+ unknown = sorted(k for k in asked if k not in by_key)
717
+ if unknown:
718
+ raise err(400, "unknown_field",
719
+ f"this database has no column {unknown[0]!r}")
720
+ computed = sorted(k for k in asked if ut.is_computed_cell(by_key[k]))
721
+ if computed:
722
+ label = by_key[computed[0]].get("label") or computed[0]
723
+ raise err(400, "computed_field",
724
+ f"{label!r} is worked out from other columns, so it cannot be imported into")
725
+ try:
726
+ made = ut.add_rows(table_key, rows_in, session.uname, st=session.runtime)
727
+ except Exception:
728
+ raise err(503, "store_unavailable", "nothing was imported β€” the store refused")
729
+ if made is None:
730
+ raise err(400, "refused",
731
+ f"nothing was imported β€” {len(rows_in)} rows would take this database past "
732
+ f"its {ut.MAX_ROWS}-row cap, or a profile column rejected a value")
733
+ _refresh_relations(session)
734
+ return {"imported": len(made), "pids": [int(r) for r in made]}
735
+
736
+
737
  # ---------------------------------------------------------------------------------------------
738
  # THE SHARED FIELD SCHEMA (contract C-FIELD, owner ruling R2)
739
  # ---------------------------------------------------------------------------------------------
 
947
  except grid_events.StoreUnavailable:
948
  raise err(503, "store_unavailable",
949
  "the tenant store is unavailable β€” your change was not saved")
950
+ # ⚠ THE READ-BACK IS THE DEFINITION ROW, AND ON A `ut_` SCOPE THAT IS THE WHOLE OF IT.
951
+ #
952
+ # β›” CORRECTED, wave-29 T22 (owner item 2a): this note used to say "THE READ-BACK SPANS BOTH
953
+ # STRATA, and it has to (wave 25, C3-A1)" while the two lines under it read exactly one bucket.
954
+ # It was true of the wave-25 world it was written in β€” an ordinary cell landed in the caller's
955
+ # OVERLAY and only a PROFILE cell wrote through β€” and it stayed after `grid_events` began
956
+ # routing EVERY accepted cell on a `ut_` scope to `user_tables.patch_cells`
957
+ # (`grid_events.py:1979-1984`). There is no second stratum this read is missing; a docstring
958
+ # claiming otherwise is what makes the next reader look for a merge bug that is not here.
959
+ # ⚠ Legacy overlay values, written before that routing existed, are still merged for DISPLAY
960
+ # by `table_rows` (:587-595) β€” display only, and deliberately not re-asserted here: `_took`
961
+ # asks whether THIS write landed, and this write goes to the definition.
962
  stored = dict(((_ut().get(table_key, st=session.runtime) or {}).get("rows") or {})
963
  .get(str(pid)) or {})
964
  accepted = {k: stored.get(k) for k in updates if k in stored}
platform/aios_grid.py CHANGED
@@ -673,7 +673,10 @@ def fields_from_workspace(workspace=None, cohorts=False, scope_key=None, fields_
673
  "source": "overlay",
674
  "default": bool(field.get("default", True)),
675
  "custom": True,
676
- "agg": field.get("agg") if field.get("agg") in {"sum"} else None,
 
 
 
677
  "note": str(field.get("note") or "")[:2000],
678
  **({"options": options} if ftype in ("select", "multiselect") else {}),
679
  **(_choice_appearance(field, options)
@@ -880,8 +883,109 @@ def _clean_rhs(raw, valid_keys):
880
  #: the whole reason the two modes above it needed a staged hold: `_clean_display` DROPS an
881
  #: unknown mode, so a client that offers a mode this set does not carry lets a user build a view
882
  #: that silently reverts to a grid on the next read.
 
 
 
 
 
 
 
 
 
 
 
 
883
  DISPLAY_MODES = {'grid', 'list', 'calendar', 'kanban', 'map', 'dashboard', 'chart',
884
- 'timeseries', 'catalog', 'swipe'}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
885
 
886
  #: C3 β€” the swipe binding's option cap. `leftOption`/`rightOption` are stored VALUES of a
887
  #: single-select, and `_clean_options` trims every choice to 120 chars, so this is that same
@@ -937,6 +1041,35 @@ _LEGACY_MODES = {'dashboard': 'chart'}
937
  #: GroupTableView over salesParity.tableFromSpec.
938
  CHART_KINDS = {'bar', 'line', 'area', 'donut', 'kpi', 'table'}
939
  CHART_AGGS = {'sum', 'avg', 'count', 'min', 'max'}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
940
  MAX_CHARTS = 12 #: per view β€” a dashboard, not an unbounded render loop
941
  MAX_CHART_TITLE = 60
942
 
@@ -1379,6 +1512,10 @@ def _clean_display(raw, valid_keys):
1379
  # `kanbanClamp` law) wearing a control that promises a choice.
1380
  if left and right and left.casefold() != right.casefold():
1381
  out['swipe'] = {'fieldKey': f_key, 'leftOption': left, 'rightOption': right}
 
 
 
 
1382
  return out
1383
 
1384
 
 
673
  "source": "overlay",
674
  "default": bool(field.get("default", True)),
675
  "custom": True,
676
+ # WAVE-29 C7: the whole vocabulary, not the `{"sum"}` literal that was here β€” a
677
+ # picker offering Average against a projection that only passes Sum through is the
678
+ # silent half of this feature.
679
+ "agg": field.get("agg") if field.get("agg") in FIELD_AGGS else None,
680
  "note": str(field.get("note") or "")[:2000],
681
  **({"options": options} if ftype in ("select", "multiselect") else {}),
682
  **(_choice_appearance(field, options)
 
883
  #: the whole reason the two modes above it needed a staged hold: `_clean_display` DROPS an
884
  #: unknown mode, so a client that offers a mode this set does not carry lets a user build a view
885
  #: that silently reverts to a grid on the next read.
886
+ #: ⭐⭐ WAVE-29 R6/R7 (owner item 10, contract C3) β€” 'form', which CLOSES D-90. The client has
887
+ #: carried `form` in its union, with an icon, a label and a tone, since wave 23; this set never
888
+ #: did, so `_clean_display` DROPPED both the mode and the `display.form` spec on every write β€”
889
+ #: while `routes_forms.py` reads exactly that key to serve the public submit door. The public door
890
+ #: has therefore been live and UNREACHABLE for two waves: not broken, just impossible to point at
891
+ #: anything. The mirror is one name, and it is the half nobody could see was missing because
892
+ #: BOTH sides were individually consistent.
893
+ #: ⚠ Being a legal stored mode is NOT the same as being offered: `form` is deliberately held out
894
+ #: of the client's `CREATABLE_MODES` until `CustomerGrid` mounts a renderer for it (the hold law
895
+ #: written into `iconShapes.ts`, and now machine-enforced in BOTH directions by
896
+ #: `verify_icons.py::mode_parity` β€” offering an unmounted mode is red, and mounting an unoffered
897
+ #: one is red too, so the hold cannot outlive its reason the way wave 27's did).
898
  DISPLAY_MODES = {'grid', 'list', 'calendar', 'kanban', 'map', 'dashboard', 'chart',
899
+ 'timeseries', 'catalog', 'swipe', 'form'}
900
+
901
+ #: ⭐⭐ WAVE-29 R7 (owner item 10, contracts C3/C4) β€” THE FORM INTERFACE's stored spec, at
902
+ #: `views[<id>].config.display.form`. The public door (`aios-web/api/routes_forms.py`) has read
903
+ #: exactly this key since wave 23 and NOTHING HAS EVER BEEN ABLE TO WRITE IT: `form` was not a
904
+ #: legal mode and this function had no branch for the key, so every spec a client sent was dropped
905
+ #: on the way in. That is D-90 stated precisely β€” not a broken feature, an unreachable one.
906
+ #:
907
+ #: β›” THE TOKEN IS NOT HERE, AND IT NEVER WILL BE. A share token that rides the wire is a token a
908
+ #: browser can CHOOSE, and `routes_forms._resolve` walks tenants and answers with the FIRST match β€”
909
+ #: so one tenant setting its token to another tenant's value would silently receive that tenant's
910
+ #: submissions. The token is minted server-side and lives in a bucket no client write can reach;
911
+ #: `_clean_form` drops any `token` key that arrives here, rather than validating its shape.
912
+ FORM_ACCESS = ('public', 'emails')
913
+ MAX_FORM_FIELDS = 60
914
+ MAX_FORM_EMAILS = 200
915
+ MAX_FORM_TITLE, MAX_FORM_DESC, MAX_FORM_SUBMIT = 120, 1000, 60
916
+ MAX_FORM_EMAIL = 254
917
+
918
+ #: The field types a form may COLLECT, as an ALLOW-LIST rather than a list of exclusions β€” the
919
+ #: fail-closed direction, because the cost of the two mistakes is not symmetric. A type missing
920
+ #: from here is a question the builder cannot ask yet; a type wrongly present is a public door
921
+ #: writing values the column cannot mean (an `image` with no upload channel, a `json` document
922
+ #: typed into a text box, a `link` naming a record id a stranger guessed).
923
+ #: ⚠ NOT sufficient on its own, and the reason is a shape this codebase has been bitten by before:
924
+ #: a METRIC bag rides ANY field type (`core/user_tables.py` β€” `metric` is not a field kind), so an
925
+ #: `int` column can be machine-computed while passing this list. `routes_forms` therefore asks
926
+ #: `user_tables.is_computed_cell` as well β€” one evaluator for "is this computed", reused rather
927
+ #: than re-derived ([[one-evaluator-per-question]]).
928
+ #: Client mirror: `customer-grid/FormInterface.tsx` FORM_FIELD_TYPES; `verify_forms.py` compares
929
+ #: the two files name-for-name.
930
+ FORM_FIELD_TYPES = ('text', 'select', 'multiselect', 'int', 'currency', 'pct', 'date',
931
+ 'checkbox', 'phone', 'email', 'url', 'rating')
932
+
933
+ #: Deliberately looser than a full RFC parse and stricter than `routes_forms._clean_values`' "@ in
934
+ #: it": this list decides who MAY SUBMIT, so a typo that silently locks a colleague out is the
935
+ #: expensive failure, not an odd address that gets in.
936
+ _FORM_EMAIL = re.compile(r'^[^@\s,;]+@[^@\s,;]+\.[^@\s,;]+$')
937
+
938
+
939
+ def _clean_form(raw, valid_keys):
940
+ """One form spec, fail-closed. Returns None when nothing is configured.
941
+
942
+ ⚠ FIELD ORDER IS THE FORM'S OWN and is preserved here, not re-derived from the schema: the
943
+ builder let somebody arrange these questions, and sorting them by column order would silently
944
+ rearrange a live form every time a column was added (`_public_form` states the same rule from
945
+ the serving end).
946
+
947
+ ⚠ PARTIAL-DROP, not whole-key drop, and the asymmetry against `swipe` above is deliberate. A
948
+ swipe binding is one three-part machine: two of its parts is not a degraded deck, it is a deck
949
+ that can never write. A form is a LIST of questions β€” losing the column behind question three
950
+ costs the asker question three, and taking the whole form away because one field was deleted
951
+ would be a far larger loss than the one that happened.
952
+ """
953
+ if not isinstance(raw, dict):
954
+ return None
955
+ fields, seen = [], set()
956
+ for k in (raw.get('fields') or [])[:MAX_FORM_FIELDS]:
957
+ if k in valid_keys and k not in seen:
958
+ seen.add(k)
959
+ fields.append(k)
960
+ out = {}
961
+ if fields:
962
+ out['fields'] = fields
963
+ # A required flag on a question the form no longer asks is not a rule, it is a trap: the
964
+ # submitter can never satisfy it and the sentence names a field they cannot see.
965
+ req = [k for k in dict.fromkeys(raw.get('required') or []) if k in seen]
966
+ if req:
967
+ out['required'] = req
968
+ for key, cap in (('title', MAX_FORM_TITLE), ('desc', MAX_FORM_DESC),
969
+ ('submitLabel', MAX_FORM_SUBMIT)):
970
+ text = str(raw.get(key) or '').strip()[:cap]
971
+ if text:
972
+ out[key] = text
973
+ # `public` is the ABSENT default (the `kanbanClamp` law: one way to say one thing), so only
974
+ # the restrictive value is ever stored. β‡’ a spec that loses its `access` key fails OPEN, which
975
+ # is why `emails` is what gets written rather than a `public: false`.
976
+ if raw.get('access') == 'emails':
977
+ out['access'] = 'emails'
978
+ emails = []
979
+ for e in (raw.get('emails') or [])[:MAX_FORM_EMAILS]:
980
+ e = str(e or '').strip().lower()[:MAX_FORM_EMAIL]
981
+ if _FORM_EMAIL.match(e) and e not in emails:
982
+ emails.append(e)
983
+ # Kept even while `access` is public: a person toggling the door open to test it and back
984
+ # again must not lose the list of people they typed. It is never served publicly.
985
+ if emails:
986
+ out['emails'] = emails
987
+ return out or None
988
+
989
 
990
  #: C3 β€” the swipe binding's option cap. `leftOption`/`rightOption` are stored VALUES of a
991
  #: single-select, and `_clean_options` trims every choice to 120 chars, so this is that same
 
1041
  #: GroupTableView over salesParity.tableFromSpec.
1042
  CHART_KINDS = {'bar', 'line', 'area', 'donut', 'kpi', 'table'}
1043
  CHART_AGGS = {'sum', 'avg', 'count', 'min', 'max'}
1044
+
1045
+ #: ⭐ WAVE-29 C7 (item 17) β€” THE COLUMN-SUMMARY vocabulary: what a FIELD's `agg` may be, which is
1046
+ #: what the grid's totals row and its per-group subtotals compute. ORDERED, because the order is
1047
+ #: the picker's order; membership tests read it as a tuple perfectly well.
1048
+ #:
1049
+ #: β›” IT IS NOT `CHART_AGGS` AND THE TWO MUST NOT BE MERGED, however alike they look. `CHART_AGGS`
1050
+ #: gatekeeps a STORED value with live data behind it (`charts[].agg`, `calendarMetrics[].agg`):
1051
+ #: `_clean_chart` falls back to 'sum' on an unknown agg and `_clean_display` DROPS a whole
1052
+ #: calendarMetrics entry, so renaming its 'avg' would silently turn every saved chart into a sum
1053
+ #: and delete calendar cards, with nothing red. A chart's aggregation and a column's summary are
1054
+ #: also different questions β€” one reduces a SERIES, the other a COLUMN β€” and one list serving both
1055
+ #: would have to be the intersection of what each can express.
1056
+ #:
1057
+ #: ⭐ `average`, NOT `avg`, and the tie is broken by the vocabulary we cannot rename: `ROLLUP_FNS`
1058
+ #: (`core/user_tables.py`, 16 names, 47 rollups live in production) already spells it `average`,
1059
+ #: and it is the aggregate vocabulary a user actually reads today. Spelling it `avg` here would
1060
+ #: give the product two words for one operation on two menus a click apart.
1061
+ #:
1062
+ #: ⚠ `median` is net-new: it is in NEITHER `CHART_AGGS` nor `ROLLUP_FNS`, so a Median column
1063
+ #: summary has no rollup equivalent and this list is NOT a subset of either of its neighbours.
1064
+ #:
1065
+ #: ⚠ `count` counts ROWS in the scope (the group, or every matched row) β€” not non-blank cells.
1066
+ #: `ROLLUP_FNS` splits that hair three ways (count / counta / countall); a column summary does not,
1067
+ #: and must not grow a second spelling of it.
1068
+ #:
1069
+ #: Client mirror: `customer-grid/iconShapes.ts` FIELD_AGGS β€” ONE client list, imported by
1070
+ #: `aggregations.ts` and the field editor rather than re-declared, so the only boundary left to
1071
+ #: police is this one. `verify_icons.py::agg_parity` reads BOTH FILES and compares them.
1072
+ FIELD_AGGS = ('sum', 'average', 'median', 'min', 'max', 'count')
1073
  MAX_CHARTS = 12 #: per view β€” a dashboard, not an unbounded render loop
1074
  MAX_CHART_TITLE = 60
1075
 
 
1512
  # `kanbanClamp` law) wearing a control that promises a choice.
1513
  if left and right and left.casefold() != right.casefold():
1514
  out['swipe'] = {'fieldKey': f_key, 'leftOption': left, 'rightOption': right}
1515
+ # ── ⭐⭐ WAVE-29 R7 (item 10): the FORM spec β€” see `_clean_form` for why the token is not here.
1516
+ form = _clean_form(raw.get('form'), valid_keys)
1517
+ if form:
1518
+ out['form'] = form
1519
  return out
1520
 
1521
 
platform/core/shared_overlay.py ADDED
@@ -0,0 +1,264 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """The TENANT-WIDE overlay stratum β€” one value per (row, column) for the whole workspace.
2
+
3
+ Wave 29, item 20 / owner ruling R11, contract C5. The sibling of `core/table_store.py`, which
4
+ holds the PER-USER strata (`store.get(key)[username]`) and always has.
5
+
6
+ β›” THE DEFECT THIS EXISTS FOR IS NOT "SHARING WOULD BE NICE" β€” IT IS THAT A SHARED VIEW SILENTLY
7
+ WIDENS. `modules/product_data.py` already states it, in the comment above the supplier master:
8
+
9
+ "A user-created field and its values live in the PER-USER strata; only VIEWS are shared. So a
10
+ shared 'Buy list' view that filtered on a user-created column would, for every OTHER account,
11
+ name a column that does not exist β€” and an unknown column is an INACTIVE condition in the
12
+ tri-state engine, which IGNORES it and therefore WIDENS. The buy list would silently show the
13
+ whole catalogue to everyone but its author."
14
+
15
+ That is why the four supplier columns were frozen as read-only CONTRACT columns rather than made
16
+ editable, and why the owner's ask ("turn this Excel sheet into a User created Field that we can
17
+ edit") has been parked for two waves. A column whose value is the same for every reader makes the
18
+ shared view mean ONE thing, which is the precondition for editing it at all.
19
+
20
+ ────────────────────────────────────────────────────────────────────────────────────────────────
21
+ β›”β›” THIS MODULE IS NOT A PERMISSION WALL, AND MUST NEVER BECOME ONE BY ACCIDENT.
22
+
23
+ It refuses no reader and no writer. The caller has already answered "may this session open this
24
+ surface" (`user_tables.may_open`, `Session.require`, the BU pool) and this module answers only
25
+ "what is stored". Two different questions; one of them belongs upstream, where the session is.
26
+
27
+ What it DOES enforce is the one thing a caller can get wrong silently:
28
+
29
+ ⭐ `cells(table_key, pids)` β€” `pids` IS REQUIRED, POSITIONALLY, AND THERE IS NO "EVERYTHING"
30
+ CALL. A default of "all rows" is the widening hazard above wearing a friendly face: the
31
+ caller passes the row set it has ALREADY scoped, so a cell for a row this reader may not see
32
+ cannot come back to be merged. There is deliberately no `all_cells()` to reach for; a caller
33
+ that genuinely needs the lot passes the lot, in writing, where a reviewer can see it.
34
+
35
+ The row wall then holds twice over, because `aios_grid.rows_from_pool` iterates the POOL and looks
36
+ each pid UP in the overlay β€” never the reverse. A cell for a row outside the pool has nothing to
37
+ attach to. This module is built to keep that true rather than to re-implement it.
38
+ ────────────────────────────────────────────────────────────────────────────────────────────────
39
+
40
+ RESIDENCY. Its own bucket, `<table_key>__shared`, beside the per-user one β€” never a `__shared__`
41
+ member inside it. Two reasons, and the first is `product_data.py`'s own argument for separate
42
+ topic keys ("separate store keys make that structurally impossible, which is the whole reason the
43
+ table-page factory exists"): a per-user reader iterating usernames cannot encounter shared data
44
+ when there is no shared data in that bucket to encounter. The second is cost β€” the per-user bucket
45
+ carries every user's views, and a cell edit should not read-modify-write all of it.
46
+
47
+ SHAPE, chosen to be drop-in:
48
+
49
+ {"fields": {field_key: Field}, # the tenant-wide column DEFINITIONS
50
+ "cells": {"<pid>": {field_key: value}}} # exactly `rows_from_pool(overlays=...)`'s shape
51
+
52
+ `cells()` returns STRING pid keys for that reason β€” `rows_from_pool` does `overlays.get(str(pid))`,
53
+ so a caller merges the shared stratum over the per-user one with one `dict.update` and cannot get
54
+ the key type wrong. (`table_store` stores `{str(pid): {...}}` too; one shape, three readers.)
55
+ """
56
+ import core.store as store
57
+
58
+ #: The suffix that turns a topic's per-user workspace key into its shared one. Callers pass the
59
+ #: key they ALREADY hold (`product_data.TABLE_KEY`, `f'{ut_key}_table_workspace'`) β€” one
60
+ #: identifier for both strata, so there is no second naming convention to get wrong.
61
+ BUCKET_SUFFIX = '__shared'
62
+
63
+ #: One cell value's ceiling, matching the `json` field kind's. A shared cell is read by every user
64
+ #: in the tenant, so an unbounded one is an unbounded cost for all of them.
65
+ MAX_VALUE_CHARS = 32_768
66
+
67
+
68
+ def bucket(table_key):
69
+ """The store key this topic's shared stratum lives under."""
70
+ key = str(table_key or '').strip()
71
+ if not key:
72
+ raise ValueError('shared_overlay: a table_key is required β€” it names the bucket')
73
+ return f'{key}{BUCKET_SUFFIX}'
74
+
75
+
76
+ def _st(st):
77
+ return st if st is not None else store
78
+
79
+
80
+ def _read(table_key, st=None):
81
+ """The whole stratum, always in its full two-key shape. Lenient like every other display
82
+ read: an unreachable store degrades to "nothing shared yet", never to an exception on a page
83
+ that would otherwise render."""
84
+ try:
85
+ data = _st(st).get(bucket(table_key)) or {}
86
+ except Exception:
87
+ data = {}
88
+ return {'fields': dict(data.get('fields') or {}),
89
+ 'cells': dict(data.get('cells') or {})}
90
+
91
+
92
+ def _write(table_key, change, st=None, flush='async'):
93
+ """Read-modify-write one shared stratum.
94
+
95
+ `flush='async'` by default for the same reason `table_store._update` uses it: a typed cell
96
+ lands here inside the request round-trip, and the historical synchronous hub commit cost
97
+ seconds per keystroke. Structural writes (a field definition) pass `flush='sync'` β€” they are
98
+ rare, and a lost column definition is a worse failure than a lost keystroke.
99
+ """
100
+ def _up(data):
101
+ data = data if isinstance(data, dict) else {}
102
+ data.setdefault('fields', {})
103
+ data.setdefault('cells', {})
104
+ change(data)
105
+ return data
106
+ return _st(st).update(bucket(table_key), _up, flush=flush)
107
+
108
+
109
+ def _pid(pid):
110
+ """Pids are ints everywhere in the grid and strings in JSON. ONE coercion, here, so a caller
111
+ passing either cannot write a row that a reader keyed the other way never finds."""
112
+ return str(int(pid))
113
+
114
+
115
+ def _value(value):
116
+ """A cell holds a SCALAR. The Row contract is scalar on every surface β€” the grid, the filter
117
+ engine, formulas, export β€” and the `json` kind is a validated STRING rather than an object.
118
+
119
+ β›” A dict or a list RAISES rather than being dropped. This is called by our own code, so a
120
+ non-scalar is a programming error, and silently storing nothing would surface later as "the
121
+ shared column is blank for everyone" with no failure anywhere near the cause.
122
+ """
123
+ if isinstance(value, (dict, list, tuple, set)):
124
+ raise ValueError(f'shared_overlay: a cell holds a scalar, not {type(value).__name__}')
125
+ if value is None or isinstance(value, bool) or isinstance(value, (int, float)):
126
+ return value
127
+ text = str(value)
128
+ return text[:MAX_VALUE_CHARS]
129
+
130
+
131
+ # ----------------------------------------------------------------- the column DEFINITIONS
132
+ def fields(table_key, st=None):
133
+ """`{field_key: Field}` β€” the columns this topic shares tenant-wide.
134
+
135
+ Unscoped on purpose, and it is the one thing here that is: a shared column's EXISTENCE is
136
+ tenant-wide by definition β€” that is the whole feature, and it is what stops a shared view
137
+ naming a column half the workspace lacks. Its VALUES are scoped by `cells()`.
138
+ """
139
+ return _read(table_key, st)['fields']
140
+
141
+
142
+ def is_shared(table_key, field_key, st=None):
143
+ """Is this column's value tenant-wide? The predicate a caller uses to decide WHICH stratum to
144
+ read and write β€” one evaluator, so the read path and the write path cannot disagree about
145
+ where a given column lives ([[one-evaluator-per-question]])."""
146
+ return str(field_key or '') in _read(table_key, st)['fields']
147
+
148
+
149
+ def put_field(table_key, field_key, defn, st=None):
150
+ """Declare (or redefine) a shared column. Returns what was stored."""
151
+ key = str(field_key or '').strip()
152
+ if not key:
153
+ raise ValueError('shared_overlay: a field needs a key')
154
+ entry = dict(defn or {})
155
+ entry['key'] = key
156
+
157
+ def _add(data):
158
+ data['fields'][key] = entry
159
+
160
+ _write(table_key, _add, st, flush='sync')
161
+ return entry
162
+
163
+
164
+ def drop_field(table_key, field_key, st=None):
165
+ """Remove a shared column AND every stored value for it.
166
+
167
+ β›” The cells go with the definition, exactly as `table_store.delete_field` scrubs its own:
168
+ orphaned values would silently resurface if the key were ever reused β€” and a resurrected
169
+ value in a TENANT-WIDE stratum reappears for everybody at once.
170
+ """
171
+ key = str(field_key or '').strip()
172
+ if not key:
173
+ return False
174
+ hit = [False]
175
+
176
+ def _drop(data):
177
+ hit[0] = data['fields'].pop(key, None) is not None
178
+ for row in data['cells'].values():
179
+ if isinstance(row, dict):
180
+ row.pop(key, None)
181
+ # ⚠ AND DROP THE ROWS THAT ARE NOW EMPTY. `cells()` already skips a blank row, so this
182
+ # changes nothing a reader sees β€” but this bucket is read by every user in the tenant,
183
+ # and a `{}` per pid that once held a since-deleted column is dead weight that only ever
184
+ # grows. Caught by `prune()` reporting rows nobody could see as dropped.
185
+ for pid in [p for p, row in data['cells'].items() if not row]:
186
+ data['cells'].pop(pid, None)
187
+
188
+ _write(table_key, _drop, st, flush='sync')
189
+ return hit[0]
190
+
191
+
192
+ # ----------------------------------------------------------------------------- the VALUES
193
+ def cells(table_key, pids, st=None):
194
+ """`{"<pid>": {field_key: value}}` for the rows named by `pids` β€” and ONLY those.
195
+
196
+ β›” `pids` IS REQUIRED. See the module header: this is the row wall expressed as a signature,
197
+ so a caller cannot get "every shared cell in the tenant" by forgetting an argument. Pass the
198
+ pool you have already scoped for this session.
199
+
200
+ An empty `pids` legitimately returns `{}` β€” a reader with no rows sees no cells, which is the
201
+ correct answer rather than a special case.
202
+ """
203
+ if pids is None:
204
+ raise TypeError('shared_overlay.cells: pids is required β€” pass the row set you have '
205
+ 'already scoped for this reader (there is deliberately no "all" call)')
206
+ wanted = {_pid(p) for p in pids}
207
+ if not wanted:
208
+ return {}
209
+ stored = _read(table_key, st)['cells']
210
+ return {pid: dict(row) for pid, row in stored.items()
211
+ if pid in wanted and isinstance(row, dict) and row}
212
+
213
+
214
+ def put_cell(table_key, pid, field_key, value, st=None):
215
+ """Write ONE shared cell. Returns the value as stored (which may be truncated)."""
216
+ return put_cells(table_key, pid, {field_key: value}, st=st).get(str(field_key or ''))
217
+
218
+
219
+ def put_cells(table_key, pid, values, st=None):
220
+ """Write several shared cells on one row, in one store update. Returns what was stored."""
221
+ row_id = _pid(pid)
222
+ clean = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
223
+ if not clean:
224
+ return {}
225
+
226
+ def _patch(data):
227
+ data['cells'].setdefault(row_id, {}).update(clean)
228
+
229
+ _write(table_key, _patch, st)
230
+ return clean
231
+
232
+
233
+ def clear_row(table_key, pid, st=None):
234
+ """Forget every shared cell on one row. True when there was something to forget."""
235
+ row_id = _pid(pid)
236
+ hit = [False]
237
+
238
+ def _clear(data):
239
+ hit[0] = data['cells'].pop(row_id, None) is not None
240
+
241
+ _write(table_key, _clear, st)
242
+ return hit[0]
243
+
244
+
245
+ def prune(table_key, live_pids, st=None):
246
+ """Drop shared cells for rows that no longer exist. Returns how many rows were dropped.
247
+
248
+ β›” NOT a scoped read wearing another name, and the difference is the whole reason `cells()`
249
+ refuses to serve everything: `live_pids` here means *every row this TABLE has*, which is a
250
+ fact about the data, whereas `pids` in `cells()` means *every row this READER may see*, which
251
+ is a fact about the session. Calling this with one session's pool would delete the shared
252
+ values of every row that session cannot see. The name says which is which; so does this note.
253
+ """
254
+ keep = {_pid(p) for p in live_pids}
255
+ dropped = [0]
256
+
257
+ def _prune(data):
258
+ gone = [pid for pid in data['cells'] if pid not in keep]
259
+ for pid in gone:
260
+ data['cells'].pop(pid, None)
261
+ dropped[0] = len(gone)
262
+
263
+ _write(table_key, _prune, st, flush='sync')
264
+ return dropped[0]
platform/core/store.py CHANGED
@@ -33,6 +33,16 @@ REPO = os.environ.get('OS_DATA_REPO', 'royal-imports/cfo-os-data')
33
  _FLUSH_DELAY = 2.0 # coalesce a burst of edits into one commit
34
  _FLUSH_MIN_GAP = 20.0 # floor between commits of one key (the 256-commits/hr budget)
35
 
 
 
 
 
 
 
 
 
 
 
36
 
37
  def _token():
38
  return os.environ.get('HF_TOKEN') or None
@@ -63,6 +73,12 @@ class Store:
63
  self._flushers = {} # name -> live worker thread
64
  self._repo_ok = False # create_repo(exist_ok=True) confirmed once per instance
65
  self._last_flush = {} # name -> monotonic time of the last completed upload
 
 
 
 
 
 
66
 
67
  def available(self):
68
  """True when a token is configured β€” callers degrade gracefully without one."""
@@ -131,6 +147,49 @@ class Store:
131
  except Exception:
132
  return True
133
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
134
  def _upload(self, name, data):
135
  """The raw hub write. create_repo is confirmed ONCE per instance β€” it was a full extra
136
  API round-trip on every put(), pure latency after the first success."""
@@ -193,6 +252,7 @@ class Store:
193
  self._cache[name] = json.loads(json.dumps(data))
194
  self._owned[name] = True
195
  self._last_flush[name] = _time.monotonic()
 
196
  return self._cache[name]
197
 
198
  def _flush_worker(self, name):
@@ -322,6 +382,7 @@ class Store:
322
  raise RuntimeError('No HF_TOKEN configured β€” persistence is unavailable.')
323
  self._cache[name] = json.loads(json.dumps(data))
324
  self._owned[name] = True
 
325
  self._schedule_flush(name)
326
  return data
327
  self.put(name, data)
@@ -475,6 +536,20 @@ def update(name, fn, flush='sync'):
475
  return _d().update(name, fn, flush=flush)
476
 
477
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
478
  def _flush_all_at_exit():
479
  with _INSTANCES_LOCK:
480
  instances = list(_INSTANCES.values())
 
33
  _FLUSH_DELAY = 2.0 # coalesce a burst of edits into one commit
34
  _FLUSH_MIN_GAP = 20.0 # floor between commits of one key (the 256-commits/hr budget)
35
 
36
+ #: WAVE 29 (item 20 / ruling R11, contract C6) β€” THE CHANGE TOKEN'S PROCESS STAMP.
37
+ #:
38
+ #: `Store`'s revision counter is IN-MEMORY, so a restarted Space would begin again at 0 and a
39
+ #: browser holding `…:4` from the previous process could read `…:4` from the new one and conclude
40
+ #: nothing had changed. Prefixing every token with a per-process stamp makes a restart read as a
41
+ #: change, which is the truthful answer: the client's copy predates this process entirely.
42
+ #:
43
+ #: ⚠ NOT a clock and never compared for order β€” a token is opaque and compared ONLY for equality.
44
+ REV_EPOCH = f'{int(_time.time()):x}{os.getpid():x}'
45
+
46
 
47
  def _token():
48
  return os.environ.get('HF_TOKEN') or None
 
73
  self._flushers = {} # name -> live worker thread
74
  self._repo_ok = False # create_repo(exist_ok=True) confirmed once per instance
75
  self._last_flush = {} # name -> monotonic time of the last completed upload
76
+ # --- the CHANGE TOKEN (wave 29, item 20 / C6) ------------------------------------
77
+ # name -> how many accepted writes this process has applied to that bucket, and when.
78
+ # Read by `revision()` in O(1) with NO download and NO deep copy; see its docstring for
79
+ # why that constraint is the whole feature rather than an optimisation.
80
+ self._revs = {}
81
+ self._rev_at = {}
82
 
83
  def available(self):
84
  """True when a token is configured β€” callers degrade gracefully without one."""
 
147
  except Exception:
148
  return True
149
 
150
+ # ------------------------------------------------------- the CHANGE TOKEN (wave 29, C6)
151
+ def _bump(self, name):
152
+ """Advance one bucket's write counter. THE CALLER HOLDS THE LOCK.
153
+
154
+ Called from the two places an accepted write becomes visible to readers of this process
155
+ β€” `put()` (which `update(flush='sync')` goes through) and `update()`'s async branch. NOT
156
+ from `_flush_worker`: that uploads data a bump already accounted for, and counting it
157
+ again would report a change to every browser each time the coalescing worker woke.
158
+ """
159
+ n = str(name)
160
+ self._revs[n] = self._revs.get(n, 0) + 1
161
+ self._rev_at[n] = _time.time()
162
+
163
+ def revision(self, name):
164
+ """`{'rev', 'updated_at', 'token'}` for ONE bucket β€” a dict read, nothing else.
165
+
166
+ β›” THE ZERO-COST PROPERTY IS THE FEATURE, NOT AN OPTIMISATION, and the arithmetic is why
167
+ this method exists at all. A browser asking "has anything changed" by re-fetching rows
168
+ costs THREE full-tenant deep copies under ONE lock (`get()` json-round-trips on the way
169
+ in and on the way out) on ONE uvicorn process, at a documented ceiling of 35.8 MB / ~1.4 s
170
+ per bucket β€” so two tabs polling saturate the server and every unrelated write queues
171
+ behind them. This performs no download, no `get()`, and no copy of the value.
172
+ β‡’ Anything added here that reads a bucket destroys the whole point (`verify_live_workspace`
173
+ counts `get`/`_read_strict`/`_download` on the serving path and goes red on one).
174
+
175
+ `rev` and `updated_at` are `core/store_pg.py`'s own column names, on purpose: that backend
176
+ ALREADY increments `rev` and sets `updated_at = now()` on every write, so the token stops
177
+ being inert the moment D-4 flips, with the wire shape unchanged.
178
+
179
+ ⚠ WHAT IT CANNOT SEE, stated rather than implied: this counter is per PROCESS, so a write
180
+ by a SECOND container against the same HF dataset is invisible here. That is not a limit
181
+ this introduces β€” `get()` caches a bucket for the life of the process and never re-reads
182
+ it, so the other container's write is invisible to every reader on this backend already.
183
+ The token is exactly as fresh as the store it reports on. Postgres has no such gap.
184
+ ⚠ Bytes (`upload_bytes`/`delete_path`) are a different address space and are NOT counted:
185
+ an attachment is fetched on explicit user action, never polled.
186
+ """
187
+ n = str(name)
188
+ with self._lock:
189
+ rev = int(self._revs.get(n, 0))
190
+ at = self._rev_at.get(n)
191
+ return {'rev': rev, 'updated_at': at, 'token': f'{REV_EPOCH}:{rev}'}
192
+
193
  def _upload(self, name, data):
194
  """The raw hub write. create_repo is confirmed ONCE per instance β€” it was a full extra
195
  API round-trip on every put(), pure latency after the first success."""
 
252
  self._cache[name] = json.loads(json.dumps(data))
253
  self._owned[name] = True
254
  self._last_flush[name] = _time.monotonic()
255
+ self._bump(name) # C6 β€” AFTER the upload: a raise here is not a write
256
  return self._cache[name]
257
 
258
  def _flush_worker(self, name):
 
382
  raise RuntimeError('No HF_TOKEN configured β€” persistence is unavailable.')
383
  self._cache[name] = json.loads(json.dumps(data))
384
  self._owned[name] = True
385
+ self._bump(name) # C6 β€” the async write is ACCEPTED here, not at flush time
386
  self._schedule_flush(name)
387
  return data
388
  self.put(name, data)
 
536
  return _d().update(name, fn, flush=flush)
537
 
538
 
539
+ def revision(name):
540
+ """The bucket's change token β€” wave 29, C6. See `Store.revision` for why it copies nothing.
541
+
542
+ β›” THIS IS A TENTH STORE OPERATION, AND IT WAS ONLY ALLOWED TO BECOME ONE ONCE BOTH BACKENDS
543
+ HAD IT. `verify_store_pg.py` pins this module's public surface at a contracted list precisely
544
+ so a capability one backend lacks cannot be reached through the shared door and die at the
545
+ cutover β€” so this function, `store_pg.revision`, and that gate's `IFACE` entry are ONE change
546
+ and must stay one. It shipped for a few hours as a METHOD ONLY, deliberately, while the pg half
547
+ had no owner: a method is a capability the HF store has, a module function is a promise both
548
+ backends keep.
549
+ """
550
+ return _d().revision(name)
551
+
552
+
553
  def _flush_all_at_exit():
554
  with _INSTANCES_LOCK:
555
  instances = list(_INSTANCES.values())
platform/core/store_backend.py CHANGED
@@ -55,9 +55,13 @@ def active():
55
  return _hf
56
 
57
 
58
- # --- the nine delegates. Written out rather than generated with setattr so that reading this file
59
  # tells you the whole interface, and so a new store operation cannot be added to core/store.py
60
  # without something here failing to match (verify_store_pg.py compares the signatures).
 
 
 
 
61
  def available():
62
  return active().available()
63
 
@@ -92,3 +96,13 @@ def delete_path(path_in_repo):
92
 
93
  def flush(name_=None, timeout=30.0):
94
  return active().flush(name_, timeout=timeout)
 
 
 
 
 
 
 
 
 
 
 
55
  return _hf
56
 
57
 
58
+ # --- the TEN delegates. Written out rather than generated with setattr so that reading this file
59
  # tells you the whole interface, and so a new store operation cannot be added to core/store.py
60
  # without something here failing to match (verify_store_pg.py compares the signatures).
61
+ #
62
+ # ⭐ That guard did its job in wave 29: `revision()` landed in `core/store.py` and `core/store_pg.py`
63
+ # and the gate went red HERE, on the one file of the four that the change had missed. A generated
64
+ # delegate list would have covered it silently and left this file unable to describe itself.
65
  def available():
66
  return active().available()
67
 
 
96
 
97
  def flush(name_=None, timeout=30.0):
98
  return active().flush(name_, timeout=timeout)
99
+
100
+
101
+ def revision(name_):
102
+ """The bucket's change token (wave 29, C6) β€” `{'rev', 'updated_at', 'token'}`.
103
+
104
+ Both backends answer, and they answer with the same keys and the same units (`updated_at` is
105
+ epoch seconds on each). That parity is the reason the change-token endpoint needs no branch on
106
+ the backend, and it is asserted rather than assumed by `verify_store_pg`'s interface section.
107
+ """
108
+ return active().revision(name_)
platform/core/store_pg.py CHANGED
@@ -233,6 +233,37 @@ def delete_path(path_in_repo, tenant_slug=None):
233
  return True
234
 
235
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
236
  def flush(name=None, timeout=30.0):
237
  """A no-op that returns True: every write above is already committed when it returns. Kept in
238
  the interface because QA gates and shutdown hooks call it and must not branch on the backend."""
@@ -306,6 +337,9 @@ class PgStore:
306
  def update(self, name, fn, flush='sync'):
307
  return update(name, fn, flush=flush, tenant_slug=self.tenant_slug)
308
 
 
 
 
309
  def upload_bytes(self, path_in_repo, data, message=None):
310
  return upload_bytes(path_in_repo, data, message=message, tenant_slug=self.tenant_slug)
311
 
 
233
  return True
234
 
235
 
236
+ def revision(name, tenant_slug=None):
237
+ """`{'rev', 'updated_at', 'token'}` for ONE bucket β€” wave 29, item 20 / contract C6.
238
+
239
+ ⭐ THIS BACKEND HAS MAINTAINED THE ANSWER SINCE X4 AND NEVER PUBLISHED IT. Every `put` and
240
+ `update` above already ends `updated_at = now(), rev = {bare}.rev + 1`; all this adds is the
241
+ read door. Which is why C6 insisted the HF side use these two column NAMES for its in-memory
242
+ counter: the wire shape does not change at the cutover, so the client keeps polling the same
243
+ endpoint and the token simply stops being per-process.
244
+
245
+ ⭐ AND HERE THE TOKEN IS DURABLE, which is the real upgrade. `core.store`'s counter lives in
246
+ one process, so it cannot see a write by a second container and it restarts at zero β€” hence
247
+ the process stamp in its token. `rev` is a column: it survives a restart, and it is shared by
248
+ every process pointed at this schema. The prefix below is therefore a constant rather than a
249
+ per-process value, and a backend flip changes the token exactly once (one refetch, correct).
250
+
251
+ An absent key is `rev 0`, not an error: a bucket nobody has written yet has changed zero times,
252
+ which is a fact a client can hold a baseline against.
253
+ """
254
+ with _pool().connection() as con:
255
+ row = con.execute(
256
+ _q('SELECT rev, updated_at FROM {tbl} WHERE key = %s', 'store_kv', tenant_slug),
257
+ (str(name),)).fetchone()
258
+ rev = int(row[0]) if row and row[0] is not None else 0
259
+ stamp = row[1] if row else None
260
+ # ⚠ EPOCH SECONDS ON BOTH BACKENDS. `core.store` records `time.time()`; this column is a
261
+ # `timestamptz`. Same key, two types, is how a consumer that works on one backend breaks on
262
+ # the other β€” the exact class this module's interface parity exists to prevent.
263
+ at = stamp.timestamp() if hasattr(stamp, 'timestamp') else None
264
+ return {'rev': rev, 'updated_at': at, 'token': f'pg:{rev}'}
265
+
266
+
267
  def flush(name=None, timeout=30.0):
268
  """A no-op that returns True: every write above is already committed when it returns. Kept in
269
  the interface because QA gates and shutdown hooks call it and must not branch on the backend."""
 
337
  def update(self, name, fn, flush='sync'):
338
  return update(name, fn, flush=flush, tenant_slug=self.tenant_slug)
339
 
340
+ def revision(self, name):
341
+ return revision(name, tenant_slug=self.tenant_slug)
342
+
343
  def upload_bytes(self, path_in_repo, data, message=None):
344
  return upload_bytes(path_in_repo, data, message=message, tenant_slug=self.tenant_slug)
345
 
platform/core/user_tables.py CHANGED
@@ -165,7 +165,12 @@ MAX_JSON_CELL = 32 * 1024 * 1024
165
 
166
  #: Where a profile handle points. A CLOSED vocabulary, for the reason every other closed enum
167
  #: here is closed: a source nobody wrote a reader for renders as a column that promises a link.
168
- PROFILE_SOURCES = ('instagram',)
 
 
 
 
 
169
 
170
  #: Hosts whose `/<handle>/` path IS an Instagram profile. `www.` is stripped before the lookup.
171
  _IG_HOSTS = ('instagram.com', 'instagr.am')
@@ -179,6 +184,55 @@ _IG_RESERVED = frozenset({'p', 'reel', 'reels', 'tv', 'stories', 'explore', 'acc
179
  #: Instagram's own handle rule: 1–30 of letters, digits, period, underscore.
180
  _IG_HANDLE_RE = re.compile(r'^[A-Za-z0-9._]{1,30}$')
181
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
182
  #: The C1 preset keys a profile field OWNS β€” the cells R6 clears when its handle is blanked.
183
  #:
184
  #: MIRRORED from the engine's C1 set as local literals, the same discipline (and for the same
@@ -227,17 +281,24 @@ def _clean_profile(raw):
227
  def normalize_profile(value, source='instagram'):
228
  """A typed profile cell β†’ `(handle, ok)`. THE cell validator the flag promises (C3).
229
 
230
- Accepts a bare handle (`name`), an at-handle (`@name`) or an Instagram profile URL in any of
231
- the forms a person actually pastes (`https://www.instagram.com/name/?hl=en`,
232
- `instagram.com/name`). Returns the BARE HANDLE β€” the URL form is derived for display, so the
233
- stored truth has exactly one spelling and a filter on it cannot miss half the column.
 
 
 
 
 
 
234
 
235
  `('', True)` for a blank: clearing a profile cell is legal and is the whole of R6.
236
  `(None, False)` for anything else, and the caller refuses the write with a sentence β€” a
237
  value that is neither is not a handle we can enrich, and storing it would put the failure
238
  off until the automation runs and answers nothing.
239
  """
240
- if str(source or '').strip().lower() not in PROFILE_SOURCES:
 
241
  return (None, False)
242
  raw = str(value if value is not None else '').strip()
243
  if not raw:
@@ -259,16 +320,19 @@ def normalize_profile(value, source='instagram'):
259
  host = (parts.netloc or '').split('@')[-1].split(':')[0].strip().lower()
260
  if host.startswith('www.'):
261
  host = host[4:]
262
- if host in _IG_HOSTS:
263
  segs = [s for s in (parts.path or '').split('/') if s]
264
- if len(segs) != 1 or segs[0].lower() in _IG_RESERVED:
265
- # Two segments is a post/reel/highlight, zero is the site itself. Refused rather
 
 
 
266
  # than taking the first segment, which is what turns `/p/Cxyz` into handle `p`.
267
  return (None, False)
268
- cand = segs[0]
269
  elif host:
270
- return (None, False) # a URL, but not an Instagram one
271
- if not _IG_HANDLE_RE.match(cand) or cand.lower() in _IG_HOSTS:
272
  # The host check catches a bare `instagram.com` β€” it matches the handle charset, so
273
  # without this it would normalise to a "handle" that can only ever resolve to nothing.
274
  return (None, False)
@@ -277,11 +341,18 @@ def normalize_profile(value, source='instagram'):
277
 
278
  def profile_url(handle, source='instagram'):
279
  """The DERIVED display form of a stored handle (C3: *"the URL form is derived for display"*).
280
- Derived and never stored, so the two spellings cannot drift apart."""
 
 
 
 
 
 
281
  h = str(handle or '').strip().lstrip('@')
282
- if not h or str(source or '').strip().lower() not in PROFILE_SOURCES:
 
283
  return ''
284
- return f'https://www.instagram.com/{h}/'
285
 
286
 
287
  def _profile_of(fields, exclude=None):
@@ -355,6 +426,54 @@ FORMAT_TZ = ('local', 'utc')
355
  FORMAT_MAX_DECIMALS = 4
356
 
357
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
358
  def _clean_format(raw):
359
  """One `format` bag β†’ the stored shape, or None.
360
 
@@ -489,10 +608,12 @@ def clean_fields(raw):
489
  if entry is None:
490
  seen.discard(key)
491
  continue
492
- # `agg` decides whether the grid's totals row SUMS the column. A rollup that declares it
493
- # through one door and not the other totals differently depending on who made it.
494
- if f.get('agg') in {'sum'}:
495
- entry['agg'] = 'sum'
 
 
496
  out.append(entry)
497
  return out or None
498
 
@@ -702,6 +823,72 @@ def add_row(table_key, values=None, username=None, st=None, rid=None):
702
  return rid
703
 
704
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
705
  # β›” `upsert_rows` USED TO LIVE HERE, AND DELETING IT IS THE FIX (DEBT D-6, wave 20).
706
  #
707
  # There were TWO bulk-upsert implementations β€” this one and `automation_engine.upsert_rows` β€”
@@ -1150,6 +1337,57 @@ def _clean_field(raw, previous=None):
1150
  opts = [' '.join(str(o).split())[:60] for o in (opts_raw or []) if str(o).strip()][:50]
1151
  if opts:
1152
  out['options'] = opts
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1153
  role = str(raw.get('editRole') or prev.get('editRole') or 'admins').strip().lower()
1154
  out['editRole'] = role if role in FIELD_EDIT_ROLES else 'admins'
1155
  if prev.get('default') is True or raw.get('default') is True:
@@ -1182,8 +1420,19 @@ def _clean_field(raw, previous=None):
1182
  # which found `agg` instead.
1183
  # ⚠ Sticky across a patch for the same reason as `default` and `pinned`: a client PATCH that
1184
  # omits the key must not un-total a column as a side effect of renaming its header.
1185
- if str(raw.get('agg') or prev.get('agg') or '').strip() == 'sum':
1186
- out['agg'] = 'sum'
 
 
 
 
 
 
 
 
 
 
 
1187
  # An automation column carries the binding the engine reads; it is preserved across a patch
1188
  # rather than re-declared, because the automation editor owns it and this route does not.
1189
  auto = raw.get('automation') if 'automation' in raw else prev.get('automation')
 
165
 
166
  #: Where a profile handle points. A CLOSED vocabulary, for the reason every other closed enum
167
  #: here is closed: a source nobody wrote a reader for renders as a column that promises a link.
168
+ #:
169
+ #: ⭐ WAVE-29 CONTRACT C2 (owner R1/R2, 2026-08-11): `tiktok` joins it, so a `ut_tt_*` row can
170
+ #: carry a profile flag the enrich action resolves. **A source is not a NAME, it is three rules**
171
+ #: (below) β€” the vocabulary and the rules move together, because adding the word alone would
172
+ #: accept a TikTok handle and then hand it an `instagram.com` link from `profile_url`.
173
+ PROFILE_SOURCES = ('instagram', 'tiktok')
174
 
175
  #: Hosts whose `/<handle>/` path IS an Instagram profile. `www.` is stripped before the lookup.
176
  _IG_HOSTS = ('instagram.com', 'instagr.am')
 
184
  #: Instagram's own handle rule: 1–30 of letters, digits, period, underscore.
185
  _IG_HANDLE_RE = re.compile(r'^[A-Za-z0-9._]{1,30}$')
186
 
187
+ #: TikTok's profile hosts. β›” `vm.tiktok.com` is deliberately ABSENT: those are short links that
188
+ #: usually resolve to a VIDEO, and accepting one would store a "handle" (the opaque code) that can
189
+ #: never enrich β€” the same failure `_IG_RESERVED` exists to prevent, one layer earlier.
190
+ _TT_HOSTS = ('tiktok.com', 'm.tiktok.com')
191
+
192
+ #: TikTok's non-handle path segments. `tiktok.com/@user/video/123` is already refused by the
193
+ #: one-segment rule; these are the ONE-segment paths that are still not people.
194
+ _TT_RESERVED = frozenset({'video', 'tag', 'music', 'discover', 'search', 'foryou', 'explore',
195
+ 'live', 'upload', 'about', 'legal', 'privacy', 'terms', 'effect',
196
+ 'business', 'ads', 'node', 'login', 'signup'})
197
+
198
+ #: TikTok's own handle rule: 2–24 of letters, digits, period, underscore. ⚠ NOT Instagram's β€”
199
+ #: the charset matches but the bounds do not, and a shared regex would accept a 30-character
200
+ #: TikTok "handle" that the vendor answers nothing for.
201
+ _TT_HANDLE_RE = re.compile(r'^[A-Za-z0-9._]{2,24}$')
202
+
203
+ #: ⭐ C2 β€” the per-source rules, ONE table, so `PROFILE_SOURCES` cannot grow a member that no
204
+ #: normaliser knows. Every function below reads THIS rather than branching on the word: a source
205
+ #: with no entry refuses at the door instead of silently taking Instagram's rules and Instagram's
206
+ #: URL, which is what "add the word and ship" would have produced.
207
+ #:
208
+ #: `at_handle` = the profile path wears a leading `@` (TikTok's `/@name`; Instagram's `/name`).
209
+ #: It is stripped before validation and re-added by `profile_url`, so the STORED truth is the bare
210
+ #: handle in both families and a filter on the column cannot miss half of it.
211
+ _PROFILE_RULES = {
212
+ 'instagram': {
213
+ 'hosts': _IG_HOSTS,
214
+ 'reserved': _IG_RESERVED,
215
+ 'handle': _IG_HANDLE_RE,
216
+ 'at_handle': False,
217
+ 'url': 'https://www.instagram.com/{handle}/',
218
+ },
219
+ 'tiktok': {
220
+ 'hosts': _TT_HOSTS,
221
+ 'reserved': _TT_RESERVED,
222
+ 'handle': _TT_HANDLE_RE,
223
+ 'at_handle': True,
224
+ 'url': 'https://www.tiktok.com/@{handle}',
225
+ },
226
+ }
227
+
228
+
229
+ def _profile_rules(source):
230
+ """The rule bag for a source, or None β€” the ONE resolution of "is this source real"."""
231
+ key = str(source or '').strip().lower()
232
+ if key not in PROFILE_SOURCES:
233
+ return None
234
+ return _PROFILE_RULES.get(key)
235
+
236
  #: The C1 preset keys a profile field OWNS β€” the cells R6 clears when its handle is blanked.
237
  #:
238
  #: MIRRORED from the engine's C1 set as local literals, the same discipline (and for the same
 
281
  def normalize_profile(value, source='instagram'):
282
  """A typed profile cell β†’ `(handle, ok)`. THE cell validator the flag promises (C3).
283
 
284
+ Accepts a bare handle (`name`), an at-handle (`@name`) or a profile URL of THIS SOURCE in any
285
+ of the forms a person actually pastes (`https://www.instagram.com/name/?hl=en`,
286
+ `instagram.com/name`, `https://www.tiktok.com/@name`). Returns the BARE HANDLE β€” the URL form
287
+ is derived for display, so the stored truth has exactly one spelling and a filter on it cannot
288
+ miss half the column.
289
+
290
+ β›” C2: the host, the reserved segments and the handle rule all come from `_PROFILE_RULES[source]`.
291
+ A TikTok URL pasted into an Instagram-flagged column is REFUSED, and vice versa β€” a cell that
292
+ names the wrong network is not a handle this row's automation can enrich, and quietly accepting
293
+ it would defer the failure to a run that then answers nothing.
294
 
295
  `('', True)` for a blank: clearing a profile cell is legal and is the whole of R6.
296
  `(None, False)` for anything else, and the caller refuses the write with a sentence β€” a
297
  value that is neither is not a handle we can enrich, and storing it would put the failure
298
  off until the automation runs and answers nothing.
299
  """
300
+ rules = _profile_rules(source)
301
+ if rules is None:
302
  return (None, False)
303
  raw = str(value if value is not None else '').strip()
304
  if not raw:
 
320
  host = (parts.netloc or '').split('@')[-1].split(':')[0].strip().lower()
321
  if host.startswith('www.'):
322
  host = host[4:]
323
+ if host in rules['hosts']:
324
  segs = [s for s in (parts.path or '').split('/') if s]
325
+ # C2: TikTok's profile path is `/@name`; Instagram's is `/name`. The `@` is stripped
326
+ # here and re-added by `profile_url`, so both families STORE a bare handle.
327
+ first = segs[0].lstrip('@') if segs else ''
328
+ if len(segs) != 1 or not first or first.lower() in rules['reserved']:
329
+ # Two segments is a post/reel/video, zero is the site itself. Refused rather
330
  # than taking the first segment, which is what turns `/p/Cxyz` into handle `p`.
331
  return (None, False)
332
+ cand = first
333
  elif host:
334
+ return (None, False) # a URL, but not one of THIS source's
335
+ if not rules['handle'].match(cand) or cand.lower() in rules['hosts']:
336
  # The host check catches a bare `instagram.com` β€” it matches the handle charset, so
337
  # without this it would normalise to a "handle" that can only ever resolve to nothing.
338
  return (None, False)
 
341
 
342
  def profile_url(handle, source='instagram'):
343
  """The DERIVED display form of a stored handle (C3: *"the URL form is derived for display"*).
344
+ Derived and never stored, so the two spellings cannot drift apart.
345
+
346
+ β›” C2 β€” the template comes from the SOURCE's own rules. This function used to hardcode
347
+ `instagram.com` while its guard merely checked membership of `PROFILE_SOURCES`, so the moment
348
+ that tuple grew a second member it would have handed every TikTok handle an Instagram link β€”
349
+ a guard that passes and a body that lies ([[hardcoded-fallback-not-hardcoded-key]]).
350
+ """
351
  h = str(handle or '').strip().lstrip('@')
352
+ rules = _profile_rules(source)
353
+ if not h or rules is None:
354
  return ''
355
+ return rules['url'].format(handle=h)
356
 
357
 
358
  def _profile_of(fields, exclude=None):
 
426
  FORMAT_MAX_DECIMALS = 4
427
 
428
 
429
+ #: ⭐ WAVE-29 CONTRACT C7 β€” the COLUMN-SUMMARY vocabulary a field's `agg` may take.
430
+ #:
431
+ #: MIRRORED from `aios_grid.FIELD_AGGS` (session C publishes it) and from the client's
432
+ #: `aggregations.FIELD_AGGS`, as a local literal for the reason `METRIC_MEASURES` and
433
+ #: `PROFILE_PRESET_KEYS` are local literals here: `core/` must stay importable without the layers
434
+ #: above it. Three copies, one law, held in step by C's parity gate rather than by an import.
435
+ #:
436
+ #: β›” NOT `CHART_AGGS` (which spells it `avg` and gatekeeps STORED chart values with live data)
437
+ #: and NOT `ROLLUP_FNS` (16 fold names, overlapping but not the same list). Merging any two of the
438
+ #: three silently turns live stored charts into sums.
439
+ FIELD_AGGS = ('sum', 'average', 'median', 'min', 'max', 'count')
440
+
441
+ #: A choice colour, as the client's editor spells one. `#RRGGBB`, upper-cased on the way in so a
442
+ #: stored value has exactly ONE spelling and two fields cannot disagree about `#ebf6ef`.
443
+ _OPTION_COLOR_RE = re.compile(r'#[0-9A-F]{6}')
444
+
445
+
446
+ def _clean_option_colors(raw, options):
447
+ """`{option label β†’ #RRGGBB}`, capped to the field's own option vocabulary (wave-29 C1).
448
+
449
+ β›” MIRRORED from `aios_grid._clean_option_colors` as a LOCAL function rather than imported, for
450
+ the reason `METRIC_MEASURES` and `PROFILE_PRESET_KEYS` are local literals here: `core/` must
451
+ stay importable without the layers above it, and `aios_grid` sits above this module. The pair
452
+ is held in step by a gate leg, never by an import.
453
+
454
+ ⚠ THE CAP IS THE POINT, not tidiness: colours are keyed by LABEL, so a renamed or deleted
455
+ option would otherwise leave a colour behind that nothing renders and no editor can reach β€”
456
+ and on the next rename that orphan could re-attach to a different option with the same name.
457
+ Case-insensitive on the way in, canonical on the way out, so `Done` and `done` cannot both
458
+ claim the same option.
459
+ """
460
+ if not isinstance(raw, dict):
461
+ return {}
462
+ supplied = {}
463
+ for label, color in raw.items():
464
+ if not isinstance(label, str) or not isinstance(color, str):
465
+ continue
466
+ clean = color.strip().upper()
467
+ if _OPTION_COLOR_RE.fullmatch(clean):
468
+ supplied[label.strip().lower()] = clean
469
+ out = {}
470
+ for option in options or []:
471
+ color = supplied.get(str(option).strip().lower())
472
+ if color:
473
+ out[str(option)] = color
474
+ return out
475
+
476
+
477
  def _clean_format(raw):
478
  """One `format` bag β†’ the stored shape, or None.
479
 
 
608
  if entry is None:
609
  seen.discard(key)
610
  continue
611
+ # `agg` decides HOW the grid's totals row summarises the column. A rollup that declares it
612
+ # through one door and not the other summarises differently depending on who made it.
613
+ # ⭐ WAVE-29 C7: the vocabulary is `FIELD_AGGS`, not the single word `sum` β€” see its note.
614
+ agg_in = str(f.get('agg') or '').strip()
615
+ if agg_in in FIELD_AGGS:
616
+ entry['agg'] = agg_in
617
  out.append(entry)
618
  return out or None
619
 
 
823
  return rid
824
 
825
 
826
+ def add_rows(table_key, rows_in, username=None, st=None):
827
+ """⭐⭐ WAVE-29 T25 (owner item 6) β€” APPEND MANY ROWS IN ONE STORE WRITE. Returns the list of
828
+ new row ids, or None if the table refuses records at all.
829
+
830
+ β›” WHY THIS EXISTS RATHER THAN A LOOP OVER `add_row`. Every `add_row` is a read-modify-write of
831
+ the WHOLE table document plus a row event; importing a 2,000-row spreadsheet that way is 2,000
832
+ full-document copies under one lock, which is the same shape as the 1.4 s-per-bucket problem
833
+ item 20 exists to avoid β€” on the one uvicorn process this product runs. One `update()` writes
834
+ them all.
835
+
836
+ β›” AND WHY NOT `automation_engine.upsert_rows`, which this module's own note (below) says to
837
+ reuse: that function is UPSERT-BY-KEY shaped, and v1 of the import door is deliberately
838
+ APPEND-ONLY (no key to merge on, no silent overwrite of a row somebody edited). It also lives
839
+ in the API layer, and `core/` may not import upward. When the import door grows an "update
840
+ matching rows" mode, the engine's is the one to lift β€” the note stands, it just is not this.
841
+
842
+ ⚠ THE CAP IS CHECKED AGAINST THE WHOLE BATCH, not per row: a partial import that stops at
843
+ `MAX_ROWS` leaves the user reconciling a spreadsheet against a table, which is exactly what
844
+ the refusal-with-a-sentence exists to prevent. Nothing is written if the batch does not fit.
845
+
846
+ ⚠ Ids continue the table's own sequence, and a PROFILE column validates every cell exactly as
847
+ `add_row` does β€” a row born with an unusable handle is a row the enrich action can never
848
+ answer, and the failure would otherwise surface as an automation quietly returning nothing.
849
+ """
850
+ if not is_user_table(table_key, st) or not records_mutable(table_key, st):
851
+ return None
852
+ batch = [dict(r) for r in (rows_in or []) if isinstance(r, dict)]
853
+ if not batch:
854
+ return []
855
+ defn = get(table_key, st) or {}
856
+ rows = defn.get('rows') or {}
857
+ if len(rows) + len(batch) > MAX_ROWS:
858
+ return None
859
+ valid = {f['key'] for f in (defn.get('fields') or [])}
860
+ pf = _profile_of(defn.get('fields') or [])
861
+ next_id = max((int(r) for r in rows if str(r).isdigit()), default=0)
862
+ made = []
863
+ for values in batch:
864
+ clean = {k: str(v) for k, v in values.items() if k in valid}
865
+ if pf and pf['key'] in clean:
866
+ handle, ok = normalize_profile(clean[pf['key']], pf['profile'].get('source'))
867
+ if not ok:
868
+ return None # atomic: one bad handle refuses the FILE
869
+ clean[pf['key']] = handle
870
+ next_id += 1
871
+ made.append((str(next_id), clean))
872
+
873
+ def _add(cur):
874
+ t = cur.get(str(table_key))
875
+ if t is not None:
876
+ bucket = t.setdefault('rows', {})
877
+ for rid, clean in made:
878
+ bucket[rid] = clean
879
+ return cur
880
+
881
+ _st(st).update(STORE_KEY, _add, flush='sync')
882
+ # ⚠ ONE EVENT PER ROW, deliberately: `record_created` is a trigger substrate, and an import of
883
+ # 500 rows genuinely IS 500 created records. The engine's own flood hold is what decides
884
+ # whether that runs an automation 500 times β€” a decision that belongs there, not to a writer
885
+ # that quietly emits less than it did.
886
+ for rid, _clean in made:
887
+ emit_row_event({'type': 'record_created', 'table': str(table_key), 'rowId': rid,
888
+ 'st': _st(st), 'user': str(username or '')})
889
+ return [rid for rid, _ in made]
890
+
891
+
892
  # β›” `upsert_rows` USED TO LIVE HERE, AND DELETING IT IS THE FIX (DEBT D-6, wave 20).
893
  #
894
  # There were TWO bulk-upsert implementations β€” this one and `automation_engine.upsert_rows` β€”
 
1337
  opts = [' '.join(str(o).split())[:60] for o in (opts_raw or []) if str(o).strip()][:50]
1338
  if opts:
1339
  out['options'] = opts
1340
+ # ⭐⭐ WAVE-29 CONTRACT C1 (owner item 13) β€” **THE OPTION COLOURS, WHICH THIS DOOR DROPPED.**
1341
+ #
1342
+ # The client has carried `optionColors`/`colorCodeOptions` since wave 14 (`types.ts`, the
1343
+ # `BRAND_SWATCHES` editor, `cells.optionTint`, the kanban card) and `aios_grid._clean_field`
1344
+ # keeps both β€” but THIS validator, the one every `ut_*` create and patch goes through, had
1345
+ # zero occurrences of either key. So the owner picked a colour on a user database, the pane
1346
+ # saved, and the colour was gone on the next read: the same crossed-validator shape as item 2a,
1347
+ # in a different pair of doors. `grid_events._FIELD_ECHO_PROPS` already carried both, so the
1348
+ # echo wire was plumbed for a value nothing stored.
1349
+ #
1350
+ # β›” SIBLING KEYS, and `options` IS NOT RESHAPED. Every consumer treats options as `string[]`
1351
+ # (this function flattens each to a bare `str` twelve lines up); folding colour into the option
1352
+ # entries would be a wire change across the grid, the kanban, the editor and the filter panel.
1353
+ #
1354
+ # β›” OMIT-WHEN-ABSENT, exactly like `format`/`metric`/`link`, because `verify_api.py` and
1355
+ # `verify_automation.py` assert `_clean_field(f) == f` over every engine-seeded field list β€”
1356
+ # a branch that emitted `optionColors: {}` would redden both gates for every preset column in
1357
+ # the product. ([[default-must-pass-its-own-guard]])
1358
+ #
1359
+ # ⚠ INHERITED ACROSS A PATCH, for `agg`'s reason: a PATCH that sends only a label must not
1360
+ # silently strip the colours somebody chose, which is precisely how a money column stopped
1361
+ # totalling.
1362
+ #
1363
+ # ⚠ A HEX IS VALIDATED; BRAND MEMBERSHIP IS NOT, and that is deliberate. `_clean_option_colors`
1364
+ # (`aios_grid.py:200`) β€” the sibling this mirrors β€” accepts any `#RRGGBB`, and the client
1365
+ # renders a stored colour through `choiceColors.brandedTint`, which maps it to its NEAREST
1366
+ # brand swatch at DISPLAY time while leaving what is stored byte-stable. Refusing a non-brand
1367
+ # hex here would refuse values the other validator accepts on the same UI, and would break a
1368
+ # column that moved between the two.
1369
+ if ftype in ('select', 'multiselect'):
1370
+ colors_raw = (raw.get('optionColors') if 'optionColors' in raw
1371
+ else prev.get('optionColors'))
1372
+ colors = _clean_option_colors(colors_raw, out.get('options') or [])
1373
+ if colors:
1374
+ out['optionColors'] = colors
1375
+ color_code = (raw.get('colorCodeOptions') if 'colorCodeOptions' in raw
1376
+ else prev.get('colorCodeOptions'))
1377
+ if isinstance(color_code, bool):
1378
+ out['colorCodeOptions'] = color_code
1379
+ # ⭐ WAVE-29 T22's own repair: a `rating` column's star count. Grid-created columns on a `ut_*`
1380
+ # database now come through this door rather than the per-user overlay, and this validator had
1381
+ # no `max` β€” so a 3-star or 10-star column silently became 5-star on the way in. Bounded rather
1382
+ # than refused, mirroring `aios_grid._clean_rating_max`: the field still holds its 1..max
1383
+ # integers whatever the number was, so an unusable value is a default and never a lost column.
1384
+ if ftype == 'rating':
1385
+ max_raw = raw.get('max') if 'max' in raw else prev.get('max')
1386
+ if max_raw is not None:
1387
+ try:
1388
+ out['max'] = max(2, min(int(max_raw), 10))
1389
+ except (TypeError, ValueError):
1390
+ pass
1391
  role = str(raw.get('editRole') or prev.get('editRole') or 'admins').strip().lower()
1392
  out['editRole'] = role if role in FIELD_EDIT_ROLES else 'admins'
1393
  if prev.get('default') is True or raw.get('default') is True:
 
1420
  # which found `agg` instead.
1421
  # ⚠ Sticky across a patch for the same reason as `default` and `pinned`: a client PATCH that
1422
  # omits the key must not un-total a column as a side effect of renaming its header.
1423
+ # ⭐ WAVE-29 C7 β€” the vocabulary widened from the single word `sum` to `FIELD_AGGS`. The
1424
+ # STICKINESS is unchanged and now applies to every name: a PATCH that omits `agg` keeps
1425
+ # whatever the column had, because dropping it is how a money column silently stopped
1426
+ # totalling. β›” An unknown name is DROPPED rather than stored β€” a summary nothing can compute
1427
+ # would render blank under a picker that says otherwise.
1428
+ # ⚠ `'agg' in raw`, not `raw.get('agg') or …` β€” the same idiom `format` and `description` use
1429
+ # two screens up, and it is what makes the difference between OMITTING the key (keep what is
1430
+ # stored: the wave-28 stickiness that stops a rename un-totalling a money column) and sending
1431
+ # it EMPTY (clear the summary, which the picker's "None" row has to be able to do). Written
1432
+ # the loose way, "None" would have been a no-op with the menu cheerfully showing the change.
1433
+ agg_name = str((raw.get('agg') if 'agg' in raw else prev.get('agg')) or '').strip()
1434
+ if agg_name in FIELD_AGGS:
1435
+ out['agg'] = agg_name
1436
  # An automation column carries the binding the engine reads; it is preserved across a patch
1437
  # rather than re-declared, because the automation editor owns it and this route does not.
1438
  auto = raw.get('automation') if 'automation' in raw else prev.get('automation')
platform/harness/datastore.py CHANGED
@@ -170,9 +170,20 @@ ENTITIES = {
170
  # table itself cannot tell them apart. `salesman_as_agent` ("convert salesman into agent")
171
  # marks agents who came from staff; the owner ruling on whether those count as agents is
172
  # OUTSTANDING, so both flags are synced and neither reading is baked in.
 
 
 
 
 
 
 
 
173
  "fields": ["name", "team_id", "city", "state_id", "country_id", "active",
174
- "agent", "salesman_as_agent", "write_date"],
175
- "backfill_fields": ["agent", "salesman_as_agent"], # added 2026-07-28
 
 
 
176
  # m2m fields land as <base>_id (the FIRST linked id β€” the Customers-module convention:
177
  # a customer's assigned agent is agent_ids[0], ~one per customer, MECE) + <field> as a
178
  # JSON list of ALL ids. Declared explicitly: a 2-element m2m read would otherwise be
@@ -256,6 +267,16 @@ BATCH = 2000
256
  # from "unknown".
257
  BOOL_FIELDS = ("active", "agent", "salesman_as_agent", "settled", "commission_free")
258
 
 
 
 
 
 
 
 
 
 
 
259
 
260
  import threading as _thr
261
 
@@ -444,6 +465,8 @@ def _cols(spec):
444
  cols += [f"{base}_id BIGINT", f"{base}_name VARCHAR"]
445
  elif f in BOOL_FIELDS:
446
  cols.append(f"{f} BOOLEAN")
 
 
447
  elif f in ("amount_untaxed", "amount_untaxed_signed", "amount_residual_signed",
448
  "price_subtotal", "margin", "purchase_price", "product_uom_qty",
449
  "standard_price", "debit", "credit", "balance", "amount"):
 
170
  # table itself cannot tell them apart. `salesman_as_agent` ("convert salesman into agent")
171
  # marks agents who came from staff; the owner ruling on whether those count as agents is
172
  # OUTSTANDING, so both flags are synced and neither reading is baked in.
173
+ # ⭐ WAVE 29 (W29-T54, amendment A4). `customer_rank` is the ONLY predicate that
174
+ # distinguishes "a partner Odoo has TRANSACTED with" (today's population, 2,465) from
175
+ # "a customer" (3,614 with `rank>0 active`) β€” a 1,149-partner drop, the same join-drop
176
+ # class as item 22's SKU pool. It cannot be derived from the document tables, because
177
+ # the missing partners are precisely the ones with no document.
178
+ # β›” It is synced HERE rather than read from live Odoo because `read_customers` also runs
179
+ # at BOOT off a hydrated snapshot, where Odoo may be unreachable β€” sourcing it live would
180
+ # make the population "whatever source answered this time", changing size with the network.
181
  "fields": ["name", "team_id", "city", "state_id", "country_id", "active",
182
+ "agent", "salesman_as_agent", "customer_rank", "write_date"],
183
+ # `backfill_fields` carries it too, so mirrors that already exist pick it up on the next
184
+ # sync_all() instead of needing a reseed.
185
+ "backfill_fields": ["agent", "salesman_as_agent", # added 2026-07-28
186
+ "customer_rank"], # added 2026-08-11 (W29-T54)
187
  # m2m fields land as <base>_id (the FIRST linked id β€” the Customers-module convention:
188
  # a customer's assigned agent is agent_ids[0], ~one per customer, MECE) + <field> as a
189
  # JSON list of ALL ids. Declared explicitly: a 2-element m2m read would otherwise be
 
267
  # from "unknown".
268
  BOOL_FIELDS = ("active", "agent", "salesman_as_agent", "settled", "commission_free")
269
 
270
+ # ⭐ WAVE 29 β€” fields that are genuinely INTEGER COUNTS, and this list exists because its absence
271
+ # shipped a silent defect within minutes of `customer_rank` being added to the res_partner spec.
272
+ # `_cols` types anything it does not recognise as VARCHAR, so `customer_rank` landed as text, the
273
+ # mirror populated correctly, every row looked right β€” and `odoo_relational`'s own predicate
274
+ # `customer_rank > 0` died with `Binder Error: Cannot compare values of type VARCHAR and type
275
+ # INTEGER_LITERAL`. β›” THE COLUMN WAS PRESENT AND THE DATA WAS CORRECT; only its TYPE was wrong,
276
+ # which is why "is the field in the mirror?" answered yes and the feature still could not run.
277
+ # β‡’ A new numeric field belongs HERE, exactly as a new boolean belongs in BOOL_FIELDS above.
278
+ INT_FIELDS = ("customer_rank", "supplier_rank")
279
+
280
 
281
  import threading as _thr
282
 
 
465
  cols += [f"{base}_id BIGINT", f"{base}_name VARCHAR"]
466
  elif f in BOOL_FIELDS:
467
  cols.append(f"{f} BOOLEAN")
468
+ elif f in INT_FIELDS:
469
+ cols.append(f"{f} BIGINT")
470
  elif f in ("amount_untaxed", "amount_untaxed_signed", "amount_residual_signed",
471
  "price_subtotal", "margin", "purchase_price", "product_uom_qty",
472
  "standard_price", "debit", "credit", "balance", "amount"):
platform/modules/product_data.py CHANGED
@@ -30,11 +30,32 @@ template and this deliberately mirrors its signature and its row shape.
30
  Margin % comes from `modules/pricing.table`, which is a heavier build (channel-rate cost
31
  allocation) and is left for the wave that needs it. `validate()` reconciles what SHIPS; it
32
  does not pretend to cover columns that are absent.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
33
  """
34
  import json
35
  import zlib
36
  from pathlib import Path
37
 
 
38
  import core.periods as P
39
  import core.table_store as table_store
40
  import modules.products as products
@@ -155,31 +176,66 @@ def _inventory_by_code(t):
155
  return {}
156
 
157
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
158
  def pool(team_id=None, t=None):
159
- """One row per SKU across the scoped book β€” the PRODUCT analogue of `customer_data.pool`.
 
 
 
 
160
 
161
  `team_id` shapes the revenue columns exactly as it does for customers (`products.directory`
162
  passes it into `_sku_rev`), which is why `core.perm_scope.derive_pool_scope` must keep
163
- driving it rather than a post-filter deciding the BU.
 
164
  """
165
  t = t or P.today()
166
  consolidated = team_id is None
167
  inv = _inventory_by_code(t) if consolidated else {}
168
  sup = supplier_master()
 
 
 
 
 
 
169
 
170
  rows = []
171
- for r in products.directory(t=t, team_id=team_id):
172
- code = r["code"]
173
  row = {
174
  "pid": sku_pid(code),
175
  "code": code,
176
- "product": r.get("product") or code,
177
- "category": r.get("category") or "(uncategorized)",
178
- "rev_ytd": r.get("rev_ytd", 0.0),
179
- "rev_ly": r.get("rev_ly", 0.0),
180
- "yoy_pct": r.get("yoy_pct"),
181
- "qty_ytd": r.get("qty_ytd", 0.0),
182
- "orders_ytd": r.get("orders_ytd", 0),
 
 
 
 
 
 
183
  }
184
  # Wave 17 R3 β€” the supplier master, on every pull (it is catalogue data, not stock).
185
  s = sup.get(code) or {}
@@ -227,6 +283,10 @@ def pool(team_id=None, t=None):
227
  row["buy_now"] = None
228
  rows.append(row)
229
 
 
 
 
 
230
  rows.sort(key=lambda r: -(r["rev_ytd"] or 0.0))
231
  _assert_no_pid_collision(rows)
232
  return rows
@@ -277,20 +337,68 @@ def validate(team_id=None, t=None):
277
  """Reconcile what SHIPS to an independent aggregate β€” the platform's own rule that a number
278
  which does not tie to Odoo does not ship.
279
 
280
- The check is deliberately narrow and says so: Ξ£ per-SKU YTD revenue must equal the SKU
281
- module's own YTD total over the same scope. It does NOT cover the inventory columns (they are
282
- a different module's reconciliation, and they are absent on a scoped pull anyway).
 
 
 
 
 
 
 
 
 
 
 
 
 
283
  """
284
  t = t or P.today()
285
  rows = pool(team_id=team_id, t=t)
286
- ours = round(sum(r["rev_ytd"] or 0.0 for r in rows), 2)
287
- yf, yt = P.ytd(t)
288
- theirs = round(sum(v.get("rev", 0.0)
289
- for v in (products._sku_rev(yf, yt, team_id) or {}).values()), 2)
 
290
  checks = [{
291
- "check": "Ξ£ per-SKU YTD revenue == modules.products._sku_rev over the same window",
292
- "ours": ours, "theirs": theirs, "ok": abs(ours - theirs) < 0.01,
 
293
  }]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
294
  # WAVE 17 R3 β€” the BUY SIGNAL must be a total, exact partition of the catalogue, and every
295
  # member of it must be re-derivable from the two columns beside it. A signal somebody buys
296
  # stock on cannot be "mostly right": the failure that matters is a row that says OK because
 
30
  Margin % comes from `modules/pricing.table`, which is a heavier build (channel-rate cost
31
  allocation) and is left for the wave that needs it. `validate()` reconciles what SHIPS; it
32
  does not pretend to cover columns that are absent.
33
+
34
+ 4. **THE POOL IS CATALOGUE-FIRST, WITH REVENUE LEFT-JOINED** (wave 29, owner item 22 / R12,
35
+ 2026-08-11). It was `for r in products.directory(...)` β€” and `directory()`'s row set IS the
36
+ union of two revenue read-groups, so **a SKU that never sold could not exist** and the grid
37
+ showed **2,717** of **5,875** active products. Three things that will be re-derived otherwise:
38
+
39
+ Β· β›” THE CAUSE IS A JOIN, NOT A LIMIT. No row cap exists on this path. Removing the date
40
+ window from `directory()` would ALSO be wrong twice: it breaks four SKU-health metrics
41
+ that legitimately want a sales window, and it lands at 3,327 (all-time-sold), because
42
+ ~2,550 active SKUs have never sold in wholesale scope at all.
43
+ · ⭐ REVENUE ON A NEVER-SOLD ROW IS **BLANK, NOT $0** (R12). A row that appears in the
44
+ revenue universe carries measured numbers INCLUDING a real 0.0 β€” it sold last year and
45
+ not this one, and that zero is a measurement. A row that appears in NO revenue read
46
+ carries `None`, which the wire keeps (`aios_grid._round` passes None through) and the
47
+ client renders as an empty cell. Blank is an admission; zero is a measurement.
48
+ · ⚠ A BU-SCOPED CALLER NOW SEES THE WHOLE CATALOGUE, with ITS OWN revenue and blanks where
49
+ that BU never sold. That is not decision 2's mixed-scope defect: the catalogue is the ROW
50
+ UNIVERSE, not a company-wide VALUE sitting beside a BU-shaped one. `product.product`
51
+ carries no team, so a catalogue cannot be BU-shaped at all β€” which is exactly why the two
52
+ sources are JOINED rather than merged.
53
  """
54
  import json
55
  import zlib
56
  from pathlib import Path
57
 
58
+ import core.odoo as O
59
  import core.periods as P
60
  import core.table_store as table_store
61
  import modules.products as products
 
176
  return {}
177
 
178
 
179
+ def _catalogue_by_code():
180
+ """`{code: {'product', 'category'}}` β€” the CATALOGUE universe this pool is built from.
181
+
182
+ β›” UNLIKE `_inventory_by_code`, THIS ONE RAISES, and the asymmetry is the whole point.
183
+ Inventory degrades to `{}` because a product table with blank stock columns beats one that
184
+ will not render. The CATALOGUE is not a column β€” it is the ROW SET. A catalogue read that
185
+ failed quietly would drop the grid straight back to the sold-only 2,717 with every gate
186
+ green and nothing on screen saying so, which is the defect this seam exists to end
187
+ ([[gate-can-report-green-on-nothing]]). `routes_products._pool_for` already turns the raise
188
+ into a 503 that names the cause, so the loud failure has somewhere honest to land.
189
+
190
+ It exists as a `pd`-level function rather than an inline `products.catalogue()` call for the
191
+ same reason `_inventory_by_code` does: it is the seam `verify_perm_scope`'s section H stubs
192
+ to build a pool without Odoo.
193
+ """
194
+ return products.catalogue()
195
+
196
+
197
  def pool(team_id=None, t=None):
198
+ """One row per ACTIVE product β€” the PRODUCT analogue of `customer_data.pool`.
199
+
200
+ CATALOGUE-FIRST, REVENUE LEFT-JOINED (R12 β€” see decision 4 in the module header). The row set
201
+ is `products.catalogue()`; `products.directory()` supplies the revenue columns for the SKUs
202
+ that sold in its window and contributes NO rows of its own.
203
 
204
  `team_id` shapes the revenue columns exactly as it does for customers (`products.directory`
205
  passes it into `_sku_rev`), which is why `core.perm_scope.derive_pool_scope` must keep
206
+ driving it rather than a post-filter deciding the BU. It does NOT shape the row set: a
207
+ catalogue has no team.
208
  """
209
  t = t or P.today()
210
  consolidated = team_id is None
211
  inv = _inventory_by_code(t) if consolidated else {}
212
  sup = supplier_master()
213
+ cat = _catalogue_by_code()
214
+ # The LEFT side of the join, indexed by the same code key. β›” A code here that the catalogue
215
+ # does not carry belongs to a product no ACTIVE record claims β€” archived, and R12 keeps those
216
+ # out. `validate()` asserts that of Odoo rather than assuming it, and reports the revenue
217
+ # that therefore sits outside the grid (MEASURED 2026-08-11: 3 codes, $0.00 YTD / $294.50 LY).
218
+ rev = {r["code"]: r for r in products.directory(t=t, team_id=team_id)}
219
 
220
  rows = []
221
+ for code, meta in cat.items():
222
+ r = rev.get(code)
223
  row = {
224
  "pid": sku_pid(code),
225
  "code": code,
226
+ # ⭐ ONE source for the name and the category, the CATALOGUE β€” not the sale line's
227
+ # m2o. For a re-SKUed code the line's name can be the ARCHIVED record's; the active
228
+ # record's `display_name` is the current truth, and it is the same string for every
229
+ # SKU that is not re-SKUed. `directory()` derives the category identically.
230
+ "product": meta.get("product") or code,
231
+ "category": meta.get("category") or "(uncategorized)",
232
+ # ⭐ R12 β€” BLANK, NEVER $0, on a SKU no revenue read ever saw. A row that IS in `rev`
233
+ # keeps its measured numbers including a real 0.0 (it sold last year, not this one).
234
+ "rev_ytd": r.get("rev_ytd", 0.0) if r else None,
235
+ "rev_ly": r.get("rev_ly", 0.0) if r else None,
236
+ "yoy_pct": r.get("yoy_pct") if r else None,
237
+ "qty_ytd": r.get("qty_ytd", 0.0) if r else None,
238
+ "orders_ytd": r.get("orders_ytd", 0) if r else None,
239
  }
240
  # Wave 17 R3 β€” the supplier master, on every pull (it is catalogue data, not stock).
241
  s = sup.get(code) or {}
 
283
  row["buy_now"] = None
284
  rows.append(row)
285
 
286
+ # `or 0.0` reads a BLANK as zero FOR SORTING ONLY β€” never for the cell. A never-sold SKU
287
+ # settles among the zero-revenue ones at the bottom, which is where it belongs; the stored
288
+ # value stays None so nothing downstream can mistake "we never saw a sale" for "we measured
289
+ # nothing sold".
290
  rows.sort(key=lambda r: -(r["rev_ytd"] or 0.0))
291
  _assert_no_pid_collision(rows)
292
  return rows
 
337
  """Reconcile what SHIPS to an independent aggregate β€” the platform's own rule that a number
338
  which does not tie to Odoo does not ship.
339
 
340
+ β›”β›” THE POPULATION LEG IS NEW, AND IT IS HERE BECAUSE THIS FUNCTION USED TO BE SELF-SEALING
341
+ (wave 29, contract C8). It reconciled Ξ£ per-SKU YTD revenue against `products._sku_rev` β€” the
342
+ same function `pool()` built its rows from. BOTH SIDES CAME FROM THE JOIN, so the oracle could
343
+ not see a missing row, and a grid holding 2,717 of 5,875 active products passed for a wave.
344
+ No gate anywhere asserted a pool row COUNT against an independent Odoo `search_count` either.
345
+ That is the leg below, and it is the control that would have caught it
346
+ ([[no-unverifiable-aggregates]]).
347
+
348
+ ⚠ The revenue leg was NOT deleted with it β€” it answers a different question ("did the join
349
+ lose money?") and is still the right shape for that one. What changed is that it now has to
350
+ account for revenue belonging to codes NO ACTIVE PRODUCT CARRIES, because R12 keeps archived
351
+ products out of the grid; the total is decomposed rather than compared loosely, so a growing
352
+ "outside the grid" figure shows up as a number rather than as slack in a tolerance.
353
+
354
+ Still deliberately NOT covered, and said rather than implied: the inventory columns are a
355
+ different module's reconciliation, and they are absent on a scoped pull anyway.
356
  """
357
  t = t or P.today()
358
  rows = pool(team_id=team_id, t=t)
359
+
360
+ # ⭐⭐ THE POPULATION, AGAINST AN ORACLE THAT CANNOT SEE OUR JOIN. A bare Odoo count of active
361
+ # products, asked fresh β€” not a `len()` over anything this module or `products.catalogue()`
362
+ # built. NC: drop one row from `pool()` and this goes red; that is the whole point of it.
363
+ n_active = products.catalogue_count()
364
  checks = [{
365
+ "check": "the pool holds one row per ACTIVE product (R12) β€” row count == an INDEPENDENT "
366
+ "Odoo search_count('product.product', active=True)",
367
+ "ours": len(rows), "theirs": n_active, "ok": len(rows) == n_active,
368
  }]
369
+
370
+ yf, yt = P.ytd(t)
371
+ sku_rev = products._sku_rev(yf, yt, team_id) or {}
372
+ in_pool = {r["code"] for r in rows}
373
+ outside = {c: v for c, v in sku_rev.items() if c not in in_pool}
374
+ ours = round(sum(r["rev_ytd"] or 0.0 for r in rows), 2)
375
+ theirs = round(sum(v.get("rev", 0.0) for v in sku_rev.values()), 2)
376
+ dropped = round(sum(v.get("rev", 0.0) for v in outside.values()), 2)
377
+ checks.append({
378
+ "check": "Ξ£ per-SKU YTD revenue in the grid + Ξ£ YTD revenue of codes no ACTIVE product "
379
+ "carries == modules.products._sku_rev over the same window",
380
+ "ours": round(ours + dropped, 2), "theirs": theirs,
381
+ "ok": abs((ours + dropped) - theirs) < 0.01,
382
+ "detail": {"in_the_grid": ours, "outside_the_grid": dropped,
383
+ "codes_outside": len(outside)},
384
+ })
385
+ # β›” AND THE EXCLUSION IS ASSERTED, NOT ASSUMED. "Everything I dropped was archived" is
386
+ # trivially true when checked against the dict that did the dropping β€” that is the
387
+ # self-sealing shape all over again. So it is asked of ODOO. A code here that a live ACTIVE
388
+ # product carries means `products.catalogue()` missed a row that has revenue, which is the
389
+ # 2,717 defect returning in a smaller costume.
390
+ # ⚠ `pid:N` keys are not `default_code`s and are skipped: an UNCODED active product is in the
391
+ # catalogue under its own `pid:N` key and therefore cannot be in `outside` at all.
392
+ coded_outside = sorted(c for c in outside if not str(c).startswith("pid:"))
393
+ still_active = (O.get_odoo().search_count(
394
+ 'product.product', [('active', '=', True), ('default_code', 'in', coded_outside)])
395
+ if coded_outside else 0)
396
+ checks.append({
397
+ "check": "every SKU with revenue but NO grid row is genuinely ARCHIVED (R12: archived "
398
+ "stay out) β€” asked of Odoo, never of the catalogue that did the dropping",
399
+ "ours": still_active, "theirs": 0, "ok": still_active == 0,
400
+ "detail": {"codes": coded_outside[:10], "n_codes": len(outside)},
401
+ })
402
  # WAVE 17 R3 β€” the BUY SIGNAL must be a total, exact partition of the catalogue, and every
403
  # member of it must be re-derivable from the two columns beside it. A signal somebody buys
404
  # stock on cannot be "mostly right": the failure that matters is a row that says OK because
platform/modules/products.py CHANGED
@@ -166,6 +166,62 @@ def directory(t=None, team_id=None):
166
  return rows
167
 
168
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
169
  def categories(t=None, team_id=None):
170
  """Sorted distinct category names present in the SKU directory (for the drill-down filter)."""
171
  return sorted({r['category'] for r in directory(t, team_id)})
 
166
  return rows
167
 
168
 
169
+ def catalogue():
170
+ """`{sku_code: {'product', 'category'}}` β€” EVERY ACTIVE product, sold or not.
171
+
172
+ β›” THIS IS THE CATALOGUE UNIVERSE, AND IT IS DELIBERATELY NOT `directory()`. `directory()`'s
173
+ row set IS the union of two revenue `read_group`s over `sale.order.line` (`:155`), so a SKU
174
+ that never sold cannot exist in it. That is CORRECT for its own callers β€” `yoy_movers`,
175
+ `zombie_skus`, `new_winners` and `categories` all legitimately want a sales-window universe β€”
176
+ and it is wrong for the PRODUCT GRID, which is a catalogue and was therefore showing 2,717 of
177
+ 5,875 SKUs (wave 29, owner item 22 / ruling R12). The fix is this function plus a LEFT JOIN in
178
+ the consumer, never a window removed from `directory()`: removing the window alone lands at
179
+ 3,327 (all-time-sold), because ~2,550 active SKUs have never sold in wholesale scope at all.
180
+
181
+ ⚠ NOT BU-SHAPED, and it cannot be: `product.product` carries no team. A catalogue is one
182
+ catalogue. `directory()` stays the BU-shaped half, which is why the two are joined rather than
183
+ merged β€” a scoped caller gets every SKU with ITS OWN revenue, blank where that BU never sold.
184
+
185
+ Keyed exactly like `_code_map()` β€” the `default_code`, or a `pid:N` fallback for the 33 active
186
+ records that carry none β€” so the join against `directory()` is code-for-code with no
187
+ normaliser. Names come from `display_name` (`[CODE] NAME`), which is what `O.m2o_name` yields
188
+ off a sale line, so a never-sold row wears the same format as a sold one.
189
+
190
+ β›” RAISES on a truncated read rather than returning a short catalogue. A silently short pull
191
+ would put the grid back at a plausible wrong number with every gate green β€” the exact failure
192
+ this function exists to end ([[no-unverifiable-aggregates]], and the same truncation guard
193
+ `modules/backorders.py:161` already uses).
194
+ """
195
+ dom = [('active', '=', True)]
196
+ prods = O.search_read('product.product', dom, ['id', 'default_code', 'display_name', 'name'],
197
+ limit=50000)
198
+ n = O.get_odoo().search_count('product.product', dom)
199
+ if len(prods) != n:
200
+ raise ValueError(
201
+ f"products.catalogue: the product pull is TRUNCATED β€” read {len(prods)} rows against "
202
+ f"a search_count of {n}. A short catalogue renders as a plausible smaller grid with "
203
+ f"nothing reporting it; raise the limit before shipping this.")
204
+ code_cat = _code_category()
205
+ out = {}
206
+ for p in prods:
207
+ code = (str(p['default_code']).strip() if p.get('default_code') else f"pid:{p['id']}")
208
+ # First record wins, matching `_code_category`'s own convention. MEASURED 2026-08-11: zero
209
+ # active products share a code, so this branch is a guard, not a merge policy.
210
+ out.setdefault(code, {'product': p.get('display_name') or p.get('name') or code,
211
+ 'category': code_cat.get(code, '(uncategorized)')})
212
+ return out
213
+
214
+
215
+ def catalogue_count():
216
+ """The INDEPENDENT population oracle: Odoo's own count of active products.
217
+
218
+ Deliberately a bare `search_count` and not a `len()` over anything this module built β€” the
219
+ 2,717 defect shipped silently for a wave because `product_data.validate()` derived BOTH sides
220
+ of its reconciliation from `_sku_rev`, so the oracle could never see a missing row.
221
+ """
222
+ return O.get_odoo().search_count('product.product', [('active', '=', True)])
223
+
224
+
225
  def categories(t=None, team_id=None):
226
  """Sorted distinct category names present in the SKU directory (for the drill-down filter)."""
227
  return sorted({r['category'] for r in directory(t, team_id)})
web/src/automation/AutomationBuilder.tsx CHANGED
@@ -2544,6 +2544,95 @@ export function ActionProps({
2544
  At most 12 β€” the provider returns a profile&rsquo;s top 12 posts and no more.
2545
  </p>
2546
  </div>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2547
  {/*
2548
  ⭐ WAVE 28 Β· R6/R7 β€” THE TWO CHECKBOXES THAT STOOD HERE MOVED UP INTO THE INCLUDE
2549
  GROUP, KEYS AND ALL (`postMetrics`, `commentMetrics`). They are not deleted features:
 
2544
  At most 12 β€” the provider returns a profile&rsquo;s top 12 posts and no more.
2545
  </p>
2546
  </div>
2547
+ {/*
2548
+ ⭐⭐ W29-T09 (owner item 11: *"the last 12 reels"*) β€” THE ONLY DOOR TO `config.postGroups`.
2549
+ The server side has been whole since wave 28 β€” `clean_post_groups` validates it, the
2550
+ enrich runner applies it β€” and `postGroups` had **zero occurrences** anywhere in
2551
+ `web/src`, so NO USER COULD ASK FOR REELS-ONLY AT ALL. That is why this is a blocker for
2552
+ the reels routing work and not a nicety: those tickets' negative controls need a config
2553
+ a person can actually produce.
2554
+
2555
+ β›” THE KEYS ARE THE SERVER'S AND SO ARE THE WORDS. `vocab.postTypes` carries both; a
2556
+ client that translated `video` into "Reels" locally would be a second copy of a
2557
+ vocabulary `clean_post_groups` refuses deviations from. Absent vocabulary renders
2558
+ NOTHING rather than three guessed names.
2559
+
2560
+ β›” ABSENT IS OFF, AND OFF IS THE DEFAULT FOREVER. An enrich action stored before this
2561
+ control carries no `postGroups`, and the runner returns the post list unchanged when the
2562
+ key is missing β€” so unchecking every box must DELETE the key, never store `[]`-with-
2563
+ meaning or a group of zero. Deleting it is what keeps an old automation capturing
2564
+ exactly what it always captured.
2565
+
2566
+ ⚠ ONE WRITER FOR ONE KEY [W-12]. This is the only control in `web/src` that writes
2567
+ `postGroups`; the `maxPosts` box above writes `maxPosts` and nothing else. The two are
2568
+ related only in that a group cannot keep more posts than the pull captures β€” which is
2569
+ the server's rule, printed here rather than re-implemented.
2570
+ */}
2571
+ {(vocab?.postTypes || []).length ? (
2572
+ <div className="auto-field">
2573
+ <p className="auto-field-label">Keep only certain posts</p>
2574
+ {(vocab?.postTypes || []).map((pt) => {
2575
+ const groups =
2576
+ ((cfg as { postGroups?: { type: string; limit: number }[] }).postGroups) || [];
2577
+ const mine = groups.find((g) => g && g.type === pt.key);
2578
+ const cap = Math.max(
2579
+ 1,
2580
+ Number((cfg as { maxPosts?: number }).maxPosts || 10) || 10
2581
+ );
2582
+ /* β›” WRITE THROUGH ONE FUNCTION, so the "no groups left β‡’ remove the key" rule
2583
+ exists once. Two call sites each deciding it is how `[]` starts meaning
2584
+ "capture nothing". */
2585
+ const write = (next: { type: string; limit: number }[]) =>
2586
+ setCfg({ postGroups: next.length ? next : undefined });
2587
+ return (
2588
+ <label className="auto-check" key={pt.key}>
2589
+ <input
2590
+ type="checkbox"
2591
+ checked={!!mine}
2592
+ disabled={busy}
2593
+ onChange={(e) =>
2594
+ write(
2595
+ e.target.checked
2596
+ ? [...groups.filter((g) => g.type !== pt.key),
2597
+ { type: pt.key, limit: Math.min(cap, 12) }]
2598
+ : groups.filter((g) => g.type !== pt.key)
2599
+ )
2600
+ }
2601
+ />
2602
+ {pt.label}
2603
+ {mine ? (
2604
+ <input
2605
+ className="auto-input auto-input-inline"
2606
+ type="number"
2607
+ min={1}
2608
+ max={cap}
2609
+ aria-label={`How many ${pt.label} to keep`}
2610
+ /* Commits on BLUR, exactly like `maxPosts` above and for the identical
2611
+ reason: "1" on the way to "12" is a value the server would store. */
2612
+ defaultValue={mine.limit}
2613
+ disabled={busy}
2614
+ onBlur={(e) =>
2615
+ write([
2616
+ ...groups.filter((g) => g.type !== pt.key),
2617
+ {
2618
+ type: pt.key,
2619
+ limit: Math.max(1, Number(e.target.value) || 1),
2620
+ },
2621
+ ])
2622
+ }
2623
+ />
2624
+ ) : null}
2625
+ </label>
2626
+ );
2627
+ })}
2628
+ <p className="auto-hint">
2629
+ Leave these unticked to keep every post. Ticked, only the kinds you name are
2630
+ kept β€” and a group cannot keep more than the {" "}
2631
+ {Number((cfg as { maxPosts?: number }).maxPosts || 10) || 10} posts this
2632
+ enrichment captures.
2633
+ </p>
2634
+ </div>
2635
+ ) : null}
2636
  {/*
2637
  ⭐ WAVE 28 Β· R6/R7 β€” THE TWO CHECKBOXES THAT STOOD HERE MOVED UP INTO THE INCLUDE
2638
  GROUP, KEYS AND ALL (`postMetrics`, `commentMetrics`). They are not deleted features:
web/src/automation/AutomationSurface.tsx CHANGED
@@ -216,7 +216,7 @@ export default function AutomationSurface() {
216
  * asked for" and "what is on screen" are written in one statement and cannot drift apart.
217
  * A resolution that wants to steer the rail compares itself against `wantedId` instead.
218
  */
219
- const select = useCallback((id: string, _stage = "") => {
220
  wantedId.current = id;
221
  setActiveId(id);
222
  }, []);
@@ -527,7 +527,21 @@ export default function AutomationSurface() {
527
  time a third kind shipped, and printed inside a `--lp-rail-w` column. What the
528
  kinds are belongs to the create form, which is one click away and lists all of
529
  them from the server. */}
530
- {!items.length && !error ? (
 
 
 
 
 
 
 
 
 
 
 
 
 
 
531
  <p className="auto-rail-empty">No automations yet.</p>
532
  ) : null}
533
  </div>
 
216
  * asked for" and "what is on screen" are written in one statement and cannot drift apart.
217
  * A resolution that wants to steer the rail compares itself against `wantedId` instead.
218
  */
219
+ const select = useCallback((id: string, _stage = "") => {
220
  wantedId.current = id;
221
  setActiveId(id);
222
  }, []);
 
527
  time a third kind shipped, and printed inside a `--lp-rail-w` column. What the
528
  kinds are belongs to the create form, which is one click away and lists all of
529
  them from the server. */}
530
+ {/* ⭐ WAVE 29 (W29-T01) β€” A LOADING RAIL IS NOT AN EMPTY ONE. `data` is null until the
531
+ first `listAutomations()` resolves, and this branch read only `items.length`, so
532
+ every visit to Automation asserted "No automations yet." to a person who has
533
+ several β€” then replaced it with their list. Half of owner item 5's "takes a while
534
+ to appear" is that sentence: the wait is real, but being told you own nothing is
535
+ what makes it read as broken rather than slow. `data === null` is the one state
536
+ that means NOBODY HAS LOOKED, and it gets skeleton rows, not a claim. */}
537
+ {data === null && !error ? (
538
+ <div className="auto-rail-loading" aria-hidden="true">
539
+ <span className="auto-rail-skel" />
540
+ <span className="auto-rail-skel" />
541
+ <span className="auto-rail-skel" />
542
+ </div>
543
+ ) : null}
544
+ {data !== null && !items.length && !error ? (
545
  <p className="auto-rail-empty">No automations yet.</p>
546
  ) : null}
547
  </div>
web/src/automation/TriggerPicker.tsx CHANGED
@@ -154,8 +154,13 @@ export function TriggerMark({ kind = "" }: { kind?: string }) {
154
  </svg>
155
  );
156
  // A MUSICAL NOTE inside the same search frame as `ig_profile_match`: same act (search a corpus
157
- // of profiles), different corpus. Drawing it as a second person-in-a-magnifier would say the
158
- // two are interchangeable, which is exactly the claim D-9 is still open about.
 
 
 
 
 
159
  if (kind === "tiktok_profile_match")
160
  return (
161
  <svg {...common}>
 
154
  </svg>
155
  );
156
  // A MUSICAL NOTE inside the same search frame as `ig_profile_match`: same act (search a corpus
157
+ // of profiles), different corpus. Drawing it as a second person-in-a-magnifier would say the two
158
+ // are interchangeable, and they are not β€” the two networks have different schemas and, per wave
159
+ // 29's R2, different `ut_*` families behind them.
160
+ // ⚠ WAVE 29: this row is LIVE now (D-9 closed the trigger half). Nothing in this file changed to
161
+ // make it so β€” `planned` rides the wire, which is the property that makes a server vocabulary
162
+ // worth having. The sentence that used to end this note ("the claim D-9 is still open about")
163
+ // was true when it was written and would have quietly aged into a lie.
164
  if (kind === "tiktok_profile_match")
165
  return (
166
  <svg {...common}>
web/src/automation/automationApi.ts CHANGED
@@ -472,6 +472,18 @@ export interface FlowVocab {
472
  maxCondChildren: number;
473
  maxGroupDepth: number;
474
  maxActions: number;
 
 
 
 
 
 
 
 
 
 
 
 
475
  /** Legacy read compatibility only; the server no longer sends Board review vocabulary. */
476
  reviewDeciders?: string[];
477
  /** Legacy read compatibility only; the server no longer sends Board review readiness. */
 
472
  maxCondChildren: number;
473
  maxGroupDepth: number;
474
  maxActions: number;
475
+ /**
476
+ * ⭐ W29-T09 (owner item 11: *"the last 12 reels"*) β€” the post kinds a capture group may name,
477
+ * with the words a person reads. OPTIONAL, like every other vocabulary here: absent means a
478
+ * server older than this client, and the control renders nothing rather than inventing three
479
+ * names the save door would refuse.
480
+ * β›” `key` is what `config.postGroups` STORES; `label` is only ever painted. Writing the label
481
+ * would build a filter `clean_post_groups` rejects with a sentence naming a word nobody typed.
482
+ */
483
+ postTypes?: { key: string; label: string }[];
484
+ /** The ceiling `clean_post_groups` judges a group's limit against (the action's own maxPosts
485
+ * is the real bound; this is the absolute one, so a hint can be honest about both). */
486
+ maxPostsPerPull?: number;
487
  /** Legacy read compatibility only; the server no longer sends Board review vocabulary. */
488
  reviewDeciders?: string[];
489
  /** Legacy read compatibility only; the server no longer sends Board review readiness. */
web/src/customer-grid/ColumnMenu.tsx CHANGED
@@ -7,13 +7,14 @@ import { CODE_LANGUAGE_LABELS, CODE_LANGUAGES, CREATABLE_TYPES, choiceOptions, c
7
  codeLanguageOf, directionLabel, isDerivedLink, isMachineOwned,
8
  isProfileField, parseOptions, ratingMax, ROLLUP_FN_LABELS, ROLLUP_FNS,
9
  ROLLUP_REF_OPS } from "./types";
10
- import type { Field, FieldFormat, FieldScope, FieldType, Measure, RollupCondition, RollupFn,
11
  RollupRefOp, RollupSource, Viewer } from "./types";
12
  import type { LinkTarget, RollupSourceOffer } from "./apiBridge";
13
  import type { WindowSpec } from "./windows";
14
  import { normalizeWindow, windowLabel } from "./windows";
15
  import { WindowPicker } from "../filter-kit";
16
  import { TYPE_LABELS } from "./iconShapes";
 
17
  import { validateFormula } from "./formulaEngine";
18
  import { BRAND_SWATCHES, defaultOptionColor, nearestSwatch, normalizeOptionColor,
19
  OPTION_PALETTE } from "./choiceColors";
@@ -238,6 +239,10 @@ interface ColumnMenuProps {
238
  /** Wave-5 item 10 β€” save a display format. Supplied for number/currency/formula and
239
  * date/created_time fields. */
240
  onFormat?: (format: FieldFormat) => void;
 
 
 
 
241
  /** Wave-5 item 1 β€” Sort by this field (replaces the view's sort), and the conditional
242
  * clears (item 3). All of these mutate the EXISTING view config β€” no new host surface. */
243
  onSort: (dir: "asc" | "desc") => void;
@@ -273,7 +278,7 @@ type CreatePosition = "left" | "right" | "end";
273
  * choices/stars/formula config), and the Change-field control that swaps the column to show
274
  * another field.
275
  */
276
- type MenuPane = "menu" | "note" | "edit" | "permissions" | "format";
277
 
278
  /**
279
  * How each creatable type reads in the menu. DERIVED from CREATABLE_TYPES rather than listed
@@ -1738,6 +1743,7 @@ export default function ColumnMenu({
1738
  onDuplicate,
1739
  onPermissions,
1740
  onFormat,
 
1741
  onSort,
1742
  onClearSort,
1743
  onFilterBy,
@@ -3146,6 +3152,63 @@ export default function ColumnMenu({
3146
  }
3147
 
3148
  // ------------------------------------------------------------------ FORMAT pane (item 10)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3149
  if (pane === "format" && formatKind) {
3150
  return (
3151
  <AnchoredOverlay
@@ -3350,6 +3413,19 @@ export default function ColumnMenu({
3350
  <MenuLabel icon="format" text="Field format" />
3351
  </button>
3352
  )}
 
 
 
 
 
 
 
 
 
 
 
 
 
3353
 
3354
  <div className="cg-menu-sep" role="separator" aria-hidden />
3355
 
 
7
  codeLanguageOf, directionLabel, isDerivedLink, isMachineOwned,
8
  isProfileField, parseOptions, ratingMax, ROLLUP_FN_LABELS, ROLLUP_FNS,
9
  ROLLUP_REF_OPS } from "./types";
10
+ import type { AggName, Field, FieldFormat, FieldScope, FieldType, Measure, RollupCondition, RollupFn,
11
  RollupRefOp, RollupSource, Viewer } from "./types";
12
  import type { LinkTarget, RollupSourceOffer } from "./apiBridge";
13
  import type { WindowSpec } from "./windows";
14
  import { normalizeWindow, windowLabel } from "./windows";
15
  import { WindowPicker } from "../filter-kit";
16
  import { TYPE_LABELS } from "./iconShapes";
17
+ import { AGG_LABELS, aggOptions } from "./aggregations";
18
  import { validateFormula } from "./formulaEngine";
19
  import { BRAND_SWATCHES, defaultOptionColor, nearestSwatch, normalizeOptionColor,
20
  OPTION_PALETTE } from "./choiceColors";
 
239
  /** Wave-5 item 10 β€” save a display format. Supplied for number/currency/formula and
240
  * date/created_time fields. */
241
  onFormat?: (format: FieldFormat) => void;
242
+ /** ⭐ WAVE-29 T33 (owner item 17) β€” set (or clear, with `undefined`) this column's SUMMARY: the
243
+ * value its group footers and the table's totals row show. Supplied wherever a field write is
244
+ * possible; the pane offers only what `aggregations.aggOptions` allows for the type. */
245
+ onAggregate?: (agg: AggName | undefined) => void;
246
  /** Wave-5 item 1 β€” Sort by this field (replaces the view's sort), and the conditional
247
  * clears (item 3). All of these mutate the EXISTING view config β€” no new host surface. */
248
  onSort: (dir: "asc" | "desc") => void;
 
278
  * choices/stars/formula config), and the Change-field control that swaps the column to show
279
  * another field.
280
  */
281
+ type MenuPane = "menu" | "note" | "edit" | "permissions" | "format" | "summary";
282
 
283
  /**
284
  * How each creatable type reads in the menu. DERIVED from CREATABLE_TYPES rather than listed
 
1743
  onDuplicate,
1744
  onPermissions,
1745
  onFormat,
1746
+ onAggregate,
1747
  onSort,
1748
  onClearSort,
1749
  onFilterBy,
 
3152
  }
3153
 
3154
  // ------------------------------------------------------------------ FORMAT pane (item 10)
3155
+ /**
3156
+ * ⭐⭐ WAVE-29 T33 (owner item 17) β€” THE COLUMN SUMMARY PANE.
3157
+ *
3158
+ * A flat list of the six aggregates plus "None", because that is the whole decision β€” there is
3159
+ * no draft to reconcile and no Save button to press, so the click IS the answer and the pane
3160
+ * closes on it (the same shape as Sort, one group up, and unlike Format, which composes four
3161
+ * settings into one bag).
3162
+ *
3163
+ * β›” THE OPTIONS COME FROM `aggOptions`, never from a list written here. `sum Β· average Β·
3164
+ * median Β· min Β· max` are numeric-only and `count` counts ROWS, so a text column offers exactly
3165
+ * one row β€” and it offers it, rather than hiding the pane, because "how many records is this
3166
+ * group" is the summary a text column CAN answer.
3167
+ */
3168
+ if (pane === "summary" && onAggregate) {
3169
+ const options = aggOptions(field);
3170
+ return (
3171
+ <AnchoredOverlay
3172
+ anchor={state.anchor}
3173
+ className="cg-column-menu"
3174
+ onDismiss={onClose}
3175
+ role="dialog"
3176
+ ariaLabel={`Summarize ${field.label}`}
3177
+ initialFocus="[data-overlay-autofocus]"
3178
+ dataKind="column-menu"
3179
+ >
3180
+ <PaneHead title="Summarize" sub={field.label} onClose={onClose} />
3181
+ <div className="cg-menu-list" role="none">
3182
+ <button
3183
+ type="button"
3184
+ data-overlay-autofocus={field.agg ? undefined : true}
3185
+ aria-pressed={!field.agg}
3186
+ onClick={() => {
3187
+ onAggregate(undefined);
3188
+ onClose();
3189
+ }}
3190
+ >
3191
+ <MenuLabel icon="off" text="None" />
3192
+ </button>
3193
+ {options.map((name) => (
3194
+ <button
3195
+ key={name}
3196
+ type="button"
3197
+ data-overlay-autofocus={field.agg === name ? true : undefined}
3198
+ aria-pressed={field.agg === name}
3199
+ onClick={() => {
3200
+ onAggregate(name);
3201
+ onClose();
3202
+ }}
3203
+ >
3204
+ <MenuLabel icon="format" text={AGG_LABELS[name]} />
3205
+ </button>
3206
+ ))}
3207
+ </div>
3208
+ </AnchoredOverlay>
3209
+ );
3210
+ }
3211
+
3212
  if (pane === "format" && formatKind) {
3213
  return (
3214
  <AnchoredOverlay
 
3413
  <MenuLabel icon="format" text="Field format" />
3414
  </button>
3415
  )}
3416
+ {/* ⭐ WAVE-29 T33 (owner item 17) β€” the COLUMN SUMMARY. Offered on every column, because
3417
+ `count` applies to any type; the numeric folds are filtered per type inside the pane
3418
+ by `aggOptions`. ⚠ NOT gated on `schemaLocked`: a summary is a reading of the column,
3419
+ not a change to its schema, so it belongs on a pre-set column too β€” the same reason
3420
+ Sort and Filter sit below without that gate. */}
3421
+ {onAggregate && (
3422
+ <button type="button" onClick={() => setPane("summary")}>
3423
+ <MenuLabel
3424
+ icon="format"
3425
+ text={field.agg ? `Summary: ${AGG_LABELS[field.agg]}` : "Summarize this column"}
3426
+ />
3427
+ </button>
3428
+ )}
3429
 
3430
  <div className="cg-menu-sep" role="separator" aria-hidden />
3431
 
web/src/customer-grid/CustomerGrid.tsx CHANGED
The diff for this file is too large to render. See raw diff
 
web/src/customer-grid/FormInterface.css ADDED
@@ -0,0 +1,269 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /* ---------------------------------------------------------------------------
2
+ customer-grid / FormInterface.css
3
+ ⭐ WAVE-29 R7 β€” the FORM builder's own stylesheet.
4
+
5
+ Its own file rather than `index.css` for two reasons, and only one of them is this wave's
6
+ fence: a mode's surface that ships with its component can be read, moved or retired in one
7
+ place (`RecordDetail.css` and `ImportDialog.css` set the precedent), and `index.css` is
8
+ already the app's largest single file.
9
+
10
+ Every colour, radius and type size is a `--lp-*` token. Nothing here invents a hue: the token
11
+ parity gate compares `index.css` against `theme.ts`, and a raw hex would be invisible to it.
12
+ --------------------------------------------------------------------------- */
13
+
14
+ .cg-form-build {
15
+ display: flex;
16
+ flex-wrap: wrap;
17
+ gap: 24px;
18
+ align-items: flex-start;
19
+ overflow: auto;
20
+ padding: 20px 24px 32px;
21
+ height: 100%;
22
+ background: var(--lp-surface);
23
+ color: var(--lp-ink);
24
+ font-size: var(--lp-fs-xs);
25
+ }
26
+
27
+ .cg-form-pane {
28
+ flex: 1 1 320px;
29
+ min-width: 300px;
30
+ max-width: 560px;
31
+ }
32
+
33
+ .cg-form-h {
34
+ margin: 0 0 12px;
35
+ font-size: var(--lp-fs-lg);
36
+ font-weight: 600;
37
+ }
38
+
39
+ .cg-form-sub {
40
+ margin: 22px 0 8px;
41
+ font-size: var(--lp-fs-2xs);
42
+ font-weight: 600;
43
+ letter-spacing: 0.02em;
44
+ color: var(--lp-muted);
45
+ }
46
+
47
+ /* The first `.cg-form-sub` in a pane sits under no heading of its own. */
48
+ .cg-form-pane > .cg-form-sub:first-child {
49
+ margin-top: 0;
50
+ }
51
+
52
+ .cg-form-note {
53
+ margin: 6px 0;
54
+ color: var(--lp-muted);
55
+ font-size: var(--lp-fs-2xs);
56
+ line-height: 1.5;
57
+ }
58
+
59
+ /* An honest warning, not an alarm: it is a state the reader can fix, so it is tinted rather
60
+ than shouted. Red is reserved for a refusal that has already cost something. */
61
+ .cg-form-warn {
62
+ margin: 8px 0;
63
+ padding: 8px 10px;
64
+ border: 1px solid var(--lp-red);
65
+ border-radius: var(--lp-r-sm);
66
+ background: var(--lp-red-tint);
67
+ color: var(--lp-red-deep);
68
+ font-size: var(--lp-fs-2xs);
69
+ line-height: 1.5;
70
+ }
71
+
72
+ .cg-form-empty {
73
+ display: grid;
74
+ place-items: center;
75
+ height: 100%;
76
+ padding: 40px;
77
+ color: var(--lp-muted);
78
+ font-size: var(--lp-fs-xs);
79
+ text-align: center;
80
+ }
81
+
82
+ /* --- the spec fields ------------------------------------------------------------------- */
83
+
84
+ .cg-form-row {
85
+ display: block;
86
+ margin: 0 0 12px;
87
+ }
88
+
89
+ .cg-form-row > span {
90
+ display: block;
91
+ margin-bottom: 4px;
92
+ color: var(--lp-muted);
93
+ font-size: var(--lp-fs-3xs);
94
+ font-weight: 600;
95
+ }
96
+
97
+ .cg-form-row input[type="text"],
98
+ .cg-form-row textarea,
99
+ .cg-form-addmail input {
100
+ width: 100%;
101
+ padding: 7px 9px;
102
+ border: 1px solid var(--lp-line);
103
+ border-radius: var(--lp-r-sm);
104
+ background: var(--lp-surface);
105
+ color: var(--lp-ink);
106
+ font-family: inherit;
107
+ font-size: var(--lp-fs-xs);
108
+ resize: vertical;
109
+ }
110
+
111
+ .cg-form-row input:disabled,
112
+ .cg-form-row textarea:disabled {
113
+ background: var(--lp-wash);
114
+ color: var(--lp-muted);
115
+ }
116
+
117
+ /* --- the question list ----------------------------------------------------------------- */
118
+
119
+ .cg-form-fields {
120
+ margin: 0;
121
+ padding: 0;
122
+ list-style: none;
123
+ border: 1px solid var(--lp-line);
124
+ border-radius: var(--lp-r-md);
125
+ overflow: hidden;
126
+ }
127
+
128
+ .cg-form-field {
129
+ display: flex;
130
+ align-items: center;
131
+ justify-content: space-between;
132
+ gap: 10px;
133
+ padding: 7px 10px;
134
+ border-bottom: 1px solid var(--lp-line);
135
+ }
136
+
137
+ .cg-form-field:last-child {
138
+ border-bottom: 0;
139
+ }
140
+
141
+ .cg-form-field.on {
142
+ background: var(--lp-blue-tint);
143
+ }
144
+
145
+ .cg-form-pick {
146
+ display: flex;
147
+ align-items: center;
148
+ gap: 8px;
149
+ min-width: 0;
150
+ cursor: pointer;
151
+ }
152
+
153
+ .cg-form-label {
154
+ overflow: hidden;
155
+ text-overflow: ellipsis;
156
+ white-space: nowrap;
157
+ }
158
+
159
+ .cg-form-type {
160
+ color: var(--lp-muted);
161
+ font-size: var(--lp-fs-3xs);
162
+ }
163
+
164
+ .cg-form-req {
165
+ display: flex;
166
+ align-items: center;
167
+ gap: 5px;
168
+ flex: none;
169
+ color: var(--lp-muted);
170
+ font-size: var(--lp-fs-3xs);
171
+ cursor: pointer;
172
+ }
173
+
174
+ /* --- who can submit -------------------------------------------------------------------- */
175
+
176
+ .cg-form-radio {
177
+ display: flex;
178
+ align-items: flex-start;
179
+ gap: 9px;
180
+ margin-bottom: 10px;
181
+ cursor: pointer;
182
+ }
183
+
184
+ .cg-form-radio strong {
185
+ display: block;
186
+ font-weight: 600;
187
+ }
188
+
189
+ .cg-form-radio em {
190
+ display: block;
191
+ margin-top: 2px;
192
+ color: var(--lp-muted);
193
+ font-size: var(--lp-fs-3xs);
194
+ font-style: normal;
195
+ line-height: 1.5;
196
+ }
197
+
198
+ .cg-form-emails ul {
199
+ margin: 0 0 8px;
200
+ padding: 0;
201
+ list-style: none;
202
+ }
203
+
204
+ .cg-form-emails li {
205
+ display: flex;
206
+ align-items: center;
207
+ justify-content: space-between;
208
+ gap: 8px;
209
+ padding: 5px 0;
210
+ border-bottom: 1px solid var(--lp-line);
211
+ }
212
+
213
+ .cg-form-emails li:last-child {
214
+ border-bottom: 0;
215
+ }
216
+
217
+ .cg-form-addmail {
218
+ display: flex;
219
+ gap: 8px;
220
+ }
221
+
222
+ /* --- the share link -------------------------------------------------------------------- */
223
+
224
+ .cg-form-link {
225
+ padding: 10px 12px;
226
+ border: 1px solid var(--lp-line);
227
+ border-radius: var(--lp-r-md);
228
+ background: var(--lp-surface-2);
229
+ }
230
+
231
+ .cg-form-link code {
232
+ display: block;
233
+ margin-bottom: 8px;
234
+ overflow-wrap: anywhere;
235
+ color: var(--lp-blue-deep);
236
+ font-size: var(--lp-fs-2xs);
237
+ }
238
+
239
+ .cg-form-actions {
240
+ display: flex;
241
+ flex-wrap: wrap;
242
+ gap: 8px;
243
+ }
244
+
245
+ .cg-form-build button {
246
+ padding: 5px 11px;
247
+ border: 1px solid var(--lp-line);
248
+ border-radius: var(--lp-r-pill);
249
+ background: var(--lp-surface);
250
+ color: var(--lp-ink);
251
+ font-family: inherit;
252
+ font-size: var(--lp-fs-2xs);
253
+ cursor: pointer;
254
+ }
255
+
256
+ .cg-form-build button:hover:not(:disabled) {
257
+ border-color: var(--lp-blue-solid);
258
+ color: var(--lp-blue-deep);
259
+ }
260
+
261
+ .cg-form-build button:disabled {
262
+ color: var(--lp-muted);
263
+ cursor: default;
264
+ }
265
+
266
+ .cg-form-emails button {
267
+ padding: 2px 8px;
268
+ font-size: var(--lp-fs-3xs);
269
+ }
web/src/customer-grid/FormInterface.tsx ADDED
@@ -0,0 +1,504 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // customer-grid / FormInterface.tsx
3
+ // ⭐⭐ WAVE-29 R7 (owner item 10, contracts C3 / C4) β€” THE FORM INTERFACE.
4
+ //
5
+ // The owner's ask, verbatim: "a user fills in information; the form has a shareable link that
6
+ // accepts submissions either from authorized people (by email) or from the public. Google Forms
7
+ // is the reference."
8
+ //
9
+ // This file is the BUILDER β€” the in-app surface a `form`-kind view renders. The page a stranger
10
+ // fills in is `FormPublic.tsx` and it already shipped in wave 23, along with the whole public
11
+ // door (`api/routes_forms.py`). What had never existed was any way to CREATE the thing they
12
+ // serve: `form` was not a legal display mode and `_clean_display` dropped `display.form`, so the
13
+ // key the public door reads could not be written by anything. That is D-90, and it is why this
14
+ // component is mostly plumbing rather than a new idea β€” the door was built first and the handle
15
+ // never fitted.
16
+ //
17
+ // THE TWO HALVES, and they are stored in two different places on purpose:
18
+ // * the SPEC (questions, title, who may submit) lives on the view, at `config.display.form`,
19
+ // written through the host's ordinary view-save path like every other mode's configuration;
20
+ // * the TOKEN lives in a server-owned index a browser cannot write, because a share token that
21
+ // rides the wire is a token a browser can CHOOSE, and the public resolver answers with the
22
+ // first tenant that matches. See `routes_forms.py`'s note for the whole argument.
23
+ // ---------------------------------------------------------------------------
24
+
25
+ import { useCallback, useEffect, useMemo, useState } from "react";
26
+ import { API_V1, CREDENTIALS } from "../apiContract";
27
+ import type { Field, FieldType, FormSpec } from "./types";
28
+ import { TYPE_LABELS } from "./iconShapes";
29
+ import "./FormInterface.css";
30
+
31
+ /**
32
+ * The field types a form may COLLECT. **Mirrors `platform/aios_grid.py::FORM_FIELD_TYPES` and
33
+ * `verify_forms.py` compares the two files name-for-name** β€” a type offered here and refused
34
+ * there is a question that silently vanishes from the published form, which is the failure a
35
+ * one-sided list produces every time.
36
+ *
37
+ * An ALLOW-LIST, not a list of exclusions: a type missing here is a question the builder cannot
38
+ * ask yet, while a type wrongly present is a public door writing values its column cannot mean.
39
+ * The two mistakes do not cost the same, so the list fails closed.
40
+ */
41
+ export const FORM_FIELD_TYPES: ReadonlySet<FieldType> = new Set<FieldType>([
42
+ "text", "select", "multiselect", "int", "currency", "pct", "date",
43
+ "checkbox", "phone", "email", "url", "rating",
44
+ ]);
45
+
46
+ /**
47
+ * The stored bag at `view.config.display.form` is `FormSpec`, and it is DECLARED IN `./types`
48
+ * (imported above), not here. β›” Declaring it in this file made a type-only circular import β€”
49
+ * `types.ts` needs it for `DisplaySpec.form` while this file needs `Field` from `types.ts` β€” which
50
+ * vite erased and `tsc --ignoreConfig` could not, killing `verify_optimism` and
51
+ * `verify_live_workspace` with TS6142. Re-exported here so this file still names the contract it
52
+ * edits; the single declaration stays in the type module. β›” No `token` β€” see the header.
53
+ */
54
+ export type { FormSpec } from "./types";
55
+
56
+ export interface FormInterfaceProps {
57
+ /** The database this form collects into (`topicForScope(scope)`), e.g. `ut_leads`. */
58
+ topic: string;
59
+ /** The view holding the spec. `null` while no saved view is active β€” a form has nowhere to live. */
60
+ viewId: string | null;
61
+ /** Every column of the table; this component decides which can be questions. */
62
+ fields: Field[];
63
+ /**
64
+ * The stored spec, or `null` when this view has no form yet.
65
+ * ⚠ REQUIRED and NULLABLE, never optional: the host passes `displaySpec?.form ?? null`, and the
66
+ * `?? null` is the point β€” an optional prop degrades to "the feature does not exist", which is
67
+ * indistinguishable from never having been built.
68
+ */
69
+ spec: FormSpec | null;
70
+ /** Writes the spec back into `config.display.form`. `null` clears it. */
71
+ onSpec: (next: FormSpec | null) => void;
72
+ /** May this viewer change the form's configuration (the view-config grant)? */
73
+ canEdit: boolean;
74
+ /** Why not, in one sentence, when `canEdit` is false. `null` when it is true. */
75
+ readOnlyReason: string | null;
76
+ /** Does this database accept new records at all? A locked one can never be a form's target. */
77
+ canCollect: boolean;
78
+ }
79
+
80
+ interface LinkState {
81
+ token: string | null;
82
+ url: string | null;
83
+ stored: { fields: number; access: string; title: string } | null;
84
+ }
85
+
86
+ const EMPTY_LINK: LinkState = { token: null, url: null, stored: null };
87
+
88
+ /** The share URL the page shows. The server returns an origin-qualified one when it knows the
89
+ * public base; otherwise it returns a path, and only the browser knows where it is. */
90
+ function absolute(url: string): string {
91
+ return url.startsWith("http") ? url : `${window.location.origin}${url}`;
92
+ }
93
+
94
+ export function FormInterface({
95
+ topic,
96
+ viewId,
97
+ fields,
98
+ spec,
99
+ onSpec,
100
+ canEdit,
101
+ readOnlyReason,
102
+ canCollect,
103
+ }: FormInterfaceProps) {
104
+ const [link, setLink] = useState<LinkState>(EMPTY_LINK);
105
+ const [busy, setBusy] = useState(false);
106
+ const [problem, setProblem] = useState("");
107
+ const [copied, setCopied] = useState(false);
108
+ const [emailDraft, setEmailDraft] = useState("");
109
+
110
+ /**
111
+ * The columns that can be questions.
112
+ *
113
+ * ⚠ The server enforces this too, and both walls are needed rather than one: a column can
114
+ * BECOME computed (a formula, a rollup, a metric binding) long after it was added to a live
115
+ * form, and this component is not running when that happens. Here it is a courtesy that keeps
116
+ * the builder honest; `routes_forms._public_form` is the wall.
117
+ */
118
+ const askable = useMemo(
119
+ () =>
120
+ fields.filter(
121
+ (f) =>
122
+ FORM_FIELD_TYPES.has(f.type) &&
123
+ f.source !== "odoo" &&
124
+ !f.automation &&
125
+ !f.rollup &&
126
+ !f.metric
127
+ ),
128
+ [fields]
129
+ );
130
+ const byKey = useMemo(() => new Map(fields.map((f) => [f.key, f])), [fields]);
131
+
132
+ const chosen = spec?.fields ?? [];
133
+ const required = useMemo(() => new Set(spec?.required ?? []), [spec]);
134
+ const emails = spec?.emails ?? [];
135
+ const restricted = spec?.access === "emails";
136
+
137
+ /**
138
+ * ⭐ THE DEAD-STATE DETECTOR, and it earns its four lines.
139
+ *
140
+ * The spec reaches this panel through the host's `cleanDisplay`, which builds its output key by
141
+ * key β€” so a host that does not carry `display.form` hands back `null` forever. The panel would
142
+ * then look exactly like a form nobody has built yet: every keystroke accepted, nothing stored,
143
+ * no error anywhere. That is [W-07]'s failure verbatim β€” "the feature does not exist" and "the
144
+ * feature was never wired" are indistinguishable from the outside, and four consecutive waves
145
+ * lost a hand-off to it.
146
+ *
147
+ * One write plus one render answers it: if this panel has SENT a spec and the next render still
148
+ * has none, the carry is missing. It cannot false-positive on a slow save β€” `onSpec` is
149
+ * synchronous host state, not a request.
150
+ */
151
+ const [wrote, setWrote] = useState(false);
152
+ const carryBroken = wrote && spec === null;
153
+
154
+ const patch = useCallback(
155
+ (next: Partial<FormSpec>) => {
156
+ if (!canEdit) return;
157
+ setWrote(true);
158
+ onSpec({ ...(spec ?? {}), ...next });
159
+ },
160
+ [canEdit, onSpec, spec]
161
+ );
162
+
163
+ // ---- the share link, read from the server (never minted on read) -------------------------
164
+ const url = `${API_V1}/form-link?topic=${encodeURIComponent(topic)}&view=${encodeURIComponent(
165
+ viewId ?? ""
166
+ )}`;
167
+
168
+ useEffect(() => {
169
+ if (!viewId) {
170
+ setLink(EMPTY_LINK);
171
+ return;
172
+ }
173
+ let live = true;
174
+ fetch(url, { credentials: CREDENTIALS })
175
+ .then((r) => (r.ok ? r.json() : EMPTY_LINK))
176
+ .then((body: LinkState) => {
177
+ if (live) setLink(body ?? EMPTY_LINK);
178
+ })
179
+ .catch(() => {
180
+ if (live) setLink(EMPTY_LINK);
181
+ });
182
+ return () => {
183
+ live = false;
184
+ };
185
+ }, [url, viewId]);
186
+
187
+ const call = useCallback(
188
+ async (method: "POST" | "DELETE", body?: unknown) => {
189
+ setBusy(true);
190
+ setProblem("");
191
+ try {
192
+ const response = await fetch(method === "POST" ? `${API_V1}/form-link` : url, {
193
+ method,
194
+ credentials: CREDENTIALS,
195
+ ...(body
196
+ ? { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }
197
+ : {}),
198
+ });
199
+ const payload = await response.json().catch(() => null);
200
+ if (!response.ok) {
201
+ setProblem(
202
+ (payload as { error?: { message?: string } } | null)?.error?.message ??
203
+ `The server answered ${response.status}.`
204
+ );
205
+ return;
206
+ }
207
+ setLink(
208
+ method === "DELETE"
209
+ ? { ...EMPTY_LINK, stored: link.stored }
210
+ : { ...(payload as LinkState), stored: link.stored }
211
+ );
212
+ } finally {
213
+ setBusy(false);
214
+ }
215
+ },
216
+ [link.stored, url]
217
+ );
218
+
219
+ const copy = useCallback(() => {
220
+ if (!link.url) return;
221
+ void navigator.clipboard?.writeText(absolute(link.url));
222
+ setCopied(true);
223
+ window.setTimeout(() => setCopied(false), 1600);
224
+ }, [link.url]);
225
+
226
+ // ---- the states that are not a form -------------------------------------------------------
227
+ if (!viewId) {
228
+ return (
229
+ <div className="cg-form-empty">
230
+ A form belongs to a saved view. Save this view first, then build the form on it.
231
+ </div>
232
+ );
233
+ }
234
+ if (!canCollect) {
235
+ // ⚠ NOT `readOnlyReason`, and the two must not be merged: this is a fact about the DATABASE
236
+ // (a locked one accepts no new records, so a form could only ever collect refusals), while
237
+ // `readOnlyReason` is about the VIEWER's grant.
238
+ return (
239
+ <div className="cg-form-empty">
240
+ This database does not accept new records, so a form has nowhere to put an answer.
241
+ </div>
242
+ );
243
+ }
244
+
245
+ const diverged = spec === null && (link.stored?.fields ?? 0) > 0;
246
+
247
+ return (
248
+ <div className="cg-form-build">
249
+ <div className="cg-form-pane">
250
+ <h2 className="cg-form-h">Form</h2>
251
+ {!canEdit && readOnlyReason && <p className="cg-form-note">{readOnlyReason}</p>}
252
+ {/* ⚠ The divergence banner. The `spec` prop comes from the host's `cleanDisplay`, and if
253
+ that ever stops carrying `display.form` the panel would render an empty form over a
254
+ stored one β€” and the next save would erase real questions. Saying so beats losing
255
+ them quietly. */}
256
+ {diverged && (
257
+ <p className="cg-form-warn">
258
+ The server holds {link.stored?.fields} question
259
+ {link.stored?.fields === 1 ? "" : "s"} for this view that this page is not carrying.
260
+ Reload before editing β€” saving now would replace them.
261
+ </p>
262
+ )}
263
+ {/* ⚠ The banner above needs a STORED spec to compare against, so it can only speak once a
264
+ form has been saved successfully at least once. This one covers the state before
265
+ that: nothing has ever been stored, so there is nothing to diverge from. */}
266
+ {carryBroken && (
267
+ <p className="cg-form-warn">
268
+ Nothing is being saved: this view gave back no form after the last change. Reload the
269
+ page β€” if it repeats, this build cannot store forms and an administrator should be
270
+ told, because everything typed here is being discarded.
271
+ </p>
272
+ )}
273
+
274
+ <label className="cg-form-row">
275
+ <span>Title</span>
276
+ <input
277
+ type="text"
278
+ value={spec?.title ?? ""}
279
+ maxLength={120}
280
+ disabled={!canEdit}
281
+ placeholder="What this form is for"
282
+ onChange={(e) => patch({ title: e.target.value })}
283
+ />
284
+ </label>
285
+ <label className="cg-form-row">
286
+ <span>Description</span>
287
+ <textarea
288
+ rows={2}
289
+ value={spec?.desc ?? ""}
290
+ maxLength={1000}
291
+ disabled={!canEdit}
292
+ placeholder="Anything the person filling it in should know"
293
+ onChange={(e) => patch({ desc: e.target.value })}
294
+ />
295
+ </label>
296
+ <label className="cg-form-row">
297
+ <span>Submit button</span>
298
+ <input
299
+ type="text"
300
+ value={spec?.submitLabel ?? ""}
301
+ maxLength={60}
302
+ disabled={!canEdit}
303
+ placeholder="Submit"
304
+ onChange={(e) => patch({ submitLabel: e.target.value })}
305
+ />
306
+ </label>
307
+
308
+ <h3 className="cg-form-sub">Questions</h3>
309
+ {askable.length === 0 ? (
310
+ <p className="cg-form-note">
311
+ No column on this database can be a form question yet. A form can ask for text,
312
+ numbers, dates, choices and yes/no β€” it cannot ask for a value the app computes.
313
+ </p>
314
+ ) : (
315
+ <ul className="cg-form-fields">
316
+ {askable.map((f) => {
317
+ const on = chosen.includes(f.key);
318
+ return (
319
+ <li key={f.key} className={on ? "cg-form-field on" : "cg-form-field"}>
320
+ <label className="cg-form-pick">
321
+ <input
322
+ type="checkbox"
323
+ checked={on}
324
+ disabled={!canEdit}
325
+ onChange={() =>
326
+ patch({
327
+ // Order is the FORM's, so a newly ticked question joins the END rather
328
+ // than being sorted into the column order β€” the same rule the server
329
+ // preserves and the public page renders by.
330
+ fields: on
331
+ ? chosen.filter((k) => k !== f.key)
332
+ : [...chosen, f.key],
333
+ required: on
334
+ ? (spec?.required ?? []).filter((k) => k !== f.key)
335
+ : spec?.required,
336
+ })
337
+ }
338
+ />
339
+ <span className="cg-form-label">{f.label}</span>
340
+ <span className="cg-form-type">{TYPE_LABELS[f.type]}</span>
341
+ </label>
342
+ {on && (
343
+ <label className="cg-form-req">
344
+ <input
345
+ type="checkbox"
346
+ checked={required.has(f.key)}
347
+ disabled={!canEdit}
348
+ onChange={() =>
349
+ patch({
350
+ required: required.has(f.key)
351
+ ? (spec?.required ?? []).filter((k) => k !== f.key)
352
+ : [...(spec?.required ?? []), f.key],
353
+ })
354
+ }
355
+ />
356
+ <span>Required</span>
357
+ </label>
358
+ )}
359
+ </li>
360
+ );
361
+ })}
362
+ </ul>
363
+ )}
364
+ </div>
365
+
366
+ <div className="cg-form-pane">
367
+ <h3 className="cg-form-sub">Who can submit</h3>
368
+ <label className="cg-form-radio">
369
+ <input
370
+ type="radio"
371
+ name="cg-form-access"
372
+ checked={!restricted}
373
+ disabled={!canEdit}
374
+ onChange={() => patch({ access: "public" })}
375
+ />
376
+ <span>
377
+ <strong>Anyone with the link</strong>
378
+ <em>No sign-in. Rate-limited, and capped per day.</em>
379
+ </span>
380
+ </label>
381
+ <label className="cg-form-radio">
382
+ <input
383
+ type="radio"
384
+ name="cg-form-access"
385
+ checked={restricted}
386
+ disabled={!canEdit}
387
+ onChange={() => patch({ access: "emails" })}
388
+ />
389
+ <span>
390
+ <strong>Only the people I list</strong>
391
+ {/* ⚠ The honest boundary, in the UI and not only in the docstring: this asks the
392
+ submitter to name themselves and refuses an address that is not on the list. It
393
+ does not PROVE the address is theirs. */}
394
+ <em>
395
+ They enter their email address and it must match the list. This identifies them; it
396
+ does not verify them β€” anyone with the link who knows a listed address can submit.
397
+ </em>
398
+ </span>
399
+ </label>
400
+
401
+ {restricted && (
402
+ <div className="cg-form-emails">
403
+ <ul>
404
+ {emails.map((e) => (
405
+ <li key={e}>
406
+ <span>{e}</span>
407
+ {canEdit && (
408
+ <button
409
+ type="button"
410
+ onClick={() => patch({ emails: emails.filter((x) => x !== e) })}
411
+ aria-label={`Remove ${e}`}
412
+ >
413
+ Remove
414
+ </button>
415
+ )}
416
+ </li>
417
+ ))}
418
+ {emails.length === 0 && (
419
+ <li className="cg-form-note">
420
+ Nobody is listed yet, so nobody can submit this form.
421
+ </li>
422
+ )}
423
+ </ul>
424
+ {canEdit && (
425
+ <form
426
+ className="cg-form-addmail"
427
+ onSubmit={(e) => {
428
+ e.preventDefault();
429
+ const next = emailDraft.trim().toLowerCase();
430
+ if (!next || emails.includes(next)) return;
431
+ patch({ emails: [...emails, next] });
432
+ setEmailDraft("");
433
+ }}
434
+ >
435
+ <input
436
+ type="email"
437
+ value={emailDraft}
438
+ placeholder="name@company.com"
439
+ onChange={(e) => setEmailDraft(e.target.value)}
440
+ />
441
+ <button type="submit">Add</button>
442
+ </form>
443
+ )}
444
+ </div>
445
+ )}
446
+
447
+ <h3 className="cg-form-sub">Share link</h3>
448
+ {problem && <p className="cg-form-warn">{problem}</p>}
449
+ {link.url ? (
450
+ <div className="cg-form-link">
451
+ <code>{absolute(link.url)}</code>
452
+ <div className="cg-form-actions">
453
+ <button type="button" onClick={copy}>
454
+ {copied ? "Copied" : "Copy link"}
455
+ </button>
456
+ {canEdit && (
457
+ <>
458
+ <button
459
+ type="button"
460
+ disabled={busy}
461
+ onClick={() => void call("POST", { topic, view: viewId, regenerate: true })}
462
+ title="Mints a new link. The old one stops working immediately."
463
+ >
464
+ Regenerate
465
+ </button>
466
+ <button type="button" disabled={busy} onClick={() => void call("DELETE")}>
467
+ Turn off
468
+ </button>
469
+ </>
470
+ )}
471
+ </div>
472
+ </div>
473
+ ) : (
474
+ <div className="cg-form-link">
475
+ <p className="cg-form-note">
476
+ This form has no link yet, so nobody outside the app can reach it.
477
+ </p>
478
+ {canEdit && (
479
+ <button
480
+ type="button"
481
+ disabled={busy || chosen.length === 0}
482
+ onClick={() => void call("POST", { topic, view: viewId })}
483
+ >
484
+ Create link
485
+ </button>
486
+ )}
487
+ {chosen.length === 0 && (
488
+ <p className="cg-form-note">Pick at least one question first.</p>
489
+ )}
490
+ </div>
491
+ )}
492
+ {chosen.length > 0 && (
493
+ <p className="cg-form-note">
494
+ Answers land as new records in this database
495
+ {chosen.length === 1 ? ", one column" : `, ${chosen.length} columns`}:{" "}
496
+ {chosen.map((k) => byKey.get(k)?.label ?? k).join(", ")}.
497
+ </p>
498
+ )}
499
+ </div>
500
+ </div>
501
+ );
502
+ }
503
+
504
+ export default FormInterface;
web/src/customer-grid/ImportDialog.css ADDED
@@ -0,0 +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
+ }
web/src/customer-grid/ImportDialog.tsx ADDED
@@ -0,0 +1,325 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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 { coerceClipboardValue } from "./clipboard";
32
+ import { choiceOptions, isImportTarget } from "./types";
33
+ import type { Field } from "./types";
34
+ import "./ImportDialog.css";
35
+
36
+ /** The one header a JSON POST needs. `apiBridge` keeps its own module-local copy; this is a
37
+ * literal rather than an import because that constant is not exported and that file is not
38
+ * this session's to change. */
39
+ const JSON_HEADERS = { "Content-Type": "application/json" };
40
+
41
+ /** The upload door's answer (`routes_uploads.tabular`). */
42
+ interface Parsed {
43
+ columns: string[];
44
+ rows: number;
45
+ values: string[][];
46
+ truncated?: boolean;
47
+ }
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<Record<number, string>>({});
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 & { detail?: { error?: { message?: string } } })
96
+ | null;
97
+ if (!res.ok || !body) {
98
+ setError(
99
+ body?.detail?.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: Record<number, string> = {};
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
+ * Coerce every mapped cell and collect the refusals. Runs over the WHOLE parsed file, not the
126
+ * preview: the point of this step is that a bad value on row 900 is reported BEFORE anything is
127
+ * written, rather than discovered as a half-imported file.
128
+ */
129
+ const plan = useMemo(() => {
130
+ const problems: { row: number; column: string; value: string; field: string }[] = [];
131
+ const rows: Record<string, string>[] = [];
132
+ if (!parsed) return { rows, problems };
133
+ const mapped = Object.entries(mapping).filter(([, key]) => key !== NONE);
134
+ for (let r = 0; r < (parsed.values?.length ?? 0); r += 1) {
135
+ const out: Record<string, string> = {};
136
+ let blank = true;
137
+ for (const [idxText, key] of mapped) {
138
+ const field = targets.find((f) => f.key === key);
139
+ if (!field) continue;
140
+ const raw = String(parsed.values[r]?.[Number(idxText)] ?? "");
141
+ if (raw.trim() === "") continue;
142
+ blank = false;
143
+ const value = coerceClipboardValue(field, raw, choiceOptions(field));
144
+ if (value === null) {
145
+ problems.push({
146
+ row: r + 2, // +1 for the header row, +1 because humans count from 1
147
+ column: parsed.columns[Number(idxText)] ?? `Column ${Number(idxText) + 1}`,
148
+ value: raw.slice(0, 40),
149
+ field: field.label,
150
+ });
151
+ continue;
152
+ }
153
+ out[key] = String(value);
154
+ }
155
+ if (!blank) rows.push(out);
156
+ }
157
+ return { rows, problems };
158
+ }, [parsed, mapping, targets]);
159
+
160
+ async function run(): Promise<void> {
161
+ setBusy(true);
162
+ setError("");
163
+ try {
164
+ const res = await fetch(
165
+ `${API_V1}/tables/${encodeURIComponent(scope)}/rows/import`,
166
+ {
167
+ method: "POST",
168
+ credentials: CREDENTIALS,
169
+ headers: JSON_HEADERS,
170
+ body: JSON.stringify({ rows: plan.rows }),
171
+ }
172
+ );
173
+ const body = (await res.json().catch(() => null)) as
174
+ | { imported?: number; detail?: { error?: { message?: string } } }
175
+ | null;
176
+ if (!res.ok) {
177
+ // The server's sentence beats anything invented here: it names the column, or the cap.
178
+ setError(body?.detail?.error?.message ?? `The server answered ${res.status}.`);
179
+ return;
180
+ }
181
+ onImported(body?.imported ?? plan.rows.length);
182
+ onClose();
183
+ } catch {
184
+ setError("Nothing was imported β€” the request did not complete.");
185
+ } finally {
186
+ setBusy(false);
187
+ }
188
+ }
189
+
190
+ const mappedCount = Object.values(mapping).filter((k) => k !== NONE).length;
191
+
192
+ return (
193
+ <div className="cg-import-scrim" role="presentation" onClick={onClose}>
194
+ <div
195
+ className="cg-import"
196
+ role="dialog"
197
+ aria-modal="true"
198
+ aria-label={`Import records into ${tableName}`}
199
+ onClick={(event) => event.stopPropagation()}
200
+ >
201
+ <div className="cg-import-head">
202
+ <h2>Import records</h2>
203
+ <button type="button" className="cg-import-x" aria-label="Close" onClick={onClose}>
204
+ Γ—
205
+ </button>
206
+ </div>
207
+
208
+ {!parsed ? (
209
+ <div className="cg-import-body">
210
+ <p className="cg-import-lede">
211
+ Add records to <strong>{tableName}</strong> from a spreadsheet. Excel
212
+ (<code>.xlsx</code>) or <code>.csv</code>, up to 5&nbsp;MB.
213
+ </p>
214
+ <p className="cg-import-note">
215
+ Every row becomes a <strong>new record</strong>. Nothing already in this database is
216
+ matched or overwritten.
217
+ </p>
218
+ <input
219
+ ref={fileRef}
220
+ type="file"
221
+ accept=".xlsx,.csv"
222
+ className="cg-import-file"
223
+ onChange={(event) => {
224
+ const file = event.currentTarget.files?.[0];
225
+ if (file) void pick(file);
226
+ }}
227
+ />
228
+ </div>
229
+ ) : (
230
+ <div className="cg-import-body">
231
+ <p className="cg-import-lede">
232
+ {parsed.rows.toLocaleString()} row{parsed.rows === 1 ? "" : "s"} read
233
+ {parsed.truncated ? " (the first 20,000 β€” the rest were not read)" : ""}. Choose
234
+ where each column goes.
235
+ </p>
236
+ <div className="cg-import-map" role="list">
237
+ {parsed.columns.map((name, i) => (
238
+ <label className="cg-import-row" role="listitem" key={`${name}:${i}`}>
239
+ <span className="cg-import-col" title={name}>
240
+ {name || `Column ${i + 1}`}
241
+ </span>
242
+ <select
243
+ value={mapping[i] ?? NONE}
244
+ onChange={(event) => {
245
+ const next = event.target.value;
246
+ setMapping((cur) => ({ ...cur, [i]: next }));
247
+ }}
248
+ >
249
+ <option value={NONE}>Don&rsquo;t import</option>
250
+ {targets.map((f) => (
251
+ <option key={f.key} value={f.key}>
252
+ {f.label}
253
+ </option>
254
+ ))}
255
+ </select>
256
+ </label>
257
+ ))}
258
+ </div>
259
+ {plan.problems.length > 0 && (
260
+ <div className="cg-import-problems" role="alert">
261
+ <strong>
262
+ {plan.problems.length.toLocaleString()} value
263
+ {plan.problems.length === 1 ? "" : "s"} cannot go in the column
264
+ {plan.problems.length === 1 ? "" : "s"} chosen for them
265
+ </strong>
266
+ <ul>
267
+ {plan.problems.slice(0, 5).map((p, i) => (
268
+ <li key={i}>
269
+ Row {p.row}, {p.column}: {p.value ? `β€œ${p.value}”` : "(blank)"} is not a
270
+ valid {p.field}
271
+ </li>
272
+ ))}
273
+ </ul>
274
+ {plan.problems.length > 5 && (
275
+ <p>…and {(plan.problems.length - 5).toLocaleString()} more.</p>
276
+ )}
277
+ <p>
278
+ Fix them in the file, or point that column somewhere else β€” nothing has been
279
+ imported yet.
280
+ </p>
281
+ </div>
282
+ )}
283
+ </div>
284
+ )}
285
+
286
+ {error && (
287
+ <p className="cg-import-error" role="alert">
288
+ {error}
289
+ </p>
290
+ )}
291
+
292
+ <div className="cg-import-foot">
293
+ {parsed && (
294
+ <span className="cg-import-count">
295
+ {mappedCount === 0
296
+ ? "No columns chosen yet"
297
+ : `${plan.rows.length.toLocaleString()} record${
298
+ plan.rows.length === 1 ? "" : "s"
299
+ } from ${mappedCount} column${mappedCount === 1 ? "" : "s"}`}
300
+ </span>
301
+ )}
302
+ <button type="button" className="cg-btn" onClick={onClose}>
303
+ Cancel
304
+ </button>
305
+ {parsed && (
306
+ <button
307
+ type="button"
308
+ className="cg-btn cg-btn--primary"
309
+ /* β›” DISABLED WHILE ANY VALUE IS REFUSED. The alternative β€” import the good rows and
310
+ report the rest β€” leaves somebody reconciling a spreadsheet against a table by
311
+ hand, and neither existing write door demonstrates a partial policy. Refusing
312
+ whole is recoverable in one edit; a half-import is not. */
313
+ disabled={busy || plan.rows.length === 0 || plan.problems.length > 0}
314
+ onClick={() => void run()}
315
+ >
316
+ {busy ? "Importing…" : `Import ${plan.rows.length.toLocaleString()} record${
317
+ plan.rows.length === 1 ? "" : "s"
318
+ }`}
319
+ </button>
320
+ )}
321
+ </div>
322
+ </div>
323
+ </div>
324
+ );
325
+ }
web/src/customer-grid/MapView.tsx CHANGED
@@ -41,6 +41,7 @@ import {
41
  BASEMAP_DETAIL_K,
42
  bubbleRadius,
43
  cardBox,
 
44
  dashPattern,
45
  fitView,
46
  fromScreen,
@@ -53,7 +54,9 @@ import {
53
  haversineKm,
54
  isPlottable,
55
  normRect,
 
56
  planRoute,
 
57
  project,
58
  toScreen,
59
  unproject,
@@ -154,7 +157,19 @@ export function MapView({
154
  const [roundTrip, setRoundTrip] = useState(false);
155
  const [routeStartPid, setRouteStartPid] = useState<number | null>(null);
156
  const [view, setView] = useState<View | null>(null);
157
- const [drag, setDrag] = useState<{ x0: number; y0: number; x1: number; y1: number } | null>(null);
 
 
 
 
 
 
 
 
 
 
 
 
158
  /**
159
  * ⚠ The svg element lives in STATE, not in a ref, and that is load-bearing.
160
  *
@@ -328,15 +343,20 @@ export function MapView({
328
  [sizeField, sizeRange]
329
  );
330
 
331
- /** Client coords -> the SVG's own user-space coords (the viewBox scales). */
 
 
 
 
 
 
 
 
 
332
  const localPoint = useCallback(
333
  (clientX: number, clientY: number): Pt => {
334
  if (!svgEl) return { x: 0, y: 0 };
335
- const r = svgEl.getBoundingClientRect();
336
- return {
337
- x: ((clientX - r.left) / r.width) * VIEW_W,
338
- y: ((clientY - r.top) / r.height) * VIEW_H,
339
- };
340
  },
341
  [svgEl]
342
  );
@@ -417,10 +437,11 @@ export function MapView({
417
  // Shift (or Ctrl/Cmd) turns the drag into a SELECTION rectangle; a plain
418
  // drag pans. Both gestures are on the same button because a map that
419
  // needs a mode toggle to select is a map people never select on.
420
- if (e.shiftKey || e.ctrlKey || e.metaKey) setDrag({ x0: x, y0: y, x1: x, y1: y });
 
421
  else panRef.current = { x, y, tx: view.tx, ty: view.ty };
422
  },
423
- [view, localPoint]
424
  );
425
 
426
  const onPointerMove = useCallback(
@@ -428,7 +449,18 @@ export function MapView({
428
  const { x, y } = localPoint(e.clientX, e.clientY);
429
  if (drag) {
430
  movedRef.current = true;
431
- setDrag((d) => (d ? { ...d, x1: x, y1: y } : d));
 
 
 
 
 
 
 
 
 
 
 
432
  return;
433
  }
434
  const pan = panRef.current;
@@ -443,14 +475,24 @@ export function MapView({
443
  const onPointerUp = useCallback(
444
  (e: ReactPointerEvent<SVGSVGElement>) => {
445
  if (drag && view) {
446
- const r = normRect(drag.x0, drag.y0, drag.x1, drag.y1);
447
- // A rectangle smaller than a few px is a mis-click, not a selection β€”
448
  // clearing the user's set on a stray shift-click would be its own bug.
449
- if (r.x1 - r.x0 > 3 && r.y1 - r.y0 > 3) {
 
 
 
 
 
 
 
450
  const hits: number[] = [];
451
  for (const p of points) {
452
  const s = toScreen(p.p, view);
453
- if (s.x >= r.x0 && s.x <= r.x1 && s.y >= r.y0 && s.y <= r.y1) hits.push(p.pid);
 
 
 
 
454
  }
455
  onSelectPids(hits, e.altKey ? "add" : "replace");
456
  }
@@ -474,7 +516,8 @@ export function MapView({
474
  }
475
 
476
  const hovered = hoverPid != null ? points.find((p) => p.pid === hoverPid) : undefined;
477
- const rect = drag ? normRect(drag.x0, drag.y0, drag.x1, drag.y1) : null;
 
478
  const tf = `translate(${view.tx.toFixed(2)} ${view.ty.toFixed(2)}) scale(${view.k.toFixed(6)})`;
479
  // Strokes live in the transformed group, so they are pre-divided by the zoom.
480
  // ⚠ This is the map's ONE stroke mechanism β€” see the note over `hairline` in
@@ -630,8 +673,13 @@ export function MapView({
630
  )}
631
  </span>
632
  )}
 
 
 
 
633
  <span className="cg-map-hint">
634
- Scroll to zoom Β· drag to pan Β· shift-drag to select
 
635
  </span>
636
  </div>
637
  <div
@@ -801,6 +849,16 @@ export function MapView({
801
  height={rect.y1 - rect.y0}
802
  />
803
  )}
 
 
 
 
 
 
 
 
 
 
804
  </svg>
805
 
806
  {/* --- I18 β€” the camera controls. Zoom in / zoom out / fit to data, the
@@ -850,6 +908,35 @@ export function MapView({
850
  <path d="M6.6 8h2.8M8 6.6v2.8" />
851
  </svg>
852
  </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
853
  {/* The street-level hand-off, aimed at whatever is on screen right
854
  now. This is what makes the zoom cap honest rather than merely
855
  restrictive: the map stops where its geometry stops, and points at
 
41
  BASEMAP_DETAIL_K,
42
  bubbleRadius,
43
  cardBox,
44
+ clientToUser,
45
  dashPattern,
46
  fitView,
47
  fromScreen,
 
54
  haversineKm,
55
  isPlottable,
56
  normRect,
57
+ pathBounds,
58
  planRoute,
59
+ pointInPolygon,
60
  project,
61
  toScreen,
62
  unproject,
 
157
  const [roundTrip, setRoundTrip] = useState(false);
158
  const [routeStartPid, setRouteStartPid] = useState<number | null>(null);
159
  const [view, setView] = useState<View | null>(null);
160
+ /**
161
+ * The selection gesture in flight. Two shapes, never a mode for SELECTING
162
+ * itself: shift-drag always selects, and `lassoTool` only changes what it
163
+ * draws. That distinction is why the "no mode toggle" note over `onPointerDown`
164
+ * still holds β€” the thing people would never find behind a mode is selection,
165
+ * and it is still on the bare gesture.
166
+ */
167
+ const [drag, setDrag] = useState<
168
+ | { kind: "rect"; x0: number; y0: number; x1: number; y1: number }
169
+ | { kind: "lasso"; pts: Pt[] }
170
+ | null
171
+ >(null);
172
+ const [lassoTool, setLassoTool] = useState(false);
173
  /**
174
  * ⚠ The svg element lives in STATE, not in a ref, and that is load-bearing.
175
  *
 
343
  [sizeField, sizeRange]
344
  );
345
 
346
+ /**
347
+ * Client coords -> the svg's own user-space coords.
348
+ *
349
+ * ⚠ The maths lives in `clientToUser` (mapProjection) rather than here, and
350
+ * that placement is the fix's other half. Wave 8 wrote the conversion inline
351
+ * in this .tsx β€” where the gate's negative controls, every one of which
352
+ * mutates the compiled `mapProjection.js`, could not reach it. So the box-
353
+ * select legs passed on coordinates handed to them ALREADY in user space, and
354
+ * a broken conversion shipped green for four waves. See `clientToUser`.
355
+ */
356
  const localPoint = useCallback(
357
  (clientX: number, clientY: number): Pt => {
358
  if (!svgEl) return { x: 0, y: 0 };
359
+ return clientToUser(clientX, clientY, svgEl.getBoundingClientRect(), VIEW_W, VIEW_H);
 
 
 
 
360
  },
361
  [svgEl]
362
  );
 
437
  // Shift (or Ctrl/Cmd) turns the drag into a SELECTION rectangle; a plain
438
  // drag pans. Both gestures are on the same button because a map that
439
  // needs a mode toggle to select is a map people never select on.
440
+ if (e.shiftKey || e.ctrlKey || e.metaKey)
441
+ setDrag(lassoTool ? { kind: "lasso", pts: [{ x, y }] } : { kind: "rect", x0: x, y0: y, x1: x, y1: y });
442
  else panRef.current = { x, y, tx: view.tx, ty: view.ty };
443
  },
444
+ [view, localPoint, lassoTool]
445
  );
446
 
447
  const onPointerMove = useCallback(
 
449
  const { x, y } = localPoint(e.clientX, e.clientY);
450
  if (drag) {
451
  movedRef.current = true;
452
+ setDrag((d) => {
453
+ if (!d) return d;
454
+ if (d.kind === "rect") return { ...d, x1: x, y1: y };
455
+ // `pointermove` fires far faster than a loop needs vertices, so a slow
456
+ // hand tracing 200 px would otherwise build a thousand-point polygon
457
+ // that every pin is then tested against on every frame. Drop a sample
458
+ // that has not travelled ~2 px β€” the viewBox is fixed relative to the
459
+ // screen, so this threshold means the same thing at every zoom.
460
+ const last = d.pts[d.pts.length - 1];
461
+ if (Math.abs(x - last.x) + Math.abs(y - last.y) < 2) return d;
462
+ return { kind: "lasso", pts: [...d.pts, { x, y }] };
463
+ });
464
  return;
465
  }
466
  const pan = panRef.current;
 
475
  const onPointerUp = useCallback(
476
  (e: ReactPointerEvent<SVGSVGElement>) => {
477
  if (drag && view) {
478
+ // A gesture smaller than a few px is a mis-click, not a selection β€”
 
479
  // clearing the user's set on a stray shift-click would be its own bug.
480
+ // ONE rule for both shapes, measured on the lasso's own bounds; a loop
481
+ // also needs three points before it is a polygon at all.
482
+ const b =
483
+ drag.kind === "rect"
484
+ ? normRect(drag.x0, drag.y0, drag.x1, drag.y1)
485
+ : pathBounds(drag.pts);
486
+ const drawn = b.x1 - b.x0 > 3 && b.y1 - b.y0 > 3 && (drag.kind === "rect" || drag.pts.length >= 3);
487
+ if (drawn) {
488
  const hits: number[] = [];
489
  for (const p of points) {
490
  const s = toScreen(p.p, view);
491
+ const held =
492
+ drag.kind === "rect"
493
+ ? s.x >= b.x0 && s.x <= b.x1 && s.y >= b.y0 && s.y <= b.y1
494
+ : pointInPolygon(s, drag.pts);
495
+ if (held) hits.push(p.pid);
496
  }
497
  onSelectPids(hits, e.altKey ? "add" : "replace");
498
  }
 
516
  }
517
 
518
  const hovered = hoverPid != null ? points.find((p) => p.pid === hoverPid) : undefined;
519
+ const rect = drag?.kind === "rect" ? normRect(drag.x0, drag.y0, drag.x1, drag.y1) : null;
520
+ const lassoPts = drag?.kind === "lasso" && drag.pts.length > 1 ? drag.pts : null;
521
  const tf = `translate(${view.tx.toFixed(2)} ${view.ty.toFixed(2)}) scale(${view.k.toFixed(6)})`;
522
  // Strokes live in the transformed group, so they are pre-divided by the zoom.
523
  // ⚠ This is the map's ONE stroke mechanism β€” see the note over `hairline` in
 
673
  )}
674
  </span>
675
  )}
676
+ {/* Every gesture the map has, named. `alt` (add to the selection rather
677
+ than replace it, onPointerUp) shipped in wave 8 and was disclosed
678
+ NOWHERE, so "select these as well" was a feature only the source
679
+ knew about. It needs shift too β€” alt alone still pans. */}
680
  <span className="cg-map-hint">
681
+ Scroll to zoom Β· drag to pan Β· {lassoTool ? "shift-drag to lasso" : "shift-drag to select"}{" "}
682
+ Β· shift-alt-drag to extend the selection
683
  </span>
684
  </div>
685
  <div
 
849
  height={rect.y1 - rect.y0}
850
  />
851
  )}
852
+ {/* The loop paints as a POLYGON, so the shape on screen is the shape
853
+ the hit test uses β€” an open <polyline> would draw a mouth the
854
+ selection does not have. Same class as the rectangle: one marquee
855
+ look, and no new stylesheet rule (index.css is not this fence). */}
856
+ {lassoPts && (
857
+ <polygon
858
+ className="cg-map-marquee"
859
+ points={lassoPts.map((p) => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(" ")}
860
+ />
861
+ )}
862
  </svg>
863
 
864
  {/* --- I18 β€” the camera controls. Zoom in / zoom out / fit to data, the
 
908
  <path d="M6.6 8h2.8M8 6.6v2.8" />
909
  </svg>
910
  </button>
911
+ {/* The selection SHAPE. Not a mode for selecting β€” shift-drag selects
912
+ either way β€” so the note over `onPointerDown` still stands. The
913
+ icon shows the shape you will get, which is the only "on" state
914
+ available: `.cg-map-ctl-b` has no pressed style and index.css
915
+ belongs to another session this wave, so a pressed look would have
916
+ been a control that cannot show its own state. */}
917
+ <button
918
+ type="button"
919
+ className="cg-map-ctl-b"
920
+ title={
921
+ lassoTool
922
+ ? "Selection shape: lasso - shift-drag traces a freehand loop. Click for a rectangle."
923
+ : "Selection shape: rectangle - shift-drag draws a box. Click for a freehand lasso."
924
+ }
925
+ aria-label="Selection shape"
926
+ aria-pressed={lassoTool}
927
+ onClick={() => setLassoTool((v) => !v)}
928
+ >
929
+ {lassoTool ? (
930
+ <svg viewBox="0 0 16 16" aria-hidden="true">
931
+ <path d="M12.1 6.2c1.1 1.6.3 3.5-1.9 4.4-2.4 1-5.5.5-6.7-1.1-1-1.4-.1-3.1 2-3.9 2.2-.8 4.9-.5 6.1.6" />
932
+ <path d="M4.9 10.3 4.2 13.4" />
933
+ </svg>
934
+ ) : (
935
+ <svg viewBox="0 0 16 16" aria-hidden="true">
936
+ <path d="M3.2 4.4h9.6v7.2H3.2z" />
937
+ </svg>
938
+ )}
939
+ </button>
940
  {/* The street-level hand-off, aimed at whatever is on screen right
941
  now. This is what makes the zoom cap honest rather than merely
942
  restrictive: the map stops where its geometry stops, and points at
web/src/customer-grid/RecordDetail.tsx CHANGED
@@ -47,7 +47,21 @@ import {
47
  toggleMulti,
48
  userInitials,
49
  } from "./recordFields";
50
- import { pickTint } from "./choiceColors";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
51
  // Wave-19 R7 β€” ONE asset resolver and ONE upload path, shared with the catalog. A second URL
52
  // builder here is how the modal and the printed page would disagree about a row's picture.
53
  import { assetUrl, uploadRecordImage } from "./catalogData";
@@ -741,10 +755,27 @@ export default function RecordDetail({
741
  {field.type === "user" && current !== "" && (
742
  <UserAvatar name={current} avatars={userAvatars} />
743
  )}
 
 
 
 
 
 
744
  <select
745
  id={inputId}
746
  className="cg-detail-select"
747
  value={current}
 
 
 
 
 
 
 
 
 
 
 
748
  onChange={(event) => onNotesCommit(field.key, event.target.value)}
749
  >
750
  <option value="">
@@ -780,11 +811,24 @@ export default function RecordDetail({
780
  <span className="cg-detail-chips">
781
  {entries.map((entry) => {
782
  const on = held.includes(entry.value);
 
 
 
 
783
  return (
784
  <button
785
  key={entry.value}
786
  type="button"
787
  className={"cg-detail-chip" + (on ? " is-on" : "")}
 
 
 
 
 
 
 
 
 
788
  aria-pressed={on}
789
  title={entry.stale ? "No longer a choice on this field" : undefined}
790
  onClick={() =>
 
47
  toggleMulti,
48
  userInitials,
49
  } from "./recordFields";
50
+ /**
51
+ * ⭐⭐ WAVE-29 T24 (owner item 13, and D-121's class) β€” the record panel READS THE OPTION COLOURS.
52
+ *
53
+ * The canvas has honoured them since wave 14 (`cells.optionTint`) and so has the kanban card
54
+ * (`viewModes.tsx`), while this panel painted every chosen chip the same fixed blue and every
55
+ * single-select as an unstyled native `<select>` β€” so the SAME record showed a colour-coded
56
+ * status in the grid and a colourless one the moment somebody opened it. That is D-121 exactly
57
+ * (the record panel ignoring a field's format while the canvas honours it), one property along.
58
+ *
59
+ * ⚠ `optionTint` is THE resolver and it is not called twice: it already answers "colour coding is
60
+ * switched off" with `undefined`, in which case no inline style is set and the stylesheet's
61
+ * neutral chip is what paints. `optionBorderColor` is the same darkened companion the canvas
62
+ * draws its outline with, so a chip here and a bubble there cannot drift apart.
63
+ */
64
+ import { optionBorderColor, optionTint, pickTint } from "./choiceColors";
65
  // Wave-19 R7 β€” ONE asset resolver and ONE upload path, shared with the catalog. A second URL
66
  // builder here is how the modal and the printed page would disagree about a row's picture.
67
  import { assetUrl, uploadRecordImage } from "./catalogData";
 
755
  {field.type === "user" && current !== "" && (
756
  <UserAvatar name={current} avatars={userAvatars} />
757
  )}
758
+ {/* T24: the control wears the SELECTED option's colour. An `<option>` cannot be
759
+ styled portably (the same platform limit this block already records for avatars),
760
+ so the colour goes on the box β€” which is where the reader is looking anyway, and
761
+ matches what the canvas paints for the same cell. `user` columns are excluded: a
762
+ person is not a choice with a palette, and `optionTint` would hash a name into
763
+ one. */}
764
  <select
765
  id={inputId}
766
  className="cg-detail-select"
767
  value={current}
768
+ style={
769
+ field.type === "select"
770
+ ? (() => {
771
+ const tint = optionTint(field, current);
772
+ return tint
773
+ ? { background: tint.bg, color: tint.fg,
774
+ borderColor: optionBorderColor(tint.bg) }
775
+ : undefined;
776
+ })()
777
+ : undefined
778
+ }
779
  onChange={(event) => onNotesCommit(field.key, event.target.value)}
780
  >
781
  <option value="">
 
811
  <span className="cg-detail-chips">
812
  {entries.map((entry) => {
813
  const on = held.includes(entry.value);
814
+ // T24: the HELD chips wear the option's own colour; an unheld one stays neutral,
815
+ // because tinting every choice would make "which of these is on" a judgement
816
+ // about saturation rather than a state you can read.
817
+ const tint = on ? optionTint(field, entry.value) : undefined;
818
  return (
819
  <button
820
  key={entry.value}
821
  type="button"
822
  className={"cg-detail-chip" + (on ? " is-on" : "")}
823
+ style={
824
+ tint
825
+ ? {
826
+ background: tint.bg,
827
+ color: tint.fg,
828
+ borderColor: optionBorderColor(tint.bg),
829
+ }
830
+ : undefined
831
+ }
832
  aria-pressed={on}
833
  title={entry.stale ? "No longer a choice on this field" : undefined}
834
  onClick={() =>
web/src/customer-grid/SwipeView.css ADDED
@@ -0,0 +1,25 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+
2
+ /* ⭐⭐ WAVE-29 T26 (owner R9) β€” the card renders the RECORD: fields, attachments, comments.
3
+ The card was a title plus three cells and could stay any height it liked; carrying a whole
4
+ record it needs a ceiling and a scroll of its own, or the deck's own controls (Later, the two
5
+ decision buttons) leave the viewport on a record with twenty columns. */
6
+ .cg-swipe-card {
7
+ max-height: min(62vh, 560px);
8
+ overflow-y: auto;
9
+ }
10
+
11
+ /* Both sections are INSIDE the card, which is a `role="button"`. They stop their own events, so
12
+ the separation has to read visually too β€” otherwise a reviewer cannot tell what will open the
13
+ record and what will not. */
14
+ .cg-swipe-docs,
15
+ .cg-swipe-comments {
16
+ margin-top: 10px;
17
+ padding-top: 8px;
18
+ border-top: 1px solid var(--lp-line);
19
+ cursor: default;
20
+ }
21
+
22
+ /* The comments box carries its own composer; the card's own padding would double it. */
23
+ .cg-swipe-comments {
24
+ text-align: left;
25
+ }
web/src/customer-grid/SwipeView.tsx CHANGED
@@ -1,476 +1,562 @@
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
- import { choiceOptions } from "./types";
30
- import type { DisplaySpec, Field, Row } from "./types";
31
- import { formatDisplay } from "./cells";
32
- import { actionHref } from "./display";
33
- import { optionTint } from "./choiceColors";
34
- import { ModeIcon } from "./icons";
35
-
36
- export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
37
-
38
- /** The three ways a stored binding can rot that the host cannot see (see the header note). */
39
- type BindingFault =
40
- | { kind: "unbound" }
41
- | { kind: "field-gone"; fieldKey: string }
42
- | { kind: "not-select"; field: Field }
43
- | { kind: "option-gone"; field: Field; missing: string[] };
44
-
45
- function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
46
- { ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
47
- if (!spec) return { ok: false, fault: { kind: "unbound" } };
48
- const field = fieldByKey.get(spec.fieldKey);
49
- if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
50
- // R2 β€” SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
51
- // so "write this option" would mean append-or-replace, and a triage gesture that sometimes
52
- // adds and sometimes overwrites is two gestures wearing one button.
53
- if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
54
- const options = choiceOptions(field);
55
- const has = new Set(options.map((o) => o.toLowerCase()));
56
- const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
57
- if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
58
- return { ok: true, field, spec };
59
- }
60
-
61
- /** The bound cell is EMPTY β€” the one predicate that decides deck membership (R2). */
62
- const isUndecided = (row: Row, key: string): boolean =>
63
- String(row[key] ?? "").trim() === "";
64
-
65
- export function SwipeView({
66
- rows,
67
- fields,
68
- fieldByKey,
69
- spec,
70
- cardKeys,
71
- titleKey,
72
- canWrite,
73
- readOnlyReason,
74
- canBind,
75
- onSpec,
76
- onSwipe,
77
- onOpen,
78
- }: {
79
- /** DISTINCT data rows from the full pipeline, overlay edits layered β€” the kanban's contract.
80
- * The deck re-derives from these, so a written record leaves it as soon as the optimistic
81
- * patch lands; there is no local cursor to drift out of step with the data. */
82
- rows: Row[];
83
- /** Every field, for the picker's field list. */
84
- fields: Field[];
85
- fieldByKey: Map<string, Field>;
86
- /** The stored binding, or undefined for a deck nobody has configured yet. */
87
- spec: SwipeSpec | undefined;
88
- /** The handful of visible fields the card lists under its title. */
89
- cardKeys: string[];
90
- titleKey: string;
91
- /** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
92
- canWrite: boolean;
93
- /** Stated when the deck cannot be decided β€” permissions, or a computed column. */
94
- readOnlyReason: string | null;
95
- /** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
96
- * view-editing permission and NOT `canWrite` β€” conflating the two is
97
- * [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
98
- * nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
99
- canBind: boolean;
100
- /** `undefined` DELETES the binding β€” absent is the honest unconfigured state, and storing a
101
- * half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
102
- onSpec: (next: SwipeSpec | undefined) => void;
103
- onSwipe: (pid: number, value: string) => void;
104
- onOpen: (pid: number) => void;
105
- }) {
106
- // "Later" β€” session-only, never stored. A deck with no way past a record you cannot decide
107
- // blocks on that record forever, so this is navigation WITHIN the deck rather than a third
108
- // gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
109
- // state rather than quietly shrinking the deck (rule 8b).
110
- const [later, setLater] = useState<Set<number>>(new Set());
111
- const deckRef = useRef<HTMLDivElement>(null);
112
-
113
- const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
114
- const boundKey = binding.ok ? binding.field.key : null;
115
-
116
- const undecided = useMemo(
117
- () => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
118
- [rows, boundKey]
119
- );
120
- const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
121
- const card = deck[0];
122
-
123
- // A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β€”
124
- // otherwise the disclosed skip count drifts away from what is actually on the deck.
125
- useEffect(() => {
126
- setLater((prev) => {
127
- if (prev.size === 0) return prev;
128
- const live = new Set(undecided.map((r) => r.pid));
129
- const next = new Set([...prev].filter((pid) => live.has(pid)));
130
- return next.size === prev.size ? prev : next;
131
- });
132
- }, [undecided]);
133
-
134
- const decide = useCallback(
135
- (value: string) => {
136
- if (!card || !canWrite) return;
137
- onSwipe(card.pid, value);
138
- },
139
- [card, canWrite, onSwipe]
140
- );
141
-
142
- // ← / β†’ decide, and they are the SAME two actions the buttons are rather than a second code
143
- // path: the whole point of the mode is that one hand can clear a queue.
144
- useEffect(() => {
145
- if (!binding.ok || !canWrite || !card) return;
146
- const onKey = (e: KeyboardEvent) => {
147
- if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
148
- const el = document.activeElement as HTMLElement | null;
149
- // Never steal an arrow key from a text field or a native control the user is inside.
150
- if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
151
- return;
152
- if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
153
- e.preventDefault();
154
- decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
155
- };
156
- window.addEventListener("keydown", onKey);
157
- return () => window.removeEventListener("keydown", onKey);
158
- }, [binding, canWrite, card, decide]);
159
-
160
- if (!binding.ok) {
161
- return (
162
- <div className="cg-swipe" ref={deckRef}>
163
- <SwipeBinder
164
- fault={binding.fault}
165
- fields={fields}
166
- fieldByKey={fieldByKey}
167
- spec={spec}
168
- canBind={canBind}
169
- onSpec={onSpec}
170
- />
171
- </div>
172
- );
173
- }
174
-
175
- const { field } = binding;
176
- const leftTint = optionTint(field, binding.spec.leftOption);
177
- const rightTint = optionTint(field, binding.spec.rightOption);
178
-
179
- return (
180
- <div className="cg-swipe" ref={deckRef} tabIndex={-1}>
181
- <div className="cg-swipe-bar">
182
- <span className="cg-swipe-bound">
183
- <ModeIcon mode="swipe" />
184
- Sorting into <strong>{field.label}</strong>
185
- </span>
186
- <span className="cg-swipe-left">
187
- {deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
188
- </span>
189
- {canBind && (
190
- <button
191
- type="button"
192
- className="cg-link-btn"
193
- onClick={() => onSpec(undefined)}
194
- title="Choose a different field or different options for this deck"
195
- >
196
- Change
197
- </button>
198
- )}
199
- </div>
200
- {readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
201
- {card ? (
202
- <div className="cg-swipe-deck">
203
- <button
204
- type="button"
205
- className="cg-swipe-side cg-swipe-side--left"
206
- disabled={!canWrite}
207
- style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
208
- onClick={() => decide(binding.spec.leftOption)}
209
- title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
210
- >
211
- <span aria-hidden className="cg-swipe-arrow">
212
- <svg width="16" height="16" viewBox="0 0 16 16">
213
- <path
214
- d="M11 3.2 6.2 8l4.8 4.8"
215
- fill="none"
216
- stroke="currentColor"
217
- strokeWidth="1.6"
218
- strokeLinecap="round"
219
- strokeLinejoin="round"
220
- />
221
- </svg>
222
- </span>
223
- {binding.spec.leftOption}
224
- </button>
225
- <article
226
- className="cg-swipe-card"
227
- role="button"
228
- tabIndex={0}
229
- onClick={() => onOpen(card.pid)}
230
- onKeyDown={(e) => {
231
- if (e.key !== "Enter" && e.key !== " ") return;
232
- e.preventDefault();
233
- onOpen(card.pid);
234
- }}
235
- >
236
- <h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
237
- <div className="cg-swipe-cells">
238
- {cardKeys.map((k) => {
239
- const f = fieldByKey.get(k);
240
- if (!f) return null;
241
- const text = formatDisplay(f, card[k]);
242
- if (!text) return null;
243
- // A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
244
- // scheme guard β€” and every gesture that reaches it must be stopped from also
245
- // reaching the card, which is a button (the kanban card's note, same trap).
246
- const href = actionHref(f, card[k]);
247
- return (
248
- <div key={k} className="cg-swipe-cell">
249
- <span className="cg-lv-k">{f.label}</span>
250
- {href ? (
251
- <a
252
- className="cg-lv-v"
253
- href={href}
254
- target="_blank"
255
- rel="noopener noreferrer"
256
- title={text}
257
- onClick={(e) => e.stopPropagation()}
258
- onKeyDown={(e) => e.stopPropagation()}
259
- >
260
- {text}
261
- </a>
262
- ) : (
263
- <span className="cg-lv-v">{text}</span>
264
- )}
265
- </div>
266
- );
267
- })}
268
- </div>
269
- {canWrite && (
270
- <button
271
- type="button"
272
- className="cg-link-btn cg-swipe-later"
273
- onClick={(e) => {
274
- e.stopPropagation();
275
- setLater((prev) => new Set(prev).add(card.pid));
276
- }}
277
- >
278
- Decide later
279
- </button>
280
- )}
281
- </article>
282
- <button
283
- type="button"
284
- className="cg-swipe-side cg-swipe-side--right"
285
- disabled={!canWrite}
286
- style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
287
- onClick={() => decide(binding.spec.rightOption)}
288
- title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
289
- >
290
- {binding.spec.rightOption}
291
- <span aria-hidden className="cg-swipe-arrow">
292
- <svg width="16" height="16" viewBox="0 0 16 16">
293
- <path
294
- d="M5 3.2 9.8 8 5 12.8"
295
- fill="none"
296
- stroke="currentColor"
297
- strokeWidth="1.6"
298
- strokeLinecap="round"
299
- strokeLinejoin="round"
300
- />
301
- </svg>
302
- </span>
303
- </button>
304
- </div>
305
- ) : (
306
- // The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
307
- // between "the deck is finished" and "the filter hid everything", and the two want
308
- // different next actions. `later` is disclosed rather than quietly subtracted.
309
- <div className="cg-mode-empty cg-swipe-empty">
310
- {later.size > 0 ? (
311
- <>
312
- <p>
313
- {later.size.toLocaleString()}{" "}
314
- {later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
315
- in this view is missing a <strong>{field.label}</strong>.
316
- </p>
317
- <button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
318
- Bring them back
319
- </button>
320
- </>
321
- ) : (
322
- <p>
323
- Every record in this view already has a <strong>{field.label}</strong>. Widen the
324
- view's filters to sort more.
325
- </p>
326
- )}
327
- </div>
328
- )}
329
- </div>
330
- );
331
- }
332
-
333
- /**
334
- * The binding picker: field + two options. It is also the surface every LOST binding lands on,
335
- * with the loss stated above it β€” one place that answers "what is this deck for", rather than an
336
- * error screen beside a separate setup screen.
337
- */
338
- function SwipeBinder({
339
- fault,
340
- fields,
341
- fieldByKey,
342
- spec,
343
- canBind,
344
- onSpec,
345
- }: {
346
- fault: BindingFault;
347
- fields: Field[];
348
- fieldByKey: Map<string, Field>;
349
- spec: SwipeSpec | undefined;
350
- canBind: boolean;
351
- onSpec: (next: SwipeSpec | undefined) => void;
352
- }) {
353
- const selects = useMemo(
354
- () => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
355
- [fields]
356
- );
357
- const [fieldKey, setFieldKey] = useState<string>(() => {
358
- if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
359
- return selects[0]?.key ?? "";
360
- });
361
- const chosen = fieldByKey.get(fieldKey);
362
- const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
363
- const [left, setLeft] = useState<string>("");
364
- const [right, setRight] = useState<string>("");
365
-
366
- // The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
367
- // pick survives re-renders, and reset whenever the field changes β€” carrying an option from the
368
- // previous field would offer a value the new field cannot hold.
369
- useEffect(() => {
370
- setLeft(options[0] ?? "");
371
- setRight(options.find((o) => o !== options[0]) ?? "");
372
- }, [options]);
373
-
374
- const message = ((): string => {
375
- switch (fault.kind) {
376
- case "field-gone":
377
- return "The field this deck sorted into has been deleted. Pick another one.";
378
- case "not-select":
379
- return `β€œ${fault.field.label}” is no longer a single-select, so it has no options to`
380
- + " sort into. Pick another field.";
381
- case "option-gone":
382
- return `${fault.missing.map((m) => `β€œ${m}”`).join(" and ")} ${
383
- fault.missing.length === 1 ? "is" : "are"
384
- } no longer ${fault.missing.length === 1 ? "an option" : "options"} on β€œ${
385
- fault.field.label
386
- }”. Pick the sides again.`;
387
- default:
388
- return "Sort records one at a time into two options of a single-select field.";
389
- }
390
- })();
391
-
392
- if (!canBind) {
393
- return (
394
- <div className="cg-mode-empty">
395
- <p>{message}</p>
396
- <p>Its creator or an admin can set this view up.</p>
397
- </div>
398
- );
399
- }
400
- if (selects.length === 0) {
401
- // Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
402
- // requirement is what turns a dead end into a next action.
403
- return (
404
- <div className="cg-mode-empty">
405
- <p>
406
- A swipe deck sorts into a single-select field with at least two options. This database
407
- does not have one yet β€” add a single-select column, then come back.
408
- </p>
409
- </div>
410
- );
411
- }
412
- const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
413
- return (
414
- <div className="cg-swipe-setup">
415
- <p className="cg-swipe-setup-note">{message}</p>
416
- <label className="cg-swipe-setup-row">
417
- <span>Sort into</span>
418
- <select
419
- className="cg-select"
420
- value={fieldKey}
421
- onChange={(e) => setFieldKey(e.target.value)}
422
- >
423
- {/* Every option carries an explicit `value`: a <select> whose value names nothing
424
- renders its FIRST option and reports a choice the user never made
425
- ([[cg-condition-builder-items]]). */}
426
- {selects.map((f) => (
427
- <option key={f.key} value={f.key}>
428
- {f.label}
429
- </option>
430
- ))}
431
- </select>
432
- </label>
433
- <div className="cg-swipe-setup-sides">
434
- <label className="cg-swipe-setup-row">
435
- <span>Swipe left</span>
436
- <select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
437
- {options.map((o) => (
438
- <option key={o} value={o}>
439
- {o}
440
- </option>
441
- ))}
442
- </select>
443
- </label>
444
- <label className="cg-swipe-setup-row">
445
- <span>Swipe right</span>
446
- <select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
447
- {options.map((o) => (
448
- <option key={o} value={o}>
449
- {o}
450
- </option>
451
- ))}
452
- </select>
453
- </label>
454
- </div>
455
- {!ready && left && right && (
456
- // Stated, not silently refused: both engines DROP a binding whose sides are the same
457
- // option, so a Save that looked like it worked would simply not persist.
458
- <p className="cg-swipe-setup-warn">
459
- The two sides must be different options β€” otherwise both gestures do the same thing.
460
- </p>
461
- )}
462
- <button
463
- type="button"
464
- className="cg-btn cg-btn--primary"
465
- disabled={!ready}
466
- onClick={() =>
467
- chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
468
- }
469
- >
470
- Start sorting
471
- </button>
472
- </div>
473
- );
474
- }
475
-
476
- 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
+ import { choiceOptions } from "./types";
30
+ import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
31
+ // ⚠ `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
32
+ // loaded here) β€” the same import `RecordComments` takes for the same prop.
33
+ import type { SurfaceScope } from "./apiBridge";
34
+ import RecordComments from "./RecordComments";
35
+ import { Documents } from "./Documents";
36
+ import { formatDisplay } from "./cells";
37
+ import { actionHref } from "./display";
38
+ import { optionTint } from "./choiceColors";
39
+ import { ModeIcon } from "./icons";
40
+
41
+ export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
42
+
43
+ /** The three ways a stored binding can rot that the host cannot see (see the header note). */
44
+ type BindingFault =
45
+ | { kind: "unbound" }
46
+ | { kind: "field-gone"; fieldKey: string }
47
+ | { kind: "not-select"; field: Field }
48
+ | { kind: "option-gone"; field: Field; missing: string[] };
49
+
50
+ function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
51
+ { ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
52
+ if (!spec) return { ok: false, fault: { kind: "unbound" } };
53
+ const field = fieldByKey.get(spec.fieldKey);
54
+ if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
55
+ // R2 β€” SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
56
+ // so "write this option" would mean append-or-replace, and a triage gesture that sometimes
57
+ // adds and sometimes overwrites is two gestures wearing one button.
58
+ if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
59
+ const options = choiceOptions(field);
60
+ const has = new Set(options.map((o) => o.toLowerCase()));
61
+ const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
62
+ if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
63
+ return { ok: true, field, spec };
64
+ }
65
+
66
+ /** The bound cell is EMPTY β€” the one predicate that decides deck membership (R2). */
67
+ const isUndecided = (row: Row, key: string): boolean =>
68
+ String(row[key] ?? "").trim() === "";
69
+
70
+ export function SwipeView({
71
+ rows,
72
+ fields,
73
+ fieldByKey,
74
+ spec,
75
+ cardKeys,
76
+ detailKeys,
77
+ scope,
78
+ viewer,
79
+ docs,
80
+ docPayload,
81
+ onDocAdd,
82
+ onDocFetch,
83
+ onDocDelete,
84
+ titleKey,
85
+ canWrite,
86
+ readOnlyReason,
87
+ canBind,
88
+ onSpec,
89
+ onSwipe,
90
+ onOpen,
91
+ }: {
92
+ /** DISTINCT data rows from the full pipeline, overlay edits layered β€” the kanban's contract.
93
+ * The deck re-derives from these, so a written record leaves it as soon as the optimistic
94
+ * patch lands; there is no local cursor to drift out of step with the data. */
95
+ rows: Row[];
96
+ /** Every field, for the picker's field list. */
97
+ fields: Field[];
98
+ fieldByKey: Map<string, Field>;
99
+ /** The stored binding, or undefined for a deck nobody has configured yet. */
100
+ spec: SwipeSpec | undefined;
101
+ /** The handful of visible fields the card lists under its title. */
102
+ cardKeys: string[];
103
+ titleKey: string;
104
+ /** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
105
+ canWrite: boolean;
106
+ /** Stated when the deck cannot be decided β€” permissions, or a computed column. */
107
+ readOnlyReason: string | null;
108
+ /** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
109
+ * view-editing permission and NOT `canWrite` β€” conflating the two is
110
+ * [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
111
+ * nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
112
+ canBind: boolean;
113
+ /** `undefined` DELETES the binding β€” absent is the honest unconfigured state, and storing a
114
+ * half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
115
+ onSpec: (next: SwipeSpec | undefined) => void;
116
+ onSwipe: (pid: number, value: string) => void;
117
+ onOpen: (pid: number) => void;
118
+ /**
119
+ * ⭐⭐ WAVE-29 T26 (owner R9) β€” WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.
120
+ *
121
+ * R9: *"the swipe CARD itself renders the record detail inline β€” fields, comments and
122
+ * attachments β€” so a reviewer decides without leaving the deck."* Everything below is that,
123
+ * and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply
124
+ * different amounts. A card must render with none of them rather than throw β€” the standalone
125
+ * embed has no `scope`, and a deployment with no document storage serves no handlers.
126
+ */
127
+ /** Every field the VIEW shows, in its order β€” not the three-key card summary. */
128
+ detailKeys?: string[];
129
+ /** The surface these records live on. Comments are keyed by it; absent β‡’ no comments section,
130
+ * which is the pre-existing precondition `RecordDetail` already carries. */
131
+ scope?: SurfaceScope;
132
+ viewer?: Viewer;
133
+ /** This record's attachments, and the plumbing. Handlers absent β‡’ the section is not rendered
134
+ * at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app
135
+ * cannot keep). */
136
+ /** Keyed by pid, because a deck shows many records β€” `RecordDetail` takes ONE record's list
137
+ * and that shape cannot serve a deck. */
138
+ docs?: Record<string, CustomerDoc[]>;
139
+ docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };
140
+ /** ⚠ EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE
141
+ * open record. A deck paints many records at once, so a handler bound to a single pid would
142
+ * attach every reviewer's upload to whichever card happened to be open. */
143
+ onDocAdd?: (
144
+ pid: number,
145
+ file: { name: string; mime: string; size: number; data_b64: string }
146
+ ) => void;
147
+ onDocFetch?: (pid: number, docId: string) => void;
148
+ onDocDelete?: (pid: number, docId: string) => void;
149
+ }) {
150
+ // "Later" β€” session-only, never stored. A deck with no way past a record you cannot decide
151
+ // blocks on that record forever, so this is navigation WITHIN the deck rather than a third
152
+ // gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
153
+ // state rather than quietly shrinking the deck (rule 8b).
154
+ const [later, setLater] = useState<Set<number>>(new Set());
155
+ const deckRef = useRef<HTMLDivElement>(null);
156
+
157
+ const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
158
+ const boundKey = binding.ok ? binding.field.key : null;
159
+
160
+ const undecided = useMemo(
161
+ () => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
162
+ [rows, boundKey]
163
+ );
164
+ const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
165
+ const card = deck[0];
166
+
167
+ // A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β€”
168
+ // otherwise the disclosed skip count drifts away from what is actually on the deck.
169
+ useEffect(() => {
170
+ setLater((prev) => {
171
+ if (prev.size === 0) return prev;
172
+ const live = new Set(undecided.map((r) => r.pid));
173
+ const next = new Set([...prev].filter((pid) => live.has(pid)));
174
+ return next.size === prev.size ? prev : next;
175
+ });
176
+ }, [undecided]);
177
+
178
+ const decide = useCallback(
179
+ (value: string) => {
180
+ if (!card || !canWrite) return;
181
+ onSwipe(card.pid, value);
182
+ },
183
+ [card, canWrite, onSwipe]
184
+ );
185
+
186
+ // ← / β†’ decide, and they are the SAME two actions the buttons are rather than a second code
187
+ // path: the whole point of the mode is that one hand can clear a queue.
188
+ useEffect(() => {
189
+ if (!binding.ok || !canWrite || !card) return;
190
+ const onKey = (e: KeyboardEvent) => {
191
+ if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
192
+ const el = document.activeElement as HTMLElement | null;
193
+ // Never steal an arrow key from a text field or a native control the user is inside.
194
+ if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
195
+ return;
196
+ if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
197
+ e.preventDefault();
198
+ decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
199
+ };
200
+ window.addEventListener("keydown", onKey);
201
+ return () => window.removeEventListener("keydown", onKey);
202
+ }, [binding, canWrite, card, decide]);
203
+
204
+ if (!binding.ok) {
205
+ return (
206
+ <div className="cg-swipe" ref={deckRef}>
207
+ <SwipeBinder
208
+ fault={binding.fault}
209
+ fields={fields}
210
+ fieldByKey={fieldByKey}
211
+ spec={spec}
212
+ canBind={canBind}
213
+ onSpec={onSpec}
214
+ />
215
+ </div>
216
+ );
217
+ }
218
+
219
+ const { field } = binding;
220
+ const leftTint = optionTint(field, binding.spec.leftOption);
221
+ const rightTint = optionTint(field, binding.spec.rightOption);
222
+
223
+ return (
224
+ <div className="cg-swipe" ref={deckRef} tabIndex={-1}>
225
+ <div className="cg-swipe-bar">
226
+ <span className="cg-swipe-bound">
227
+ <ModeIcon mode="swipe" />
228
+ Sorting into <strong>{field.label}</strong>
229
+ </span>
230
+ <span className="cg-swipe-left">
231
+ {deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
232
+ </span>
233
+ {canBind && (
234
+ <button
235
+ type="button"
236
+ className="cg-link-btn"
237
+ onClick={() => onSpec(undefined)}
238
+ title="Choose a different field or different options for this deck"
239
+ >
240
+ Change
241
+ </button>
242
+ )}
243
+ </div>
244
+ {readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
245
+ {card ? (
246
+ <div className="cg-swipe-deck">
247
+ <button
248
+ type="button"
249
+ className="cg-swipe-side cg-swipe-side--left"
250
+ disabled={!canWrite}
251
+ style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
252
+ onClick={() => decide(binding.spec.leftOption)}
253
+ title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
254
+ >
255
+ <span aria-hidden className="cg-swipe-arrow">
256
+ <svg width="16" height="16" viewBox="0 0 16 16">
257
+ <path
258
+ d="M11 3.2 6.2 8l4.8 4.8"
259
+ fill="none"
260
+ stroke="currentColor"
261
+ strokeWidth="1.6"
262
+ strokeLinecap="round"
263
+ strokeLinejoin="round"
264
+ />
265
+ </svg>
266
+ </span>
267
+ {binding.spec.leftOption}
268
+ </button>
269
+ <article
270
+ className="cg-swipe-card"
271
+ role="button"
272
+ tabIndex={0}
273
+ onClick={() => onOpen(card.pid)}
274
+ onKeyDown={(e) => {
275
+ if (e.key !== "Enter" && e.key !== " ") return;
276
+ e.preventDefault();
277
+ onOpen(card.pid);
278
+ }}
279
+ >
280
+ <h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
281
+ <div className="cg-swipe-cells">
282
+ {/* ⭐ WAVE-29 T26 (R9) β€” the RECORD's visible fields, not the three-key summary the
283
+ kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not
284
+ been widened yet renders exactly what it rendered before. */}
285
+ {(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {
286
+ const f = fieldByKey.get(k);
287
+ if (!f) return null;
288
+ const text = formatDisplay(f, card[k]);
289
+ if (!text) return null;
290
+ // A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
291
+ // scheme guard β€” and every gesture that reaches it must be stopped from also
292
+ // reaching the card, which is a button (the kanban card's note, same trap).
293
+ const href = actionHref(f, card[k]);
294
+ return (
295
+ <div key={k} className="cg-swipe-cell">
296
+ <span className="cg-lv-k">{f.label}</span>
297
+ {href ? (
298
+ <a
299
+ className="cg-lv-v"
300
+ href={href}
301
+ target="_blank"
302
+ rel="noopener noreferrer"
303
+ title={text}
304
+ onClick={(e) => e.stopPropagation()}
305
+ onKeyDown={(e) => e.stopPropagation()}
306
+ >
307
+ {text}
308
+ </a>
309
+ ) : (
310
+ <span className="cg-lv-v">{text}</span>
311
+ )}
312
+ </div>
313
+ );
314
+ })}
315
+ </div>
316
+ {/* ⭐ R9's other two thirds. Both stop their own events: the card is a `role="button"`
317
+ that opens the record, and a click on a comment box or an upload control must not
318
+ also open the modal it exists to make unnecessary (the kanban card's link trap,
319
+ one surface over). */}
320
+ {onDocAdd && onDocFetch && onDocDelete && (
321
+ <div
322
+ className="cg-swipe-docs"
323
+ onClick={(e) => e.stopPropagation()}
324
+ onKeyDown={(e) => e.stopPropagation()}
325
+ role="presentation"
326
+ >
327
+ <Documents
328
+ pid={Number(card.pid)}
329
+ docs={docs?.[String(card.pid)] ?? []}
330
+ docPayload={docPayload}
331
+ onAdd={(file) => onDocAdd(card.pid, file)}
332
+ onFetch={(docId) => onDocFetch(card.pid, docId)}
333
+ onDelete={(docId) => onDocDelete(card.pid, docId)}
334
+ />
335
+ </div>
336
+ )}
337
+ {scope != null && (
338
+ <div
339
+ className="cg-swipe-comments"
340
+ onClick={(e) => e.stopPropagation()}
341
+ onKeyDown={(e) => e.stopPropagation()}
342
+ role="presentation"
343
+ >
344
+ {/* ⚠ KEYED ON scope+pid, the same key `RecordDetail` uses: without it React
345
+ reuses the mounted instance across a card change and paints one record's
346
+ comments under another's name until the fetch returns. */}
347
+ <RecordComments
348
+ key={`${scope}:${Number(card.pid)}`}
349
+ scope={scope}
350
+ pid={Number(card.pid)}
351
+ viewer={viewer}
352
+ />
353
+ </div>
354
+ )}
355
+ {canWrite && (
356
+ <button
357
+ type="button"
358
+ className="cg-link-btn cg-swipe-later"
359
+ onClick={(e) => {
360
+ e.stopPropagation();
361
+ setLater((prev) => new Set(prev).add(card.pid));
362
+ }}
363
+ >
364
+ Decide later
365
+ </button>
366
+ )}
367
+ </article>
368
+ <button
369
+ type="button"
370
+ className="cg-swipe-side cg-swipe-side--right"
371
+ disabled={!canWrite}
372
+ style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
373
+ onClick={() => decide(binding.spec.rightOption)}
374
+ title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
375
+ >
376
+ {binding.spec.rightOption}
377
+ <span aria-hidden className="cg-swipe-arrow">
378
+ <svg width="16" height="16" viewBox="0 0 16 16">
379
+ <path
380
+ d="M5 3.2 9.8 8 5 12.8"
381
+ fill="none"
382
+ stroke="currentColor"
383
+ strokeWidth="1.6"
384
+ strokeLinecap="round"
385
+ strokeLinejoin="round"
386
+ />
387
+ </svg>
388
+ </span>
389
+ </button>
390
+ </div>
391
+ ) : (
392
+ // The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
393
+ // between "the deck is finished" and "the filter hid everything", and the two want
394
+ // different next actions. `later` is disclosed rather than quietly subtracted.
395
+ <div className="cg-mode-empty cg-swipe-empty">
396
+ {later.size > 0 ? (
397
+ <>
398
+ <p>
399
+ {later.size.toLocaleString()}{" "}
400
+ {later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
401
+ in this view is missing a <strong>{field.label}</strong>.
402
+ </p>
403
+ <button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
404
+ Bring them back
405
+ </button>
406
+ </>
407
+ ) : (
408
+ <p>
409
+ Every record in this view already has a <strong>{field.label}</strong>. Widen the
410
+ view's filters to sort more.
411
+ </p>
412
+ )}
413
+ </div>
414
+ )}
415
+ </div>
416
+ );
417
+ }
418
+
419
+ /**
420
+ * The binding picker: field + two options. It is also the surface every LOST binding lands on,
421
+ * with the loss stated above it β€” one place that answers "what is this deck for", rather than an
422
+ * error screen beside a separate setup screen.
423
+ */
424
+ function SwipeBinder({
425
+ fault,
426
+ fields,
427
+ fieldByKey,
428
+ spec,
429
+ canBind,
430
+ onSpec,
431
+ }: {
432
+ fault: BindingFault;
433
+ fields: Field[];
434
+ fieldByKey: Map<string, Field>;
435
+ spec: SwipeSpec | undefined;
436
+ canBind: boolean;
437
+ onSpec: (next: SwipeSpec | undefined) => void;
438
+ }) {
439
+ const selects = useMemo(
440
+ () => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
441
+ [fields]
442
+ );
443
+ const [fieldKey, setFieldKey] = useState<string>(() => {
444
+ if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
445
+ return selects[0]?.key ?? "";
446
+ });
447
+ const chosen = fieldByKey.get(fieldKey);
448
+ const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
449
+ const [left, setLeft] = useState<string>("");
450
+ const [right, setRight] = useState<string>("");
451
+
452
+ // The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
453
+ // pick survives re-renders, and reset whenever the field changes β€” carrying an option from the
454
+ // previous field would offer a value the new field cannot hold.
455
+ useEffect(() => {
456
+ setLeft(options[0] ?? "");
457
+ setRight(options.find((o) => o !== options[0]) ?? "");
458
+ }, [options]);
459
+
460
+ const message = ((): string => {
461
+ switch (fault.kind) {
462
+ case "field-gone":
463
+ return "The field this deck sorted into has been deleted. Pick another one.";
464
+ case "not-select":
465
+ return `β€œ${fault.field.label}” is no longer a single-select, so it has no options to`
466
+ + " sort into. Pick another field.";
467
+ case "option-gone":
468
+ return `${fault.missing.map((m) => `β€œ${m}”`).join(" and ")} ${
469
+ fault.missing.length === 1 ? "is" : "are"
470
+ } no longer ${fault.missing.length === 1 ? "an option" : "options"} on β€œ${
471
+ fault.field.label
472
+ }”. Pick the sides again.`;
473
+ default:
474
+ return "Sort records one at a time into two options of a single-select field.";
475
+ }
476
+ })();
477
+
478
+ if (!canBind) {
479
+ return (
480
+ <div className="cg-mode-empty">
481
+ <p>{message}</p>
482
+ <p>Its creator or an admin can set this view up.</p>
483
+ </div>
484
+ );
485
+ }
486
+ if (selects.length === 0) {
487
+ // Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
488
+ // requirement is what turns a dead end into a next action.
489
+ return (
490
+ <div className="cg-mode-empty">
491
+ <p>
492
+ A swipe deck sorts into a single-select field with at least two options. This database
493
+ does not have one yet β€” add a single-select column, then come back.
494
+ </p>
495
+ </div>
496
+ );
497
+ }
498
+ const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
499
+ return (
500
+ <div className="cg-swipe-setup">
501
+ <p className="cg-swipe-setup-note">{message}</p>
502
+ <label className="cg-swipe-setup-row">
503
+ <span>Sort into</span>
504
+ <select
505
+ className="cg-select"
506
+ value={fieldKey}
507
+ onChange={(e) => setFieldKey(e.target.value)}
508
+ >
509
+ {/* Every option carries an explicit `value`: a <select> whose value names nothing
510
+ renders its FIRST option and reports a choice the user never made
511
+ ([[cg-condition-builder-items]]). */}
512
+ {selects.map((f) => (
513
+ <option key={f.key} value={f.key}>
514
+ {f.label}
515
+ </option>
516
+ ))}
517
+ </select>
518
+ </label>
519
+ <div className="cg-swipe-setup-sides">
520
+ <label className="cg-swipe-setup-row">
521
+ <span>Swipe left</span>
522
+ <select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
523
+ {options.map((o) => (
524
+ <option key={o} value={o}>
525
+ {o}
526
+ </option>
527
+ ))}
528
+ </select>
529
+ </label>
530
+ <label className="cg-swipe-setup-row">
531
+ <span>Swipe right</span>
532
+ <select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
533
+ {options.map((o) => (
534
+ <option key={o} value={o}>
535
+ {o}
536
+ </option>
537
+ ))}
538
+ </select>
539
+ </label>
540
+ </div>
541
+ {!ready && left && right && (
542
+ // Stated, not silently refused: both engines DROP a binding whose sides are the same
543
+ // option, so a Save that looked like it worked would simply not persist.
544
+ <p className="cg-swipe-setup-warn">
545
+ The two sides must be different options β€” otherwise both gestures do the same thing.
546
+ </p>
547
+ )}
548
+ <button
549
+ type="button"
550
+ className="cg-btn cg-btn--primary"
551
+ disabled={!ready}
552
+ onClick={() =>
553
+ chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
554
+ }
555
+ >
556
+ Start sorting
557
+ </button>
558
+ </div>
559
+ );
560
+ }
561
+
562
+ export default SwipeView;
web/src/customer-grid/ViewSidebar.tsx CHANGED
The diff for this file is too large to render. See raw diff
 
web/src/customer-grid/aggregations.ts CHANGED
@@ -1,41 +1,109 @@
1
  // ---------------------------------------------------------------------------
2
  // customer-grid / aggregations.ts
3
- // Per-group subtotals for the GROUPING batch. `computeAggs` sums every field
4
- // the API marks `agg:"sum"` across a bucket of rows and returns a map
5
- // fieldKey -> formatted display string (the SAME formatting the data cells use:
6
- // "$"+toLocaleString for currency, toLocaleString for int). Non-agg fields are
7
- // simply absent from the map, so the footer renderer draws them blank.
8
  //
9
  // Called ONCE per group inside the useVisibleRows memo (never per cell/frame);
10
- // the resulting object is shared by that group's header and footer.
 
11
  // ---------------------------------------------------------------------------
12
 
13
- import type { Field, Row } from "./types";
 
14
 
15
- /** Coerce any cell value to a finite number (blank/garbage -> 0). */
16
- function toNum(v: unknown): number {
17
- const n = typeof v === "number" ? v : Number(v);
18
- return Number.isFinite(n) ? n : 0;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
19
  }
20
 
21
  /**
22
- * Sum every `agg:"sum"` field over `rows`, formatted to match its column:
23
- * currency -> "$" + toLocaleString | int -> toLocaleString
24
- * Sums are rounded to 2 decimals first to kill floating-point drift
25
- * (e.g. 1234.5600000001) before formatting. Only summed fields appear in the
26
- * returned map; everything else is left out (footer draws it blank).
 
 
 
 
 
 
27
  */
28
  export function computeAggs(rows: Row[], fields: Field[]): Record<string, string> {
29
  const out: Record<string, string> = {};
30
  for (const f of fields) {
31
- if (f.agg !== "sum") continue;
32
- let sum = 0;
33
- for (const r of rows) sum += toNum(r[f.key]);
34
- const clean = Math.round(sum * 100) / 100; // drop float artifacts
35
- out[f.key] =
36
- f.type === "currency"
37
- ? "$" + clean.toLocaleString()
38
- : clean.toLocaleString();
 
 
 
 
 
 
 
 
 
 
 
 
 
39
  }
40
  return out;
41
  }
 
1
  // ---------------------------------------------------------------------------
2
  // customer-grid / aggregations.ts
3
+ // COLUMN SUMMARIES β€” the per-group subtotal AND the table's own totals row.
4
+ // `computeAggs` folds every field carrying an `agg` over a bucket of rows and
5
+ // returns fieldKey -> formatted display string. Non-agg fields are simply
6
+ // absent from the map, so the footer renderer draws them blank.
 
7
  //
8
  // Called ONCE per group inside the useVisibleRows memo (never per cell/frame);
9
+ // the resulting object is shared by that group's header and footer, and once
10
+ // more for the ungrouped totals row.
11
  // ---------------------------------------------------------------------------
12
 
13
+ import { isNumericFieldType } from "./types";
14
+ import type { AggName, Field, Row } from "./types";
15
 
16
+ /**
17
+ * ⭐⭐ WAVE-29 CONTRACT C7 β€” **THE CLIENT MIRROR of `platform/aios_grid.FIELD_AGGS`**, published
18
+ * by session C and held in step by a parity gate that reads both files. The ORDER is the
19
+ * picker's order.
20
+ *
21
+ * β›” THREE VOCABULARIES EXIST AND THEY ARE NOT ONE LIST β€” merging them is the trap on this
22
+ * contract:
23
+ * Β· `FIELD_AGGS` (here + aios_grid) a FIELD's `agg`: the column summary. This.
24
+ * Β· `CHART_AGGS` (aios_grid, `avg`) STORED chart values with live data. Untouchable:
25
+ * an unknown agg falls back to `sum` and drops a
26
+ * calendar metric card, with nothing red.
27
+ * Β· `ROLLUP_FNS` (user_tables, 16 names) rollup FOLDS. Overlaps; is not the same list.
28
+ *
29
+ * ⚠ `average`, not `avg`: `ROLLUP_FNS` already spells it that way and 47 rollups run on it in
30
+ * production, so a column summary and a rollup fold name the same operation the same way.
31
+ * ⚠ `median` is in NEITHER of the other two β€” it is net-new on both sides of this contract.
32
+ */
33
+ export const FIELD_AGGS: readonly AggName[] = [
34
+ "sum", "average", "median", "min", "max", "count",
35
+ ];
36
+
37
+ /** How each one reads in the picker. Sentence case, because it is a menu row, not a header. */
38
+ export const AGG_LABELS: Record<AggName, string> = {
39
+ sum: "Sum",
40
+ average: "Average",
41
+ median: "Median",
42
+ min: "Min",
43
+ max: "Max",
44
+ count: "Count",
45
+ };
46
+
47
+ /**
48
+ * What THIS column may be summarised by (C7's semantics, not a preference):
49
+ * `sum Β· average Β· median Β· min Β· max` are numeric-only; `count` counts ROWS and so applies to
50
+ * every type. Offering Sum on a text column would render a number nobody can reconcile.
51
+ */
52
+ export function aggOptions(field: Field): readonly AggName[] {
53
+ return isNumericFieldType(field.type)
54
+ ? FIELD_AGGS
55
+ : FIELD_AGGS.filter((a) => a === "count");
56
+ }
57
+
58
+ /** The numeric value of a cell, or `undefined` β€” blank and unparseable are NOT zero. */
59
+ function numOf(v: unknown): number | undefined {
60
+ if (v === null || v === undefined || v === "") return undefined;
61
+ const n = typeof v === "number" ? v : Number(String(v).replace(/[$,\s]/g, ""));
62
+ return Number.isFinite(n) ? n : undefined;
63
+ }
64
+
65
+ function median(sorted: number[]): number {
66
+ const mid = sorted.length >> 1;
67
+ return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
68
  }
69
 
70
  /**
71
+ * Fold every field carrying an `agg` over `rows`, formatted to match its column:
72
+ * currency -> "$" + toLocaleString | everything else -> toLocaleString
73
+ * Values are rounded to 2 decimals first to kill floating-point drift (1234.5600000001).
74
+ *
75
+ * β›” **BLANK, NEVER ZERO** (C7, and the codebase's standing law): a numeric fold over a set
76
+ * holding no numeric value at all returns nothing and the cell stays empty β€” `0` is a
77
+ * measurement and this is an admission that there was nothing to measure. Only `count` returns
78
+ * `0`, because "no rows" genuinely is a count. This is also what `_rollup_fold` already does.
79
+ *
80
+ * ⚠ `count` counts ROWS IN SCOPE, not non-blank cells. `ROLLUP_FNS` splits that hair three ways
81
+ * (`count`/`counta`/`countall`); a column summary does not, and must not grow a second spelling.
82
  */
83
  export function computeAggs(rows: Row[], fields: Field[]): Record<string, string> {
84
  const out: Record<string, string> = {};
85
  for (const f of fields) {
86
+ const agg = f.agg as AggName | undefined;
87
+ if (!agg || !FIELD_AGGS.includes(agg)) continue;
88
+ if (agg === "count") {
89
+ out[f.key] = rows.length.toLocaleString();
90
+ continue;
91
+ }
92
+ if (!isNumericFieldType(f.type)) continue;
93
+ const nums: number[] = [];
94
+ for (const r of rows) {
95
+ const n = numOf(r[f.key]);
96
+ if (n !== undefined) nums.push(n);
97
+ }
98
+ if (!nums.length) continue; // blank, never zero
99
+ let value: number;
100
+ if (agg === "sum") value = nums.reduce((a, b) => a + b, 0);
101
+ else if (agg === "average") value = nums.reduce((a, b) => a + b, 0) / nums.length;
102
+ else if (agg === "median") value = median([...nums].sort((a, b) => a - b));
103
+ else if (agg === "min") value = Math.min(...nums);
104
+ else value = Math.max(...nums);
105
+ const clean = Math.round(value * 100) / 100; // drop float artifacts
106
+ out[f.key] = f.type === "currency" ? "$" + clean.toLocaleString() : clean.toLocaleString();
107
  }
108
  return out;
109
  }
web/src/customer-grid/apiBridge.ts CHANGED
@@ -53,6 +53,8 @@ import {
53
  signal,
54
  } from "../apiContract";
55
  import { setStandaloneSink } from "./hostBridge";
 
 
56
  import { CUSTOMER_TOPIC } from "./types";
57
  import type { CustomersPayload, Field, GridWorkspace, HostEvent, Row, TopicConfig } from "./types";
58
  import type { TsPayload, TsRequest } from "./timeSeriesData";
@@ -122,6 +124,17 @@ export function clearCustomersCache(): void {
122
  rowsCache.clear();
123
  }
124
 
 
 
 
 
 
 
 
 
 
 
 
125
  /**
126
  * X2 `GET /api/v1/<topic.rowsPath>` β†’ `{fields, rows, today, pulled_at}`, rows already
127
  * scoped to the session's BU pool (EXIT-3b). The cookie replaces HTTP Basic.
@@ -231,6 +244,123 @@ export async function fetchWorkspace(
231
  return w && typeof w.storageKey === "string" && Array.isArray(w.views) ? w : null;
232
  }
233
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
234
  /**
235
  * X2 `PATCH /api/v1/<topic.rowsPath>/{pid}` β€” the overlay stratum only (Odoo is never
236
  * written). Kept as its own route rather than folded into the events log
 
53
  signal,
54
  } from "../apiContract";
55
  import { setStandaloneSink } from "./hostBridge";
56
+ import { changedBuckets } from "./liveWorkspace";
57
+ import type { ChangeTokens } from "./liveWorkspace";
58
  import { CUSTOMER_TOPIC } from "./types";
59
  import type { CustomersPayload, Field, GridWorkspace, HostEvent, Row, TopicConfig } from "./types";
60
  import type { TsPayload, TsRequest } from "./timeSeriesData";
 
124
  rowsCache.clear();
125
  }
126
 
127
+ /**
128
+ * Drop ONE topic's rows memo. The change poller's companion (wave 29, item 20).
129
+ *
130
+ * β›” NOT `clearCustomersCache()`, and the difference is a megabyte. That clears every topic's
131
+ * window, so a poll that noticed a change on the Product grid would also force the Customer pool
132
+ * to be re-downloaded on the next surface switch. One bucket changed; one memo is dropped.
133
+ */
134
+ export function clearTopicRowsCache(rowsPath: string): void {
135
+ rowsCache.delete(rowsPath);
136
+ }
137
+
138
  /**
139
  * X2 `GET /api/v1/<topic.rowsPath>` β†’ `{fields, rows, today, pulled_at}`, rows already
140
  * scoped to the session's BU pool (EXIT-3b). The cookie replaces HTTP Basic.
 
244
  return w && typeof w.storageKey === "string" && Array.isArray(w.views) ? w : null;
245
  }
246
 
247
+ // --- the CHANGE POLLER (wave 29, item 20 / R11 / contract C6) ---------------
248
+
249
+ /**
250
+ * `GET /api/v1/changes?scope=…` β†’ `{bucket: opaque token}`, or null.
251
+ *
252
+ * ⚠ A FAILED POLL IS SILENT. It raises no `DATA_ERROR_EVENT`, because the frame REPLACES the whole
253
+ * surface with an error card on that signal β€” so one dropped packet, six times a minute, would turn
254
+ * a working grid into a failure screen. `changedBuckets` reads a null as "no baseline, no change"
255
+ * and the tab simply carries on with what it has. 401 still ends the session: that is the one
256
+ * status which is never about this route.
257
+ */
258
+ export async function fetchChangeTokens(scope: string): Promise<ChangeTokens | null> {
259
+ let res: Response;
260
+ try {
261
+ res = await fetch(`${API_V1}/changes?scope=${encodeURIComponent(scope)}`,
262
+ { credentials: CREDENTIALS });
263
+ } catch {
264
+ return null;
265
+ }
266
+ if (handledSession(res)) return null;
267
+ if (!res.ok) return null;
268
+ const body = (await readJson(res)) as { tokens?: unknown } | null;
269
+ const tokens = body?.tokens;
270
+ if (!tokens || typeof tokens !== "object" || Array.isArray(tokens)) return null;
271
+ const out: ChangeTokens = {};
272
+ for (const [bucket, token] of Object.entries(tokens as Record<string, unknown>))
273
+ out[bucket] = typeof token === "string" ? token : null;
274
+ return out;
275
+ }
276
+
277
+ /** ~10 s. The owner's ask is "a new record shows up in about ten seconds", and the request it
278
+ * costs is a dict read server-side β€” see `routes_changes.py` for why that is the whole design. */
279
+ export const CHANGE_POLL_MS = 10_000;
280
+
281
+ interface ChangeWatch {
282
+ timer: ReturnType<typeof setInterval> | null;
283
+ tokens: ChangeTokens | null;
284
+ listeners: Set<(changed: string[]) => void>;
285
+ inFlight: boolean;
286
+ /** ⭐ ONE poll implementation per watch, held here so the interval and the visibility handler
287
+ * call the SAME function. The visibility handler used to re-inline the body, which quietly
288
+ * skipped `inFlight` β€” so returning to a tab whose poll was still outstanding stacked a second
289
+ * request on top of it, exactly what that guard exists to prevent. */
290
+ poll: () => Promise<void>;
291
+ }
292
+
293
+ const changeWatches = new Map<string, ChangeWatch>();
294
+ let visibilityBound = false;
295
+
296
+ /**
297
+ * Watch one scope for server-side changes. Returns its unsubscribe.
298
+ *
299
+ * ⭐ ONE TIMER PER SCOPE, REFCOUNTED, and that is a budget rather than tidiness. A linked-record
300
+ * grid mounts a second `useCustomerData` on the same surface, and a per-hook interval would double
301
+ * the poll rate for a table the user opened once. The done-when is "roughly 6 tiny calls per minute
302
+ * per tab" β€” per TAB, not per component.
303
+ *
304
+ * β›” IT DOES NOT POLL A HIDDEN TAB, and it polls IMMEDIATELY on becoming visible again. A background
305
+ * tab left open overnight would otherwise spend the night asking a question nobody can see the
306
+ * answer to, and the one moment its answer certainly matters is the moment you look at it.
307
+ * `visibilitychange` had zero listeners in this client before this.
308
+ */
309
+ export function subscribeChanges(scope: string,
310
+ onChange: (changed: string[]) => void): () => void {
311
+ if (typeof window === "undefined") return () => {};
312
+ let watch = changeWatches.get(scope);
313
+ if (!watch) {
314
+ const w0: ChangeWatch = {
315
+ timer: null, tokens: null, listeners: new Set(), inFlight: false,
316
+ poll: async () => {
317
+ // A slow answer must not queue a second request behind itself: on a cold Space the first
318
+ // poll can outlive the interval, and without this the backlog grows while it stays slow.
319
+ if (w0.inFlight || document.visibilityState !== "visible") return;
320
+ w0.inFlight = true;
321
+ try {
322
+ const next = await fetchChangeTokens(scope);
323
+ const changed = changedBuckets(w0.tokens, next);
324
+ if (next) w0.tokens = next;
325
+ if (changed.length) for (const fn of [...w0.listeners]) fn(changed);
326
+ } finally {
327
+ w0.inFlight = false;
328
+ }
329
+ },
330
+ };
331
+ watch = w0;
332
+ changeWatches.set(scope, w0);
333
+ }
334
+ const w = watch;
335
+ w.listeners.add(onChange);
336
+
337
+ if (!w.timer) {
338
+ void w.poll(); // take the baseline now, not in ten seconds
339
+ w.timer = setInterval(() => { void w.poll(); }, CHANGE_POLL_MS);
340
+ }
341
+ if (!visibilityBound) {
342
+ visibilityBound = true;
343
+ window.addEventListener("visibilitychange", () => {
344
+ if (document.visibilityState !== "visible") return;
345
+ for (const watched of changeWatches.values())
346
+ if (watched.timer) void watched.poll();
347
+ });
348
+ }
349
+
350
+ return () => {
351
+ w.listeners.delete(onChange);
352
+ if (w.listeners.size === 0 && w.timer) {
353
+ clearInterval(w.timer);
354
+ w.timer = null;
355
+ // ⚠ The tokens are DROPPED with the last listener. A remount must re-baseline rather than
356
+ // compare against a token from before it was unmounted: the payload it is about to fetch is
357
+ // fresh by definition, so treating the interval it missed as "a change" would cost a second
358
+ // full read of what it just read.
359
+ w.tokens = null;
360
+ }
361
+ };
362
+ }
363
+
364
  /**
365
  * X2 `PATCH /api/v1/<topic.rowsPath>/{pid}` β€” the overlay stratum only (Odoo is never
366
  * written). Kept as its own route rather than folded into the events log
web/src/customer-grid/display.ts CHANGED
@@ -160,8 +160,14 @@ export function numberText(v: number, fmt: FieldFormat | undefined): string {
160
  * "YYYY-MM-DD HH:MM:SS" and are UTC by Odoo convention, so a time-carrying
161
  * value with no zone gets a Z; a bare date keeps today's parse (UTC midnight)
162
  * so format-less rendering stays byte-identical to the pre-wave-5 path.
 
 
 
 
 
 
163
  */
164
- function parseStamp(raw: string): Date | null {
165
  const s = raw.includes(" ") ? raw.replace(" ", "T") : raw;
166
  const iso =
167
  /T\d{2}:\d{2}/.test(s) && !/(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(s) ? s + "Z" : s;
@@ -588,6 +594,23 @@ export function formatDisplay(field: Field, v: CellValue): string {
588
  // rendering that as 0 would fabricate a measurement (the engine's own blank-never-zero
589
  // law, kept at the display seam too).
590
  return v == null || v === "" ? "" : numberText(num(v), field.format);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
591
  case "multiselect":
592
  // The comma-joined SET, read back with breathing room ("A, B" not "A,B").
593
  return String(v ?? "")
 
160
  * "YYYY-MM-DD HH:MM:SS" and are UTC by Odoo convention, so a time-carrying
161
  * value with no zone gets a Z; a bare date keeps today's parse (UTC midnight)
162
  * so format-less rendering stays byte-identical to the pre-wave-5 path.
163
+ *
164
+ * ⭐ EXPORTED in wave 29 (W29-T30) because the xlsx writer needs a Date to turn
165
+ * into an Excel serial, and the alternative was a SECOND date parser in
166
+ * `export.ts` β€” two evaluators for one question, which is how the two drift and
167
+ * a stamp exports as a different day than it renders
168
+ * ([[one-evaluator-per-question]]). It stays the only parser in this module.
169
  */
170
+ export function parseStamp(raw: string): Date | null {
171
  const s = raw.includes(" ") ? raw.replace(" ", "T") : raw;
172
  const iso =
173
  /T\d{2}:\d{2}/.test(s) && !/(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(s) ? s + "Z" : s;
 
594
  // rendering that as 0 would fabricate a measurement (the engine's own blank-never-zero
595
  // law, kept at the display seam too).
596
  return v == null || v === "" ? "" : numberText(num(v), field.format);
597
+ case "rollup": {
598
+ // ⭐ WAVE 29 (W29-T30) β€” THE MISSING CASE. `rollup` fell through to `default` and printed
599
+ // its raw fold string, so ONE cell rendered two ways: the canvas showed `1,491,552.43`
600
+ // (`cells.ts`'s rollup branch, comma-fixed 2026-08-10 on the owner's instruction) while
601
+ // every CSV, PDF, JSON-display and Excel export showed `1491552.43`. Same family as D-121
602
+ // (the record panel ignoring a field's format) β€” three surfaces, one concept.
603
+ //
604
+ // β›” THE BLANK RULE IS THE POINT, and it is why this is a guarded branch and not a call to
605
+ // `numberText(num(v), ...)`. `_rollup_fold` returns "" for "no rows to aggregate" and only
606
+ // the count family ever returns a real 0, so `num("")` β€” which is 0 β€” would paint the
607
+ // measurement the server just refused to invent. A fold that is not a number at all
608
+ // (`concatenate`, `arrayunique`, `latest` over text) keeps its own text.
609
+ // β‡’ Mirrors `cells.ts`'s branch line for line, deliberately: one concept, one rendering.
610
+ const raw = String(v ?? "");
611
+ const asNum = raw.trim() === "" ? NaN : Number(raw);
612
+ return Number.isFinite(asNum) ? numberText(asNum, field.format) : raw;
613
+ }
614
  case "multiselect":
615
  // The comma-joined SET, read back with breathing room ("A, B" not "A,B").
616
  return String(v ?? "")
web/src/customer-grid/export.ts CHANGED
@@ -28,7 +28,13 @@
28
  // ---------------------------------------------------------------------------
29
 
30
  import type { Field, Row } from "./types";
31
- import { formatDisplay } from "./display";
 
 
 
 
 
 
32
 
33
  export const EXPORT_FORMATS = ["csv", "xlsx", "pdf", "json"] as const;
34
  export type ExportFormat = (typeof EXPORT_FORMATS)[number];
@@ -193,9 +199,127 @@ function sheetName(name: string): string {
193
  return (s || "Export").slice(0, 31);
194
  }
195
 
196
- /** A minimal SpreadsheetML workbook: one sheet, every cell an inline string
197
- * carrying the DISPLAY value (contract C2 β€” what the grid shows is what the
198
- * file says). */
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
199
  export function buildXlsx(
200
  fields: Field[],
201
  rows: Row[],
@@ -203,12 +327,61 @@ export function buildXlsx(
203
  today: string | undefined
204
  ): Uint8Array {
205
  const enc = new TextEncoder();
 
206
  const cell = (v: string) =>
207
  `<c t="inlineStr"><is><t xml:space="preserve">${xmlEscape(v)}</t></is></c>`;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
208
  const rowXml = (cells: string[]) => `<row>${cells.join("")}</row>`;
209
  const body = [
 
210
  rowXml(fields.map((f) => cell(f.label))),
211
- ...rows.map((r) => rowXml(fields.map((f) => cell(formatDisplay(f, r[f.key]))))),
212
  ].join("");
213
  const sheet =
214
  `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
@@ -227,6 +400,11 @@ export function buildXlsx(
227
  `<Default Extension="xml" ContentType="application/xml"/>` +
228
  `<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>` +
229
  `<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>` +
 
 
 
 
 
230
  `</Types>`;
231
  const rootRels =
232
  `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
@@ -237,13 +415,18 @@ export function buildXlsx(
237
  `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
238
  `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
239
  `<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>` +
 
240
  `</Relationships>`;
 
 
 
241
  return buildZip(
242
  [
243
  { name: "[Content_Types].xml", data: enc.encode(contentTypes) },
244
  { name: "_rels/.rels", data: enc.encode(rootRels) },
245
  { name: "xl/workbook.xml", data: enc.encode(workbook) },
246
  { name: "xl/_rels/workbook.xml.rels", data: enc.encode(wbRels) },
 
247
  { name: "xl/worksheets/sheet1.xml", data: enc.encode(sheet) },
248
  ],
249
  today
 
28
  // ---------------------------------------------------------------------------
29
 
30
  import type { Field, Row } from "./types";
31
+ import {
32
+ formatDisplay,
33
+ formulaIsBlank,
34
+ formulaIsText,
35
+ isBareDay,
36
+ parseStamp,
37
+ } from "./display";
38
 
39
  export const EXPORT_FORMATS = ["csv", "xlsx", "pdf", "json"] as const;
40
  export type ExportFormat = (typeof EXPORT_FORMATS)[number];
 
199
  return (s || "Export").slice(0, 31);
200
  }
201
 
202
+ // -------------------------------------------------------- xlsx: real numbers
203
+ //
204
+ // ⭐ WAVE 29, OWNER ITEM 19 (W29-T30). Until now EVERY cell was `t="inlineStr"`
205
+ // carrying `formatDisplay`'s output, so a revenue column arrived in Excel as the
206
+ // TEXT "$1,234,567.50" and `=SUM()` over it returned 0. The owner's complaint was
207
+ // that the download is not usable as a spreadsheet, and that was exactly right.
208
+ //
209
+ // β›” AND THE GATE CERTIFIED IT. `_test/export.test.ts` asserted the inline-string
210
+ // shape as the PASSING condition, so the bug had a green check standing over it β€”
211
+ // the third instance of that shape this wave. It is INVERTED there, not deleted:
212
+ // a gate that greps a literal you just changed goes green forever after.
213
+
214
+ /** Field kinds whose value is ARITHMETIC, so Excel must receive a number rather
215
+ * than a pre-formatted string. W29-T30's `done-when` names exactly these.
216
+ * ⚠ `rating` is deliberately NOT here: it renders "4 of 5", a sentence about a
217
+ * scale rather than a quantity, and the ticket does not ask for it. */
218
+ const XLSX_NUMERIC_TYPES = new Set([
219
+ "int", "currency", "pct", "rollup", "formula", "metric",
220
+ ]);
221
+
222
+ /** Days from Excel's serial origin (1899-12-30) to the Unix epoch.
223
+ * ⚠ 1899-12-30, not 12-31, absorbs Excel's phantom 1900-02-29 β€” correct for
224
+ * every date after 1900-03-01, which is every date this product holds. */
225
+ const EXCEL_EPOCH_DAYS = 25569;
226
+
227
+ /** A Date as an Excel serial, read on the stated clock.
228
+ * β›” Excel has no timezone: a serial IS a wall clock. So the clock is chosen
229
+ * the same way `dateTimeText` chooses it, or a stamp exports as a different day
230
+ * than it renders β€” the off-by-a-day that `dateTimeText`'s own note records for
231
+ * everyone west of Greenwich. */
232
+ function excelSerial(d: Date, utc: boolean): number {
233
+ const ms = utc
234
+ ? d.getTime()
235
+ : Date.UTC(d.getFullYear(), d.getMonth(), d.getDate(),
236
+ d.getHours(), d.getMinutes(), d.getSeconds());
237
+ return ms / 86400000 + EXCEL_EPOCH_DAYS;
238
+ }
239
+
240
+ /** The Excel number-format code that makes a numeric cell READ the way the grid
241
+ * paints it β€” `null` = General. Derived from the same `field.format` bag
242
+ * `numberText` reads, so the file and the canvas agree by construction.
243
+ * ⚠ `abbrev` has no Excel equivalent ("34.0M" is not a number format). The
244
+ * NUMBER still ships β€” summable beats abbreviated in a spreadsheet β€” so an
245
+ * abbreviated column reads in full here. Stated, not silent. */
246
+ function numFmtCode(f: Field): string | null {
247
+ const fmt = f.format;
248
+ const d =
249
+ fmt && Number.isInteger(fmt.decimals) && (fmt.decimals as number) >= 0 &&
250
+ (fmt.decimals as number) <= 4 ? (fmt.decimals as number) : null;
251
+ const grouped = fmt?.thousands !== false;
252
+ const dec = (n: number) => (n > 0 ? "." + "0".repeat(n) : "");
253
+ if (f.type === "currency")
254
+ // The done-when's own example: `$1,234.50`. Two places unless the column says otherwise.
255
+ return `"$"${grouped ? "#,##0" : "0"}${dec(d ?? 2)}`;
256
+ if (f.type === "pct")
257
+ // β›” THE VALUE STAYS IN PERCENT UNITS AND THIS IS DELIBERATE. `display.ts`
258
+ // renders `num(v).toFixed(1) + "%"`, i.e. 12.3 MEANS 12.3%. Pairing that
259
+ // stored 12.3 with Excel's builtin `0.0%` would multiply by 100 and show
260
+ // 1230.0%; dividing by 100 to suit the builtin would make this file
261
+ // disagree with `buildJson`, which exports the RAW 12.3 β€” the same
262
+ // one-cell-two-answers defect this ticket exists to end. So: raw value, and
263
+ // a format whose `%` is a LITERAL suffix.
264
+ return `0.0"%"`;
265
+ if (d != null) return `${grouped ? "#,##0" : "0"}${dec(d)}`;
266
+ // No declared decimals: `numberText` falls to `toLocaleString()`, which groups
267
+ // and shows up to 3 fraction digits. `#,##0.###` is that, in Excel's dialect.
268
+ return grouped ? "#,##0.###" : null;
269
+ }
270
+
271
+ /** Interns format codes and hands back a `cellXfs` index. Style 0 is General,
272
+ * which the header row and every string cell use. */
273
+ function styleTable() {
274
+ const byCode = new Map<string, number>();
275
+ return {
276
+ /** `null` code = General = style 0. */
277
+ idFor(code: string | null): number {
278
+ if (code == null) return 0;
279
+ const seen = byCode.get(code);
280
+ if (seen != null) return seen;
281
+ const id = byCode.size + 1; // 0 is General
282
+ byCode.set(code, id);
283
+ return id;
284
+ },
285
+ codes(): string[] {
286
+ return [...byCode.keys()];
287
+ },
288
+ };
289
+ }
290
+
291
+ /** The stylesheet. ⚠ Excel is strict here in ways a reader would not guess:
292
+ * `fills` must carry at least the two reserved entries (none + gray125) or the
293
+ * file opens with a repair prompt, and custom `numFmtId`s must start at 164
294
+ * because everything below is reserved for builtins. */
295
+ function buildStyles(codes: string[]): string {
296
+ const numFmts = codes
297
+ .map((c, i) => `<numFmt numFmtId="${164 + i}" formatCode="${xmlEscape(c)}"/>`)
298
+ .join("");
299
+ const xfs = codes
300
+ .map((_, i) =>
301
+ `<xf numFmtId="${164 + i}" fontId="0" fillId="0" borderId="0" xfId="0" applyNumberFormat="1"/>`)
302
+ .join("");
303
+ return (
304
+ `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
305
+ `<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">` +
306
+ (codes.length ? `<numFmts count="${codes.length}">${numFmts}</numFmts>` : "") +
307
+ `<fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>` +
308
+ `<fills count="2"><fill><patternFill patternType="none"/></fill>` +
309
+ `<fill><patternFill patternType="gray125"/></fill></fills>` +
310
+ `<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>` +
311
+ `<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>` +
312
+ `<cellXfs count="${codes.length + 1}">` +
313
+ `<xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/>${xfs}</cellXfs>` +
314
+ `<cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>` +
315
+ `</styleSheet>`
316
+ );
317
+ }
318
+
319
+ /** A minimal SpreadsheetML workbook: one sheet, NUMERIC kinds written as real
320
+ * numbers with a number format that reproduces the grid's rendering, everything
321
+ * else an inline string carrying the DISPLAY value (contract C2 β€” what the grid
322
+ * shows is what the file says). */
323
  export function buildXlsx(
324
  fields: Field[],
325
  rows: Row[],
 
327
  today: string | undefined
328
  ): Uint8Array {
329
  const enc = new TextEncoder();
330
+ const styles = styleTable();
331
  const cell = (v: string) =>
332
  `<c t="inlineStr"><is><t xml:space="preserve">${xmlEscape(v)}</t></is></c>`;
333
+ /** A number Excel can sum, in style `s`. No `t` attribute: numeric is the default. */
334
+ const numCell = (n: number, s: number) =>
335
+ `<c${s ? ` s="${s}"` : ""}><v>${n}</v></c>`;
336
+ /** β›” BLANK STAYS BLANK β€” never `0`. A zero here would fabricate a measurement
337
+ * the server refused to make (the codebase's standing law, and for a `date` a
338
+ * 0 serial renders as a nonsense 1900 day). Styled but empty. */
339
+ const blankCell = (s: number) => `<c${s ? ` s="${s}"` : ""}/>`;
340
+
341
+ /** β›” VALUE-DRIVEN, NOT TYPE-DRIVEN. A `formula` may return TEXT and a `rollup`
342
+ * fold may be `concatenate`/`latest`-over-text, so branching on the column's
343
+ * type alone would emit `<v>NaN</v>` and Excel would open with a repair
344
+ * prompt. Anything that is not a finite number falls back to the display
345
+ * string, which is at least true. */
346
+ function dataCell(f: Field, raw: Row[string]): string {
347
+ const isNumeric = XLSX_NUMERIC_TYPES.has(f.type);
348
+ const isDate = f.type === "date" || f.type === "created_time";
349
+ if (!isNumeric && !isDate) return cell(formatDisplay(f, raw));
350
+
351
+ if (isDate) {
352
+ const text = formatDisplay(f, raw);
353
+ const s = String(raw ?? "").trim();
354
+ if (s === "") return blankCell(0);
355
+ const d = parseStamp(s);
356
+ if (!d) return cell(text); // unparseable: the raw string is true
357
+ // β›” BOTH RULES ARE `dateTimeText`'s (`display.ts:245-246`), MIRRORED LINE
358
+ // FOR LINE rather than re-derived. `time` defaults to true only for
359
+ // `created_time` β€” a `date` defaults to NO time, and my first version had
360
+ // that backwards. A bare YYYY-MM-DD is a calendar DAY and is read in UTC,
361
+ // or it shows the previous day to everyone west of Greenwich.
362
+ const withTime = f.format?.time ?? f.type === "created_time";
363
+ const utc = f.format?.tz === "utc" || isBareDay(raw);
364
+ const sid = styles.idFor(withTime ? "mmm d, yyyy hh:mm" : "mmm d, yyyy");
365
+ return numCell(excelSerial(d, utc), sid);
366
+ }
367
+
368
+ // `formula`'s three states, in the order that makes them total.
369
+ if (f.type === "formula") {
370
+ if (formulaIsBlank(raw)) return blankCell(styles.idFor(numFmtCode(f)));
371
+ if (formulaIsText(raw)) return cell(raw);
372
+ }
373
+ const str = String(raw ?? "").trim();
374
+ if (str === "") return blankCell(styles.idFor(numFmtCode(f)));
375
+ const n = Number(str);
376
+ if (!Number.isFinite(n)) return cell(formatDisplay(f, raw));
377
+ return numCell(n, styles.idFor(numFmtCode(f)));
378
+ }
379
+
380
  const rowXml = (cells: string[]) => `<row>${cells.join("")}</row>`;
381
  const body = [
382
+ // The header row is LABELS β€” text, and it stays text.
383
  rowXml(fields.map((f) => cell(f.label))),
384
+ ...rows.map((r) => rowXml(fields.map((f) => dataCell(f, r[f.key])))),
385
  ].join("");
386
  const sheet =
387
  `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
 
400
  `<Default Extension="xml" ContentType="application/xml"/>` +
401
  `<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>` +
402
  `<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>` +
403
+ // β›” A stylesheet needs THREE registrations, not one: the zip part, this
404
+ // Override, and a Relationship in workbook.xml.rels. Miss any and Excel
405
+ // opens the file with a silent "we found a problem" repair β€” which a zip
406
+ // signature check passes straight over.
407
+ `<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>` +
408
  `</Types>`;
409
  const rootRels =
410
  `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
 
415
  `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
416
  `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
417
  `<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>` +
418
+ `<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>` +
419
  `</Relationships>`;
420
+ // Built LAST: the format codes are interned while the body is written, so the
421
+ // stylesheet can only be correct once every cell has asked for its style.
422
+ const stylesXml = buildStyles(styles.codes());
423
  return buildZip(
424
  [
425
  { name: "[Content_Types].xml", data: enc.encode(contentTypes) },
426
  { name: "_rels/.rels", data: enc.encode(rootRels) },
427
  { name: "xl/workbook.xml", data: enc.encode(workbook) },
428
  { name: "xl/_rels/workbook.xml.rels", data: enc.encode(wbRels) },
429
+ { name: "xl/styles.xml", data: enc.encode(stylesXml) },
430
  { name: "xl/worksheets/sheet1.xml", data: enc.encode(sheet) },
431
  ],
432
  today
web/src/customer-grid/iconShapes.ts CHANGED
@@ -472,8 +472,66 @@ export const CREATABLE_MODES: DisplayMode[] = [
472
  "list",
473
  "catalog",
474
  "swipe",
 
 
 
 
 
 
 
475
  ];
476
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
477
  export const MODE_TONE: Record<DisplayMode, FolderTone> = {
478
  grid: "blue",
479
  list: "blue",
@@ -508,7 +566,13 @@ export const MODE_TONE: Record<DisplayMode, FolderTone> = {
508
  * imports it rather than keeping a second copy).
509
  */
510
  export const TYPE_LABELS: Record<FieldType, string> = {
511
- text: "Single line text",
 
 
 
 
 
 
512
  select: "Single select",
513
  multiselect: "Multi select",
514
  user: "Assignee",
@@ -546,6 +610,59 @@ export const TYPE_LABELS: Record<FieldType, string> = {
546
  status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
547
  };
548
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
549
 
550
  // ------------------------------------------------------------ glide sprites
551
 
 
472
  "list",
473
  "catalog",
474
  "swipe",
475
+ // Mounted 2026-08-11 (`CustomerGrid.tsx`, `displayMode === "form"` renders `FormInterface`), so
476
+ // `form` is offerable and its `HELD_MODES` entry came out in the same edit β€” the hold's own text
477
+ // named this mount as its release condition. ⚠ Found by `verify_icons.py::mode_parity` law E
478
+ // during /validate-wave, NOT by the lane that mounted it: T29 mounted the component and T41 built
479
+ // the Interface group, and between them the DOOR was never opened β€” the wave's biggest new
480
+ // surface was unreachable behind two green tickets.
481
+ "form",
482
  ];
483
 
484
+ /**
485
+ * ⭐ WAVE-29 R6 (owner item 10) β€” the kind dropdown splits under TWO headers, and the strings are
486
+ * the owner's own: exactly `View` and `Interface`. Not "View as" (what the popover said before),
487
+ * not "Custom interface".
488
+ *
489
+ * The line the two groups draw: a **View** ARRANGES the records β€” the same rows, re-shaped (a
490
+ * grid, a board, a deck, a chart). An **Interface** is a SURFACE BUILT OVER them: a map is a
491
+ * picture of the world with records placed on it, a catalog is a published artifact, a form is a
492
+ * door records come IN through and shows no records at all. It is the same distinction
493
+ * `MODE_TONE` below already draws by colour β€” the four tones name families of ways to arrange
494
+ * records, and `catalog`/`form` are NEUTRAL there precisely because they arrange nothing.
495
+ *
496
+ * ⚠ TOTAL over `DisplayMode`, so tsc refuses a new mode with no group rather than letting it
497
+ * vanish from the dropdown: membership is derived by FILTERING `CREATABLE_MODES` through this
498
+ * map, and a mode whose group label matched nothing would silently stop being offered while
499
+ * every existing check (paintable, labelled, toned, unique, ordered) stayed green.
500
+ * `dashboard` is grouped like the `chart` it is the legacy spelling of β€” it is never offered, and
501
+ * a partial map is a worse answer than an unused entry.
502
+ */
503
+ export const MODE_GROUP_LABELS = ["View", "Interface"] as const;
504
+ export type ModeGroup = (typeof MODE_GROUP_LABELS)[number];
505
+
506
+ export const MODE_GROUP: Record<DisplayMode, ModeGroup> = {
507
+ grid: "View",
508
+ list: "View",
509
+ kanban: "View",
510
+ calendar: "View",
511
+ chart: "View",
512
+ dashboard: "View",
513
+ timeseries: "View",
514
+ swipe: "View",
515
+ map: "Interface",
516
+ catalog: "Interface",
517
+ form: "Interface",
518
+ };
519
+
520
+ /**
521
+ * The offered modes, split into R6's two groups β€” DERIVED, never a third hand-written list.
522
+ *
523
+ * ⚠ ORDER: R6 names each group's MEMBERS; the order inside a group stays `CREATABLE_MODES`', which
524
+ * is the wave-17 owner ruling ("Grid Β· Chart Β· Calendar Β· Kanban Β· Time series Β· Map Β· List") and
525
+ * is separately asserted. The two rulings are compatible read this way and only this way: R6 moved
526
+ * `map` out of the run of views, so wave-17's single sequence can no longer exist as one list, but
527
+ * every pair it ordered is still in that relative order here.
528
+ */
529
+ export const CREATABLE_GROUPS: readonly { label: ModeGroup; modes: DisplayMode[] }[] =
530
+ MODE_GROUP_LABELS.map((label) => ({
531
+ label,
532
+ modes: CREATABLE_MODES.filter((m) => MODE_GROUP[m] === label),
533
+ }));
534
+
535
  export const MODE_TONE: Record<DisplayMode, FolderTone> = {
536
  grid: "blue",
537
  list: "blue",
 
566
  * imports it rather than keeping a second copy).
567
  */
568
  export const TYPE_LABELS: Record<FieldType, string> = {
569
+ // ⭐ WAVE-29 item 3 β€” the owner's own words: "Change 'Single line text' to 'Text', keep it
570
+ // simple for the Field type". Airtable's phrase described the column's SHAPE (one line, versus
571
+ // its long-text sibling); this product has no multi-line text kind, so the qualifier
572
+ // distinguished the type from nothing and only made the commonest row in the menu the longest.
573
+ // βœ… The STORED key is `"text"` and always was β€” the old string was never persisted anywhere,
574
+ // client or server, so this is a label change with no migration behind it.
575
+ text: "Text",
576
  select: "Single select",
577
  multiselect: "Multi select",
578
  user: "Assignee",
 
610
  status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
611
  };
612
 
613
+ /**
614
+ * ⭐ WAVE-29 C7 (item 17) β€” THE COLUMN-SUMMARY vocabulary: what a field's `agg` may be, which is
615
+ * what the totals row and the per-group subtotals compute. Server twin:
616
+ * `platform/aios_grid.py::FIELD_AGGS`, and `verify_icons.py::agg_parity` reads BOTH FILES and
617
+ * compares them name-for-name in order β€” the cross-language boundary is the one a type cannot
618
+ * police, so it gets a gate.
619
+ *
620
+ * β›” ONE CLIENT LIST, IMPORTED β€” never re-declared. `aggregations.ts` and the field editor import
621
+ * from here rather than keeping their own copy, which is why this lives in the pure data module
622
+ * beside `TYPE_LABELS` and `CREATABLE_MODES`: a second client list would need a second gate, and
623
+ * the two would drift in the direction nobody is watching. C7 says "C publishes, E mirrors"; a
624
+ * mirror that is an import cannot fall out of step at all.
625
+ *
626
+ * β›” NOT the chart vocabulary. `CHART_AGGS` (`aios_grid.py`, `viz/chartData.ts`) spells it `avg`
627
+ * and gatekeeps a STORED value β€” renaming it would silently turn saved charts into sums. This
628
+ * list spells it `average`, matching `ROLLUP_FNS` (16 names, live in production), so a column
629
+ * summary and a rollup fold say the same word for the same operation.
630
+ *
631
+ * ⚠ `median` is net-new β€” in neither `CHART_AGGS` nor `ROLLUP_FNS`.
632
+ * ⚠ `count` counts ROWS in the scope, not non-blank cells.
633
+ * ⚠ Which types may carry which: `sum/average/median/min/max` are numeric-only and the evaluator
634
+ * for that is ALREADY `isNumericFieldType` (types.ts) β€” do not write a second one. `count` is
635
+ * legal on any type.
636
+ */
637
+ export type FieldAgg = "sum" | "average" | "median" | "min" | "max" | "count";
638
+
639
+ /** ORDERED β€” the order is the picker's order, on both engines. */
640
+ export const FIELD_AGGS: readonly FieldAgg[] = [
641
+ "sum",
642
+ "average",
643
+ "median",
644
+ "min",
645
+ "max",
646
+ "count",
647
+ ];
648
+
649
+ /**
650
+ * Human labels, in the summary bar's own compact register (Airtable's wording).
651
+ *
652
+ * ⚠ `FIELD_AGG_LABELS`, not `AGG_LABELS`, and the prefix is load-bearing: `viewModes.tsx` already
653
+ * has a module-local `AGG_LABELS` for the CALENDAR summary picker over `CHART_AGGS`, where the
654
+ * same five names wear different words ("Total", "Lowest", "Highest") for a day cell. Two tables
655
+ * called `AGG_LABELS` describing two vocabularies is how a future import lands on the wrong one.
656
+ */
657
+ export const FIELD_AGG_LABELS: Record<FieldAgg, string> = {
658
+ sum: "Sum",
659
+ average: "Average",
660
+ median: "Median",
661
+ min: "Min",
662
+ max: "Max",
663
+ count: "Count",
664
+ };
665
+
666
 
667
  // ------------------------------------------------------------ glide sprites
668
 
web/src/customer-grid/liveWorkspace.ts CHANGED
@@ -197,3 +197,128 @@ export function adoptNewFields(
197
  }
198
  return fresh.length === 0 ? current : [...current, ...fresh];
199
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
197
  }
198
  return fresh.length === 0 ? current : [...current, ...fresh];
199
  }
200
+
201
+ // ===========================================================================
202
+ // THE CHANGE TOKEN (wave 29, item 20 / R11 / contract C6)
203
+ //
204
+ // Everything above answers "what appeared in the payload we just read". This
205
+ // half answers the question nobody was asking at all: **should we read?**
206
+ //
207
+ // β›” THE DEFECT (owner, 2026-08-10): a record created in another tab, by an
208
+ // automation, or by a connector sync does not appear until you reload. The
209
+ // rows fetch runs once per mount and re-runs only on ROWS_STALE_EVENT β€” and
210
+ // EVERY dispatcher of that event is this browser's own write path. Of the
211
+ // owner's three writers, only "another tab" emits anything, and only into the
212
+ // tab that did the writing. There is no polling, no revalidation, no
213
+ // visibilitychange and no BroadcastChannel anywhere in the client.
214
+ //
215
+ // The server now publishes a per-bucket revision that costs no deep copy
216
+ // (`GET /api/v1/changes`). These are the pure decisions taken on it, here
217
+ // rather than inside the effect so `verify_live_workspace.py` can run them
218
+ // under node β€” the same reason the merges above are pure.
219
+ // ===========================================================================
220
+
221
+ /** `{bucket: opaque token}`. A null means the backend publishes no revision for
222
+ * that bucket (Odoo-cached rows; a store backend that has none yet) β€” "do not
223
+ * poll this", which is a different fact from "unchanged". */
224
+ export type ChangeTokens = Record<string, string | null>;
225
+
226
+ /**
227
+ * Which buckets genuinely changed between two observations.
228
+ *
229
+ * ⭐ A CHANGE IS REPORTED ONLY WHEN BOTH SIDES CARRY A NON-NULL TOKEN AND THEY
230
+ * DIFFER. Every other case β€” the first observation, a poll that failed, a
231
+ * bucket that has no token, a bucket appearing or disappearing from the map β€”
232
+ * reports NOTHING, and the reasoning is asymmetric on purpose:
233
+ *
234
+ * * a missed change costs one stale view until the next real write, which is
235
+ * exactly today's behaviour and therefore cannot be a regression;
236
+ * * a false change costs a full rows re-read, and a false change that repeats
237
+ * EVERY interval costs one per tab per 10 s β€” the melt this whole design
238
+ * exists to avoid.
239
+ *
240
+ * So the unknown cases resolve to "no", and each of them is a one-time
241
+ * transition (first poll, a deploy adding a bucket, a backend flip) rather than
242
+ * a standing condition. The alerts engine takes the identical `seeded` posture
243
+ * server-side: its first evaluation raises nothing.
244
+ */
245
+ export function changedBuckets(
246
+ prev: ChangeTokens | null | undefined,
247
+ next: ChangeTokens | null | undefined
248
+ ): string[] {
249
+ if (!prev || !next) return []; // no baseline yet, or the poll failed
250
+ const out: string[] = [];
251
+ for (const [bucket, token] of Object.entries(next)) {
252
+ if (typeof token !== "string" || token === "") continue;
253
+ const before = prev[bucket];
254
+ if (typeof before !== "string" || before === "") continue; // baseline it
255
+ if (before !== token) out.push(bucket);
256
+ }
257
+ return out;
258
+ }
259
+
260
+ /** What a set of changed buckets asks this tab to do. */
261
+ export interface ChangePlan {
262
+ /** Drop this topic's rows memo and re-read the pool β€” the expensive one. */
263
+ refetchRows: boolean;
264
+ /** Re-read `/workspace` β€” views, fields, derived cells. The cheap one. */
265
+ rereadWorkspace: boolean;
266
+ }
267
+
268
+ /**
269
+ * β›” THE ROWS MEMO IS WHY THIS IS NOT JUST "REFETCH". `fetchTopicRows` holds a
270
+ * FIVE-MINUTE per-topic memo, cleared only by the writing tab, so a refetch
271
+ * triggered without dropping it is served from the copy that predates the very
272
+ * change we detected: a poll that costs a request, reports success, and shows
273
+ * the user nothing new. The caller must drop the memo for THIS topic β€”
274
+ * `clearTopicRowsCache(topic.rowsPath)`, never `clearCustomersCache()`, which
275
+ * would evict the other topic's window and re-download ~1 MB on the next
276
+ * surface switch.
277
+ *
278
+ * An UNRECOGNISED bucket takes the CHEAP branch. A later server may publish a
279
+ * bucket this build has never heard of (the shared overlay stratum is exactly
280
+ * that case), and "something I do not understand changed" should cost a small
281
+ * workspace read, never a pool download.
282
+ */
283
+ export function planChangeReaction(changed: readonly string[]): ChangePlan {
284
+ const plan: ChangePlan = { refetchRows: false, rereadWorkspace: false };
285
+ for (const bucket of changed) {
286
+ if (bucket === "rows") plan.refetchRows = true;
287
+ else plan.rereadWorkspace = true;
288
+ }
289
+ return plan;
290
+ }
291
+
292
+ /**
293
+ * The floor between two POOL re-reads of one topic. Only bites under sustained writing.
294
+ *
295
+ * β›” WHY A FLOOR IS NOT OPTIONAL, and the arithmetic is the same one that killed the naive design.
296
+ * `user_tables.STORE_KEY` is ONE bucket holding EVERY `ut_*` table in a tenant, so the rows token
297
+ * for every user table moves together β€” and while an automation upserts rows, or the relation
298
+ * refresh commits, the token moves on every single interval. Without a floor each open tab would
299
+ * then re-read the whole pool six times a minute, at three full-tenant deep copies per read: the
300
+ * "two tabs saturate the server" case the poller was designed to avoid, reached through the
301
+ * REFETCH instead of through the poll. Bounding cost per token request and leaving refetches
302
+ * unbounded would just move the melt one step downstream.
303
+ */
304
+ export const ROWS_REFETCH_FLOOR_MS = 30_000;
305
+
306
+ /**
307
+ * How long to wait before re-reading this topic's pool: `0` = now.
308
+ *
309
+ * ⭐ IT COALESCES, IT NEVER DROPS. A caller that is told to wait must schedule the read for the
310
+ * boundary, not discard the signal β€” several changes inside the window collapse into ONE read,
311
+ * which is the same shape `routes_tables._refresh_relations` uses server-side and for the same
312
+ * reason. Discarding would leave a tab stale for good if the burst ended right after a suppressed
313
+ * change.
314
+ *
315
+ * ⚠ THE IDLE CASE IS UNAFFECTED, which is what keeps the owner's "about ten seconds" true: one
316
+ * person adding one record hits a `lastAt` far in the past and re-reads immediately on the next
317
+ * poll. The floor is only reachable when changes arrive faster than it.
318
+ */
319
+ export function rowsRefetchDelay(lastAt: number, now: number,
320
+ floorMs: number = ROWS_REFETCH_FLOOR_MS): number {
321
+ if (!lastAt) return 0; // never read on this surface β€” go now
322
+ const since = now - lastAt;
323
+ return since >= floorMs ? 0 : floorMs - since;
324
+ }
web/src/customer-grid/mapProjection.ts CHANGED
@@ -506,6 +506,100 @@ export function googleRouteUrl(
506
  }
507
  }
508
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
509
  /** Screen-space rect (any two corners) -> normalized {x0,y0,x1,y1}. */
510
  export function normRect(ax: number, ay: number, bx: number, by: number) {
511
  return {
 
506
  }
507
  }
508
 
509
+ /** An svg's own bounding box in client px β€” the `getBoundingClientRect()` half
510
+ * of the conversion below, taken as plain data so the maths stays testable
511
+ * without a DOM. */
512
+ export interface FrameRect {
513
+ left: number;
514
+ top: number;
515
+ width: number;
516
+ height: number;
517
+ }
518
+
519
+ /**
520
+ * Client px -> the svg's own user-space coords. Every pointer gesture on the
521
+ * map β€” marquee, rubber band, cursor-anchored wheel zoom β€” starts here.
522
+ *
523
+ * ⚠ It is NOT `(client / frame) * viewBox`. MapView paints with
524
+ * `preserveAspectRatio="xMidYMid meet"`, so the viewBox is scaled UNIFORMLY by
525
+ * the tighter of the two axes and then CENTRED, leaving a letterbox band on the
526
+ * other axis. Wave 8 (`f6f45a6`) bolted a stretch-to-fill conversion onto that
527
+ * `meet` svg: the binding axis came out right and the other carried BOTH a
528
+ * wrong scale and a missing offset. On a 1400x600 frame the full 0..1000
529
+ * x-range collapsed into ~154..846 β€” so a marquee at either edge caught
530
+ * NOTHING, the rubber band lagged the cursor by ~150 px, and cursor-anchored
531
+ * zoom drifted, all from this one function. `zoomAt` and the hit test were
532
+ * always correct; they were being handed the wrong point.
533
+ *
534
+ * β›” The result is deliberately NOT clamped to the viewBox. A drag that begins
535
+ * in the letterbox band is a real gesture β€” everything from the painted edge
536
+ * inward must still be caught β€” and clamping re-breaks exactly the edge
537
+ * marquee this exists to fix.
538
+ */
539
+ export function clientToUser(
540
+ clientX: number,
541
+ clientY: number,
542
+ rect: FrameRect,
543
+ viewW: number,
544
+ viewH: number
545
+ ): Pt {
546
+ const s = Math.min(rect.width / viewW, rect.height / viewH);
547
+ if (!(s > 0) || !Number.isFinite(s)) return { x: 0, y: 0 };
548
+ const offX = (rect.width - viewW * s) / 2;
549
+ const offY = (rect.height - viewH * s) / 2;
550
+ return { x: (clientX - rect.left - offX) / s, y: (clientY - rect.top - offY) / s };
551
+ }
552
+
553
+ /**
554
+ * Is `p` inside the closed polygon `poly`? Even-odd ray casting (the crossing
555
+ * number), in the same user-space units `toScreen` returns.
556
+ *
557
+ * β›” It is NOT a bounding-box test, and that difference IS the feature. A lasso
558
+ * drawn as a C or a horseshoe must EXCLUDE whatever sits in its mouth β€”
559
+ * otherwise it is the rectangle marquee wearing a lasso's name, which is the
560
+ * one thing a person drawing a loop by hand would never expect. The gate
561
+ * asserts exactly that case, over a shape whose bounding box gives a different
562
+ * answer: a convex test polygon would make the control inert.
563
+ *
564
+ * The ray is cast along +x from `p`, and each edge that straddles `p.y` and
565
+ * crosses to the LEFT of nothing / RIGHT of `p.x` flips the parity. A point
566
+ * exactly on a vertex or an edge may fall either way: this selects pins under a
567
+ * hand-drawn path, where a half-pixel tie carries no meaning and an epsilon to
568
+ * break it would be a number nobody could justify.
569
+ */
570
+ export function pointInPolygon(p: Pt, poly: Pt[]): boolean {
571
+ if (poly.length < 3) return false;
572
+ let inside = false;
573
+ for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
574
+ const a = poly[i];
575
+ const b = poly[j];
576
+ const straddles = a.y > p.y !== b.y > p.y;
577
+ if (straddles && p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
578
+ }
579
+ return inside;
580
+ }
581
+
582
+ /**
583
+ * The axis-aligned bounds of a freehand path, in `normRect`'s own {x0,y0,x1,y1}
584
+ * shape so one mis-click rule can measure either gesture. An empty path is a
585
+ * zero box rather than an Infinity one β€” the caller's "did this move at all"
586
+ * test must answer NO, not NaN.
587
+ */
588
+ export function pathBounds(pts: Pt[]) {
589
+ if (pts.length === 0) return { x0: 0, y0: 0, x1: 0, y1: 0 };
590
+ let x0 = pts[0].x;
591
+ let y0 = pts[0].y;
592
+ let x1 = pts[0].x;
593
+ let y1 = pts[0].y;
594
+ for (const p of pts) {
595
+ if (p.x < x0) x0 = p.x;
596
+ if (p.x > x1) x1 = p.x;
597
+ if (p.y < y0) y0 = p.y;
598
+ if (p.y > y1) y1 = p.y;
599
+ }
600
+ return { x0, y0, x1, y1 };
601
+ }
602
+
603
  /** Screen-space rect (any two corners) -> normalized {x0,y0,x1,y1}. */
604
  export function normRect(ax: number, ay: number, bx: number, by: number) {
605
  return {
web/src/customer-grid/theme.ts CHANGED
@@ -254,20 +254,14 @@ export type ControlTone = "filter" | "sort" | "group";
254
  */
255
  export const INVOLVED_HEADER_FONT = "700 13px";
256
 
257
- /**
258
- * `#RRGGBB` β†’ `rgba(r, g, b, a)`.
259
- *
260
- * Exists so a wash below is DERIVED from the palette constant it belongs to instead of being a
261
- * second hand-written copy of the same hue. `verify_icons`' I7c parity diffs the `LP_*` hexes in
262
- * this file against the `--lp-*` custom properties in index.css β€” a literal `rgba(53, 117, 78,
263
- * …)` beside `LP_GREEN_DEEP` would sit OUTSIDE that check and could drift from the token the
264
- * toolbar chip reads while both still looked right in isolation. Derivation puts the wash under
265
- * the gate that already exists.
266
- */
267
- function washOf(hex: string, alpha: number): string {
268
- const n = parseInt(hex.slice(1), 16);
269
- return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`;
270
- }
271
 
272
  /**
273
  * ⭐ Wave-15 item 8 (owner rulings R5 + R6) β€” **an involved column wears ITS OWN CONTROL'S HUE
@@ -277,11 +271,22 @@ function washOf(hex: string, alpha: number): string {
277
  * pastels read as "too loud". Both instructions came from the owner and both were about the same
278
  * thing β€” R4 objected to the LOUDNESS, R5 asks for the LINK β€” so what changed is the strength,
279
  * not the idea: the header takes the chip's own pale tint (`--lp-*-tint`, which is what the chip
280
- * paints, so the eye connects the two without being told), and the cell takes the chip's INK at
281
- * 6%, which is a whisper. What is gone is the wave-14 claim that hue coding "lives ONLY in the
282
- * toolbar chips".
283
  *
284
- * Three properties carried over from R4's version, each of which was a bug fix:
 
 
 
 
 
 
 
 
 
 
 
 
285
  *
286
  * 1. **All THREE header states carry the tint.** Setting `bgHeader` + `bgHeaderHovered` and not
287
  * `bgHeaderHasFocus` is why the tint used to VANISH the moment a cell in that column was
@@ -289,31 +294,28 @@ function washOf(hex: string, alpha: number): string {
289
  * (`data-grid-render.header.js:48,59`). There must be no state in which the header changes
290
  * identity.
291
  * 2. **The bold** (`INVOLVED_HEADER_FONT`, see its note β€” it needs drawGridHeader's help).
292
- * 3. **`bgCell` is rgba, NOT a hex, and that is load-bearing.** `mergeAndRealizeTheme`
293
- * alpha-BLENDS `bgCell` and hard-replaces every other key (glide `common/styles.js`). An
294
- * opaque tint here would ERASE a colour-by row's status wash wherever the two met β€” which is
295
- * exactly what the pre-wave-14 `LP_*_TINT` cell values did.
296
  */
297
  export const COLUMN_TONE_THEME: Record<ControlTone, Partial<Theme>> = {
298
  filter: {
299
  bgHeader: LP_GREEN_TINT,
300
  bgHeaderHovered: LP_GREEN_TINT,
301
  bgHeaderHasFocus: LP_GREEN_TINT,
302
- bgCell: washOf(LP_GREEN_DEEP, 0.06),
303
  headerFontStyle: INVOLVED_HEADER_FONT,
304
  },
305
  sort: {
306
  bgHeader: LP_YELLOW_TINT,
307
  bgHeaderHovered: LP_YELLOW_TINT,
308
  bgHeaderHasFocus: LP_YELLOW_TINT,
309
- bgCell: washOf(LP_YELLOW_DEEP, 0.06),
310
  headerFontStyle: INVOLVED_HEADER_FONT,
311
  },
312
  group: {
313
  bgHeader: LP_PURPLE_TINT,
314
  bgHeaderHovered: LP_PURPLE_TINT,
315
  bgHeaderHasFocus: LP_PURPLE_TINT,
316
- bgCell: washOf(LP_PURPLE_DEEP, 0.06),
317
  headerFontStyle: INVOLVED_HEADER_FONT,
318
  },
319
  };
 
254
  */
255
  export const INVOLVED_HEADER_FONT = "700 13px";
256
 
257
+ /* β›” `washOf` (`#RRGGBB` β†’ `rgba(r, g, b, a)`) DELETED with the body whisper below β€” wave-29 R8,
258
+ 2026-08-11. Its ONLY three callers were `COLUMN_TONE_THEME`'s `bgCell` washes, and an unused
259
+ hex→rgba helper sitting beside the tone table is an invitation to paint a body wash back in.
260
+ The palette constants it derived from (`LP_*_DEEP`) stay: they are one half of `verify_icons`'
261
+ I7c parity against index.css's `--lp-*`, and deleting one side of a mirrored pair reddens that
262
+ gate for a reason unrelated to any defect. Every rgba still on this canvas (`STATUS_ROW_THEME`,
263
+ `HOVER_ROW_THEME`, `ROW_HIGHLIGHT_NEUTRAL`) is a ROW wash written as a literal, which is where
264
+ those already lived β€” nothing lost its derivation. */
 
 
 
 
 
 
265
 
266
  /**
267
  * ⭐ Wave-15 item 8 (owner rulings R5 + R6) β€” **an involved column wears ITS OWN CONTROL'S HUE
 
271
  * pastels read as "too loud". Both instructions came from the owner and both were about the same
272
  * thing β€” R4 objected to the LOUDNESS, R5 asks for the LINK β€” so what changed is the strength,
273
  * not the idea: the header takes the chip's own pale tint (`--lp-*-tint`, which is what the chip
274
+ * paints, so the eye connects the two without being told). What is gone is the wave-14 claim that
275
+ * hue coding "lives ONLY in the toolbar chips".
 
276
  *
277
+ * β›” **WAVE-29 R8 (2026-08-11) β€” THIS IS A HEADER-ONLY SIGNAL. The body whisper is DELETED.**
278
+ * R5's other half was a `bgCell: washOf(<tone>_DEEP, 0.06)` on every cell of an involved column.
279
+ * The owner's complaint is the one the whisper's own doc note predicted and shrugged off: a cell
280
+ * carries the record's meaning (a `colorBy` status wash, an automation outcome), and a column-level
281
+ * wash layered over it means **sorting a table repaints its records** β€” so a `growing` row stops
282
+ * looking green because somebody clicked a sort. R8: *"sorting or filtering a column must never
283
+ * repaint a record body again."* The signal is not weakened, it MOVED β€” it lives entirely in the
284
+ * header, where nothing else is competing for the same pixels, and where all three states below
285
+ * carry it. A body wash is now something only a ROW theme (`STATUS_ROW_THEME`) or a CELL theme
286
+ * (`cells.AUTOMATION_TINT`) may paint, which makes "who owns this hue" answerable per layer.
287
+ * ⚠ Do NOT reinstate it at a lower alpha: a fainter whisper is the same collision, harder to see.
288
+ *
289
+ * Two properties carried over from R4's version, each of which was a bug fix:
290
  *
291
  * 1. **All THREE header states carry the tint.** Setting `bgHeader` + `bgHeaderHovered` and not
292
  * `bgHeaderHasFocus` is why the tint used to VANISH the moment a cell in that column was
 
294
  * (`data-grid-render.header.js:48,59`). There must be no state in which the header changes
295
  * identity.
296
  * 2. **The bold** (`INVOLVED_HEADER_FONT`, see its note β€” it needs drawGridHeader's help).
297
+ *
298
+ * (The third β€” *"`bgCell` is rgba, NOT a hex, and that is load-bearing"* β€” died with the wash it
299
+ * described. It is preserved in `STATUS_ROW_THEME`'s and `ROW_HIGHLIGHT_NEUTRAL`'s notes, which
300
+ * are the two tables where the alpha-blend rule still governs something that paints.)
301
  */
302
  export const COLUMN_TONE_THEME: Record<ControlTone, Partial<Theme>> = {
303
  filter: {
304
  bgHeader: LP_GREEN_TINT,
305
  bgHeaderHovered: LP_GREEN_TINT,
306
  bgHeaderHasFocus: LP_GREEN_TINT,
 
307
  headerFontStyle: INVOLVED_HEADER_FONT,
308
  },
309
  sort: {
310
  bgHeader: LP_YELLOW_TINT,
311
  bgHeaderHovered: LP_YELLOW_TINT,
312
  bgHeaderHasFocus: LP_YELLOW_TINT,
 
313
  headerFontStyle: INVOLVED_HEADER_FONT,
314
  },
315
  group: {
316
  bgHeader: LP_PURPLE_TINT,
317
  bgHeaderHovered: LP_PURPLE_TINT,
318
  bgHeaderHasFocus: LP_PURPLE_TINT,
 
319
  headerFontStyle: INVOLVED_HEADER_FONT,
320
  },
321
  };
web/src/customer-grid/types.ts CHANGED
The diff for this file is too large to render. See raw diff
 
web/src/customer-grid/useCustomerData.ts CHANGED
@@ -26,8 +26,17 @@ import { useCallback, useEffect, useRef, useState } from "react";
26
  import type { Dispatch, SetStateAction } from "react";
27
  import { topicForScope } from "./types";
28
  import type { CustomersPayload, Field, GridWorkspace, Row } from "./types";
29
- import { fetchTopicRows, fetchWorkspace, patchTopicRow, setSurfaceScope } from "./apiBridge";
 
 
 
 
 
 
 
30
  import { DERIVED_CELLS_EVENT, ROWS_STALE_EVENT, WORKSPACE_STALE_EVENT } from "../apiContract";
 
 
31
  import type { SurfaceScope } from "./apiBridge";
32
  import {
33
  emitHostEvent,
@@ -158,29 +167,29 @@ export interface CustomerData {
158
  patchOverlay: (pid: number, updates: Partial<Row>) => void;
159
  }
160
 
161
- interface CustomerDataOptions {
162
- /** A linked-record grid is nested inside its parent grid. It must not replace the
163
- * module-level write scope that the parent still owns. */
164
- bindSurface?: boolean;
165
- /** Linked-record grids deliberately open on a clean Grid view, not on the target
166
- * database's last saved view. The rows payload already carries its field contract. */
167
- includeWorkspace?: boolean;
168
- /** Defence in depth for read-only nested grids. */
169
- writable?: boolean;
170
- }
171
-
172
- export function useCustomerData(
173
- scope: SurfaceScope = "customer",
174
- options: CustomerDataOptions = {},
175
- ): CustomerData {
176
- const bindSurface = options.bindSurface !== false;
177
- const includeWorkspace = options.includeWorkspace !== false;
178
- const writable = options.writable !== false;
179
  // β›” SET BEFORE THE FIRST FETCH, not in an effect. Every event the grid emits carries this
180
  // scope, and an effect would run AFTER the first render β€” so a write triggered by that render
181
  // would be posted as `customer` from the Cohort surface. Module scope + a synchronous set is
182
  // what keeps the read and the write talking about the same surface.
183
- if (bindSurface) setSurfaceScope(scope);
184
  // Wave 16 C-TOPIC: the topic is DERIVED from the scope (cohort = the customer topic), so
185
  // the rows fetch, the patch route and the workspace scope can never disagree about which
186
  // table this is.
@@ -212,6 +221,70 @@ export function useCustomerData(
212
  return () => window.removeEventListener(ROWS_STALE_EVENT, onStale);
213
  }, []);
214
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
215
  useEffect(() => {
216
  if (STREAMLIT_COMPONENT) {
217
  const accept = () => {
@@ -274,14 +347,14 @@ export function useCustomerData(
274
  loudScope.current = scope;
275
 
276
  async function load() {
277
- const [payload, workspace] = await Promise.all([
278
- fetchTopicRows(topic),
279
  // A workspace that cannot be read at first paint is not "a table with no saved
280
  // views" β€” it is a table whose schema we do not have, and the grid used to fill
281
  // that hole from a localStorage bucket shared with every other surface.
282
- includeWorkspace
283
- ? fetchWorkspace(scope, { announceFailure: firstPaint })
284
- : Promise.resolve(null),
285
  ]);
286
  if (cancelled || !payload) return;
287
  setData(workspace ? withWorkspace(payload, workspace) : payload);
@@ -296,9 +369,9 @@ export function useCustomerData(
296
  // nothing and cost the expensive call. The measure channel rides the workspace
297
  // (see `withWorkspace`), so a NEW measure column's values arrive on this cheap
298
  // re-read too β€” no pool refetch.
299
- async function reread() {
300
- if (!includeWorkspace) return;
301
- const ws = await fetchWorkspace(scope);
302
  if (cancelled || !ws) return; // absent stays absent β€” never blank a live panel
303
  setData((prev) => (prev ? withWorkspace(prev, ws) : prev));
304
  }
@@ -352,14 +425,14 @@ export function useCustomerData(
352
  // `topic` is a stable module constant per scope (topicForScope β€” ut topics are memoized
353
  // per key for exactly this dependency), so this cannot loop. `rowsBump` re-runs it on the
354
  // rows-stale signal only.
355
- }, [scope, topic, rowsBump, includeWorkspace]);
356
 
357
  // Optimistic overlay write: apply the edit immediately (so the grid cell and
358
  // the detail panel reflect it at once), snapshot the pre-edit entry, then
359
  // PATCH. On a non-ok response, restore the snapshot so the UI never shows a
360
  // value the server rejected.
361
- const patchOverlay = useCallback((pid: number, updates: Partial<Row>) => {
362
- if (!writable) return;
363
  let prevEntry: Partial<Row> | undefined;
364
  setOverlayEdits((prev) => {
365
  prevEntry = prev[pid];
@@ -424,7 +497,7 @@ export function useCustomerData(
424
  return next;
425
  });
426
  });
427
- }, [topic, writable]);
428
 
429
  return {
430
  fields: data?.fields ?? [],
 
26
  import type { Dispatch, SetStateAction } from "react";
27
  import { topicForScope } from "./types";
28
  import type { CustomersPayload, Field, GridWorkspace, Row } from "./types";
29
+ import {
30
+ clearTopicRowsCache,
31
+ fetchTopicRows,
32
+ fetchWorkspace,
33
+ patchTopicRow,
34
+ setSurfaceScope,
35
+ subscribeChanges,
36
+ } from "./apiBridge";
37
  import { DERIVED_CELLS_EVENT, ROWS_STALE_EVENT, WORKSPACE_STALE_EVENT } from "../apiContract";
38
+ import { planChangeReaction, rowsRefetchDelay } from "./liveWorkspace";
39
+ import { signal } from "../apiContract";
40
  import type { SurfaceScope } from "./apiBridge";
41
  import {
42
  emitHostEvent,
 
167
  patchOverlay: (pid: number, updates: Partial<Row>) => void;
168
  }
169
 
170
+ interface CustomerDataOptions {
171
+ /** A linked-record grid is nested inside its parent grid. It must not replace the
172
+ * module-level write scope that the parent still owns. */
173
+ bindSurface?: boolean;
174
+ /** Linked-record grids deliberately open on a clean Grid view, not on the target
175
+ * database's last saved view. The rows payload already carries its field contract. */
176
+ includeWorkspace?: boolean;
177
+ /** Defence in depth for read-only nested grids. */
178
+ writable?: boolean;
179
+ }
180
+
181
+ export function useCustomerData(
182
+ scope: SurfaceScope = "customer",
183
+ options: CustomerDataOptions = {},
184
+ ): CustomerData {
185
+ const bindSurface = options.bindSurface !== false;
186
+ const includeWorkspace = options.includeWorkspace !== false;
187
+ const writable = options.writable !== false;
188
  // β›” SET BEFORE THE FIRST FETCH, not in an effect. Every event the grid emits carries this
189
  // scope, and an effect would run AFTER the first render β€” so a write triggered by that render
190
  // would be posted as `customer` from the Cohort surface. Module scope + a synchronous set is
191
  // what keeps the read and the write talking about the same surface.
192
+ if (bindSurface) setSurfaceScope(scope);
193
  // Wave 16 C-TOPIC: the topic is DERIVED from the scope (cohort = the customer topic), so
194
  // the rows fetch, the patch route and the workspace scope can never disagree about which
195
  // table this is.
 
221
  return () => window.removeEventListener(ROWS_STALE_EVENT, onStale);
222
  }, []);
223
 
224
+ /**
225
+ * ⭐ WAVE 29, item 20 (R11 / C6) β€” THE LIVE VIEW.
226
+ *
227
+ * β›” THE DEFECT, stated as the owner found it: a record created in another tab, by an
228
+ * automation, or by a connector sync does not appear in a filtered view until you reload. The
229
+ * effect below re-runs on `rowsBump`, and `rowsBump` moves only on `ROWS_STALE_EVENT` β€” whose
230
+ * every dispatcher is THIS browser's own write path. So of the three writers the owner named,
231
+ * two could never reach this hook at all, and the third only reached the tab that did the
232
+ * writing. Nothing here was broken; nothing was ever asking.
233
+ *
234
+ * β›” AND POLLING THE ROWS ENDPOINT WOULD HAVE BEEN A WORSE BUG THAN THE ONE IT FIXED: each
235
+ * rows request costs three full-tenant deep copies under one lock on a single uvicorn process
236
+ * (~4.2 s of lock-held CPU at the documented ceiling), so two tabs asking every ten seconds
237
+ * saturate the server for everybody. `GET /changes` reads an in-memory counter instead and
238
+ * copies nothing, which is why this can run at all.
239
+ *
240
+ * The reaction is deliberately the plumbing that already exists: drop this topic's rows memo
241
+ * and raise the same stale signals a local write raises. Nothing here merges rows by hand β€”
242
+ * `pendingRows` and the cell journal already own "keep what this browser just did", and a
243
+ * second merge law beside them is how the two drift.
244
+ */
245
+ useEffect(() => {
246
+ if (STREAMLIT_COMPONENT || readEmbed()) return; // the host pushes; there is nothing to poll
247
+ let lastRowsRead = 0;
248
+ let coalescing: ReturnType<typeof setTimeout> | null = null;
249
+
250
+ const readRows = () => {
251
+ // β›” THE MEMO FIRST, ALWAYS. `fetchTopicRows` holds a five-minute per-topic window, so a
252
+ // bump without this is served the copy that predates the change we just detected β€” a
253
+ // refetch that costs a request, succeeds, and shows the user nothing.
254
+ clearTopicRowsCache(topic.rowsPath);
255
+ lastRowsRead = Date.now();
256
+ setRowsBump((b) => b + 1);
257
+ };
258
+
259
+ // β›” `topic.scope`, NEVER the hook's own `scope`. They are not the same string: the COHORT
260
+ // surface is the customer topic (`topicForScope`), and `?scope=cohort` names no bucket the
261
+ // server watches β€” so this would have 404'd six times a minute on a live surface while
262
+ // reporting no changes and failing silently, which is the shipped bug wearing a poller. One
263
+ // resolver decides which table a surface is, and it is `topicForScope`.
264
+ const unsubscribe = subscribeChanges(topic.scope, (changed) => {
265
+ const plan = planChangeReaction(changed);
266
+ if (plan.refetchRows) {
267
+ const wait = rowsRefetchDelay(lastRowsRead, Date.now());
268
+ // COALESCE, never drop: under a sustained writer the token moves on every interval, and
269
+ // re-reading the pool each time is the saturation case. Waiting collapses a burst into
270
+ // one read at the boundary; discarding would leave this tab stale for good if the burst
271
+ // ended on a suppressed change.
272
+ if (wait === 0) readRows();
273
+ else if (!coalescing)
274
+ coalescing = setTimeout(() => { coalescing = null; readRows(); }, wait);
275
+ }
276
+ if (plan.rereadWorkspace) signal(WORKSPACE_STALE_EVENT);
277
+ });
278
+
279
+ return () => {
280
+ unsubscribe();
281
+ // ⚠ AND THE COALESCING TIMER, which the unsubscribe above knows nothing about: it lives in
282
+ // this closure, not in the poller. Left armed, it fires a state update into an unmounted
283
+ // component up to the floor after the user has navigated away.
284
+ if (coalescing) clearTimeout(coalescing);
285
+ };
286
+ }, [scope, topic]);
287
+
288
  useEffect(() => {
289
  if (STREAMLIT_COMPONENT) {
290
  const accept = () => {
 
347
  loudScope.current = scope;
348
 
349
  async function load() {
350
+ const [payload, workspace] = await Promise.all([
351
+ fetchTopicRows(topic),
352
  // A workspace that cannot be read at first paint is not "a table with no saved
353
  // views" β€” it is a table whose schema we do not have, and the grid used to fill
354
  // that hole from a localStorage bucket shared with every other surface.
355
+ includeWorkspace
356
+ ? fetchWorkspace(scope, { announceFailure: firstPaint })
357
+ : Promise.resolve(null),
358
  ]);
359
  if (cancelled || !payload) return;
360
  setData(workspace ? withWorkspace(payload, workspace) : payload);
 
369
  // nothing and cost the expensive call. The measure channel rides the workspace
370
  // (see `withWorkspace`), so a NEW measure column's values arrive on this cheap
371
  // re-read too β€” no pool refetch.
372
+ async function reread() {
373
+ if (!includeWorkspace) return;
374
+ const ws = await fetchWorkspace(scope);
375
  if (cancelled || !ws) return; // absent stays absent β€” never blank a live panel
376
  setData((prev) => (prev ? withWorkspace(prev, ws) : prev));
377
  }
 
425
  // `topic` is a stable module constant per scope (topicForScope β€” ut topics are memoized
426
  // per key for exactly this dependency), so this cannot loop. `rowsBump` re-runs it on the
427
  // rows-stale signal only.
428
+ }, [scope, topic, rowsBump, includeWorkspace]);
429
 
430
  // Optimistic overlay write: apply the edit immediately (so the grid cell and
431
  // the detail panel reflect it at once), snapshot the pre-edit entry, then
432
  // PATCH. On a non-ok response, restore the snapshot so the UI never shows a
433
  // value the server rejected.
434
+ const patchOverlay = useCallback((pid: number, updates: Partial<Row>) => {
435
+ if (!writable) return;
436
  let prevEntry: Partial<Row> | undefined;
437
  setOverlayEdits((prev) => {
438
  prevEntry = prev[pid];
 
497
  return next;
498
  });
499
  });
500
+ }, [topic, writable]);
501
 
502
  return {
503
  fields: data?.fields ?? [],
web/src/customer-grid/useGetCellContent.ts CHANGED
@@ -201,6 +201,10 @@ export function useGetCellContent(
201
  // Synthetic grouping rows branch BEFORE the data path.
202
  if (vr.kind === "group-header")
203
  return groupHeaderCell(vr, col, visibleCols.length, groupLabelSpace, measureText);
 
 
 
 
204
  if (vr.kind === "group-footer") return groupFooterCell(vr, field);
205
 
206
  if (!field) return EMPTY_CELL;
 
201
  // Synthetic grouping rows branch BEFORE the data path.
202
  if (vr.kind === "group-header")
203
  return groupHeaderCell(vr, col, visibleCols.length, groupLabelSpace, measureText);
204
+ /* ⭐ WAVE-29 T33 β€” the TOTALS row arrives here as a `group-footer` carrying
205
+ `TOTAL_GROUP_KEY`, so one function paints a subtotal and a total. A table's total and a
206
+ group's subtotal are the same statement at two scopes; a second renderer would be a
207
+ second place for the tint, the weight and the right-alignment to drift apart. */
208
  if (vr.kind === "group-footer") return groupFooterCell(vr, field);
209
 
210
  if (!field) return EMPTY_CELL;
web/src/customer-grid/useGridColumns.ts CHANGED
@@ -91,6 +91,14 @@ function filteredKeys(
91
  *
92
  * ⚠ Wave-15 R5: the returned object is one of the three SHARED `COLUMN_TONE_THEME` references
93
  * (never a fresh object), which is what keeps glide's theme merge cache-friendly across frames.
 
 
 
 
 
 
 
 
94
  */
95
  function columnTheme(tone: ControlTone | undefined): Partial<Theme> | undefined {
96
  return tone ? COLUMN_TONE_THEME[tone] : undefined;
 
91
  *
92
  * ⚠ Wave-15 R5: the returned object is one of the three SHARED `COLUMN_TONE_THEME` references
93
  * (never a fresh object), which is what keeps glide's theme merge cache-friendly across frames.
94
+ *
95
+ * β›” Wave-29 R8 (2026-08-11): those three references now carry **HEADER keys only**. glide builds a
96
+ * header theme from the column override alone and a cell theme from column β†’ row β†’ cell
97
+ * (`data-grid-render.header.js:59`, `common/styles.js mergeAndRealizeTheme`), so the tone reaching
98
+ * a column theme is exactly how a sort used to repaint record bodies. With no `bgCell` in the
99
+ * table there is no longer a path from "this column is sorted" to a cell's background at all β€”
100
+ * which is a property of what `COLUMN_TONE_THEME` CONTAINS, not of anything this function does.
101
+ * A body wash belongs to `getRowThemeOverride` (status) or the cell itself (automation).
102
  */
103
  function columnTheme(tone: ControlTone | undefined): Partial<Theme> | undefined {
104
  return tone ? COLUMN_TONE_THEME[tone] : undefined;
web/src/customer-grid/useVisibleRows.ts CHANGED
@@ -622,6 +622,70 @@ function groupRows(
622
  return out;
623
  }
624
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
625
  /** Everything `useVisibleRows` does, minus the memo β€” so it is callable from a plain test.
626
  * The hook is a one-line wrapper; this is where the pipeline actually lives. */
627
  export interface PipelineInput {
 
622
  return out;
623
  }
624
 
625
+ /**
626
+ * ⭐⭐ WAVE-29 T33 β€” the DISPLAY cap, counted in DATA ROWS and never mid-group.
627
+ *
628
+ * `visibleRows` is FLATTENED: `[header, row, row, footer, header, …]`. The cap used to be a
629
+ * straight `slice(0, cap)` over that list, so two things went wrong at once for a grouped view:
630
+ * the structural rows ate the budget (a table of 50 groups spent 100 of its 200 slots on headers
631
+ * and footers), and a cut could land BETWEEN a group's last row and its footer β€” which deleted
632
+ * that group's subtotal from the screen with nothing to say so.
633
+ *
634
+ * The rule here: a DATA row costs one, headers and footers cost nothing, and a group is admitted
635
+ * WHOLE or not at all β€” so every group you can see carries its own footer, and "showing first N"
636
+ * counts the thing the reader is counting.
637
+ */
638
+ export function sliceForDisplay(rows: VisibleRow[], cap: number): VisibleRow[] {
639
+ const out: VisibleRow[] = [];
640
+ let taken = 0;
641
+ /** The group being accumulated. Held back until its footer arrives, because a group without
642
+ * its own subtotal is the defect this function exists to remove. */
643
+ let group: { header: VisibleRow; rows: VisibleRow[]; footer?: VisibleRow } | null = null;
644
+
645
+ const flush = (g: typeof group): void => {
646
+ if (!g) return;
647
+ // A COLLAPSED group emits a header and nothing else β€” complete as it stands.
648
+ if (!g.rows.length && !g.footer) {
649
+ out.push(g.header);
650
+ return;
651
+ }
652
+ // No footer means the cap cut this group short. Dropped WHOLE rather than shown with a
653
+ // subtotal that describes rows the reader cannot see β€” a wrong number beats a missing one
654
+ // only if you never have to reconcile it.
655
+ if (!g.footer) return;
656
+ out.push(g.header, ...g.rows, g.footer);
657
+ };
658
+
659
+ for (const vr of rows) {
660
+ if (vr.kind === "group-header") {
661
+ flush(group);
662
+ group = null;
663
+ if (taken >= cap) break; // no budget for another group at all
664
+ group = { header: vr, rows: [] };
665
+ continue;
666
+ }
667
+ if (vr.kind === "group-footer") {
668
+ if (group) {
669
+ group.footer = vr;
670
+ flush(group);
671
+ }
672
+ group = null;
673
+ continue;
674
+ }
675
+ if (vr.kind !== "data") continue; // a totals row never reaches here (appended later)
676
+ if (taken >= cap) {
677
+ if (!group) break; // ungrouped: nothing structural left to wait for
678
+ group = null; // this group is truncated -> drop it whole
679
+ continue;
680
+ }
681
+ taken += 1;
682
+ if (group) group.rows.push(vr);
683
+ else out.push(vr);
684
+ }
685
+ flush(group);
686
+ return out;
687
+ }
688
+
689
  /** Everything `useVisibleRows` does, minus the memo β€” so it is callable from a plain test.
690
  * The hook is a one-line wrapper; this is where the pipeline actually lives. */
691
  export interface PipelineInput {