perceptkit 0.2.2__tar.gz → 0.2.4__tar.gz

{perceptkit-0.2.2 → perceptkit-0.2.4}/CHANGELOG.md

@@ -1,6 +1,58 @@
 # 变更记录
 
-## 0.2.2 — 未发布
+## 0.2.4 — 未发布
+
+**第一批真机数据跑出来的。** 4052 次比对里三处不一致，这是其中属于内核的那一处。
+
+### 修复
+
+- **「音乐停了」这个状态进不了系统。** `track_key` 声明成必填，而播放器停着的
+  时候没有曲目 —— 于是那条观测因「缺必填字段」被**整条拒掉**：在放什么记得住，
+  停了永远记不住。而「他刚把音乐关了」恰恰是这个信号最有用的那一半。
+  真机上 83 次上报，83 次都是这个。
+
+  规范 §5.3 把 `track_id` 列为字段，没说它任何时候都必须有值。
+
+
+## 0.2.3 — 2026-09-01
+
+**七个「声明了、但没有代码做」的修复。** 都是拿规范逐条跑代码跑出来的，
+不是照着清单打勾 —— 清单把这七条全判成了成立，因为它核的是 manifest 怎么写的。
+
+### 修复
+
+- 🔴 **归属日期用的是时间戳自带的 offset，不是观测声明的 IANA 时区。**
+  producer 完全可以用 UTC 发 `occurred_at`、把时区另放在观测里（参考的 iOS
+  适配层就是这么发的）。上海用户本地 00:00–08:00 的数据**每天全部落到前一天**，
+  "昨天走了多少步""昨晚睡了几小时"跟着一起偏。
+
+- 🔴 **去重身份问错了保留期。** `DurableDedupeIdentity` 单独成表的全部理由是
+  「明细会过期、聚合可能永久」，而标记它的条件问的是**明细**永不永久 ——
+  于是恰好在它唯一有用的四个信号上（照片、focus、motion、music）判成不用守。
+  身份先于聚合被清掉之后，一次重传把永久聚合多加一遍，**明细已经不在，
+  算不回去**。
+
+- 🔴 **`comparison_strategy="state_change"` 声明了，没有任何代码读它。**
+  保活上报每 5 分钟一次，「还在专注」一天写出几百条一模一样的记录。
+  只跳过明细，**当前值和聚合照常走** —— `duration_by_state` 靠相邻观测的
+  时间差累计，跳过聚合是拿一个 bug 换另一个。
+
+- 🔴 **一个信号只能有一条当前值。** `dimension_key` 在主键里、却永远等于信号名。
+  同时连着两个 Wi-Fi 锚点只剩一个；用户搬家、新旧网络都叫 "home" 会被合并，
+  之后历史再也分不开哪段是哪个家。信号现在可以声明 `dimension_fields`，
+  不声明的行为逐字节不变。
+
+- **「今天打开了几次」永远答 1。** `open_count` 声明的是 `daily_total`（取 max），
+  而每次打开各贡献 1 —— 一列 1 取最大值还是 1。新增 `occurrence_count`（求和），
+  和 `cumulative` 并排放、把差别写在定义旁边。
+
+- **每日照片数量按明细的保留期过期。** 明细和聚合是两个数，只写了一个，
+  于是聚合继承了 7 天 ——「8月1日新增 5 张」是发生过的事实，不是"现在还剩几张"。
+
+- conformance 补第 ⑪ 条已在 0.2.1；本版把上面这些各配一条会红的回归测试。
+
+
+## 0.2.2 — 2026-09-01
 
 **代码没有变化。** 这一版只换了「怎么发出去」。
 

{perceptkit-0.2.2 → perceptkit-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: perceptkit
-Version: 0.2.2
+Version: 0.2.4
 Summary: 从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不碰存储、不调模型。
 License: 
                                          Apache License

{perceptkit-0.2.2 → perceptkit-0.2.4}/docs/reference-storage-mapping.md

@@ -24,7 +24,7 @@
 | `location_city` | CurrentProjection + StoredObservation + DailyAggregate | 900s | 永久 | 同明细 | deterministic_digest | instant |
 | `motion_state` | CurrentProjection + StoredObservation + DailyAggregate | 900s | 365 天 | 永久 | deterministic_digest | instant |
 | `music_playback` | CurrentProjection + StoredObservation + DailyAggregate | 600s | 365 天 | 永久 | deterministic_digest | instant |
-| `photo_library_added` | CurrentProjection + StoredObservation + DailyAggregate | — | 7 天 | 同明细 | source_event_id | instant |
+| `photo_library_added` | CurrentProjection + StoredObservation + DailyAggregate | — | 7 天 | 永久 | source_event_id | instant |
 | `presence_recovery` | CurrentProjection | — | 不存 | 不适用 | source_event_id | instant |
 | `proximity_anchor` | CurrentProjection + StoredObservation | 900s | 7 天 | 同明细 | deterministic_digest | instant |
 | `screen_change` | CurrentProjection | 60s | 不存 | 不适用 | singleton | instant |

{perceptkit-0.2.2 → perceptkit-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "perceptkit"
-version = "0.2.2"
+version = "0.2.4"
 description = "从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不碰存储、不调模型。"
 readme = "README.md"
 requires-python = ">=3.10"

{perceptkit-0.2.2 → perceptkit-0.2.4}/src/perceptkit/algorithms/attribution.py

@@ -73,17 +73,45 @@ def _utc_naive(dtobj: _dt.datetime) -> _dt.datetime:
     return dtobj.replace(tzinfo=None) - dtobj.utcoffset()
 
 
-def attribute_instant(when: str) -> str:
-    """单点测量：按它自己那个 offset 下的本地日期。"""
-    return _aware(when).date().isoformat()
+def _local(dtobj: _dt.datetime, tz: str | None) -> _dt.datetime:
+    """换算到观测声明的那个时区。没声明就用时间戳自带的 offset。
 
+    ★ **这两件事不是一回事，混用会把数据归错天。**
 
-def attribute_episode(start: str, end: str) -> str:
-    """区间事件（睡眠、一次运动）：整体归结束那天。"""
+    时间戳自带的是一个**固定 offset**；``tz`` 是一整套带换日规则的时区。
+    producer 完全可以（而且常常）用 UTC 发 ``occurred_at``、把 IANA 时区另放
+    在观测的 ``timezone`` 字段里 —— 那时按 offset 算出来的是 UTC 日期，不是
+    用户的本地日期。
+
+    实例（这就是它被写出来的原因）：上海用户早上 7 点，``occurred_at`` 是
+    ``T-1 23:00+00:00``。按 offset 算 = 前一天。**每天本地 00:00–08:00 的数据
+    全部落到前一天**，"昨天走了多少步""昨晚睡了几小时"跟着一起偏。
+    """
+    if not tz:
+        return dtobj
+    try:
+        return dtobj.astimezone(_zoneinfo.ZoneInfo(tz))
+    except Exception:                              # noqa: BLE001
+        # 时区名不认识时按 offset 算 —— 这是降级，不是等价物，
+        # 但比整条观测拒收好：调用方已经在别处对时区名做了校验。
+        return dtobj
+
+
+def attribute_instant(when: str, *, tz: str | None = None) -> str:
+    """单点测量：归到它发生时、**当地**的那一天。
+
+    ``tz`` 是观测声明的 IANA 时区。不传时退回时间戳自带的 offset —— 见
+    ``_local`` 里说明这两者为什么不等价。
+    """
+    return _local(_aware(when), tz).date().isoformat()
+
+
+def attribute_episode(start: str, end: str, *, tz: str | None = None) -> str:
+    """区间事件（睡眠、一次运动）：整体归结束那天的**当地**日期。"""
     s, e = _aware(start), _aware(end)
     if e < s:
         raise ValueError(f"区间结束早于开始：{start!r} -> {end!r}")
-    return e.date().isoformat()
+    return _local(e, tz).date().isoformat()
 
 
 def split_across_midnight(start: str, end: str, *, tz: str | None = None) -> list[tuple[str, float]]:

{perceptkit-0.2.2 → perceptkit-0.2.4}/src/perceptkit/algorithms/history.py

@@ -32,6 +32,16 @@ EVENT_LIST = "event_list"            # discrete items, deduped by id/key
 SUBJECTIVE = "subjective"            # append each self-report entry
 PLACE_DWELL = "place_dwell"          # minutes spent at each place label
 TALLY = "tally"                      # daily digest: total minutes + top artists/tracks
+OCCURRENCE_COUNT = "occurrence_count"    # per numeric field: SUM of per-event contributions
+
+# ★ `occurrence_count` 和 `cumulative` 差一个字，语义正好相反，混用不会报错、
+#   只会给出一个安静的错数：
+#
+#       cumulative        来源自己在数（今日步数 8000 → 8300），当天代表值取 **max**
+#       occurrence_count  每次事件各贡献一份（每次打开 app 记 1），当天要 **sum**
+#
+#   拿 cumulative 去数「今天打开了几次」，每条都是 1，max 永远是 1 —— 用户开了
+#   二十次，答案还是「1 次」。
 
 _TALLY_CAP = 30                      # keep only the top-N artists/tracks per day
 
@@ -265,8 +275,26 @@ def _merge_subjective(doc: dict, values: Mapping, *, ts: float | None = None, **
     return out
 
 
+def _merge_occurrence_count(doc: dict, values: Mapping, **_) -> dict:
+    """每次事件各贡献一份，当天累加。
+
+    和 ``_merge_cumulative`` 的区别见 ``OCCURRENCE_COUNT`` 上面那段：那个取
+    max（来源自己在数），这个求和（我们在数）。
+    """
+    out = dict(doc)
+    for field, raw in values.items():
+        n = _numeric(raw)
+        if n is None:
+            continue
+        prev = out.get(field)
+        base = prev.get("total", 0.0) if isinstance(prev, Mapping) else 0.0
+        out[field] = {"total": base + n}
+    return out
+
+
 _MERGERS = {
     NUMERIC_DIST: _merge_numeric_dist,
+    OCCURRENCE_COUNT: _merge_occurrence_count,
     CUMULATIVE: _merge_cumulative,
     MAIN_OF_DAY: _merge_main_of_day,
     DURATION_BY_STATE: _merge_duration_by_state,

{perceptkit-0.2.2 → perceptkit-0.2.4}/src/perceptkit/manifest/minimal.py

@@ -600,6 +600,10 @@ PHOTO_LIBRARY_ADDED = SignalDefinition(
     identity_strategy="source_event_id",
     attribution_strategy="instant",
     history_retention_days=7,
+    # 单条明细 7 天，**每日新增数量永久**。两个数必须分开写：不写聚合那个
+    # 就会继承明细的 7 天，于是「8月1日新增了 5 张」一周后被扫掉 ——
+    # 而那是一件发生过的事实，不是「现在还剩几张」。
+    aggregate_retention_days=PERMANENT,
     source_profile="device_occurrence",
     note=(
         "一张照片一条 count=1，不是「今天 5 张」报一次 —— 拆成一条条才能让照片"
@@ -973,6 +977,9 @@ PROXIMITY_ANCHOR = SignalDefinition(
     # 同上：时间点快照，时长由聚合层从相邻观测算。
     attribution_strategy="instant",
     # 产品规范 §1-15：Wi-Fi / 蓝牙连接历史保留 7 天。
+    # 每个 anchor 各一条当前值。同时连着家里和公司是两个答案；
+    # 用户搬家后新旧网络都叫 "home",按名字看是一个、按 anchor_id 看是两个。
+    dimension_fields=("anchor_id",),
     history_retention_days=7,
     source_profile="location",
     note=(
@@ -1086,7 +1093,15 @@ MUSIC_PLAYBACK = SignalDefinition(
             key="track_key",
             value_type="string",
             privacy_class="sensitive",
-            nullable=False,
+            nullable=True,
+            # ★ 「什么都没在放」是一个**正常状态**，而它没有曲目。
+            #
+            #   非空的话，播放器停着的那条观测因为缺必填字段被整条拒掉 ——
+            #   于是 kit 永远不知道「音乐停了」，只知道「在放什么」。
+            #   真机上这条占了 83 次差异里的 83 次：老路记着 stopped，
+            #   kit 那边一片空白。
+            #
+            #   规范 §5.3 把 track_id 列为字段，没说它任何时候都必须有值。,
             comparison_strategy="exact",
             wake_eligible=True,
             query_visibility="on_demand",
@@ -1233,9 +1248,11 @@ APP_USAGE = SignalDefinition(
             unit="count",
             privacy_class="sensitive",
             valid_range=(0, None),
-            # 每条 open 贡献 1，当天累加。**只靠 open，所以可信** ——
+            # 每条 open 贡献 1，当天**求和**。**只靠 open，所以可信** ——
             # 这正是砍掉时长统计之后仍然答得准的那部分。
-            aggregation_strategy="daily_total",
+            # ⚠️ 曾经写的是 daily_total（取 max），于是「今天打开了几次」
+            # 永远等于 1 —— 这个信号唯一保证答得准的问题，答错了。
+            aggregation_strategy="occurrence_count",
             comparison_strategy="none",
             query_visibility="on_demand",
             trend_model="fluctuating",

{perceptkit-0.2.2 → perceptkit-0.2.4}/src/perceptkit/manifest/types.py

@@ -16,7 +16,7 @@ manifest 只声明**属性**,不实现算法。``normalizer`` / ``aggregation_st
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Mapping
 
 # ---------------------------------------------------------------------------
 # 值域
@@ -46,7 +46,7 @@ STORAGE_MODES: frozenset[str] = frozenset({
 
 #: 日聚合的算法。名字要能解析到实现。
 AGGREGATION_STRATEGIES: frozenset[str] = frozenset({
-    "none", "daily_total", "numeric_dist",
+    "none", "daily_total", "occurrence_count", "numeric_dist",
     "duration_by_state", "event_list", "tally", "main_of_day", "cumulative",
 })
 
@@ -159,6 +159,16 @@ class SignalDefinition:
     identity_strategy: str
     attribution_strategy: str
     fields: tuple[FieldDefinition, ...]
+    #: 哪几个字段把这个信号的当前值**分成并列的多条**。
+    #:
+    #: 空（默认）= 一个信号一条当前值，新的覆盖旧的。绝大多数信号就该这样：
+    #: 电量、天气、运动状态，同一时刻只有一个答案。
+    #:
+    #: 非空 = 每个取值组合各留一条。锚点是这么来的：同时连着家里和公司两个
+    #: Wi-Fi，「当前连着哪些锚点」有两个答案，覆盖式写入只会剩最后一个。
+    #: 更糟的是用户搬家、新旧网络都叫 "home" —— 按名字看是同一个，按
+    #: ``anchor_id`` 看是两个，合并之后历史再也分不开哪段是哪个家。
+    dimension_fields: tuple[str, ...] = ()
     #: **明细**（逐条观测）保留多少天。``PERMANENT`` = 永久;``0`` = 不存历史。
     history_retention_days: int = 0
     #: **聚合**（日统计）保留多少天。默认跟着明细走 —— 但两者常常不该一样。
@@ -191,6 +201,18 @@ class SignalDefinition:
     def keeps_history_forever(self) -> bool:
         return self.history_retention_days == PERMANENT
 
+    def dimension_key_for(self, value: Mapping[str, Any] | None) -> str:
+        """这条观测落在哪一条当前值上。
+
+        没声明 ``dimension_fields`` 就用信号名 —— 一个信号一条，和以前一样。
+        声明了就按那几个字段的取值拼出来；取不到值的按空串参与，**不能退回
+        信号名**：那会让「拿不到 anchor_id 的那条」去覆盖掉一条真的锚点。
+        """
+        if not self.dimension_fields:
+            return self.key
+        parts = [str((value or {}).get(f) or "") for f in self.dimension_fields]
+        return self.key + "\x1f" + "\x1f".join(parts)
+
     @property
     def effective_aggregate_retention_days(self) -> int:
         """聚合实际留多久。没单独声明就跟明细一样。"""

{perceptkit-0.2.2 → perceptkit-0.2.4}/src/perceptkit/processing/aggregate.py

@@ -17,6 +17,9 @@ from ..manifest.types import SignalDefinition
 _STRATEGY_TO_SHAPE: dict[str, str] = {
     "daily_total": history.CUMULATIVE,
     "cumulative": history.CUMULATIVE,
+    # 每次事件贡献一份、当天求和。**不是** daily_total：那个取 max，
+    # 用来数「打开了几次」会永远得到 1。
+    "occurrence_count": history.OCCURRENCE_COUNT,
     "numeric_dist": history.NUMERIC_DIST,
     "main_of_day": history.MAIN_OF_DAY,
     "duration_by_state": history.DURATION_BY_STATE,

{perceptkit-0.2.2 → perceptkit-0.2.4}/src/perceptkit/processing/normalize.py

@@ -217,7 +217,7 @@ def effective_date(
         # 上游说好了给本地日期却没给 —— 退回按发生时刻算，并记一笔，
         # 不静默换算法。
         problems.append(f"{sig.key}: 声明了 source_local_date 但 payload 里没有 local_date")
-        return _parse(attribution.attribute_instant(iso)), (), problems
+        return _parse(attribution.attribute_instant(iso, tz=timezone_name)), (), problems
 
     if strategy in ("episode_end", "split_at_midnight"):
         start, end = value.get("start_at"), value.get("end_at")
@@ -226,21 +226,21 @@ def effective_date(
                 f"{sig.key}: {strategy} 需要 start_at / end_at，"
                 f"退回按 occurred_at 归属"
             )
-            return _parse(attribution.attribute_instant(iso)), (), problems
+            return _parse(attribution.attribute_instant(iso, tz=timezone_name)), (), problems
         # producer 可能发来不合法的区间（结束早于开始、时间戳格式不对）。
         # **只拒这一条，不能炸掉整批** —— 一批十条里一条有问题就全丢，
         # 是最容易让人骂街的设计，管线其他地方都守住了这条，这里以前漏了。
         try:
             if strategy == "episode_end":
-                return _parse(attribution.attribute_episode(start, end)), (), problems
+                return _parse(attribution.attribute_episode(start, end, tz=timezone_name)), (), problems
             slices = tuple(attribution.split_across_midnight(start, end, tz=timezone_name))
             return _parse(slices[-1][0]) if slices else _parse(
-                attribution.attribute_episode(start, end)
+                attribution.attribute_episode(start, end, tz=timezone_name)
             ), slices, problems
         except (ValueError, TypeError) as exc:
             raise AttributionError(f"{sig.key}: {exc}") from exc
 
-    return _parse(attribution.attribute_instant(iso)), (), problems
+    return _parse(attribution.attribute_instant(iso, tz=timezone_name)), (), problems
 
 
 # ---------------------------------------------------------------------------

{perceptkit-0.2.2 → perceptkit-0.2.4}/src/perceptkit/processing/pipeline.py

@@ -172,6 +172,41 @@ def ingest_report(
     return outcome
 
 
+def _repeats_declared_state(
+    item: NormalizedObservation,
+    sig: SignalDefinition,
+    *,
+    context: IngestContext,
+    storage: StoragePort,
+) -> bool:
+    """这条观测是不是「和当前值同一个状态」的重复上报。
+
+    只看声明了 ``comparison_strategy="state_change"`` 的字段。**这个声明以前
+    在 manifest 里写着、却没有任何代码读它** —— 于是 focus / motion /
+    time_context 上那句「只在变化时追加」在文档里成立、在数据里不成立。
+
+    保守判定：只有当前值确实存在、且**每一个**声明了 state_change 的字段都和
+    当前值一样时，才算重复。任何一个字段变了、或者当前值还不存在（第一条）、
+    或者这条不是 observed，都照常写明细 —— 宁可多写一条，不可漏掉一次真正的
+    状态变化。
+    """
+    if item.stored.availability != "observed":
+        return False
+    watched = [f.key for f in sig.fields if f.comparison_strategy == "state_change"]
+    if not watched:
+        return False
+    value = item.stored.typed_value or {}
+    for projection in storage.get_current(
+        subject_id=context.subject_id, signals=[sig.key],
+    ).get(sig.key, ()):
+        if (projection.dimension_key != sig.dimension_key_for(value)
+                or projection.availability != "observed"):
+            continue
+        current = projection.typed_value or {}
+        return all(current.get(k) == value.get(k) for k in watched)
+    return False
+
+
 def _apply_one(
     item: NormalizedObservation,
     sig: SignalDefinition,
@@ -200,7 +235,17 @@ def _apply_one(
         return
 
     # ④ 写观测。只留当前值的信号不写明细 —— 否则 current_only 名不副实。
-    if sig.stores_history:
+    #
+    #    声明了 `state_change` 的字段还有一条：状态没变就**不追加明细**，只刷新
+    #    当前值。iOS 每 5 分钟保活上报一次，「还在专注」「还在静止」会一天写出
+    #    几百条一模一样的记录 —— 时间线本该记的是「什么时候变了」，被同一个
+    #    状态刷满之后，「每日切换次数」「最长一段」这类聚合直接失去意义。
+    #
+    #    ⚠️ 只跳过明细，**当前值和聚合照常走**：`duration_by_state` 靠相邻两条
+    #    观测的时间差累计时长，跳过聚合会把时长永远停在第一次。
+    if sig.stores_history and not _repeats_declared_state(
+        item, sig, context=context, storage=storage,
+    ):
         if not storage.append_observation(stored):
             outcome.duplicates.append(item)
             return
@@ -213,7 +258,15 @@ def _apply_one(
         source=stored.source,
         source_event_identity_digest=item.identity_digest,
         first_applied_at=context.received_at,
-        aggregate_scope=sig.key if sig.keeps_history_forever else None,
+        # ★ 问的是**聚合**永不永久，不是明细。
+        #
+        #   这条记录存在的全部理由就是「明细会过期、聚合可能永久」——
+        #   所以拿明细的保留期来判断，恰好在它唯一有用的那些信号上判成 None：
+        #   照片（明细 7 天 / 每日数量永久）、focus / motion / music
+        #   （明细 1 年 / 聚合永久）。四个信号的去重身份可以先于聚合被清掉，
+        #   之后一次重传就把永久聚合多加一遍，**加完没法回滚**。
+        #   产品规范 §14-2 点名的正是这个场景。
+        aggregate_scope=sig.key if sig.keeps_aggregates_forever else None,
         # 永久聚合依赖的身份必须永久保留：明细删了之后，
         # 它是唯一还能挡住重放的东西。
         retain_until=None,
@@ -289,7 +342,7 @@ def _update_current(
     from ..contracts.records import decide_current_update
 
     stored = item.stored
-    dimension = sig.key
+    dimension = sig.dimension_key_for(stored.typed_value)
 
     for attempt in range(MAX_CAS_RETRIES):
         existing = None

{perceptkit-0.2.2 → perceptkit-0.2.4}/tests/test_manifest.py

@@ -360,7 +360,10 @@ def test_app_usage_counts_opens_but_never_totals_duration():
     「今天打开了几次」只靠 open 就能答，所以配置不全也不影响。
     """
     fields = MINIMAL_SIGNALS["app_usage"].field_map()
-    assert fields["open_count"].aggregation_strategy == "daily_total"
+    # `occurrence_count`（求和），**不是** `daily_total`（取 max）。
+    # 后者是给「来源自己在数」的量用的（今日步数 8000 → 8300）；每次打开各贡献
+    # 1 的话，max 永远是 1 —— 用户开了二十次，答案还是「1 次」。
+    assert fields["open_count"].aggregation_strategy == "occurrence_count"
     # 没有任何字段在按时长聚合
     assert all(f.aggregation_strategy != "duration_by_state"
                for f in MINIMAL_SIGNALS["app_usage"].fields)

{perceptkit-0.2.2 → perceptkit-0.2.4}/tests/test_regressions.py

@@ -556,3 +556,301 @@ def test_a_field_that_declares_no_aggregation_is_not_aggregated():
                                 start_date=at.date(), end_date=at.date()
                                 )[0].typed_aggregate
     assert list(doc) == ["temperature_c"]
+
+
+# ---------------------------------------------------------------------------
+# I6 —— 归属日期用了时间戳的 offset，而不是观测声明的时区
+#
+# 我们**自己**在给产品方的信里写过这条（§19）：「`occurred_at` 的偏移不能
+# 替代时区」。代码里没做到。
+# ---------------------------------------------------------------------------
+
+def test_the_declared_timezone_decides_the_day_not_the_timestamp_offset():
+    """上海用户早上 7 点，那条数据属于今天，不是昨天。
+
+    producer 用 UTC 发 `occurred_at`、把 IANA 时区放在观测的 `timezone` 里 ——
+    这是完全正常的发法，io 的适配层就是这么发的。按 offset 算日期的话，
+    **本地 00:00–08:00 的数据每天都落到前一天**：一整个凌晨加早晨，
+    「昨天走了多少步」「昨晚睡了几小时」跟着一起偏。
+    """
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    at = datetime(2026, 9, 1, 16, 0, tzinfo=timezone.utc)      # 上海 = 9/2 00:00
+    kit.ingest({
+        "schema_version": 1, "report_id": "r1", "producer": "ios",
+        "observations": [{
+            "signal": "motion_state", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai", "value": {"state": "walking"},
+        }],
+    }, context=IngestContext("u", at))
+    rows, _ = storage.list_observations(subject_id="u", signal="motion_state")
+    assert str(rows[0].effective_local_date) == "2026-09-02"
+
+
+# ---------------------------------------------------------------------------
+# I7 —— `comparison_strategy` 声明了，但没有任何代码读它
+# ---------------------------------------------------------------------------
+
+def _focus(kit, at, active=True):
+    kit.ingest({
+        "schema_version": 1, "report_id": f"f{at.isoformat()}", "producer": "ios",
+        "observations": [{
+            "signal": "focus_state", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai", "value": {"is_active": active},
+        }],
+    }, context=IngestContext("u", at))
+
+
+def test_a_state_that_did_not_change_does_not_add_a_timeline_entry():
+    """iOS 每 5 分钟保活上报一次，「还在专注」一天能写出几百条一样的记录。
+
+    时间线记的是**什么时候变了**。被同一个状态刷满之后，「每日切换次数」
+    「最长一段」这类聚合就没有意义了。manifest 上一直写着
+    `comparison_strategy="state_change"`，只是没有代码读它。
+    """
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    base = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    for i in range(4):
+        _focus(kit, base + timedelta(minutes=5 * i))
+    rows, _ = storage.list_observations(subject_id="u", signal="focus_state")
+    assert len(rows) == 1
+
+    _focus(kit, base + timedelta(minutes=25), active=False)     # 真的变了
+    rows, _ = storage.list_observations(subject_id="u", signal="focus_state")
+    assert len(rows) == 2
+
+
+def test_suppressing_repeats_still_lets_the_duration_aggregate_advance():
+    """只跳过明细，**当前值和聚合照常走**。
+
+    `duration_by_state` 靠相邻两条观测的时间差累计时长 —— 跳过聚合会让时长
+    永远停在第一次，那就是用一个 bug 换另一个。
+    """
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    base = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    for i in range(4):
+        _focus(kit, base + timedelta(minutes=5 * i))
+    doc = storage.get_aggregate(subject_id="u", signal="focus_state",
+                                start_date=base.date(), end_date=base.date()
+                                )[0].typed_aggregate
+    assert doc["minutes"]["focused"] == 15.0        # 三段 5 分钟
+
+
+# ---------------------------------------------------------------------------
+# I8 —— 一个信号只能有一条当前值，锚点因此被合并
+# ---------------------------------------------------------------------------
+
+def _anchor(kit, at, anchor_id, label):
+    kit.ingest({
+        "schema_version": 1, "report_id": f"a{anchor_id}{at.isoformat()}",
+        "producer": "ios", "observations": [{
+            "signal": "proximity_anchor", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai",
+            "value": {"anchor_id": anchor_id, "anchor_type": "wifi",
+                      "label": label, "is_connected": True},
+        }],
+    }, context=IngestContext("u", at))
+
+
+def test_two_anchors_named_home_stay_two_anchors():
+    """用户搬家，新旧网络都叫 "home"。
+
+    按名字看是同一个，按 `anchor_id` 看是两个。合并之后历史再也分不开
+    哪一段是哪个家 —— 规范 §12 专门列了这一条。
+    """
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    base = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    _anchor(kit, base, "wifi-old-home", "home")
+    _anchor(kit, base + timedelta(minutes=1), "wifi-new-home", "home")
+    current = storage.get_current(subject_id="u", signals=["proximity_anchor"]
+                                  )["proximity_anchor"]
+    assert len(current) == 2
+    assert {p.typed_value["anchor_id"] for p in current} == {
+        "wifi-old-home", "wifi-new-home"}
+
+
+def test_renaming_an_anchor_does_not_create_a_second_one():
+    """身份是 anchor_id，不是 label。改名只是改名。"""
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    base = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    _anchor(kit, base, "wifi-1", "家")
+    _anchor(kit, base + timedelta(minutes=1), "wifi-1", "老家")
+    current = storage.get_current(subject_id="u", signals=["proximity_anchor"]
+                                  )["proximity_anchor"]
+    assert len(current) == 1
+    assert current[0].typed_value["label"] == "老家"
+
+
+def test_a_signal_without_declared_dimensions_still_keeps_one_current():
+    """默认行为不能变：绝大多数信号同一时刻只有一个答案。"""
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    base = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    for i, level in enumerate((0.9, 0.8)):
+        kit.ingest({
+            "schema_version": 1, "report_id": f"b{i}", "producer": "ios",
+            "observations": [{
+                "signal": "battery", "signal_schema_version": 1,
+                "occurred_at": (base + timedelta(minutes=i)).isoformat(),
+                "availability": "observed", "timezone": "Asia/Shanghai",
+                "value": {"level_ratio": level, "is_charging": False,
+                          "is_low_power_mode_enabled": False},
+            }],
+        }, context=IngestContext("u", base + timedelta(minutes=i)))
+    current = storage.get_current(subject_id="u", signals=["battery"])["battery"]
+    assert len(current) == 1 and current[0].typed_value["level_ratio"] == 0.8
+
+
+# ---------------------------------------------------------------------------
+# I9 —— 每日照片数量按明细的保留期被扫掉
+# ---------------------------------------------------------------------------
+
+def test_the_daily_photo_count_outlives_the_individual_photos():
+    """单条明细 7 天、**每日数量永久**，是两个数。
+
+    只写明细那个，聚合会继承它 —— 于是「8月1日新增了 5 张」一周后被清掉。
+    那是一件发生过的事实，不是「现在还剩几张」。
+    """
+    sig = MINIMAL_SIGNALS["photo_library_added"]
+    assert sig.history_retention_days == 7
+    assert sig.keeps_aggregates_forever
+
+
+# ---------------------------------------------------------------------------
+# 交付清单 §15 里唯一没有测试盯着的一项：
+#   「App 缺失 close、Music 采样间断」
+#
+# 两个都是**我们和规范不同的地方**，而且不同得有理由。没有测试的话，
+# 后来的人看到「规范要求算时长，代码没算」，最可能的动作是把它补上 ——
+# 补回来的是一份大概率残缺的数字，比没有更糟。
+# ---------------------------------------------------------------------------
+
+def _app(kit, at, app, action):
+    kit.ingest({
+        "schema_version": 1, "report_id": f"{app}{action}{at.isoformat()}",
+        "producer": "ios", "observations": [{
+            "signal": "app_usage", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai",
+            "value": {"app_id": app, "app_name": app, "action": action,
+                      **({"open_count": 1} if action == "open" else {})},
+        }],
+    }, context=IngestContext("u", at))
+
+
+def test_a_missing_close_never_becomes_an_invented_duration():
+    """只配了 open 自动化的用户，绝大多数 app 根本没有结束事件。
+
+    拿有 close 的那部分算平均时长，得到的是一个只反映「谁配得全」的数字。
+    所以这个信号**刻意不建时长统计** —— 聚合里只该有靠 open 就能答准的
+    「今天打开了几次」。
+    """
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    base = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    _app(kit, base, "Slack", "open")
+    _app(kit, base + timedelta(minutes=30), "Slack", "open")   # 没有 close
+    doc = storage.get_aggregate(subject_id="u", signal="app_usage",
+                                start_date=base.date(), end_date=base.date()
+                                )[0].typed_aggregate
+    assert doc["open_count"]["total"] == 2
+    assert not any("minute" in k or "duration" in k for k in doc), \
+        "app_usage 不该出现任何时长统计——覆盖面残缺，那个数字不可信"
+
+
+def test_music_edges_are_marked_per_record_not_all_estimated():
+    """规范说「只有轮询样本就标 estimated」，实际是同一个信号两种精度并存。
+
+    Apple Music 走系统播放器、切歌 2 秒后就上报，起止是准的；Spotify、
+    网易云只能靠快照采到的点。一律标 estimated 会把本来准确的那一半丢掉。
+    """
+    field = {f.key: f for f in MINIMAL_SIGNALS["music_playback"].fields}["edge_quality"]
+    assert field.enum == ("measured", "estimated")
+    assert not field.nullable, "每条都必须表态，不能留空让读的人自己猜"
+
+
+# ---------------------------------------------------------------------------
+# I10 —— 去重身份问错了保留期：拿明细的、不是聚合的
+#
+# 这条记录单独成表的**全部理由**就是「明细会过期、聚合可能永久，所以身份必须
+# 比它守着的明细活得久」。判断条件却问的是明细永不永久 —— 于是恰好在它唯一
+# 有用的那四个信号上判成不用守。规范 §14-2 点名了这个场景。
+# ---------------------------------------------------------------------------
+
+def test_the_dedupe_identity_is_marked_by_the_aggregate_it_guards():
+    """明细 7 天、每日数量永久的照片，就是这条存在的理由。
+
+    身份先于聚合被清掉之后，一次重传把永久聚合多加一遍，**加完没法回滚** ——
+    「8月1日新增 5 张」变成 10 张，而原始明细已经不在了，没有任何东西能算回去。
+
+    这里包一层记录用的 storage，直接看管线**递给** remember_identity 的那条
+    记录 —— 内存实现只留了身份的键、把 scope 丢了，拿它验等于没验。
+    """
+    seen = []
+
+    class Recording(InMemoryStorage):
+        def remember_identity(self, identity):
+            seen.append(identity)
+            return super().remember_identity(identity)
+
+    storage = Recording()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    at = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    kit.ingest({
+        "schema_version": 1, "report_id": "p1", "producer": "ios",
+        "observations": [{
+            "signal": "photo_library_added", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai", "source_event_id": "ph-1",
+            "value": {"count": 1, "added_at": at.isoformat()},
+        }],
+    }, context=IngestContext("u", at))
+    assert [i.aggregate_scope for i in seen] == ["photo_library_added"], (
+        "明细 7 天、聚合永久 —— 身份必须标明它守着一个永久聚合，"
+        "否则保留期清理会把它当成可以删的")
+
+
+def test_every_signal_with_a_permanent_aggregate_marks_its_identity():
+    """不只照片。focus / motion / music 都是明细 1 年、聚合永久。"""
+    at_risk = [k for k, s in MINIMAL_SIGNALS.items()
+               if s.keeps_aggregates_forever and not s.keeps_history_forever]
+    assert set(at_risk) == {"focus_state", "motion_state",
+                            "music_playback", "photo_library_added"}
+
+
+# ---------------------------------------------------------------------------
+# I11 —— 「音乐停了」这个状态进不了系统
+#
+# 真机上跑出来的：老路 83 次记着 stopped，kit 那边一片空白。
+# ---------------------------------------------------------------------------
+
+def test_a_stopped_player_is_a_state_the_system_can_hold():
+    """播放器停着的时候没有曲目 —— 那是正常的，不是数据缺失。
+
+    `track_key` 非空的话，这条观测因为缺必填字段被**整条拒掉**：于是
+    「在放什么」记得住，「停了」永远记不住。而「他刚把音乐关了」恰恰是
+    这个信号最有用的那一半。
+    """
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    at = datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc)
+    outcome = kit.ingest({
+        "schema_version": 1, "report_id": "m1", "producer": "ios",
+        "observations": [{
+            "signal": "music_playback", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai",
+            "value": {"playback_state": "stopped", "edge_quality": "estimated"},
+        }],
+    }, context=IngestContext("u", at))
+    assert not outcome.rejected, list(outcome.rejected)
+    current = storage.get_current(subject_id="u", signals=["music_playback"]
+                                  )["music_playback"][0]
+    assert current.typed_value["playback_state"] == "stopped"

{perceptkit-0.2.2 → perceptkit-0.2.4}/uv.lock

@@ -43,7 +43,7 @@ wheels = [
 
 [[package]]
 name = "perceptkit"
-version = "0.2.2"
+version = "0.2.4"
 source = { editable = "." }
 
 [package.optional-dependencies]