perceptkit 0.2.5__tar.gz → 0.2.7__tar.gz

{perceptkit-0.2.5 → perceptkit-0.2.7}/CHANGELOG.md

@@ -1,5 +1,52 @@
 # 变更记录
 
+## 0.2.7 — 2026-09-02
+
+- **跳过原因带上稳定的 `code`（`SkippedSignal`）。** 0.2.6 的清理计划里，
+  跳过理由只有一句中文 —— 这个包的注释都是中文，但**宿主的运维界面不一定是**，
+  直接印进一个英文报告里就成了半中半英。一个库不该替宿主决定报告用什么语言：
+  `code` 稳定、机器可读，文案归宿主。`SkippedSignal` 仍然能按 `(signal, detail)`
+  解包，老调用方不用改。
+  （0.2.6 发出去之后接 io 时当场撞到的 —— 那份英文运维报告里蹦出中文。）
+
+## 0.2.6 — 2026-09-02
+
+外部审查那份清单里剩下的两条（P0-1 / P0-6 的可做部分）。
+
+### 新增
+
+- **`PerceptionKit.run_retention()` —— 清理终于有了统一入口（P0-1）。**
+  以前包里只有保留期表和查询函数，没有任何东西真的执行，于是每个宿主自己
+  照 manifest 推导一遍。**什么时候跑仍然是宿主的事**（这里没有调度），
+  但规则只该有一份 —— 这条路上每个坑错了都不报错：明细和聚合是两个保留期、
+  PERMANENT 要跳过、没声明的不许猜一个、去重身份不能跟着明细删。
+  默认 `dry_run=True`：这是包里唯一会永久删用户数据的动作。
+- **`StoragePort.delete_aggregates()`。** 端口原来只有明细的删除口，
+  日聚合根本删不掉 —— 宿主要么自己写 SQL，要么干脆不清，而
+  「有限保留期的聚合永远不删」不会报错，只会让库一直长。
+
+### 修复
+
+- **修订过的那天，重算会把错值和改正值一起折进去（P0-6 的一半）。**
+  `source_revision` 原来**只**用在当前值上，历史和聚合完全没读它：
+  心率 90（revision 1）被改成 60（revision 2），重算那天折出来是 75 ——
+  一个从来没发生过的数字。而这个错只有重算时才现形，当前值那条路是对的，
+  所以"改完之后当前显示对了"会让人以为整条链路都对了。
+  修订号按数字比不按字符串比（否则 `"10" < "9"`，第 10 版被第 9 版盖掉）。
+  **一组观测全都没有修订号时一条都不合并** —— 那等于替它们编一个
+  "后来的覆盖先来的"顺序，而那恰好不是 `cumulative` 现在的规则（它取 max）。
+
+### 已知未做
+
+- **来源侧删除没有 tombstone 契约。** 修订带着 `availability` 一起来时，
+  上面那条已经能把事实从当天移掉；但 HealthKit 真正的删除走的是
+  `deletedObjects`，那是一条完全没接的路。
+- **`cumulative` 取 max，分不清「迟到的旧数据」和「向下的修正」。**
+  用户删掉一次运动、当日活动能量从 500 降到 300 —— 当前值会跟着降，
+  日聚合停在 500，同一天同一个指标两个数。改成"最新的赢"能修这个，
+  但会让来源侧的一次归零（比如重装后当日步数从头算）把那天清掉。
+  两种规则各有一个失败模式，要产品拍板，不从代码里溜进去。
+
 ## 0.2.5 — 2026-09-02
 
 **外部审查（2026-09-02）逐条核出来的。** 四条里三条是"查询静默给错答案"，

{perceptkit-0.2.5 → perceptkit-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: perceptkit
-Version: 0.2.5
+Version: 0.2.7
 Summary: 从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不选数据库、不调模型 —— 存储由宿主实现 StoragePort，编排在包内。
 License: 
                                          Apache License

{perceptkit-0.2.5 → perceptkit-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "perceptkit"
-version = "0.2.5"
+version = "0.2.7"
 description = "从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不选数据库、不调模型 —— 存储由宿主实现 StoragePort，编排在包内。"
 readme = "README.md"
 requires-python = ">=3.10"

{perceptkit-0.2.5 → perceptkit-0.2.7}/src/perceptkit/conformance/memory.py

@@ -164,6 +164,14 @@ class InMemoryStorage:
 
     # -- 聚合 ------------------------------------------------------------
 
+    def delete_aggregates(self, *, subject_id, signal, before) -> int:
+        doomed = [k for k, v in self.aggregates.items()
+                  if v.subject_id == subject_id and v.signal == signal
+                  and v.local_date < before]
+        for k in doomed:
+            del self.aggregates[k]
+        return len(doomed)
+
     def get_aggregate(self, *, subject_id, signal, start_date, end_date,
                       aggregation_kind=None):
         return [

{perceptkit-0.2.5 → perceptkit-0.2.7}/src/perceptkit/kit.py

@@ -14,7 +14,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from datetime import date, datetime
+from datetime import date, datetime, time, timezone
 from typing import Any, Callable, Mapping, Sequence
 
 from .contracts.context import IngestContext
@@ -26,6 +26,7 @@ from .ports.wake import WakePort
 from .processing.dispatch import DispatchOutcome, drain
 from .processing.pipeline import AGGREGATION_VERSION, IngestOutcome, ingest_report
 from .processing.recompute import RecomputeOutcome, recompute_range
+from .retention import plan_retention
 from .processing.scheduled import ScheduledOutcome, evaluate_absence, evaluate_daily
 from .queries import api as _queries
 from .rules.types import EventDefinition
@@ -142,6 +143,58 @@ class PerceptionKit:
             now=now, allow_incomplete=allow_incomplete,
         )
 
+    def run_retention(
+        self, *, subject_id: str, now: datetime, dry_run: bool = True,
+    ) -> dict[str, Any]:
+        """按 manifest 清理过期数据。**默认只试跑。**
+
+        规则在 ``retention.plan_retention``（纯函数），删除走存储端口 ——
+        **什么时候跑仍然是宿主的事**，这里没有任何调度。给这个入口是因为
+        规则只该有一份：早先 kit 只声明保留期、不提供执行，于是每个宿主
+        自己照 manifest 推导一遍，而这条路上每个坑错了都不报错
+        （明细和聚合是两个保留期、PERMANENT 要跳过、没声明的不许猜、
+        去重身份不能跟着明细删）。
+
+        ``dry_run=True`` 是默认值，不是谨慎癖：这是这个包里**唯一**会永久
+        删用户数据的动作，而保留期的 bug 从外面完全看不见 —— 系统照常工作，
+        用户只是安静地少了历史，直到有人问一个数据已经答不出的问题。
+        先看一眼数字，再决定要不要真删。
+
+        按 subject 清，和这个端口所有其他方法一样。宿主要全量清就自己循环 ——
+        跨用户的一条 DELETE 少写一个 WHERE 就会删掉别人的数据，
+        而这个包里没有一个地方允许那种写法存在。
+        """
+        plan = plan_retention(self.signals, now=now)
+        removed: dict[str, int] = {}
+        if not dry_run:
+            for action in plan.actions:
+                if action.kind == "observations":
+                    n = self.storage.delete_observations(
+                        subject_id=subject_id, signal=action.signal,
+                        before=datetime.combine(action.before, time.min,
+                                                tzinfo=timezone.utc),
+                    )
+                else:
+                    n = self.storage.delete_aggregates(
+                        subject_id=subject_id, signal=action.signal,
+                        before=action.before,
+                    )
+                if n:
+                    removed[f"{action.signal}.{action.kind}"] = (
+                        removed.get(f"{action.signal}.{action.kind}", 0) + int(n))
+        return {
+            "applied": not dry_run,
+            "planned": [
+                {"signal": a.signal, "kind": a.kind, "before": a.before.isoformat()}
+                for a in plan.actions
+            ],
+            # 故意不删的也要列出来 —— 一份只说"删了 0 条"的报告，读不出
+            # 「是没到期，还是规则写错了」。
+            "skipped": [{"signal": s.signal, "code": s.code, "detail": s.detail}
+                        for s in plan.skipped],
+            "removed": removed,
+        }
+
     def evaluate_absence(
         self, *, subject_id: str, now: datetime,
     ) -> ScheduledOutcome:

{perceptkit-0.2.5 → perceptkit-0.2.7}/src/perceptkit/ports/storage.py

@@ -125,6 +125,21 @@ class StoragePort(Protocol):
 
     # -- 聚合 ------------------------------------------------------------
 
+    def delete_aggregates(
+        self, *, subject_id: str, signal: str, before: date,
+    ) -> int:
+        """按**聚合的**保留期清理日聚合，返回删了多少条。
+
+        和 :meth:`delete_observations` 是两个动作，因为是两个保留期：典型形态
+        就是「明细 1 年、聚合永久」。没有这个方法的话，宿主要么自己写 SQL
+        （于是每个宿主各自重新推导一遍规则），要么干脆不清 —— 而
+        「有限保留期的聚合永远不删」不会报错，只会让库一直长。
+
+        🔴 **``aggregate_retention_days`` 是 PERMANENT 的信号绝不能进来。**
+        判定在 kit 里（``run_retention``），不指望每个宿主自己记得。
+        """
+        ...
+
     def get_aggregate(
         self, *, subject_id: str, signal: str,
         start_date: date, end_date: date,

{perceptkit-0.2.5 → perceptkit-0.2.7}/src/perceptkit/processing/recompute.py

@@ -63,6 +63,60 @@ def details_may_be_incomplete(
     return day < cutoff
 
 
+def _revision_key(raw: object) -> tuple[int, str]:
+    """修订号的比较键。数字按数字比，其余按字符串比，两者不混。
+
+    ``"10"`` 和 ``10`` 是不同的东西：全按字符串比的话 ``"10" < "9"``，
+    第 10 版会被第 9 版盖掉。所以数字排一档、字符串排另一档，
+    并且**数字档永远小于字符串档**——不给两个不可比的值编一个假的顺序。
+    """
+    if raw is None:
+        return (0, "")
+    text = str(raw)
+    try:
+        return (1, f"{int(text):020d}")
+    except ValueError:
+        return (2, text)
+
+
+def _canonical(rows: list, sig: SignalDefinition) -> list:
+    """同一件源事实的多个修订，只留最新那一版。
+
+    ``source_revision`` 原来只用在当前值上（高版本替换低版本），**历史和聚合
+    完全没用它**。于是修订过的那天会同时折进错值和改正值：
+
+        体重 70.5kg（revision 1）→ 用户在健康 app 里改成 68.5（revision 2）
+        重算那天 → 两条都在 → 平均值 69.5，一个从来没发生过的数字
+
+    而且这个错**只有重算时才现形**：当前值那条路是对的，所以"改过之后当前
+    显示对了"会让人以为整条链路都对了。
+
+    只对按 ``source_event_id`` 定身份的信号生效 —— 别的信号一条观测就是
+    一件独立的事，本来就不该合并。
+    """
+    if sig.identity_strategy != "source_event_id":
+        return rows
+    groups: dict[str, list] = {}
+    for o in rows:
+        if o.source_event_id is not None:       # 没有源身份的，各算各的
+            groups.setdefault(o.source_event_id, []).append(o)
+
+    winners = set()
+    for key, members in groups.items():
+        # **一组里全都没有修订号 = 没有"哪版更新"的信息，一条都不合并。**
+        # 合并的话就等于替这些观测编一个"后来的覆盖先来的"的顺序，而那正好
+        # 是 `cumulative` 现在**不**采用的规则（它取 max）—— 重算和增量折叠
+        # 会给出两个不同的数，同一份数据看你从哪条路读。
+        # 修订语义该不该改成"最新的赢"是另一件事，得先定，不能从这里溜进去。
+        if all(o.source_revision is None for o in members):
+            winners.update(id(o) for o in members)
+            continue
+        best = max(members, key=lambda o: (_revision_key(o.source_revision),
+                                           o.occurred_at, o.observation_id))
+        winners.add(id(best))
+    return [o for o in rows if o.source_event_id is None or id(o) in winners]
+
+
 def recompute_day(
     storage: StoragePort,
     sig: SignalDefinition,
@@ -87,8 +141,9 @@ def recompute_day(
         )
         page.extend(more)
 
-    same_day = [o for o in page
-                if o.effective_local_date == day and o.availability == "observed"]
+    same_day = [o for o in page if o.effective_local_date == day]
+    same_day = _canonical(same_day, sig)
+    same_day = [o for o in same_day if o.availability == "observed"]
     same_day.sort(key=lambda o: (o.occurred_at, o.observation_id))
 
     doc: dict = {}

perceptkit-0.2.7/src/perceptkit/retention.py

@@ -0,0 +1,194 @@
+"""保留期（存多久才删）与保质期（多久之后不再采信）。
+
+★ **接定时器仍然是宿主的事**，这里没有任何调度。但「删什么、留什么、
+  为什么跳过」是**规则**，规则只该有一份 —— 早先这里连规则都不给，
+  于是每个宿主自己照 manifest 重新推导一遍，而这条路上的每个坑
+  （两个保留期要分开、永久的要跳过、去重身份不能跟着明细删）
+  错了都不报错，只是安静地少数据或多数据。
+  ``plan_retention`` 给规则，``PerceptionKit.run_retention`` 走端口执行。
+
+★ 保留期的判据：这条数据在 N 个月后，还会改变 agent 对这个人的理解吗。
+
+★ 保质期这一块只列「改判测量时间之后需要改的」。改判之前它判的是
+  「距这次上报多久」，改判之后判「这条数据多久前测的」—— 沿用旧值会把功能
+  杀死：体重 24 小时 = 除非今天刚称过否则永远 null。
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from dataclasses import dataclass, field as _field
+from typing import TYPE_CHECKING, Mapping as _Mapping
+
+from .manifest.types import PERMANENT
+
+if TYPE_CHECKING:                       # 仅为类型标注，运行时不引入依赖
+    from .manifest.types import SignalDefinition
+
+KEEP_FOREVER = None
+
+_DAY = 86400.0
+
+# signal -> 保留天数；None = 永久；不在表里 = 不进历史表
+RETENTION_DAYS: dict[str, int | None] = {
+    # 永久：趋势本身就是价值
+    "health_body": KEEP_FOREVER,
+    "health_sleep": KEEP_FOREVER,
+    "health_vitals": KEEP_FOREVER,
+    "health_activity": KEEP_FOREVER,
+    "health_workout": KEEP_FOREVER,
+    "health_metabolic": KEEP_FOREVER,
+    "health_mood": KEEP_FOREVER,
+    "health_cycle": KEEP_FOREVER,
+    "location_signal": KEEP_FOREVER,
+    # 一年：年度口味有价值，再久没人问
+    "playback": 365,
+    # 90 天：瞬时状态，回看价值掉得快
+    "motion_state": 90,
+    "focus": 90,
+    "audio_route": 90,
+    # weather 现在的 SHAPE 是 NUMERIC_DIST（history.py），仍在产生 rollup，
+    # 所以现在必须有真实保留期 —— 跟瞬时状态同档。
+    # ⚠️ Codex code_review 2026-08-23 抓到：早先按"weather 即将改成仅当前+预报、
+    # 不再存历史"的未来态把这条声明成了 KEEP_FOREVER 之外/None，
+    # 但 SHAPE/history.record_daily 从未真的改过去，导致四张声明表互相矛盾。
+    # 真要把 weather 改成不存历史时，这一行、attribution.ATTRIBUTION 里的
+    # weather 条目、history.SHAPE 里的 weather 条目，三处必须在同一批一起删，
+    # 不许只删一处。
+    "weather": 90,
+    # 60 天：采集窗口是前后 14 天，够覆盖「未来的会 → 过去的会 → 再留一个月回看」
+    "calendar_next_event": 60,
+    "reminders": 60,
+}
+
+# 改判「测量时间」之后的保质期。只列与 catalog 现值不同的；
+# 「现在测现在传」的信号（位置/运动/专注/音频/播放）不需要改。
+MEASURED_AT_TTL_SEC: dict[str, float] = {
+    "health_body": 90 * _DAY,        # 三个月内称过就还算数
+    "health_metabolic": 30 * _DAY,   # 一个月内测过就还算数
+    "health_cycle": 60 * _DAY,       # 两个月内有记录就还算数
+    "health_vitals": 7 * _DAY,       # 一周内测过就还算数
+}
+
+
+# ⚠️ 「永久保存」不等于「不可删除」（Codex 评审修订 K）。
+#    以下生命周期动作必须由消费方实现，本表只是保留期，不是删除策略的全部：
+#      · 账号删除时清空
+#      · 用户主动清空
+#      · 健康权限关闭后：禁用读取与 wake（不是继续用存量）
+#      · 第三方撤权
+#      · 来源侧删除 / 纠正如何传播到我们的汇总
+#    本模块不实现这些 —— 它零 I/O。放在这里是为了让读到保留期的人
+#    不会把「永久」误解成「不可删」。
+LIFECYCLE_NOTE = "retention != undeletable; see design doc 修订 K"
+
+
+@dataclass(frozen=True)
+class RetentionAction:
+    """一个信号、一类数据、一条截止线。"""
+
+    signal: str
+    #: ``"observations"`` 或 ``"aggregates"``。
+    kind: str
+    #: 早于这个时间点的删掉。
+    before: _dt.date
+
+
+@dataclass(frozen=True)
+class SkippedSignal:
+    """故意不清的一个信号，以及为什么。
+
+    ``code`` 是稳定的机器可读标识，``detail`` 是给人看的一句话。
+    **宿主的运维界面该用 code 自己渲染** —— 一个库不该替宿主决定报告用什么
+    语言。这里的 detail 是中文（这个包的注释都是中文），直接印进一个英文
+    运维报告里就成了半中半英。
+    """
+
+    signal: str
+    code: str
+    detail: str
+
+    def __iter__(self):
+        """还能按 ``(signal, detail)` 解包 —— 老调用方不用一次全改。"""
+        return iter((self.signal, self.detail))
+
+
+#: 稳定的跳过原因。宿主按这个渲染自己的文案。
+SKIP_NO_HISTORY = "no_history"
+SKIP_DETAILS_PERMANENT = "details_permanent"
+SKIP_DETAILS_UNDECLARED = "details_undeclared"
+SKIP_AGGREGATES_PERMANENT = "aggregates_permanent"
+SKIP_AGGREGATES_UNDECLARED = "aggregates_undeclared"
+
+
+@dataclass
+class RetentionPlan:
+    """要删什么，以及**故意不删什么、为什么**。
+
+    跳过的理由必须列出来 —— 一份只说"删了 0 条"的报告，和一份说
+    "这些信号是永久保存的所以跳过"的报告，看起来一样，但前者读不出
+    「是没到期，还是规则写错了」。
+    """
+
+    actions: list[RetentionAction] = _field(default_factory=list)
+    skipped: list[SkippedSignal] = _field(default_factory=list)
+
+
+def plan_retention(
+    signals: _Mapping[str, "SignalDefinition"], *, now: _dt.datetime,
+) -> RetentionPlan:
+    """按 manifest 算出这一轮该删什么。**纯函数，零 I/O，不读时钟。**
+
+    规则一共四条，每条都对应一个"错了不报错"的坑：
+
+        明细和聚合是**两个**保留期   典型形态是「明细 1 年、聚合永久」。
+                                     不分开写就会继承明细的天数，于是
+                                     「8月1日新增了 5 张照片」一年后被扫掉，
+                                     而那是一件发生过的事实。
+        PERMANENT 的一律跳过         判定放这里，不指望每个宿主记得。
+        没声明保留期的**跳过，不默认** 猜一个数字就是拿真实数据去赌。
+        去重身份**不在这里删**       明细没了之后，它是「重放的上报会不会
+                                     把永久聚合数两遍」之间唯一的东西，
+                                     而那个错是不可逆的。
+    """
+    plan = RetentionPlan()
+    for key in sorted(signals):
+        sig = signals[key]
+        if not sig.stores_history:
+            plan.skipped.append(SkippedSignal(key, SKIP_NO_HISTORY, "不进历史表，没东西可清"))
+            continue
+
+        if sig.history_retention_days == PERMANENT:
+            plan.skipped.append(SkippedSignal(key, SKIP_DETAILS_PERMANENT, "明细永久保存"))
+        elif sig.history_retention_days is None:
+            plan.skipped.append(SkippedSignal(key, SKIP_DETAILS_UNDECLARED, "没声明明细保留期 —— 跳过，不替它猜一个"))
+        else:
+            plan.actions.append(RetentionAction(
+                key, "observations",
+                (now - _dt.timedelta(days=sig.history_retention_days)).date()))
+
+        agg_days = sig.effective_aggregate_retention_days
+        if agg_days == PERMANENT:
+            plan.skipped.append(SkippedSignal(key, SKIP_AGGREGATES_PERMANENT, "日聚合永久保存"))
+        elif agg_days is None:
+            plan.skipped.append(SkippedSignal(key, SKIP_AGGREGATES_UNDECLARED, "没声明聚合保留期 —— 跳过，不替它猜一个"))
+        else:
+            plan.actions.append(RetentionAction(
+                key, "aggregates",
+                (now - _dt.timedelta(days=agg_days)).date()))
+    return plan
+
+
+def stores_history(signal: str) -> bool:
+    """这个信号进不进历史表。"""
+    return signal in RETENTION_DAYS
+
+
+def retention_days(signal: str) -> int | None:
+    """保留天数；``KEEP_FOREVER``（None）表示永久。
+
+    不进历史表的信号调用这个是调用方的错，直接抛 —— 静默返回 None 会被
+    误当成「永久」，那是最坏的一种默认值。
+    """
+    if signal not in RETENTION_DAYS:
+        raise KeyError(f"signal {signal!r} 不进历史表，先用 stores_history() 判断")
+    return RETENTION_DAYS[signal]

perceptkit-0.2.7/tests/test_retention_entry.py

@@ -0,0 +1,178 @@
+"""统一的清理入口 —— 规则只有一份。
+
+外部审查（2026-09-02，P0-1）："Retention 现在是声明，不是完整执行链路"。
+成立：包里只有保留期表和查询函数，没有任何东西真的执行；于是每个宿主自己
+照 manifest 推导一遍。io 那边写了一百多行 —— 下一个宿主还得再写一遍，
+而这条路上的每个坑**错了都不报错**：
+
+    明细和聚合当成一个保留期   「8月1日新增了 5 张照片」一年后被扫掉
+    忘了跳过 PERMANENT        永久聚合被删，且不可逆
+    没声明保留期就默认一个     拿真实数据去赌一个猜出来的天数
+    去重身份跟着明细一起删     重放的上报把永久聚合数两遍，无法回滚
+
+所以这个文件测的是**规则**，不是"函数能跑"。
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+
+import pytest
+
+from perceptkit import IngestContext, PerceptionKit
+from perceptkit.conformance import InMemoryStorage
+from perceptkit.manifest import MINIMAL_SIGNALS
+from perceptkit.manifest.types import PERMANENT
+from perceptkit.retention import plan_retention
+
+NOW = datetime(2026, 9, 2, 12, 0, tzinfo=timezone.utc)
+
+
+def _plan():
+    return plan_retention(MINIMAL_SIGNALS, now=NOW)
+
+
+def test_details_and_aggregates_get_their_own_cutoffs():
+    """两个保留期是两条截止线，不是一条。
+
+    典型形态是「明细短、聚合永久」——合成一条的话，要么把该留的永久聚合
+    删了，要么把该清的明细一直留着。
+    """
+    plan = _plan()
+    photo = [a for a in plan.actions if a.signal == "photo_library_added"]
+    # 明细 7 天要清，聚合永久不许出现在动作里。
+    assert [a.kind for a in photo] == ["observations"]
+    assert photo[0].before == (NOW - timedelta(days=7)).date()
+    assert any(sk.signal == "photo_library_added"
+               and sk.code == "aggregates_permanent" for sk in plan.skipped)
+
+
+def test_permanent_never_appears_as_something_to_delete():
+    plan = _plan()
+    doomed = {(a.signal, a.kind) for a in plan.actions}
+    for key, sig in MINIMAL_SIGNALS.items():
+        if sig.history_retention_days == PERMANENT:
+            assert (key, "observations") not in doomed, f"{key} 的明细是永久的"
+        if sig.effective_aggregate_retention_days == PERMANENT:
+            assert (key, "aggregates") not in doomed, f"{key} 的聚合是永久的"
+
+
+def test_a_signal_with_no_declared_retention_is_skipped_not_defaulted():
+    """没声明就跳过。默认一个天数 = 拿真实数据赌一个猜出来的数字。"""
+    from dataclasses import replace
+    sig = replace(MINIMAL_SIGNALS["audio_route"],
+                  history_retention_days=None, aggregate_retention_days=None)
+    plan = plan_retention({"audio_route": sig}, now=NOW)
+    assert plan.actions == []
+    assert all(sk.code.endswith("undeclared") for sk in plan.skipped)
+
+
+def test_the_plan_says_why_it_skipped_things():
+    """只说"删了 0 条"的报告，读不出「是没到期，还是规则写错了」。"""
+    plan = _plan()
+    assert plan.skipped
+    assert all(sk.detail.strip() for sk in plan.skipped)
+
+
+def test_skip_reasons_carry_a_stable_code_for_the_host_to_render():
+    """理由的**文字**是中文（这个包的注释都是中文）。宿主的运维界面不一定是。
+
+    直接把 detail 印进一个英文报告里就成了半中半英 —— 一个库不该替宿主
+    决定报告用什么语言。code 是稳定的，文案归宿主。
+    """
+    from perceptkit.retention import (
+        SKIP_AGGREGATES_PERMANENT, SKIP_DETAILS_PERMANENT, SKIP_NO_HISTORY,
+        SKIP_DETAILS_UNDECLARED, SKIP_AGGREGATES_UNDECLARED,
+    )
+    known = {SKIP_NO_HISTORY, SKIP_DETAILS_PERMANENT, SKIP_DETAILS_UNDECLARED,
+             SKIP_AGGREGATES_PERMANENT, SKIP_AGGREGATES_UNDECLARED}
+    plan = _plan()
+    assert {sk.code for sk in plan.skipped} <= known
+    assert all(sk.code for sk in plan.skipped)
+
+
+def test_a_dry_run_removes_nothing():
+    """这是包里唯一会永久删用户数据的动作。默认不删。"""
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    at = NOW - timedelta(days=400)
+    kit.ingest({
+        "schema_version": 1, "report_id": "r1", "producer": "ios",
+        "observations": [{
+            "signal": "audio_route", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai",
+            "value": {"output_type": "bluetooth_a2dp", "is_bluetooth": True},
+        }],
+    }, context=IngestContext("u", at))
+    before = len(storage.observations)
+    assert before
+
+    out = kit.run_retention(subject_id="u", now=NOW)          # 默认 dry_run
+    assert out["applied"] is False and out["removed"] == {}
+    assert len(storage.observations) == before, "试跑不该删任何东西"
+
+    out = kit.run_retention(subject_id="u", now=NOW, dry_run=False)
+    assert out["applied"] is True and out["removed"]
+    assert len(storage.observations) < before
+
+
+def test_the_sweep_does_not_touch_dedupe_identities():
+    """明细没了之后，去重身份是「重放的上报会不会把永久聚合数两遍」
+    之间唯一的东西 —— 而那个错不可逆。"""
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    at = NOW - timedelta(days=400)
+    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": "asset-1",
+            "value": {"count": 1, "added_at": at.isoformat()},
+        }],
+    }, context=IngestContext("u", at))
+    identities = set(storage.identities)
+    assert identities
+
+    kit.run_retention(subject_id="u", now=NOW, dry_run=False)
+    assert set(storage.identities) == identities, "去重身份被清理带走了"
+
+    # 明细被清掉之后重放同一条上报：永久新增数**不能**变成 2。
+    def daily():
+        rows = storage.get_aggregate(subject_id="u", signal="photo_library_added",
+                                     start_date=at.date(), end_date=at.date())
+        return rows[0].typed_aggregate["count"]["total"] if rows else 0
+    was = daily()
+    kit.ingest({
+        "schema_version": 1, "report_id": "p1-replay", "producer": "ios",
+        "observations": [{
+            "signal": "photo_library_added", "signal_schema_version": 1,
+            "occurred_at": at.isoformat(), "availability": "observed",
+            "timezone": "Asia/Shanghai", "source_event_id": "asset-1",
+            "value": {"count": 1, "added_at": at.isoformat()},
+        }],
+    }, context=IngestContext("u", NOW))
+    assert daily() == was, "清理之后重放把永久聚合数了两遍"
+
+
+def test_the_sweep_stays_inside_one_subject():
+    """跨用户的一条 DELETE 少写一个 WHERE 就会删掉别人的数据。"""
+    storage = InMemoryStorage()
+    kit = PerceptionKit(storage=storage, signals=MINIMAL_SIGNALS)
+    at = NOW - timedelta(days=400)
+    for who in ("u1", "u2"):
+        kit.ingest({
+            "schema_version": 1, "report_id": f"r-{who}", "producer": "ios",
+            "observations": [{
+                "signal": "audio_route", "signal_schema_version": 1,
+                "occurred_at": at.isoformat(), "availability": "observed",
+                "timezone": "Asia/Shanghai",
+                "value": {"output_type": "bluetooth_a2dp", "is_bluetooth": True},
+            }],
+        }, context=IngestContext(who, at))
+    others = [o for o in storage.observations.values() if o.subject_id == "u2"]
+    assert others
+
+    kit.run_retention(subject_id="u1", now=NOW, dry_run=False)
+    still = [o for o in storage.observations.values() if o.subject_id == "u2"]
+    assert len(still) == len(others), "清 u1 把 u2 的数据也删了"

perceptkit-0.2.7/tests/test_revision_recompute.py

@@ -0,0 +1,103 @@
+"""修订过的那天，重算不能把错值和改正值一起折进去。
+
+外部审查（2026-09-02，P0-6）："当前 source_revision 可以帮助较高 revision
+替换 Current，但不足以正确处理历史和聚合"。核下来成立：``source_revision``
+原来**只**用在当前值上，历史和聚合完全没读它。于是
+
+    体重 70.5kg（revision 1）→ 用户在健康 app 里改成 68.5（revision 2）
+    两条都在明细里 → 重算那天 → 69.5，一个从来没发生过的数字
+
+而且这个错**只有重算时才现形**：当前值那条路是对的，所以"改完之后当前显示
+对了"会让人以为整条链路都对了。
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+
+import pytest
+
+from perceptkit.contracts.records import StoredObservation
+from perceptkit.conformance import InMemoryStorage
+from perceptkit.manifest import MINIMAL_SIGNALS
+from perceptkit.processing.recompute import recompute_day
+
+DAY = date(2026, 9, 2)
+T = datetime(2026, 9, 2, 9, 0, tzinfo=timezone.utc)
+
+
+def _obs(storage, oid, *, value, event_id, revision=None, minutes=0,
+         availability="observed"):
+    storage.append_observation(StoredObservation(
+        subject_id="u", observation_id=oid, signal="health_vitals",
+        signal_schema_version=1, source="ios",
+        occurred_at=T + timedelta(minutes=minutes), received_at=T,
+        availability=availability, effective_local_date=DAY,
+        typed_value=value, timezone="Asia/Shanghai",
+        source_event_id=event_id, source_revision=revision, created_at=T,
+    ))
+
+
+def _rhr(storage):
+    agg = recompute_day(storage, MINIMAL_SIGNALS["health_vitals"],
+                        subject_id="u", day=DAY, version=1, updated_at=T)
+    return (agg.typed_aggregate.get("resting_heart_rate"),
+            agg.source_coverage["observations"])
+
+
+def test_a_corrected_sample_replaces_the_wrong_one_instead_of_averaging_with_it():
+    s = InMemoryStorage()
+    _obs(s, "o1", value={"resting_heart_rate": 90}, event_id="hk-sample-A", revision=1)
+    _obs(s, "o2", value={"resting_heart_rate": 60}, event_id="hk-sample-A", revision=2,
+         minutes=5)
+    stats, n = _rhr(s)
+    assert n == 1, "错值和改正值被一起折进去了"
+    assert stats["min"] == stats["max"] == 60, (
+        f"折出来是 {stats} —— 90 和 60 一起折成了平均值 75，一个从来没发生过的心率")
+
+
+def test_revisions_are_compared_as_numbers_not_as_text():
+    """全按字符串比的话 "10" < "9"，第 10 版会被第 9 版盖掉。"""
+    s = InMemoryStorage()
+    _obs(s, "o1", value={"resting_heart_rate": 90}, event_id="hk-A", revision=9)
+    _obs(s, "o2", value={"resting_heart_rate": 60}, event_id="hk-A", revision=10,
+         minutes=5)
+    stats, n = _rhr(s)
+    assert n == 1 and stats["max"] == 60
+
+
+def test_different_source_facts_are_never_merged():
+    """两个不同的样本是两件事，不是一件事的两个版本。"""
+    s = InMemoryStorage()
+    _obs(s, "o1", value={"resting_heart_rate": 70}, event_id="hk-A", revision=1)
+    _obs(s, "o2", value={"resting_heart_rate": 80}, event_id="hk-B", revision=1,
+         minutes=5)
+    _, n = _rhr(s)
+    assert n == 2
+
+
+def test_a_group_with_no_revisions_at_all_is_left_alone():
+    """没有修订号 = 没有「哪版更新」的信息。
+
+    这时候合并就等于替这些观测编一个"后来的覆盖先来的"顺序 —— 而那恰好
+    **不是** cumulative 现在采用的规则（它取 max）。编了的话，同一份数据
+    重算和增量折叠会给出两个不同的数。
+    """
+    s = InMemoryStorage()
+    _obs(s, "o1", value={"resting_heart_rate": 70}, event_id="hk-A")
+    _obs(s, "o2", value={"resting_heart_rate": 80}, event_id="hk-A", minutes=5)
+    _, n = _rhr(s)
+    assert n == 2
+
+
+def test_a_revision_marked_unavailable_removes_the_fact_from_the_day():
+    """来源侧撤回：最高修订说"读不到了"，那天就不该再有这条事实。
+
+    ⚠️ 这条只覆盖「修订带着 availability 一起来」的形态。iOS 真正的删除走的是
+    HealthKit 的 deletedObjects，**现在根本没接**，见 P0-6 的交付说明。
+    """
+    s = InMemoryStorage()
+    _obs(s, "o1", value={"resting_heart_rate": 90}, event_id="hk-A", revision=1)
+    _obs(s, "o2", value=None, event_id="hk-A", revision=2, minutes=5,
+         availability="unavailable")
+    _, n = _rhr(s)
+    assert n == 0

{perceptkit-0.2.5 → perceptkit-0.2.7}/uv.lock

@@ -16,7 +16,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -43,7 +43,7 @@ wheels = [
 
 [[package]]
 name = "perceptkit"
-version = "0.2.5"
+version = "0.2.7"
 source = { editable = "." }
 
 [package.optional-dependencies]

perceptkit-0.2.5/src/perceptkit/retention.py

@@ -1,84 +0,0 @@
-"""保留期（存多久才删）与保质期（多久之后不再采信）的声明表。
-
-★ 本模块只声明，不含任何删除逻辑 —— 真正的清理任务要接定时器，属于消费方。
-
-★ 保留期的判据：这条数据在 N 个月后，还会改变 agent 对这个人的理解吗。
-
-★ 保质期这一块只列「改判测量时间之后需要改的」。改判之前它判的是
-  「距这次上报多久」，改判之后判「这条数据多久前测的」—— 沿用旧值会把功能
-  杀死：体重 24 小时 = 除非今天刚称过否则永远 null。
-"""
-from __future__ import annotations
-
-KEEP_FOREVER = None
-
-_DAY = 86400.0
-
-# signal -> 保留天数；None = 永久；不在表里 = 不进历史表
-RETENTION_DAYS: dict[str, int | None] = {
-    # 永久：趋势本身就是价值
-    "health_body": KEEP_FOREVER,
-    "health_sleep": KEEP_FOREVER,
-    "health_vitals": KEEP_FOREVER,
-    "health_activity": KEEP_FOREVER,
-    "health_workout": KEEP_FOREVER,
-    "health_metabolic": KEEP_FOREVER,
-    "health_mood": KEEP_FOREVER,
-    "health_cycle": KEEP_FOREVER,
-    "location_signal": KEEP_FOREVER,
-    # 一年：年度口味有价值，再久没人问
-    "playback": 365,
-    # 90 天：瞬时状态，回看价值掉得快
-    "motion_state": 90,
-    "focus": 90,
-    "audio_route": 90,
-    # weather 现在的 SHAPE 是 NUMERIC_DIST（history.py），仍在产生 rollup，
-    # 所以现在必须有真实保留期 —— 跟瞬时状态同档。
-    # ⚠️ Codex code_review 2026-08-23 抓到：早先按"weather 即将改成仅当前+预报、
-    # 不再存历史"的未来态把这条声明成了 KEEP_FOREVER 之外/None，
-    # 但 SHAPE/history.record_daily 从未真的改过去，导致四张声明表互相矛盾。
-    # 真要把 weather 改成不存历史时，这一行、attribution.ATTRIBUTION 里的
-    # weather 条目、history.SHAPE 里的 weather 条目，三处必须在同一批一起删，
-    # 不许只删一处。
-    "weather": 90,
-    # 60 天：采集窗口是前后 14 天，够覆盖「未来的会 → 过去的会 → 再留一个月回看」
-    "calendar_next_event": 60,
-    "reminders": 60,
-}
-
-# 改判「测量时间」之后的保质期。只列与 catalog 现值不同的；
-# 「现在测现在传」的信号（位置/运动/专注/音频/播放）不需要改。
-MEASURED_AT_TTL_SEC: dict[str, float] = {
-    "health_body": 90 * _DAY,        # 三个月内称过就还算数
-    "health_metabolic": 30 * _DAY,   # 一个月内测过就还算数
-    "health_cycle": 60 * _DAY,       # 两个月内有记录就还算数
-    "health_vitals": 7 * _DAY,       # 一周内测过就还算数
-}
-
-
-# ⚠️ 「永久保存」不等于「不可删除」（Codex 评审修订 K）。
-#    以下生命周期动作必须由消费方实现，本表只是保留期，不是删除策略的全部：
-#      · 账号删除时清空
-#      · 用户主动清空
-#      · 健康权限关闭后：禁用读取与 wake（不是继续用存量）
-#      · 第三方撤权
-#      · 来源侧删除 / 纠正如何传播到我们的汇总
-#    本模块不实现这些 —— 它零 I/O。放在这里是为了让读到保留期的人
-#    不会把「永久」误解成「不可删」。
-LIFECYCLE_NOTE = "retention != undeletable; see design doc 修订 K"
-
-
-def stores_history(signal: str) -> bool:
-    """这个信号进不进历史表。"""
-    return signal in RETENTION_DAYS
-
-
-def retention_days(signal: str) -> int | None:
-    """保留天数；``KEEP_FOREVER``（None）表示永久。
-
-    不进历史表的信号调用这个是调用方的错，直接抛 —— 静默返回 None 会被
-    误当成「永久」，那是最坏的一种默认值。
-    """
-    if signal not in RETENTION_DAYS:
-        raise KeyError(f"signal {signal!r} 不进历史表，先用 stores_history() 判断")
-    return RETENTION_DAYS[signal]