perceptkit 0.2.8__tar.gz → 0.3.0__tar.gz

{perceptkit-0.2.8 → perceptkit-0.3.0}/CHANGELOG.md

@@ -1,5 +1,51 @@
 # 变更记录
 
+## 0.3.0 — 2026-09-03
+
+外部审查（2026-09-03）里**不需要产品拍板的那批契约漏洞**。其中三条是审查者
+自己复现的，一条是我们没发现的双重真相。
+
+### ⚠️ 破坏性变更
+
+- **``CalendarEventMirror`` / ``ReminderItemMirror`` 新增必填字段 ``source``。**
+  它是唯一身份的一部分，不是标签 —— 少了它，一次 ``source="ios"`` 的全量同步
+  会把概念上属于 Google 的日程一起删掉（快照收尾删的是"这轮没见到的"，
+  而另一个来源的条目当然没在这轮里）。用户会发现自己另一个日历账户的日程
+  凭空消失，且不可逆。
+  走 ``sync_source_mirror`` 的调用方不用改：kit 会用这一批声明的 ``source``
+  盖上去，和 ``sync_id`` 同一个道理。
+- **``StoragePort`` 新增 ``delete_source_items``**（见下）。
+
+### 修复
+
+- **增量同步执行来源明确的删除（§8.1）。** 早先把增量定义成"一条都不许删"，
+  防住了"拿局部列表当全量"，但同时堵死了另一条：来源的 change feed 明确
+  传来一条删除时，那是**确定的事实**，不是推断。结果是用户在手机上删掉的
+  日程，在 agent 眼里永远还在，还会一直出现在"接下来有什么安排"里。
+  ``SyncBatch.deleted_item_ids`` + ``StoragePort.delete_source_items``；
+  和全量收尾的删除**分开计数**，否则分不清某次异常删除是范围判断出错
+  还是来源真的删了。
+- **来源进入镜像唯一身份（§8.2）。** 见上面的破坏性变更。
+- **``collection_kind`` 与条目类型交叉校验（§8.3）。**
+  ``collection_kind="reminders"`` 配一批日历条目原本会被照单全收：日历表
+  被写进去了，而**提醒的游标往前推进了** —— 数据和游标从此互相矛盾，
+  下一轮增量提醒同步会以为上一轮成功了，那段提醒永远补不回来。
+- **镜像条目的 subject 一律用可信上下文覆盖（§8.4）。** 条目是宿主从来源
+  数据翻译出来的，它自带的 ``subject_id`` 最好的情况是冗余、最坏的情况是
+  把 A 的日程写进 B 的花园。可信 subject 只有一个来源：``IngestContext``。
+- **``retention_days()`` / ``stores_history()`` 改从 manifest 查（§9）。**
+  它们原本读本模块顶上那张旧表，和 manifest **七条全对不上**：
+  ``focus_state`` 抛 KeyError（manifest 说 365）、``audio_route`` 返回 90
+  （manifest 说 7）。接入方和工程 AI 调公开 API 会拿到错的结论，而且没有
+  任何地方报错 —— 两个真相各自自洽，只是不一样。
+  旧名（``focus`` / ``playback`` / ``location_signal``）作为显式的、
+  受测试的别名保留；那张旧表降级成历史记录，不再是任何查询的依据。
+
+  🔴 ``retention_days()`` 对不进历史表的信号**仍然抛 ``KeyError``，
+  不返回 ``None``** —— 这条早先的决策改用 manifest 之后理由更硬了：
+  旧词表里 ``None`` 是「永久保存」，静默返回 ``None`` 会让照旧词表理解的
+  调用方把「根本不存历史」读成「永久保留」，两个意思正好相反。
+
 ## 0.2.8 — 2026-09-02
 
 - **来源镜像的同步终于有了和 ``ingest()`` 对等的入口（P0-2）。**

{perceptkit-0.2.8 → perceptkit-0.3.0}/PKG-INFO

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

{perceptkit-0.2.8 → perceptkit-0.3.0}/pyproject.toml

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

{perceptkit-0.2.8 → perceptkit-0.3.0}/src/perceptkit/conformance/memory.py

@@ -196,14 +196,16 @@ class InMemoryStorage:
         self.sync_state[(state.subject_id, state.source, state.collection_kind)] = state
 
     def upsert_calendar_events(self, *, subject_id, events) -> None:
+        # 键里带 source —— 少了它，两个来源系统里碰巧同 id 的日程会互相覆盖，
+        # 而全量同步还会把另一个来源的条目当成"这轮没见到"删掉。
         for e in events:
-            self.calendar[(subject_id, e.source_account_id, e.source_calendar_id,
-                           e.source_event_id)] = e
+            self.calendar[(subject_id, e.source, e.source_account_id,
+                           e.source_calendar_id, e.source_event_id)] = e
 
     def upsert_reminders(self, *, subject_id, items) -> None:
         for r in items:
-            self.reminders[(subject_id, r.source_account_id, r.source_list_id,
-                            r.source_reminder_id)] = r
+            self.reminders[(subject_id, r.source, 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, offset=0):
@@ -235,6 +237,17 @@ class InMemoryStorage:
                                  i.source_reminder_id))
         return keep[offset:offset + limit]
 
+    def delete_source_items(self, *, subject_id, source, collection_kind,
+                            source_item_ids) -> int:
+        store = self.calendar if collection_kind == "calendar" else self.reminders
+        wanted = set(source_item_ids)
+        # key = (subject, source, account, collection, item_id) —— 最后一位是 id。
+        doomed = [k for k in store
+                  if k[0] == subject_id and k[1] == source and k[-1] in wanted]
+        for k in doomed:
+            del store[k]
+        return len(doomed)
+
     def apply_source_snapshot(self, *, subject_id, source, collection_kind, sync_id,
                               coverage_start, coverage_end, snapshot_kind) -> int:
         # 增量同步没有资格删任何东西 —— 它只知道"变了什么"，不知道"还剩什么"。
@@ -243,7 +256,11 @@ class InMemoryStorage:
         store = self.calendar if collection_kind == "calendar" else self.reminders
         doomed = []
         for key, item in store.items():
-            if key[0] != subject_id or item.last_seen_sync_id == sync_id:
+            # 🔴 必须同时限定 subject **和 source**。只按 subject 删的话，
+            # 一次 source="ios" 的全量同步会把 Google 日历的条目一起删掉 ——
+            # 它们当然没出现在这一轮 ios 的批次里。
+            if (key[0] != subject_id or item.source != source
+                    or item.last_seen_sync_id == sync_id):
                 continue
             # 🔴 只删【能证明落在覆盖范围内】的。拿局部窗口去删窗口外的数据，
             # 会让用户发现自己去年的日程凭空消失，而且不可逆。

{perceptkit-0.2.8 → perceptkit-0.3.0}/src/perceptkit/conformance/suite.py

@@ -228,12 +228,12 @@ def _g8_partial_sync_does_not_delete_outside_its_window(new: StorageFactory) ->
     problems: list[str] = []
     s = new()
     inside = CalendarEventMirror(
-        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        subject_id="u1", source="ios", source_account_id="a", source_calendar_id="c",
         source_event_id="e_in", event_fields={"start_at": T0},
         last_seen_sync_id="old",
     )
     outside = CalendarEventMirror(
-        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        subject_id="u1", source="ios", source_account_id="a", source_calendar_id="c",
         source_event_id="e_out", event_fields={"start_at": T0 - timedelta(days=400)},
         last_seen_sync_id="old",
     )
@@ -348,7 +348,7 @@ def _g11_both_source_mirrors_round_trip(new: StorageFactory) -> list[str]:
     problems: list[str] = []
     s = new()
     s.upsert_calendar_events(subject_id="u1", events=[CalendarEventMirror(
-        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        subject_id="u1", source="ios", source_account_id="a", source_calendar_id="c",
         source_event_id="e1", event_fields={"title": "站会", "start_at": T0},
     )])
     got = list(s.list_calendar_events(subject_id="u1", limit=10))
@@ -357,7 +357,7 @@ def _g11_both_source_mirrors_round_trip(new: StorageFactory) -> list[str]:
 
     s2 = new()
     s2.upsert_reminders(subject_id="u1", items=[ReminderItemMirror(
-        subject_id="u1", source_account_id="a", source_list_id="l",
+        subject_id="u1", source="ios", source_account_id="a", source_list_id="l",
         source_reminder_id="r1", reminder_fields={"title": "买牛奶",
                                                   "is_completed": False},
     )])
@@ -368,7 +368,7 @@ def _g11_both_source_mirrors_round_trip(new: StorageFactory) -> list[str]:
         )
     # 已完成的默认不出现，除非明说要。
     s2.upsert_reminders(subject_id="u1", items=[ReminderItemMirror(
-        subject_id="u1", source_account_id="a", source_list_id="l",
+        subject_id="u1", source="ios", source_account_id="a", source_list_id="l",
         source_reminder_id="r2", reminder_fields={"title": "交房租",
                                                   "is_completed": True},
     )])
@@ -447,7 +447,7 @@ def _g12_terminal_events_and_offsets_are_queryable(new: StorageFactory) -> list[
 
     s2 = new()
     s2.upsert_calendar_events(subject_id="u1", events=[CalendarEventMirror(
-        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        subject_id="u1", source="ios", 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)])
@@ -460,7 +460,7 @@ def _g12_terminal_events_and_offsets_are_queryable(new: StorageFactory) -> list[
 
     s3 = new()
     s3.upsert_reminders(subject_id="u1", items=[ReminderItemMirror(
-        subject_id="u1", source_account_id="a", source_list_id="l",
+        subject_id="u1", source="ios", 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)},

{perceptkit-0.2.8 → perceptkit-0.3.0}/src/perceptkit/contracts/records.py

@@ -218,11 +218,18 @@ class CalendarEventMirror:
     **镜像不是快照历史。** 存的是"来源现在有哪些条目"，条目自己带着
     过去或未来的时间；不存"我们每次同步时看到了什么"。来源删除 → 本地删除。
 
-    唯一身份必须**包含来源账户和日历**：不同账户碰巧用同一个 event id
-    是完全可能的。
+    唯一身份必须**包含来源系统、来源账户和日历**：不同账户碰巧用同一个
+    event id 是完全可能的，不同来源系统更是必然。
     """
 
     subject_id: str
+    #: 哪个来源系统（``ios`` / ``google`` / ``exchange`` …）。
+    #:
+    #: 🔴 **它是唯一身份的一部分，不是标签。** 少了它，一次
+    #: ``source="ios"`` 的全量同步会把概念上属于 Google 的日程一起删掉 ——
+    #: 快照收尾删的是「这轮没见到的」，而另一个来源的条目当然没在这轮里。
+    #: 用户发现自己另一个日历账户的日程凭空消失了，且不可逆。
+    source: str
     source_account_id: str
     source_calendar_id: str
     source_event_id: str
@@ -242,6 +249,8 @@ class ReminderItemMirror:
     """外部提醒里现在还存在的一条待办。"""
 
     subject_id: str
+    #: 哪个来源系统。理由同 :class:`CalendarEventMirror.source`。
+    source: str
     source_account_id: str
     source_list_id: str
     source_reminder_id: str

{perceptkit-0.2.8 → perceptkit-0.3.0}/src/perceptkit/ports/storage.py

@@ -215,6 +215,27 @@ class StoragePort(Protocol):
         """镜像里现在还存在的提醒事项。``offset`` 的要求同上。"""
         ...
 
+    def delete_source_items(
+        self, *, subject_id: str, source: str, collection_kind: str,
+        source_item_ids: Sequence[str],
+    ) -> int:
+        """删掉来源**明确说删了**的那几条，返回删了几条。
+
+        和 :meth:`apply_source_snapshot` 是两件事，别合并：
+
+            全量收尾   "覆盖范围内、这轮没见到的" —— 推断出来的，所以只有
+                       全量有资格，而且必须限定在声明的范围内
+            这个方法   "来源说这条删了" —— 确定的事实，增量也必须执行
+
+        没有这个方法的话，增量同步只能选：要么一条都不删（用户在手机上
+        删掉的日程，在 agent 眼里永远还在，还会一直出现在"接下来有什么
+        安排"里），要么拿局部列表当全量删（更糟，且不可逆）。
+
+        🔴 ``source`` 是删除范围的一部分。少了它，一次 ``ios`` 的删除会
+        命中另一个来源系统里碰巧同 id 的条目。
+        """
+        ...
+
     def apply_source_snapshot(
         self, *, subject_id: str, source: str, collection_kind: str,
         sync_id: str, coverage_start: datetime, coverage_end: datetime,

{perceptkit-0.2.8 → perceptkit-0.3.0}/src/perceptkit/processing/source_sync.py

@@ -46,6 +46,9 @@ INCREMENTAL = "incremental"
 CALENDAR = "calendar"
 REMINDERS = "reminders"
 
+#: 集合种类 -> 它唯一接受的条目类型。
+_ITEM_TYPE = {CALENDAR: CalendarEventMirror, REMINDERS: ReminderItemMirror}
+
 
 class SyncContractError(ValueError):
     """这一批的声明本身自相矛盾，处理它会造成不可逆的损失。
@@ -73,6 +76,13 @@ class SyncBatch:
     cursor: str | None = None
     attempted_at: datetime | None = None
     completed_at: datetime | None = None
+    #: 来源**明确说**被删掉的条目身份。见 ``sync_source_mirror`` 的文档。
+    #:
+    #: 和「这一批里没出现」是两回事：没出现推断不出删除（增量只知道变了什么，
+    #: 不知道还剩什么），但来源的 change feed 明确传来一条删除时，
+    #: 那是确定的事实，必须执行 —— 否则用户在手机上删掉的日程，
+    #: 在 agent 眼里永远还在。
+    deleted_item_ids: Sequence[str] = field(default_factory=tuple)
     #: 非空 = 这一批**没有成功拿到**。见 ``SyncOutcome`` 的文档。
     error_code: str | None = None
 
@@ -82,7 +92,12 @@ class SyncOutcome:
     """这一轮做了什么。``failed`` 时 ``upserted`` / ``deleted`` 一定是 0。"""
 
     upserted: int = 0
+    #: 全量收尾按范围删掉的条数。
     deleted: int = 0
+    #: 按来源明确的 tombstone 删掉的条数。和上面一个分开数 —— 一个是
+    #: "这轮没见到所以删"，一个是"来源说删了"，混在一起就分不清
+    #: 某次异常删除是范围判断出错还是来源真的删了。
+    tombstoned: int = 0
     failed: bool = False
     #: 记下来的错误码，原样来自这一批。
     error_code: str | None = None
@@ -162,6 +177,8 @@ def sync_source_mirror(
 
     with storage.transaction():
         upserted = _upsert(storage, batch, context)
+        # 来源明确的删除，全量和增量都执行 —— 它不是推断出来的。
+        tombstoned = _apply_tombstones(storage, batch, context)
         deleted = 0
         if kind == FULL:
             # 只有全量才有资格删，而且只在它自己声明的范围内。
@@ -189,10 +206,34 @@ def sync_source_mirror(
             last_error_code=None,
         ))
     return SyncOutcome(upserted=upserted, deleted=deleted,
+                       tombstoned=tombstoned,
                        cursor=batch.cursor if batch.cursor is not None
                        else prior_cursor)
 
 
+def _apply_tombstones(storage: StoragePort, batch: SyncBatch,
+                      context: IngestContext) -> int:
+    """执行来源**明确传来**的删除。
+
+    这和全量收尾的删除是两件事，别合并：
+
+        全量收尾   "覆盖范围内、这轮没见到的" —— 推断出来的，所以只有全量
+                   有资格，而且必须限定在声明的范围内
+        tombstone  "来源说这条删了" —— 确定的事实，增量也必须执行
+
+    早先把增量定义成「一条都不许删」，防住了「拿局部列表当全量」，
+    但同时也堵死了这条：用户在手机上删掉的日程，在 agent 眼里永远还在，
+    而且它会一直出现在"接下来有什么安排"里。
+    """
+    ids = [str(i) for i in (batch.deleted_item_ids or ()) if str(i).strip()]
+    if not ids:
+        return 0
+    return int(storage.delete_source_items(
+        subject_id=context.subject_id, source=batch.source,
+        collection_kind=batch.collection_kind, source_item_ids=ids,
+    ) or 0)
+
+
 def _upsert(storage: StoragePort, batch: SyncBatch,
             context: IngestContext) -> int:
     items = list(batch.items)
@@ -204,20 +245,51 @@ def _upsert(storage: StoragePort, batch: SyncBatch,
     # 不打的话，刚写进去的条目在同一个事务里被自己的快照收尾删掉 ——
     # 一次"成功"的全量同步，结果是镜像空了。
     # 这个由 kit 打，不指望宿主记得：忘了不报错，只是数据没了。
-    items = [replace(i, last_seen_sync_id=batch.sync_id) for i in items]
+    # 这一批声明的 source 和 sync_id 由 kit 盖上去，不要求宿主在每个条目上
+    # 再写一遍。两者忘了都不报错，但后果不一样：
+    #   sync_id 忘了 → 刚写进去的被自己的快照收尾删掉
+    #   source  忘了 → 这批条目落在别的来源名下，下次那个来源的全量同步删掉它们
+    # 🔴 subject 一律用**可信上下文**的，不用条目自己带的那个。
+    #
+    # 条目是宿主从来源数据翻译出来的，它带的 subject_id 最好的情况是冗余、
+    # 最坏的情况是把 A 的日程写进 B 的花园。可信 subject 只有一个来源：
+    # IngestContext —— 那是宿主鉴权之后填的，不经过来源数据也不经过模型。
+    # 校验一致再拒绝也行，但覆盖更彻底：没有"该信哪个"这个问题存在。
+    items = [replace(i, subject_id=context.subject_id, source=batch.source,
+                     last_seen_sync_id=batch.sync_id)
+             for i in items]
     kinds = {type(i) for i in items}
-    if kinds == {CalendarEventMirror}:
-        storage.upsert_calendar_events(subject_id=context.subject_id,
-                                       events=items)
-    elif kinds == {ReminderItemMirror}:
-        storage.upsert_reminders(subject_id=context.subject_id, items=items)
-    else:
+    if len(kinds) > 1:
         # 混着来说明宿主那边的翻译出了问题。挑一部分写进去、剩下的丢掉，
         # 会得到一份"成功了"的半份镜像。
         raise SyncContractError(
             f"一批里混了 {sorted(k.__name__ for k in kinds)}："
             f"一次同步只处理一种集合，混着来会写出一份看起来成功的半份镜像"
         )
+    # 🔴 声明的集合种类必须和条目类型对上。
+    #
+    # 不校验的话，「collection_kind=reminders + 一批日历条目」会被照单全收：
+    # 日历表被写进去了，而**提醒的同步游标往前推进了** —— 数据和游标从此
+    # 互相矛盾，下一轮增量提醒同步会以为上一轮成功了，那段提醒永远补不回来。
+    expected = _ITEM_TYPE.get(batch.collection_kind)
+    if expected is None:
+        raise SyncContractError(
+            f"不认识的 collection_kind={batch.collection_kind!r}："
+            f"只有 {CALENDAR!r} 和 {REMINDERS!r}。放过去的话，"
+            f"这批数据会落在一个没人读的地方，而同步状态说成功了"
+        )
+    actual = kinds.pop()
+    if actual is not expected:
+        raise SyncContractError(
+            f"collection_kind={batch.collection_kind!r} 声明的是 "
+            f"{expected.__name__}，实际给的是 {actual.__name__}："
+            f"照做会把数据写进一张表、把另一张表的游标往前推"
+        )
+    if expected is CalendarEventMirror:
+        storage.upsert_calendar_events(subject_id=context.subject_id,
+                                       events=items)
+    else:
+        storage.upsert_reminders(subject_id=context.subject_id, items=items)
     return len(items)
 
 

{perceptkit-0.2.8 → perceptkit-0.3.0}/src/perceptkit/retention.py

@@ -28,6 +28,12 @@ KEEP_FOREVER = None
 
 _DAY = 86400.0
 
+# ⚠️ **这张表不再是任何查询的依据。** 它是早期设计的记录，键还是旧目录名。
+# 唯一的真相是 manifest（``manifest.minimal.MINIMAL_SIGNALS``），
+# ``retention_days()`` / ``stores_history()`` 现在都从那里查。
+# 保留它是因为下面那段 weather 的注释记着一次真实的四表打架，值得留着；
+# 但**别再往里加条目，也别照它做判断**。
+#
 # signal -> 保留天数；None = 永久；不在表里 = 不进历史表
 RETENTION_DAYS: dict[str, int | None] = {
     # 永久：趋势本身就是价值
@@ -178,17 +184,64 @@ def plan_retention(
     return plan
 
 
+#: 旧目录名 -> manifest 里的信号名。
+#:
+#: 这是一张**显式的兼容表**，不是第二套目录。它存在的唯一理由是老调用方还在
+#: 用旧名；查出来的答案一律来自 manifest。
+#:
+#: 🔴 审查（2026-09-03 §9）复现的：这两个公开函数原本读的是本模块自己那张
+#: ``RETENTION_DAYS``，和 manifest 七条全对不上 ——
+#: ``retention_days("focus_state")`` 抛 KeyError（manifest 说 365）、
+#: ``retention_days("audio_route")`` 返回 90（manifest 说 7）。
+#: 接入方和工程 AI 调公开 API 会拿到错的结论，而且没有任何地方报错。
+#: **同一件事有两个真相时，公开 API 必须指向那个会被执行的那个。**
+_LEGACY_NAMES: dict[str, str] = {
+    "focus": "focus_state",
+    "playback": "music_playback",
+    "location_signal": "location_city",
+}
+
+
+def _resolve(signal: str) -> "SignalDefinition | None":
+    from .manifest.minimal import MINIMAL_SIGNALS
+    return MINIMAL_SIGNALS.get(_LEGACY_NAMES.get(signal, signal))
+
+
 def stores_history(signal: str) -> bool:
-    """这个信号进不进历史表。"""
-    return signal in RETENTION_DAYS
+    """这个信号进不进历史表。**答案来自 manifest。**"""
+    sig = _resolve(signal)
+    return bool(sig and sig.stores_history)
+
+
+def retention_days(signal: str) -> int:
+    """明细保留多少天；``PERMANENT``（-1）= 永久。
 
+    **答案来自 manifest**，不是本模块顶上那张历史表 —— 那张表现在只作为
+    早期设计的记录留着，不再是任何查询的依据。
 
-def retention_days(signal: str) -> int | None:
-    """保留天数；``KEEP_FOREVER``（None）表示永久。
+    🔴 **不进历史表的信号抛 ``KeyError``，不返回 ``None``。**
+    这是本模块早就定下的决策，改用 manifest 之后仍然成立，而且理由更硬了：
+    旧表里 ``None`` 是「永久保存」（``KEEP_FOREVER``）。静默返回 ``None``
+    的话，一个照旧词表理解的调用方会把「这个信号根本不存历史」读成
+    「永久保留」—— 两个意思正好相反，而且不会有任何地方报错。
 
-    不进历史表的信号调用这个是调用方的错，直接抛 —— 静默返回 None 会被
-    误当成「永久」，那是最坏的一种默认值。
+    问"存不存历史"用 :func:`stores_history`，那才是它该回答的问题。
     """
-    if signal not in RETENTION_DAYS:
-        raise KeyError(f"signal {signal!r} 不进历史表，先用 stores_history() 判断")
-    return RETENTION_DAYS[signal]
+    sig = _resolve(signal)
+    if sig is None or not sig.stores_history:
+        raise KeyError(
+            f"{signal!r} 不进历史表，没有明细保留期。"
+            f"想问存不存历史用 stores_history()；"
+            f"这里不返回 None —— 旧词表里 None 是「永久保存」，"
+            f"两个意思正好相反"
+        )
+    return sig.history_retention_days
+
+
+__all__ = [
+    "KEEP_FOREVER", "RETENTION_DAYS", "MEASURED_AT_TTL_SEC", "LIFECYCLE_NOTE",
+    "RetentionAction", "RetentionPlan", "SkippedSignal", "plan_retention",
+    "SKIP_NO_HISTORY", "SKIP_DETAILS_PERMANENT", "SKIP_DETAILS_UNDECLARED",
+    "SKIP_AGGREGATES_PERMANENT", "SKIP_AGGREGATES_UNDECLARED",
+    "stores_history", "retention_days",
+]

{perceptkit-0.2.8 → perceptkit-0.3.0}/tests/test_export.py

@@ -36,11 +36,11 @@ def build() -> tuple[PerceptionKit, InMemoryStorage]:
         ],
     }, context=IngestContext("u1", when("09:00")))
     s.upsert_calendar_events(subject_id="u1", events=[CalendarEventMirror(
-        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        subject_id="u1", source="ios", source_account_id="a", source_calendar_id="c",
         source_event_id="e1",
         event_fields={"title": "牙医", "start_at": when("15:00")})])
     s.upsert_reminders(subject_id="u1", items=[ReminderItemMirror(
-        subject_id="u1", source_account_id="a", source_list_id="l",
+        subject_id="u1", source="ios", source_account_id="a", source_list_id="l",
         source_reminder_id="r1",
         reminder_fields={"title": "交房租", "is_completed": True})])
     return kit, s

{perceptkit-0.2.8 → perceptkit-0.3.0}/tests/test_queries.py

@@ -480,7 +480,7 @@ def test_the_calendar_pages_like_everything_else():
     s = InMemoryStorage()
     s.upsert_calendar_events(subject_id="u1", events=[
         CalendarEventMirror(
-            subject_id="u1", source_account_id="a", source_calendar_id="c",
+            subject_id="u1", source="ios", source_account_id="a", source_calendar_id="c",
             source_event_id=f"e{i}",
             event_fields={"title": f"会 {i}", "start_at": t(f"2026-08-{i+1:02d}")})
         for i in range(5)])
@@ -497,7 +497,7 @@ def test_the_reminder_list_pages_too():
     s = InMemoryStorage()
     s.upsert_reminders(subject_id="u1", items=[
         ReminderItemMirror(
-            subject_id="u1", source_account_id="a", source_list_id="l",
+            subject_id="u1", source="ios", source_account_id="a", source_list_id="l",
             source_reminder_id=f"r{i}",
             reminder_fields={"title": f"事 {i}", "is_completed": False})
         for i in range(5)])

{perceptkit-0.2.8 → perceptkit-0.3.0}/tests/test_recurrence.py

@@ -149,7 +149,7 @@ def series(rule: dict | None = None) -> CalendarEventMirror:
     if rule is not None:
         fields["recurrence"] = rule
     return CalendarEventMirror(
-        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        subject_id="u1", source="ios", source_account_id="a", source_calendar_id="c",
         source_event_id="weekly-standup", event_fields=fields,
         recurrence_identity="series-1",
     )

{perceptkit-0.2.8 → perceptkit-0.3.0}/tests/test_regressions.py

@@ -929,7 +929,7 @@ def _reminders(storage, subject, n):
     for i in range(n):
         rid = f"r{i:04d}"
         storage.reminders[(subject, rid)] = ReminderItemMirror(
-            subject_id=subject, source_account_id="a", source_list_id="l",
+            subject_id=subject, source="ios", source_account_id="a", source_list_id="l",
             source_reminder_id=rid,
             reminder_fields={"title": rid, "due_at": base + timedelta(minutes=i)},
         )
@@ -963,7 +963,7 @@ def test_calendar_pagination_walks_the_whole_mirror():
     for i in range(600):
         eid = f"c{i:04d}"
         s.calendar[("u", eid)] = CalendarEventMirror(
-            subject_id="u", source_account_id="a", source_calendar_id="c",
+            subject_id="u", source="ios", source_account_id="a", source_calendar_id="c",
             source_event_id=eid,
             event_fields={"title": eid, "start_at": base + timedelta(minutes=i)},
         )