perceptkit 0.2.2__py3-none-any.whl

perceptkit/conformance/wake.py

@@ -0,0 +1,151 @@
+"""Wake adapter 的一致性检查 —— 宿主用它证明自己的 ``WakePort`` 实现是对的。
+
+产品规范 §20 把 storage / wake / report 三种 adapter conformance 并列为最低
+交付物。storage 那一套早就有了；这是 wake 那一套。
+
+用法（在宿主自己的测试里）::
+
+    from perceptkit.conformance import run_wake_conformance
+
+    def test_my_runtime_adapter_is_conformant():
+        problems = run_wake_conformance(lambda: MyRuntimeWake(fake_queue()))
+        assert not problems, "\\n".join(problems)
+
+---
+
+## 为什么 wake 需要单独一套
+
+storage 错了通常会崩或者查不到；**wake 错了只会让用户被同一件事提醒两次**，
+或者一条提醒永远不到 —— 两种都不报错，都只有用户会发现。
+
+三件最容易做错的事，这套检查全都盯着：
+
+    幂等      崩溃重投是常态不是异常。投出去之后、回执存下来之前进程挂掉，
+              重启一定会再投一次。runtime 不按 event_id 幂等，用户就被提醒两次
+    别抛异常  "runtime 拒绝"是一种**正常应答**，用 rejected / suppressed 表达。
+              抛异常会被当成投递失败，于是无限重试一条对方明确不想要的事件
+    回执对得上 回执里的 event_id / attempt_id 必须原样回传。对不上的话，
+              调用方就无法判断这条回执说的是哪一次投递
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Callable
+
+from ..contracts.delivery import DeliveryAttempt
+from ..contracts.event import EventCondition, PerceptionEvent
+from ..contracts.receipt import WAKE_STATUSES, WakeReceipt
+
+UTC = timezone.utc
+T0 = datetime(2026, 8, 27, 10, 0, tzinfo=UTC)
+
+WakeFactory = Callable[[], Any]
+
+#: 这套检查覆盖的保证。宿主读这份清单就知道自己被要求了什么。
+WAKE_GUARANTEES: tuple[str, ...] = (
+    "W1 回执的 status 必须是协议里的那几个之一",
+    "W2 回执必须原样回传 event_id 和 attempt_id",
+    "W3 同一个 event_id 重投必须是幂等的（第二次返回 duplicate，不重复处理）",
+    "W4 拒绝和抑制要用回执表达，不能抛异常",
+    "W5 attempt_id 变了但 event_id 没变，仍然算同一件事",
+    "W6 回执的 received_at 必须是带时区的时间",
+)
+
+#: 这套检查**证明不了**的事。写下来免得被当成验过了。
+WAKE_NOT_PROVABLE: tuple[str, ...] = (
+    "真实的超时行为 —— 要宿主自己让 runtime 卡住，确认返回 enqueue_failed "
+    "而不是永远挂着",
+    "真正的并发投递 —— 两条连接同时投同一个 event_id，只能有一个真正处理",
+    "跨进程幂等 —— 内存里的 seen 集合重启就没了，真实实现要落库",
+)
+
+
+def _event(event_id: str = "evt_1") -> PerceptionEvent:
+    return PerceptionEvent(
+        event_id=event_id, definition_id="d1", definition_version=1,
+        subject_id="u1", type="activity.step_goal_reached", signal="steps",
+        occurred_at=T0, received_at=T0,
+        condition=EventCondition(type="threshold_crossing", operator="gte", value=3000),
+        field_name="step_count", previous=2999, current=3000,
+    )
+
+
+def _attempt(event_id: str = "evt_1", attempt_id: str = "att_1",
+             count: int = 1) -> DeliveryAttempt:
+    return DeliveryAttempt(
+        event_id=event_id, attempt_id=attempt_id, attempt_number=count,
+    )
+
+
+def _call(wake: Any, event: PerceptionEvent, attempt: DeliveryAttempt,
+          problems: list[str], label: str) -> WakeReceipt | None:
+    try:
+        return wake.wake(event, attempt)
+    except Exception as exc:                       # noqa: BLE001 — 这正是要抓的
+        problems.append(
+            f"W4 {label}：wake() 抛了 {type(exc).__name__}({exc})。"
+            "拒绝和抑制是正常应答，要用 rejected / conversation_suppressed 回执表达 —— "
+            "抛异常会被调用方当成投递失败，于是无限重试一条对方明确不想要的事件"
+        )
+        return None
+
+
+def run_wake_conformance(new: WakeFactory) -> list[str]:
+    """跑一遍 wake adapter 的一致性检查，返回问题清单（空 = 通过）。
+
+    ``new`` 每次调用要给一个**全新的**适配器实例 —— 检查之间不能共享状态，
+    否则 W3 的幂等检查会被上一轮的痕迹影响。
+    """
+    problems: list[str] = []
+
+    # -- W1 / W2 / W6：回执本身的形状 -----------------------------------
+    wake = new()
+    ev, att = _event(), _attempt()
+    receipt = _call(wake, ev, att, problems, "首次投递")
+    if receipt is not None:
+        if receipt.status not in WAKE_STATUSES:
+            problems.append(
+                f"W1 回执 status={receipt.status!r} 不在协议里。"
+                f"合法值：{sorted(WAKE_STATUSES)}"
+            )
+        if receipt.event_id != ev.event_id:
+            problems.append(
+                f"W2 回执的 event_id 是 {receipt.event_id!r}，投的是 {ev.event_id!r}。"
+                "对不上的话调用方无法判断这条回执说的是哪一次投递"
+            )
+        if receipt.attempt_id != att.attempt_id:
+            problems.append(
+                f"W2 回执的 attempt_id 是 {receipt.attempt_id!r}，"
+                f"投的是 {att.attempt_id!r}"
+            )
+        if receipt.received_at.tzinfo is None:
+            problems.append(
+                "W6 回执的 received_at 没有时区。裸时间在跨时区宿主上会被解释错，"
+                "而且错得不会报错"
+            )
+
+    # -- W3 / W5：幂等 ---------------------------------------------------
+    wake = new()
+    ev = _event("evt_idem")
+    first = _call(wake, ev, _attempt("evt_idem", "att_1", 1), problems, "幂等第一次")
+    # 同一个 event_id、不同的 attempt_id —— 这正是崩溃重投的形状
+    second = _call(wake, ev, _attempt("evt_idem", "att_2", 2), problems, "幂等重投")
+    if first is not None and second is not None:
+        if second.status != "duplicate":
+            problems.append(
+                f"W3 同一个 event_id 投第二次返回了 {second.status!r}，应该是 'duplicate'。"
+                "崩溃重投是常态：投出去之后、回执存下来之前进程挂掉，重启一定会再投一次。"
+                "不幂等的话用户会被同一件事提醒两次"
+            )
+        if second.event_id != ev.event_id:
+            problems.append("W5 重投的回执 event_id 变了 —— 它跨重试必须保持不变")
+        if second.attempt_id != "att_2":
+            problems.append(
+                "W5 重投的回执 attempt_id 没跟上这一次的尝试。"
+                "event_id 认的是「哪件事」，attempt_id 认的是「哪一次投递」，两个都要对"
+            )
+
+    return problems
+
+
+__all__ = ["WAKE_GUARANTEES", "WAKE_NOT_PROVABLE", "run_wake_conformance"]

perceptkit/contracts/__init__.py

@@ -0,0 +1,97 @@
+"""契约层 —— 数据在 kit 边界上的样子。
+
+四个信封,对应管线的四个交接点:
+
+    ReportEnvelope   宿主 → kit      一批采集到的数据
+    Observation      kit 内部        校验、标准化之后的事实
+    PerceptionEvent  kit → 宿主      一次规则命中
+    WakeReceipt      宿主 → kit      runtime 对投递的应答
+
+外加两样不属于信封、但必须在契约层出现的东西:
+
+    IngestContext    绝不能从信封里读的可信值(谁的数据、宿主的钟、授权范围)
+    IngestReceipt    一批上报的处理结果,用于重传幂等
+
+**这一层只描述形状和校验规则,不做任何 I/O。** 谁在什么时候调、
+落到哪张表,分别是 ``processing`` 和 ``ports`` 的事。
+"""
+from __future__ import annotations
+
+from .availability import (
+    AVAILABILITY_STATES,
+    LEGACY_STATES,
+    NO_DATA,
+    OBSERVED,
+    UNAVAILABLE,
+    UNAVAILABLE_REASONS,
+    enters_trend,
+    normalize,
+    updates_current,
+)
+from . import delivery, records
+from .context import IngestContext
+from .errors import ContractError
+from .event import EventCondition, PerceptionEvent
+from .observation import Observation
+from .receipt import (
+    INGEST_ACCEPTED,
+    INGEST_CONFLICT,
+    INGEST_DUPLICATE,
+    INGEST_REJECTED,
+    WAKE_ACCEPTED,
+    WAKE_DUPLICATE,
+    WAKE_ENQUEUE_FAILED,
+    WAKE_REJECTED,
+    WAKE_RETRYABLE,
+    WAKE_SUPPRESSED,
+    IngestReceipt,
+    WakeReceipt,
+)
+from .records import (
+    CONFLICT,
+    IGNORE,
+    REPLACE,
+    CalendarEventMirror,
+    CurrentProjection,
+    DailyAggregate,
+    DurableDedupeIdentity,
+    EventOutboxEntry,
+    ReminderItemMirror,
+    SourceSyncState,
+    StoredObservation,
+    decide_current_update,
+)
+from .report import ReportEnvelope
+from .versioning import (
+    EVENT_SCHEMA_VERSION,
+    REPORT_SCHEMA_VERSION,
+    SUPPORTED_REPORT_VERSIONS,
+    UnsupportedSchemaVersion,
+    check_report_version,
+)
+
+__all__ = [
+    # availability
+    "OBSERVED", "NO_DATA", "UNAVAILABLE",
+    "AVAILABILITY_STATES", "LEGACY_STATES", "UNAVAILABLE_REASONS",
+    "normalize", "updates_current", "enters_trend",
+    # envelopes
+    "ReportEnvelope", "Observation", "PerceptionEvent", "EventCondition",
+    # trusted context + receipts
+    "IngestContext", "IngestReceipt", "WakeReceipt",
+    "INGEST_ACCEPTED", "INGEST_DUPLICATE", "INGEST_CONFLICT", "INGEST_REJECTED",
+    "WAKE_ACCEPTED", "WAKE_DUPLICATE", "WAKE_SUPPRESSED",
+    "WAKE_ENQUEUE_FAILED", "WAKE_REJECTED", "WAKE_RETRYABLE",
+    # versioning
+    "REPORT_SCHEMA_VERSION", "EVENT_SCHEMA_VERSION", "SUPPORTED_REPORT_VERSIONS",
+    "UnsupportedSchemaVersion", "check_report_version",
+    # 逻辑存储对象
+    "StoredObservation", "CurrentProjection", "DailyAggregate",
+    "CalendarEventMirror", "ReminderItemMirror", "SourceSyncState",
+    "DurableDedupeIdentity", "EventOutboxEntry",
+    "decide_current_update", "REPLACE", "IGNORE", "CONFLICT",
+    # 投递状态机
+    "delivery", "records",
+    # errors
+    "ContractError",
+]

perceptkit/contracts/_time.py

@@ -0,0 +1,89 @@
+"""时间戳解析 —— 只用标准库,兼容到 Python 3.10。
+
+为什么不直接用 ``datetime.fromisoformat``:3.10 的版本只认
+``datetime.isoformat()`` 自己吐出来的那个窄格式 —— ``Z`` 后缀不认,
+少写秒不认。真实 producer(iOS / Android / 各种 SDK)发过来的东西比那宽。
+3.11 起放宽了,但这个包声明支持 3.10,所以自己兜一层。
+
+**返回的一律是 aware datetime。** naive 的时间戳在这套系统里没有意义 ——
+归属到哪一天完全取决于时区,丢了偏移就只能猜,而猜错会静默写进历史。
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+#: ``fromisoformat`` 兜不住时挨个试的格式。按常见程度排。
+_FALLBACK_FORMATS = (
+    "%Y-%m-%dT%H:%M:%S%z",
+    "%Y-%m-%dT%H:%M:%S.%f%z",
+    "%Y-%m-%dT%H:%M%z",
+    "%Y-%m-%d %H:%M:%S%z",
+)
+
+
+class TimestampError(ValueError):
+    """时间戳解析不了,或者解析出来是 naive 的。"""
+
+
+def parse_timestamp(raw: object, *, field: str = "timestamp") -> datetime:
+    """把 ISO 8601 字符串解析成带时区的 :class:`datetime`。
+
+    也接受 :class:`datetime` 本身(必须 aware)。naive 一律拒绝 —— 见模块开头。
+    """
+    if isinstance(raw, datetime):
+        if raw.tzinfo is None or raw.tzinfo.utcoffset(raw) is None:
+            raise TimestampError(
+                f"{field}: naive datetime; 时间戳必须带 UTC 偏移,"
+                f"否则归属到哪一天只能靠猜"
+            )
+        return raw
+
+    if not isinstance(raw, str) or not raw.strip():
+        raise TimestampError(f"{field}: expected an ISO 8601 string, got {raw!r}")
+
+    text = raw.strip()
+    # 3.10 的 fromisoformat 不认 Z;统一换成显式偏移。
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+
+    parsed: datetime | None = None
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        for fmt in _FALLBACK_FORMATS:
+            try:
+                parsed = datetime.strptime(text, fmt)
+                break
+            except ValueError:
+                continue
+
+    if parsed is None:
+        raise TimestampError(f"{field}: cannot parse {raw!r} as ISO 8601")
+    if parsed.tzinfo is None or parsed.tzinfo.utcoffset(parsed) is None:
+        raise TimestampError(
+            f"{field}: {raw!r} 没有 UTC 偏移;时间戳必须带偏移,"
+            f"否则归属到哪一天只能靠猜"
+        )
+    return parsed
+
+
+def to_iso(value: datetime) -> str:
+    """序列化回 ISO 8601。UTC 用 ``+00:00`` 而不是 ``Z``,保持一种写法。"""
+    if value.tzinfo is None:
+        raise TimestampError("naive datetime cannot be serialised")
+    return value.isoformat()
+
+
+def utc_now_is_not_available() -> None:
+    """占位:这个包不读时钟。
+
+    "现在几点"是宿主的事 —— 内核读时钟就没法测试、没法重放、没法在
+    conformance test 里固定输入。需要"现在"的地方一律由调用方把时间传进来。
+    """
+    raise NotImplementedError(
+        "perceptkit 不读时钟:需要 now 的地方由宿主传入,"
+        "这样才能重放和测试"
+    )
+
+
+__all__ = ["TimestampError", "parse_timestamp", "to_iso", "timezone"]

perceptkit/contracts/availability.py

@@ -0,0 +1,77 @@
+"""一次观测的三种状态 —— 协议层唯一的可用性词表。
+
+    observed      拿到了可靠的值。``0`` / ``False`` / ``[]`` 都是合法的值,
+                  不需要单独一个"观测到零"的状态。
+    no_data       查询成功了,但在指定范围内没有样本。
+                  典型:昨晚没戴表 —— 不等于"睡了 0 分钟"。
+    unavailable   来源当前给不出这项数据(没授权 / 不支持 / 来源报错)。
+
+**为什么是三个而不是四个。** 这个包早期用的是四态(多一个 ``observed_zero``),
+问题在于"零"是值域里的一个普通取值,不是一种观测结果:把它提到状态位上,
+每个消费方都得记住"observed 和 observed_zero 都算观测到了",迟早有人漏一个。
+零值归 ``observed``,状态位就只回答一个问题:**这次到底有没有拿到数**。
+
+``LEGACY_STATES`` 保留旧词表到新词表的映射,让还在用四态的宿主平滑过渡;
+新代码一律用这里的三个常量。
+
+**``stale`` 不在这里。** 它不是上报状态,是读取 current 时由
+``occurred_at + current_ttl`` 推导出来的结果 —— 属于查询层,不属于上报协议。
+"""
+from __future__ import annotations
+
+#: 拿到了可靠的值(``0`` / ``False`` / ``[]`` 都算)。
+OBSERVED = "observed"
+
+#: 查询成功但范围内没有样本。不参与数值趋势,不当 0 用。
+NO_DATA = "no_data"
+
+#: 来源当前无法提供该数据。不覆盖最后一次可靠值。
+UNAVAILABLE = "unavailable"
+
+#: 协议层允许的全部状态。
+AVAILABILITY_STATES: frozenset[str] = frozenset({OBSERVED, NO_DATA, UNAVAILABLE})
+
+#: 旧四态 -> 新三态。``observed_zero`` 并进 ``observed``,``no_observation``
+#: 改名 ``no_data``(语义不变,只是名字更直白)。
+LEGACY_STATES: dict[str, str] = {
+    "observed": OBSERVED,
+    "observed_zero": OBSERVED,
+    "no_observation": NO_DATA,
+    "no_data": NO_DATA,
+    "unavailable": UNAVAILABLE,
+}
+
+#: ``unavailable`` 可选的粗粒度原因。刻意不穷举操作系统的每种权限状态 ——
+#: 那些属于 adapter 的诊断信息,不该进 agent 的上下文。
+UNAVAILABLE_REASONS: frozenset[str] = frozenset({
+    "permission_denied",
+    "not_supported",
+    "source_error",
+})
+
+
+def normalize(state: str) -> str:
+    """把任意(含旧词表的)状态归一成三态之一。
+
+    未知状态一律当 ``unavailable`` —— 宁可让 agent 觉得"这项现在没有",
+    也不要把一个看不懂的状态当成有效观测混进趋势。
+    """
+    return LEGACY_STATES.get(state, UNAVAILABLE)
+
+
+def updates_current(state: str) -> bool:
+    """这个状态该不该更新 current 的数值。
+
+    只有 ``observed`` 会。``no_data`` 只更新 coverage/诊断,``unavailable``
+    只标记"当前不可用",两者都不许覆盖最后一次可靠值。
+    """
+    return normalize(state) == OBSERVED
+
+
+def enters_trend(state: str) -> bool:
+    """这个状态该不该进数值趋势和 streak 计算。
+
+    只有 ``observed`` 会。把 ``no_data`` 当 0 塞进趋势,是这类系统最常见的
+    错误 —— 十四天里两天没戴表,平均值会被两个 0 直接拉垮。
+    """
+    return normalize(state) == OBSERVED

perceptkit/contracts/context.py

@@ -0,0 +1,50 @@
+"""可信上下文 —— 那些**绝不能**从上报信封里读的值。
+
+信封是 producer 写的,producer 在用户设备上,设备是可以被改的。所以三样东西
+必须由宿主从已认证的连接注入,而不是从信封里读:
+
+    subject_id    这批数据算谁的。信客户端自报 = 任何人都能往别人账号里写观测。
+    received_at   宿主自己的钟。producer 报的时间可能不准(设备时钟错、
+                  离线补传),审计和乱序判断要用可信的那个。
+    auth_scope    这个连接被授权写哪些 signal。用户关掉了健康权限,
+                  设备却还在发 health_* —— 得在这里挡掉,不能等写库了才发现。
+
+**为什么做成显式参数而不是全局变量**:如果 ``ingest()`` 的签名里没有它们的位置,
+实现只有两条路 —— 去读某个环境全局(那就没法并发、没法测试),或者退回去信
+信封里的值(那就是跨用户写入漏洞)。签名上留位置,是唯一能让"不信客户端"
+这句话真正成立的做法。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ._time import parse_timestamp
+from .errors import ContractError
+
+
+@dataclass(frozen=True)
+class IngestContext:
+    """一次 ingest 的可信上下文。全部由宿主提供,信封不得覆盖。"""
+
+    #: 这批数据属于谁。宿主从已认证连接解析,**不读信封**。
+    subject_id: str
+    #: 宿主收到这批数据的时刻。必须是 aware datetime。
+    received_at: datetime
+    #: 这个连接被授权写哪些 signal。``None`` = 不限制(宿主自己已经把过关了)。
+    #: 空集合 = 一个都不许写(权限全关),和 ``None`` 是两回事。
+    auth_scope: frozenset[str] | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.subject_id, str) or not self.subject_id.strip():
+            raise ContractError(["subject_id: required, must be a non-empty string"])
+        # 走一遍解析,把 naive datetime 挡在门外 —— 用 naive 的钟做乱序判断,
+        # 跨时区部署时会静默算错。
+        parse_timestamp(self.received_at, field="received_at")
+
+    def allows(self, signal: str) -> bool:
+        """这个连接有没有被授权写这个 signal。"""
+        return self.auth_scope is None or signal in self.auth_scope
+
+
+__all__ = ["IngestContext"]

perceptkit/contracts/delivery.py

@@ -0,0 +1,167 @@
+"""投递状态机 —— 事件从落地到送达之间会经过什么。
+
+**为什么状态机必须由 kit 定义，而不是留给每个宿主。**
+
+投递这件事本身（写哪个队列、起几个 worker、用什么定时器）确实是宿主的。
+但"什么时候算投出去了""崩在中间怎么恢复""重试会不会重复打扰用户"，
+是**正确性问题**——每个宿主自己发挥的结果是：
+
+    A 宿主 先投再落地           → 崩了丢事件
+    B 宿主 落地了但不重投        → 崩了事件永远卡住
+    C 宿主 重投但没去重          → 用户被同一件事提醒三次
+    D 宿主 投出去就扣冷却额度    → runtime 拒了，额度白扣，那轮该说的话没说
+
+同一个 kit 装到四个宿主上，四种可靠性 —— "可插拔"就是假的。所以状态和
+转移规则在这里定死，宿主只实现"怎么把状态存下来、怎么把 worker 跑起来"。
+
+**冷却额度为什么要先占位再兑现**（这条产品规范里没有）。规范只说
+"accepted 之后提交冷却/额度"，但没说 accepted **之前**那段窗口怎么办：
+两个 worker 同时捞到同一个事件、都还没拿到 accepted、于是都不扣额度、
+于是都投出去了。所以 ``claimed`` 状态必须持有一个**可过期的占位**，
+accepted 时兑现成真正的消耗，其余情况释放。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# ---------------------------------------------------------------------------
+# 状态
+# ---------------------------------------------------------------------------
+
+#: 已经落地，等人来捞。**事件走到这个状态才算不会丢。**
+PENDING = "pending"
+
+#: 某个 worker 领走了，持有一个带到期时间的租约和一个冷却额度占位。
+#: 租约到期没有进展 → 回到 ``pending`` 让别人接手（原持有者可能已经死了）。
+CLAIMED = "claimed"
+
+#: 终态：runtime 收下了。**只有这个状态会把额度占位兑现成真正的消耗。**
+DELIVERED = "delivered"
+
+#: 终态：runtime 收到了但选择不响应（会话正忙、安静时段）。
+#: **这不是失败**，事件已经送达 —— 重投只会打扰第二次。额度占位释放。
+SUPPRESSED = "suppressed"
+
+#: 终态：runtime 明确拒绝（事件类型不认、subject 不属于它）。不重试。
+REJECTED = "rejected"
+
+#: 终态：重试次数用尽。留着给人看，不再自动投。
+DEAD_LETTER = "dead_letter"
+
+#: 终态：规则说了这条不唤醒。**事件仍然是事实、仍然落地**，只是不投。
+#: 和 ``suppressed`` 不同 —— 那是 runtime 收到之后自己选择不响应，
+#: 这个是压根没打算投。两者混用会让"到底送没送到"说不清。
+NOT_DISPATCHED = "not_dispatched"
+
+DELIVERY_STATES: frozenset[str] = frozenset({
+    PENDING, CLAIMED, DELIVERED, SUPPRESSED, REJECTED, DEAD_LETTER, NOT_DISPATCHED,
+})
+
+#: 终态：不会再变，也不再占用额度占位。
+TERMINAL_STATES: frozenset[str] = frozenset({
+    DELIVERED, SUPPRESSED, REJECTED, DEAD_LETTER, NOT_DISPATCHED,
+})
+
+#: 合法的状态转移。任何不在这里的转移都是 bug，不是"边界情况"。
+_TRANSITIONS: dict[str, frozenset[str]] = {
+    PENDING: frozenset({CLAIMED}),
+    # claimed → pending 有两条路：主动放回（投递失败，等下次重试），
+    # 或租约到期被别人接管。两条都合法。
+    CLAIMED: frozenset({PENDING, DELIVERED, SUPPRESSED, REJECTED, DEAD_LETTER}),
+    DELIVERED: frozenset(),
+    SUPPRESSED: frozenset(),
+    REJECTED: frozenset(),
+    DEAD_LETTER: frozenset(),
+    NOT_DISPATCHED: frozenset(),
+}
+
+
+class IllegalTransition(ValueError):
+    """试图做一个不合法的状态转移。
+
+    这类错误不该被 catch 掉当边界情况处理 —— 它意味着投递逻辑有 bug，
+    继续往下走只会让状态更乱。
+    """
+
+
+def can_transition(current: str, target: str) -> bool:
+    return target in _TRANSITIONS.get(current, frozenset())
+
+
+def assert_transition(current: str, target: str) -> None:
+    if current not in DELIVERY_STATES:
+        raise IllegalTransition(f"未知状态 {current!r}")
+    if not can_transition(current, target):
+        allowed = sorted(_TRANSITIONS.get(current, frozenset()))
+        raise IllegalTransition(
+            f"{current} -> {target} 不合法；从 {current} 只能走到 {allowed or ['(终态)']}"
+        )
+
+
+def is_terminal(state: str) -> bool:
+    return state in TERMINAL_STATES
+
+
+# ---------------------------------------------------------------------------
+# 回执 -> 状态
+# ---------------------------------------------------------------------------
+
+def next_state_for_receipt(status: str, *, attempts_left: bool) -> str:
+    """runtime 给了这个回执之后，事件该进哪个状态。
+
+    ``attempts_left`` 为假时，本该重试的转成 ``dead_letter`` —— 无限重试
+    会让一个投不出去的事件永远占着 worker。
+    """
+    from .receipt import (
+        WAKE_ACCEPTED, WAKE_DUPLICATE, WAKE_ENQUEUE_FAILED,
+        WAKE_REJECTED, WAKE_SUPPRESSED,
+    )
+    if status in (WAKE_ACCEPTED, WAKE_DUPLICATE):
+        # duplicate 也算送达：runtime 认得这个 event_id，说明之前那次其实成了，
+        # 只是回执没存下来。当成功处理，别再投第三次。
+        return DELIVERED
+    if status == WAKE_SUPPRESSED:
+        return SUPPRESSED
+    if status == WAKE_REJECTED:
+        return REJECTED
+    if status == WAKE_ENQUEUE_FAILED:
+        return PENDING if attempts_left else DEAD_LETTER
+    raise IllegalTransition(f"没有为回执状态 {status!r} 定义后续状态")
+
+
+def consumes_budget(state: str) -> bool:
+    """走到这个状态时，冷却额度占位该不该兑现成真正的消耗。
+
+    **只有 ``delivered``。** 被压制、被拒绝、进死信都要把占位释放掉 ——
+    用户那一轮该说的话没说出去、额度却被吃掉了，是最难查的一类问题：
+    没有报错、没有日志，只有"它今天怎么不说话"。
+    """
+    return state == DELIVERED
+
+
+@dataclass(frozen=True)
+class DeliveryAttempt:
+    """一次投递尝试的身份。
+
+    ``event_id`` 跨重试**保持不变** —— runtime 靠它幂等，变了就等于
+    每次重试都是一个新事件，用户会被重复打扰。
+    ``attempt_id`` 每次都变 —— 用来把回执对上具体是哪一次投递，
+    以及在日志里分辨"第三次重试失败"和"三个并发投递失败"。
+    """
+
+    event_id: str
+    attempt_id: str
+    attempt_number: int
+
+    def __post_init__(self) -> None:
+        if self.attempt_number < 1:
+            raise ValueError("attempt_number 从 1 开始")
+
+
+__all__ = [
+    "PENDING", "CLAIMED", "DELIVERED", "SUPPRESSED", "REJECTED", "DEAD_LETTER",
+    "NOT_DISPATCHED",
+    "DELIVERY_STATES", "TERMINAL_STATES",
+    "IllegalTransition", "can_transition", "assert_transition", "is_terminal",
+    "next_state_for_receipt", "consumes_budget", "DeliveryAttempt",
+]

perceptkit/contracts/errors.py

@@ -0,0 +1,22 @@
+"""契约层的错误类型。
+
+单独一个模块,免得 report / observation 互相 import 成环。
+"""
+from __future__ import annotations
+
+from typing import Sequence
+
+
+class ContractError(ValueError):
+    """契约校验失败。
+
+    **一次报全部问题,不是遇到第一个就抛。** 一批上报里往往同时有好几个字段
+    不对,逐个试错要往返很多次;adapter 拿到完整清单才能一次改完。
+    """
+
+    def __init__(self, errors: Sequence[str]) -> None:
+        self.errors = list(errors)
+        super().__init__("; ".join(self.errors))
+
+
+__all__ = ["ContractError"]