perceptkit 0.2.7__tar.gz → 0.2.8__tar.gz

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

@@ -1,5 +1,29 @@
 # 变更记录
 
+## 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.2.8}/PKG-INFO

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

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

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

{perceptkit-0.2.7 → perceptkit-0.2.8}/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.2.8}/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.8/src/perceptkit/processing/source_sync.py

@@ -0,0 +1,227 @@
+"""来源镜像的同步编排 —— 日历和提醒走的那条路。
+
+写入侧原本只有四个原语（``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"
+
+
+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
+    #: 非空 = 这一批**没有成功拿到**。见 ``SyncOutcome`` 的文档。
+    error_code: str | None = None
+
+
+@dataclass
+class SyncOutcome:
+    """这一轮做了什么。``failed`` 时 ``upserted`` / ``deleted`` 一定是 0。"""
+
+    upserted: int = 0
+    deleted: 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)
+        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,
+                       cursor=batch.cursor if batch.cursor is not None
+                       else prior_cursor)
+
+
+def _upsert(storage: StoragePort, batch: SyncBatch,
+            context: IngestContext) -> int:
+    items = list(batch.items)
+    if not items:
+        return 0
+    # 🔴 **这一批的条目必须打上这一批的 sync_id。**
+    #
+    # 全量收尾删的是「覆盖范围内、这轮没见到的」，判据就是这个字段。
+    # 不打的话，刚写进去的条目在同一个事务里被自己的快照收尾删掉 ——
+    # 一次"成功"的全量同步，结果是镜像空了。
+    # 这个由 kit 打，不指望宿主记得：忘了不报错，只是数据没了。
+    items = [replace(i, 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:
+        # 混着来说明宿主那边的翻译出了问题。挑一部分写进去、剩下的丢掉，
+        # 会得到一份"成功了"的半份镜像。
+        raise SyncContractError(
+            f"一批里混了 {sorted(k.__name__ for k in kinds)}："
+            f"一次同步只处理一种集合，混着来会写出一份看起来成功的半份镜像"
+        )
+    return len(items)
+
+
+__all__ = [
+    "CALENDAR", "REMINDERS", "FULL", "INCREMENTAL",
+    "SyncBatch", "SyncOutcome", "SyncContractError", "sync_source_mirror",
+]

perceptkit-0.2.8/tests/test_source_sync.py

@@ -0,0 +1,251 @@
+"""来源镜像同步的编排规则。
+
+外部审查（2026-09-02，P0-2）："只有 Storage 原语，没有标准同步工作流"。
+成立：写入侧有四个原语但没有和 ingest() 对等的入口，于是每个宿主自己拼
+「收数据 → upsert → 写状态 → 全量按范围删 → 处理失败」这一串。
+
+这个文件测的是**规则**，不是"函数能跑"。这条路上的每个坑错了都不报错，
+而且大多不可逆 —— 用户发现自己去年的日程凭空消失了，而系统一切正常。
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from perceptkit import IngestContext, PerceptionKit
+from perceptkit.conformance import InMemoryStorage
+from perceptkit.contracts.records import CalendarEventMirror, ReminderItemMirror
+from perceptkit.processing.source_sync import (
+    FULL, INCREMENTAL, SyncBatch, SyncContractError, sync_source_mirror,
+)
+
+T0 = datetime(2026, 9, 2, 9, 0, tzinfo=timezone.utc)
+CTX = IngestContext("u1", T0)
+
+
+def _event(eid: str, at: datetime = T0) -> CalendarEventMirror:
+    return CalendarEventMirror(
+        subject_id="u1", source_account_id="a", source_calendar_id="c",
+        source_event_id=eid, event_fields={"title": eid, "start_at": at},
+        last_seen_sync_id="old",
+    )
+
+
+def _batch(**over) -> SyncBatch:
+    base = dict(source="ios", collection_kind="calendar", sync_id="s1",
+                snapshot_kind=INCREMENTAL, items=[_event("e1")])
+    base.update(over)
+    return SyncBatch(**base)
+
+
+def _state(storage):
+    return storage.get_sync_state(subject_id="u1", source="ios",
+                                  collection_kind="calendar")
+
+
+# ---------------------------------------------------------------------------
+# 增量绝不许删
+# ---------------------------------------------------------------------------
+
+def test_an_incremental_batch_never_deletes_anything():
+    """拿一个局部窗口去删窗口外的数据 —— 用户发现自己去年的日程凭空消失了。"""
+    s = InMemoryStorage()
+    s.upsert_calendar_events(subject_id="u1", events=[_event("old-one")])
+    # ⚠️ 这一批**带着覆盖范围**。增量给范围是合法的（它说明这批数据来自哪一段），
+    #    但它仍然不许删。不给范围的话这条测试会因为错误的原因通过：
+    #    就算删除逻辑真的跑了，没有范围也删不掉任何东西。
+    out = sync_source_mirror(s, _batch(
+        items=[_event("e1")],
+        coverage_start=T0 - timedelta(days=1), coverage_end=T0 + timedelta(days=1),
+    ), context=CTX)
+    assert out.deleted == 0
+    left = {e.source_event_id for e in s.list_calendar_events(subject_id="u1", limit=50)}
+    assert "old-one" in left, "增量同步把范围内的旧条目删了"
+
+
+def test_a_host_that_forgot_the_incremental_guard_is_still_safe():
+    """端口契约要求 ``snapshot_kind != full`` 时一条都不删，内存参考实现也照做了。
+
+    但**这条不能指望每个宿主都实现对** —— 忘了就是删掉用户范围内的全部
+    日程，不可逆。所以 kit 这一层压根不调用它。
+
+    这里用一个"忘了那条守卫"的宿主来证明：kit 根本不会走到那个调用。
+    """
+    class _ForgetfulHost(InMemoryStorage):
+        called_with: list = []
+
+        def apply_source_snapshot(self, **kw):
+            _ForgetfulHost.called_with.append(kw["snapshot_kind"])
+            return super().apply_source_snapshot(**{**kw, "snapshot_kind": FULL})
+
+    _ForgetfulHost.called_with = []
+    s = _ForgetfulHost()
+    s.upsert_calendar_events(subject_id="u1", events=[_event("old-one")])
+    sync_source_mirror(s, _batch(
+        items=[_event("e1")],
+        coverage_start=T0 - timedelta(days=1), coverage_end=T0 + timedelta(days=1),
+    ), context=CTX)
+    assert _ForgetfulHost.called_with == [], (
+        "增量批次调到了快照收尾 —— 宿主只要少一条守卫就会删掉真实数据")
+    left = {e.source_event_id for e in s.list_calendar_events(subject_id="u1", limit=50)}
+    assert "old-one" in left
+
+
+def test_a_full_batch_deletes_inside_its_coverage():
+    s = InMemoryStorage()
+    s.upsert_calendar_events(subject_id="u1", events=[_event("gone")])
+    out = sync_source_mirror(s, _batch(
+        snapshot_kind=FULL, items=[_event("e1")],
+        coverage_start=T0 - timedelta(days=1), coverage_end=T0 + timedelta(days=1),
+    ), context=CTX)
+    left = {e.source_event_id for e in s.list_calendar_events(subject_id="u1", limit=50)}
+    assert "gone" not in left and "e1" in left
+    assert out.deleted >= 1
+
+
+def test_a_full_batch_without_coverage_is_refused():
+    """「全量」永远是相对于某个范围说的。没有范围的全量删除删的是全部。"""
+    s = InMemoryStorage()
+    with pytest.raises(SyncContractError, match="coverage"):
+        sync_source_mirror(s, _batch(snapshot_kind=FULL, coverage_start=None,
+                                     coverage_end=None), context=CTX)
+
+
+def test_an_unknown_snapshot_kind_is_refused_not_treated_as_incremental():
+    """不认识的种类当成增量放过去：万一它的本意是全量，该删的没删，
+    镜像会一直留着来源已经删掉的条目。"""
+    s = InMemoryStorage()
+    with pytest.raises(SyncContractError, match="snapshot_kind"):
+        sync_source_mirror(s, _batch(snapshot_kind="partial"), context=CTX)
+
+
+def test_an_inverted_coverage_window_is_refused():
+    s = InMemoryStorage()
+    with pytest.raises(SyncContractError, match="coverage_start"):
+        sync_source_mirror(s, _batch(
+            snapshot_kind=FULL, coverage_start=T0 + timedelta(days=1),
+            coverage_end=T0 - timedelta(days=1)), context=CTX)
+
+
+# ---------------------------------------------------------------------------
+# 失败的一批：记下来，但什么都不动
+# ---------------------------------------------------------------------------
+
+def test_a_failed_batch_changes_no_data():
+    """来源临时不可达 ≠ 来源侧删光了。"""
+    s = InMemoryStorage()
+    s.upsert_calendar_events(subject_id="u1", events=[_event("keep")])
+    out = sync_source_mirror(s, _batch(
+        snapshot_kind=FULL, error_code="transport_timeout",
+        items=[_event("e1")],
+        coverage_start=T0 - timedelta(days=1), coverage_end=T0 + timedelta(days=1),
+    ), context=CTX)
+    assert out.failed and out.upserted == 0 and out.deleted == 0
+    left = {e.source_event_id for e in s.list_calendar_events(subject_id="u1", limit=50)}
+    assert left == {"keep"}, "失败的一批把数据写进去了"
+
+
+def test_a_failed_batch_does_not_advance_the_cursor():
+    """推进了那段数据就**永远**不会再被同步一次，而且没有任何地方记得它缺过。"""
+    s = InMemoryStorage()
+    sync_source_mirror(s, _batch(cursor="page-1"), context=CTX)
+    assert _state(s).sync_cursor == "page-1"
+
+    sync_source_mirror(s, _batch(cursor="page-2", error_code="http_503"),
+                       context=CTX)
+    assert _state(s).sync_cursor == "page-1", "失败还把游标推到了 page-2"
+
+
+def test_a_failed_batch_does_not_touch_last_successful_sync_at():
+    """否则「日历数据已过期」这个判断永远为假 —— 同步挂了三天，
+    界面还在说这是最新完整的数据。"""
+    s = InMemoryStorage()
+    sync_source_mirror(s, _batch(), context=CTX)
+    ok_at = _state(s).last_successful_sync_at
+    assert ok_at is not None
+
+    later = IngestContext("u1", T0 + timedelta(days=3))
+    sync_source_mirror(s, _batch(error_code="auth_revoked"), context=later)
+    st = _state(s)
+    assert st.last_successful_sync_at == ok_at
+    assert st.last_error_code == "auth_revoked"
+    assert st.last_attempted_at is not None
+
+
+def test_a_success_clears_a_stale_error_code():
+    """留着的话，一次早就恢复的故障会一直挂在状态里，看的人分不清
+    是历史还是现在。"""
+    s = InMemoryStorage()
+    sync_source_mirror(s, _batch(error_code="http_503"), context=CTX)
+    assert _state(s).last_error_code == "http_503"
+    sync_source_mirror(s, _batch(), context=CTX)
+    assert _state(s).last_error_code is None
+
+
+# ---------------------------------------------------------------------------
+# 三个动作在同一个事务里
+# ---------------------------------------------------------------------------
+
+def test_the_whole_round_is_one_transaction():
+    """分开提交的话，「镜像里少一批条目、同步状态却说这轮成功了」就会出现，
+    而下一轮增量同步不会去补 —— 它以为上一轮是完整的。"""
+    s = InMemoryStorage()
+    before = s.transactions_opened
+    sync_source_mirror(s, _batch(
+        snapshot_kind=FULL, coverage_start=T0 - timedelta(days=1),
+        coverage_end=T0 + timedelta(days=1)), context=CTX)
+    assert s.transactions_opened == before + 1, "写条目/删/写状态没在同一个事务里"
+
+
+def test_a_mixed_batch_is_refused():
+    """挑一部分写进去、剩下的丢掉，会得到一份"成功了"的半份镜像。"""
+    s = InMemoryStorage()
+    mixed = [_event("e1"), ReminderItemMirror(
+        subject_id="u1", source_account_id="a", source_list_id="l",
+        source_reminder_id="r1", reminder_fields={"title": "买牛奶"})]
+    with pytest.raises(SyncContractError, match="混"):
+        sync_source_mirror(s, _batch(items=mixed), context=CTX)
+
+
+def test_reminders_go_down_the_reminder_path():
+    s = InMemoryStorage()
+    item = ReminderItemMirror(
+        subject_id="u1", source_account_id="a", source_list_id="l",
+        source_reminder_id="r1",
+        reminder_fields={"title": "买牛奶", "is_completed": False})
+    out = sync_source_mirror(s, SyncBatch(
+        source="ios", collection_kind="reminders", sync_id="s1", items=[item]),
+        context=CTX)
+    assert out.upserted == 1
+    assert [r.source_reminder_id
+            for r in s.list_reminders(subject_id="u1", limit=10)] == ["r1"]
+
+
+def test_the_kit_exposes_it_next_to_ingest():
+    """和 ingest() 对等的入口 —— 这条是审查里点名要的。"""
+    s = InMemoryStorage()
+    kit = PerceptionKit(storage=s)
+    out = kit.sync_source_mirror(_batch(), context=CTX)
+    assert out.upserted == 1
+
+
+def test_a_full_sync_does_not_delete_the_items_it_just_wrote():
+    """全量收尾删的是「覆盖范围内、这轮没见到的」，判据是 last_seen_sync_id。
+
+    这批条目不打上这一批的 sync_id，刚写进去的就会在同一个事务里被自己的
+    快照收尾删掉 —— 一次"成功"的全量同步，结果是镜像空了。
+
+    这条是写这个文件时真踩到的：宿主传进来的条目带着上一轮的 sync_id，
+    orchestration 原样 upsert，然后 apply_source_snapshot 把它们全删了。
+    """
+    s = InMemoryStorage()
+    stale = [_event("e1"), _event("e2")]          # helper 带的是 last_seen_sync_id="old"
+    assert all(e.last_seen_sync_id == "old" for e in stale)
+    out = sync_source_mirror(s, _batch(
+        snapshot_kind=FULL, sync_id="round-7", items=stale,
+        coverage_start=T0 - timedelta(days=1), coverage_end=T0 + timedelta(days=1),
+    ), context=CTX)
+    left = {e.source_event_id for e in s.list_calendar_events(subject_id="u1", limit=50)}
+    assert left == {"e1", "e2"}, f"全量同步把自己刚写的条目删了，剩下 {left}"
+    assert out.upserted == 2

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

@@ -16,7 +16,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
 ]
 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.7"
+version = "0.2.8"
 source = { editable = "." }
 
 [package.optional-dependencies]