perceptkit 0.2.2__py3-none-any.whl

perceptkit/manifest/types.py

@@ -0,0 +1,211 @@
+"""Manifest 的类型 —— 每个信号、每个字段的完整声明。
+
+**为什么要有这一层。** 在这之前,一个字段的属性散在七个互不关联的地方:
+catalog 声明输入和 TTL、fields 决定 agent 能不能看、history 决定怎么聚合、
+retention 决定留多久、attribution 决定算哪天、trend_models 决定用哪种趋势、
+prompts 决定怎么讲给模型。加一个字段要同时改七处,**漏一处就是静默出错**
+—— 没有任何测试会因为"你忘了给新字段声明 retention"而变红。
+
+manifest 把这七处并成一处,并让四条自动检查有了施力点(见 ``checks.py``)。
+
+manifest 只声明**属性**,不实现算法。``normalizer`` / ``aggregation_strategy``
+这类字段存的是名字,具体实现由 kit 或宿主注册 —— 但名字必须能解析到实现,
+否则就是一个永远不会被发现的空指针(现状:catalog 里有 10 个 resolver 名字
+没有任何实现)。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# 值域
+# ---------------------------------------------------------------------------
+
+#: 字段的类型。刻意只有这几种 —— 协议要能被非 Python 的 producer 实现。
+VALUE_TYPES: frozenset[str] = frozenset({
+    "integer", "number", "boolean", "string", "enum", "timestamp", "array", "object",
+})
+
+#: 隐私级别。决定这个字段能不能进日志、能不能持久化、能不能给 agent 看。
+#: kit 不做加解密 —— 这只是给宿主的处理提示。
+PRIVACY_CLASSES: frozenset[str] = frozenset({
+    "public",      # 无所谓,如电量
+    "personal",    # 用户的日常事实,如城市、专注状态
+    "sensitive",   # 健康、日历内容、照片属性
+    "restricted",  # 默认不持久化、不给 agent,如精确坐标、BSSID
+})
+
+#: 四种存储形态。每个信号必须明确属于其中一种,不能"看情况"。
+STORAGE_MODES: frozenset[str] = frozenset({
+    "current_only",              # 只留最近可信值。电量、屏幕变化
+    "current_timeline_aggregate",  # 最新 + 变化明细 + 日聚合。位置、专注、健康
+    "current_short_timeline",    # 最新 + 有限期明细。Wi-Fi、天气、音频路由
+    "source_mirror",             # 跟随外部可变集合。日历、提醒
+})
+
+#: 日聚合的算法。名字要能解析到实现。
+AGGREGATION_STRATEGIES: frozenset[str] = frozenset({
+    "none", "daily_total", "numeric_dist",
+    "duration_by_state", "event_list", "tally", "main_of_day", "cumulative",
+})
+
+#: 怎么判"这个字段该触发了"。事件规则和 wake 判断都读它。
+#: 注意 ``occurrence`` 不是在比较 —— 它表示"这条观测到达本身就是事件"
+#: （解锁、新增照片这类）,没有前后值可比,靠 source_event_id 去重。
+COMPARISON_STRATEGIES: frozenset[str] = frozenset({
+    "none", "exact", "numeric_delta", "threshold_crossing", "state_change",
+    "occurrence",
+})
+
+#: 一条观测的去重身份怎么来。
+IDENTITY_STRATEGIES: frozenset[str] = frozenset({
+    # 上游给稳定 id(HealthKit sample、日历事件)。最可靠。
+    "source_event_id",
+    # 上游给不了 id,用 (signal, occurred_at, 值摘要) 造一个确定性的键。
+    # 音乐、照片现在只能走这条 —— 见 FACTS.md ③ 和 3.1。
+    "deterministic_digest",
+    # 每个 subject+signal 只有一条,后来的直接覆盖。电量这类纯快照。
+    "singleton",
+})
+
+#: 一条观测算哪一天。
+ATTRIBUTION_STRATEGIES: frozenset[str] = frozenset({
+    "instant",            # 瞬时值,按发生时刻的本地日期
+    "episode_end",        # 区间,按结束时刻(睡眠算醒来那天)
+    "split_at_midnight",  # 区间,跨午夜按本地日切开分摊
+    "source_local_date",  # 上游直接给了本地日期,原样用
+})
+
+#: 这个字段的历史该用哪种趋势读法。三种算法结论完全不同,选错就是错的:
+#:   fluctuating 有"平时水平",偏离才是信号(睡眠时长、步数)
+#:   drifting    没有平时水平,方向和速率才是信号(体重)
+#:   cyclical    看间隔不看数值高低(经期)
+TREND_MODELS: frozenset[str] = frozenset({
+    "none", "fluctuating", "drifting", "cyclical",
+})
+
+#: agent 能不能看到这个字段。
+QUERY_VISIBILITY: frozenset[str] = frozenset({
+    "always",     # 直接进上下文
+    "on_demand",  # agent 主动查才给
+    "never",      # 只在 kit 内部用,永不出给模型(如原始坐标)
+})
+
+#: 需要额外语义的来源。不是所有信号都要背 revision / cursor / tombstone。
+SOURCE_PROFILES: frozenset[str] = frozenset({
+    "health_sample", "calendar_sync", "location", "device_occurrence", "proximity_anchor",
+})
+
+#: 保留期用这个值表示"永久"。用 ``None`` 会和"忘了声明"混淆。
+PERMANENT = -1
+
+
+# ---------------------------------------------------------------------------
+# 声明
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class FieldDefinition:
+    """一个字段的完整声明。"""
+
+    key: str
+    value_type: str
+    privacy_class: str
+    #: **标准**单位。无量纲的(布尔、枚举、标签)写 ``None``,但**数值型必须有** ——
+    #: 没有单位的数字在跨宿主传递时必然被解释错。
+    unit: str | None = None
+    #: producer 还可能发来哪些单位。收到这些一律换算成 ``unit``,
+    #: 原始单位留作 metadata。不在这个名单里的单位**拒收** ——
+    #: 一个磅的数字当公斤存进去,比拒收难查得多(没有报错,只有一个悄悄
+    #: 错掉一半的体重)。
+    accepted_units: tuple[str, ...] = ()
+    #: 相邻两次测量的相对变化上限。超过就报 conflict(**不拒收**,交给宿主决定)。
+    #: 这是唯一能挡住"单位标错"的一道:体重一次掉一半,不管单位对不对都不正常。
+    #: 值域校验拦不住它 —— 31.8 kg 完全合法。
+    #: 会误伤(用户真换了体重计),所以只报冲突。``None`` = 不检查。
+    max_relative_jump: float | None = None
+    nullable: bool = True
+    #: 数值型的合法区间 ``(min, max)``,任一端可为 ``None``。
+    valid_range: tuple[float | None, float | None] | None = None
+    #: 枚举型的合法取值。
+    enum: tuple[str, ...] | None = None
+    aggregation_strategy: str = "none"
+    comparison_strategy: str = "none"
+    #: 这个字段的变化能不能触发唤醒。
+    wake_eligible: bool = False
+    query_visibility: str = "on_demand"
+    trend_model: str = "none"
+    #: 标准化函数的名字。``None`` = 原样存。
+    normalizer: str | None = None
+    #: 这个字段为什么长这样 —— 和规范不一致的地方、平台限制、放弃的替代方案。
+    #: **写进数据结构而不是注释**：读 manifest 的人(和 dump 出来的文档)一定
+    #: 看得到,注释只有读源码的人看得到。信号级有同名字段,这里补上字段级。
+    note: str | None = None
+
+
+@dataclass(frozen=True)
+class SignalDefinition:
+    """一个信号的完整声明。"""
+
+    key: str
+    label: str
+    schema_version: int
+    #: 权限门。用户关掉这个 capability,整个信号停止读取和唤醒。
+    capability: str
+    storage_mode: str
+    #: 超过这个秒数就不能再叫"当前值"。仍可作为带 ``as_of`` 的 last known 返回。
+    current_ttl_sec: float
+    identity_strategy: str
+    attribution_strategy: str
+    fields: tuple[FieldDefinition, ...]
+    #: **明细**（逐条观测）保留多少天。``PERMANENT`` = 永久;``0`` = 不存历史。
+    history_retention_days: int = 0
+    #: **聚合**（日统计）保留多少天。默认跟着明细走 —— 但两者常常不该一样。
+    #:
+    #: 明细是聚合的几十倍体量,而能回答的问题正好反过来:
+    #: 「上周三下午你专注了多久」时间越久越没人问,
+    #: 「你今年专注时间比去年长了吗」时间越久越值钱。
+    #: 所以典型形态是**明细短、聚合永久** —— 省的全在明细上,
+    #: 多花的不到 2%,长期趋势保住了。
+    #:
+    #: ``None`` = 跟明细一样。
+    #:
+    #: ⚠️ 明细过期而聚合永久时,**去重记录必须比明细活得久**,
+    #: 否则旧数据重放会把永久聚合的数字加两遍且无法回滚。
+    aggregate_retention_days: int | None = None
+    source_profile: str | None = None
+    #: 这条声明为什么长这样 —— 特别是和产品规范有出入的地方。
+    #: 写进数据结构而不是注释,是为了让它跟着 manifest 一起被读到。
+    note: str | None = None
+    extensions: dict[str, Any] = field(default_factory=dict)
+
+    def field_map(self) -> dict[str, FieldDefinition]:
+        return {f.key: f for f in self.fields}
+
+    @property
+    def stores_history(self) -> bool:
+        return self.history_retention_days != 0
+
+    @property
+    def keeps_history_forever(self) -> bool:
+        return self.history_retention_days == PERMANENT
+
+    @property
+    def effective_aggregate_retention_days(self) -> int:
+        """聚合实际留多久。没单独声明就跟明细一样。"""
+        return (self.history_retention_days if self.aggregate_retention_days is None
+                else self.aggregate_retention_days)
+
+    @property
+    def keeps_aggregates_forever(self) -> bool:
+        return self.effective_aggregate_retention_days == PERMANENT
+
+
+__all__ = [
+    "VALUE_TYPES", "PRIVACY_CLASSES", "STORAGE_MODES",
+    "AGGREGATION_STRATEGIES", "COMPARISON_STRATEGIES",
+    "IDENTITY_STRATEGIES", "ATTRIBUTION_STRATEGIES",
+    "QUERY_VISIBILITY", "TREND_MODELS", "SOURCE_PROFILES", "PERMANENT",
+    "FieldDefinition", "SignalDefinition",
+]

perceptkit/manifest/units.py

@@ -0,0 +1,84 @@
+"""单位换算 —— 把 producer 发来的单位统一成 manifest 声明的那个。
+
+**为什么必须换算而不是拒收**：同一个数据可能来自不同来源，各自习惯的单位不一样
+（美区设备报磅、国区报公斤）。拒收会让一整类用户的数据进不来。
+
+**但换算会放大错误，所以从来不能单独用**：
+
+    用户体重 70 kg，设备把单位标成了 lb（标错了）
+      → 我们老老实实换算：70 lb = 31.8 kg
+      → 用户的体重记录突然掉了一半，而且没有任何报错
+      → 值域校验也拦不住（31.8 kg 完全合法）
+
+所以三道一起：
+
+    ① 换算      按声明的单位转成标准单位，原始单位留作 metadata
+    ② 值域校验  换算【之后】再查一遍范围
+    ③ 跳变阈值  和上一次比，变化超过阈值就报 conflict —— 不拒收，交给宿主决定
+
+第 ③ 道是唯一能挡住"单位标错"的：体重一次掉一半，不管单位对不对都不正常。
+它也会误伤（用户真换了体重计），所以只报 conflict 不拒收。
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+#: 换算表：``(来的单位, 目标单位) -> 换算函数``。
+#: 刻意只放真实会遇到的，不做通用单位库 —— 那是另一个包的活。
+_CONVERSIONS: dict[tuple[str, str], Callable[[float], float]] = {
+    # 质量
+    ("lb", "kg"): lambda v: v * 0.45359237,
+    ("g", "kg"): lambda v: v / 1000.0,
+    # 温度
+    ("fahrenheit", "celsius"): lambda v: (v - 32.0) * 5.0 / 9.0,
+    # 长度
+    ("in", "cm"): lambda v: v * 2.54,
+    ("m", "cm"): lambda v: v * 100.0,
+    ("ft", "cm"): lambda v: v * 30.48,
+    # 距离
+    ("km", "m"): lambda v: v * 1000.0,
+    ("mi", "m"): lambda v: v * 1609.344,
+    # 能量
+    ("kj", "kcal"): lambda v: v / 4.184,
+    # 血糖 —— 换算系数取决于摩尔质量，葡萄糖是 18.0182
+    ("mg_dl", "mmol_l"): lambda v: v / 18.0182,
+}
+
+
+class UnitError(ValueError):
+    """来的单位换算不到目标单位。"""
+
+
+def can_convert(source: str, target: str) -> bool:
+    return source == target or (source, target) in _CONVERSIONS
+
+
+def convert(value: float, *, source: str, target: str) -> float:
+    """把 ``value`` 从 ``source`` 换算成 ``target``。
+
+    换不了就抛 —— **不要静默按原值放行**：一个 lb 的数字当 kg 存进去，
+    比拒收难查得多（没有报错，只有一个悄悄错掉一半的体重）。
+    """
+    if source == target:
+        return float(value)
+    fn = _CONVERSIONS.get((source, target))
+    if fn is None:
+        raise UnitError(f"没有 {source!r} -> {target!r} 的换算")
+    return fn(float(value))
+
+
+def relative_jump(new: float, old: float) -> float | None:
+    """两次测量的相对变化幅度。``old`` 为 0 或缺失时返回 ``None``（比不了）。
+
+    用相对值不用绝对值：体重差 5 公斤和血糖差 5 mmol/L 是完全不同量级的事，
+    每个字段各写一个绝对阈值既啰嗦又容易写错。
+    """
+    if old in (None, 0) or new is None:
+        return None
+    try:
+        return abs((float(new) - float(old)) / float(old))
+    except (TypeError, ValueError, ZeroDivisionError):
+        return None
+
+
+__all__ = ["UnitError", "can_convert", "convert", "relative_jump"]

perceptkit/ports/__init__.py

@@ -0,0 +1,19 @@
+"""端口 —— 宿主要实现的两个接口。
+
+    StoragePort   数据落到哪儿、怎么保证一致
+    WakePort      事件交给谁
+
+**端口只定行为,不定实现。** 宿主填的每个方法都是孤立的一件事;
+"先落地再投递""迟到数据不覆盖当前值"这些顺序和规则在 kit 的处理管线里,
+宿主没有那个入口 —— 让写错的那条路根本不存在,比在文档里提醒别写错可靠。
+
+这两个 Protocol 都是 ``runtime_checkable`` 的,宿主可以用 ``isinstance``
+自查有没有漏方法;但真正的验收是跑 ``perceptkit.conformance`` 那套测试 ——
+方法签名对得上不代表语义对得上。
+"""
+from __future__ import annotations
+
+from .storage import StoragePort
+from .wake import WakePort
+
+__all__ = ["StoragePort", "WakePort"]

perceptkit/ports/storage.py

@@ -0,0 +1,288 @@
+"""存储端口 —— 宿主要填的方法体。
+
+**这里只定行为，不定 SQL。** 用 PostgreSQL、SQLite、文档数据库、甚至内存，
+都行；但必须满足同样的查询、幂等、重算、删除和一致性语义 —— 这一点由
+``perceptkit.conformance`` 的测试来证明，不靠自觉。
+
+宿主实现的每个方法都是**孤立的一件事**（写一条、读一批、提交一次）。
+"先落地再投递""迟到数据不覆盖当前值""同一时刻不同内容要报冲突"这些顺序
+和规则不在宿主手里 —— 它们在 kit 的处理管线里，宿主没有那个入口。
+这不是不信任宿主，是让"写错的那条路根本不存在"。
+
+**每个方法都必须按 subject 隔离。** ``subject_id`` 一律来自
+:class:`~perceptkit.contracts.context.IngestContext`，绝不来自上报信封 ——
+信封是设备写的，设备可以被改。
+"""
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, ContextManager, Protocol, Sequence, runtime_checkable
+
+from ..contracts.records import (
+    CalendarEventMirror,
+    CurrentProjection,
+    DailyAggregate,
+    DurableDedupeIdentity,
+    EventOutboxEntry,
+    ReminderItemMirror,
+    SourceSyncState,
+    StoredObservation,
+)
+from ..contracts.receipt import IngestReceipt, WakeReceipt
+
+
+@runtime_checkable
+class StoragePort(Protocol):
+    """宿主的存储适配器。
+
+    方法分六组：批级幂等 / 观测 / 当前值 / 聚合 / 来源镜像 / 事件与投递。
+    """
+
+    # -- 事务 ------------------------------------------------------------
+
+    def transaction(self) -> ContextManager[None]:
+        """一个原子边界。
+
+        kit 会把"写规则状态 + 写待发件箱"这类**必须一起成功**的操作包在
+        同一个 ``with`` 里。宿主如果做不到真正的单事务，必须提供可证明的
+        补偿/对账机制，并在一致性测试里证明它 —— 不能默认它不会出问题。
+
+        产品规范这里留了活口（"处于同一原子边界，**或有可证明的恢复机制**"），
+        所以不强制单事务，但强制"能证明"。
+        """
+        ...
+
+    # -- 批级幂等 --------------------------------------------------------
+
+    def claim_report(
+        self, *, subject_id: str, producer: str, report_id: str, payload_digest: str,
+        received_at: datetime,
+    ) -> IngestReceipt:
+        """认领一批上报，同时回答"这批处理过没有"。
+
+        同 identity + 同摘要 → 返回原来那份回执（``duplicate``），**不重复处理**。
+        同 identity + 异摘要 → ``conflict``，不能静默挑一个覆盖。
+        没见过         → ``accepted``，并占住这个 identity。
+
+        必须是原子的 check-and-claim：两个并发请求带同一个 ``report_id``
+        进来，只能有一个拿到 ``accepted``。
+        """
+        ...
+
+    # -- 观测 ------------------------------------------------------------
+
+    def append_observation(self, observation: StoredObservation) -> bool:
+        """追加一条观测。已经存在（同一去重身份）时返回 ``False`` 且不重复写。
+
+        返回值不是可有可无的：调用方靠它决定要不要去更新聚合 ——
+        重复的观测如果也去加一遍日总数，那就是重复累计。
+        """
+        ...
+
+    def list_observations(
+        self, *, subject_id: str, signal: str,
+        start: datetime | None = None, end: datetime | None = None,
+        cursor: str | None = None, limit: int = 100,
+    ) -> tuple[Sequence[StoredObservation], str | None]:
+        """按时间取观测。返回 ``(结果, 下一页游标)``。
+
+        **必须分页。** agent 问一句"我这个月都去过哪"，不设上限就是几千条
+        直接塞进模型上下文。
+        """
+        ...
+
+    def delete_observations(
+        self, *, subject_id: str, signal: str | None = None,
+        before: datetime | None = None,
+    ) -> int:
+        """按保留期清理明细，返回删了多少条。
+
+        🔴 **绝不能删掉永久聚合还在依赖的唯一事实，也不能删掉去重身份。**
+        删了去重身份，旧数据重放时会把永久聚合的数字加两遍，而且无法回滚。
+        """
+        ...
+
+    # -- 当前值 ----------------------------------------------------------
+
+    def get_current(
+        self, *, subject_id: str, signals: Sequence[str],
+    ) -> dict[str, Sequence[CurrentProjection]]:
+        """取当前值。TTL 判定不在这里做 —— 这里只负责把存的东西读出来，
+        "过期了算不算当前"由查询层按 manifest 判。
+        """
+        ...
+
+    def compare_and_put_current(
+        self, projection: CurrentProjection, *, expected_version: int,
+    ) -> bool:
+        """乐观并发地写当前值。版本对不上返回 ``False``，调用方重读重试。
+
+        为什么不是简单的 upsert：两条并发上报（一条新一条旧）同时到达时，
+        简单覆盖的结果取决于谁后写完 —— 旧数据可能赢。带版本号才能保证
+        "只有一个胜者，而且是应该赢的那个"。
+        """
+        ...
+
+    # -- 聚合 ------------------------------------------------------------
+
+    def get_aggregate(
+        self, *, subject_id: str, signal: str,
+        start_date: date, end_date: date,
+        aggregation_kind: str | None = None,
+    ) -> Sequence[DailyAggregate]:
+        ...
+
+    def put_aggregate(self, aggregate: DailyAggregate) -> None:
+        """写入或替换一个聚合。
+
+        按 ``(subject, signal, date, kind, aggregation_version)`` 覆盖 ——
+        换了 ``aggregation_version`` 就是新的一份，旧的留着，**不原地改写
+        旧统计的语义**。
+        """
+        ...
+
+    # -- 去重身份 --------------------------------------------------------
+    #
+    # 产品规范的端口清单里没有这两个，但它的一致性保证第 4 条（"永久聚合不会
+    # 因重放重复累计"）和第 9 条（"清理不会误删 dedupe 身份"）离开它们没法实现。
+
+    def remember_identity(self, identity: DurableDedupeIdentity) -> bool:
+        """记住"这条我处理过了"。已经记过返回 ``False``。"""
+        ...
+
+    def has_seen_identity(
+        self, *, subject_id: str, signal: str, source: str, digest: str,
+    ) -> bool:
+        """这条处理过没有。明细已按保留期删掉之后，这是唯一还能回答的东西。"""
+        ...
+
+    # -- 来源镜像 --------------------------------------------------------
+
+    def get_sync_state(
+        self, *, subject_id: str, source: str, collection_kind: str,
+    ) -> SourceSyncState | None:
+        ...
+
+    def put_sync_state(self, state: SourceSyncState) -> None:
+        ...
+
+    def upsert_calendar_events(
+        self, *, subject_id: str, events: Sequence[CalendarEventMirror],
+    ) -> None:
+        ...
+
+    def upsert_reminders(
+        self, *, subject_id: str, items: Sequence[ReminderItemMirror],
+    ) -> None:
+        ...
+
+    def list_calendar_events(
+        self, *, subject_id: str,
+        start: datetime | None = None, end: datetime | None = None,
+        limit: int = 50,
+    ) -> Sequence[CalendarEventMirror]:
+        """镜像里现在还存在的日程，按开始时间排序。
+
+        产品规范的端口清单里只有写入没有读取 —— 但读取侧要用，不给它一个
+        端口方法，实现就只能去摸具体存储的内部结构，换个宿主就静默返回空。
+        """
+        ...
+
+    def list_reminders(
+        self, *, subject_id: str, include_completed: bool = False, limit: int = 50,
+    ) -> Sequence[ReminderItemMirror]:
+        """镜像里现在还存在的提醒事项。理由同上。"""
+        ...
+
+    def apply_source_snapshot(
+        self, *, subject_id: str, source: str, collection_kind: str,
+        sync_id: str, coverage_start: datetime, coverage_end: datetime,
+        snapshot_kind: str,
+    ) -> int:
+        """全量同步收尾：删掉**覆盖范围内**这轮没见到的条目，返回删了几条。
+
+        🔴 ``coverage_start`` / ``coverage_end`` 是硬边界。拿一个局部窗口去删
+        窗口外的数据，是同步实现最容易犯的错，而且删完不可逆 —— 用户会发现
+        自己去年的日程凭空消失了。
+
+        ``snapshot_kind`` 不是 ``full`` 时，这个方法必须什么都不删。
+        """
+        ...
+
+    # -- 规则状态 --------------------------------------------------------
+
+    def get_rule_state(
+        self, *, subject_id: str, definition_id: str, scope_key: str,
+    ) -> dict[str, Any] | None:
+        ...
+
+    def put_rule_state(
+        self, *, subject_id: str, definition_id: str, scope_key: str,
+        state: dict[str, Any],
+    ) -> None:
+        """写规则状态。
+
+        **必须和 ``enqueue_event`` 在同一个事务里。** 分开的话，可能出现
+        "状态说已经触发过了，但事件没进发件箱" —— 那这次触发就永远丢了，
+        而且规则要等到下一个 scope 才会 rearm。
+        """
+        ...
+
+    # -- 事件与投递 ------------------------------------------------------
+
+    def enqueue_event(self, entry: EventOutboxEntry) -> bool:
+        """把事件写进待发件箱。同 ``event_id`` 已存在时返回 ``False``。
+
+        **提交成功那一刻，事件就丢不了了。** 之后崩多少次都能重投。
+        """
+        ...
+
+    def claim_pending_event(
+        self, *, worker_id: str, now: datetime, lease_seconds: float,
+    ) -> EventOutboxEntry | None:
+        """领一个待投递的事件，拿一个到期的租约。
+
+        必须原子地做三件事：挑一个 ``pending``（或租约已过期的 ``claimed``）、
+        置为 ``claimed``、写上 ``lease_owner`` 和 ``lease_expires_at``。
+
+        租约过期能被别人接管，是因为原持有者可能已经死了；而"到期才接管"
+        保证了正常情况下同一个事件同时只有一个 worker 在处理。
+        """
+        ...
+
+    def record_wake_receipt(
+        self, *, receipt: WakeReceipt, next_state: str,
+        claim_token: str | None = None,
+        next_attempt_at: datetime | None = None,
+    ) -> None:
+        """存回执并推进投递状态。返回 ``False`` 表示令牌过期、状态未改。
+
+        **必须和"兑现或释放冷却额度占位"在同一个事务里。** 分开的话，
+        "已送达但额度没扣"和"额度扣了但状态还是 pending"两种错都会出现，
+        后者更糟：用户被打扰了两次。
+
+        **``claim_token`` 对不上时只能记审计，不能改状态。** 旧 worker 租约
+        过期、事件被别人接管之后它才返回 —— 让它推进状态，等于一次超时
+        变成一次错误的覆盖，而且看起来完全正常。
+        """
+        ...
+
+    def list_pending_events(
+        self, *, subject_id: str | None = None, limit: int = 100,
+    ) -> Sequence[EventOutboxEntry]:
+        """列出还没送达的事件。给宿主的 worker 和 backlog 告警用。"""
+        ...
+
+    # -- 用户数据 --------------------------------------------------------
+
+    def purge_subject(self, *, subject_id: str) -> dict[str, int]:
+        """删掉这个用户的全部数据，返回各类删了多少条。
+
+        必须覆盖：观测、当前值、聚合、来源镜像、同步状态、去重身份、
+        规则状态、待发件箱、回执。**漏一类就是删不干净**，而"删除我的数据"
+        这件事没有部分成功。
+        """
+        ...
+
+
+__all__ = ["StoragePort"]

perceptkit/ports/wake.py

@@ -0,0 +1,43 @@
+"""唤醒端口 —— 把事件交给宿主的 agent runtime。
+
+只有一个方法。它刻意很窄:kit 不知道也不该知道宿主是用队列、消息、
+还是直接函数调用把事件送到 runtime 的。
+
+**戳醒 ≠ 该开口。** runtime 收下这次唤醒之后,继续睡、只看一眼、还是开口
+说话,是三个平行选项 —— 这个包不参与那个决定,也不产出任何"该说话了"式的
+措辞。回执里的 ``accepted`` 只表示"我收到了并且会处理",不表示"我会说话"。
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ..contracts.delivery import DeliveryAttempt
+from ..contracts.event import PerceptionEvent
+from ..contracts.receipt import WakeReceipt
+
+
+@runtime_checkable
+class WakePort(Protocol):
+    """宿主的 runtime 适配器。"""
+
+    def wake(self, event: PerceptionEvent, attempt: DeliveryAttempt) -> WakeReceipt:
+        """把一个事件交给 runtime,返回它的应答。
+
+        **实现必须按 ``event.event_id`` 幂等。** 崩溃重投是常态不是异常:
+        投出去之后、回执存下来之前进程挂掉,重启后一定会再投一次。
+        runtime 认得这个 id 就返回 ``duplicate``,不要真的再处理一遍 ——
+        否则用户会被同一件事提醒两次。
+
+        ``attempt`` 带着"这是第几次"。``event_id`` 跨重试不变,
+        ``attempt_id`` 每次都变 —— 后者用来在日志里分辨"第三次重试失败"
+        和"三个并发投递失败"。
+
+        **不要在这里抛异常表示"runtime 拒绝"** —— 拒绝是一种正常应答,
+        用 ``rejected`` / ``conversation_suppressed`` 表达。异常留给
+        真正的意外(连接断了、序列化失败),调用方会把它当作
+        ``enqueue_failed`` 处理并安排重试。
+        """
+        ...
+
+
+__all__ = ["WakePort"]