perceptkit 0.2.7__tar.gz → 0.3.0__tar.gz

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

@@ -1,5 +1,75 @@
 # 变更记录
 
+## 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）。**
+  写入侧原本只有四个原语，于是每个宿主自己拼「收数据 → upsert → 写同步状态
+  → 全量按范围删 → 处理失败」这一串。而这条路上**每个坑错了都不报错，
+  且大多不可逆**：
+
+      增量当全量删       用户发现自己去年的日程凭空消失了，系统一切正常
+      失败还推进游标     那段数据永远不会再被同步一次，也没人记得它缺过
+      失败还删条目       来源临时不可达被当成"来源侧删光了"
+      删了但没提交       镜像少一批、状态说成功，下轮增量不会补
+      没有覆盖范围就删   "全量"是相对某个范围说的，没范围就是删全部
+      条目没打这轮的 id  刚写进去的被自己的快照收尾删掉，一次"成功"的
+                         全量同步把镜像清空了（写这个模块时真踩到的）
+
+  ``SyncBatch`` 的字段就是审查里列的那份契约（source / collection_kind /
+  sync_id / snapshot_kind / coverage_start / coverage_end / cursor / items /
+  attempted_at / completed_at / error_code）。
+  ``PerceptionKit.sync_source_mirror(batch, context=...)`` 编排 upsert、
+  范围内删除和同步状态，三个动作在同一个事务里。
+
+  **不解析来源格式** —— 苹果日历、Google、Exchange 的条目长得完全不一样，
+  翻译成标准镜像记录仍然是宿主的活。
+
 ## 0.2.7 — 2026-09-02
 
 - **跳过原因带上稳定的 `code`（`SkippedSignal`）。** 0.2.6 的清理计划里，

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

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

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

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

{perceptkit-0.2.7 → perceptkit-0.3.0}/src/perceptkit/__init__.py

@@ -33,6 +33,9 @@ from .algorithms.attribution import attribute_episode, attribute_instant, split_
 from .catalog import CAPABILITIES, SIGNALS
 from .contracts import IngestContext, Observation, PerceptionEvent, ReportEnvelope, WakeReceipt
 from .kit import PerceptionKit
+from .processing.source_sync import (
+    FULL, INCREMENTAL, SyncBatch, SyncContractError, SyncOutcome,
+)
 from .fields import AGENT_PERCEPTION_SIGNALS, project_signal
 from .algorithms.glance import build_perception_glance
 from .algorithms.history import is_historized
@@ -53,6 +56,8 @@ from .algorithms.wake import is_wake_worthy_signal, is_significant_change, shoul
 __all__ = [
     # 接入口
     "PerceptionKit",
+    "SyncBatch", "SyncOutcome", "SyncContractError",
+    "FULL", "INCREMENTAL",
     "ReportEnvelope", "Observation", "PerceptionEvent", "WakeReceipt", "IngestContext",
     "contracts", "manifest", "ports", "processing", "rules",
     # 算法

{perceptkit-0.2.7 → 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.7 → 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.7 → 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.7 → perceptkit-0.3.0}/src/perceptkit/kit.py

@@ -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 .processing.source_sync import sync_source_mirror
 from .retention import plan_retention
 from .processing.scheduled import ScheduledOutcome, evaluate_absence, evaluate_daily
 from .queries import api as _queries
@@ -143,6 +144,23 @@ class PerceptionKit:
             now=now, allow_incomplete=allow_incomplete,
         )
 
+    def sync_source_mirror(self, batch, *, context: IngestContext):
+        """把一批日历/提醒的来源数据落进镜像，并推进同步状态。
+
+        和 :meth:`ingest` 对等的那个入口 —— 来源镜像走的是完全不同的一条路
+        （它存「来源现在有哪些条目」，不是「我们每次看到了什么」），
+        但同样有一串**错了不报错、而且大多不可逆**的规则：增量不许删、
+        全量只在自己声明的范围内删、失败的批次什么都不动也不推进游标、
+        三个动作必须在同一个事务里。
+
+        见 ``processing.source_sync`` 的模块文档 —— 每条规则都配了它对应的
+        那个故障长什么样。
+
+        **不解析来源格式。** 苹果日历、Google、Exchange 的条目长得完全不一样，
+        翻译成标准镜像记录是宿主的活。
+        """
+        return sync_source_mirror(self.storage, batch, context=context)
+
     def run_retention(
         self, *, subject_id: str, now: datetime, dry_run: bool = True,
     ) -> dict[str, Any]:

{perceptkit-0.2.7 → 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.3.0/src/perceptkit/processing/source_sync.py

@@ -0,0 +1,299 @@
+"""来源镜像的同步编排 —— 日历和提醒走的那条路。
+
+写入侧原本只有四个原语（``upsert_calendar_events`` / ``upsert_reminders`` /
+``apply_source_snapshot`` / ``put_sync_state``），没有和 ``ingest()`` 对等的
+公开入口。于是每个宿主自己拼：
+
+    收到来源数据 → 解析身份 → upsert → 写同步状态 → 全量时按范围删 → 处理失败
+
+**这条路上的每个坑，错了都不报错，而且大多不可逆。** 那正是它该收进 kit 的理由：
+
+    增量当全量删       拿一个局部窗口去删窗口外的数据 —— 用户发现自己去年的
+                       日程凭空消失了，而系统一切正常
+    失败还推进游标     这一批没拿到，游标却往前走了 —— 那段数据**永远**不会
+                       再被同步一次，而且没有任何地方记得它缺过
+    失败还删条目       来源临时不可达被当成"来源侧删光了"
+    删了但没提交       镜像里少一批条目、同步状态却说这轮成功了；
+                       下一轮增量同步不会补，因为它以为上一轮是完整的
+    没有覆盖范围就删   "全量"是相对于某个范围说的。没有范围的全量删除，
+                       删的是这个用户在这个来源下的**全部**条目
+
+所以这个模块只做一件事：把这几条规则变成一条路，而不是六个宿主各写一遍。
+
+**它不解析来源格式。** 苹果日历、Google、Exchange 的条目长得完全不一样，
+翻译成 ``CalendarEventMirror`` / ``ReminderItemMirror`` 是宿主的活 ——
+kit 只管拿到标准条目之后的顺序和边界。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from datetime import datetime
+from typing import Any, Sequence
+
+from ..contracts.context import IngestContext
+from ..contracts.records import (
+    CalendarEventMirror,
+    ReminderItemMirror,
+    SourceSyncState,
+)
+from ..ports.storage import StoragePort
+
+#: 全量：这一批覆盖范围内的条目就是来源的全部，范围内没见到的可以删。
+FULL = "full"
+#: 增量：只带了变化的部分，**一条都不许删**。
+INCREMENTAL = "incremental"
+
+CALENDAR = "calendar"
+REMINDERS = "reminders"
+
+#: 集合种类 -> 它唯一接受的条目类型。
+_ITEM_TYPE = {CALENDAR: CalendarEventMirror, REMINDERS: ReminderItemMirror}
+
+
+class SyncContractError(ValueError):
+    """这一批的声明本身自相矛盾，处理它会造成不可逆的损失。
+
+    刻意抛异常而不是返回一个"部分成功" —— 这几种情况下继续做的代价是删掉
+    用户的真实数据，而那没有"部分"可言。
+    """
+
+
+@dataclass
+class SyncBatch:
+    """一批来源镜像数据，以及它自己声明的边界。
+
+    ``coverage_start`` / ``coverage_end`` 对 ``full`` 是**必填**：
+    "全量"永远是相对于某个范围说的，没有范围的全量删除删的是全部。
+    """
+
+    source: str
+    collection_kind: str
+    sync_id: str
+    snapshot_kind: str = INCREMENTAL
+    items: Sequence[Any] = field(default_factory=tuple)
+    coverage_start: datetime | None = None
+    coverage_end: datetime | None = None
+    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
+
+
+@dataclass
+class SyncOutcome:
+    """这一轮做了什么。``failed`` 时 ``upserted`` / ``deleted`` 一定是 0。"""
+
+    upserted: int = 0
+    #: 全量收尾按范围删掉的条数。
+    deleted: int = 0
+    #: 按来源明确的 tombstone 删掉的条数。和上面一个分开数 —— 一个是
+    #: "这轮没见到所以删"，一个是"来源说删了"，混在一起就分不清
+    #: 某次异常删除是范围判断出错还是来源真的删了。
+    tombstoned: int = 0
+    failed: bool = False
+    #: 记下来的错误码，原样来自这一批。
+    error_code: str | None = None
+    #: 游标推进到哪了。失败时**保持原值**，不是 None —— 置空等于让下一轮
+    #: 从头拉一遍，而那对一个只是临时不可达的来源是纯粹的浪费。
+    cursor: str | None = None
+
+
+def _existing_cursor(storage: StoragePort, ctx: IngestContext,
+                     batch: SyncBatch) -> tuple[str | None, datetime | None]:
+    prior = storage.get_sync_state(
+        subject_id=ctx.subject_id, source=batch.source,
+        collection_kind=batch.collection_kind,
+    )
+    if prior is None:
+        return None, None
+    return prior.sync_cursor, prior.last_successful_sync_at
+
+
+def sync_source_mirror(
+    storage: StoragePort, batch: SyncBatch, *, context: IngestContext,
+) -> SyncOutcome:
+    """把一批来源镜像数据落进去，并把同步状态推到该有的位置。
+
+    顺序是固定的，而且**整个包在一个事务里**：写条目、按范围删、写同步状态
+    要么全都成立、要么全都不成立。分开提交的话，"镜像里少一批条目、
+    同步状态却说这轮成功了"就会出现，而下一轮增量同步不会去补 ——
+    它以为上一轮是完整的。
+    """
+    kind = batch.snapshot_kind or INCREMENTAL
+    if kind not in (FULL, INCREMENTAL):
+        raise SyncContractError(
+            f"snapshot_kind={kind!r}：只有 {FULL!r} 和 {INCREMENTAL!r} 两种。"
+            f"不认识的种类不能当成增量放过去 —— 万一它的本意是全量，"
+            f"该删的没删，镜像会一直留着来源已经删掉的条目"
+        )
+    if kind == FULL and batch.error_code is None and (
+            batch.coverage_start is None or batch.coverage_end is None):
+        raise SyncContractError(
+            "全量同步必须给 coverage_start 和 coverage_end。"
+            "「全量」永远是相对于某个范围说的 —— 没有范围的全量删除，"
+            "删的是这个用户在这个来源下的全部条目，且不可逆"
+        )
+    if (batch.coverage_start is not None and batch.coverage_end is not None
+            and batch.coverage_start > batch.coverage_end):
+        raise SyncContractError(
+            f"coverage_start({batch.coverage_start}) 晚于 "
+            f"coverage_end({batch.coverage_end})：这个范围是空的，"
+            f"照它删会删掉范围外的一切或者什么都不删，两种都不该猜"
+        )
+
+    prior_cursor, prior_ok_at = _existing_cursor(storage, context, batch)
+    now = batch.completed_at or batch.attempted_at or context.received_at
+
+    # ── 失败的一批：记下来，但**什么都不动** ──────────────────────────
+    #
+    # 不 upsert（这一批的内容不可信）、不删（来源临时不可达不等于来源侧删光了）、
+    # 不推进游标（推进了那段数据就永远不会被再同步一次，而且没有任何地方
+    # 记得它缺过）、不动 last_successful_sync_at（否则"日历数据已过期"
+    # 这个判断永远为假）。
+    if batch.error_code is not None:
+        with storage.transaction():
+            storage.put_sync_state(SourceSyncState(
+                subject_id=context.subject_id,
+                source=batch.source,
+                collection_kind=batch.collection_kind,
+                sync_cursor=prior_cursor,
+                coverage_start=batch.coverage_start,
+                coverage_end=batch.coverage_end,
+                snapshot_kind=kind,
+                last_attempted_at=batch.attempted_at or now,
+                last_successful_sync_at=prior_ok_at,
+                last_error_code=batch.error_code,
+            ))
+        return SyncOutcome(failed=True, error_code=batch.error_code,
+                           cursor=prior_cursor)
+
+    with storage.transaction():
+        upserted = _upsert(storage, batch, context)
+        # 来源明确的删除，全量和增量都执行 —— 它不是推断出来的。
+        tombstoned = _apply_tombstones(storage, batch, context)
+        deleted = 0
+        if kind == FULL:
+            # 只有全量才有资格删，而且只在它自己声明的范围内。
+            deleted = int(storage.apply_source_snapshot(
+                subject_id=context.subject_id,
+                source=batch.source,
+                collection_kind=batch.collection_kind,
+                sync_id=batch.sync_id,
+                coverage_start=batch.coverage_start,
+                coverage_end=batch.coverage_end,
+                snapshot_kind=kind,
+            ) or 0)
+        storage.put_sync_state(SourceSyncState(
+            subject_id=context.subject_id,
+            source=batch.source,
+            collection_kind=batch.collection_kind,
+            sync_cursor=batch.cursor if batch.cursor is not None else prior_cursor,
+            coverage_start=batch.coverage_start,
+            coverage_end=batch.coverage_end,
+            snapshot_kind=kind,
+            last_attempted_at=batch.attempted_at or now,
+            last_successful_sync_at=now,
+            # 成功了就把上一次的错误清掉 —— 留着的话，一次早就恢复的
+            # 故障会一直挂在状态里，看的人分不清是历史还是现在。
+            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)
+    if not items:
+        return 0
+    # 🔴 **这一批的条目必须打上这一批的 sync_id。**
+    #
+    # 全量收尾删的是「覆盖范围内、这轮没见到的」，判据就是这个字段。
+    # 不打的话，刚写进去的条目在同一个事务里被自己的快照收尾删掉 ——
+    # 一次"成功"的全量同步，结果是镜像空了。
+    # 这个由 kit 打，不指望宿主记得：忘了不报错，只是数据没了。
+    # 这一批声明的 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 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)
+
+
+__all__ = [
+    "CALENDAR", "REMINDERS", "FULL", "INCREMENTAL",
+    "SyncBatch", "SyncOutcome", "SyncContractError", "sync_source_mirror",
+]