File size: 33,621 Bytes
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
 
 
 
9e15897
b2aa446
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
9e15897
 
 
 
 
 
 
b2aa446
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
9e15897
 
 
 
 
 
 
 
 
b2aa446
9e15897
 
b2aa446
 
 
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
9e15897
 
 
 
b2aa446
 
 
 
 
 
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
 
 
 
 
 
 
9e15897
 
 
 
 
b2aa446
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b2aa446
 
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
"""Compose weekly snapshots and retain delivery claims under the store's 128 MB document ceiling.

No rows are capped. Partition receipts by year before this document reaches the ceiling.
API callers inject App grants, destinations and tenant iteration. No API module is imported here.
"""
import copy
import datetime as dt
import hashlib
import json
import unicodedata
import uuid
from decimal import Decimal, InvalidOperation
from urllib.parse import quote, urlsplit
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

from modules import amazon_operator as op

KEY = "amazon_operator_weekly"
KIND = "amazon_operator_weekly"
PAGE_SIZE = 256
DEFAULTS = {"weekly_weekday": 0, "weekly_time": "08:00"}
OPEN = ("proposed",)
AMAZON_KINDS = {op.SOURCE_KIND, "amazon_sku_profit", "competitor_watch", *op.APP_LABELS}
FIGURES = ("sales", "net_profit", "ad_spend", "stock_risks", "open_items")
METRIC_BASIS = "Latest saved SKU profit snapshot. These are not ISO-week transaction totals."
ALL_SKUS = "All saved Amazon SKUs"
ITEM_SKUS = "SKUs in this App owner's open inbox items"
#: C5 source of each App message: its App record, the grant every recipient was checked against.
SOURCE_TABLE = "applications"


def iso_week(value):
    """Require a valid ISO week, including its ISO year."""
    try:
        year, week = str(value).split("-W")
        day = dt.date.fromisocalendar(int(year), int(week), 1)
    except (TypeError, ValueError) as exc:
        raise ValueError("Choose a valid ISO week, such as 2026-W44.") from exc
    return f"{day.isocalendar().year:04d}-W{day.isocalendar().week:02d}"


def settings(tenant_key, *, st=None):
    """Read the weekly weekday and local send time without writing defaults."""
    doc = op._doc(op._rt(tenant_key, st), op.KEY_SETTINGS)
    return clean_settings({key: doc.get(key, value) for key, value in DEFAULTS.items()})


def clean_settings(values):
    """Check only the supplied weekly settings."""
    out = {}
    if "weekly_weekday" in values:
        day = values["weekly_weekday"]
        if type(day) is not int or not 0 <= day <= 6:
            raise ValueError("Choose a weekday from 0 (Monday) to 6 (Sunday).")
        out["weekly_weekday"] = day
    if "weekly_time" in values:
        value = values["weekly_time"]
        try:
            parsed = dt.time.fromisoformat(value)
            if parsed.tzinfo or parsed.strftime("%H:%M") != value:
                raise ValueError
        except (TypeError, ValueError) as exc:
            raise ValueError("Choose a local send time in HH:MM format.") from exc
        out["weekly_time"] = value
    return out


def set_settings(tenant_key, *, st=None, **values):
    """Save weekly settings in the existing Operator settings document."""
    st = op._rt(tenant_key, st)
    clean = clean_settings(values)
    st.update(op.KEY_SETTINGS, lambda doc: {**(doc or {}), **clean})
    return settings(tenant_key, st=st)


def local_time(now, timezone):
    """Use the tenant's IANA time zone and refuse an unknown zone."""
    try:
        zone = ZoneInfo(timezone)
    except (TypeError, ValueError, ZoneInfoNotFoundError) as exc:
        raise ValueError("The tenant time zone must be configured before weekly delivery.") from exc
    if now.tzinfo is None:
        raise ValueError("Weekly delivery needs a clock with a time zone.")
    return now.astimezone(zone)


def resolve_owner(st, owner):
    """Resolve an active tenant account by username or one unambiguous display name."""
    wanted = str(owner or "").strip().casefold()
    if not wanted:
        return None

    def active(user):
        return (isinstance(user, dict) and user.get("active", True)
                and str(user.get("tenant") or getattr(st, "key", "")).casefold()
                == str(getattr(st, "key", "")).casefold())

    try:
        user = op.account_get(wanted, st=st)
        if user is not None:
            return wanted if active(user) else None
        matches = [str(name) for name, user in op.account_registry(st=st).items()
                   if active(user) and wanted in (str(name).casefold(), str(user.get("name") or "").casefold())]
    except Exception as exc:
        raise RuntimeError("Weekly owner accounts are unavailable.") from exc
    return matches[0] if len(matches) == 1 else None


def _inbox_rows(tenant_key, st):
    """Page the saved inbox through SQL without loading its production document."""
    if op._screen_backend(st, tenant_key) is None:
        doc = st.get(op.KEY_INBOX, fresh=True) or {}
        yield from (value for _key, value in sorted((doc.get("items") or {}).items()) if isinstance(value, dict))
        return
    with op._screen_store(tenant_key, st, documents=(op.KEY_INBOX,)) as (execute, pg, _names):
        p, each = ("%s", "jsonb_each") if pg else ("?", "json_each")
        source = f"SELECT value FROM {{tbl}} WHERE key = {p}" if pg else f"SELECT value FROM docs WHERE name = {p}"
        base = (f"WITH document AS ({source}) SELECT i.key, i.value FROM document d, "
                f"LATERAL {each}(COALESCE(d.value -> 'items', '{{}}')) i ORDER BY i.key")
        offset = 0
        while True:
            rows = execute(base + f" LIMIT {p} OFFSET {p}", [PAGE_SIZE, offset]).fetchall()
            for _key, value in rows:
                yield json.loads(value) if isinstance(value, str) else value
            if len(rows) < PAGE_SIZE:
                break
            offset += PAGE_SIZE


def _profit_rows(tenant_key, st):
    """Stream saved SKU profit records, with bounded SQL pages on legacy stores."""
    backend = op._screen_backend(st, tenant_key)
    if backend is None:
        table = ((st.get("user_tables", fresh=True) or {}).get(op.PROFIT_TABLE) or {})
        yield from (table.get("rows") or {}).values()
        return
    from core import store_pg, user_table_rows
    name = getattr(st, "store_key", lambda key: key)("user_tables")
    if user_table_rows.rows_mode(name, backend.tenant_slug):
        for batch in user_table_rows.iter_records(name, backend.tenant_slug, op.PROFIT_TABLE, batch_size=PAGE_SIZE):
            for _rid, value in batch:
                yield value
        return
    sql = ("SELECT r.value FROM {tbl} d, LATERAL jsonb_each(COALESCE(d.value -> %s -> 'rows', '{{}}')) r "
           "WHERE d.key = %s ORDER BY r.key LIMIT %s OFFSET %s")
    offset = 0
    with store_pg._pool().connection() as con:
        while True:
            rows = con.execute(store_pg._q(sql, "store_kv", backend.tenant_slug),
                               [op.PROFIT_TABLE, name, PAGE_SIZE, offset]).fetchall()
            for (value,) in rows:
                yield json.loads(value) if isinstance(value, str) else value
            if len(rows) < PAGE_SIZE:
                break
            offset += PAGE_SIZE


def _stock_risks(tenant_key, st):
    """Read latest inventory cover for every SKU without a row cap."""
    out, offset = {}, 0
    threshold = op.settings(tenant_key, st=st)["stop_cover_days"]
    with op._reader(tenant_key, st) as cur:
        if cur is None or not {"sku", "_snapshot_date", "days_of_supply"} <= op._columns(cur, op.PLANNING_TABLE):
            raise ValueError("Inventory planning is unavailable.")
        while True:
            rows = cur.execute("WITH latest AS (SELECT sku, days_of_supply, ROW_NUMBER() OVER "
                               "(PARTITION BY sku ORDER BY _snapshot_date DESC) AS n FROM amzn_inventory_planning) "
                               "SELECT sku, days_of_supply FROM latest WHERE n = 1 ORDER BY sku LIMIT ? OFFSET ?",
                               [PAGE_SIZE, offset]).fetchall()
            for sku, days in rows:
                value = op._num(days)
                if value is None:
                    raise ValueError("Inventory planning contains unknown cover.")
                if value < threshold:
                    out[str(sku)] = value
            if len(rows) < PAGE_SIZE:
                break
            offset += PAGE_SIZE
    return out


def _metrics(rows):
    result = {"periods": sorted({op._plain(r.get("period")) for r in rows if r.get("period")}),
              "metric_basis": METRIC_BASIS}
    for output, field in (("sales", "net_sales"), ("net_profit", "net_profit"), ("ad_spend", "sponsored_ads")):
        numbers = [op._num(r.get(field)) for r in rows]
        result[output] = round(sum(numbers), 2) if numbers and all(n is not None for n in numbers) else None
    if any(result[key] is None for key in ("sales", "net_profit", "ad_spend")):
        result["metrics_reason"] = "Saved SKU profit figures are missing or incomplete."
    return result


def _owned_rows(st, owner, app, inbox, default):
    """Use an item's assigned account, with the App default only when that assignment is absent."""
    rows = [r for r in inbox if r.get("source_kind") == app.get("templateKind")]
    assignments = {r.get("owner") or app.get("defaultOwner") or default for r in rows}
    accounts = {value: resolve_owner(st, value) for value in assignments}
    return [r for r in rows if accounts[r.get("owner") or app.get("defaultOwner") or default] == owner]


def _recipient_scope(st, owner, apps, may_read, inbox, default):
    """Count omitted open rows once for their resolved recipient without naming their sources."""
    candidates = [app for app in apps if not app.get("retired") and app.get("templateKind") in AMAZON_KINDS]
    permitted = [app for app in candidates if may_read(app, owner)]
    owned = {id(row) for app in candidates for row in _owned_rows(st, owner, app, inbox, default)
             if row.get("status") in OPEN}
    visible = {id(row) for app in permitted for row in _owned_rows(st, owner, app, inbox, default)
               if row.get("status") in OPEN}
    kinds = {app.get("templateKind") for app in candidates}
    owned.update(id(row) for row in inbox if row.get("status") in OPEN and row.get("source_kind") not in kinds
                 and resolve_owner(st, row.get("owner") or default) == owner)
    count = len(owned - visible)
    operator = next((app for app in permitted if app.get("templateKind") == op.SOURCE_KIND), None)
    source = {"table": SOURCE_TABLE, "rowIds": [str(operator["id"])]} if count and operator else None
    return permitted, {**op.withheld(count), "withheldSource": source}


def compose(tenant_key, owner, week, *, st=None, apps=None, may_read=None, source_state=None, now=None, base_url="",
            _validate=True):
    """Compose permitted App snapshots from saved profit rows, inventory and the Operator inbox."""
    st, week = op._rt(tenant_key, st), iso_week(week)
    if apps is None or not callable(may_read):
        raise RuntimeError("Weekly App records and grants are unavailable.")
    owner = resolve_owner(st, owner)
    if owner is None:
        raise ValueError("The summary owner is not one active tenant account.")
    try:
        inbox, inbox_error = list(_inbox_rows(tenant_key, st)), None
    except Exception:
        inbox, inbox_error = [], "The Operator inbox could not be read."
    try:
        profit, profit_error = list(_profit_rows(tenant_key, st)), None
    except Exception:
        profit, profit_error = [], "Saved SKU profit could not be read."
    try:
        risks, risk_error = _stock_risks(tenant_key, st), None
    except Exception:
        risks, risk_error = {}, "Inventory planning could not be read."
    result = {"tenant": tenant_key, "owner": owner, "week": week,
              "as_of": op._stamp(now or op._now()), "apps": []}
    default = op.settings(tenant_key, st=st)["defaultOwner"]
    permitted, withheld = _recipient_scope(st, owner, apps, may_read, inbox, default)
    result.update(withheld)
    for app in permitted:
        kind = app.get("templateKind")
        rows = _owned_rows(st, owner, app, inbox, default)
        skus = {str(r["sku"]) for r in rows if r.get("sku") and r.get("status") in OPEN}
        all_skus = kind in (op.SOURCE_KIND, "amazon_sku_profit")
        selected = [r for r in profit if isinstance(r, dict) and (all_skus or str(r.get("sku")) in skus)]
        entry = {"id": app["id"], "kind": kind, "name": op._plain(app.get("name") or kind),
                 "link": base_url.rstrip("/") + "/#/app/template/" + quote(str(app["id"]), safe=""),
                 "state": "ready", "open_items": sum(r.get("status") in OPEN for r in rows),
                 "stock_risks": sum(all_skus or sku in skus for sku in risks), **_metrics(selected),
                 "sku_scope": ALL_SKUS if all_skus else ITEM_SKUS}
        if risk_error:
            entry.update(stock_risks=None, stock_reason=risk_error)
        if profit_error:
            entry["metrics_reason"] = profit_error
        source = "modules." + str(kind)
        if kind in op.APP_LABELS and (source_state is None or source not in source_state.get("read", ())):
            entry.update(state="unavailable", open_items=None, reason="This App's proposals could not be read on the send day.")
        elif kind not in op.APP_LABELS:
            entry.update(open_items=None, inbox_reason="This App has no proposal source in the Operator inbox.")
        if inbox_error:
            entry.update(open_items=None, inbox_reason=inbox_error)
            if not all_skus:
                entry.update(sales=None, net_profit=None, ad_spend=None, stock_risks=None,
                             metrics_reason=inbox_error, stock_reason=inbox_error)
        result["apps"].append(entry)
    return (_validated(tenant_key, result, st=st, apps=apps, may_read=may_read, source_state=source_state)
            if _validate else result)


def _decimal(value):
    try:
        number = Decimal(str(value))
        return number if number.is_finite() else None
    except (InvalidOperation, ValueError):
        return None


def _validation_cover(tenant_key, st):
    """Read newest cover independently of the producer's risk filter and count."""
    cover, offset = {}, 0
    with op._reader(tenant_key, st) as cur:
        if cur is None or not {"sku", "_snapshot_date", "days_of_supply"} <= op._columns(cur, op.PLANNING_TABLE):
            raise ValueError("Inventory planning is unavailable.")
        while True:
            rows = cur.execute(
                "WITH dates AS (SELECT sku, MAX(_snapshot_date) AS latest FROM amzn_inventory_planning GROUP BY sku) "
                "SELECT p.sku, p.days_of_supply FROM amzn_inventory_planning p JOIN dates d "
                "ON p.sku = d.sku AND p._snapshot_date = d.latest ORDER BY p.sku LIMIT ? OFFSET ?",
                [PAGE_SIZE, offset]).fetchall()
            for sku, days in rows:
                value = _decimal(days)
                key = str(sku)
                cover[key] = value if key not in cover or cover[key] == value else None
            if len(rows) < PAGE_SIZE:
                break
            offset += PAGE_SIZE
    if not cover:
        raise ValueError("Inventory planning has no saved snapshot.")
    return cover


def _figure(actual, expected, reason=None, missing_reason=None):
    if reason:
        return {"value": None, "valid": None, "state": "unknown", "reason": reason}
    if actual is None:
        return {"value": None, "valid": None, "state": "unknown",
                "reason": missing_reason or "The produced figure is unavailable."}
    if isinstance(actual, bool) or _decimal(actual) != _decimal(expected):
        return {"value": None, "valid": False, "state": "invalid",
                "reason": "The produced figure does not reconcile with the fresh source read."}
    return {"value": expected, "valid": True, "state": "valid", "reason": None}


def validate(tenant_key, summary, *, st=None, apps=None, may_read=None, source_state=None):
    """Reconcile each permitted figure against fresh saved rows and mirror reads without producer calculations."""
    st = op._rt(tenant_key, st)
    if apps is None or not callable(may_read):
        raise RuntimeError("Weekly App records and grants are unavailable.")
    owner = resolve_owner(st, summary.get("owner"))
    if owner is None:
        raise ValueError("The summary owner is not one active tenant account.")
    week = iso_week(summary.get("week"))
    produced = summary.get("apps") or []
    by_id = {row.get("id"): row for row in produced}
    try:
        inbox, inbox_error = list(_inbox_rows(tenant_key, st)), None
    except Exception:
        inbox, inbox_error = [], "The Operator inbox could not be independently read."
    try:
        profit, profit_error = list(_profit_rows(tenant_key, st)), None
    except Exception:
        profit, profit_error = [], "Saved SKU profit could not be independently read."
    try:
        cover, cover_error = _validation_cover(tenant_key, st), None
    except Exception:
        cover, cover_error = {}, "Inventory planning could not be independently read."
    default = op.settings(tenant_key, st=st)["defaultOwner"]
    permitted, withheld = _recipient_scope(st, owner, apps, may_read, inbox, default)
    withheld_valid = (not inbox_error and type(summary.get("withheldCount")) is int
                      and all(summary.get(key) == value for key, value in withheld.items()))
    context_ok = (summary.get("tenant") == tenant_key and len(produced) == len(by_id) == len(permitted)
                  and set(by_id) == {app["id"] for app in permitted})
    threshold = _decimal(op.settings(tenant_key, st=st)["stop_cover_days"])
    result = {"ok": context_ok, "owner": owner, "week": week, "apps": [],
              **withheld, "withheldValid": withheld_valid}
    for app in permitted:
        kind, row = app.get("templateKind"), by_id.get(app["id"], {})
        owned = _owned_rows(st, owner, app, inbox, default)
        opened = [item for item in owned if item.get("status") == "proposed"]
        skus = {str(item["sku"]) for item in opened if item.get("sku")}
        all_skus = kind in (op.SOURCE_KIND, "amazon_sku_profit")
        scope = ALL_SKUS if all_skus else ITEM_SKUS
        selected = [item for item in profit if isinstance(item, dict) and (all_skus or str(item.get("sku")) in skus)]
        periods = sorted({op._plain(item.get("period")) for item in selected if item.get("period")})
        scope_error = inbox_error if not all_skus else None
        financial_error = profit_error or scope_error
        if not financial_error and (not selected or any(not item.get("period") for item in selected)):
            financial_error = "Saved SKU profit rows or their snapshot periods are missing."
        metadata_ok = row.get("sku_scope") == scope and row.get("kind") == kind
        financial_metadata_ok = row.get("periods") == periods and row.get("metric_basis") == METRIC_BASIS
        figures = {}
        for name, field in (("sales", "net_sales"), ("net_profit", "net_profit"), ("ad_spend", "sponsored_ads")):
            values = [_decimal(item.get(field)) for item in selected]
            reason = financial_error or ("Saved SKU profit figures are missing or incomplete."
                                          if any(value is None for value in values) else None)
            expected = float(sum(values, Decimal(0)).quantize(Decimal("0.01"))) if not reason else None
            figures[name] = _figure(row.get(name), expected, reason, row.get("metrics_reason"))
        relevant_cover = [value for sku, value in cover.items() if all_skus or sku in skus]
        stock_error = cover_error or scope_error or ("Inventory planning contains unknown cover."
                                                    if any(value is None for value in relevant_cover) else None)
        risk_count = len([value for value in relevant_cover if value is not None and value < threshold])
        figures["stock_risks"] = _figure(row.get("stock_risks"), risk_count, stock_error, row.get("stock_reason"))
        inbox_reason = inbox_error
        if kind not in op.APP_LABELS:
            inbox_reason = "This App has no proposal source in the Operator inbox."
        elif source_state is None or "modules." + str(kind) not in source_state.get("read", ()):
            inbox_reason = "This App's proposals could not be read on the send day."
        figures["open_items"] = _figure(row.get("open_items"), len(opened), inbox_reason, row.get("inbox_reason"))
        for name in FIGURES:
            mismatch = not context_ok or not metadata_ok or (name in ("sales", "net_profit", "ad_spend")
                                                             and not financial_metadata_ok)
            if mismatch and figures[name]["state"] != "unknown":
                figures[name] = {"value": None, "valid": False, "state": "invalid",
                                 "reason": "The App, owner, saved periods or SKU scope do not match the fresh source context."}
        result["apps"].append({"id": app["id"], "kind": kind, "periods": periods, "sku_scope": scope, "figures": figures})
    result["ok"] = context_ok and withheld_valid and all(
        figure["valid"] is True for app in result["apps"] for figure in app["figures"].values())
    return result


def _validated(tenant_key, summary, **kwargs):
    """Expose per-figure validity and withhold every unverified value before display or delivery."""
    summary = copy.deepcopy(summary)
    check = validate(tenant_key, summary, **kwargs)
    summary.update({field: check[field] for field in ("withheldCount", "withheldMessage", "withheldSource")})
    checks = {app["id"]: app for app in check["apps"]}
    summary["apps"] = [app for app in summary["apps"] if app["id"] in checks]
    for app in summary["apps"]:
        checked = checks[app["id"]]
        app.update(periods=checked["periods"], sku_scope=checked["sku_scope"], metric_basis=METRIC_BASIS,
                   validation=checked["figures"])
        for name, figure in checked["figures"].items():
            app[name] = figure["value"]
        for names, field in ((("sales", "net_profit", "ad_spend"), "metrics_reason"),
                             (("stock_risks",), "stock_reason"), (("open_items",), "inbox_reason")):
            reasons = sorted({checked["figures"][name]["reason"] for name in names if checked["figures"][name]["reason"]})
            if reasons:
                app[field] = " ".join(reasons)
    summary["validation"] = check
    return summary


def owners(tenant_key, *, st, apps):
    """Find active item owners and App defaults without importing another App."""
    default = op.settings(tenant_key, st=st)["defaultOwner"]
    values = [app.get("defaultOwner") or default for app in apps
              if not app.get("retired") and app.get("templateKind") in AMAZON_KINDS]
    kinds = {app.get("templateKind") for app in apps if not app.get("retired")
             and app.get("templateKind") in AMAZON_KINDS}
    values.extend(row.get("owner") for row in _inbox_rows(tenant_key, st)
                  if row.get("source_kind") in kinds and row.get("status") == "proposed")
    return sorted({resolved for value in values if (resolved := resolve_owner(st, value))})


def _week_key(tenant_key, owner, week):
    return json.dumps([str(tenant_key), owner, iso_week(week)], separators=(",", ":"))


def _claim(st, key, summary, now):
    token, claimed, prior = uuid.uuid4().hex, [], {}

    def apply(doc):
        claimed.clear()
        prior.clear()
        doc = doc if isinstance(doc, dict) else {}
        records = doc.setdefault("sends", {})
        if key not in records:
            records[key] = {"token": token, "state": "unknown", "claimed_at": op._stamp(now),
                            "reason": "Delivery is reserved. Its outcome is not yet known.", "summary": summary,
                            **op.withheld(summary["withheldCount"])}
            claimed.append(token)
        else:
            prior.update({field: records[key].get(field) for field in ("state", "reason")})
        return doc
    st.update(KEY, apply, flush="sync")
    return (token if claimed else None), prior


def _notification_items(summary, key):
    """Split each complete App message into lossless C5 items, each naming the App record it summarises."""
    title = f"Amazon summary for {summary['week']}"
    items = []
    apps = summary["apps"]
    if summary.get("withheldCount") and all(app["kind"] == op.SOURCE_KIND for app in apps):
        apps = []
    for index, app in enumerate(apps):
        values = {name: "Unknown" if app[name] is None else str(app[name]) for name in FIGURES}
        lines = [title, f"{app['name']}: " + (app["reason"] if app["state"] == "unavailable" else
                 f"{values['open_items']} open items. Sales {values['sales']}. Net profit {values['net_profit']}. "
                 f"Ad spend {values['ad_spend']}. Stock risks {values['stock_risks']}.")]
        lines.extend(str(app.get(field) or "") for field in
                     ("metric_basis", "metrics_reason", "stock_reason", "inbox_reason"))
        lines.extend(["Saved periods: " + (", ".join(app["periods"]) or "Unknown"), app["link"]])
        body = "\n".join("".join(" " if unicodedata.category(c) == "Cc" else c for c in op._plain(line))
                         for line in lines if line)
        identity = hashlib.sha256(json.dumps([key, index, app["id"]]).encode()).hexdigest()
        part = 0
        while body:
            end = min(len(body), 8000)
            if end < len(body):
                boundary = max(body.rfind("\n", 0, end), body.rfind(" ", 0, end))
                if boundary > 0:
                    end = boundary + 1
            chunk, body = body[:end], body[end:]
            item = {"id": f"{identity}:{part}", "title": title, "body": chunk,
                    "source": {"table": SOURCE_TABLE, "rowIds": [str(app["id"])]}}
            if len(app["link"]) <= 2000:
                item["url"] = app["link"]
            items.append(item)
            part += 1
    if summary.get("withheldCount"):
        source = summary.get("withheldSource")
        if not source:
            raise ValueError("The summary needs a readable Operator App for its access count.")
        identity = hashlib.sha256(json.dumps([key, "withheld", source]).encode()).hexdigest()
        items.append({"id": identity + ":0", "title": title, "body": summary["withheldMessage"],
                      "source": copy.deepcopy(source)})
    return items


def _outcome(result, *, owner, item_count):
    """Reconcile recipient-bound C5 destination receipts before claiming any successful delivery."""
    unknown = ("unknown", "The destination transport returned an invalid or uncertain delivery receipt.")
    if (not isinstance(result, dict) or result.get("kind") != KIND
            or type(result.get("itemCount")) is not int or result["itemCount"] != item_count
            or not isinstance(result.get("results"), list)
            or any(type(result.get(name)) is not int or result[name] < 0 for name in ("sent", "refused"))):
        return unknown
    rows, seen = result["results"], set()
    for row in rows:
        if (not isinstance(row, dict) or row.get("user") != owner
                or row.get("state") not in ("sent", "refused")
                or type(row.get("recorded")) is not bool
                or "reason" not in row or not isinstance(row.get("message"), str)):
            return unknown
        destination = row.get("destination")
        if (not isinstance(destination, str) or not destination.startswith(("slack:", "email:"))
                or not destination.partition(":")[2].strip()
                or any(unicodedata.category(c) == "Cc" for c in destination) or destination in seen):
            return unknown
        if row["state"] == "refused" and (not isinstance(row["reason"], str) or not row["reason"].strip()):
            return unknown
        if row["state"] == "sent" and row["reason"] is not None:
            return unknown
        seen.add(destination)
    sent = sum(row["state"] == "sent" for row in rows)
    if result["sent"] != sent or result["refused"] != len(rows) - sent:
        return unknown
    if not rows:
        return "failed", "No notification destinations were selected for this owner."
    if any(not row["recorded"] for row in rows):
        return "unknown", "A destination outcome was not recorded. This week will not retry."
    refused = [row for row in rows if row["state"] == "refused"]
    reason = " ".join(op._plain(f"{row['destination']}: {row['reason']}. {row['message']}") for row in refused) or None
    if sent == len(rows):
        return "sent", None
    if sent:
        return "partial", reason
    uncertain = {"transport_error", "email_delivery_unconfirmed", "dispatcher_contract_mismatch"}
    return ("unknown" if any(row["reason"] in uncertain for row in refused) else "failed"), reason


def send(tenant_key, owner, week, *, st, apps, may_read, deliver=None, source_state=None, now=None, base_url=""):
    """Claim the owner and ISO week atomically before calling the injected destination transport."""
    if not callable(deliver):
        return {"state": "unavailable", "reason": "notify_destinations.deliver is not installed."}
    address = urlsplit(base_url)
    if (address.scheme not in ("https", "http") or not address.hostname or address.username or address.password
            or address.fragment or address.query
            or any(unicodedata.category(c) == "Cc" for c in base_url)):
        return {"state": "unavailable", "reason": "APP_BASE_URL must name this deployment before weekly delivery."}
    now = now or op._now()
    summary = compose(tenant_key, owner, week, st=st, apps=apps, may_read=may_read, source_state=source_state,
                      now=now, base_url=base_url, _validate=False)
    summary = _validated(tenant_key, summary, st=st, apps=apps, may_read=may_read, source_state=source_state)
    withheld = op.withheld(summary["withheldCount"])
    if not summary["validation"]["withheldValid"]:
        return {"state": "unavailable", "reason": "The access count could not be checked against the saved Operator inbox.",
                "summary": summary, **withheld}
    if summary["withheldCount"] and not summary.get("withheldSource"):
        return {"state": "unavailable", "reason": "The summary needs a readable Operator App for its access count.",
                "summary": summary, **withheld}
    if not summary["apps"] and not summary["withheldCount"]:
        return {"state": "empty", "reason": "The owner has no readable Amazon Apps."}
    key = _week_key(tenant_key, summary["owner"], summary["week"])
    token, prior = _claim(st, key, summary, now)
    if token is None:
        return {"state": "skipped", "key": key, "prior_state": prior.get("state"), "prior_reason": prior.get("reason"),
                "reason": "This owner and ISO week already have a delivery claim.", **withheld}
    try:
        items = _notification_items(summary, key)
        receipt = deliver(st, KIND, items, user=summary["owner"])
        state, reason = _outcome(receipt, owner=summary["owner"], item_count=len(items))
    except Exception:
        receipt = None
        state, reason = "unknown", "The destination transport failed. Delivery may have occurred. This week will not retry."

    def finish(doc):
        record = doc["sends"][key]
        if record["token"] == token:
            record.update(state=state, reason=reason, delivery=op._json_safe(receipt), finished_at=op._stamp(now))
        return doc
    try:
        st.update(KEY, finish, flush="sync")
    except Exception:
        return {"state": "unknown", "key": key, "summary": summary,
                "reason": "The delivery receipt could not be recorded. The weekly claim remains reserved.", **withheld}
    return {"state": state, "reason": reason, "key": key, "summary": summary,
            "delivery": op._json_safe(receipt), **withheld}


def send_tenant(tenant_key, st, *, apps, may_read, timezone, deliver=None, now=None, force=False, owner=None, base_url=""):
    """Send due summaries once per owner, sharing the claim with admin send-now."""
    now = now or op._now()
    if not any(a.get("templateKind") == op.SOURCE_KIND and not a.get("retired") for a in apps):
        return {"state": "empty", "rows": []}
    local = local_time(now, timezone)
    conf = settings(tenant_key, st=st)
    due = (local.weekday(), local.strftime("%H:%M")) >= (conf["weekly_weekday"], conf["weekly_time"])
    if not force and not due:
        return {"state": "not_due", "rows": []}
    if not callable(deliver):
        return {"state": "unavailable", "reason": "notify_destinations.deliver is not installed.", "rows": []}
    refresh = op.pull_app_proposals(tenant_key, st=st, now=now)
    recipients = [owner] if owner is not None else owners(tenant_key, st=st, apps=apps)
    week = f"{local.isocalendar().year:04d}-W{local.isocalendar().week:02d}"
    rows = []
    for recipient in recipients:
        try:
            rows.append(send(tenant_key, recipient, week, st=st, apps=apps, may_read=may_read,
                             deliver=deliver, source_state=refresh, now=now, base_url=base_url))
        except Exception:
            rows.append({"state": "failed", "reason": "This owner's summary could not be prepared or recorded."})
    return {"state": "processed", "week": week, "rows": rows}


def run_once(*, for_each_tenant, context, deliver, logger, now=None):
    """Delegate independent tenant jobs to the injected C10 dispatcher."""
    return for_each_tenant(lambda tenant, st: send_tenant(tenant, st, deliver=deliver, now=now, **context(st)),
                           name="amazon-operator-weekly", logger=logger, kind="heavy")