agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/events/runtime_event.py

@@ -1,264 +1,28 @@
-"""RuntimeEvent v1 schema (goal-02 / G0.2 冻结稿)。
+"""Public canonical RuntimeEvent schema version 2.
 
-事件只定义一次:Runtime 产生 → server 持久化 → gateway 透传 → UI/协议 adapter 消费。
-本模块只负责**定义层**(类型 + 序列化/反序列化 + 事件族清单);不改 runtime.py 发事件
-(那是后续阶段)。
-
-设计约束(友商证伪,G0.2 冻结):
-
-- **additive + ``SCHEMA_VERSION``**:只增字段/事件类型,不改既有字段语义。
-- **相位字段** ``phase``:区分 ``commentary``(过程解说)vs ``final_answer``(最终答案),
-  仅 text/reasoning 类事件使用。
-- **工具审批一等事件**(``approval.*``),不是普通 text;审批回包走独立命令/恢复通道,
-  事件流上的 ``approval.resolved`` 仅作回放/审计(非 duplex stream)。
+The schema-v1 wire model intentionally lives only in :mod:`ksadk.events.v1_compat`.
 """
 
-from __future__ import annotations
-
-import time
-import uuid
-from enum import Enum
-from typing import Any, Literal, Optional
-
-from pydantic import BaseModel, Field
-
-#: additive 演进锚点。冻结为 1;只增不改。
-SCHEMA_VERSION: Literal[1] = 1
-
-
-class EventPhase(str, Enum):
-    """相位:text/reasoning 类事件区分过程解说与最终答案。"""
-
-    COMMENTARY = "commentary"
-    FINAL_ANSWER = "final_answer"
-
-
-# ---------------------------------------------------------------------------
-# 事件族(event_type 常量,v1 冻结)。新增事件类型只能 additive 追加。
-# ---------------------------------------------------------------------------
-
-
-class EventType:
-    """v1 事件族清单(冻结)。按族分组;每族注释标明 payload 关键字段。"""
-
-    # text(相位:commentary/final_answer)。payload: text, message_id
-    TEXT_DELTA = "text.delta"
-    TEXT_COMPLETED = "text.completed"
-    # reasoning(相位恒 commentary)。payload: text, summary
-    REASONING_DELTA = "reasoning.delta"
-    REASONING_COMPLETED = "reasoning.completed"
-    # tool。begin: call_id, name, args;end: call_id, name, result, error, duration_ms
-    TOOL_CALL_BEGIN = "tool.call.begin"
-    TOOL_CALL_END = "tool.call.end"
-    # artifact。payload: name, version, uri, mime
-    ARTIFACT_CREATED = "artifact.created"
-    ARTIFACT_UPDATED = "artifact.updated"
-    # approval(一等)。requested: approval_id, call_id, kind, detail;
-    # resolved: approval_id, call_id, decision(回放/审计)
-    APPROVAL_REQUESTED = "approval.requested"
-    APPROVAL_RESOLVED = "approval.resolved"
-    # run 生命周期。payload: status;progress?: progress;failed: error;canceled: cancel_result
-    RUN_STARTED = "run.started"
-    RUN_PROGRESS = "run.progress"
-    RUN_INTERRUPTED = "run.interrupted"
-    RUN_COMPLETED = "run.completed"
-    RUN_FAILED = "run.failed"
-    RUN_CANCELED = "run.canceled"
-    # checkpoint。payload: checkpoint_id, granularity(delta|snapshot), resume_target?
-    CHECKPOINT_CREATED = "checkpoint.created"
-    CHECKPOINT_RESUMED = "checkpoint.resumed"
-    # usage。payload: input_tokens, output_tokens, total_tokens, cached_tokens, reasoning_tokens
-    USAGE_REPORTED = "usage.reported"
-    # A2UI。payload: surface_id, block_id?, catalog?, data?
-    A2UI_SURFACE_BEGIN = "a2ui.surface.begin"
-    A2UI_SURFACE_UPDATE = "a2ui.surface.update"
-    A2UI_SURFACE_END = "a2ui.surface.end"
-    A2UI_INTERACTION = "a2ui.interaction"
-    A2UI_ACTION = "a2ui.action"
-    # remote A2A。payload: task_id, origin(remote agent url/space), status?, artifact?
-    A2A_TASK_CREATED = "a2a.task.created"
-    A2A_TASK_STATUS = "a2a.task.status"
-    A2A_TASK_ARTIFACT = "a2a.task.artifact"
-
-
-#: 全部 v1 事件类型(供校验/枚举)。
-ALL_EVENT_TYPES: frozenset[str] = frozenset(
-    {
-        EventType.TEXT_DELTA,
-        EventType.TEXT_COMPLETED,
-        EventType.REASONING_DELTA,
-        EventType.REASONING_COMPLETED,
-        EventType.TOOL_CALL_BEGIN,
-        EventType.TOOL_CALL_END,
-        EventType.ARTIFACT_CREATED,
-        EventType.ARTIFACT_UPDATED,
-        EventType.APPROVAL_REQUESTED,
-        EventType.APPROVAL_RESOLVED,
-        EventType.RUN_STARTED,
-        EventType.RUN_PROGRESS,
-        EventType.RUN_INTERRUPTED,
-        EventType.RUN_COMPLETED,
-        EventType.RUN_FAILED,
-        EventType.RUN_CANCELED,
-        EventType.CHECKPOINT_CREATED,
-        EventType.CHECKPOINT_RESUMED,
-        EventType.USAGE_REPORTED,
-        EventType.A2UI_SURFACE_BEGIN,
-        EventType.A2UI_SURFACE_UPDATE,
-        EventType.A2UI_SURFACE_END,
-        EventType.A2UI_INTERACTION,
-        EventType.A2UI_ACTION,
-        EventType.A2A_TASK_CREATED,
-        EventType.A2A_TASK_STATUS,
-        EventType.A2A_TASK_ARTIFACT,
-    }
-)
-
-#: 各 event_type 的 payload 必填键(conformance 用;additive —— 只允许增键)。
-#: 信封字段是硬冻结;payload 必填键是 v1 最低契约,后续版本只能加可选键。
-EVENT_PAYLOAD_REQUIRED_KEYS: dict[str, frozenset[str]] = {
-    EventType.TEXT_DELTA: frozenset({"text"}),
-    EventType.TEXT_COMPLETED: frozenset({"text"}),
-    EventType.REASONING_DELTA: frozenset({"text"}),
-    EventType.REASONING_COMPLETED: frozenset({"text"}),
-    EventType.TOOL_CALL_BEGIN: frozenset({"call_id", "name"}),
-    EventType.TOOL_CALL_END: frozenset({"call_id", "name"}),
-    EventType.ARTIFACT_CREATED: frozenset({"name", "version"}),
-    EventType.ARTIFACT_UPDATED: frozenset({"name", "version"}),
-    EventType.APPROVAL_REQUESTED: frozenset({"approval_id", "call_id", "kind"}),
-    EventType.APPROVAL_RESOLVED: frozenset({"approval_id", "call_id", "decision"}),
-    EventType.RUN_STARTED: frozenset({"status"}),
-    EventType.RUN_PROGRESS: frozenset({"status"}),
-    EventType.RUN_INTERRUPTED: frozenset({"status"}),
-    EventType.RUN_COMPLETED: frozenset({"status"}),
-    EventType.RUN_FAILED: frozenset({"status", "error"}),
-    EventType.RUN_CANCELED: frozenset({"status"}),
-    EventType.CHECKPOINT_CREATED: frozenset({"checkpoint_id", "granularity"}),
-    EventType.CHECKPOINT_RESUMED: frozenset({"checkpoint_id"}),
-    EventType.USAGE_REPORTED: frozenset({"input_tokens", "output_tokens", "total_tokens"}),
-    EventType.A2UI_SURFACE_BEGIN: frozenset({"surface_id"}),
-    EventType.A2UI_SURFACE_UPDATE: frozenset({"surface_id"}),
-    EventType.A2UI_SURFACE_END: frozenset({"surface_id"}),
-    EventType.A2UI_INTERACTION: frozenset({"surface_id"}),
-    EventType.A2UI_ACTION: frozenset({"surface_id"}),
-    EventType.A2A_TASK_CREATED: frozenset({"task_id", "origin"}),
-    EventType.A2A_TASK_STATUS: frozenset({"task_id", "origin", "status"}),
-    EventType.A2A_TASK_ARTIFACT: frozenset({"task_id", "origin"}),
-}
-
-#: 仅 text/reasoning 类事件使用相位字段。
-_PHASE_AWARE_TYPES: frozenset[str] = frozenset(
-    {
-        EventType.TEXT_DELTA,
-        EventType.TEXT_COMPLETED,
-        EventType.REASONING_DELTA,
-        EventType.REASONING_COMPLETED,
-    }
-)
-
-
-class RuntimeEvent(BaseModel):
-    """RuntimeEvent v1 信封。
-
-    字段全部硬冻结(additive 演进只允许新增可选字段)。``payload`` 按 event_type
-    承载,最低必填键见 :data:`EVENT_PAYLOAD_REQUIRED_KEYS`。
-    """
-
-    schema_version: Literal[1] = SCHEMA_VERSION
-    event_id: str
-    event_type: str
-    timestamp: float
-    agent_id: str
-    user_id: str
-    session_id: str
-    invocation_id: str
-    seq_id: int
-    phase: Optional[Literal["commentary", "final_answer"]] = None
-    payload: dict[str, Any] = Field(default_factory=dict)
-
-    # ---- 构造 ----
-
-    @classmethod
-    def create(
-        cls,
-        event_type: str,
-        *,
-        agent_id: str,
-        user_id: str,
-        session_id: str,
-        invocation_id: str,
-        seq_id: int,
-        payload: Optional[dict[str, Any]] = None,
-        phase: Optional[str] = None,
-        event_id: Optional[str] = None,
-        timestamp: Optional[float] = None,
-    ) -> "RuntimeEvent":
-        """便捷构造:自动补 event_id / timestamp,并按 event_type 校验相位与 payload。"""
-        event = cls(
-            event_id=event_id or f"evt_{uuid.uuid4().hex}",
-            event_type=event_type,
-            timestamp=time.time() if timestamp is None else timestamp,
-            agent_id=agent_id,
-            user_id=user_id,
-            session_id=session_id,
-            invocation_id=invocation_id,
-            seq_id=seq_id,
-            phase=phase,  # type: ignore[arg-type]
-            payload=payload or {},
-        )
-        event.validate_conformance()
-        return event
-
-    # ---- 序列化 ----
-
-    def to_dict(self) -> dict[str, Any]:
-        """序列化为 dict(含全部信封字段 + payload)。"""
-        return self.model_dump(mode="json", exclude_none=True)
-
-    def to_json(self) -> str:
-        """序列化为 JSON 字符串。"""
-        return self.model_dump_json(exclude_none=True)
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "RuntimeEvent":
-        """从 dict 反序列化。与 :meth:`create` 一致过 conformance:
-        未知 event_type / 相位滥用 / 缺必填键抛 ``ValueError``,不得混入系统。"""
-        event = cls.model_validate(data)
-        event.validate_conformance()
-        return event
-
-    @classmethod
-    def from_json(cls, raw: str) -> "RuntimeEvent":
-        """从 JSON 字符串反序列化(同 :meth:`from_dict` 过 conformance)。"""
-        event = cls.model_validate_json(raw)
-        event.validate_conformance()
-        return event
+from ksadk.events.canonical import *  # noqa: F403
+from ksadk.events.canonical import __all__
+from ksadk.events.v1_compat import EventTypeV1
 
-    # ---- conformance ----
 
-    def validate_conformance(self) -> None:
-        """按 v1 契约校验:事件类型已知、相位仅用于 text/reasoning、payload 必填键齐全。
+class _MergedEventType(EventTypeV1):
+    """EventTypeV1 plus the v1 members added by the observability branch
+    (user.message / turn.* / step.* / model.call.*) so that merged callers
+    keep working on top of the canonical v2 event core."""
 
-        additive 演进:允许 payload 含额外键(不作 strict 拒绝),只校验最低必填键。
-        未知 event_type / 缺必填键 / 相位滥用抛 :class:`ValueError`。
-        """
-        if self.event_type not in ALL_EVENT_TYPES:
-            raise ValueError(f"unknown event_type: {self.event_type!r}(v1 事件族之外)")
-        if self.phase is not None and self.event_type not in _PHASE_AWARE_TYPES:
-            raise ValueError(
-                f"phase 仅用于 text/reasoning 事件,{self.event_type!r} 不应带 phase={self.phase!r}"
-            )
-        required = EVENT_PAYLOAD_REQUIRED_KEYS.get(self.event_type, frozenset())
-        missing = required - set(self.payload.keys())
-        if missing:
-            raise ValueError(f"event_type {self.event_type!r} payload 缺必填键: {sorted(missing)}")
+    USER_MESSAGE = "user.message"
+    TURN_STARTED = "turn.started"
+    TURN_COMPLETED = "turn.completed"
+    STEP_STARTED = "step.started"
+    STEP_COMPLETED = "step.completed"
+    MODEL_CALL_BEGIN = "model.call.begin"
+    MODEL_CALL_FIRST_TOKEN = "model.call.first_token"
+    MODEL_CALL_END = "model.call.end"
 
 
-__all__ = [
-    "ALL_EVENT_TYPES",
-    "EVENT_PAYLOAD_REQUIRED_KEYS",
-    "EventPhase",
-    "EventType",
-    "RuntimeEvent",
-    "SCHEMA_VERSION",
-]
+# Alias kept for callers integrated before the canonical v2 refactor
+# (studio observability/evaluation imports on merged branches).
+EventType = _MergedEventType

ksadk/events/session_event.py

@@ -0,0 +1,324 @@
+"""Generic single-log SessionEvent store port（Phase 1 Task 2）。
+
+把 control/runtime/workflow 等 family 的 ``SessionEventEnvelope/v1`` 收敛进
+同一个 session event log，复用 Session backend 的原子 per-session seq。
+写入权限是 typed guard（``AdmissionWriteGuard | ActivationWriteGuard``），
+禁止无 guard append；发布（订阅可见性）只发生在 backend 事务 commit 之后，
+订阅先 replay ``seq > after_seq`` 再切 live，用同一 cursor 去重。
+
+物理 ``SessionEvent.id`` 是 ``(session_id, event_id)`` 的确定性编码，
+与 ``ksadk.events.canonical_store.canonical_storage_id`` 算法一致，
+让 durable 主键在分配 session cursor 之前先约束幂等域。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from collections.abc import AsyncIterator, Awaitable, Callable
+from datetime import datetime, timezone
+from typing import Any, Protocol
+
+from ksadk.events.canonical import parse_runtime_event
+from ksadk.kernel.contracts import (
+    ActivationWriteGuard,
+    AdmissionWriteGuard,
+    SessionEventEnvelope,
+    SessionEventWriteGuard,
+)
+from ksadk.sessions.base import BaseSessionService, SessionEvent
+
+_ENVELOPE_MARKER = "ksadk_session_event_envelope"
+_ENVELOPE_CONTENT_KEY = "session_event"
+_RUNTIME_CONTENT_KEY = "runtime_event"
+_RUNTIME_FAMILY = "runtime"
+_RUNTIME_FAMILY_VERSION = 2
+_ADMISSION_CONTROL_EVENT_TYPES = frozenset(
+    {"control.command_accepted", "control.command_rejected"}
+)
+
+
+def session_event_storage_id(session_id: str, event_id: str) -> str:
+    """Deterministic physical id for one envelope fact (same digest as canonical)."""
+
+    if not session_id.strip() or not event_id.strip():
+        raise ValueError("session_id and event_id must be nonempty")
+    encoded = json.dumps([session_id, event_id], ensure_ascii=False, separators=(",", ":")).encode(
+        "utf-8"
+    )
+    return f"cev_{hashlib.sha256(encoded).hexdigest()[:40]}"
+
+
+def _timestamp_to_float(value: str) -> float:
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.timestamp()
+
+
+class SessionEventStore(Protocol):
+    """Generic envelope port. Append without a typed guard is forbidden."""
+
+    async def append(
+        self, envelope: SessionEventEnvelope, *, guard: SessionEventWriteGuard
+    ) -> SessionEventEnvelope: ...
+
+    async def read(
+        self, session_id: str, after_seq: int, limit: int
+    ) -> list[SessionEventEnvelope]: ...
+
+    def subscribe(
+        self, session_id: str, after_seq: int
+    ) -> AsyncIterator[SessionEventEnvelope]: ...
+
+
+def validate_write_guard(
+    envelope: SessionEventEnvelope, guard: SessionEventWriteGuard
+) -> SessionEventWriteGuard:
+    """Typed write permission: no bare booleans, no nullable fences.
+
+    AdmissionWriteGuard 只允许 admission 产生的 ``control.command_accepted`` /
+    ``control.command_rejected``。ActivationWriteGuard 在 Phase 1 允许
+    worker/control/runtime facts；activation_id/fencing_token 与 lease 的
+    事务内比较由 Task 3 的 AgentKernelStore 承接。
+    """
+
+    if isinstance(guard, bool) or not isinstance(guard, (AdmissionWriteGuard, ActivationWriteGuard)):
+        raise TypeError(
+            "append requires a typed SessionEventWriteGuard "
+            "(AdmissionWriteGuard | ActivationWriteGuard)"
+        )
+    if isinstance(guard, AdmissionWriteGuard):
+        if envelope.family != "control" or envelope.event_type not in _ADMISSION_CONTROL_EVENT_TYPES:
+            raise PermissionError(
+                "AdmissionWriteGuard may only append control.command_accepted or "
+                "control.command_rejected facts"
+            )
+    return guard
+
+
+def envelope_to_session_event(envelope: SessionEventEnvelope) -> SessionEvent:
+    """Pack one envelope into the existing SessionEvent carrier."""
+
+    content: dict[str, Any] = {_ENVELOPE_CONTENT_KEY: envelope.model_dump(mode="json")}
+    binding = "session_event.seq"
+    if envelope.family == _RUNTIME_FAMILY and envelope.family_version == _RUNTIME_FAMILY_VERSION:
+        binding = "runtime_event.seq"
+        content[_RUNTIME_CONTENT_KEY] = dict(envelope.payload)
+    metadata: dict[str, Any] = {
+        _ENVELOPE_MARKER: True,
+        "schema_version": 1,
+        "family": envelope.family,
+        "family_version": envelope.family_version,
+        "canonical_event_id": str(envelope.event_id),
+    }
+    if envelope.run_id is not None:
+        metadata["run_id"] = envelope.run_id
+    return SessionEvent(
+        id=session_event_storage_id(envelope.session_id, str(envelope.event_id)),
+        session_id=envelope.session_id,
+        author=envelope.actor_ref or envelope.family,
+        event_type=envelope.event_type,
+        content=content,
+        timestamp=_timestamp_to_float(envelope.timestamp),
+        invocation_id=envelope.run_id,
+        metadata=metadata,
+        seq_binding=binding,  # type: ignore[arg-type]
+    )
+
+
+def session_event_to_envelope(event: SessionEvent) -> SessionEventEnvelope | None:
+    """Restore an envelope using the physical session cursor as ``seq``."""
+
+    metadata = event.metadata or {}
+    if not metadata.get(_ENVELOPE_MARKER):
+        return None
+    dump = dict((event.content or {}).get(_ENVELOPE_CONTENT_KEY) or {})
+    if not isinstance(dump, dict):
+        raise ValueError("canonical SessionEvent is missing session_event content")
+    if metadata.get("family") == _RUNTIME_FAMILY:
+        runtime_payload = (event.content or {}).get(_RUNTIME_CONTENT_KEY)
+        if not isinstance(runtime_payload, dict):
+            raise ValueError("runtime family SessionEvent is missing runtime_event content")
+        if runtime_payload.get("seq") != event.seq_id:
+            raise ValueError("runtime payload seq does not match physical seq")
+        dump["payload"] = dict(runtime_payload)
+    if str(dump.get("event_id")) != str(metadata.get("canonical_event_id")):
+        raise ValueError("canonical SessionEvent event id metadata does not match content")
+    dump["seq"] = event.seq_id
+    return SessionEventEnvelope.model_validate(dump)
+
+
+class SessionServiceEventStore:
+    """``SessionEventStore`` adapter over one ``BaseSessionService`` backend.
+
+    ``fence_validator`` 是可选的 ActivationWriteGuard 事务内 CAS seam：
+    提供时（典型为 ``AgentKernelStore.validate_write_fence``），每个
+    activation 写都在持久化之前比较当前 lease 的 fencing token，被
+    takeover 的旧 owner 得到 :class:`~ksadk.kernel.errors.StaleFenceError`。
+    validator 只看 guard，不向 envelope/payload 写入任何 fence 字段。
+    """
+
+    def __init__(
+        self,
+        session_service: BaseSessionService,
+        *,
+        fence_validator: Callable[
+            [SessionEventEnvelope, ActivationWriteGuard], Awaitable[None]
+        ]
+        | None = None,
+    ) -> None:
+        self._service = session_service
+        self._fence_validator = fence_validator
+
+    @property
+    def session_service(self) -> BaseSessionService:
+        return self._service
+
+    async def append(
+        self, envelope: SessionEventEnvelope, *, guard: SessionEventWriteGuard
+    ) -> SessionEventEnvelope:
+        validate_write_guard(envelope, guard)
+        if (
+            isinstance(guard, ActivationWriteGuard)
+            and self._fence_validator is not None
+        ):
+            await self._fence_validator(envelope, guard)
+        if not envelope.session_id.strip():
+            raise ValueError("session_id must be nonempty")
+        self._require_storage_capabilities(envelope)
+        existing = await self._find_envelope(envelope)
+        if existing is not None:
+            self._assert_same_fact(existing, envelope)
+            return existing
+        packed = envelope_to_session_event(envelope)
+        try:
+            stored = await self._service.append_event(envelope.session_id, packed)
+        except Exception:
+            # Deterministic physical id turns concurrent appends into an
+            # insert-winner/insert-loser race on durable backends.
+            existing = await self._find_envelope(envelope)
+            if existing is None:
+                raise
+            self._assert_same_fact(existing, envelope)
+            return existing
+        persisted = session_event_to_envelope(stored)
+        if persisted is None:  # pragma: no cover - packed by this module
+            raise RuntimeError("SessionEventEnvelope lost its storage marker")
+        return persisted
+
+    async def read(
+        self, session_id: str, after_seq: int, limit: int
+    ) -> list[SessionEventEnvelope]:
+        if limit < 1:
+            raise ValueError("limit must be positive")
+        raw = await self._service.get_events(
+            session_id,
+            after_seq_id=int(after_seq),
+            limit=limit,
+        )
+        rows = sorted(raw, key=lambda event: event.seq_id)
+        envelopes = []
+        for row in rows:
+            envelope = session_event_to_envelope(row)
+            if envelope is None:
+                continue
+            _validate_runtime_payload(envelope)
+            envelopes.append(envelope)
+        return envelopes[:limit]
+
+    async def subscribe(
+        self,
+        session_id: str,
+        after_seq: int,
+        *,
+        poll_interval: float = 0.25,
+        timeout: float = 5 * 60,
+        should_stop: Callable[[], Awaitable[bool]] | None = None,
+    ) -> AsyncIterator[SessionEventEnvelope]:
+        """Replay ``seq > after_seq`` first, then follow live with the same cursor.
+
+        只读取已 commit 的事实行（backend append 返回值），因此 publish 天然
+        发生在 transaction commit 之后；replay→live 切换窗口由同一 cursor 去重。
+        """
+
+        cursor = int(after_seq or 0)
+        deadline = asyncio.get_running_loop().time() + timeout
+        while True:
+            rows = await self._service.get_events(session_id, after_seq_id=cursor)
+            rows.sort(key=lambda event: event.seq_id)
+            for row in rows:
+                cursor = row.seq_id
+                envelope = session_event_to_envelope(row)
+                if envelope is not None:
+                    _validate_runtime_payload(envelope)
+                    yield envelope
+            if asyncio.get_running_loop().time() >= deadline:
+                return
+            if should_stop is not None and await should_stop():
+                # 客户端断开：及时收口，而不是继续轮询到 timeout。
+                return
+            await asyncio.sleep(poll_interval)
+
+    async def _find_envelope(
+        self, envelope: SessionEventEnvelope
+    ) -> SessionEventEnvelope | None:
+        storage_id = session_event_storage_id(envelope.session_id, str(envelope.event_id))
+        stored = await self._service.get_event_by_id(envelope.session_id, storage_id)
+        return session_event_to_envelope(stored) if stored is not None else None
+
+    @staticmethod
+    def _assert_same_fact(
+        existing: SessionEventEnvelope, candidate: SessionEventEnvelope
+    ) -> None:
+        # ``seq`` is the store-assigned delivery cursor, not producer identity;
+        # the runtime payload's placeholder ``seq`` participates in the same rule.
+        def _comparable(envelope: SessionEventEnvelope) -> dict[str, Any]:
+            dump = envelope.model_dump(mode="json", exclude={"seq"})
+            payload = dict(dump.get("payload") or {})
+            payload.pop("seq", None)
+            dump["payload"] = payload
+            return dump
+
+        if _comparable(existing) != _comparable(candidate):
+            raise ValueError(f"SessionEvent id collision for {candidate.event_id!r}")
+
+    def _require_storage_capabilities(self, envelope: SessionEventEnvelope) -> None:
+        capabilities = self._service.storage_capabilities
+        required_binding = (
+            "runtime_event.seq"
+            if envelope.family == _RUNTIME_FAMILY
+            and envelope.family_version == _RUNTIME_FAMILY_VERSION
+            else "session_event.seq"
+        )
+        if required_binding not in capabilities.atomic_seq_bindings or (
+            not capabilities.indexed_event_lookup
+        ):
+            raise RuntimeError(
+                "session backend must support atomic "
+                f"{required_binding} binding and indexed physical event lookup"
+            )
+
+
+def _validate_runtime_payload(envelope: SessionEventEnvelope) -> None:
+    """family=runtime/v2 时 payload 必须通过现有 RuntimeEvent/v2 校验。"""
+
+    if envelope.family != _RUNTIME_FAMILY or envelope.family_version != _RUNTIME_FAMILY_VERSION:
+        return
+    try:
+        parse_runtime_event(dict(envelope.payload))
+    except Exception as error:  # noqa: BLE001 - surface as contract violation
+        raise ValueError(
+            f"runtime family payload failed RuntimeEvent/v2 validation: {error}"
+        ) from error
+
+
+__all__ = [
+    "SessionEventStore",
+    "SessionServiceEventStore",
+    "validate_write_guard",
+    "envelope_to_session_event",
+    "session_event_to_envelope",
+    "session_event_storage_id",
+]