perceptkit 0.2.2__py3-none-any.whl

perceptkit/conformance/report.py

@@ -0,0 +1,170 @@
+"""Report adapter 的一致性检查 —— 宿主用它证明自己的上报适配器产出的信封是对的。
+
+产品规范 §20 并列的第三种 conformance。适配器指的是把 producer 的原始载荷
+（iOS 的一份快照、某个手环的一批样本）转成 ``ReportEnvelope`` 的那段代码。
+
+用法（在宿主自己的测试里）::
+
+    from perceptkit.conformance import run_report_conformance
+
+    def test_my_ios_adapter_is_conformant():
+        problems = run_report_conformance(
+            lambda payload: my_adapter.to_envelope(payload),
+            samples=[
+                (REAL_IOS_SNAPSHOT, "observed"),
+                (EMPTY_SNAPSHOT, "no_data"),
+                (PERMISSION_DENIED_SNAPSHOT, "unavailable"),
+            ],
+        )
+        assert not problems, "\\n".join(problems)
+
+---
+
+## 为什么 report 也要单独一套
+
+上报适配器是**唯一**能凭空造出事实的地方。它错了，后面每一层都在忠实地
+处理一份假数据 —— 管线不会报错，规则会照常触发，agent 会照常开口。
+
+三种最容易犯的错：
+
+    把"没测到"变成 0      "今天 0 步"和"今天没戴表"对 agent 是两句完全不同的话
+    把"没权限"变成"没数据" 前者要引导用户去开权限,后者只该闭嘴
+    补一个 occurred_at    源头没给时间就不该编一个"现在" —— 编出来的时间
+                          会让这条数据被归到错误的一天,而且永远查不出来
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, Sequence
+
+from ..contracts.availability import AVAILABILITY_STATES
+from ..contracts.errors import ContractError
+from ..contracts.report import ReportEnvelope
+
+AdapterFn = Callable[[Any], Any]
+
+REPORT_GUARANTEES: tuple[str, ...] = (
+    "R1 产出的东西必须能被 ReportEnvelope 解析",
+    "R2 每条观测的 availability 必须是三态之一",
+    "R3 `no_data` / `unavailable` 不许带值 —— 带了就是在编事实",
+    "R4 `observed` 必须带值，哪怕值是 0",
+    "R5 同一份载荷转两次要得到同样的信封（不许掺进当前时间、随机数）",
+    "R6 report_id 在一份载荷内稳定 —— 它是幂等的钥匙",
+    "R7 样本标了预期状态的话，产出的状态必须对得上",
+)
+
+REPORT_NOT_PROVABLE: tuple[str, ...] = (
+    "字段语义对不对 —— 我们能查出「这里是个数字」，查不出「这个数字是步数不是心率」",
+    "真机采集的完整性 —— 要拿真实设备抓下来的载荷跑，手写的样本证明不了覆盖面",
+    "🔴 不标预期状态的话，**查不出零填充** —— 光看信封，「真的走了 0 步」和"
+    "「没戴表被写成 0 步」长得一模一样。这正是 R7 存在的理由：只有你知道"
+    "这份载荷应该产出什么",
+)
+
+
+def _split(sample: Any) -> tuple[Any, str | None]:
+    """样本可以是裸载荷，也可以是 ``(载荷, 预期状态)``。"""
+    if (isinstance(sample, tuple) and len(sample) == 2
+            and sample[1] in AVAILABILITY_STATES):
+        return sample[0], sample[1]
+    return sample, None
+
+
+def _check_one(envelope: ReportEnvelope, label: str, problems: list[str]) -> None:
+    if not envelope.report_id:
+        problems.append(f"R6 {label}：report_id 是空的。它是幂等的钥匙，"
+                        "空的话同一份上报重传会被当成两份")
+    for i, obs in enumerate(envelope.observations):
+        where = f"{label} 第 {i + 1} 条观测（{obs.signal}）"
+        if obs.availability not in AVAILABILITY_STATES:
+            problems.append(
+                f"R2 {where}：availability={obs.availability!r} 不是三态之一"
+                f"（{sorted(AVAILABILITY_STATES)}）"
+            )
+            continue
+        has_value = obs.value is not None
+        if obs.availability != "observed" and has_value:
+            problems.append(
+                f"R3 {where}：availability={obs.availability!r} 却带了值 {obs.value!r}。"
+                "没测到就是没测到 —— 带上一个值等于在编事实"
+            )
+        if obs.availability == "observed" and not has_value:
+            # 走 parse 的路径上，信封契约自己就会拦掉这种（报成 R1）。
+            # 这里兜的是适配器直接返回 ReportEnvelope 对象的情况。
+            problems.append(
+                f"R4 {where}：说是 observed 却没有值。"
+                "如果真的测到 0，就把 0 写进来 —— 零是一个有效的观测，不是缺失"
+            )
+        if obs.occurred_at is None:
+            problems.append(
+                f"R1 {where}：没有 occurred_at。源头给不了时间的话，"
+                "这条观测就不该被造出来 —— 补一个「现在」会让它被归到错误的一天"
+            )
+
+
+def run_report_conformance(adapter: AdapterFn,
+                           samples: Sequence[Any] | Iterable[Any]) -> list[str]:
+    """拿几份真实载荷跑一遍适配器，返回问题清单（空 = 通过）。
+
+    ``samples`` 至少应该包含：一份正常的、一份**什么都没测到**的、
+    一份**权限被拒**的。后两种正是最容易被写成「返回 0」的。
+
+    每份样本可以是裸载荷，也可以是 ``(载荷, 预期状态)``。**强烈建议带上预期**：
+    不带的话这套检查查不出零填充 —— 光看信封，「真的走了 0 步」和「没戴表被
+    写成 0 步」长得一模一样，只有你知道这份载荷应该产出什么。
+    """
+    problems: list[str] = []
+    samples = list(samples)
+    if not samples:
+        problems.append(
+            "一份样本都没给。至少要三份：正常 / 什么都没测到 / 权限被拒 —— "
+            "后两种正是最容易被写成「返回 0」的"
+        )
+        return problems
+
+    for n, sample in enumerate(samples, 1):
+        payload, expected = _split(sample)
+        label = f"样本 {n}" + (f"（预期 {expected}）" if expected else "")
+        try:
+            raw = adapter(payload)
+        except Exception as exc:                   # noqa: BLE001
+            problems.append(f"R1 {label}：适配器抛了 {type(exc).__name__}({exc})")
+            continue
+        try:
+            envelope = (raw if isinstance(raw, ReportEnvelope)
+                        else ReportEnvelope.parse(raw))
+        except (ContractError, Exception) as exc:  # noqa: BLE001
+            problems.append(f"R1 {label}：产出的东西解析不了 —— {exc}")
+            continue
+
+        _check_one(envelope, label, problems)
+
+        if expected is not None:
+            got = {o.availability for o in envelope.observations}
+            if got != {expected}:
+                problems.append(
+                    f"R7 {label}：产出的状态是 {sorted(got)}，预期 {expected!r}。"
+                    + ("把「没测到」写成 observed 就是零填充 —— "
+                       "「今天 0 步」和「今天没戴表」对 agent 是两句完全不同的话"
+                       if expected != "observed" and "observed" in got else "")
+                )
+
+        # R5：同一份载荷转两次要一样。掺进 now() 或随机 id 的适配器会在这里露馅，
+        # 而那种适配器会让每次重传都变成一份"新"上报，幂等彻底失效。
+        try:
+            again = adapter(payload)
+            again = (again if isinstance(again, ReportEnvelope)
+                     else ReportEnvelope.parse(again))
+        except Exception:                          # noqa: BLE001
+            continue
+        if again.report_id != envelope.report_id:
+            problems.append(
+                f"R5 {label}：同一份载荷转两次得到了两个 report_id"
+                f"（{envelope.report_id!r} / {again.report_id!r}）。"
+                "适配器里掺了当前时间或随机数 —— 这会让每次重传都变成一份新上报，"
+                "幂等彻底失效"
+            )
+
+    return problems
+
+
+__all__ = ["REPORT_GUARANTEES", "REPORT_NOT_PROVABLE", "run_report_conformance"]

perceptkit/conformance/suite.py

@@ -0,0 +1,419 @@
+"""一致性测试套件 —— 宿主用它证明自己的 adapter 是对的。
+
+产品规范说得很准：宿主可以用任何数据库，**但需要证明能够满足相同的查询、
+幂等、重算、删除和一致性语义**。这个模块就是那个"证明"。
+
+用法（在宿主自己的测试里）::
+
+    from perceptkit.conformance import run_storage_conformance
+
+    def test_my_adapter_is_conformant():
+        problems = run_storage_conformance(lambda: MyPostgresStorage(fresh_db()))
+        assert not problems, "\\n".join(problems)
+
+---
+
+## 🔴 这套东西能证明什么、不能证明什么
+
+**能证明**：端口语义对不对、调用顺序对不对、给同样的输入是不是给同样的结果。
+
+**不能证明**（必须宿主另外做）：
+
+    真正的事务边界      需要真实数据库 + 在关键写操作之间打断点，
+                        然后【从另一条连接】观察：规则状态和发件箱
+                        要么都旧/不存在，要么都提交
+    并发下只有一个胜者   需要两条独立连接 + 同时发起，
+                        断言同 report / 同 event / 新旧 current 只有一个赢
+    崩溃恢复            需要模拟"wake 已 accepted、回执还没存下来"就断电
+
+在内存实现上这三类**永远是绿的** —— 内存天然原子、天然无并发。
+把它们当验过了，是这套东西最危险的用法。
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import date, datetime, timedelta, timezone
+from typing import Any, Callable
+
+from ..contracts import delivery as _delivery
+from ..contracts import receipt as _receipt
+from ..contracts.records import (
+    CalendarEventMirror,
+    CurrentProjection,
+    DailyAggregate,
+    DurableDedupeIdentity,
+    EventOutboxEntry,
+    ReminderItemMirror,
+    StoredObservation,
+)
+from ..contracts.receipt import WakeReceipt
+
+UTC = timezone.utc
+T0 = datetime(2026, 8, 27, 10, 0, tzinfo=UTC)
+DAY = date(2026, 8, 27)
+
+StorageFactory = Callable[[], Any]
+
+
+def _obs(**over: Any) -> StoredObservation:
+    base: dict[str, Any] = dict(
+        observation_id="obs_1", subject_id="u1", signal="steps",
+        signal_schema_version=1, source="ios", occurred_at=T0, received_at=T0,
+        availability="observed", effective_local_date=DAY,
+        typed_value={"step_count": 100},
+    )
+    base.update(over)
+    return StoredObservation(**base)
+
+
+def _current(**over: Any) -> CurrentProjection:
+    base: dict[str, Any] = dict(
+        subject_id="u1", signal="steps", dimension_key="steps",
+        typed_value={"step_count": 100}, availability="observed",
+        observed_at=T0, received_at=T0, version=0, content_digest="d1",
+    )
+    base.update(over)
+    return CurrentProjection(**base)
+
+
+def _entry(**over: Any) -> EventOutboxEntry:
+    base: dict[str, Any] = dict(
+        event_id="evt_1", subject_id="u1", definition_id="d1", definition_version=1,
+        event_type="t", occurred_at=T0, detected_at=T0, fact_snapshot={},
+    )
+    base.update(over)
+    return EventOutboxEntry(**base)
+
+
+# ---------------------------------------------------------------------------
+# 十条保证
+# ---------------------------------------------------------------------------
+
+def _g1_report_and_observation_idempotency(new: StorageFactory) -> list[str]:
+    """① 同一批上报、同一条观测重传，都不重复处理。"""
+    problems: list[str] = []
+    s = new()
+    first = s.claim_report(subject_id="u1", producer="ios", report_id="r1",
+                           payload_digest="d1", received_at=T0)
+    if first.status != _receipt.INGEST_ACCEPTED:
+        problems.append("①: 第一次认领一批新上报应该 accepted")
+    again = s.claim_report(subject_id="u1", producer="ios", report_id="r1",
+                           payload_digest="d1", received_at=T0)
+    if again.status != _receipt.INGEST_DUPLICATE:
+        problems.append("①: 同 identity 同摘要重传应该 duplicate，不重复处理")
+
+    s2 = new()
+    if not s2.append_observation(_obs()):
+        problems.append("①: 第一次写观测应该返回 True")
+    if s2.append_observation(_obs()):
+        problems.append("①: 同一个 observation_id 重复写应该返回 False 且不重复落库")
+    return problems
+
+
+def _g2_old_does_not_overwrite_new(new: StorageFactory) -> list[str]:
+    """② 迟到的旧观测不能覆盖更新的当前值。"""
+    problems: list[str] = []
+    s = new()
+    s.compare_and_put_current(_current(observed_at=T0, version=0), expected_version=-1)
+    stale = _current(observed_at=T0 - timedelta(hours=1),
+                     typed_value={"step_count": 1}, version=1)
+    # 用错误的版本号写 —— 应该被拒。真正的"旧不覆盖新"判断在 kit 的管线里，
+    # 这里验的是端口有没有提供那个把手。
+    if s.compare_and_put_current(stale, expected_version=99):
+        problems.append("②: 版本号对不上时 compare_and_put_current 必须返回 False")
+    got = s.get_current(subject_id="u1", signals=["steps"])["steps"]
+    if got and got[0].typed_value != {"step_count": 100}:
+        problems.append("②: 当前值被一次版本不匹配的写入改掉了")
+    return problems
+
+
+def _g3_same_identity_different_content_conflicts(new: StorageFactory) -> list[str]:
+    """③ 同一个上报 identity、不同内容 —— 必须报冲突，不能静默覆盖。"""
+    problems: list[str] = []
+    s = new()
+    s.claim_report(subject_id="u1", producer="ios", report_id="r1",
+                   payload_digest="d1", received_at=T0)
+    clash = s.claim_report(subject_id="u1", producer="ios", report_id="r1",
+                           payload_digest="d2", received_at=T0)
+    if clash.status != _receipt.INGEST_CONFLICT:
+        problems.append(
+            "③: 同 report_id 不同内容必须 conflict —— 静默挑一个覆盖会让"
+            "「到底哪份数据生效了」永远说不清"
+        )
+    return problems
+
+
+def _g4_permanent_aggregates_survive_replay(new: StorageFactory) -> list[str]:
+    """④ 永久聚合不会因为旧数据重放而重复累计。"""
+    problems: list[str] = []
+    s = new()
+    ident = DurableDedupeIdentity(
+        subject_id="u1", signal="steps", source="ios",
+        source_event_identity_digest="abc", first_applied_at=T0,
+    )
+    if not s.remember_identity(ident):
+        problems.append("④: 第一次记住去重身份应该返回 True")
+    if s.remember_identity(ident):
+        problems.append("④: 重复记住同一个身份应该返回 False")
+    if not s.has_seen_identity(subject_id="u1", signal="steps", source="ios",
+                               digest="abc"):
+        problems.append("④: 记过的身份必须查得到")
+    # 关键：明细被保留期清理之后，身份仍然要在 —— 否则重放会把数字加两遍。
+    s.append_observation(_obs())
+    s.delete_observations(subject_id="u1", signal="steps",
+                          before=T0 + timedelta(days=1))
+    if not s.has_seen_identity(subject_id="u1", signal="steps", source="ios",
+                               digest="abc"):
+        problems.append(
+            "④: 清理明细把去重身份一起删了 —— 旧数据重放会让永久聚合的数字"
+            "加两遍，而且无法回滚"
+        )
+    return problems
+
+
+def _g5_atomic_boundary_is_offered(new: StorageFactory) -> list[str]:
+    """⑤ 端口提供了原子边界这个把手。
+
+    🔴 **这一条只验"有没有提供"，验不出"真的原子"。** 真正的验证需要
+    真实数据库、两条连接、在关键写操作之间打断点，然后从另一条连接观察。
+    """
+    problems: list[str] = []
+    s = new()
+    try:
+        with s.transaction():
+            s.append_observation(_obs())
+    except Exception as exc:                       # noqa: BLE001
+        problems.append(f"⑤: transaction() 不可用：{exc}")
+    return problems
+
+
+def _g6_event_is_durable_before_dispatch(new: StorageFactory) -> list[str]:
+    """⑥ 事件在投递之前已经落地。"""
+    problems: list[str] = []
+    s = new()
+    if not s.enqueue_event(_entry()):
+        problems.append("⑥: 第一次入队应该返回 True")
+    pending = s.list_pending_events()
+    if len(pending) != 1 or pending[0].delivery_state != _delivery.PENDING:
+        problems.append("⑥: 刚入队的事件应该处于 pending，且能被列出来")
+    return problems
+
+
+def _g7_delivery_is_idempotent_by_event_id(new: StorageFactory) -> list[str]:
+    """⑦ 投递按 event_id 幂等；租约保证同时只有一个 worker 在处理。"""
+    problems: list[str] = []
+    s = new()
+    s.enqueue_event(_entry())
+    if s.enqueue_event(_entry()):
+        problems.append("⑦: 同一个 event_id 重复入队应该返回 False")
+
+    first = s.claim_pending_event(worker_id="w1", now=T0, lease_seconds=60)
+    if first is None:
+        problems.append("⑦: 应该能领到那个 pending 事件")
+        return problems
+    if s.claim_pending_event(worker_id="w2", now=T0, lease_seconds=60) is not None:
+        problems.append(
+            "⑦: 租约没到期时第二个 worker 不该领到同一个事件 —— "
+            "两个都投出去，用户被提醒两次"
+        )
+    taken = s.claim_pending_event(worker_id="w2", now=T0 + timedelta(seconds=120),
+                                  lease_seconds=60)
+    if taken is None:
+        problems.append("⑦: 租约到期后应该能被别的 worker 接管（原持有者可能已经死了）")
+    return problems
+
+
+def _g8_partial_sync_does_not_delete_outside_its_window(new: StorageFactory) -> list[str]:
+    """⑧ 局部同步不会误删覆盖范围外的条目。"""
+    problems: list[str] = []
+    s = new()
+    inside = CalendarEventMirror(
+        subject_id="u1", 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",
+        source_event_id="e_out", event_fields={"start_at": T0 - timedelta(days=400)},
+        last_seen_sync_id="old",
+    )
+    s.upsert_calendar_events(subject_id="u1", events=[inside, outside])
+    s.apply_source_snapshot(
+        subject_id="u1", source="ios", collection_kind="calendar", sync_id="new",
+        coverage_start=T0 - timedelta(days=1), coverage_end=T0 + timedelta(days=1),
+        snapshot_kind="full",
+    )
+    # 🔴 用端口方法验，**不摸具体实现的内部属性**。
+    #    先前这里读的是 InMemoryStorage 的 `.calendar` 字典 —— 换成任何
+    #    真实现都读不到，于是 remaining 恒为空集，这一条对每个真 adapter
+    #    都报一个假失败。一套"检查别人有没有做对"的工具，自己先得走公开接口。
+    remaining = {
+        e.source_event_id
+        for e in s.list_calendar_events(subject_id="u1", limit=100)
+    }
+    if "e_out" not in remaining:
+        problems.append(
+            "⑧: 全量同步删掉了覆盖范围【外】的条目 —— 用户会发现自己去年的"
+            "日程凭空消失，而且不可逆"
+        )
+    if "e_in" in remaining:
+        problems.append("⑧: 覆盖范围内这轮没见到的条目应该被删掉")
+
+    # 增量同步没有资格删任何东西：它只知道"变了什么"，不知道"还剩什么"。
+    s2 = new()
+    s2.upsert_calendar_events(subject_id="u1", events=[inside])
+    removed = s2.apply_source_snapshot(
+        subject_id="u1", source="ios", collection_kind="calendar", sync_id="new",
+        coverage_start=T0 - timedelta(days=1), coverage_end=T0 + timedelta(days=1),
+        snapshot_kind="incremental",
+    )
+    if removed:
+        problems.append("⑧: 增量同步不该删除任何条目")
+    return problems
+
+
+def _g9_retention_cleanup_spares_what_permanent_aggregates_need(
+    new: StorageFactory,
+) -> list[str]:
+    """⑨ 保留期清理不会破坏永久聚合的正确性。"""
+    problems: list[str] = []
+    s = new()
+    s.append_observation(_obs())
+    s.remember_identity(DurableDedupeIdentity(
+        subject_id="u1", signal="steps", source="ios",
+        source_event_identity_digest="abc", first_applied_at=T0,
+    ))
+    s.put_aggregate(DailyAggregate(
+        subject_id="u1", signal="steps", local_date=DAY, aggregation_kind="daily",
+        aggregation_version=1, typed_aggregate={"step_count": {"total": 100}},
+    ))
+    s.delete_observations(subject_id="u1", before=T0 + timedelta(days=1))
+
+    if not s.get_aggregate(subject_id="u1", signal="steps",
+                           start_date=DAY, end_date=DAY):
+        problems.append("⑨: 清理明细把永久聚合也删了")
+    if not s.has_seen_identity(subject_id="u1", signal="steps", source="ios",
+                               digest="abc"):
+        problems.append("⑨: 清理明细把去重身份也删了")
+    return problems
+
+
+def _g10_subject_isolation_and_purge(new: StorageFactory) -> list[str]:
+    """⑩ 用户之间互不可见；删除一个用户能删干净。"""
+    problems: list[str] = []
+    s = new()
+    s.append_observation(_obs(subject_id="u1", observation_id="o1"))
+    s.append_observation(_obs(subject_id="u2", observation_id="o2"))
+    s.compare_and_put_current(_current(subject_id="u1"), expected_version=-1)
+    s.compare_and_put_current(_current(subject_id="u2"), expected_version=-1)
+    s.remember_identity(DurableDedupeIdentity(
+        subject_id="u1", signal="steps", source="ios",
+        source_event_identity_digest="abc", first_applied_at=T0,
+    ))
+
+    # 跨用户负面测试：u2 不该看到 u1 的东西。
+    rows, _ = s.list_observations(subject_id="u2", signal="steps")
+    if any(o.subject_id != "u2" for o in rows):
+        problems.append("⑩: 列观测时看到了别的用户的数据")
+    if s.has_seen_identity(subject_id="u2", signal="steps", source="ios",
+                           digest="abc"):
+        problems.append("⑩: 去重身份跨用户串了 —— u2 的新数据会被当成重复丢掉")
+
+    s.purge_subject(subject_id="u1")
+    left, _ = s.list_observations(subject_id="u1", signal="steps")
+    if left:
+        problems.append("⑩: 删除用户之后还留着观测")
+    if s.has_seen_identity(subject_id="u1", signal="steps", source="ios",
+                           digest="abc"):
+        problems.append("⑩: 删除用户之后还留着去重身份")
+    still, _ = s.list_observations(subject_id="u2", signal="steps")
+    if not still:
+        problems.append("⑩: 删 u1 把 u2 的数据也删了")
+    return problems
+
+
+def _g11_both_source_mirrors_round_trip(new: StorageFactory) -> list[str]:
+    """⑪ 两个来源镜像都能写进去、读回来。
+
+    看起来不值一条。它值 —— **这一条是从一个真实现上倒推出来的**：
+
+        io 的 Postgres adapter 写提醒时读了 `r.source_created_at`，
+        读回来时又把它当构造参数传回去。`ReminderItemMirror` 上根本没有
+        这个字段（日历那个有，提醒那个没有）。写会抛、读也会抛，
+        **整条提醒镜像从来没通过过一次**，而这套套件全绿。
+
+    ⑧ 已经在用日历了，所以日历那半一直被覆盖着；提醒那半一次都没被碰过。
+    一个只测一半的套件，给出的是「都测过了」的印象。
+    """
+    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",
+        source_event_id="e1", event_fields={"title": "站会", "start_at": T0},
+    )])
+    got = list(s.list_calendar_events(subject_id="u1", limit=10))
+    if not any(e.source_event_id == "e1" for e in got):
+        problems.append("⑪: 日历条目写进去之后读不回来")
+
+    s2 = new()
+    s2.upsert_reminders(subject_id="u1", items=[ReminderItemMirror(
+        subject_id="u1", source_account_id="a", source_list_id="l",
+        source_reminder_id="r1", reminder_fields={"title": "买牛奶",
+                                                  "is_completed": False},
+    )])
+    back = list(s2.list_reminders(subject_id="u1", limit=10))
+    if not any(r.source_reminder_id == "r1" for r in back):
+        problems.append(
+            "⑪: 提醒条目写进去之后读不回来 —— 提醒镜像整条不通"
+        )
+    # 已完成的默认不出现，除非明说要。
+    s2.upsert_reminders(subject_id="u1", items=[ReminderItemMirror(
+        subject_id="u1", source_account_id="a", source_list_id="l",
+        source_reminder_id="r2", reminder_fields={"title": "交房租",
+                                                  "is_completed": True},
+    )])
+    default = {r.source_reminder_id
+               for r in s2.list_reminders(subject_id="u1", limit=10)}
+    if "r2" in default:
+        problems.append("⑪: 已完成的提醒默认不该出现在待办列表里")
+    with_done = {r.source_reminder_id for r in s2.list_reminders(
+        subject_id="u1", include_completed=True, limit=10)}
+    if "r2" not in with_done:
+        problems.append("⑪: include_completed=True 时应该能读到已完成的提醒")
+    return problems
+
+
+GUARANTEES: dict[str, Callable[[StorageFactory], list[str]]] = {
+    "①上报与观测幂等": _g1_report_and_observation_idempotency,
+    "②旧数据不覆盖新当前值": _g2_old_does_not_overwrite_new,
+    "③同身份异内容报冲突": _g3_same_identity_different_content_conflicts,
+    "④永久聚合抗重放": _g4_permanent_aggregates_survive_replay,
+    "⑤提供原子边界": _g5_atomic_boundary_is_offered,
+    "⑥事件投递前已落地": _g6_event_is_durable_before_dispatch,
+    "⑦投递按 event_id 幂等": _g7_delivery_is_idempotent_by_event_id,
+    "⑧局部同步不误删": _g8_partial_sync_does_not_delete_outside_its_window,
+    "⑨清理不破坏永久聚合": _g9_retention_cleanup_spares_what_permanent_aggregates_need,
+    "⑩用户隔离与删除": _g10_subject_isolation_and_purge,
+    "⑪两个来源镜像都能往返": _g11_both_source_mirrors_round_trip,
+}
+
+#: 这几条在内存实现上**永远是绿的**，因为内存天然原子、天然无并发。
+#: 宿主必须另外用真实数据库证明，见模块开头。
+NOT_PROVABLE_IN_MEMORY: frozenset[str] = frozenset({"⑤提供原子边界"})
+
+
+def run_storage_conformance(factory: StorageFactory) -> list[str]:
+    """跑全部十条，返回问题清单（空 = 通过）。
+
+    返回列表而不是抛异常：一次看到全部缺口，比逐个修再重跑快得多。
+    """
+    problems: list[str] = []
+    for name, check in GUARANTEES.items():
+        try:
+            problems += [f"{name} {p}" for p in check(factory)]
+        except Exception as exc:                   # noqa: BLE001
+            problems.append(f"{name}: 检查本身抛异常了 —— {type(exc).__name__}: {exc}")
+    return problems
+
+
+__all__ = ["run_storage_conformance", "GUARANTEES", "NOT_PROVABLE_IN_MEMORY"]