agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/kernel/readiness.py

@@ -0,0 +1,125 @@
+"""Read runtime readiness from storage, leases, worker state, and contracts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ksadk.kernel.bootstrap import AgentKernelRuntime
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from ksadk.kernel.contract_fingerprints import (
+    AGENT_KERNEL_V1_AGGREGATE_DIGEST,
+    runtime_capability_admission_digest,
+    runtime_capability_matrix_wire_value,
+)
+from ksadk.kernel.runtime_identity import runtime_identity
+
+
+@dataclass
+class AgentKernelReadiness:
+    """truthful readiness probe：每个维度都是真实查询，不是配置回显。"""
+
+    runtime: "AgentKernelRuntime"
+
+    async def check(self) -> dict[str, Any]:
+        config = self.runtime.config
+        store_ok = False
+        try:
+            # 真实 store 查询（PG driver 即真实 SQL round-trip）。
+            await self.runtime.kernel_store.list_messages(config.agent_instance_id)
+            store_ok = True
+        except Exception:
+            store_ok = False
+
+        lease_healthy = True
+        activation_id: str | None = None
+        for session_id in self.runtime.heartbeat_sessions():
+            try:
+                lease = await self.runtime.kernel_store.current_lease(
+                    config.agent_instance_id, session_id
+                )
+            except Exception:
+                lease = None
+            if lease is None:
+                lease_healthy = False
+                continue
+            if not self.runtime.lease_heartbeat.owns_lease(session_id, lease):
+                # lease 存在但已被其它 activation 接管：对本 runtime 而言
+                # 等价于丢失，必须如实上报 not-ready。
+                lease_healthy = False
+                continue
+            activation_id = activation_id or lease.activation_id
+            expires = getattr(lease, "lease_expires_at", "")
+            try:
+                from datetime import datetime
+
+                expires_at = datetime.fromisoformat(str(expires).replace("Z", "+00:00"))
+                if expires_at <= datetime.now(expires_at.tzinfo):
+                    lease_healthy = False
+            except ValueError:
+                lease_healthy = False
+
+        worker_running = self.runtime.worker_running
+        degraded = self.runtime.degraded
+        quarantined = self.runtime.quarantined_sessions()
+        capability = self.runtime.kernel.capabilities()
+        capability_matrix = runtime_capability_matrix_wire_value(capability)
+        computed_capability_digest = runtime_capability_admission_digest(
+            capability, config.capability_digest
+        )
+        # The control plane compares all three digests before declaring an
+        # AgentInstance ready.  Reporting ready with only a contract digest
+        # would conceal a missing bundle/capability projection and make the
+        # runtime's health endpoint more optimistic than Server readiness.
+        digests_match = all(
+            (
+                config.contract_digest == AGENT_KERNEL_V1_AGGREGATE_DIGEST,
+                config.capability_digest == computed_capability_digest,
+                config.bundle_digest,
+            )
+        )
+        ready = store_ok and worker_running and lease_healthy and digests_match and not degraded
+        health = {
+            "ready": ready,
+            "store_ok": store_ok,
+            "worker_running": worker_running,
+            "degraded": degraded,
+            # additive：被隔离（恢复失败）的 session 数量；隔离本身不影响
+            # ready，其余 session 照常服务。
+            "quarantined_sessions": len(quarantined),
+            "lease_healthy": lease_healthy,
+            "activation_id": activation_id,
+            # Contract support is packaged with this KsADK image; never echo
+            # an unverified control-plane environment value as evidence.
+            "contract_digest": AGENT_KERNEL_V1_AGGREGATE_DIGEST,
+            # Derive the admission proof from the actual Adapter matrix and the
+            # selected policy rather than echoing the deployment value blindly.
+            "capability_digest": computed_capability_digest,
+            # Runtime/Operator/Server readiness chain must carry the actual
+            # typed capability facts, not merely a digest supplied at deploy
+            # time. Server admission uses these to reject unsupported control
+            # operations before they enter the durable inbox.
+            "capabilities": capability_matrix,
+            "bundle_digest": config.bundle_digest,
+            "durability_tier": config.durability_tier,
+            # Identity is derived from the KsADK source Python imported, not
+            # ``importlib.metadata`` for the base image distribution.
+            "runtime_identity": runtime_identity(),
+        }
+        # 诊断字段（additive，runtime 内部端点非 wire 冻结合同）：
+        # degraded 时必须能从 health 直接回答 "为什么降级、何时降级"，
+        # 出问题的 session 明细同样可见，运维不必再对着布尔值猜。
+        teams_descriptor = getattr(self.runtime, "teams_host_descriptor", None)
+        if teams_descriptor is not None:
+            health["teams_host"] = await teams_descriptor()
+        if quarantined:
+            health["quarantined_session_ids"] = sorted(quarantined)
+        if degraded:
+            health["degradation_reason"] = self.runtime._degradation_reason
+            health["degraded_at"] = self.runtime._degraded_at
+            health["degradation_last_error"] = self.runtime._degraded_last_error
+        return health

ksadk/kernel/recovery.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""冷恢复决策表：RecoveryCoordinator（Phase 1 Task 7）。
+"""冷恢复决策表：RecoveryCoordinator（Kernel Task 7）。
 
 接管一个 agent_instance 的 open run 时按固定决策表收口：
 
@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import time
+from contextlib import nullcontext
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Literal
@@ -31,6 +32,7 @@ from ksadk.kernel.contracts import (
     RuntimeCapabilityMatrix,
     WriteContext,
 )
+from ksadk.kernel.errors import InvalidCommandError, StaleFenceError
 from ksadk.kernel.state import RunState, is_terminal_run
 from ksadk.kernel.store import AgentKernelStore, RunRecord, control_event
 
@@ -80,8 +82,10 @@ class RecoveryCoordinator:
         executor: "RuntimeExecutor | None" = None,
         launch_context: "RuntimeLaunchContext | None" = None,
         adapter_factory: Callable[[], object] | None = None,
+        session_service=None,
         clock: Callable[[], float] = time.time,
         execution_sink: Callable[..., None] | None = None,
+        recovery_stream_sink: Callable[..., object] | None = None,
     ) -> None:
         self._store = store
         self._session_events = session_events
@@ -89,10 +93,12 @@ class RecoveryCoordinator:
         self._executor = executor
         self._launch_context = launch_context
         self._adapter_factory = adapter_factory
+        self._session_service = session_service
         self._clock = clock
         # Task 6：takeover 重建的 ActiveExecution 只在 lease 获取 +
         # provider 支持的 attach/resume 成功后回调注册（worker.adopt_execution）。
         self._execution_sink = execution_sink
+        self._recovery_stream_sink = recovery_stream_sink
 
     async def recover(
         self,
@@ -100,12 +106,28 @@ class RecoveryCoordinator:
         activation: ActivationLease,
         *,
         run_id: str | None = None,
+        session_id: str | None = None,
+    ) -> RecoveryReport:
+        from ksadk.sessions import bind_session_service
+
+        binding = (bind_session_service(self._session_service)
+                   if self._session_service is not None else nullcontext())
+        with binding:
+            return await self._recover_bound(
+                agent_instance_id, activation, run_id=run_id, session_id=session_id
+            )
+
+    async def _recover_bound(
+        self, agent_instance_id: str, activation: ActivationLease, *,
+        run_id: str | None = None, session_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)
+        run = await self._load_run(agent_instance_id, run_id, session_id=session_id)
+        if run is not None:
+            await self._require_session_lease(run, activation)
         if run is None or is_terminal_run(run.state):
             return await self._decide(
                 agent_instance_id,
@@ -131,11 +153,46 @@ class RecoveryCoordinator:
             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
+            and (
+                self._adapter_factory is not None
+                or (self._executor is not None and self._launch_context is not None)
+            )
         ):
             try:
-                handle = await self._executor.attach_record(run, self._launch_context)
+                from ksadk.runtime.adapter import RunHandle
+
+                persisted_handle = RunHandle.model_validate(handle_dump)
+                if self._adapter_factory is not None:
+                    # PluginHost/DSH builds must recover through their pinned
+                    # provider adapter. Going through the global RuntimeExecutor
+                    # would create a different direct runtime and bypass the
+                    # provider's checkpoint, capabilities and resources.
+                    adapter = self._adapter_factory()
+                    prepare_record = getattr(adapter, "prepare_attach_record", None)
+                    if callable(prepare_record):
+                        await prepare_record(persisted_handle, run)
+                    handle = await adapter.durable_restore(persisted_handle)
+                    if handle != persisted_handle:
+                        raise ValueError(
+                            "adapter durable_restore must preserve persisted handle identity"
+                        )
+                    restore_record = getattr(adapter, "restore_run_record", None)
+                    if callable(restore_record):
+                        try:
+                            await restore_record(handle, run)
+                        except Exception:
+                            await adapter.close(handle)
+                            raise
+                    stream_owner = adapter
+                else:
+                    assert self._executor is not None
+                    assert self._launch_context is not None
+                    handle = await self._executor.attach_record(run, self._launch_context)
+                    adapter = self._executor.adapter_for_handle(handle)
+                    stream_owner = self._executor
+
+                def stream():  # type: ignore[no-untyped-def]
+                    return stream_owner.stream(handle)
             except Exception as error:
                 return await self._decide(
                     agent_instance_id,
@@ -145,18 +202,61 @@ class RecoveryCoordinator:
                     reason=f"attach_failed:{type(error).__name__}",
                     guard=guard,
                 )
+            scoped_stream_requirement = getattr(adapter, "requires_recovery_stream", None)
+            requires_stream = (
+                scoped_stream_requirement(handle)
+                if callable(scoped_stream_requirement)
+                else getattr(adapter, "recovery_requires_stream", False)
+            )
+            if requires_stream:
+                try:
+                    if self._recovery_stream_sink is None:
+                        raise RuntimeError("runtime recovery requires a worker stream owner")
+                    self._recovery_stream_sink(run=run, adapter=adapter, handle=handle, guard=guard)
+                except Exception as error:
+                    await adapter.close(handle)
+                    return await self._decide(
+                        agent_instance_id,
+                        activation,
+                        run,
+                        outcome="failed",
+                        reason=f"recovery_stream_failed:{type(error).__name__}",
+                        guard=guard,
+                    )
+                return await self._decide(
+                    agent_instance_id,
+                    activation,
+                    run,
+                    outcome="attached",
+                    reason="durable_stream_restarted",
+                    guard=guard,
+                )
+
             # attach 成功即把 live execution 交还 worker（lease 已在调用方获取，
             # attach 已证明 runtime 支持接管），stream 消费失败时仍保留。
             self._register_execution(
                 run.run_id,
                 handle.run_id,
-                getattr(self._executor, "adapter", None),
+                adapter,
                 handle,
             )
+            if run.state is RunState.WAITING:
+                # A durable interaction checkpoint has no remaining events
+                # until a user/approver replies.  Empty stream output here is
+                # not completion: retain WAITING and the attached execution so
+                # submit_interaction reaches the same provider instance.
+                return await self._decide(
+                    agent_instance_id,
+                    activation,
+                    run,
+                    outcome="attached",
+                    reason="durable_interaction_attached",
+                    guard=guard,
+                )
             # attach 成功后重新消费剩余 stream：事实继续落库，自然结束收口。
             try:
                 await self._consume_remaining_stream(
-                    lambda: self._executor.stream(handle),  # type: ignore[union-attr]
+                    stream,
                     run,
                     guard,
                 )
@@ -203,6 +303,7 @@ class RecoveryCoordinator:
         activation: ActivationLease,
         *,
         reason: str = "recover_error_settled_interrupted",
+        session_id: str | None = None,
     ) -> RecoveryReport:
         """P0-1 兜底收口：``recover`` 抛错后的确定性 interrupted 决策。
 
@@ -216,7 +317,9 @@ class RecoveryCoordinator:
             activation_id=activation.activation_id,
             fencing_token=activation.fencing_token,
         )
-        run = await self._load_run(agent_instance_id, None)
+        run = await self._load_run(agent_instance_id, None, session_id=session_id)
+        if run is not None:
+            await self._require_session_lease(run, activation)
         if run is None or is_terminal_run(run.state):
             return await self._decide(
                 agent_instance_id,
@@ -332,28 +435,55 @@ class RecoveryCoordinator:
     ) -> None:
         """消费剩余事件流（run_id 统一 durable id），自然结束收口 COMPLETED。"""
 
+        from ksadk.kernel.recovery_projection import RecoveryEventReconciler
+
         runtime_store = RuntimeEventStore(self._session_events, session_id=run.session_id)
+        reconciler = RecoveryEventReconciler(
+            await runtime_store.list(run.session_id, run_id=run.run_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]
+            for candidate in reconciler.accept(event):
+                await runtime_store.append(candidate, guard=guard)  # type: ignore[arg-type]
+        for candidate in reconciler.flush():
+            await runtime_store.append(candidate, 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
+        self, agent_instance_id: str, run_id: str | None, *, session_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
+            run = await self._store.load_run(run_id)
+        else:
+            run = await self._store.find_active_run(agent_instance_id, session_id)
+        if run is not None and (
+            run.agent_instance_id != agent_instance_id
+            or (session_id is not None and run.session_id != session_id)
+        ):
+            raise InvalidCommandError("Run does not belong to the requested recovery scope")
+        return run
+
+    async def _require_session_lease(
+        self, run: RunRecord, activation: ActivationLease
+    ) -> None:
+        # Fencing counters are independent per session and commonly equal.
+        # Validate the activation identity before attaching a native execution;
+        # a matching integer alone cannot authorize another member's Run.
+        owned = await self._store.current_lease(run.agent_instance_id, run.session_id)
+        if (
+            activation.agent_instance_id != run.agent_instance_id
+            or owned is None
+            or owned.activation_id != activation.activation_id
+            or owned.fencing_token != activation.fencing_token
+        ):
+            raise StaleFenceError("recovery requires the Run's current session lease")
 
     async def _interrupt_deterministically(
         self,
@@ -365,6 +495,17 @@ class RecoveryCoordinator:
         reason: str = "runtime_not_durably_attachable",
     ) -> RecoveryReport:
         fence = activation.fencing_token
+        tenant = str(run.metadata.get("tenant_id") or "")
+        if tenant:
+            for interaction in await self._store.list_pending_interactions(tenant, run.session_id):
+                if (
+                    interaction.run_id == run.run_id
+                    and interaction.agent_instance_id == agent_instance_id
+                    and interaction.provider_id == "managed-a2a"
+                ):
+                    await self._store.cancel(
+                        interaction.interaction_id, interaction.revision, guard=guard
+                    )
         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)
@@ -378,7 +519,16 @@ class RecoveryCoordinator:
                 timestamp=self._clock(),
                 reason=reason,
             )
-            pipeline = CanonicalEventPipeline(runtime_store, session_id=run.session_id)
+            # Settlement closes items created by the previous owner. Validate
+            # against that run's persisted facts, not an empty projection.
+            from ksadk.events.reducer import StreamReducer
+
+            reducer = StreamReducer()
+            for persisted in await runtime_store.list(run.session_id, run_id=run.run_id):
+                reducer.apply(persisted)
+            pipeline = CanonicalEventPipeline(
+                runtime_store, session_id=run.session_id, reducer=reducer
+            )
             for event in events:
                 persisted = await pipeline.emit(event, write_context=guard)
                 written.append(persisted)

ksadk/kernel/recovery_projection.py

@@ -0,0 +1,124 @@
+"""Reconcile provider replay with already durable root output during takeover."""
+
+from __future__ import annotations
+
+import json
+
+from ksadk.events.canonical import (
+    ItemCompleted,
+    ItemFailed,
+    ItemSnapshotReplaced,
+    ItemStarted,
+    ItemUpdated,
+    RunCompleted,
+    RuntimeEvent,
+)
+
+
+def _root_message_fingerprint(event: ItemCompleted) -> str | None:
+    if event.item_kind != "message" or event.parent_scope_id is not None:
+        return None
+    source = event.source
+    metadata = source.metadata
+    stable_source = {
+        "framework": source.framework,
+        "native_run_id": source.native_run_id,
+        "scope_id": event.scope_id,
+        "path_key": metadata.get("path_key"),
+        "path": metadata.get("path"),
+        "author": metadata.get("author"),
+    }
+    return json.dumps(
+        {
+            "source": stable_source,
+            "snapshot": event.snapshot.model_dump(mode="json"),
+        },
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+
+
+class RecoveryEventReconciler:
+    """Drop one replayed root message without weakening normal item identity.
+
+    Native ADK recovery may reconstruct the final provider message with fresh
+    native/event/item ids after that same complete message was durably written
+    but before ``run.completed`` committed.  Buffering only the recovery
+    stream's root message lets us compare the complete snapshot.  Ordinary
+    live streams never use this reconciler, so equal-text distinct items remain
+    distinct there.
+    """
+
+    def __init__(self, prior_events: list[RuntimeEvent]) -> None:
+        self._prior: dict[str, str] = {}
+        for event in prior_events:
+            if isinstance(event, ItemCompleted):
+                fingerprint = _root_message_fingerprint(event)
+                if fingerprint is not None:
+                    self._prior[fingerprint] = event.item_id
+        self._pending_item_id: str | None = None
+        self._pending: list[RuntimeEvent] = []
+        self._aliases: dict[str, str] = {}
+        self._novel_root_message_seen = False
+
+    def accept(self, event: RuntimeEvent) -> tuple[RuntimeEvent, ...]:
+        if isinstance(event, ItemStarted) and self._is_root_message(event):
+            flushed = self.flush()
+            self._pending_item_id = event.item_id
+            self._pending = [event]
+            return flushed
+
+        if self._pending_item_id == getattr(event, "item_id", None):
+            if isinstance(event, (ItemUpdated, ItemSnapshotReplaced)):
+                self._pending.append(event)
+                return ()
+            if isinstance(event, ItemCompleted):
+                fingerprint = _root_message_fingerprint(event)
+                prior_item_id = self._prior.get(fingerprint or "")
+                pending = tuple(self._pending)
+                replayed_item_id = self._pending_item_id
+                self._pending_item_id = None
+                self._pending = []
+                if prior_item_id is not None and not self._novel_root_message_seen:
+                    self._aliases[replayed_item_id] = prior_item_id
+                    return ()
+                self._novel_root_message_seen = True
+                if fingerprint is not None:
+                    self._prior.setdefault(fingerprint, event.item_id)
+                return (*pending, event)
+            if isinstance(event, ItemFailed):
+                pending = tuple(self._pending)
+                self._pending_item_id = None
+                self._pending = []
+                self._novel_root_message_seen = True
+                return (*pending, event)
+
+        flushed = self.flush()
+        if isinstance(event, RunCompleted) and self._aliases:
+            event = event.model_copy(
+                update={
+                    "output_refs": tuple(
+                        ref.model_copy(
+                            update={"item_id": self._aliases.get(ref.item_id, ref.item_id)}
+                        )
+                        for ref in event.output_refs
+                    )
+                }
+            )
+        return (*flushed, event)
+
+    def flush(self) -> tuple[RuntimeEvent, ...]:
+        pending = tuple(self._pending)
+        if pending:
+            self._novel_root_message_seen = True
+        self._pending_item_id = None
+        self._pending = []
+        return pending
+
+    @staticmethod
+    def _is_root_message(event: ItemStarted) -> bool:
+        return event.item_kind == "message" and event.parent_scope_id is None
+
+
+__all__ = ["RecoveryEventReconciler"]

ksadk/kernel/runtime_checkpoint.py

@@ -0,0 +1,34 @@
+"""Private adapter checkpoints; writes must not change a Run's control state."""
+
+import json
+
+from ksadk.kernel.errors import InvalidCommandError
+from ksadk.kernel.state import RunState
+
+RUNTIME_CHECKPOINT_KEY = "runtime_checkpoint"
+MAX_CHECKPOINT_BYTES = 12 * 1024 * 1024
+
+
+def checkpoint_copy(value: dict) -> dict:
+    if not isinstance(value, dict):
+        raise ValueError("runtime checkpoint must be an object")
+    encoded = json.dumps(value, ensure_ascii=False, allow_nan=False)
+    if len(encoded.encode("utf-8")) > MAX_CHECKPOINT_BYTES:
+        raise ValueError("runtime checkpoint is too large")
+    return json.loads(encoded)
+
+
+def require_checkpoint_owner(run, *, agent_instance_id, session_id):
+    if run is None or run.agent_instance_id != agent_instance_id or run.session_id != session_id:
+        raise InvalidCommandError("runtime checkpoint run identity mismatch")
+    if run.state not in {RunState.RUNNING, RunState.WAITING, RunState.PAUSED}:
+        raise InvalidCommandError("runtime checkpoint requires an active run")
+
+
+def preserve_runtime_checkpoint(incoming: dict, existing: dict | None) -> dict:
+    """Only the checkpoint writer can replace this reserved private field."""
+    result = dict(incoming)
+    result.pop(RUNTIME_CHECKPOINT_KEY, None)
+    if existing is not None and RUNTIME_CHECKPOINT_KEY in existing:
+        result[RUNTIME_CHECKPOINT_KEY] = existing[RUNTIME_CHECKPOINT_KEY]
+    return result

ksadk/kernel/sql/001_agent_kernel.sql

@@ -118,3 +118,31 @@ CREATE TABLE IF NOT EXISTS kernel_interaction_submissions (
   created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
   PRIMARY KEY (tenant_id, interaction_id, idempotency_key)
 );
+
+-- Revocable execution-grants/v1 extension. Grant lock precedes Inbox lock.
+-- Timestamps use the portable wire representation; receipts are stable JSON.
+CREATE TABLE IF NOT EXISTS kernel_execution_grants (
+  grant_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  agent_instance_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  owner_ref TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('active','suspended','revoked')),
+  revision BIGINT NOT NULL CHECK (revision > 0),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_kernel_execution_grants_scope
+  ON kernel_execution_grants (tenant_id, agent_instance_id, session_id);
+-- Additive upgrade: existing non-expiring grants retain their old semantics.
+ALTER TABLE kernel_execution_grants ADD COLUMN IF NOT EXISTS attempt_epoch BIGINT CHECK (attempt_epoch > 0);
+ALTER TABLE kernel_execution_grants ADD COLUMN IF NOT EXISTS expires_at TEXT;
+ALTER TABLE kernel_execution_grants ADD COLUMN IF NOT EXISTS admission_allowed BOOLEAN NOT NULL DEFAULT TRUE;
+ALTER TABLE kernel_execution_grants ADD COLUMN IF NOT EXISTS admission_revision BIGINT NOT NULL DEFAULT 1 CHECK (admission_revision > 0);
+CREATE TABLE IF NOT EXISTS kernel_execution_grant_operations (
+  grant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  request_digest TEXT NOT NULL,
+  receipt_json TEXT NOT NULL,
+  PRIMARY KEY (grant_id, idempotency_key)
+);