perceptkit 0.2.2__py3-none-any.whl

perceptkit/catalog.py

@@ -0,0 +1,252 @@
+"""Capability catalog — the single source of truth for Extended Perception.
+
+Every perceptual capability is declared here ONCE. This drives all the generic
+machinery:
+  - the report endpoint (which input fields are accepted, which permission gates
+    them, how raw values resolve to labels, which state fields they produce)
+  - the snapshot endpoint (which fields are cheap context, their freshness TTL)
+  - wake triggering (which capabilities are wake sources + their debounce)
+  - the transparency UI (label + tier + default-on per capability)
+
+Adding a Tier 2 capability = adding rows here + (if it has query tools) a thin
+MCP pass-through. No changes to service/routes logic.
+
+Privacy: capabilities whose `resolver` is set accept RAW values (lat/lon, ssid,
+bundle id) and resolve them to coarse labels via the user's perception_config.
+The raw value is used transiently and never written to perception_state, so the
+agent only ever sees labels.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Capability:
+    """One perceptual ability (always available; authorization is implicit in
+    whether the client reports a value — see the host's design docs for the
+    reasoning behind implicit, report-based authorization)."""
+    key: str                 # canonical capability key
+    label: str               # human copy for the transparency UI
+    tier: int                # 1 = ships with V2, 2 = follow-up
+    wake_source: bool = False
+    debounce_sec: float = 0.0
+    context_field: bool = False   # appears in cheap wake snapshot
+    query_tool: bool = False      # agent pulls on demand
+
+
+@dataclass(frozen=True)
+class Signal:
+    """One field the client may report, mapped to its capability + processing."""
+    input: str                       # key inside report `signals`
+    capability: str                  # permission key gating it
+    outputs: tuple[str, ...]         # state field name(s) produced
+    resolver: str | None = None      # name in resolve.RESOLVERS, or None (store as-is)
+    ttl_sec: float = 600.0           # snapshot freshness; older -> null
+    significant: bool = True         # value change can trigger a wake (if wake_source)
+
+
+# ---------------------------------------------------------------------------
+# Capabilities
+# ---------------------------------------------------------------------------
+
+CAPABILITIES: dict[str, Capability] = {c.key: c for c in [
+    # --- always-on (no iOS permission) ---
+    Capability("time", "本地时间", 1, context_field=True),
+    Capability("device", "电量", 1, context_field=True),
+    # Starting/stopping a user-initiated share is a discrete presence edge. A
+    # shared cooldown prevents rapid iOS on/off flapping from producing a burst
+    # of proactive turns.
+    Capability("broadcast", "屏幕采集状态", 1,
+               wake_source=True, debounce_sec=60.0, context_field=True),
+
+    # --- permissioned ---
+    Capability("location", "你大概在哪里（只看地点标签，不看具体地址）", 1,
+               wake_source=True, debounce_sec=60.0, context_field=True, query_tool=True),
+    # Motion remains pullable context, but is intentionally not a wake source.
+    # It changes too frequently to justify interrupting the user — see
+    # wake.NOT_WAKE_WORTHY_SIGNALS, which suppresses it for the same reason.
+    Capability("motion", "你在动还是静止", 1, context_field=True),
+    Capability("calendar", "日历下一场日程", 1, context_field=True, query_tool=True),
+    Capability("now_playing", "你在听的音乐", 1, context_field=True, query_tool=True),
+    Capability("focus", "专注模式", 1, context_field=True),
+    Capability("audio_route", "音频输出路由", 2, query_tool=True),
+    # One switch covers BOTH resolutions (current field + the recent_apps
+    # history tool), so the copy has to say so — otherwise the user thinks they
+    # are allowing "which app now" and is actually allowing a usage trajectory.
+    Capability("app", "你最近打开了哪些 app（通过 iOS 快捷指令上报，含最近使用记录）", 1,
+               context_field=True, query_tool=True),
+    Capability("weather", "粗天气", 2, query_tool=True),
+    Capability("photos", "你拍的照片", 2, wake_source=True, query_tool=True),
+    Capability("reminders", "提醒事项", 2, query_tool=True),
+    Capability("health_sleep", "睡眠", 2, query_tool=True),
+    Capability("health_workout", "运动", 2, query_tool=True),
+    Capability("health_vitals", "身体趋势", 2, query_tool=True),
+    Capability("health_activity", "活动量（能量/锻炼/站立/正念）", 2, query_tool=True),
+    Capability("health_body", "身体测量（体重/BMI/体脂/身高）", 2, query_tool=True),
+    Capability("health_metabolic", "代谢点值（血糖/血压）", 2, query_tool=True),
+    Capability("health_cycle", "经期", 2, query_tool=True),
+    Capability("health_mood", "心情 / State of Mind", 2, query_tool=True),
+]}
+
+
+# ---------------------------------------------------------------------------
+# Signals (report inputs) — keyed by the iOS context_snapshot `key`.
+# `data` (a JSON string) parses into the shapes in perception-report-fields.md;
+# the resolver picks out the label/state fields and DISCARDS raw/precise fields
+# (coordinates, BSSID, placemark address) so the agent only sees coarse state.
+# ---------------------------------------------------------------------------
+
+SIGNALS: dict[str, Signal] = {s.input: s for s in [
+    # always-on
+    Signal("time", "time", ("local_time", "timezone", "locale"),
+           resolver="time", ttl_sec=300.0, significant=False),
+    Signal("battery", "device", ("battery_level", "charging", "low_power_mode"),
+           resolver="battery", ttl_sec=600.0, significant=False),
+    Signal("broadcast", "broadcast", ("broadcast_state", "broadcast_active"),
+           resolver="broadcast", ttl_sec=300.0, significant=True),
+    Signal("focus", "focus", ("focus_authorization_status", "in_focus"),
+           resolver="focus_presence", ttl_sec=300.0, significant=False),
+
+    # permissioned
+    Signal("location_signal", "location", ("place_label", "wifi_label", "country", "locality", "wifi_anchor_id"),
+           resolver="location_signal", ttl_sec=900.0),
+    Signal("motion_state", "motion", ("motion_state",), ttl_sec=300.0),
+    Signal("calendar_next_event", "calendar", ("calendar_next_event", "calendar_events", "calendar_events_truncated"),
+           ttl_sec=3600.0, significant=False),
+    Signal("playback", "now_playing", ("now_playing",),
+           ttl_sec=600.0, significant=False),
+    Signal("audio_route", "audio_route", ("output_type", "is_bluetooth", "device_name"),
+           resolver="audio_route", ttl_sec=600.0, significant=False),
+    Signal("weather", "weather",
+           ("condition", "temperature", "apparent_temperature", "humidity",
+            "precipitation_chance", "uv_index", "is_daylight", "alerts"),
+           resolver="weather", ttl_sec=1800.0, significant=False),
+    Signal("reminders", "reminders",
+           ("next_reminder", "reminders", "overdue_count", "due_today_count", "reminders_truncated"),
+           ttl_sec=3600.0, significant=False),
+    Signal("health_sleep", "health_sleep",
+           ("asleep_minutes", "core_minutes", "deep_minutes", "rem_minutes"),
+           resolver="health_sleep", ttl_sec=86400.0, significant=False),
+    Signal("health_workout", "health_workout", ("workout_type", "duration_min", "count_today"),
+           resolver="health_workout", ttl_sec=86400.0, significant=False),
+    Signal("health_vitals", "health_vitals",
+           ("resting_heart_rate", "step_count", "current_heart_rate", "hrv_sdnn_ms",
+            "respiratory_rate", "oxygen_saturation_pct", "vo2_max"),
+           resolver="health_vitals", ttl_sec=3600.0, significant=False),
+    Signal("health_activity", "health_activity",
+           ("active_energy_kcal", "exercise_minutes", "stand_minutes", "mindful_minutes"),
+           ttl_sec=3600.0, significant=False),
+    Signal("health_body", "health_body",
+           ("weight_kg", "bmi", "body_fat_pct", "height_cm"),
+           ttl_sec=86400.0, significant=False),
+    Signal("health_metabolic", "health_metabolic",
+           ("blood_glucose_mmol_l", "blood_pressure_systolic", "blood_pressure_diastolic"),
+           ttl_sec=86400.0, significant=False),
+    Signal("health_cycle", "health_cycle",
+           ("flow_level", "is_active_period"),
+           ttl_sec=86400.0, significant=False),
+    Signal("health_mood", "health_mood",
+           ("valence", "valence_classification", "kind", "label_count", "recorded_today"),
+           ttl_sec=86400.0, significant=False),
+    # `app` is reported via the GET /app_open + /app_close shortcut endpoints
+    # (not /report); this entry exists so app_name/app_category/app_state appear
+    # in the snapshot with a TTL. 900s, not the 300s this used to be: an app
+    # session routinely outlives a 5-minute window, so a shorter TTL made the
+    # agent see app_name=None for any turn that wasn't right after a launch.
+    # `app_state` is what distinguishes "still in it" (foreground) from "just
+    # left it" (closed); `recent_apps` covers anything older.
+    #
+    # NOTE: this `app_state` (values "foreground" / "closed" / null) is about
+    # some OTHER app on the user's phone — the one the iOS Shortcut just
+    # opened or closed. It is UNRELATED to any `app_state` field a host's own
+    # scene-phase tracking might use for ITS OWN foreground/background/inactive
+    # phase. Same name, different namespace (perception_state field vs. a
+    # host-internal event payload), no functional overlap — don't assume they
+    # can be compared or merged.
+    Signal("app", "app", ("app_name", "app_category", "app_state"),
+           ttl_sec=900.0, significant=False),
+]}
+
+
+# Back-compat aliases: canonical capability names also map to the iOS key.
+KEY_ALIASES = {
+    "location": "location_signal",
+    "motion": "motion_state",
+    "now_playing": "playback",
+    "calendar": "calendar_next_event",
+}
+
+# iOS keys that carry only null placeholders (frontmost_app/silent_mode/focus/
+# precise_unlock — not obtainable on iOS). Accepted and silently ignored.
+IGNORED_KEYS = {"unsupported"}
+
+# Composite report keys whose `data` expands into several signals. (none now —
+# battery is its own iOS key.)
+COMPOSITE_KEYS: dict[str, list[str]] = {}
+
+
+# perception_items kinds (collection-style data; see migration 0002) and the
+# capability that gates the GENERIC /items endpoint for each kind.
+# NOTE: "photo" is intentionally ABSENT from KIND_CAPABILITY — photos must go
+# through the dedicated /photo/evaluate flow, which stores the encrypted
+# envelope in the frame channel. Allowing kind=photo via /items would let a
+# caller inject a confirmed photo doc without the envelope path.
+# (calendar is reported via /report, not /items.)
+KIND_CAPABILITY = {
+    "workout": "health_workout",
+    "sleep": "health_sleep",
+    "vitals": "health_vitals",
+}
+
+# Burst de-dup backstop. Clustering is primarily done ON DEVICE (iOS collapses a
+# 30s burst and uploads only the representative frame); this window is the
+# server-side safety net so a client that uploads several still wakes once.
+PHOTO_CLUSTER_SEC = 30.0
+
+# scene_hint — the canonical enum shared with the iOS Vision classifier. The
+# client MUST emit one of these strings; anything else is treated as "other".
+# V2 removes the old platform hard block: sensitive hints are metadata for the
+# companion's expression policy, not a perception gate.
+SCENE_HINTS = (
+    # non-sensitive — may reach the agent
+    "landscape", "food", "people", "pet", "activity", "object", "art",
+    "text_note", "other",
+    # contextual
+    "private", "receipt",
+    # objectively sensitive
+    "document", "id_card", "medical", "screenshot",
+)
+SENSITIVE_PHOTO_SCENES = {"private", "receipt", "document", "id_card", "medical", "screenshot"}
+
+# Extended on-device metadata the iOS Vision pass may include. The runtime does
+# not use these fields as a gate; they are passed through as context for the
+# agent's own judgment and voice.
+PHOTO_METADATA_FIELDS = (
+    "has_faces", "face_count", "scene_hint", "scene_confidence",
+    "time_of_day", "is_burst", "is_indoor", "has_text_block", "is_screenshot",
+    # Stable per-photo identity + capture time. Both are new; older clients
+    # simply omit them and every consumer must treat them as optional.
+    #
+    # `source_event_id` is an on-device HMAC of PHAsset.localIdentifier under a
+    # device-local random key -- stable across re-reports, never reversible to
+    # the user's library. It is deliberately NOT the envelope id: that one is
+    # bound into the ciphertext's AAD and must stay random.
+    #
+    # `occurred_at` is when the photo was taken, which is not when it reaches
+    # us -- an import backfills months of photos in one session.
+    "source_event_id", "occurred_at",
+)
+# "Back after long lock" wake threshold.
+UNLOCK_BACK_THRESHOLD_SEC = 1800.0  # 30 min
+
+# Legacy recent app-open rows surfaced in the snapshot (folds the standalone
+# /app_usage read; capped to keep the wake-attached snapshot small). The merged
+# TTL-bounded open/close trajectory is exposed separately as recent_app_events.
+RECENT_APPS_LIMIT = 10
+
+# Explicit `perception.recent_apps` pulls merge the existing open/close streams,
+# but an agent asking "what have I been using today?" wants more than the wake
+# budget.
+RECENT_APPS_TOOL_LIMIT = 20
+RECENT_APPS_TOOL_MAX = 100

perceptkit/conformance/__init__.py

@@ -0,0 +1,28 @@
+"""一致性测试工具。
+
+    memory  内存版 StoragePort —— **只是测试工具,不是生产实现**
+    suite   storage adapter：十条一致性保证
+    wake    wake adapter：回执形状与幂等
+    report  report adapter：producer 产出的信封本身对不对
+
+产品规范 §20 把这三种 adapter conformance 并列为最低交付物。
+
+🔴 内存实现天然原子、天然没有并发,所以它**验不出**真实数据库的事务边界和
+隔离级别。"RuleState 和 Outbox 必须同事务"这类保证在这里永远是绿的。
+宿主必须另外用真实数据库 + 两条独立连接 + 在关键写操作之间打断点来证明。
+"""
+from __future__ import annotations
+
+from .memory import InMemoryStorage
+from .suite import GUARANTEES, NOT_PROVABLE_IN_MEMORY, run_storage_conformance
+from .report import (
+    REPORT_GUARANTEES, REPORT_NOT_PROVABLE, run_report_conformance,
+)
+from .wake import WAKE_GUARANTEES, WAKE_NOT_PROVABLE, run_wake_conformance
+
+__all__ = [
+    "InMemoryStorage",
+    "run_storage_conformance", "GUARANTEES", "NOT_PROVABLE_IN_MEMORY",
+    "run_wake_conformance", "WAKE_GUARANTEES", "WAKE_NOT_PROVABLE",
+    "run_report_conformance", "REPORT_GUARANTEES", "REPORT_NOT_PROVABLE",
+]

perceptkit/conformance/memory.py

@@ -0,0 +1,364 @@
+"""内存版存储 —— **只是测试工具，不是生产实现。**
+
+它存在的意义是让宿主在写自己的 adapter 之前，先有一个能跑通的参照，
+以及让 kit 自己的管线测试不依赖任何数据库。
+
+🔴 **它验不出真正的事务边界和隔离级别。** 内存实现天然是原子的、天然没有
+并发 —— "RuleState 和 Outbox 必须同事务"这类保证，在这里永远是绿的，
+不代表真实数据库上也绿。宿主必须另外用真实数据库、两条独立连接、
+在关键写操作之间打断点，才能证明那条保证成立。
+
+在这里绿 = 端口语义、调用顺序、确定性没问题。
+仅此而已。
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from datetime import date, datetime, timezone
+
+#: 排序时给「没有时间」的条目垫底用的哨兵，不参与任何业务判断。
+_EPOCH = datetime(1, 1, 1, tzinfo=timezone.utc)
+from typing import Any, Iterator, Sequence
+
+from ..contracts import delivery as _delivery
+from ..contracts.records import (
+    CalendarEventMirror,
+    CurrentProjection,
+    DailyAggregate,
+    DurableDedupeIdentity,
+    EventOutboxEntry,
+    ReminderItemMirror,
+    SourceSyncState,
+    StoredObservation,
+)
+from ..contracts.receipt import (
+    INGEST_ACCEPTED,
+    INGEST_CONFLICT,
+    INGEST_DUPLICATE,
+    IngestReceipt,
+    WakeReceipt,
+)
+
+
+class InMemoryStorage:
+    """把 :class:`~perceptkit.ports.storage.StoragePort` 实现在几个字典上。"""
+
+    def __init__(self) -> None:
+        self.reports: dict[tuple[str, str, str], IngestReceipt] = {}
+        self.observations: dict[str, StoredObservation] = {}
+        self.identities: set[tuple[str, str, str, str]] = set()
+        self.current: dict[tuple[str, str, str], CurrentProjection] = {}
+        self.aggregates: dict[tuple[str, str, date, str, int], DailyAggregate] = {}
+        self.calendar: dict[tuple, CalendarEventMirror] = {}
+        self.reminders: dict[tuple, ReminderItemMirror] = {}
+        self.sync_state: dict[tuple[str, str, str], SourceSyncState] = {}
+        self.rule_state: dict[tuple[str, str, str], dict[str, Any]] = {}
+        self.outbox: dict[str, EventOutboxEntry] = {}
+        self.receipts: list[WakeReceipt] = []
+        #: 测试用：数一数事务嵌套层数，验证调用方确实把该原子的操作包起来了。
+        self.transaction_depth = 0
+        self.transactions_opened = 0
+
+    # -- 事务 ------------------------------------------------------------
+
+    @contextmanager
+    def transaction(self) -> Iterator[None]:
+        """内存里没有真正的回滚 —— 只记录边界，供测试断言"该包起来的确实包了"。
+
+        **不要把这里的绿当成"原子性验过了"。** 见模块开头。
+        """
+        self.transaction_depth += 1
+        self.transactions_opened += 1
+        try:
+            yield
+        finally:
+            self.transaction_depth -= 1
+
+    # -- 批级幂等 --------------------------------------------------------
+
+    def claim_report(self, *, subject_id, producer, report_id, payload_digest,
+                     received_at) -> IngestReceipt:
+        key = (subject_id, producer, report_id)
+        prior = self.reports.get(key)
+        if prior is not None:
+            status = (INGEST_DUPLICATE if prior.payload_digest == payload_digest
+                      else INGEST_CONFLICT)
+            return IngestReceipt(
+                subject_id=subject_id, producer=producer, report_id=report_id,
+                payload_digest=prior.payload_digest, received_at=prior.received_at,
+                status=status,
+                error_code=None if status == INGEST_DUPLICATE else "digest_mismatch",
+                observations_applied=0,
+            )
+        fresh = IngestReceipt(
+            subject_id=subject_id, producer=producer, report_id=report_id,
+            payload_digest=payload_digest, received_at=received_at,
+            status=INGEST_ACCEPTED,
+        )
+        self.reports[key] = fresh
+        return fresh
+
+    # -- 观测 ------------------------------------------------------------
+
+    def append_observation(self, observation: StoredObservation) -> bool:
+        if observation.observation_id in self.observations:
+            return False
+        self.observations[observation.observation_id] = observation
+        return True
+
+    def list_observations(self, *, subject_id, signal, start=None, end=None,
+                          cursor=None, limit=100):
+        rows = sorted(
+            (o for o in self.observations.values()
+             if o.subject_id == subject_id and o.signal == signal
+             and (start is None or o.occurred_at >= start)
+             and (end is None or o.occurred_at <= end)),
+            key=lambda o: (o.occurred_at, o.observation_id),
+        )
+        offset = int(cursor) if cursor else 0
+        page = rows[offset:offset + limit]
+        nxt = str(offset + limit) if offset + limit < len(rows) else None
+        return page, nxt
+
+    def delete_observations(self, *, subject_id, signal=None, before=None) -> int:
+        doomed = [
+            k for k, o in self.observations.items()
+            if o.subject_id == subject_id
+            and (signal is None or o.signal == signal)
+            and (before is None or o.occurred_at < before)
+        ]
+        for k in doomed:
+            del self.observations[k]
+        return len(doomed)
+
+    # -- 去重身份 --------------------------------------------------------
+
+    def remember_identity(self, identity: DurableDedupeIdentity) -> bool:
+        key = (identity.subject_id, identity.signal, identity.source,
+               identity.source_event_identity_digest)
+        if key in self.identities:
+            return False
+        self.identities.add(key)
+        return True
+
+    def has_seen_identity(self, *, subject_id, signal, source, digest) -> bool:
+        return (subject_id, signal, source, digest) in self.identities
+
+    # -- 当前值 ----------------------------------------------------------
+
+    def get_current(self, *, subject_id, signals):
+        out: dict[str, list[CurrentProjection]] = {s: [] for s in signals}
+        for (subj, sig, _dim), proj in self.current.items():
+            if subj == subject_id and sig in out:
+                out[sig].append(proj)
+        return out
+
+    def compare_and_put_current(self, projection, *, expected_version) -> bool:
+        key = (projection.subject_id, projection.signal, projection.dimension_key)
+        existing = self.current.get(key)
+        actual = existing.version if existing else -1
+        if actual != expected_version:
+            return False
+        self.current[key] = projection
+        return True
+
+    # -- 聚合 ------------------------------------------------------------
+
+    def get_aggregate(self, *, subject_id, signal, start_date, end_date,
+                      aggregation_kind=None):
+        return [
+            a for (subj, sig, day, kind, _v), a in self.aggregates.items()
+            if subj == subject_id and sig == signal
+            and start_date <= day <= end_date
+            and (aggregation_kind is None or kind == aggregation_kind)
+        ]
+
+    def put_aggregate(self, aggregate: DailyAggregate) -> None:
+        self.aggregates[(
+            aggregate.subject_id, aggregate.signal, aggregate.local_date,
+            aggregate.aggregation_kind, aggregate.aggregation_version,
+        )] = aggregate
+
+    # -- 来源镜像 --------------------------------------------------------
+
+    def get_sync_state(self, *, subject_id, source, collection_kind):
+        return self.sync_state.get((subject_id, source, collection_kind))
+
+    def put_sync_state(self, state: SourceSyncState) -> None:
+        self.sync_state[(state.subject_id, state.source, state.collection_kind)] = state
+
+    def upsert_calendar_events(self, *, subject_id, events) -> None:
+        for e in events:
+            self.calendar[(subject_id, 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
+
+    def list_calendar_events(self, *, subject_id, start=None, end=None, limit=50):
+        rows = [v for k, v in self.calendar.items() if k[0] == subject_id]
+        keep = []
+        for item in rows:
+            at = item.event_fields.get("start_at")
+            # 时间不明的条目**保留** —— 和删除那边同一条纪律：证明不了它在
+            # 范围外，就不能替用户把它藏起来。
+            if at is not None and start is not None and at < start:
+                continue
+            if at is not None and end is not None and at > end:
+                continue
+            keep.append(item)
+        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]
+
+    def list_reminders(self, *, subject_id, include_completed=False, limit=50):
+        keep = [
+            v for k, v in self.reminders.items()
+            if k[0] == subject_id
+            and (include_completed or not v.reminder_fields.get("is_completed"))
+        ]
+        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]
+
+    def apply_source_snapshot(self, *, subject_id, source, collection_kind, sync_id,
+                              coverage_start, coverage_end, snapshot_kind) -> int:
+        # 增量同步没有资格删任何东西 —— 它只知道"变了什么"，不知道"还剩什么"。
+        if snapshot_kind != "full":
+            return 0
+        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:
+                continue
+            # 🔴 只删【能证明落在覆盖范围内】的。拿局部窗口去删窗口外的数据，
+            # 会让用户发现自己去年的日程凭空消失，而且不可逆。
+            # **时间不明的条目一律不删** —— 证明不了它在范围内，就没有资格删它。
+            start = (item.event_fields.get("start_at")
+                     if isinstance(item, CalendarEventMirror)
+                     else item.reminder_fields.get("due_at"))
+            if start is None or not (coverage_start <= start <= coverage_end):
+                continue
+            doomed.append(key)
+        for key in doomed:
+            del store[key]
+        return len(doomed)
+
+    # -- 规则状态 --------------------------------------------------------
+
+    def get_rule_state(self, *, subject_id, definition_id, scope_key):
+        return self.rule_state.get((subject_id, definition_id, scope_key))
+
+    def put_rule_state(self, *, subject_id, definition_id, scope_key, state) -> None:
+        self.rule_state[(subject_id, definition_id, scope_key)] = dict(state)
+
+    # -- 事件与投递 ------------------------------------------------------
+
+    def enqueue_event(self, entry: EventOutboxEntry) -> bool:
+        if entry.event_id in self.outbox:
+            return False
+        self.outbox[entry.event_id] = entry
+        return True
+
+    def claim_pending_event(self, *, worker_id, now, lease_seconds):
+        from dataclasses import replace
+        from datetime import timedelta
+        for event_id, entry in sorted(self.outbox.items()):
+            claimable = (
+                entry.delivery_state == _delivery.PENDING
+                or (entry.delivery_state == _delivery.CLAIMED
+                    and entry.lease_expires_at is not None
+                    and entry.lease_expires_at <= now)
+            )
+            if not claimable:
+                continue
+            if entry.next_attempt_at is not None and entry.next_attempt_at > now:
+                continue
+            claimed = replace(
+                entry,
+                delivery_state=_delivery.CLAIMED,
+                attempt_count=entry.attempt_count + 1,
+                lease_owner=worker_id,
+                lease_expires_at=now + timedelta(seconds=lease_seconds),
+                # 额度只是占位，不是消耗 —— delivered 时才兑现。
+                budget_reservation_id=f"resv_{event_id}_{entry.attempt_count + 1}",
+                # 每次认领换一个新令牌 —— 旧 worker 回来时手里是旧的。
+                claim_token=f"{worker_id}:{entry.attempt_count + 1}",
+            )
+            self.outbox[event_id] = claimed
+            return claimed
+        return None
+
+    def record_wake_receipt(self, *, receipt, next_state, claim_token=None,
+                            next_attempt_at=None) -> bool:
+        from dataclasses import replace
+        entry = self.outbox.get(receipt.event_id)
+        if entry is None:
+            raise KeyError(f"unknown event_id {receipt.event_id!r}")
+        if claim_token is not None and entry.claim_token != claim_token:
+            # 令牌过期:这个事件已经被别人接管了。只记审计,不改状态。
+            self.receipts.append(receipt)
+            return False
+        _delivery.assert_transition(entry.delivery_state, next_state)
+        self.receipts.append(receipt)
+        self.outbox[receipt.event_id] = replace(
+            entry,
+            delivery_state=next_state,
+            next_attempt_at=next_attempt_at,
+            lease_owner=None,
+            lease_expires_at=None,
+            # 兑现或释放：只有 delivered 会把占位变成真正的消耗。
+            claim_token=None,
+            budget_reservation_id=(
+                entry.budget_reservation_id
+                if _delivery.consumes_budget(next_state) else None
+            ),
+        )
+        return True
+
+    def list_pending_events(self, *, subject_id=None, limit=100):
+        return [
+            e for e in self.outbox.values()
+            if not e.is_terminal and (subject_id is None or e.subject_id == subject_id)
+        ][:limit]
+
+    # -- 用户数据 --------------------------------------------------------
+
+    def purge_subject(self, *, subject_id) -> dict[str, int]:
+        doomed_event_ids = {e.event_id for e in self.outbox.values()
+                            if e.subject_id == subject_id}
+
+        def drop(store: dict, pick) -> int:
+            doomed = [k for k, v in store.items() if pick(k, v) == subject_id]
+            for k in doomed:
+                del store[k]
+            return len(doomed)
+
+        counts = {
+            "reports": drop(self.reports, lambda k, v: k[0]),
+            "observations": drop(self.observations, lambda k, v: v.subject_id),
+            "current": drop(self.current, lambda k, v: k[0]),
+            "aggregates": drop(self.aggregates, lambda k, v: k[0]),
+            "calendar": drop(self.calendar, lambda k, v: k[0]),
+            "reminders": drop(self.reminders, lambda k, v: k[0]),
+            "sync_state": drop(self.sync_state, lambda k, v: k[0]),
+            "rule_state": drop(self.rule_state, lambda k, v: k[0]),
+            "outbox": drop(self.outbox, lambda k, v: v.subject_id),
+        }
+        before = len(self.identities)
+        self.identities = {i for i in self.identities if i[0] != subject_id}
+        counts["identities"] = before - len(self.identities)
+        # 回执按它对应事件的 subject 清理。以前这里只是原样复制了一遍列表 ——
+        # "删除我的数据"这件事没有部分成功。
+        doomed_events = {k for k in doomed_event_ids}
+        kept = [r for r in self.receipts if r.event_id not in doomed_events]
+        counts["receipts"] = len(self.receipts) - len(kept)
+        self.receipts = kept
+        return counts
+
+
+__all__ = ["InMemoryStorage"]