File size: 20,675 Bytes
ea2c336
 
 
 
 
 
81a8217
 
ea2c336
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8145bee
81a8217
ea2c336
 
9e15897
ea2c336
 
 
 
9e15897
ea2c336
 
9e15897
 
8145bee
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ea2c336
 
 
 
1ad1eea
 
ea2c336
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ef68ae0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ea2c336
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
81a8217
 
 
ea2c336
81a8217
 
 
 
 
ea2c336
81a8217
 
 
 
ea2c336
 
 
81a8217
 
ea2c336
9e15897
b2aa446
9e15897
 
ea2c336
 
81a8217
ea2c336
 
 
 
 
 
 
 
 
 
 
b2aa446
ea2c336
 
aa1490a
1ad1eea
c3e4cb4
 
 
 
 
 
 
 
 
 
 
 
f546440
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1ad1eea
 
 
c3e4cb4
aa1490a
 
1ad1eea
aa1490a
 
 
b2aa446
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
aa1490a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1ad1eea
 
aa1490a
 
8145bee
1ad1eea
 
c3e4cb4
9e15897
b2aa446
9e15897
 
c3e4cb4
aa1490a
1ad1eea
aa1490a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c3e4cb4
 
b2aa446
1ad1eea
c3e4cb4
 
9e15897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ea2c336
 
 
9e15897
ea2c336
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
"""core/alerts.py β€” "tell me when a record ENTERS this view" (wave 20, owner item 25).

THE OWNER'S SHAPE, verbatim: *"a user click a view and click 'Create alert'. This way when a
Record gets into that Filter's criteria, a user gets notified in that module … Read/Unread like an
inbox type of thing so they can confirm whether they have seen the Record that got filtered in."*

An alert remembers a View's matched set and delivers one counted notification per run.
An entrant is a pid that matches now and did not last time. That definition is what
makes the module trustworthy rather than noisy:

  * a record already in the view when the alert is created is NOT news. The first evaluation
    SEEDS the set silently (`seed=True`); without that, creating an alert on a 400-row view
    would announce 400 "new" records, and the user would turn the feature off in one click;
  * a record that leaves and comes back IS news again β€” it re-entered the criteria, which is the
    event the owner described;
  * a record that merely CHANGES while staying in the view is not an entrant. "Still matching" is
    not an event. (An on-change alert is a different feature with a different noise budget; it is
    NOT smuggled in here under the same name.)

⚠ **WHY THE MATCHED SET IS STORED AND NOT RECOMPUTED FROM HISTORY.** There is no row-level audit
log to diff against β€” `store` holds current state, and Odoo is read-only. The remembered set IS
the history, so it is written on every evaluation, in the same transaction that queues the
notifications. Losing that write while keeping the notifications would re-announce the same
records forever.

⚠ **WHAT AN UNANSWERABLE LEAF ACTUALLY DOES HERE β€” CHECKED, NOT ASSUMED.** `harness.filter_eval`'s
`EvalCtx` is explicit that each of its four members "absent, the condition matches NOTHING rather
than everything" β€” the engine NARROWS on an unresolved measure/cohort/rank set rather than
widening. So the failure mode is not a false alert; it is a **missed** one, and a missed entrant
is re-detected on the next evaluation because `matched` only ever records what genuinely matched.

That is the safe direction, and it is why `partial` is a caller-supplied flag rather than
something inferred in here: the caller (`routes_alerts`) is the only layer that knows whether it
could BUILD a complete context. When it says so, `evaluate()` records the attempt and changes
nothing β€” updating `matched` from a narrowed evaluation would drop rows out of the remembered set
and then re-announce every one of them as an "entrant" on the next complete pass. That is the
real hazard: not a phantom alert, but a storm of stale ones.

⚠ **EVERY STAMP CARRIES A UTC OFFSET** (DEBT D-18). A browser can only render a timestamp
relatively if it can subtract it from `now`, and a naive container-local stamp is unsubtractable β€”
it renders VERBATIM or, worse, silently as the reader's own zone. `_now_iso()` is the one place
that is decided.
"""
import datetime as _dt
import logging as _logging
from urllib.parse import urlencode

import core.store as store
from core import account_rows

#: Alert DEFINITIONS, per tenant: {alert_id: {...}}. Separate from the notifications bucket so a
#: busy inbox never rewrites the definitions (and a definition edit never rewrites the inbox).
ALERTS_KEY = 'alerts'
#: Legacy inbox document, replaced by recipient-scoped notification rows on PostgreSQL.
NOTIFICATIONS_KEY = 'alert_notifications'

#: Keep 200 per recipient when possible, dropping only the oldest read notifications.
MAX_NOTIFICATIONS = account_rows.NOTIFICATION_TARGET
_SINK = None
_LOG = _logging.getLogger(__name__)


def set_sink(fn):
    """Register the optional notification sink without importing an application layer."""
    if fn is not None and not callable(fn):
        raise ValueError('A notification sink must be callable.')
    global _SINK
    _SINK = fn


def _publish(owner, item, st):
    if _SINK is not None:
        try:
            _SINK(_st(st), owner, item)
        except Exception as exc:
            # A failed notice must not roll back its producer or suppress the compatibility row.
            _LOG.warning('Assistant notice was not delivered: %s', type(exc).__name__)


def _now_iso():
    """UTC, WITH the offset β€” `2026-08-05T09:41:07.123456+00:00`. See the module note (D-18)."""
    from core import write_execution
    return write_execution.utcnow().isoformat()


def _st(st):
    return st if st is not None else store


def list_alerts(user=None, st=None, is_admin=False):
    """Alert definitions this user may see: their own. Admins see all (they support them)."""
    try:
        recs = _st(st).get(ALERTS_KEY) or {}
    except Exception:
        return []
    out = []
    for aid, rec in recs.items():
        if not isinstance(rec, dict):
            continue
        if user and not is_admin and str(rec.get('owner') or '') != str(user):
            continue
        out.append({**rec, 'id': str(aid)})
    return sorted(out, key=lambda r: str(r.get('createdAt') or ''))


def create(alert_id, *, view_id, topic, owner, label='', st=None):
    """Register an alert on a view. Returns the record.

    The view is stored BY ID, never by a copy of its filter tree. An alert whose criteria were
    snapshotted at creation would silently stop matching the view the moment its owner edited it β€”
    and the user's mental model is "alert me on THIS VIEW", not "on this view as it was in
    August".
    """
    rec = {'id': str(alert_id), 'viewId': str(view_id), 'topic': str(topic),
           'owner': str(owner), 'label': str(label or '')[:160],
           'createdAt': _now_iso(), 'matched': [], 'seeded': False,
           'lastRunAt': None, 'lastError': None}

    def _apply(data):
        data[str(alert_id)] = rec
        return data

    _st(st).update(ALERTS_KEY, _apply, flush='sync')
    return rec


def drop_topic(topic, st=None):
    """Delete every alert DEFINITION on a topic (wave 21, item 6a / C3 β€” a deleted database's
    alerts die with it; an alert on a view that no longer exists can only ever error).
    Notifications already delivered are left in inboxes: they are history, and history is the
    one thing a delete must not rewrite."""
    t = str(topic or '')
    if not t:
        return

    def _apply(data):
        for aid in [k for k, r in (data or {}).items()
                    if isinstance(r, dict) and str(r.get('topic') or '') == t]:
            data.pop(aid, None)
        return data

    _st(st).update(ALERTS_KEY, _apply, flush='async')


def delete(alert_id, st=None):
    def _apply(data):
        data.pop(str(alert_id), None)
        return data

    _st(st).update(ALERTS_KEY, _apply, flush='sync')
    return True


def evaluate(alert_id, matching_pids, *, labels=None, partial=False, st=None):
    """Fold a fresh evaluation of one alert's view into its state; queue any NEW entrants.

    `matching_pids` is what the view matches NOW β€” the caller owns running the filter, because
    only it knows the topic's rows and the reader's scope. `partial` says the evaluation could not
    answer every leaf; see the module note on why that suppresses everything.

    Returns `{'new': [...], 'seeded': bool}` or `{'skipped': 'partial'|'missing'}`.
    """
    now_set = {str(p) for p in (matching_pids or ())}
    outcome = {}

    def _apply(data):
        rec = data.get(str(alert_id))
        if not isinstance(rec, dict):
            outcome['skipped'] = 'missing'
            return data
        if partial:
            # Record the ATTEMPT (so "last checked" is honest) but change nothing else. Writing
            # `matched` here would bake a widened set in as truth, and the next COMPLETE
            # evaluation would then report every genuinely-absent row as an entrant.
            rec['lastRunAt'] = _now_iso()
            rec['lastError'] = ('the view could not be fully evaluated (a filter leaf was '
                                'unanswerable); no alert was raised')
            outcome['skipped'] = 'partial'
            data[str(alert_id)] = rec
            return data
        prior = {str(p) for p in (rec.get('matched') or ())}
        seeding = not rec.get('seeded')
        entrants = [] if seeding else sorted(now_set - prior, key=lambda s: (len(s), s))
        rec['matched'] = sorted(now_set, key=lambda s: (len(s), s))
        rec['seeded'] = True
        rec['lastRunAt'] = _now_iso()
        rec['lastError'] = None
        data[str(alert_id)] = rec
        outcome['new'] = entrants
        outcome['seeded'] = seeding
        outcome['_rec'] = rec
        return data

    _st(st).update(ALERTS_KEY, _apply, flush='sync')
    if outcome.get('skipped'):
        return {'skipped': outcome['skipped']}
    rec = outcome.pop('_rec', {}) or {}
    if outcome.get('new'):
        _queue(rec, outcome['new'], labels or {}, st=st)
    return outcome


def _queue(rec, pids, labels, st=None):
    """Append one counted delivery per filter run to both internal destinations."""
    if not pids:
        return
    at = _now_iso()
    topic = str(rec.get('topic') or '')
    database = {'customer': 'customer_data', 'product': 'product_data'}.get(topic, topic)
    view = str(rec.get('viewId') or '')
    count = len(pids)
    item = {'id': f"{rec.get('id')}:{at}",
              'alertId': str(rec.get('id')), 'viewId': str(rec.get('viewId')),
              'topic': topic, 'rowId': '', 'kind': 'alert', 'count': count,
              'label': f"{count} {'record' if count == 1 else 'records'} entered this View",
              'target': {'module': 'database', 'id': database, 'tab': view},
              'link': '#/data?' + urlencode({'database': database, 'view': view}),
              'alertLabel': str(rec.get('label') or ''),
              'at': at, 'read': False}
    owner = str(rec.get('owner') or '')
    # The sink's first-post cutover must finish before the new bell row is appended.
    _publish(owner, item, st)

    if account_rows.records_backend(_st(st)):
        _notification_write(st, lambda: _append_notification_rows([(owner, False, item, {})], st=st), 1)
        return

    def _apply(data):
        inbox = list(data.get(owner) or [])
        inbox.append(item)
        if len(inbox) > MAX_NOTIFICATIONS:
            # Drop READ entries oldest-first; keep every unread one. A cap that dropped unread
            # notifications would silently lose exactly the records the user has not confirmed β€”
            # the one thing this module promises not to do.
            unread = [n for n in inbox if not n.get('read')]
            read = [n for n in inbox if n.get('read')]
            keep_read = read[max(0, len(unread) + len(read) - MAX_NOTIFICATIONS):]
            inbox = sorted(unread + keep_read, key=lambda n: str(n.get('at') or ''))
        data[owner] = inbox
        return data

    _notification_write(st, lambda: _st(st).update(NOTIFICATIONS_KEY, _apply, flush='async'), 1)


def notify(owner, label, *, topic='automation', key='', row_id='', detail='', actor='', st=None,
           replace=False, target=None, inbox=None):
    """⭐ WAVE 23 (C6) β€” put ONE notification in a named user's inbox, for a producer that is not
    a view-alert evaluation.

    The automation engine needs the bell to ring when records arrive at a review gate, and that
    is not an alert over a view: there is no filter tree, no `matched` set, no entrant diff. It
    reached for `_queue` directly during the wave, which would have made a private function a
    cross-module contract β€” so this is the public door instead, and `_queue` stays the internal
    half of `evaluate()`.

    The inbox shape is UNCHANGED, deliberately: `AlertsPane` reads one list, and a second row
    shape would mean a client that must branch on where a notification came from. `alertId`
    carries the producer's key so a click-through can route (W23-W5).

    ⭐⭐ W33-T28 (`ASK C-14`) β€” `actor` IS THE ONLY THING THAT KNOWS WHO. Owner item: *"the Inbox
    reads like email"*, and a verifier reading the carried wave-32 surface found the SENDER position
    occupied by `kindLabel(n.kind)` β€” the literals "Alert" / "Automation" / "Shared with you", i.e. a
    CATEGORY where mail puts a who β€” with no sender field anywhere on the wire, in the model or in
    the markup. An alert and an automation have no person behind them and are honestly named by
    their machine; **a SHARE has a real person, and only the PRODUCER knows their name.** By the time
    the read path sees the row that fact is gone, so it has to be carried at write time.

    β›” ADDITIVE, AND THAT IS THE WHOLE DESIGN. No existing caller changes, no stored row changes
    shape, and every reader already tolerates the key's absence β€” so an inbox written before this
    line reads exactly as it did. The alternative C rejected is worth recording because it is the
    tempting one: recovering the name by REGEXING the body prose (`"<name> shared this with you"`).
    A sender parsed out of a sentence breaks the first time the sentence is reworded, and it breaks
    SILENTLY, in the header β€” [[one-question-two-normalizers]] with the second normaliser being
    English.
    ⚠ Blank is a legitimate value and means *"no person did this"*, NOT "unknown". The client falls
    back BY KIND rather than to an empty From column, so an automation never borrows a human's name.

    `inbox` (S72-T27) is an agent message's C6 payload. It rides to the sink only and never
    enters the compatibility row or the returned item.
    """
    items = notify_many([{'owner': owner, 'label': label, 'topic': topic, 'key': key,
                         'row_id': row_id, 'detail': detail, 'actor': actor,
                         'replace': replace, 'target': target, 'inbox': inbox}], st=st)
    return items[0] if items else None


def _notification_write(st, write, count):
    """Count refused notices under their tenant and clear the loss after a successful write."""
    from core import audit
    target = _st(st)
    tenant = getattr(target, 'key', None) or getattr(target, 'tenant_slug', None)
    if tenant is None and target is store:
        tenant = getattr(store._d(), 'tenant_slug', None) or 'royal-imports'
    tenant = tenant or 'unknown'
    try:
        result = write()
    except Exception as exc:
        audit.note_loss(tenant, NOTIFICATIONS_KEY, exc, count)
        raise
    audit.note_ok(tenant, NOTIFICATIONS_KEY)
    return result


def notify_many(entries, st=None):
    """Queue a producer's notifications in one write, preserving the existing inbox wire.

    Replacement is opt-in and scoped to one owner's (topic, alertId). Ticket assignments keep
    the assignment count in the row label and the ticket title in an additive detail cell.
    """
    queued = []
    for entry in entries:
        owner = str(entry.get('owner') or '').strip()
        label = entry.get('label')
        if not owner or not label:
            continue
        topic, key = str(entry.get('topic', 'automation')), str(entry.get('key') or '')
        row_id, detail = str(entry.get('row_id') or ''), str(entry.get('detail') or '')
        at = _now_iso()
        replace = bool(entry.get('replace'))
        item = {'id': f"{key or topic}:{row_id or 'n'}:{at}",
                'alertId': key, 'viewId': '', 'topic': topic, 'rowId': row_id,
                'label': str(detail or label), 'alertLabel': str(label), 'at': at,
                'read': False, 'actor': str(entry.get('actor') or '')}
        if topic == 'ticket' and replace:
            # Subject (`alertLabel`) says who assigned it; the preview (`label`) names the ticket.
            item['detail'] = detail
        if isinstance(entry.get('target'), dict):
            item['target'] = dict(entry['target'])
        sink_extra = {'inbox': dict(entry['inbox'])} if isinstance(entry.get('inbox'), dict) else {}
        queued.append((owner, replace, item, sink_extra))
    if not queued:
        return []
    # Cutover drops old unread rows before this batch writes fresh compatibility rows.
    for owner, _replace, item, sink_extra in queued:
        _publish(owner, {**item, **sink_extra}, st)

    if account_rows.records_backend(_st(st)):
        _notification_write(st, lambda: _append_notification_rows(queued, st=st), len(queued))
        return [item for _owner, _replace, item, _extra in queued]

    def _apply(data):
        owners = set()
        for owner, replace, item, _extra in queued:
            box = list(data.get(owner) or [])
            if replace:
                box = [n for n in box if (n.get('topic'), n.get('alertId')) !=
                       (item['topic'], item['alertId'])]
            box.append(dict(item))
            data[owner] = box
            owners.add(owner)
        for owner in owners:
            box = data[owner]
            if len(box) > MAX_NOTIFICATIONS:
                unread = [n for n in box if not n.get('read')]
                read = [n for n in box if n.get('read')]
                keep_read = read[max(0, len(unread) + len(read) - MAX_NOTIFICATIONS):]
                box = sorted(unread + keep_read, key=lambda n: str(n.get('at') or ''))
            data[owner] = box
        return data

    _notification_write(st, lambda: _st(st).update(NOTIFICATIONS_KEY, _apply, flush='async'), len(queued))
    return [item for _owner, _replace, item, _extra in queued]


def _trim_notifications(items):
    return account_rows.retain_notifications(items)


def _append_notification_rows(queued, *, st):
    for owner in sorted({entry[0] for entry in queued}):
        def append(items, owner=owner):
            for recipient, replace, item, _extra in queued:
                if recipient != owner:
                    continue
                if replace:
                    items = [n for n in items if (n.get('topic'), n.get('alertId')) !=
                             (item['topic'], item['alertId'])]
                items.append(dict(item))
            return _trim_notifications(items)
        account_rows.update_notifications(owner, append, st=_st(st))


def notification_items(user, st=None):
    """Return only the recipient's notices without falling back after a row-store failure."""
    st = _st(st)
    if account_rows.records_backend(st):
        return account_rows.notification_items(str(user), st=st)
    reader = getattr(st, 'get_entry', None)
    if callable(reader):
        return reader(NOTIFICATIONS_KEY, str(user)) or []
    return (st.get(NOTIFICATIONS_KEY) or {}).get(str(user)) or []


def mark_read(user, ids, st=None):
    """Mark allowed notification ids read without changing another recipient's inbox."""
    ids = set(ids)
    def mark(items):
        for item in items:
            if isinstance(item, dict) and item.get('id') in ids:
                item['read'] = True
        return _trim_notifications(items)
    st = _st(st)
    if account_rows.records_backend(st):
        return account_rows.update_notifications(str(user), mark, st=st)
    def apply(data):
        data[str(user)] = mark(data.get(str(user)) or [])
        return data
    return st.update(NOTIFICATIONS_KEY, apply, flush='sync')


def inbox(user, st=None, limit=100):
    """`{'unread': int, 'items': [...]}` β€” newest first, for the badge and the pane."""
    try:
        items = list(notification_items(user, st=st))
    except Exception:
        return {'unread': 0, 'items': []}
    items = [n for n in items if isinstance(n, dict)]
    items.sort(key=lambda n: str(n.get('at') or ''), reverse=True)
    return {'unread': sum(1 for n in items if not n.get('read')), 'items': items[:max(0, limit)]}


def after_write(topic_key, st=None, runner=None):
    """The write-path HOOK: re-evaluate every alert whose view belongs to `topic_key`.

    ⚠ CALLED FROM A WRITE PATH, SO IT MUST NOT RAISE AND MUST NOT BLOCK ON A FULL POOL BUILD.
    A failed alert evaluation must never fail the edit that triggered it β€” the user typed into a
    cell; whether an alert fires is not their problem. `runner` is injected by the caller
    (`routes_alerts` passes one that can resolve the topic's rows for the alert's owner), so this
    module never reaches for a pool itself and stays unit-testable with a fake.
    """
    if runner is None:
        return {'evaluated': 0}
    n = 0
    for rec in list_alerts(st=st):
        if str(rec.get('topic')) != str(topic_key):
            continue
        try:
            runner(rec)
            n += 1
        except Exception:                      # noqa: BLE001 β€” see the docstring
            continue
    return {'evaluated': n}