perceptkit 0.2.4__tar.gz → 0.2.6__tar.gz

perceptkit-0.2.6/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+# 每次推送都跑，跨所有**声明支持**的 Python 版本。
+#
+# 为什么要矩阵：这个包声明 requires-python >=3.10，而在此之前只有发版那条
+# workflow 会跑测试，且只跑 3.12。结果是 3.10 上「两位小数秒的时间戳整条被拒」
+# 这个 bug 活到了外部审查才被发现 —— 声明支持一个版本却从不在上面跑，
+# 等于把"支持"两个字写在一个没人验的地方。
+#
+# 矩阵的下边界必须和 pyproject 的 requires-python 一致。要提最低版本，
+# 就同时改这两处，不许只改一处。
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pipx install uv
+
+      - name: requires-python 的下界必须就是矩阵的下界
+        # 光有矩阵不够 —— 有人把 requires-python 降到 3.9 而矩阵没跟，
+        # 就又回到"声明支持但从不验"那个状态，而且这次是无声的。
+        run: |
+          FLOOR=$(grep -m1 '^requires-python' pyproject.toml \
+                  | sed 's/.*>=\([0-9.]*\).*/\1/')
+          echo "requires-python 下界=$FLOOR  矩阵下界=3.10"
+          test "$FLOOR" = "3.10" || {
+            echo "::error::requires-python 是 >=$FLOOR，但 CI 矩阵从 3.10 起。"
+            echo "::error::改最低版本时 pyproject 和这个矩阵必须一起改。"
+            exit 1; }
+
+      - name: 跑测试
+        run: uv run --python ${{ matrix.python-version }} --extra dev pytest tests/ -q
+
+      - name: 示例必须能脱离宿主跑通
+        run: |
+          uv run --python ${{ matrix.python-version }} python3 examples/quickstart.py
+          uv run --python ${{ matrix.python-version }} python3 examples/end_to_end.py

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

@@ -1,6 +1,92 @@
 # 变更记录
 
-## 0.2.4 — 未发布
+## 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）逐条核出来的。** 四条里三条是"查询静默给错答案"，
+不是崩溃 —— 这类最贵，因为看上去一切正常。
+
+### 修复
+
+- **排查查不到终态事件。** `list_events` 的文档自己写着「答案往往不是
+  pending，而是 suppressed 或 rejected」，下一行却调了只看待投递的端口，
+  而那两个恰好都是终态。于是「为什么没提醒我」这个问题，代码保证答不出来 ——
+  排查看到的是"压根没产生过这个事件"，方向直接错。新增 `StoragePort.list_events`
+  （任何投递状态，状态/类型/时间窗全部下推），旧的 `list_pending_events`
+  仍然只给 worker 用。
+- **日历和提醒最多只能看到 500 条。** 从存储取一个固定上限、再在内存里切页：
+  游标只在那一批里打转，第 501 条永远取不到，而且不报错 —— 用户看到的是
+  "我八月没有日程"。`offset` 现在真的下推给存储；日历因为要展开重复规则，
+  用 `(读到第几条:那一条消费到第几个)` 的复合游标，翻页不会把同一条日程重给一遍。
+- **Python 3.10 上两位小数秒的时间戳整条被拒。** 归属那一层自己调了
+  `fromisoformat`，绕开了包里那个宽解析器；3.10 的 `fromisoformat` 只认三位或
+  六位小数秒，而真机 producer 发的是 `23:59:59.96+08:00`。冷却判定也走了同一条
+  窄路 —— 那里解析失败会**静默当作没冷却过**，同一件事反复叫醒 agent。
+  两处都改走 `contracts._time`。
+
+- **「今天新增了几张照片」永远答 1。** `photo_library_added.count` 的声明是
+  `valid_range=(1,1)`（一张照片一条 count=1）配 `daily_total`（当天取 max）——
+  max 恒等于 1。用户拍了二十张，聚合里写着 1，而这条聚合是**永久**保存的。
+  这是第二次：`app_usage.open_count` 先踩过同一个坑，教训写进了注释、
+  例子都写着「用户开了二十次，答案还是 1 次」，但隔壁的照片没人回头看。
+  **一条只写在注释里的纪律，保护不了下一个信号** —— 所以同时加了
+  `check_counting_strategies_can_actually_count`：取 max 的策略配上「取值范围
+  只有一个数」的字段，是可以机械证明的矛盾，直接在 `validate_manifest` 里拦掉。
+  写完这个检查的当下它就把照片这条抓出来了。
+  ⚠️ 已经落库的历史数字修不回来：明细只留 7 天，更早的日子连重算的原料都没有。
+
+### 新增
+
+- **一致性套件第 ⑫ 条：终态可查与翻页下推。** 前两条修的是包内实现，但同样的
+  错宿主也会犯：把 `offset` 加进签名、body 里照旧忽略 —— 签名对了、行为没变，
+  而 Protocol 不会告诉你。所以这条验的是行为。
+- `tests/test_docs_match_code.py`：文档里声称的信号数量、CHANGELOG 顶上的版本，
+  和代码对不上就红。
+
+### 文档
+
+- manifest 开头不再说"五个信号"（实际 23 个），`PerceptionKit` 的默认值注释同步。
+- README 去掉写死的测试条数 —— 每次提交都在变，写死了就是保证会漂。
+- `pyproject` 的描述不再说"不碰存储"：不选数据库，但存储编排在包内。
+
+## 0.2.4 — 2026-09-01
 
 **第一批真机数据跑出来的。** 4052 次比对里三处不一致，这是其中属于内核的那一处。
 

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: perceptkit
-Version: 0.2.4
-Summary: 从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不碰存储、不调模型。
+Version: 0.2.6
+Summary: 从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不选数据库、不调模型 —— 存储由宿主实现 StoragePort，编排在包内。
 License: 
                                          Apache License
                                    Version 2.0, January 2004
@@ -247,7 +247,7 @@ kit.dispatch_pending(worker_id="w1", now=now)
 ```bash
 git clone git@github.com:teleport-computer/perceptkit.git
 cd perceptkit
-uv run pytest                        # 283 条测试
+uv run pytest                        # 全部测试
 uv run python3 examples/quickstart.py   # 一分钟看它怎么判断
 ```
 
@@ -429,8 +429,9 @@ src/perceptkit/
 
 ## 六、现状
 
-107 条测试全绿（含 `test_purity.py` 的 AST 扫描：本包只依赖标准库，
-以及 `test_no_host_leakage.py`：不带宿主内部痕迹）。`examples/quickstart.py`
+测试全绿（含 `test_purity.py` 的 AST 扫描：本包只依赖标准库，
+以及 `test_no_host_leakage.py`：不带宿主内部痕迹）。条数不写在这里 ——
+每次提交都在变，写死了就是保证会漂，而"多少条"本身帮不了任何判断。`examples/quickstart.py`
 本身也有一条测试盯着（`tests/test_examples.py`）——它必须一直能跑，
 不能悄悄烂掉。
 

{perceptkit-0.2.4 → perceptkit-0.2.6}/README.md

@@ -34,7 +34,7 @@ kit.dispatch_pending(worker_id="w1", now=now)
 ```bash
 git clone git@github.com:teleport-computer/perceptkit.git
 cd perceptkit
-uv run pytest                        # 283 条测试
+uv run pytest                        # 全部测试
 uv run python3 examples/quickstart.py   # 一分钟看它怎么判断
 ```
 
@@ -216,8 +216,9 @@ src/perceptkit/
 
 ## 六、现状
 
-107 条测试全绿（含 `test_purity.py` 的 AST 扫描：本包只依赖标准库，
-以及 `test_no_host_leakage.py`：不带宿主内部痕迹）。`examples/quickstart.py`
+测试全绿（含 `test_purity.py` 的 AST 扫描：本包只依赖标准库，
+以及 `test_no_host_leakage.py`：不带宿主内部痕迹）。条数不写在这里 ——
+每次提交都在变，写死了就是保证会漂，而"多少条"本身帮不了任何判断。`examples/quickstart.py`
 本身也有一条测试盯着（`tests/test_examples.py`）——它必须一直能跑，
 不能悄悄烂掉。
 

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

@@ -99,7 +99,7 @@ iOS 拿不到前台 app（`frontmost_app` 恒为 null），数据全靠用户在
 
 一张照片一条 count=1，不是「今天 5 张」报一次 —— 拆成一条条才能让照片走通用管线：跨午夜天然各归各的日、某条字段有问题只拒那一条。传输上仍然可以一个信封装多条，不多发请求。
 🔴 删照片【不回减】过去某日的数量：它记的是「那天发生过什么」，不是「现在还剩几张」。
-🔴 前提未满足：iOS 现在上报的是随机 id，同一张照片两次上报算出两个不同身份 —— 去重表再完美也挡不住。要 iOS 改成用 PHAsset.localIdentifier 的端上哈希（和 wifi_anchor_id 同一套做法）。已列入 iOS 待办。
+身份必须由设备给一个稳定值：内容信封 id 是每次上传新生成的，用它的话同一张照片重传就是两张，去重表再完美也挡不住。iOS 送的是SHA256(固定 namespace + PHAsset.localIdentifier)——固定 namespace 而不是wifi_anchor_id 那种设备本地随机密钥：照片 id 是本机相册的高熵 UUID，别的设备上不存在，固定 namespace 就够不可逆；而且重装后仍然稳定，正好让重扫相册时认出「这些都数过了」。
 去重指纹的保留期：规范建议永久；我们查下来当前实现【找不到超过 7 天的重放路径】，所以按「覆盖明细保留期 + 富余」取 30 天更实在。规范自己也是条件句：「若 producer 可以在超过 7 天后重放，才必须永久保留」。
 
 ### `presence_recovery`

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

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

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

@@ -15,6 +15,8 @@ from __future__ import annotations
 import datetime as _dt
 import zoneinfo as _zoneinfo
 
+from ..contracts import _time
+
 INSTANT = "instant"                        # 单点：按其自带 offset 的本地日期
 EPISODE_END = "episode_end"                # 区间：整体归结束（醒来）那天
 SPLIT_AT_MIDNIGHT = "split_at_midnight"    # 可加总时长：按本地午夜切分
@@ -52,14 +54,17 @@ ATTRIBUTION: dict[str, str] = {
 
 
 def _aware(raw: str) -> _dt.datetime:
-    """解析成带 offset 的时刻。没有 offset 就报错 —— 不猜。"""
+    """解析成带 offset 的时刻。没有 offset 就报错 —— 不猜。
+
+    🔴 **走 ``contracts._time`` 那一个解析器，不许自己调 ``fromisoformat``。**
+    3.10 的 ``fromisoformat`` 只认三位或六位小数秒，真实 producer 发的是
+    ``23:59:59.96+08:00`` 这种两位的；自己调就是"3.12 上全绿、3.10 上
+    整条上报被拒"。这个包声明 ``requires-python>=3.10``，那就得真的能跑。
+    """
     try:
-        parsed = _dt.datetime.fromisoformat(str(raw))
-    except (TypeError, ValueError) as exc:
-        raise ValueError(f"无法解析时间：{raw!r}") from exc
-    if parsed.tzinfo is None or parsed.utcoffset() is None:
-        raise ValueError(f"时间缺少时区 offset，拒绝按 UTC 或本机时区猜测：{raw!r}")
-    return parsed
+        return _time.parse_timestamp(raw, field="时间")
+    except _time.TimestampError as exc:
+        raise ValueError(str(exc)) from exc
 
 
 def _utc_naive(dtobj: _dt.datetime) -> _dt.datetime:

{perceptkit-0.2.4 → perceptkit-0.2.6}/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 [
@@ -197,7 +205,8 @@ class InMemoryStorage:
             self.reminders[(subject_id, r.source_account_id, r.source_list_id,
                             r.source_reminder_id)] = r
 
-    def list_calendar_events(self, *, subject_id, start=None, end=None, limit=50):
+    def list_calendar_events(self, *, subject_id, start=None, end=None,
+                             limit=50, offset=0):
         rows = [v for k, v in self.calendar.items() if k[0] == subject_id]
         keep = []
         for item in rows:
@@ -212,9 +221,10 @@ class InMemoryStorage:
         keep.sort(key=lambda i: (i.event_fields.get("start_at") is None,
                                  i.event_fields.get("start_at") or _EPOCH,
                                  i.source_event_id))
-        return keep[:limit]
+        return keep[offset:offset + limit]
 
-    def list_reminders(self, *, subject_id, include_completed=False, limit=50):
+    def list_reminders(self, *, subject_id, include_completed=False,
+                       limit=50, offset=0):
         keep = [
             v for k, v in self.reminders.items()
             if k[0] == subject_id
@@ -223,7 +233,7 @@ class InMemoryStorage:
         keep.sort(key=lambda i: (i.reminder_fields.get("due_at") is None,
                                  i.reminder_fields.get("due_at") or _EPOCH,
                                  i.source_reminder_id))
-        return keep[:limit]
+        return keep[offset:offset + limit]
 
     def apply_source_snapshot(self, *, subject_id, source, collection_kind, sync_id,
                               coverage_start, coverage_end, snapshot_kind) -> int:
@@ -326,6 +336,22 @@ class InMemoryStorage:
             if not e.is_terminal and (subject_id is None or e.subject_id == subject_id)
         ][:limit]
 
+    def list_events(self, *, subject_id, delivery_states=None, event_type=None,
+                    start=None, end=None, limit=50, offset=0):
+        # 注意这里**没有** is_terminal 过滤 —— 排查要的正是终态。
+        rows = [e for e in self.outbox.values() if e.subject_id == subject_id]
+        if delivery_states is not None:
+            wanted = set(delivery_states)
+            rows = [e for e in rows if e.delivery_state in wanted]
+        if event_type is not None:
+            rows = [e for e in rows if e.event_type == event_type]
+        if start is not None:
+            rows = [e for e in rows if e.occurred_at >= start]
+        if end is not None:
+            rows = [e for e in rows if e.occurred_at <= end]
+        rows.sort(key=lambda e: (e.occurred_at, e.event_id), reverse=True)
+        return rows[offset:offset + limit]
+
     # -- 用户数据 --------------------------------------------------------
 
     def purge_subject(self, *, subject_id) -> dict[str, int]:

{perceptkit-0.2.4 → perceptkit-0.2.6}/src/perceptkit/conformance/suite.py

@@ -86,7 +86,7 @@ def _entry(**over: Any) -> EventOutboxEntry:
 
 
 # ---------------------------------------------------------------------------
-# 十条保证
+# 十二条保证
 # ---------------------------------------------------------------------------
 
 def _g1_report_and_observation_idempotency(new: StorageFactory) -> list[str]:
@@ -383,6 +383,97 @@ def _g11_both_source_mirrors_round_trip(new: StorageFactory) -> list[str]:
     return problems
 
 
+def _g12_terminal_events_and_offsets_are_queryable(new: StorageFactory) -> list[str]:
+    """⑫ 终态事件查得到，翻页翻得过读取批次。
+
+    两件事都是"静默给错答案"，不是"报错"：
+
+        终态查不到  「为什么没提醒我」的答案通常是 suppressed（撞了安静时段）
+                    或 rejected（宿主拒了），而这两个都是终态。宿主只实现了
+                    「待投递」那个查询的话，排查看到的是"压根没产生过这个
+                    事件"，方向直接错了。
+        翻页翻不动  offset 不真的下推到存储，游标就只在第一批里打转。
+                    用户看到的是"我八月没有日程"，不是"结果被截断了"。
+
+    宿主容易只把 ``offset`` 加进签名、body 里照旧忽略 —— 签名对了、行为没变，
+    而 Protocol 不会告诉你。所以这里验的是**行为**，不是方法在不在。
+    """
+    problems: list[str] = []
+    s = new()
+    base = T0
+    # 回执状态和投递状态是**两套词表**：runtime 回 conversation_suppressed，
+    # 落到发件箱上叫 suppressed。这里照真实那条路走，不直接改状态字段。
+    wanted = {
+        "ev0": (_receipt.WAKE_SUPPRESSED, _delivery.SUPPRESSED),  # 撞了安静时段
+        "ev1": (_receipt.WAKE_REJECTED, _delivery.REJECTED),      # 宿主拒了
+        "ev2": (_receipt.WAKE_ACCEPTED, _delivery.DELIVERED),
+        "ev3": (None, _delivery.PENDING),
+    }
+    for i, (eid, (status, state)) in enumerate(wanted.items()):
+        s.enqueue_event(_entry(event_id=eid, event_type="t",
+                               occurred_at=base + timedelta(minutes=i)))
+        if status is None:
+            continue
+        claimed = s.claim_pending_event(worker_id="w", now=base,
+                                        lease_seconds=60)
+        if claimed is None:
+            problems.append("⑫: 领不到刚入队的事件，后面测不了")
+            return problems
+        s.record_wake_receipt(
+            receipt=WakeReceipt(event_id=claimed.event_id,
+                                attempt_id=f"a{i}", status=status,
+                                received_at=base),
+            next_state=state, claim_token=claimed.claim_token,
+        )
+
+    seen = {e.event_id: e.delivery_state
+            for e in s.list_events(subject_id="u1", limit=50)}
+    for eid, (_status, state) in wanted.items():
+        if eid not in seen:
+            problems.append(
+                f"⑫: list_events 看不到 {state} 的事件 —— "
+                f"「为什么没提醒我」这个问题就答不出来"
+            )
+    only = [e.event_id for e in s.list_events(
+        subject_id="u1", delivery_states=[_delivery.SUPPRESSED], limit=50)]
+    if only != ["ev0"]:
+        problems.append("⑫: 按投递状态筛没生效")
+
+    # offset 必须真的下推：连着两页不能给出同一条。
+    first = [e.event_id for e in s.list_events(subject_id="u1", limit=2, offset=0)]
+    second = [e.event_id for e in s.list_events(subject_id="u1", limit=2, offset=2)]
+    if set(first) & set(second) or len(first) + len(second) != 4:
+        problems.append("⑫: list_events 的 offset 没有下推到存储，翻页会重复或漏")
+
+    s2 = new()
+    s2.upsert_calendar_events(subject_id="u1", events=[CalendarEventMirror(
+        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        source_event_id=f"e{i}",
+        event_fields={"title": f"e{i}", "start_at": base + timedelta(minutes=i)},
+    ) for i in range(4)])
+    p1 = [e.source_event_id for e in s2.list_calendar_events(
+        subject_id="u1", limit=2, offset=0)]
+    p2 = [e.source_event_id for e in s2.list_calendar_events(
+        subject_id="u1", limit=2, offset=2)]
+    if set(p1) & set(p2) or len(set(p1) | set(p2)) != 4:
+        problems.append("⑫: list_calendar_events 的 offset 没有下推到存储")
+
+    s3 = new()
+    s3.upsert_reminders(subject_id="u1", items=[ReminderItemMirror(
+        subject_id="u1", source_account_id="a", source_list_id="l",
+        source_reminder_id=f"r{i}",
+        reminder_fields={"title": f"r{i}", "is_completed": False,
+                         "due_at": base + timedelta(minutes=i)},
+    ) for i in range(4)])
+    q1 = [r.source_reminder_id for r in s3.list_reminders(
+        subject_id="u1", limit=2, offset=0)]
+    q2 = [r.source_reminder_id for r in s3.list_reminders(
+        subject_id="u1", limit=2, offset=2)]
+    if set(q1) & set(q2) or len(set(q1) | set(q2)) != 4:
+        problems.append("⑫: list_reminders 的 offset 没有下推到存储")
+    return problems
+
+
 GUARANTEES: dict[str, Callable[[StorageFactory], list[str]]] = {
     "①上报与观测幂等": _g1_report_and_observation_idempotency,
     "②旧数据不覆盖新当前值": _g2_old_does_not_overwrite_new,
@@ -395,6 +486,7 @@ GUARANTEES: dict[str, Callable[[StorageFactory], list[str]]] = {
     "⑨清理不破坏永久聚合": _g9_retention_cleanup_spares_what_permanent_aggregates_need,
     "⑩用户隔离与删除": _g10_subject_isolation_and_purge,
     "⑪两个来源镜像都能往返": _g11_both_source_mirrors_round_trip,
+    "⑫终态可查与翻页下推": _g12_terminal_events_and_offsets_are_queryable,
 }
 
 #: 这几条在内存实现上**永远是绿的**，因为内存天然原子、天然无并发。
@@ -403,7 +495,7 @@ NOT_PROVABLE_IN_MEMORY: frozenset[str] = frozenset({"⑤提供原子边界"})
 
 
 def run_storage_conformance(factory: StorageFactory) -> list[str]:
-    """跑全部十条，返回问题清单（空 = 通过）。
+    """跑全部十二条，返回问题清单（空 = 通过）。
 
     返回列表而不是抛异常：一次看到全部缺口，比逐个修再重跑快得多。
     """

{perceptkit-0.2.4 → perceptkit-0.2.6}/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
@@ -37,7 +38,7 @@ class PerceptionKit:
 
     storage: StoragePort
     wake: WakePort | None = None
-    #: 信号声明。默认是最小集（五个信号，覆盖两种存储形态）；
+    #: 信号声明。默认是 ``MINIMAL_SIGNALS``（23 个，覆盖四种存储形态）；
     #: 宿主应当传自己的完整 manifest。
     signals: Mapping[str, SignalDefinition] = field(
         default_factory=lambda: dict(MINIMAL_SIGNALS)
@@ -142,6 +143,57 @@ 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": k, "why": why} for k, why in plan.skipped],
+            "removed": removed,
+        }
+
     def evaluate_absence(
         self, *, subject_id: str, now: datetime,
     ) -> ScheduledOutcome:

{perceptkit-0.2.4 → perceptkit-0.2.6}/src/perceptkit/manifest/checks.py

@@ -286,12 +286,49 @@ def check_projections_do_not_drift(
                 )
     return problems
 
+def check_counting_strategies_can_actually_count(
+    signals: Mapping[str, SignalDefinition],
+) -> list[str]:
+    """取 max 的策略配上「取值范围只有一个数」的字段 —— 结果恒等于那个数。
+
+    这不是风格问题，是一个可以机械证明的矛盾，而它的表现是**一个安静的错数**：
+
+        photo_library_added.count  valid_range=(1, 1)  一张照片一条 count=1
+                                   aggregation_strategy="daily_total"（取 max）
+                                   → max(1, 1, 1, ...) = 1
+                                   → "今天新增了几张照片" 永远答 1
+
+    照片那条聚合还是永久保存的，所以错的是一个永远不会自己修好的历史数字。
+    真实发生过：``app_usage.open_count`` 先踩了一次，教训写进了
+    ``aggregate._STRATEGY_TO_SHAPE`` 的注释里，但隔壁的 ``photo_library_added``
+    没人回头看 —— 一条只写在注释里的纪律，保护不了下一个信号。
+
+    「每次事件贡献一份」用 ``occurrence_count``（求和）。
+    ``daily_total`` / ``cumulative`` 是给**来源自己在数**的量用的
+    （今日步数 8000 → 8300，取 max 才对）。
+    """
+    problems: list[str] = []
+    for key, sig in signals.items():
+        for f in sig.fields:
+            if f.aggregation_strategy not in ("daily_total", "cumulative"):
+                continue
+            rng = f.valid_range
+            if rng is None or rng[0] != rng[1]:
+                continue
+            problems.append(
+                f"{key}.{f.key}: valid_range={rng} 只允许一个值，"
+                f"而 {f.aggregation_strategy!r} 取当天最大值 —— 结果恒等于 {rng[0]}。"
+                f"每次事件各贡献一份的量要用 'occurrence_count'（求和）"
+            )
+    return problems
+
+
 def validate_manifest(
     signals: Mapping[str, SignalDefinition],
     *,
     available_normalizers: Iterable[str] = (),
 ) -> list[str]:
-    """跑全部五条检查（产品规范 §8 列的那五条），返回问题清单（空 = 通过）。
+    """跑全部六条检查（产品规范 §8 列的五条 + 一条计数策略自洽），返回问题清单（空 = 通过）。
 
     返回列表而不是抛异常：一次看到全部缺口，比逐个修再重跑快得多。
     """
@@ -311,6 +348,7 @@ def validate_manifest(
     )
     problems += check_wake_eligible_fields_have_comparators(signals)
     problems += check_projections_do_not_drift(signals)
+    problems += check_counting_strategies_can_actually_count(signals)
     return problems
 
 
@@ -319,5 +357,6 @@ __all__ = [
     "check_history_has_retention",
     "check_named_implementations_exist",
     "check_wake_eligible_fields_have_comparators",
+    "check_counting_strategies_can_actually_count",
     "validate_manifest",
 ]

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

@@ -1,10 +1,13 @@
-"""最小可执行 manifest —— 五个信号，把整条管线走通一遍。
+"""默认 manifest —— 23 个信号。
 
-**为什么先做五个而不是二十个。** 管线的正确性（幂等、乱序、TTL、聚合重算、
-规则求值、投递可靠性）和信号数量无关；而字段细节还有一堆没和产品方对齐的问题
-（见 ``OPEN-QUESTIONS.md``）。先用五个把管线跑通，剩下十五个只是往表里填格子。
+**它是怎么长到 23 个的。** 一开始只有五个：管线的正确性（幂等、乱序、TTL、
+聚合重算、规则求值、投递可靠性）和信号数量无关，所以先用五个把管线跑通，
+剩下的只是往表里填格子。管线验完之后按真机上真实出现的来源逐个补齐，
+现在 23 个。改这个数字时**这一行也要跟着改** —— 一份说"五个"的文件
+会让下一个接入的人（和下一个工程 AI）按五个去设计。
 
-选这五个是因为它们**恰好覆盖四种存储形态和三种身份策略**：
+最早那五个之所以是那五个，是因为它们**恰好覆盖四种存储形态和三种身份策略**，
+这个骨架现在仍然成立：
 
     battery            current_only          · singleton
     presence_recovery  current_only          · source_event_id  · occurrence 事件
@@ -611,9 +614,12 @@ PHOTO_LIBRARY_ADDED = SignalDefinition(
         "传输上仍然可以一个信封装多条，不多发请求。\n"
         "🔴 删照片【不回减】过去某日的数量：它记的是「那天发生过什么」，"
         "不是「现在还剩几张」。\n"
-        "🔴 前提未满足：iOS 现在上报的是随机 id，同一张照片两次上报算出两个不同"
-        "身份 —— 去重表再完美也挡不住。要 iOS 改成用 PHAsset.localIdentifier 的"
-        "端上哈希（和 wifi_anchor_id 同一套做法）。已列入 iOS 待办。\n"
+        "身份必须由设备给一个稳定值：内容信封 id 是每次上传新生成的，用它的话"
+        "同一张照片重传就是两张，去重表再完美也挡不住。iOS 送的是"
+        "SHA256(固定 namespace + PHAsset.localIdentifier)——固定 namespace 而不是"
+        "wifi_anchor_id 那种设备本地随机密钥：照片 id 是本机相册的高熵 UUID，"
+        "别的设备上不存在，固定 namespace 就够不可逆；而且重装后仍然稳定，"
+        "正好让重扫相册时认出「这些都数过了」。\n"
         "去重指纹的保留期：规范建议永久；我们查下来当前实现【找不到超过 7 天的"
         "重放路径】，所以按「覆盖明细保留期 + 富余」取 30 天更实在。"
         "规范自己也是条件句：「若 producer 可以在超过 7 天后重放，才必须永久保留」。"
@@ -626,7 +632,11 @@ PHOTO_LIBRARY_ADDED = SignalDefinition(
             privacy_class="personal",
             nullable=False,
             valid_range=(1, 1),        # 永远是 1 —— 一张照片一条
-            aggregation_strategy="daily_total",
+            # 🔴 求和，不是取 max。每张照片各贡献一份 1，取 max 的话
+            # 「今天新增了几张」永远答 1，而这条聚合是永久保存的。
+            # app_usage.open_count 先踩过同一个坑；现在
+            # check_counting_strategies_can_actually_count 会拦住第三次。
+            aggregation_strategy="occurrence_count",
             comparison_strategy="occurrence",
             trend_model="fluctuating",
             wake_eligible=True,