perceptkit 0.2.2__py3-none-any.whl

perceptkit/algorithms/identity.py

@@ -0,0 +1,43 @@
+"""测量的幂等键。
+
+★ 为什么不能用测量时间（设计文档修订 B）：同一时刻可以有不同设备、不同指标、
+  多条样本；同一条样本还会被修订或删除。按时间去重会同时造成误删和重复累计，
+  而 min/max/sum/count 这类累积形状一旦被重复上传污染就无法回滚 —— 后端不存
+  原始点，扣不回去。
+
+★ 三段都必须由来源提供。缺任何一段就拒绝造键：造一个假键出来，
+  等于让这条记录每次上传都被当成新的。
+
+★ 零 I/O、无随机、跨进程稳定（不用内置 hash()，它每进程加盐）。
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+class MissingIdentity(ValueError):
+    """来源没给齐 (source, metric, sample_id)，无法安全去重。"""
+
+
+def _encode_part(value: str) -> str:
+    """长度前缀编码单个字段：``f"{len(v)}:{v}"``。
+
+    ★ 为什么不能用分隔符拼接（Codex code_review 2026-08-23 抓到）：任何固定
+      分隔符都可能出现在字段内容里，造成两个不同的三元组拼出同一段字节：
+      ``("s", "a\\x1fb", "c")`` 与 ``("s\\x1fa", "b", "c")`` 用 ``\\x1f`` 拼接
+      结果完全相同，无论截多少位哈希都会撞键。长度前缀是自描述的：每一段
+      自带自己的字节长度，解析在读到冒号后精确消费 N 个字节，不依赖内容
+      里不出现某个字符这条无法保证的假设——第三方适配器迟早会传入任意字节。
+    """
+    v = value.strip()
+    return f"{len(v.encode('utf-8'))}:{v}"
+
+
+def measurement_key(*, source: str, metric: str, sample_id: str) -> str:
+    """`(来源命名空间, 指标, 来源侧稳定样本 id)` -> 稳定的十六进制键。"""
+    parts = {"source": source, "metric": metric, "sample_id": sample_id}
+    missing = sorted(k for k, v in parts.items() if not str(v or "").strip())
+    if missing:
+        raise MissingIdentity(f"缺少 {missing}，无法构造幂等键")
+    raw = "".join(_encode_part(str(parts[k])) for k in ("source", "metric", "sample_id"))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:32]

perceptkit/algorithms/observation.py

@@ -0,0 +1,44 @@
+"""观测四态 —— 「没测到」和「测到是零」和「不能测」是三件不同的事。
+
+★ 为什么要分（设计文档修订 A）：HealthKit 没返回睡眠样本，可能是没戴表、
+  没授权、没同步、查询窗口不对。把这些压成一个「没数据」，下游只有两条错路：
+  当成零值 → 编造健康事实（「你昨晚没睡」）；当成不存在 → 连续性判断把
+  周一三五当成连续三天。
+
+★ 零 I/O、纯判断。
+"""
+from __future__ import annotations
+
+OBSERVED = "observed"                 # 有测量值
+OBSERVED_ZERO = "observed_zero"       # 来源明确记录为零（步数/活动量会有；睡眠几乎不会）
+NO_OBSERVATION = "no_observation"     # 查询成功但无样本 —— 「没戴表」和「没睡」都长这样
+UNAVAILABLE = "unavailable"           # 未授权 / 查询失败 / 尚未同步
+
+# 只有这两种可以进数值趋势。其余是 coverage 信息，不是数值。
+TREND_ELIGIBLE: frozenset[str] = frozenset({OBSERVED, OBSERVED_ZERO})
+
+
+def classify(value, *, source_reported_zero: bool = False, available: bool = True) -> str:
+    """把一次取数的结果归到四态之一。
+
+    ``available=False`` 优先级最高：拿不到授权时即使带了值也不能采信。
+    ``source_reported_zero`` 必须由来源背书 —— 我们不从 ``value == 0``
+    自作主张推断，因为多数指标的 0 只是一个普通数值。
+    """
+    if not available:
+        return UNAVAILABLE
+    if value is None:
+        return NO_OBSERVATION
+    if source_reported_zero:
+        return OBSERVED_ZERO
+    return OBSERVED
+
+
+def is_trend_eligible(state: str) -> bool:
+    """这一天的观测能不能作为一个数值参与趋势。未知状态一律不能。"""
+    return state in TREND_ELIGIBLE
+
+
+def breaks_streak(state: str) -> bool:
+    """这一天会不会打断「连续 N 天」。未知状态一律打断（往安全那边倒）。"""
+    return state not in TREND_ELIGIBLE

perceptkit/algorithms/streaks.py

@@ -0,0 +1,111 @@
+"""「连续 N 天偏离」到底怎么算。
+
+★ 四个坑（设计文档修订 G，第④条 2026-08-23 review 补）：
+  ① 按「最近 N 行」算 —— 历史读法会丢掉空日，于是周一三五被排在一起，
+     看起来像连续三天。必须按日历日期判相邻。
+  ② 把「没数据」当成「正常」或「继续」—— 没戴表的那天既不能算偏离，
+     也不能让连续性跨过去。
+  ③ 异常持续超过冷却期就再叫一次 —— 同一个 episode 会被反复播报。
+     所以是 edge-trigger：只在从正常跨入异常那一刻叫。
+  ④ 信任调用方「一定是按日期升序传入」—— 一旦上游（比如读历史表那层）的
+     排序出了问题，会安静地数错，而不是报错或归零。所以 ``current_streak``
+     的输入契约是顺序无关的：自己先排序再走，不假设调用方给对了。
+
+★ 零 I/O、不读时钟：日期与状态都由调用方给。
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import datetime as _dt
+from typing import NamedTuple
+
+from .observation import breaks_streak
+
+
+class Trigger(NamedTuple):
+    """``should_trigger`` 的返回值。
+
+    ★ 为什么加 ``next_firing``（Codex code_review 2026-08-23 抓到）：
+      旧签名只返回 ``(fire, reason)``，``already_firing`` 这个锁存状态完全
+      交给调用方自己维护——但调用方唯一能看到的信号就是这个返回值，如果
+      不把"这段异常有没有结束"算在这里，调用方要么手写一套重复的判断
+      （容易和这里的日历/edge-trigger 逻辑漂移），要么干脆一直传
+      ``already_firing=True`` 直到手动清掉，锁存了就再也打不开——
+      「恢复过再复发」永远叫不出第二次。
+      现在锁存的开合由 ``current_streak`` 算出来，调用方只需要把
+      ``next_firing`` 原样存起来、下次调用原样传回来。
+    """
+    fire: bool
+    reason: str
+    next_firing: bool
+
+
+def _date(raw) -> _dt.date | None:
+    try:
+        return _dt.date.fromisoformat(str(raw)[:10])
+    except (TypeError, ValueError):
+        return None
+
+
+def _sort_key(row) -> tuple[bool, _dt.date]:
+    """结构损坏的行（非 dict、日期解析不了）统一排到最后，让它们在倒序
+    遍历时第一个被撞见 —— 与「结构损坏即不可信」的降级方式保持一致。"""
+    d = _date(row.get("date")) if isinstance(row, Mapping) else None
+    return (d is None, d or _dt.date.min)
+
+
+def current_streak(days: Sequence[Mapping]) -> int:
+    """从最后一天往回数，连续的「有观测且偏离」有几天。
+
+    ``days``：``[{"date", "state", "abnormal"}]``，顺序无关 —— 不依赖调用方
+    保证升序，函数自己先按日期排序再从最近一天往回走。结构损坏的行（非
+    dict、日期解析不了）排到最后，一旦撞见就安全降级、返回 0，而不是抛错
+    或凭空报出一个看似合理实则算错的数字。
+    日历上不相邻、观测缺失、或不偏离，三者任一都终止计数。
+    """
+    ordered = sorted(list(days or ()), key=_sort_key)
+    count = 0
+    expected: _dt.date | None = None
+    for row in reversed(ordered):
+        if not isinstance(row, Mapping):
+            break
+        d = _date(row.get("date"))
+        if d is None:
+            break
+        if expected is not None and d != expected:
+            break                       # 日历上断开了
+        if breaks_streak(str(row.get("state") or "")):
+            break                       # 没观测：不算偏离，也不许跨过去
+        if not row.get("abnormal"):
+            break                       # 回到正常
+        count += 1
+        expected = d - _dt.timedelta(days=1)
+    return count
+
+
+def should_trigger(
+    days: Sequence[Mapping],
+    *,
+    min_days: int,
+    already_firing: bool,
+) -> Trigger:
+    """要不要为这段连续偏离发一次事件，以及调用方下次该存的锁存状态。
+
+    ``already_firing``：调用方记录的「这一段异常是否已经叫过」。它就是
+    hysteresis —— 只有恢复过（连续中断）之后再次达标，才算新事件。
+    返回的 ``reason`` 是给日志和回执用的机器可读串，不是给模型看的措辞。
+
+    ``already_firing=True`` 时不会无条件一直锁着：会用 ``current_streak``
+    检查这段异常是不是已经结束（回到 0）——已经结束就把 ``next_firing``
+    复位成 ``False``，这样调用方下次传回来就能重新触发，而不是永久锁死。
+    复位本身不叫醒（那一刻还没有新的连续异常），真正的下一次叫醒要等
+    新一段异常重新攒够 ``min_days``。
+    """
+    streak = current_streak(days)
+    if already_firing:
+        if streak == 0:
+            return Trigger(False, "recovered", False)
+        return Trigger(False, "already_firing", True)
+    if streak < max(1, int(min_days)):
+        return Trigger(False, "streak_too_short", False)
+    return Trigger(True, "streak_reached", True)

perceptkit/algorithms/trend_models.py

@@ -0,0 +1,184 @@
+"""趋势按三类模型分开算。
+
+★ 为什么不能一套算法走天下（这是本模块存在的全部理由）：
+  现有 read_trend 是「跟最近 N 天的中位数比」，它只适合围绕一个稳定值波动的量。
+  体重一年从 80 掉到 60，用它会得出「你比平时轻 10 公斤」——而这个人
+  从来没有一个叫「平时」的体重。周期性的量（经期）同样不适用。
+
+★ 零 I/O、纯函数：日期只做字符串解析与差值，不取当前时间。
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import datetime as _dt
+
+FLUCTUATING = "fluctuating"   # 有「平时水平」，偏离才是信号
+DRIFTING = "drifting"         # 没有「平时水平」，方向与速率才是信号
+CYCLICAL = "cyclical"         # 看间隔，不看数值高低
+
+# signal -> 模型。未列出的信号沿用波动型（现有 read_trend 的行为）。
+TREND_MODEL: dict[str, str] = {
+    "health_sleep": FLUCTUATING,
+    "health_vitals": FLUCTUATING,
+    "health_activity": FLUCTUATING,
+    "health_body": DRIFTING,
+    "health_cycle": CYCLICAL,
+    # 只查询、不叫醒（见下方 QUERY_ONLY）：血糖/血压/当前心率
+    "health_metabolic": FLUCTUATING,
+}
+
+# 允许进入主动叫醒的指标必须同时满足：有模型 + 不在这张表里。
+#
+# 血糖、血压、当前心率缺餐前/餐后、体位、运动关系与稳定采样协议，
+# 这些数不能直接做同质趋势比较 —— 给 agent 查得到，但不主动打扰。
+QUERY_ONLY: frozenset[str] = frozenset({
+    "health_metabolic",
+})
+
+# 字段级的"只查询、不叫醒"——比 QUERY_ONLY 更细一档（Codex code_review
+# 2026-08-23 抓到）：当前心率不是一个独立信号，是 health_vitals 信号里的
+# 一个字段；而 health_vitals 整体是 FLUCTUATING 且不在 QUERY_ONLY 里，
+# 单看"有模型 + 不在 QUERY_ONLY"会让当前心率被判定成可以叫醒——但它每次
+# 心跳都在变，跟血糖血压一样缺采样协议，不该拿来触发主动打扰。
+# 存 (signal, field) 二元组，不是单独一张 field 名单：同名字段换了信号
+# 语境可能就该叫醒，必须连着信号一起认。
+QUERY_ONLY_FIELDS: frozenset[tuple[str, str]] = frozenset({
+    ("health_vitals", "current_heart_rate"),
+})
+
+# 不参与趋势的派生量 / 常量。
+#
+# BMI 是体重的派生量：体重掉了 BMI 必然跟着掉，两个都叫醒等于同一件事叫两次。
+# 成人身高基本是常量，趋势无意义。
+DERIVED_OR_CONSTANT_FIELDS: frozenset[str] = frozenset({
+    "bmi",
+    "height_cm",
+})
+
+
+def wake_eligible(signal: str, field: str | None = None) -> bool:
+    """这个 (signal, field) 允不允许触发主动叫醒 —— 唯一的判定入口。
+
+    ``QUERY_ONLY``（整个信号只查询）、``QUERY_ONLY_FIELDS``（信号内单个字段
+    只查询，如当前心率）、``DERIVED_OR_CONSTANT_FIELDS``（派生量/常量字段，
+    与信号无关）三张表一起查——接线层不该自己拼「有模型 + 不在 QUERY_ONLY」
+    这条逻辑，那样会漏掉字段级例外。``field`` 缺省时只判信号级。
+    """
+    if field is not None and field in DERIVED_OR_CONSTANT_FIELDS:
+        return False
+    if signal in QUERY_ONLY:
+        return False
+    if field is not None and (signal, field) in QUERY_ONLY_FIELDS:
+        return False
+    return True
+
+_DAYS_PER_MONTH = 30.4375     # 365.25 / 12，避免月份长度参差
+
+
+def model_for(signal: str) -> str:
+    return TREND_MODEL.get(signal, FLUCTUATING)
+
+
+def _date(raw) -> _dt.date | None:
+    try:
+        return _dt.date.fromisoformat(str(raw)[:10])
+    except (TypeError, ValueError):
+        return None
+
+
+def _numeric(v) -> float | None:
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    return None
+
+
+def _points(rows: Sequence[Mapping], field: str | None) -> list[tuple[_dt.date, float]]:
+    out: list[tuple[_dt.date, float]] = []
+    for row in rows or ():
+        if not isinstance(row, Mapping):
+            continue
+        d = _date(row.get("date"))
+        doc = row.get("doc")
+        v = _numeric(doc.get(field)) if (isinstance(doc, Mapping) and field) else None
+        if d is not None and v is not None:
+            out.append((d, v))
+    out.sort(key=lambda p: p[0])
+    return out
+
+
+def _rate_per_month(points: list[tuple[_dt.date, float]]) -> float | None:
+    if len(points) < 2:
+        return None
+    span_days = (points[-1][0] - points[0][0]).days
+    if span_days <= 0:
+        return None
+    delta = points[-1][1] - points[0][1]
+    return round(delta / (span_days / _DAYS_PER_MONTH), 3)
+
+
+def read_drift(rows: Sequence[Mapping], signal: str, field: str | None = None) -> dict:
+    """漂移型：起止对比 + 每月变化速率 + 近期是否在加速。"""
+    points = _points(rows, field)
+    first = {"date": points[0][0].isoformat(), "value": points[0][1]} if points else None
+    last = {"date": points[-1][0].isoformat(), "value": points[-1][1]} if points else None
+    total = round(points[-1][1] - points[0][1], 3) if len(points) >= 2 else (
+        0.0 if len(points) == 1 else None
+    )
+    overall = _rate_per_month(points)
+
+    # 近期速率：最后三分之一的点（至少 2 个）
+    recent = None
+    if len(points) >= 4:
+        recent = _rate_per_month(points[-max(2, len(points) // 3):])
+
+    accelerating = False
+    if overall is not None and recent is not None and overall != 0.0:
+        # 同向且更陡才算加速；反向或走平都不算
+        accelerating = (recent * overall > 0) and (abs(recent) > abs(overall))
+
+    return {
+        "signal": signal,
+        "field": field,
+        "model": DRIFTING,
+        "first": first,
+        "last": last,
+        "total_delta": total,
+        "per_month": overall,
+        "recent_per_month": recent,
+        "accelerating": accelerating,
+        "n": len(points),
+    }
+
+
+def read_cycles(events: Sequence[str], *, today: str) -> dict:
+    """周期型：看相邻两次的间隔，以及这次是否比往常推迟。
+
+    ``events`` 是事件日期（升序或乱序都行，内部会排序去重）；
+    ``today`` 由调用方传入 —— 内核不取当前时间。
+    """
+    dates = sorted({d for d in (_date(e) for e in (events or ())) if d is not None})
+    now = _date(today)
+
+    intervals = [(b - a).days for a, b in zip(dates, dates[1:])]
+    typical = None
+    if intervals:
+        ordered = sorted(intervals)
+        mid = len(ordered) // 2
+        typical = (ordered[mid] if len(ordered) % 2
+                   else round((ordered[mid - 1] + ordered[mid]) / 2))
+
+    days_since = (now - dates[-1]).days if (now is not None and dates) else None
+    overdue = None
+    if typical is not None and days_since is not None:
+        overdue = max(0, days_since - typical)
+
+    return {
+        "model": CYCLICAL,
+        "intervals": intervals,
+        "typical_interval": typical,
+        "days_since_last": days_since,
+        "overdue_by": overdue,
+        "n": len(dates),
+    }

perceptkit/algorithms/wake.py

@@ -0,0 +1,149 @@
+"""「这次上报算不算一件事」「值不值得戳一下 agent」的纯判据。
+
+★ wake ≠ 该开口了。这里只回答要不要戳；戳醒之后 agent 继续睡 / 只看一眼 /
+  开口说话，是三个平行选项，内核不参与。``should_wake`` 的第二个返回值是
+  **给日志和回执用的机器可读原因**，不是给模型看的措辞，更不是「该说什么」。
+
+★ 零 I/O：不查库、不看时钟、不发 metrics。时间由调用方传进来
+  （``now`` / ``last_wake_ts`` / ``observed`` / ``previous_seen``），
+  这样才可测、才能被任意宿主复用。
+
+★ 判据搬过来，机制一行不动：事务、行锁、指纹比对这类「怎么保证不重复触发」的
+  机制，全部留在宿主那一侧。内核只回答「算不算 / 值不值得」，不管怎么落地。
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+# ---------------------------------------------------------------------------
+# 感知叫醒源
+# ---------------------------------------------------------------------------
+# 🔴 **刻意不叫 "wake kind"。** 宿主自己的运行时往往已经有别的、含义不同的
+#    "wake kind" 概念——比如「这次叫醒走哪条投递通道」，或者「哪几类叫醒要
+#    互相防撞去重」。这些都是宿主接线层的关注点，和这里要回答的问题不是一件事：
+#
+#      宿主·投递通道选择   —— 「这次叫醒该走哪条路径送出去」
+#      宿主·防撞分类       —— 「哪几类叫醒要互相防重复」
+#      本模块 `PERCEPTION_WAKE_SOURCES` —— 「这次戳是被什么感知到的」
+#
+#    三者关注的问题不同，字面上即使有重叠的词（比如都用到 "screen_watch"
+#    这个名字），含义也不能互换。本模块这套讲的是**感知来源**，不是运行时
+#    通道、也不是防撞分类，故用 `PERCEPTION_WAKE_SOURCES` 这个名字，和宿主
+#    自己那几套划清界限——接线时不要为了「统一命名」反过来去改宿主已有的
+#    契约，那是两件独立的事。
+#
+# 下面五个是感知来源的语义分类，各自对应「一类可能触发叫醒的信号变化」：
+#
+#   source        语义
+#   ------------  ---------------------------------------------
+#   arrival       到达某个持久锚点附近（比如常去的地点）
+#   unlock        长时间静默后重新解锁
+#   photo         新增照片
+#   screen_watch  屏幕内容/场景发生显著变化
+#   broadcast     一段广播式状态开始或结束
+#
+# broadcast 没有独立开关——宿主实现里可能把它挂在 screen_watch 那个总开关下；
+# 但它在信号目录里是独立的一个 wake capability（自带独立的 debounce），所以
+# 去重要分开算。两件事，都保留。
+PERCEPTION_WAKE_SOURCES: tuple[str, ...] = (
+    "arrival",
+    "unlock",
+    "photo",
+    "screen_watch",
+    "broadcast",
+)
+
+
+# ---------------------------------------------------------------------------
+# 「值变了算不算一件事」
+# ---------------------------------------------------------------------------
+# 这份名单的语义是**默认算数 + 一张明确的否决名单**，不是「白名单里才算」——
+# 真正的叫醒源（photo_added / screen_phash / unlock_after_absence / 几个
+# anchor 类信号 / broadcast_state）压根不在信号目录（catalog）的 SIGNALS
+# 表里（那张表装的是设备上报字段的 key，两套词表交集为空），用白名单会把
+# 每一个真实叫醒源都判成「不算」——这是一个真实踩过的坑：换成白名单实现后，
+# 会静默停发全部叫醒事件，而当时的回归测试全绿，因为没有一条测试直接对着
+# `is_wake_worthy_signal` 断言过真实叫醒信号该返回 True。
+#
+# motion 的特例：它是可拉取的上下文，但变得太频繁，故意不作为叫醒源。
+NOT_WAKE_WORTHY_SIGNALS: frozenset[str] = frozenset({
+    "motion_state",
+    "battery",
+    "now_playing",
+    "time",
+    "place_label",
+})
+
+
+def is_wake_worthy_signal(signal: str) -> bool:
+    """这个信号变了，值不值得发一次叫醒事件（不问值本身变没变）。
+
+    给已经在别处 durable 地判完「变没变」的调用方用——调用方自己负责判断
+    「这次上报和上一次相比是否真的不同」（比如做指纹比对），这里只回答
+    「即使真的变了，这类信号是否值得为此叫醒一次」。
+    """
+    return signal not in NOT_WAKE_WORTHY_SIGNALS
+
+
+def is_significant_change(signal: str, previous, current) -> bool:
+    """值变了、且这个信号的变化本身值得注意，才算一件事。
+
+    调用方同时握着新旧两个值时用这个；只握着「变没变」这个结论时用
+    ``is_wake_worthy_signal``。两者是同一条判据的两半，不是两套。
+    """
+    if previous == current:
+        return False
+    return is_wake_worthy_signal(signal)
+
+
+# ---------------------------------------------------------------------------
+# 「这条上报是不是迟到 / 撞点了」
+# ---------------------------------------------------------------------------
+# 纯粹的先后判断。调用方通常是在加锁读出上一条记录的时间戳之后调它——
+# **锁、事务、指纹比对这些机制都留在宿主**，内核只回答先后关系。
+OBSERVATION_STALE = "stale"          # 比上一条还早：迟到的乱序上报
+OBSERVATION_SAME_TS = "same_ts"      # 和上一条同一时刻：可能是重复，也可能是撞点冲突
+OBSERVATION_NEWER = "newer"          # 比上一条新：正常的下一条
+
+
+def observation_order(observed, previous_seen) -> str:
+    """比较两个时刻，返回 ``stale`` / ``same_ts`` / ``newer`` 之一。
+
+    只用 ``<`` 和 ``==``，对 float 和 tz-aware datetime 都成立；不做任何
+    转换，免得把调用方原本的比较语义改掉。
+    """
+    if observed < previous_seen:
+        return OBSERVATION_STALE
+    if observed == previous_seen:
+        return OBSERVATION_SAME_TS
+    return OBSERVATION_NEWER
+
+
+# ---------------------------------------------------------------------------
+# 「值不值得戳一下 agent」
+# ---------------------------------------------------------------------------
+# ⚠️ 接线提醒：下面这几个原因串是**内核自己的词**（``source_disabled`` /
+#    ``debounced``），宿主如果已经有一套用户可见的原因字符串在用（比如按
+#    source 分开命名、或写进事件流 / 审计日志），接线时要先决定「统一成一套」
+#    还是「维护一张映射表」——这属于用户可见的行为变更，不要在接线时顺手改掉。
+def should_wake(
+    source: str,
+    *,
+    enabled_sources: Sequence[str],
+    last_wake_ts: float | None,
+    now: float,
+    debounce_sec: float,
+) -> tuple[bool, str]:
+    """返回 ``(要不要戳, 原因)``。
+
+    原因是给日志和回执用的机器可读短语，**不是给模型看的**：这里不产出、不暗示
+    任何跟「该说什么」有关的东西。戳醒之后 agent 接着睡、只查一个工具、还是开口
+    说话，是三个平行且同等合法的结局，内核不参与那个决定。
+    """
+    if source not in PERCEPTION_WAKE_SOURCES:
+        return False, "unknown_source"
+    if source not in tuple(enabled_sources or ()):
+        return False, "source_disabled"
+    if last_wake_ts is not None and (now - last_wake_ts) < debounce_sec:
+        return False, "debounced"
+    return True, source