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

ksadk/kernel/recovery.py

@@ -0,0 +1,452 @@
+# -*- coding: utf-8 -*-
+"""冷恢复决策表：RecoveryCoordinator（Phase 1 Task 7）。
+
+接管一个 agent_instance 的 open run 时按固定决策表收口：
+
+- run 已终态（或不存在 open run）→ ``no_op``；
+- ``attach`` + ``durable_restore`` 能力可用且 durable handle digest 有效 →
+  ``attach``（跨进程接回 live handle）；
+- ``resume`` 能力可用且存在 continuation → ``resume``（从最后 continuation 续跑）；
+- 否则 → 确定性 ``interrupted``（唯一 ``run.interrupted`` + open item close），
+  reason 固定为 ``runtime_not_durably_attachable``。
+
+每个决定都追加一条 fenced ``control.recovery_decided`` 审计事实；
+``RecoveryReport`` 只用于审计与测试，不进入公网 projection。
+"""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+from ksadk.events.canonical import RuntimeEvent
+from ksadk.events.canonical_store import RuntimeEventStore
+from ksadk.events.cold_recovery import scan_open_runs, settle_finding
+from ksadk.events.pipeline import CanonicalEventPipeline
+from ksadk.events.session_event import SessionEventStore
+from ksadk.kernel.contracts import (
+    ActivationLease,
+    ActivationWriteGuard,
+    RuntimeCapabilityMatrix,
+    WriteContext,
+)
+from ksadk.kernel.state import RunState, is_terminal_run
+from ksadk.kernel.store import AgentKernelStore, RunRecord, control_event
+
+if TYPE_CHECKING:  # pragma: no cover - import cycle guard
+    from ksadk.runtime.executor import RuntimeExecutor
+    from ksadk.runtime.launch import RuntimeLaunchContext
+
+RecoveryOutcome = Literal["no_op", "attached", "resumed", "interrupted", "failed"]
+
+CapabilityProvider = Callable[[], RuntimeCapabilityMatrix]
+
+
+@dataclass
+class RecoveryReport:
+    """一次 recover 决策的审计结果（不进入公网 projection）。"""
+
+    agent_instance_id: str
+    activation_id: str
+    run_id: str | None = None
+    outcome: RecoveryOutcome = "no_op"
+    reason: str | None = None
+    last_seq: int | None = None
+    written_events: list[RuntimeEvent] = field(default_factory=list)
+
+
+def _durable_handle_digest(handle_dump: dict) -> str | None:
+    """durable handle 行携带的 digest；缺失/形状不符返回 None。"""
+
+    try:
+        from ksadk.runtime.adapter import RunHandle
+        from ksadk.runtime.executor import handle_digest
+
+        return handle_digest(RunHandle.model_validate(handle_dump))
+    except Exception:
+        return None
+
+
+class RecoveryCoordinator:
+    """对 open run 做确定性收口或接管的协调器。"""
+
+    def __init__(
+        self,
+        store: AgentKernelStore,
+        session_events: SessionEventStore,
+        capabilities: CapabilityProvider,
+        *,
+        executor: "RuntimeExecutor | None" = None,
+        launch_context: "RuntimeLaunchContext | None" = None,
+        adapter_factory: Callable[[], object] | None = None,
+        clock: Callable[[], float] = time.time,
+        execution_sink: Callable[..., None] | None = None,
+    ) -> None:
+        self._store = store
+        self._session_events = session_events
+        self._capabilities = capabilities
+        self._executor = executor
+        self._launch_context = launch_context
+        self._adapter_factory = adapter_factory
+        self._clock = clock
+        # Task 6：takeover 重建的 ActiveExecution 只在 lease 获取 +
+        # provider 支持的 attach/resume 成功后回调注册（worker.adopt_execution）。
+        self._execution_sink = execution_sink
+
+    async def recover(
+        self,
+        agent_instance_id: str,
+        activation: ActivationLease,
+        *,
+        run_id: str | None = None,
+    ) -> RecoveryReport:
+        fence = activation.fencing_token
+        guard: WriteContext = ActivationWriteGuard(
+            activation_id=activation.activation_id, fencing_token=fence
+        )
+        run = await self._load_run(agent_instance_id, run_id)
+        if run is None or is_terminal_run(run.state):
+            return await self._decide(
+                agent_instance_id,
+                activation,
+                run,
+                outcome="no_op",
+                reason=(
+                    "run_already_terminal"
+                    if run is not None
+                    else "no_open_run_for_agent_instance"
+                ),
+                guard=guard,
+            )
+
+        capabilities = self._capabilities()
+        handle_dump = run.metadata.get("handle")
+        handle_digest_valid = (
+            isinstance(handle_dump, dict)
+            and isinstance(run.metadata.get("handle_digest"), str)
+            and _durable_handle_digest(handle_dump) == run.metadata.get("handle_digest")
+        )
+        if (
+            capabilities.attach.supported
+            and capabilities.durable_restore.supported
+            and handle_digest_valid
+            and self._executor is not None
+            and self._launch_context is not None
+        ):
+            try:
+                handle = await self._executor.attach_record(run, self._launch_context)
+            except Exception as error:
+                return await self._decide(
+                    agent_instance_id,
+                    activation,
+                    run,
+                    outcome="failed",
+                    reason=f"attach_failed:{type(error).__name__}",
+                    guard=guard,
+                )
+            # attach 成功即把 live execution 交还 worker（lease 已在调用方获取，
+            # attach 已证明 runtime 支持接管），stream 消费失败时仍保留。
+            self._register_execution(
+                run.run_id,
+                handle.run_id,
+                getattr(self._executor, "adapter", None),
+                handle,
+            )
+            # attach 成功后重新消费剩余 stream：事实继续落库，自然结束收口。
+            try:
+                await self._consume_remaining_stream(
+                    lambda: self._executor.stream(handle),  # type: ignore[union-attr]
+                    run,
+                    guard,
+                )
+            except Exception as error:
+                return await self._decide(
+                    agent_instance_id,
+                    activation,
+                    run,
+                    outcome="failed",
+                    reason=f"attach_stream_failed:{type(error).__name__}",
+                    guard=guard,
+                )
+            return await self._decide(
+                agent_instance_id,
+                activation,
+                run,
+                outcome="attached",
+                reason="durable_handle_attached",
+                guard=guard,
+            )
+
+        if capabilities.resume.supported and run.metadata.get("continuation_ref"):
+            resumed_report = await self._try_real_resume(
+                agent_instance_id, activation, run, guard=guard
+            )
+            if resumed_report is not None:
+                return resumed_report
+            return await self._decide(
+                agent_instance_id,
+                activation,
+                run,
+                outcome="resumed",
+                reason="continuation_resume_delegated",
+                guard=guard,
+            )
+
+        return await self._interrupt_deterministically(
+            agent_instance_id, activation, run, guard=guard
+        )
+
+    async def settle_interrupted(
+        self,
+        agent_instance_id: str,
+        activation: ActivationLease,
+        *,
+        reason: str = "recover_error_settled_interrupted",
+    ) -> RecoveryReport:
+        """P0-1 兜底收口：``recover`` 抛错后的确定性 interrupted 决策。
+
+        不依赖任何 runtime 能力：直接对 open run 写唯一
+        ``run.interrupted`` + open item close，并以当前 fencing 追加
+        ``control.recovery_decided`` 审计事实。没有 open run 时退化为
+        ``no_op``。持久化失败向上抛出，由调用方决定 degraded。
+        """
+
+        guard: WriteContext = ActivationWriteGuard(
+            activation_id=activation.activation_id,
+            fencing_token=activation.fencing_token,
+        )
+        run = await self._load_run(agent_instance_id, None)
+        if run is None or is_terminal_run(run.state):
+            return await self._decide(
+                agent_instance_id,
+                activation,
+                run,
+                outcome="no_op",
+                reason=(
+                    "run_already_terminal"
+                    if run is not None
+                    else "no_open_run_for_agent_instance"
+                ),
+                guard=guard,
+            )
+        return await self._interrupt_deterministically(
+            agent_instance_id, activation, run, guard=guard, reason=reason
+        )
+
+    # ------------------------------------------------------------- internals
+
+    def _register_execution(
+        self,
+        durable_run_id: str,
+        runtime_run_id: str,
+        adapter: object | None,
+        handle: object,
+    ) -> None:
+        """把 takeover 重建的 live execution 交还 worker（best-effort）。"""
+
+        if self._execution_sink is None or adapter is None:
+            return
+        try:
+            self._execution_sink(
+                durable_run_id=durable_run_id,
+                runtime_run_id=runtime_run_id,
+                adapter=adapter,
+                handle=handle,
+            )
+        except Exception:  # noqa: BLE001 - 审计/恢复路径绝不因 sink 失败中断
+            pass
+
+    async def _try_real_resume(
+        self,
+        agent_instance_id: str,
+        activation: ActivationLease,
+        run: RunRecord,
+        *,
+        guard: WriteContext,
+    ) -> RecoveryReport | None:
+        """用真实 adapter 从 continuation 恢复执行并继续消费 stream。
+
+        返回 ``None`` 表示没有可用 adapter（委托 worker 重放的旧路径）。
+        adapter 不支持 resume 时保持确定性收口（interrupted）。
+        """
+
+        from ksadk.kernel.errors import UnsupportedControlError
+        from ksadk.runtime.adapter import ResumeTarget, RunHandle
+
+        if self._adapter_factory is None:
+            return None
+        handle_dump = run.metadata.get("handle")
+        continuation_ref = run.metadata.get("continuation_ref")
+        if not isinstance(handle_dump, dict) or not continuation_ref:
+            return None
+        adapter = self._adapter_factory()
+        try:
+            handle = RunHandle.model_validate(handle_dump)
+            resumed = await adapter.resume(
+                handle,
+                ResumeTarget(kind="invocation_id", id=str(continuation_ref)),
+                None,
+            )
+        except UnsupportedControlError:
+            # EchoAdapter 等不支持 resume 的 runtime：确定性收口，不重试。
+            return await self._interrupt_deterministically(
+                agent_instance_id, activation, run, guard=guard
+            )
+        except Exception as error:
+            return await self._decide(
+                agent_instance_id,
+                activation,
+                run,
+                outcome="failed",
+                reason=f"resume_failed:{type(error).__name__}",
+                guard=guard,
+            )
+        # lease 已获取 + provider 支持的 resume 已成功：takeover 重建
+        # ActiveExecution，后续控制命令/回包作用于同一 live execution。
+        self._register_execution(run.run_id, resumed.run_id, adapter, resumed)
+        try:
+            await self._consume_remaining_stream(
+                lambda: adapter.stream(resumed), run, guard
+            )
+        except Exception as error:
+            return await self._decide(
+                agent_instance_id,
+                activation,
+                run,
+                outcome="failed",
+                reason=f"resume_stream_failed:{type(error).__name__}",
+                guard=guard,
+            )
+        return await self._decide(
+            agent_instance_id,
+            activation,
+            run,
+            outcome="resumed",
+            reason="continuation_resumed",
+            guard=guard,
+        )
+
+    async def _consume_remaining_stream(
+        self, stream_factory, run: RunRecord, guard: WriteContext
+    ) -> None:
+        """消费剩余事件流（run_id 统一 durable id），自然结束收口 COMPLETED。"""
+
+        runtime_store = RuntimeEventStore(self._session_events, session_id=run.session_id)
+        async for event in stream_factory():
+            if event.run_id != run.run_id:
+                update: dict = {"run_id": run.run_id}
+                if getattr(event, "scope_id", None) == f"run:{event.run_id}":
+                    update["scope_id"] = f"run:{run.run_id}"
+                event = event.model_copy(update=update)
+            await runtime_store.append(event, guard=guard)  # type: ignore[arg-type]
+        await self._store.save_run_transition(
+            run.model_copy(update={"state": RunState.COMPLETED}),
+            expected_fence=guard.fencing_token,  # type: ignore[attr-defined]
+        )
+
+    async def _load_run(
+        self, agent_instance_id: str, run_id: str | None
+    ) -> RunRecord | None:
+        if run_id is not None:
+            return await self._store.load_run(run_id)
+        finder = getattr(self._store, "find_active_run", None)
+        if finder is not None:
+            return await finder(agent_instance_id)
+        return None
+
+    async def _interrupt_deterministically(
+        self,
+        agent_instance_id: str,
+        activation: ActivationLease,
+        run: RunRecord,
+        *,
+        guard: WriteContext,
+        reason: str = "runtime_not_durably_attachable",
+    ) -> RecoveryReport:
+        fence = activation.fencing_token
+        runtime_store = RuntimeEventStore(self._session_events, session_id=run.session_id)
+        findings = await scan_open_runs(runtime_store, run.session_id)
+        finding = next((item for item in findings if item.run_id == run.run_id), None)
+        written: list[RuntimeEvent] = []
+        last_seq: int | None = None
+        if finding is not None:
+            events = settle_finding(
+                finding,
+                run.session_id,
+                allow_resume=False,
+                timestamp=self._clock(),
+                reason=reason,
+            )
+            pipeline = CanonicalEventPipeline(runtime_store, session_id=run.session_id)
+            for event in events:
+                persisted = await pipeline.emit(event, write_context=guard)
+                written.append(persisted)
+                last_seq = persisted.seq
+        await self._store.save_run_transition(
+            run.model_copy(update={"state": RunState.INTERRUPTED}),
+            expected_fence=fence,
+        )
+        return await self._decide(
+            agent_instance_id,
+            activation,
+            run,
+            outcome="interrupted",
+            reason=reason,
+            guard=guard,
+            written=written,
+            last_seq=last_seq,
+        )
+
+    async def _decide(
+        self,
+        agent_instance_id: str,
+        activation: ActivationLease,
+        run: RunRecord | None,
+        *,
+        outcome: RecoveryOutcome,
+        reason: str,
+        guard: WriteContext,
+        written: list[RuntimeEvent] | None = None,
+        last_seq: int | None = None,
+    ) -> RecoveryReport:
+        if run is not None:
+            await self._store.append_event(
+                control_event(
+                    session_id=run.session_id,
+                    event_type="control.recovery_decided",
+                    payload={
+                        "agent_instance_id": agent_instance_id,
+                        "activation_id": activation.activation_id,
+                        "fencing_token": activation.fencing_token,
+                        "run_id": run.run_id,
+                        "outcome": outcome,
+                        "reason": reason,
+                    },
+                    run_id=run.run_id,
+                ),
+                expected_fence=activation.fencing_token,
+                agent_instance_id=agent_instance_id,
+            )
+        return RecoveryReport(
+            agent_instance_id=agent_instance_id,
+            activation_id=activation.activation_id,
+            run_id=run.run_id if run is not None else None,
+            outcome=outcome,
+            reason=reason,
+            last_seq=last_seq,
+            written_events=list(written or []),
+        )
+
+
+def durable_handle_digest(handle_dump: dict) -> str | None:
+    """Public shim kept for callers that only need digest validation."""
+    return _durable_handle_digest(handle_dump)
+
+
+__all__ = [
+    "RecoveryCoordinator",
+    "RecoveryReport",
+    "RecoveryOutcome",
+    "durable_handle_digest",
+]

ksadk/kernel/runtime_identity.py

@@ -0,0 +1,103 @@
+"""Non-secret provenance for the KsADK code that is actually imported.
+
+The base runtime image may contain an older ``ksadk`` distribution while a
+Code deployment shadows it from ``/app/code``.  Health must therefore report
+the source package identity, never the base image's distribution metadata.
+
+``_bundle_identity.py`` is generated into Code archives by :class:`CodeBuilder`.
+It is package content, not a user environment variable, and is intentionally
+optional so legacy images report an honest incomplete provenance record.
+
+The managed-runtime image also attests the exact wheel it installs.  That
+image provenance is used only when Python is importing KsADK from the image's
+``site-packages`` directory.  A Code archive that shadows KsADK must carry its
+own bundle identity; an environment variable from the base image must never
+claim provenance for user-supplied code.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from ksadk.version import VERSION
+
+_COMMIT_RE = re.compile(r"^[0-9a-f]{40,64}$")
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _imports_image_installed_ksadk() -> bool:
+    """Whether ``ksadk`` is the distribution installed by the runtime image."""
+
+    try:
+        package = importlib.import_module("ksadk")
+        package_file = Path(str(package.__file__ or "")).resolve()
+    except (ImportError, OSError, RuntimeError):
+        return False
+    return "site-packages" in package_file.parts
+
+
+def _image_identity() -> dict[str, str]:
+    """Read image-attested provenance without trusting it for shadowed code."""
+
+    if not _imports_image_installed_ksadk():
+        return {}
+    return {
+        "ksadk_commit": str(
+            os.environ.get("KSADK_RUNTIME_IMAGE_SOURCE_COMMIT") or ""
+        ).lower(),
+        "ksadk_wheel_sha256": str(
+            os.environ.get("KSADK_RUNTIME_IMAGE_WHEEL_SHA256") or ""
+        ).lower(),
+    }
+
+
+@lru_cache(maxsize=1)
+def runtime_identity() -> dict[str, str]:
+    """Return the provenance embedded beside the imported KsADK package.
+
+    Missing or malformed optional provenance is represented by an empty field.
+    Image provenance is accepted only for the image-installed distribution;
+    callers must not substitute a process environment value for Code-bundled
+    KsADK or infer identity from an image tag.
+    """
+
+    identity: dict[str, str] = {
+        "ksadk_version": VERSION,
+        "ksadk_commit": "",
+        "ksadk_source_digest": "",
+        "ksadk_wheel_sha256": "",
+    }
+    try:
+        bundled: Any = importlib.import_module("ksadk._bundle_identity")
+        candidate = getattr(bundled, "BUNDLE_IDENTITY", {})
+    except (ImportError, AttributeError):
+        candidate = {}
+    if isinstance(candidate, dict) and str(candidate.get("ksadk_version") or "") == VERSION:
+        # A Code bundle is the closest provenance of the code Python imported.
+        commit = str(candidate.get("ksadk_commit") or "").lower()
+        digest = str(candidate.get("ksadk_source_digest") or "").lower()
+        if _COMMIT_RE.fullmatch(commit):
+            identity["ksadk_commit"] = commit
+        if _SHA256_RE.fullmatch(digest):
+            identity["ksadk_source_digest"] = digest
+        if identity["ksadk_commit"] or identity["ksadk_source_digest"]:
+            return identity
+
+    # No valid bundle identity means the installed image distribution is the
+    # imported source only when it has not been shadowed by a Code archive.
+    image = _image_identity()
+    commit = image.get("ksadk_commit", "")
+    wheel_digest = image.get("ksadk_wheel_sha256", "")
+    if _COMMIT_RE.fullmatch(commit):
+        identity["ksadk_commit"] = commit
+    if _SHA256_RE.fullmatch(wheel_digest):
+        identity["ksadk_wheel_sha256"] = wheel_digest
+    return identity
+
+
+__all__ = ["runtime_identity"]

ksadk/kernel/sql/001_agent_kernel.sql

@@ -0,0 +1,120 @@
+-- Agent Kernel durable state (Phase 1 Task 4).
+-- BIGINT fencing_token / TIMESTAMPTZ lease / JSONB payload.
+-- Idempotency: (tenant_id, session_id, idempotency_key) unique.
+-- Claim ordering: FOR UPDATE SKIP LOCKED ordered by accepted_seq (see postgres_store.py).
+
+CREATE TABLE IF NOT EXISTS kernel_inbox (
+  message_id UUID PRIMARY KEY,
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  agent_instance_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  request_digest TEXT NOT NULL,
+  accepted_seq BIGINT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('accepted','claimed','completed','discarded')),
+  claimed_fence BIGINT,
+  payload JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (tenant_id, session_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS idx_kernel_inbox_claim
+  ON kernel_inbox (agent_instance_id, session_id, status, accepted_seq);
+
+CREATE TABLE IF NOT EXISTS kernel_runs (
+  run_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  agent_instance_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN (
+    'pending','running','paused','waiting','completed','failed','cancelled','interrupted'
+  )),
+  activation_fence BIGINT NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  metadata JSONB NOT NULL DEFAULT '{}'::jsonb
+);
+CREATE INDEX IF NOT EXISTS idx_kernel_runs_session_state
+  ON kernel_runs (session_id, state);
+
+-- Activation lease: one row per (agent_instance_id, session_id). Takeover uses
+-- INSERT .. ON CONFLICT .. DO UPDATE .. WHERE lease_expires_at <= now()
+-- (or released / same activation) and atomically bumps fencing_token + 1.
+CREATE TABLE IF NOT EXISTS kernel_activations (
+  agent_instance_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  activation_id TEXT NOT NULL,
+  fencing_token BIGINT NOT NULL,
+  lease_expires_at TIMESTAMPTZ NOT NULL,
+  released BOOLEAN NOT NULL DEFAULT FALSE,
+  runtime_type TEXT NOT NULL DEFAULT 'ksadk',
+  bundle_digest TEXT NOT NULL DEFAULT '',
+  capability_digest TEXT NOT NULL DEFAULT '',
+  PRIMARY KEY (agent_instance_id, session_id)
+);
+CREATE INDEX IF NOT EXISTS idx_kernel_activations_expiry
+  ON kernel_activations (lease_expires_at);
+
+CREATE TABLE IF NOT EXISTS kernel_accepted_seq (
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  session_id TEXT NOT NULL,
+  last_seq BIGINT NOT NULL DEFAULT 0,
+  PRIMARY KEY (tenant_id, session_id)
+);
+
+-- Mutation permit nonce 单次使用（durable replay 防护，跨 Pod / 重启共享）。
+-- register 语义见 postgres_store.PostgresNonceStore：INSERT .. ON CONFLICT DO
+-- NOTHING，冲突时读回 (command_id, idempotency_key) 判定网络重试 vs 重放。
+CREATE TABLE IF NOT EXISTS kernel_permit_nonces (
+  nonce TEXT PRIMARY KEY,
+  command_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_kernel_permit_nonces_created
+  ON kernel_permit_nonces (created_at);
+
+-- Durable Interaction ledger (Phase 1 Task 5). First-wins terminal CAS on
+-- (revision, status); terminal decision and its SessionEvent append happen in
+-- the same writer transaction (see postgres_store interaction methods).
+-- Row key: (tenant_id, interaction_id); idempotency submissions are unique on
+-- (tenant_id, interaction_id, idempotency_key).
+CREATE TABLE IF NOT EXISTS kernel_interactions (
+  interaction_id TEXT NOT NULL,
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  agent_instance_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  run_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('approval','structured_input','plan_review','custom')),
+  request_schema JSONB NOT NULL,
+  presentation JSONB,
+  revision BIGINT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN (
+    'pending','resolving','resolved','cancelled','expired'
+  )),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  expires_at TIMESTAMPTZ,
+  provider_id TEXT NOT NULL DEFAULT '',
+  native_target JSONB,
+  continuation_metadata JSONB,
+  request_digest TEXT NOT NULL,
+  response JSONB,
+  outcome TEXT,
+  actor TEXT,
+  event_id UUID,
+  accepted_seq BIGINT,
+  fencing_token BIGINT,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, interaction_id)
+);
+CREATE INDEX IF NOT EXISTS idx_kernel_interactions_pending
+  ON kernel_interactions (tenant_id, session_id, status);
+
+CREATE TABLE IF NOT EXISTS kernel_interaction_submissions (
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  interaction_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  submission_digest TEXT NOT NULL,
+  receipt JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, interaction_id, idempotency_key)
+);