Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,5 +1,5 @@
 {
- "current": "398e917",
+ "current": "cb05235",
  "releases": [
   {
    "version": "v25",

VERSION

@@ -1 +1 @@
-398e917
+cb05235

api/routes_grid.py

@@ -726,6 +726,111 @@ def grid_calendar_metrics(body: dict = Body(default=None), scope: str = "custome
     return out
 
 
+#: ⭐⭐ THE BULK CELL DOOR'S OWN CEILING, and it is REPORTED rather than silently enforced. The
+#: standing no-cap rule governs data read from a connected source; this is a WRITE of team-typed
+#: values, so a bound is right — but R6's second sentence still binds, which is why exceeding it
+#: is a 400 naming the number and the count, never a truncation.
+#: Sized against the real job with headroom: the 2027 catalog is 1,397 rows.
+MAX_BULK_ROWS = 10_000
+
+
+@router.post("/grid/bulk-cells")
+def bulk_cells(body: dict = Body(default=None),
+               session: Session = Depends(require_session)):
+    """`{scopeKey, rows: {"<pid>": {key: value}}}` → shared cells on many rows, ONE transaction.
+
+    ⭐⭐ WHY THIS EXISTS AT ALL, because "we already have `/grid/events`" is the obvious objection.
+    That door is capped at `_MAX_EVENTS = 24` (it is sized for the client's resend window), so a
+    1,397-row import is ~59 sequential POSTs against ONE JSON document — and this repo has a
+    MEASURED scar for exactly that: 18 writes against one document under the store's coalescing
+    single-flight landed **zero** while answering 200 eighteen times. Raising `_MAX_EVENTS` would
+    have widened the browser's own resend window to fix a script's problem. One door, one
+    transaction, is the honest shape.
+
+    ⛔ TENANT-WIDE KEYS ONLY, AND THAT IS THE POINT RATHER THAN A LIMITATION. It writes through
+    `shared_overlay`, which every account in the tenant reads. A per-user bulk write would be a
+    contradiction: nobody imports 1,397 rows of the team's work so that one account can see it —
+    that is precisely the failure owner ruling R6 was made to avoid. A key that is not declared
+    `shared: true` in the canonical contract is REFUSED BY NAME.
+
+    ⛔ ADMIN ONLY. This mutates data every account in the tenant reads, in bulk, in one call.
+    D-172 already records that the shared stratum has an asymmetric wall (anyone may create a
+    tenant-wide column, only the creator or an admin may delete one); a new door does not get to
+    inherit the loose half of an asymmetry somebody already flagged.
+    """
+    import core.shared_overlay as shared_overlay
+    import modules.product_data as pd
+    import core.perm_scope as perm_scope
+    from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
+
+    scope = _scope_or_400((body or {}).get("scopeKey"))
+    if scope != "product":
+        # Fail-closed with the reason: the shared stratum is a PRODUCT-topic mechanism today.
+        raise err(400, "scope_not_bulk_writable",
+                  f"bulk cell writes are available on the product database; '{scope}' has no "
+                  f"tenant-wide cell stratum")
+    session.require(PRODUCT_MODULE)
+    if not session.admin:
+        raise err(403, "admin_only",
+                  "a bulk write changes values every account in this workspace reads")
+
+    rows = (body or {}).get("rows")
+    if not isinstance(rows, dict):
+        raise err(400, "bad_rows", "expected {rows: {\"<pid>\": {field: value}}}")
+    if len(rows) > MAX_BULK_ROWS:
+        raise err(400, "too_many_rows",
+                  f"at most {MAX_BULK_ROWS} rows per request; this one carried {len(rows)}")
+
+    pids, _team, _src, fields_base = scoped_pool(session)
+    allowed = {int(p) for p in pids}
+    shared_keys = set(pd.SHARED_KEYS())
+    hidden = perm_scope.hidden_keys(session.user, PRODUCT_MODULE, fields_base)
+
+    clean, unknown_pid, refused_keys = {}, [], {}
+    for raw_pid, values in rows.items():
+        try:
+            pid = int(raw_pid)
+        except (TypeError, ValueError):
+            unknown_pid.append(str(raw_pid)[:40])
+            continue
+        # ⚠ THE POOL IS THE WALL. `scoped_pool` is the same predicate the read door uses, so a
+        # caller cannot write a row they could not see — including a row in another BU.
+        if pid not in allowed:
+            unknown_pid.append(str(raw_pid)[:40])
+            continue
+        keep = {}
+        for key, value in dict(values or {}).items():
+            key = str(key)
+            if key not in shared_keys:
+                refused_keys.setdefault("not_shared", set()).add(key)
+                continue
+            if key in hidden:
+                refused_keys.setdefault("hidden_by_permissions", set()).add(key)
+                continue
+            if not isinstance(value, (str, int, float)) or isinstance(value, bool):
+                refused_keys.setdefault("unsupported_value", set()).add(key)
+                continue
+            keep[key] = value
+        if keep:
+            clean[pid] = keep
+
+    written = shared_overlay.put_rows(pd.TABLE_KEY, clean, st=pd.TABLE_OPS.st) if clean else {}
+    out = {
+        "rows_written": len(written),
+        "cells_written": sum(len(v) for v in written.values()),
+        "rows_requested": len(rows),
+    }
+    # ⭐ R6's second sentence: what did NOT land, and why. A bulk door that reports only its
+    # successes is how 701 unmatched SKUs disappear quietly.
+    if unknown_pid:
+        out["rows_not_in_your_pool"] = {"count": len(unknown_pid),
+                                        "sample": sorted(unknown_pid)[:10]}
+    if refused_keys:
+        out["refused_fields"] = {reason: sorted(keys)
+                                 for reason, keys in refused_keys.items()}
+    return out
+
+
 @router.post("/grid/events")
 def grid_events_route(body: dict = Body(default=None),
                       session: Session = Depends(require_session)):
@@ -822,13 +927,30 @@ def grid_events_route(body: dict = Body(default=None),
     try:
         for one in events:
             eid = str(one.get("id") or "") if isinstance(one, dict) else ""
+            # ⭐⭐ D-291 — WHICH event was refused, not merely THAT something was. The handler
+            # appends to a shared list, so the refusals belonging to THIS event are exactly the
+            # ones that appeared across THIS call. Reading the list once after the loop would
+            # answer "the batch was refused" and leave the caller to guess which member, which is
+            # the same class of unfalsifiable answer the channel exists to end.
+            _before = len(ctx.out.refusals)
             rerender = grid_events.handle_one(one, ctx)
-            results.append({"id": eid, "rerender": bool(rerender)})
+            row = {"id": eid, "rerender": bool(rerender)}
+            mine = ctx.out.refusals[_before:]
+            if mine:
+                # `refused` is the SHAPE a caller branches on; the first reason is the one that
+                # stopped this write (a handler returns at its first refusal).
+                row["refused"] = mine[0]
+            results.append(row)
     except grid_events.StoreUnavailable:
         raise err(503, "store_unavailable",
                   "the tenant store is unavailable — none of your changes were saved")
 
     out = {"results": results, "rerender": any(r["rerender"] for r in results)}
+    if ctx.out.refusals:
+        # ⚠ ALSO AT THE TOP LEVEL, because a batch that was wholly refused must not read as a
+        # batch that wholly landed. A caller that only checks the envelope still learns something
+        # is wrong, and a caller that walks `results` learns exactly which member.
+        out["refusals"] = list(ctx.out.refusals)
     if ctx.out.doc is not None:
         # ⭐ C4 / W30-T27 — `docPayload` IS THE NAME THE CLIENT ALREADY DECLARES. `types.ts` has
         # carried `docPayload?: {pid, docId, name, mime, data_b64}` since C5, and `Documents.tsx`

platform/aios_grid_fields.json

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

platform/core/shared_overlay.py

@@ -230,6 +230,44 @@ def put_cells(table_key, pid, values, st=None):
     return clean
 
 
+def put_rows(table_key, rows, st=None):
+    """Write shared cells on MANY rows in ONE store update. Returns `{row_id: {key: value}}`.
+
+    ⭐⭐ THE WHOLE POINT IS THE *ONE*, AND IT IS NOT AN OPTIMISATION. `put_cells` is one row per
+    store write, so a 1,397-row catalog import is 1,397 download-modify-upload cycles against one
+    JSON document. This repo has a MEASURED scar for that shape: **18 writes against one document
+    under the store's coalescing single-flight landed ZERO while answering 200 eighteen times.**
+    Batching is what makes a bulk import land at all, not what makes it fast.
+
+    ⚠ It deliberately takes the WHOLE SET rather than accepting a stream: a caller that loops over
+    this function has simply rebuilt `put_cells` with extra steps, and the failure it reintroduces
+    is silent. If the set does not fit in memory it does not fit in this store either — that is a
+    signal to change substrate, not to chunk.
+
+    ⛔ NO CAP HERE, ON PURPOSE. The bound belongs at the DOOR, where a caller identity and a
+    reportable refusal exist (`routes_grid.bulk_cells`). A silent ceiling in a store primitive is
+    exactly the shape the standing no-cap rule forbids.
+    """
+    clean = {}
+    for pid, values in dict(rows or {}).items():
+        row_id = _pid(pid)
+        cells_for_row = {str(k): _value(v) for k, v in dict(values or {}).items() if str(k)}
+        if cells_for_row:
+            clean.setdefault(row_id, {}).update(cells_for_row)
+    if not clean:
+        return {}
+
+    def _patch(data):
+        for row_id, values in clean.items():
+            data['cells'].setdefault(row_id, {}).update(values)
+
+    # `flush='sync'` because a bulk import must be durable when the call returns: the caller is a
+    # script that will report "1,397 rows written" and exit, and an async flush would make that
+    # sentence a prediction rather than a fact.
+    _write(table_key, _patch, st, flush='sync')
+    return clean
+
+
 def clear_row(table_key, pid, st=None):
     """Forget every shared cell on one row. True when there was something to forget."""
     row_id = _pid(pid)