netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/management/service.py

@@ -0,0 +1,2187 @@
+"""Typed application boundary shared by Feishu and the Admin control plane."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import Counter
+from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass, replace
+from enum import Enum
+from pathlib import Path
+from typing import Any, NoReturn
+
+from .blocking_io import BoundedBlockingIOExecutor, BlockingIOExecutorSaturated
+from .chat_labels import ChatLabel, ChatLabelProvider, ChatLabelResolver
+from .coordination import ScopeCoordinator
+from .updates import UpdateService
+from ..bindings import (
+    BindingCursor,
+    BindingInventoryRecord,
+    BindingNotFound,
+    BindingPage,
+    BindingQuery,
+    BindingStore,
+    BindingTaskFeedback,
+    BindingTurnSettings,
+    ProjectAggregate,
+    ProjectAggregatePage,
+    ProjectDeleteSnapshot,
+    ProjectDisabled as StoredProjectDisabled,
+    ProjectNotFound as StoredProjectNotFound,
+    ProjectRevisionConflict as StoredProjectRevisionConflict,
+    ScopeRecord,
+    SideTopicCursor,
+    SideTopicConflict,
+    SideTopicInventoryRecord,
+    SideTopicPage,
+    SideTopicQuery,
+    SideTopicRecord,
+    SideTopicState,
+    ThreadBinding,
+)
+from ..codex_runtime import CodexRuntime
+from ..runtime.contracts import (
+    ActiveTurnSnapshot,
+    BindingRuntimeSnapshot,
+    NativeThreadCatalog,
+    NativeThreadCatalogState,
+    NativeThreadMetadata,
+    ReleaseDisposition,
+    SideLifecycleOutcome,
+    SideCloseFailed,
+    SideSessionSnapshot,
+    SideSessionNotFound,
+    StopAcknowledger,
+    StopDisposition,
+    ThreadSubscriptionState,
+    ThreadArchived,
+    ThreadCatalogIdentityMissing,
+    ThreadDeleteTargetChanged,
+    ThreadDeleteUnavailable,
+    ThreadLifecycleError,
+    ThreadLifecycleStateUnknown,
+)
+from ..domain import (
+    FeishuScope,
+    GoalStatus,
+    MessageContextAnchor,
+    MentionContextMode,
+    NativeCapability,
+    SESSION_IDLE_STATE,
+    session_stop_available,
+)
+from ..projects import (
+    Project,
+    ProjectDisabled,
+    ProjectRegistry,
+    StaleProject,
+    UnknownProject,
+)
+from ..sdk_gap_adapter import GoalControlError, GoalSnapshot
+from ..schedules.service import ScheduleService
+from ..defaults.service import SessionDefaultsService
+from ..model_settings import ModelCatalog
+
+
+_BINDING_STATUS_RESOLUTION_CONCURRENCY = 8
+_NATIVE_INDEX_READ_SECONDS = 3.0
+_SESSION_SUMMARY_READ_CONCURRENCY = 4
+_PROJECT_DELETE_SECONDS = 120.0
+_PROJECT_DELETE_STEP_SECONDS = 30.0
+logger = logging.getLogger(__name__)
+
+
+class ManagementError(RuntimeError):
+    """Base class for stable application-boundary precondition failures."""
+
+
+class NoCurrentBinding(ManagementError):
+    pass
+
+
+class CurrentBindingChanged(ManagementError):
+    pass
+
+
+class BindingScopeMismatch(ManagementError):
+    pass
+
+
+class ActivePointerChanged(ManagementError):
+    pass
+
+
+class SideIdentityMismatch(ManagementError):
+    pass
+
+
+class NativeThreadMissing(ManagementError):
+    pass
+
+
+class NativeCatalogInconsistent(ManagementError):
+    pass
+
+
+class RuntimeStateChanged(ManagementError):
+    pass
+
+
+class SidePublicationInProgress(ManagementError):
+    pass
+
+
+class SchedulePublicationInProgress(ManagementError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class NativeThreadView:
+    # None means the management catalog could not classify a materialized Thread.
+    # An absent NativeThreadView, rather than an absent state, represents Lazy.
+    state: NativeThreadCatalogState | None
+    metadata: NativeThreadMetadata | None
+
+
+def classify_native_thread_view(
+    thread_id: str | None,
+    *,
+    active: Mapping[str, NativeThreadMetadata],
+    archived: Mapping[str, NativeThreadMetadata],
+) -> NativeThreadView | None:
+    """Classify raw catalog membership, preferring archived on overlap.
+
+    Inventory readers resolve overlap to Unknown before calling this helper;
+    raw catalog absence alone does not establish inventory Missing.
+    """
+
+    if thread_id is None:
+        return None
+    archived_metadata = archived.get(thread_id)
+    if archived_metadata is not None:
+        return NativeThreadView(
+            NativeThreadCatalogState.ARCHIVED,
+            archived_metadata,
+        )
+    active_metadata = active.get(thread_id)
+    if active_metadata is not None:
+        return NativeThreadView(NativeThreadCatalogState.ACTIVE, active_metadata)
+    return NativeThreadView(NativeThreadCatalogState.MISSING, None)
+
+
+class BindingPrimaryStatusResolution(str, Enum):
+    LOCAL = "local"
+    ARCHIVED = "archived"
+    RESOLVED = "resolved"
+    DEFERRED = "deferred"
+    UNAVAILABLE = "unavailable"
+
+
+@dataclass(frozen=True, slots=True)
+class BindingStatusProjection:
+    snapshot: BindingRuntimeSnapshot
+    primary_status: str | None
+    primary_status_resolution: BindingPrimaryStatusResolution
+    persisted_goal_status: GoalStatus | None
+    subscription_state: ThreadSubscriptionState | None
+    pointer_state: str
+    catalog_state: NativeThreadCatalogState | None
+    can_stop: bool
+    can_release: bool
+
+    @property
+    def binding_id(self) -> str:
+        return self.snapshot.binding_id
+
+
+def _project_binding_status(
+    *,
+    binding: ThreadBinding,
+    snapshot: BindingRuntimeSnapshot,
+    persisted_goal: GoalSnapshot | None = None,
+    persisted_goal_resolved: bool = False,
+    primary_status_unavailable: bool = False,
+    catalog_state: NativeThreadCatalogState | None = None,
+) -> BindingStatusProjection:
+    """Project one ordinary Binding without letting deferred Goal reads mean idle."""
+
+    if snapshot.binding_id != binding.id:
+        raise ValueError("Binding status projection identity mismatch")
+    persisted_status = (
+        persisted_goal.status if persisted_goal is not None else None
+    )
+    if snapshot.lifecycle is not None:
+        primary_status = snapshot.lifecycle.state.value
+        resolution = BindingPrimaryStatusResolution.LOCAL
+    elif snapshot.turn is not None:
+        primary_status = snapshot.turn.state.value
+        resolution = BindingPrimaryStatusResolution.LOCAL
+    elif snapshot.compacting:
+        primary_status = "compacting"
+        resolution = BindingPrimaryStatusResolution.LOCAL
+    elif snapshot.goal is not None:
+        primary_status = snapshot.goal.state.value
+        resolution = BindingPrimaryStatusResolution.LOCAL
+    elif catalog_state is NativeThreadCatalogState.ARCHIVED:
+        primary_status = None
+        resolution = BindingPrimaryStatusResolution.ARCHIVED
+    elif primary_status_unavailable:
+        primary_status = None
+        resolution = BindingPrimaryStatusResolution.UNAVAILABLE
+    elif persisted_goal_resolved:
+        primary_status = (
+            SESSION_IDLE_STATE
+            if persisted_status is None
+            else f"goal-{persisted_status.value}"
+        )
+        resolution = BindingPrimaryStatusResolution.RESOLVED
+    else:
+        primary_status = None
+        resolution = BindingPrimaryStatusResolution.DEFERRED
+    subscription_state = (
+        snapshot.subscription.state
+        if snapshot.subscription is not None
+        else None
+    )
+    can_release = (
+        binding.native_thread_id is not None
+        and resolution is BindingPrimaryStatusResolution.RESOLVED
+        and subscription_state
+        in {
+            ThreadSubscriptionState.SUBSCRIBED,
+            ThreadSubscriptionState.RELEASE_PENDING,
+        }
+        and snapshot.lifecycle is None
+        and snapshot.turn is None
+        and not snapshot.compacting
+        and snapshot.goal is None
+        and persisted_status is not GoalStatus.ACTIVE
+    )
+    return BindingStatusProjection(
+        snapshot=snapshot,
+        primary_status=primary_status,
+        primary_status_resolution=resolution,
+        persisted_goal_status=persisted_status,
+        subscription_state=subscription_state,
+        pointer_state="current" if binding.active else "inactive",
+        catalog_state=catalog_state,
+        can_stop=session_stop_available(primary_status),
+        can_release=can_release,
+    )
+
+
+class SessionInventoryState(str, Enum):
+    ACTIVE = "active"
+    LAZY = "lazy"
+    ARCHIVED = "archived"
+    MISSING = "missing"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class SessionQuery:
+    local: BindingQuery = BindingQuery()
+    inventory_states: tuple[SessionInventoryState, ...] | None = None
+
+
+def _session_inventory_state(
+    binding: ThreadBinding, native: NativeThreadView | None,
+) -> SessionInventoryState:
+    if binding.native_thread_id is None:
+        return SessionInventoryState.LAZY
+    if native is None or native.state is None:
+        return SessionInventoryState.UNKNOWN
+    return SessionInventoryState(native.state.value)
+
+
+@dataclass(frozen=True, slots=True)
+class SessionInventoryItem:
+    record: BindingInventoryRecord
+    native: NativeThreadView | None
+    chat: ChatLabel
+
+    @property
+    def inventory_state(self) -> SessionInventoryState:
+        return _session_inventory_state(self.record.binding, self.native)
+
+
+@dataclass(frozen=True, slots=True)
+class SessionInventoryPage:
+    items: tuple[SessionInventoryItem, ...]
+    next_cursor: BindingCursor | None
+    catalog_available: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class ScopeSessionPage:
+    items: tuple[SessionInventoryItem, ...]
+    total_count: int
+    page: int
+    active_binding_id: str | None
+    catalog_available: bool
+    unconfirmed_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class SideTopicInventoryItem:
+    record: SideTopicInventoryRecord
+    chat: ChatLabel
+    runtime: SideSessionSnapshot | None
+
+
+@dataclass(frozen=True, slots=True)
+class SideTopicInventoryPage:
+    items: tuple[SideTopicInventoryItem, ...]
+    next_cursor: SideTopicCursor | None
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectInventoryItem:
+    aggregate: ProjectAggregate
+    archived_binding_count: int | None
+    deleting: bool = False
+    unconfirmed_binding_count: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectInventoryPage:
+    items: tuple[ProjectInventoryItem, ...]
+    next_cursor: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectDeletionResult:
+    project_alias: str
+    deleted: bool
+    deleted_session_count: int
+    remaining_sessions: tuple[ThreadBinding, ...]
+    remaining_side_count: int
+    failed_binding_id: str | None = None
+    failed_side_id: str | None = None
+    code: str = "deleted"
+    deleted_plan_count: int = 0
+    remaining_scheduled_run_count: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeSnapshots:
+    bindings: tuple[BindingStatusProjection, ...]
+    sides: tuple[SideSessionSnapshot, ...]
+    missing_side_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimePrecondition:
+    activity_revision: int
+    physical_turn_id: str | None
+
+    def __post_init__(self) -> None:
+        if self.activity_revision < 0:
+            raise ValueError("runtime activity revision must be non-negative")
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentBindingTarget:
+    scope_key: str
+    binding_id: str
+
+    def __post_init__(self) -> None:
+        if not self.scope_key or not self.binding_id:
+            raise ValueError("current Binding target identity must not be empty")
+
+
+@dataclass(frozen=True, slots=True)
+class ExactBindingTarget:
+    scope_key: str
+    binding_id: str
+    expected_active_binding_id: str | None
+
+    def __post_init__(self) -> None:
+        if not self.scope_key or not self.binding_id:
+            raise ValueError("exact Binding target identity must not be empty")
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentSideTarget:
+    side_id: str
+    app_id: str
+    chat_id: str
+    topic_id: str | None
+    root_message_id: str | None
+
+    def __post_init__(self) -> None:
+        if not self.side_id or not self.app_id or not self.chat_id:
+            raise ValueError("Side target identity must not be empty")
+
+
+@dataclass(frozen=True, slots=True)
+class CreatedBinding:
+    # Reusing an existing Binding leaves Project resolution to ordinary input.
+    project: Project | None
+    binding: ThreadBinding
+    created: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class RenamedBinding:
+    binding: ThreadBinding
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReleasedBinding:
+    binding: ThreadBinding
+    disposition: ReleaseDisposition
+
+
+@dataclass(frozen=True, slots=True)
+class StoppedBinding:
+    binding: ThreadBinding
+    disposition: StopDisposition
+
+
+@dataclass(frozen=True, slots=True)
+class ClosedSide:
+    record: SideTopicRecord
+    outcome: SideLifecycleOutcome | None
+    missing_runtime_session: bool = False
+
+
+class ManagementRuntimePort:
+    """Concrete capability wrapper exposing only approved management seams.
+
+    Keeping this as a real object, rather than merely a structural Protocol,
+    prevents a future HTTP handler from accidentally receiving the complete
+    Runtime and reaching Prompt, Turn, Goal, Compact, or Side-create
+    capabilities.  Native delete is exposed only as one exact Binding
+    lifecycle operation; adapters still decide which product surfaces may use
+    it.
+    """
+
+    __slots__ = ("__runtime",)
+
+    def __init__(self, runtime: CodexRuntime) -> None:
+        self.__runtime = runtime
+
+    async def read_scheduled_turn(
+        self, binding_id: str, turn_id: str, *, deadline: float | None = None,
+    ) -> str:
+        return await self.__runtime.read_scheduled_turn(binding_id, turn_id, deadline=deadline)
+
+    @property
+    def native_delete_available(self) -> bool:
+        return NativeCapability.DELETE in self.__runtime.available_capabilities
+
+    async def configure_exact(
+        self,
+        *,
+        binding_id: str,
+        expected_revision: int,
+        settings: BindingTurnSettings | None,
+    ) -> ThreadBinding:
+        return await self.__runtime.configure_exact(
+            binding_id=binding_id,
+            expected_revision=expected_revision,
+            settings=settings,
+        )
+
+    async def configure_context_exact(
+        self,
+        *,
+        binding_id: str,
+        expected_settings_revision: int,
+        expected_context_revision: int,
+        expected_feedback_revision: int,
+        settings: BindingTurnSettings | None,
+        task_feedback: BindingTaskFeedback,
+        message_context_mode: MentionContextMode,
+        context_anchor: MessageContextAnchor | None,
+    ) -> ThreadBinding:
+        return await self.__runtime.configure_context_exact(
+            binding_id=binding_id,
+            expected_settings_revision=expected_settings_revision,
+            expected_context_revision=expected_context_revision,
+            expected_feedback_revision=expected_feedback_revision,
+            settings=settings,
+            task_feedback=task_feedback,
+            message_context_mode=message_context_mode,
+            context_anchor=context_anchor,
+        )
+
+    async def activate_exact(
+        self,
+        binding_id: str,
+        *,
+        context_anchor: MessageContextAnchor | None = None,
+    ) -> ThreadBinding:
+        return await self.__runtime.activate_exact(
+            binding_id,
+            context_anchor=context_anchor,
+        )
+
+    async def model_catalog(self) -> ModelCatalog:
+        return await self.__runtime.model_catalog()
+
+    async def resolve_turn_settings(
+        self,
+        *,
+        model_id: str,
+        effort_id: str,
+        service_tier_id: str,
+    ) -> BindingTurnSettings:
+        resolved = await self.__runtime.resolve_model_settings(
+            model_id=model_id,
+            effort_id=effort_id,
+            service_tier_id=service_tier_id,
+        )
+        return BindingTurnSettings(
+            model_id=resolved.model_id,
+            effort_id=resolved.effort_id,
+            service_tier_id=resolved.service_tier_id,
+        )
+
+    async def rename_exact(self, binding_id: str, name: str) -> str:
+        return await self.__runtime.rename_exact(binding_id, name)
+
+    async def archive_exact(self, binding_id: str) -> ThreadBinding:
+        return await self.__runtime.archive_exact(binding_id)
+
+    async def restore_exact(self, binding_id: str) -> ThreadBinding:
+        return await self.__runtime.restore_exact(binding_id)
+
+    async def restore_as_current_exact(
+        self,
+        binding_id: str,
+        *,
+        context_anchor: MessageContextAnchor | None = None,
+    ) -> ThreadBinding:
+        return await self.__runtime.restore_as_current_exact(
+            binding_id,
+            context_anchor=context_anchor,
+        )
+
+    async def delete_lazy_exact(self, binding_id: str) -> ThreadBinding:
+        return await self.__runtime.delete_lazy_exact(binding_id)
+
+    async def delete_exact(
+        self,
+        binding_id: str,
+        *,
+        expected_native_thread_id: str | None,
+    ) -> ThreadBinding:
+        return await self.__runtime.delete_exact(
+            binding_id,
+            expected_native_thread_id=expected_native_thread_id,
+        )
+
+    async def delete_archived_exact(
+        self,
+        binding_id: str,
+        *,
+        expected_native_thread_id: str,
+    ) -> ThreadBinding:
+        return await self.__runtime.delete_archived_exact(
+            binding_id,
+            expected_native_thread_id=expected_native_thread_id,
+        )
+
+    async def stop_exact(
+        self,
+        binding_id: str,
+        *,
+        acknowledge: StopAcknowledger | None = None,
+        expected_activity_revision: int | None = None,
+        expected_turn_id: str | None = None,
+    ) -> StopDisposition:
+        if expected_activity_revision is None:
+            return await self.__runtime.stop_exact(
+                binding_id,
+                acknowledge=acknowledge,
+            )
+        return await self.__runtime.stop_exact(
+            binding_id,
+            acknowledge=acknowledge,
+            expected_activity_revision=expected_activity_revision,
+            expected_turn_id=expected_turn_id,
+        )
+
+    async def recheck_turn_exact(
+        self,
+        binding_id: str,
+        *,
+        expected_activity_revision: int,
+        expected_turn_id: str,
+    ) -> ActiveTurnSnapshot:
+        return await self.__runtime.recheck_turn_exact(
+            binding_id,
+            expected_activity_revision=expected_activity_revision,
+            expected_turn_id=expected_turn_id,
+        )
+
+    async def release_exact(self, binding_id: str) -> ReleaseDisposition:
+        return await self.__runtime.release_exact(binding_id)
+
+    async def close_side_exact(
+        self,
+        side_id: str,
+        *,
+        state: SideTopicState,
+    ) -> SideLifecycleOutcome:
+        return await self.__runtime.close_side_exact(side_id, state=state)
+
+    async def drain_project_side_creation(self, binding_id: str) -> None:
+        await self.__runtime.drain_project_side_creation(binding_id)
+
+    async def binding_pointer_changed(
+        self,
+        previous_binding_id: str | None,
+        current_binding_id: str | None,
+    ) -> None:
+        await self.__runtime.binding_pointer_changed(
+            previous_binding_id,
+            current_binding_id,
+        )
+
+    async def is_thread_archived(self, thread_id: str) -> bool:
+        return await self.__runtime.thread_is_archived(thread_id)
+
+    async def thread_catalog_state_exact(
+        self,
+        thread_id: str,
+    ) -> NativeThreadCatalogState:
+        return await self.__runtime.thread_catalog_state(thread_id)
+
+    def runtime_snapshot_exact(self, binding_id: str) -> BindingRuntimeSnapshot:
+        return self.__runtime.binding_runtime_snapshot(binding_id)
+
+    async def goal_snapshot_exact(
+        self,
+        binding: ThreadBinding,
+    ) -> GoalSnapshot | None:
+        return await self.__runtime.goal_snapshot(binding)
+
+    def side_snapshot_exact(self, side_id: str) -> SideSessionSnapshot | None:
+        try:
+            return self.__runtime.side_snapshot(side_id)
+        except SideSessionNotFound:
+            return None
+
+    def project_side_snapshots(self, alias: str) -> tuple[SideSessionSnapshot, ...]:
+        return self.__runtime.project_side_snapshots(alias)
+
+    async def thread_metadata_exact(
+        self,
+        thread_ids: tuple[str, ...],
+        *,
+        archived: bool,
+        deadline: float,
+        use_state_db_only: bool | None = None,
+    ) -> dict[str, NativeThreadMetadata]:
+        return await self.__runtime.thread_metadata(
+            thread_ids,
+            archived=archived,
+            deadline=deadline,
+            max_pages=1_000,
+            max_items=100_000,
+            use_state_db_only=use_state_db_only,
+        )
+
+    async def thread_summary_exact(
+        self, thread_id: str,
+    ) -> NativeThreadMetadata:
+        return await self.__runtime.thread_summary(thread_id)
+
+    async def thread_catalog_exact(
+        self,
+        *,
+        archived: bool,
+        deadline: float,
+        use_state_db_only: bool | None = None,
+    ) -> NativeThreadCatalog:
+        return await self.__runtime.thread_catalog(
+            archived=archived,
+            deadline=deadline,
+            use_state_db_only=use_state_db_only,
+        )
+
+
+class InstanceManagementService:
+    """Coordinate management mutations over the one Store and Runtime."""
+
+    def __init__(
+        self,
+        *,
+        bindings: BindingStore,
+        projects: ProjectRegistry,
+        runtime: ManagementRuntimePort,
+        scope_coordinator: ScopeCoordinator,
+        blocking_io: BoundedBlockingIOExecutor | None = None,
+        chat_labels: ChatLabelProvider | None = None,
+        updates: UpdateService | None = None,
+        root: Path | None = None,
+    ) -> None:
+        self._bindings = bindings
+        self._projects = projects
+        self._runtime = runtime
+        self._scope_coordinator = scope_coordinator
+        self._updates = updates or UpdateService(root=root)
+        self._chat_labels = (
+            ChatLabelResolver(chat_labels) if chat_labels is not None else None
+        )
+        self._blocking_io = blocking_io or BoundedBlockingIOExecutor(
+            max_workers=1,
+            capacity=2,
+        )
+        self._goal_status_read_limiter = asyncio.Semaphore(
+            _BINDING_STATUS_RESOLUTION_CONCURRENCY
+        )
+        self._summary_read_limiter = asyncio.Semaphore(
+            _SESSION_SUMMARY_READ_CONCURRENCY
+        )
+        self._summary_reads: set[asyncio.Task[NativeThreadMetadata]] = set()
+        self._summary_reads_closed = False
+        self.schedules: ScheduleService | None = None
+        self.defaults: SessionDefaultsService | None = None
+        self._schedule_creation_drain: Callable[[str, float], Awaitable[bool]] | None = None
+
+    def enable_schedules(self, *, app_id: str, chat_info: Any = None) -> ScheduleService:
+        if self.schedules is None:
+            self.schedules = ScheduleService(
+                bindings=self._bindings, runtime=self._runtime,
+                app_id=app_id, chat_info=chat_info,
+            )
+        elif self.schedules.app_id != app_id:
+            raise ValueError("schedule management App identity cannot change")
+        return self.schedules
+
+    def set_schedule_creation_drain(
+        self, callback: Callable[[str, float], Awaitable[bool]],
+    ) -> None:
+        self._schedule_creation_drain = callback
+
+    def enable_defaults(self, *, app_id: str, chat_info: Any = None) -> SessionDefaultsService:
+        if self.defaults is None:
+            self.defaults = SessionDefaultsService(
+                bindings=self._bindings, projects=self._projects,
+                runtime=self._runtime, app_id=app_id, chat_info=chat_info,
+                blocking_io=self._blocking_io,
+            )
+        elif self.defaults.app_id != app_id:
+            raise ValueError("default configuration App identity cannot change")
+        return self.defaults
+
+    @property
+    def scope_coordinator(self) -> ScopeCoordinator:
+        return self._scope_coordinator
+
+    @property
+    def native_delete_available(self) -> bool:
+        return self._runtime.native_delete_available
+
+    async def close(self, *, deadline: float | None = None) -> None:
+        self._summary_reads_closed = True
+        if self.schedules is not None:
+            self.schedules.close_admission()
+        await self._updates.close(deadline=deadline)
+        if self._chat_labels is not None:
+            await self._chat_labels.aclose()
+        await self._blocking_io.aclose(deadline=deadline)
+        if self._summary_reads:
+            remaining = (
+                1.0 if deadline is None
+                else min(1.0, max(0.0, deadline - asyncio.get_running_loop().time()))
+            )
+            # Do not cancel SDK wrappers and lose accounting for their workers.
+            # Any remaining reads finish when the shared Codex transport closes.
+            await asyncio.wait(tuple(self._summary_reads), timeout=remaining)
+
+    def set_service_ready(self, ready: bool) -> None:
+        self._updates.set_service_ready(ready)
+
+    async def update_status(self) -> dict[str, Any]:
+        return await self._updates.status()
+
+    async def restart_service(self, *, installation_id: str) -> dict[str, Any]:
+        return await self._updates.restart(installation_id=installation_id)
+
+    async def register_project(
+        self,
+        *,
+        alias: str,
+        path: str | None,
+        create_directory: bool,
+        deadline: float | None = None,
+    ) -> Project:
+        return await self._blocking_io.submit(
+            self._projects.register,
+            alias=alias,
+            path=path,
+            create_directory=create_directory,
+            deadline=deadline,
+        )
+
+    async def resolve_new_project(
+        self, alias: str, *, deadline: float,
+    ) -> Project:
+        """Validate a creation cwd without blocking the shared event loop."""
+
+        async with asyncio.timeout_at(deadline):
+            while True:
+                try:
+                    return await self._blocking_io.submit(
+                        self._projects.resolve_for_new,
+                        alias,
+                        deadline=deadline,
+                    )
+                except BlockingIOExecutorSaturated:
+                    # Several plans commonly share a due minute. Wait within
+                    # this short creation budget for existing filesystem I/O;
+                    # no native execution is queued or concurrency-limited.
+                    await self._blocking_io.drain(deadline=deadline)
+
+    async def set_project_enabled(
+        self,
+        *,
+        alias: str,
+        enabled: bool,
+        expected_revision: int,
+    ) -> Project:
+        return self._projects.set_enabled(
+            alias=alias,
+            enabled=enabled,
+            expected_revision=expected_revision,
+        )
+
+    async def query_project_options(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int = 25,
+        deadline: float,
+    ) -> ProjectAggregatePage:
+        """Read registered Projects without native catalog hydration."""
+
+        return await self._bindings.query_project_aggregates(
+            cursor=cursor,
+            limit=limit,
+            deadline_seconds=self._query_seconds(deadline),
+        )
+
+    async def query_projects(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int = 25,
+        deadline: float,
+    ) -> ProjectInventoryPage:
+        page = await self._bindings.query_project_aggregates(
+            cursor=cursor,
+            limit=limit,
+            deadline_seconds=self._query_seconds(deadline),
+        )
+        native = (
+            await self._indexed_native_views(deadline=deadline)
+            if any(item.materialized_binding_count for item in page.items)
+            else {}
+        )
+        confirmed = {
+            thread_id: view for thread_id, view in (native or {}).items()
+            if view.state is not None
+        }
+        try:
+            project_by_thread = await self._bindings.project_aliases_for_native_threads(
+                tuple(confirmed), expected_projects=page.items,
+                deadline_seconds=self._query_seconds(deadline),
+            )
+        except Exception as error:
+            logger.warning("project catalog counts unavailable error_type=%s", type(error).__name__)
+            native = None
+            project_by_thread = {}
+        known_counts = Counter(project_by_thread.values())
+        archived_counts = Counter(
+            alias for thread_id, alias in project_by_thread.items()
+            if confirmed[thread_id].state is NativeThreadCatalogState.ARCHIVED
+        )
+        return ProjectInventoryPage(
+            items=tuple(
+                ProjectInventoryItem(
+                    aggregate=item,
+                    archived_binding_count=(
+                        archived_counts[item.project.alias]
+                        if native is not None or item.materialized_binding_count == 0
+                        else None
+                    ),
+                    deleting=self._bindings.project_delete_in_progress(item.project.alias),
+                    unconfirmed_binding_count=max(
+                        0, item.materialized_binding_count - known_counts[item.project.alias],
+                    ),
+                )
+                for item in page.items
+            ),
+            next_cursor=page.next_cursor,
+        )
+
+    async def preview_project_delete(
+        self,
+        *,
+        alias: str,
+        expected_revision: int,
+        deadline: float,
+    ) -> ProjectDeleteSnapshot:
+        snapshot = await self._blocking_io.submit(
+            self._projects.preview_delete, alias,
+            extra_side_ids=self._project_side_ids(alias), deadline=deadline,
+        )
+        if snapshot.project.revision != expected_revision:
+            raise StaleProject("Project 已改变，请刷新后重新确认。")
+        self._require_project_delete_capability(snapshot)
+        return snapshot
+
+    def _require_project_delete_capability(self, snapshot: ProjectDeleteSnapshot) -> None:
+        if not self.native_delete_available and any(
+            item.binding.native_thread_id is not None for item in snapshot.bindings
+        ):
+            raise ThreadDeleteUnavailable("原生会话删除能力不可用，Project 未删除。")
+
+    def _project_side_ids(self, alias: str) -> tuple[str, ...]:
+        return tuple(side.side_id for side in self._runtime.project_side_snapshots(alias))
+
+    async def delete_project(
+        self,
+        *,
+        alias: str,
+        expected_revision: int,
+        expected_inventory_fingerprint: str,
+        deadline: float | None = None,
+    ) -> ProjectDeletionResult:
+        """Delete one confirmed inventory through the existing exact operations.
+
+        Only short Registry transactions reserve admission.  Native operations
+        hold their own Binding/Side lifecycle slots; neither a Project execution
+        lock nor a durable batch job is introduced.  Partial work is never rolled
+        back or automatically retried.
+        """
+        loop = asyncio.get_running_loop()
+        deadline = min(
+            deadline if deadline is not None else float("inf"),
+            loop.time() + _PROJECT_DELETE_SECONDS,
+        )
+        if deadline <= loop.time():
+            raise TimeoutError("Project deletion deadline elapsed")
+        extra_side_ids = self._project_side_ids(alias)
+        self._require_project_delete_capability(self._projects.preview_delete(
+            alias, extra_side_ids=extra_side_ids,
+        ))
+        snapshot = self._projects.begin_delete(
+            alias=alias,
+            expected_revision=expected_revision,
+            expected_inventory_fingerprint=expected_inventory_fingerprint,
+            extra_side_ids=extra_side_ids,
+        )
+        failed_binding_id: str | None = None
+        failed_side_id: str | None = None
+        code = "deleted"
+        deleted = False
+        try:
+            if self._schedule_creation_drain is not None:
+                drained = await self._schedule_creation_drain(
+                    alias, min(deadline, loop.time() + _PROJECT_DELETE_STEP_SECONDS),
+                )
+                if not drained:
+                    raise SchedulePublicationInProgress(alias)
+            # Frozen plans cannot issue another claim. A publication with no
+            # complete native identity remains in the exact remaining inventory;
+            # do not pretend deleting its definition undid an external call.
+            if any(
+                run.phase in {"claimed", "publishing_topic", "binding_ready", "starting_turn"}
+                or run.error_code == "publishing_unknown"
+                for run in self._bindings.schedules.project_pending_runs(alias)
+            ):
+                raise SchedulePublicationInProgress(alias)
+            bindings_by_id = {item.binding.id: item.binding for item in snapshot.bindings}
+            parent_ids = tuple(dict.fromkeys([
+                *bindings_by_id,
+                *(side.parent_binding_id for side in snapshot.sides),
+            ]))
+            for parent_id in parent_ids:
+                binding = bindings_by_id.get(parent_id)
+                failed_binding_id = binding.id if binding is not None else None
+                failed_side_id = None
+                sides = tuple(
+                    side for side in snapshot.sides if side.parent_binding_id == parent_id
+                )
+                if sides:
+                    if loop.time() >= deadline:
+                        raise TimeoutError("Project deletion deadline elapsed")
+                    async with asyncio.timeout_at(min(deadline, loop.time() + _PROJECT_DELETE_STEP_SECONDS)):
+                        await self._runtime.drain_project_side_creation(parent_id)
+                    for side in sides:
+                        failed_side_id = side.id
+                        if self._bindings.get_side_topic(side.id).state is SideTopicState.CREATING:
+                            # Native setup may be done while Feishu is still
+                            # publishing the root/topic.  Closing now could
+                            # strand a late message without its route tombstone.
+                            raise SidePublicationInProgress(side.id)
+                        if loop.time() >= deadline:
+                            raise TimeoutError("Project deletion deadline elapsed")
+                        async with asyncio.timeout_at(min(deadline, loop.time() + _PROJECT_DELETE_STEP_SECONDS)):
+                            closed = await self.close_side(target=CurrentSideTarget(
+                                side_id=side.id,
+                                app_id=side.app_id,
+                                chat_id=side.chat_id,
+                                topic_id=side.topic_id,
+                                root_message_id=side.root_message_id,
+                            ))
+                            if (
+                                not closed.record.state.terminal
+                                or (closed.outcome is not None and closed.outcome.error is not None)
+                                or self._runtime.side_snapshot_exact(side.id) is not None
+                            ):
+                                raise SideCloseFailed("关联 Side 的关闭尚未确认。")
+                failed_side_id = None
+                if binding is None:
+                    continue
+                if loop.time() >= deadline:
+                    raise TimeoutError("Project deletion deadline elapsed")
+                try:
+                    async with asyncio.timeout_at(min(deadline, loop.time() + _PROJECT_DELETE_STEP_SECONDS)):
+                        await self.delete_exact_binding(
+                            target=ExactBindingTarget(binding.scope_key, binding.id, None),
+                            expected_native_thread_id=binding.native_thread_id,
+                        )
+                except BindingNotFound:
+                    # Another exact deletion may have completed since preview.
+                    # Only absence of this same local identity can be skipped.
+                    try:
+                        self._bindings.get(binding.id)
+                    except BindingNotFound:
+                        pass
+                    else:
+                        raise
+            failed_binding_id = None
+            if self._runtime.project_side_snapshots(alias):
+                raise SideCloseFailed("Project 仍有未完成关闭的 Side。")
+            self._projects.finish_delete(
+                alias=alias,
+                expected_revision=snapshot.project.revision,
+                expected_inventory_fingerprint=snapshot.fingerprint,
+            )
+            deleted = True
+        except Exception as error:
+            logger.warning(
+                "project_delete_incomplete project_alias=%s binding_id=%s side_id=%s error_type=%s",
+                alias, failed_binding_id, failed_side_id, type(error).__name__,
+            )
+            if isinstance(error, ThreadLifecycleStateUnknown):
+                code = "outcome_unknown"
+            elif isinstance(error, TimeoutError):
+                code = "deadline_exceeded"
+            elif isinstance(error, (ThreadDeleteTargetChanged, SideIdentityMismatch)):
+                code = "inventory_changed"
+            elif isinstance(error, SideCloseFailed):
+                code = "side_close_failed"
+            elif isinstance(error, SidePublicationInProgress):
+                code = "side_creation_in_progress"
+            elif isinstance(error, SchedulePublicationInProgress):
+                code = "schedule_creation_in_progress"
+            else:
+                code = "delete_failed"
+        finally:
+            # Cancellation or process shutdown leaves a disabled Project.  A
+            # new explicit confirmation reads fresh identities; no loop resumes.
+            self._projects.release_delete(
+                alias=alias, expected_revision=snapshot.project.revision,
+            )
+        remaining = self._project_delete_remaining(snapshot, alias)
+        remaining_side_count = sum(
+            not self._bindings.get_side_topic(side.id).state.terminal
+            or self._runtime.side_snapshot_exact(side.id) is not None
+            for side in snapshot.sides
+        )
+        return ProjectDeletionResult(
+            alias, deleted, len(snapshot.bindings) - len(remaining), remaining,
+            remaining_side_count, failed_binding_id, failed_side_id, code,
+            len(snapshot.scheduled_plans),
+            len(self._bindings.schedules.project_pending_runs(alias)),
+        )
+
+    def _project_delete_remaining(
+        self, snapshot: ProjectDeleteSnapshot, alias: str,
+    ) -> tuple[ThreadBinding, ...]:
+        remaining = []
+        for item in snapshot.bindings:
+            try:
+                binding = self._bindings.get(item.binding.id)
+            except BindingNotFound:
+                continue
+            if binding.project_alias == alias:
+                remaining.append(binding)
+        return tuple(remaining)
+
+    async def query_sessions(
+        self,
+        *,
+        query: SessionQuery = SessionQuery(),
+        cursor: BindingCursor | None = None,
+        limit: int = 20,
+        deadline: float,
+    ) -> SessionInventoryPage:
+        if (
+            isinstance(limit, bool)
+            or not isinstance(limit, int)
+            or not 1 <= limit <= 100
+        ):
+            raise ValueError("page size must be between 1 and 100")
+        if query.inventory_states is not None and (
+            not isinstance(query.inventory_states, tuple)
+            or not query.inventory_states
+            or any(
+                not isinstance(state, SessionInventoryState)
+                for state in query.inventory_states
+            )
+        ):
+            raise ValueError("Session inventory states filter is invalid")
+        states = (
+            frozenset(query.inventory_states)
+            if query.inventory_states is not None
+            else frozenset(SessionInventoryState)
+        )
+        if states == frozenset(SessionInventoryState):
+            page = await self._bindings.query_bindings(
+                query=query.local,
+                cursor=cursor,
+                limit=limit,
+                deadline_seconds=self._query_seconds(deadline),
+            )
+            thread_ids = tuple(dict.fromkeys(
+                record.binding.native_thread_id for record in page.items
+                if record.binding.native_thread_id is not None
+            ))
+            native = await self._indexed_native_views(
+                thread_ids=thread_ids, deadline=deadline,
+            )
+            return await self._session_page(
+                page.items,
+                native=native,
+                next_cursor=page.next_cursor,
+                deadline=deadline,
+            )
+
+        if states == {SessionInventoryState.LAZY}:
+            page = await self._bindings.query_bindings(
+                query=replace(query.local, materialized=False),
+                cursor=cursor,
+                limit=limit,
+                deadline_seconds=self._query_seconds(deadline),
+            )
+            return await self._session_page(
+                page.items,
+                native={},
+                next_cursor=page.next_cursor,
+                deadline=deadline,
+            )
+
+        local = replace(
+            query.local,
+            materialized=None if SessionInventoryState.LAZY in states else True,
+        )
+        native = await self._indexed_native_views(deadline=deadline)
+        selected: list[BindingInventoryRecord] = []
+        scan_cursor = cursor
+        next_cursor: BindingCursor | None = None
+        exhausted = False
+        while len(selected) < limit and not exhausted:
+            page = await self._bindings.query_bindings(
+                query=local,
+                cursor=scan_cursor,
+                limit=50,
+                deadline_seconds=self._query_seconds(deadline),
+            )
+            if not page.items:
+                break
+            for index, record in enumerate(page.items):
+                binding = record.binding
+                scan_cursor = BindingCursor(binding.created_at, binding.id)
+                view = (native or {}).get(binding.native_thread_id)
+                state = _session_inventory_state(binding, view)
+                if state not in states:
+                    continue
+                selected.append(record)
+                if len(selected) == limit:
+                    has_more_local = (
+                        index + 1 < len(page.items) or page.next_cursor is not None
+                    )
+                    next_cursor = scan_cursor if has_more_local else None
+                    break
+            else:
+                if page.next_cursor is None:
+                    exhausted = True
+                else:
+                    scan_cursor = page.next_cursor
+                continue
+            break
+
+        return await self._session_page(
+            tuple(selected),
+            native=native,
+            next_cursor=next_cursor,
+            deadline=deadline,
+        )
+
+    async def query_scope_sessions(
+        self,
+        *,
+        scope: FeishuScope,
+        archived: bool = False,
+        page: int = 0,
+        limit: int | None = 10,
+        deadline: float,
+    ) -> ScopeSessionPage:
+        """Use the shared inventory for a Scope's stateless numbered cards.
+
+        Preserve activation order, current-first ordering and page clamping.
+        The existing archived card is unpaged (limit=None); confirmed archived
+        rows already have metadata and never need Goal or summary enrichment.
+        """
+        if limit is None:
+            if not archived or page != 0:
+                raise ValueError("only the archived list can be unpaged")
+        elif isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 100:
+            raise ValueError("page size must be between 1 and 100")
+        self._query_seconds(deadline)
+        bindings = self._bindings.list_bindings(scope.key)
+        thread_ids = tuple(dict.fromkeys(
+            binding.native_thread_id for binding in bindings
+            if binding.native_thread_id is not None
+        ))
+        native = await self._indexed_native_views(thread_ids=thread_ids, deadline=deadline)
+        if archived and native is None:
+            raise ThreadLifecycleError("无法读取 Codex 归档会话列表，请稍后重试。")
+        selected = []
+        unconfirmed_count = 0
+        for binding in bindings:
+            state = _session_inventory_state(binding, (native or {}).get(binding.native_thread_id))
+            unconfirmed_count += state is SessionInventoryState.UNKNOWN
+            if (state is SessionInventoryState.ARCHIVED) == archived:
+                selected.append(binding)
+        if not archived:
+            selected.sort(key=lambda binding: not binding.active)
+        total_count = len(selected)
+        active_binding_id = next((binding.id for binding in bindings if binding.active), None)
+        if limit is not None:
+            page = max(0, min(page, max(0, (total_count - 1) // limit)))
+            selected = selected[page * limit:(page + 1) * limit]
+        views = await self._session_native_views(selected, native=native, deadline=deadline)
+        scope_record = self._bindings.get_scope(scope.key) if bindings else None
+        return ScopeSessionPage(
+            items=tuple(
+                SessionInventoryItem(
+                    record=BindingInventoryRecord(binding, scope_record),
+                    native=views.get(binding.native_thread_id),
+                    chat=ChatLabelResolver.fallback(scope.chat_id),
+                )
+                for binding in selected
+            ),
+            total_count=total_count,
+            page=page,
+            active_binding_id=active_binding_id,
+            catalog_available=native is not None,
+            unconfirmed_count=unconfirmed_count,
+        )
+
+    async def query_side_topics(
+        self,
+        *,
+        query: SideTopicQuery = SideTopicQuery(),
+        cursor: SideTopicCursor | None = None,
+        limit: int = 25,
+        deadline: float,
+    ) -> SideTopicInventoryPage:
+        page = await self._bindings.query_side_topics(
+            query=query,
+            cursor=cursor,
+            limit=limit,
+            deadline_seconds=self._query_seconds(deadline),
+        )
+        labels = await self.resolve_chat_labels(
+            (item.side_topic.chat_id for item in page.items),
+            deadline=deadline,
+        )
+        return SideTopicInventoryPage(
+            items=tuple(
+                SideTopicInventoryItem(
+                    record=item,
+                    chat=labels[item.side_topic.chat_id],
+                    runtime=self._runtime.side_snapshot_exact(item.side_topic.id),
+                )
+                for item in page.items
+            ),
+            next_cursor=page.next_cursor,
+        )
+
+    async def binding_status_exact(
+        self,
+        binding_id: str,
+        *,
+        snapshot: BindingRuntimeSnapshot | None = None,
+        catalog_state: NativeThreadCatalogState | None = None,
+        deadline: float | None = None,
+    ) -> BindingStatusProjection:
+        binding = self._bindings.get(binding_id)
+        before = snapshot or self._runtime.runtime_snapshot_exact(binding.id)
+        local = _project_binding_status(
+            binding=binding,
+            snapshot=before,
+            catalog_state=catalog_state,
+        )
+        if local.primary_status_resolution in {
+            BindingPrimaryStatusResolution.LOCAL,
+            BindingPrimaryStatusResolution.ARCHIVED,
+        }:
+            return local
+        if (
+            binding.native_thread_id is None
+            or catalog_state is NativeThreadCatalogState.MISSING
+        ):
+            return _project_binding_status(
+                binding=binding,
+                snapshot=before,
+                persisted_goal_resolved=True,
+                catalog_state=catalog_state,
+            )
+        try:
+            async with self._goal_status_read_limiter:
+                if deadline is not None and asyncio.get_running_loop().time() >= deadline:
+                    raise TimeoutError("management query deadline elapsed")
+                persisted_goal = await self._runtime.goal_snapshot_exact(binding)
+        except asyncio.CancelledError:
+            raise
+        except (GoalControlError, ThreadLifecycleError):
+            after = self._runtime.runtime_snapshot_exact(binding.id)
+            local_after = _project_binding_status(
+                binding=binding,
+                snapshot=after,
+                catalog_state=catalog_state,
+            )
+            if (
+                local_after.primary_status_resolution
+                is BindingPrimaryStatusResolution.LOCAL
+            ):
+                return local_after
+            raise
+        after = self._runtime.runtime_snapshot_exact(binding.id)
+        return _project_binding_status(
+            binding=binding,
+            snapshot=after,
+            persisted_goal=persisted_goal,
+            persisted_goal_resolved=True,
+            catalog_state=catalog_state,
+        )
+
+    async def binding_statuses_exact(
+        self,
+        *,
+        binding_ids: Sequence[str],
+        catalog_states: Mapping[
+            str, NativeThreadCatalogState | None
+        ] | None = None,
+        deadline: float | None = None,
+    ) -> tuple[BindingStatusProjection, ...]:
+        binding_ids = self._validated_snapshot_ids(binding_ids, "Binding")
+        if len(binding_ids) > 50:
+            raise ValueError("Binding status request accepts at most 50 IDs")
+        resolved_catalog_states = catalog_states or {}
+        if not resolved_catalog_states.keys() <= set(binding_ids):
+            raise ValueError("catalog states must target requested Bindings")
+        async def resolve(binding_id: str) -> BindingStatusProjection:
+            catalog_state = resolved_catalog_states.get(binding_id)
+            try:
+                if deadline is None:
+                    return await self.binding_status_exact(
+                        binding_id,
+                        catalog_state=catalog_state,
+                    )
+                async with asyncio.timeout_at(deadline):
+                    return await self.binding_status_exact(
+                        binding_id,
+                        catalog_state=catalog_state,
+                        deadline=deadline,
+                    )
+            except asyncio.CancelledError:
+                raise
+            except (GoalControlError, ThreadLifecycleError, TimeoutError):
+                binding = self._bindings.get(binding_id)
+                snapshot = self._runtime.runtime_snapshot_exact(binding_id)
+                return _project_binding_status(
+                    binding=binding,
+                    snapshot=snapshot,
+                    primary_status_unavailable=True,
+                    catalog_state=catalog_state,
+                )
+
+        return tuple(await asyncio.gather(*(resolve(item) for item in binding_ids)))
+
+    def runtime_snapshots(
+        self,
+        *,
+        binding_ids: Sequence[str] = (),
+        side_ids: Sequence[str] = (),
+    ) -> RuntimeSnapshots:
+        binding_ids = self._validated_snapshot_ids(binding_ids, "Binding")
+        side_ids = self._validated_snapshot_ids(side_ids, "Side")
+        if len(binding_ids) + len(side_ids) > 50:
+            raise ValueError("runtime snapshot request accepts at most 50 IDs")
+        binding_snapshots = []
+        for binding_id in binding_ids:
+            binding = self._bindings.get(binding_id)
+            binding_snapshots.append(
+                _project_binding_status(
+                    binding=binding,
+                    snapshot=self._runtime.runtime_snapshot_exact(binding.id),
+                )
+            )
+        sides: list[SideSessionSnapshot] = []
+        missing: list[str] = []
+        for side_id in side_ids:
+            snapshot = self._runtime.side_snapshot_exact(side_id)
+            if snapshot is None:
+                missing.append(side_id)
+            else:
+                sides.append(snapshot)
+        return RuntimeSnapshots(
+            bindings=tuple(binding_snapshots),
+            sides=tuple(sides),
+            missing_side_ids=tuple(missing),
+        )
+
+    async def create_current_binding(
+        self,
+        *,
+        scope: FeishuScope,
+        creator_id: str,
+        project_alias: str,
+        expected_project_revision: int | None = None,
+        turn_settings: BindingTurnSettings | None = None,
+        task_feedback: BindingTaskFeedback = BindingTaskFeedback(),
+        message_context_mode: MentionContextMode = MentionContextMode.CURRENT_ONLY,
+        context_anchor: MessageContextAnchor | None = None,
+        deadline: float | None = None,
+        only_if_empty: bool = False,
+    ) -> CreatedBinding:
+        project = await self._blocking_io.submit(
+            self._projects.resolve_for_new,
+            project_alias,
+            expected_revision=expected_project_revision,
+            deadline=deadline,
+        )
+        async with self._scope_coordinator.hold(scope.key):
+            previous_id = self._active_id(scope.key)
+            if only_if_empty and previous_id is not None:
+                return CreatedBinding(
+                    project=None, binding=self._bindings.get(previous_id), created=False,
+                )
+            try:
+                binding = self._bindings.create_channel_binding(
+                    scope=scope,
+                    project_alias=project.alias,
+                    creator_id=creator_id,
+                    expected_project_revision=(
+                        project.revision if only_if_empty else expected_project_revision
+                    ),
+                    turn_settings=turn_settings,
+                    task_feedback=task_feedback,
+                    message_context_mode=message_context_mode,
+                    context_anchor=context_anchor,
+                )
+            except (
+                StoredProjectNotFound,
+                StoredProjectDisabled,
+                StoredProjectRevisionConflict,
+            ) as error:
+                self._raise_project_create_error(project_alias, error)
+            await self._runtime.binding_pointer_changed(previous_id, binding.id)
+        return CreatedBinding(project=project, binding=binding)
+
+    async def resolve_turn_settings(
+        self,
+        *,
+        model_id: str,
+        effort_id: str,
+        service_tier_id: str,
+    ) -> BindingTurnSettings:
+        return await self._runtime.resolve_turn_settings(
+            model_id=model_id,
+            effort_id=effort_id,
+            service_tier_id=service_tier_id,
+        )
+
+    async def create_exact_lazy_binding(
+        self,
+        *,
+        scope_key: str,
+        project_alias: str,
+        expected_project_revision: int,
+        expected_active_binding_id: str | None,
+        activate: bool,
+        turn_settings: BindingTurnSettings | None = None,
+        deadline: float | None = None,
+    ) -> CreatedBinding:
+        project = await self._blocking_io.submit(
+            self._projects.resolve_for_new,
+            project_alias,
+            expected_revision=expected_project_revision,
+            deadline=deadline,
+        )
+        async with self._scope_coordinator.hold(scope_key):
+            scope = self._bindings.get_scope(scope_key).scope
+            previous_id = self._active_id(scope_key)
+            if previous_id != expected_active_binding_id:
+                raise ActivePointerChanged(
+                    "Scope active Binding changed before Lazy creation"
+                )
+            try:
+                binding = self._bindings.create_admin_binding(
+                    scope=scope,
+                    project_alias=project.alias,
+                    expected_project_revision=expected_project_revision,
+                    activate=activate,
+                    turn_settings=turn_settings,
+                )
+            except (
+                StoredProjectNotFound,
+                StoredProjectDisabled,
+                StoredProjectRevisionConflict,
+            ) as error:
+                self._raise_project_create_error(project_alias, error)
+            if activate:
+                await self._runtime.binding_pointer_changed(previous_id, binding.id)
+        return CreatedBinding(project=project, binding=binding)
+
+    async def resume_current_binding(
+        self,
+        *,
+        scope_key: str,
+        reference: str,
+        context_anchor: MessageContextAnchor | None = None,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(scope_key):
+            previous_id = self._active_id(scope_key)
+            binding = self._bindings.resolve_reference(
+                scope_key=scope_key,
+                reference=reference,
+            )
+            try:
+                activated = await self._runtime.activate_exact(
+                    binding.id,
+                    context_anchor=context_anchor,
+                )
+            except ThreadCatalogIdentityMissing as error:
+                raise NativeThreadMissing(
+                    "原生会话不在 active 或 archived catalog；本次未设为当前。"
+                ) from error
+            await self._runtime.binding_pointer_changed(previous_id, activated.id)
+            return activated
+
+    async def restore_current_binding(
+        self,
+        *,
+        scope_key: str,
+        reference: str,
+        context_anchor: MessageContextAnchor | None = None,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(scope_key):
+            previous_id = self._active_id(scope_key)
+            binding = self._bindings.resolve_reference(
+                scope_key=scope_key,
+                reference=reference,
+            )
+            restored = await self._runtime.restore_as_current_exact(
+                binding.id,
+                context_anchor=context_anchor,
+            )
+            await self._runtime.binding_pointer_changed(previous_id, restored.id)
+            return restored
+
+    async def configure_current_binding(
+        self,
+        *,
+        target: CurrentBindingTarget,
+        expected_settings_revision: int,
+        expected_context_revision: int,
+        expected_feedback_revision: int,
+        settings: BindingTurnSettings | None,
+        task_feedback: BindingTaskFeedback,
+        message_context_mode: MentionContextMode,
+        context_anchor: MessageContextAnchor | None,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding = self._require_current(target)
+            return await self._runtime.configure_context_exact(
+                binding_id=binding.id,
+                expected_settings_revision=expected_settings_revision,
+                expected_context_revision=expected_context_revision,
+                expected_feedback_revision=expected_feedback_revision,
+                settings=settings,
+                task_feedback=task_feedback,
+                message_context_mode=message_context_mode,
+                context_anchor=context_anchor,
+            )
+
+    async def rename_current_binding(
+        self,
+        *,
+        target: CurrentBindingTarget,
+        name: str,
+    ) -> RenamedBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding = self._require_current(target)
+        # Capture the exact target under Scope coordination, but never hold
+        # that lock while waiting for a previous name writer to finish.
+        normalized = await self._runtime.rename_exact(binding.id, name)
+        return RenamedBinding(binding=binding, name=normalized)
+
+    async def archive_current_binding(
+        self,
+        *,
+        target: CurrentBindingTarget,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding = self._require_current(target)
+            previous_id = binding.id
+        archived = await self._runtime.archive_exact(binding.id)
+        async with self._scope_coordinator.hold(target.scope_key):
+            current_id = self._active_id(target.scope_key)
+            if previous_id == binding.id and current_id is None:
+                await self._runtime.binding_pointer_changed(binding.id, None)
+        return archived
+
+    async def delete_current_lazy_binding(
+        self,
+        *,
+        target: CurrentBindingTarget,
+    ) -> ThreadBinding:
+        return await self.delete_current_binding(
+            target=target,
+            expected_native_thread_id=None,
+        )
+
+    async def delete_current_binding(
+        self,
+        *,
+        target: CurrentBindingTarget,
+        expected_native_thread_id: str | None,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding = self._require_current(target)
+            if binding.native_thread_id != expected_native_thread_id:
+                raise CurrentBindingChanged(
+                    "the current Binding native Thread changed"
+                )
+        try:
+            deleted = await self._runtime.delete_exact(
+                binding.id,
+                expected_native_thread_id=expected_native_thread_id,
+            )
+        except ThreadDeleteTargetChanged as error:
+            raise CurrentBindingChanged(
+                "the current Binding native Thread changed"
+            ) from error
+        async with self._scope_coordinator.hold(target.scope_key):
+            current_id = self._active_id(target.scope_key)
+            await self._runtime.binding_pointer_changed(binding.id, current_id)
+        return deleted
+
+    async def release_current_binding(
+        self,
+        *,
+        target: CurrentBindingTarget,
+    ) -> ReleasedBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding = self._require_current(target)
+            disposition = await self._runtime.release_exact(binding.id)
+            return ReleasedBinding(binding=binding, disposition=disposition)
+
+    async def stop_current_binding(
+        self,
+        *,
+        target: CurrentBindingTarget,
+        acknowledge: StopAcknowledger | None = None,
+        runtime_precondition: RuntimePrecondition | None = None,
+    ) -> StoppedBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding = self._require_current(target)
+            stop_kwargs: dict[str, object] = {"acknowledge": acknowledge}
+            if runtime_precondition is not None:
+                stop_kwargs.update(
+                    expected_activity_revision=(
+                        runtime_precondition.activity_revision
+                    ),
+                    expected_turn_id=runtime_precondition.physical_turn_id,
+                )
+            disposition = await self._runtime.stop_exact(
+                binding.id,
+                **stop_kwargs,
+            )
+            return StoppedBinding(binding=binding, disposition=disposition)
+
+    async def activate_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, previous_id = self._require_exact(target)
+            try:
+                activated = await self._runtime.activate_exact(binding.id)
+            except ThreadCatalogIdentityMissing as error:
+                raise NativeThreadMissing(
+                    "原生会话不在 active 或 archived catalog；本次未设为当前。"
+                ) from error
+            await self._runtime.binding_pointer_changed(previous_id, activated.id)
+            return activated
+
+    async def configure_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+        expected_settings_revision: int,
+        settings: BindingTurnSettings | None,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, _ = self._require_exact(target)
+            return await self._runtime.configure_exact(
+                binding_id=binding.id,
+                expected_revision=expected_settings_revision,
+                settings=settings,
+            )
+
+    async def rename_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+        name: str,
+    ) -> RenamedBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, _ = self._require_exact(target)
+        normalized = await self._runtime.rename_exact(binding.id, name)
+        return RenamedBinding(binding=binding, name=normalized)
+
+    async def archive_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, previous_id = self._require_exact_lifecycle_target(target)
+        archived = await self._runtime.archive_exact(binding.id)
+        async with self._scope_coordinator.hold(target.scope_key):
+            current_id = self._active_id(target.scope_key)
+            if previous_id == binding.id and current_id is None:
+                await self._runtime.binding_pointer_changed(binding.id, None)
+        return archived
+
+    async def restore_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, _ = self._require_exact(target)
+            return await self._runtime.restore_exact(binding.id)
+
+    async def restore_exact_binding_as_current(
+        self,
+        *,
+        target: ExactBindingTarget,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, previous_id = self._require_exact(target)
+            restored = await self._runtime.restore_as_current_exact(binding.id)
+            await self._runtime.binding_pointer_changed(previous_id, restored.id)
+            return restored
+
+    async def delete_exact_lazy_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, previous_id = self._require_exact(target)
+            deleted = await self._runtime.delete_lazy_exact(binding.id)
+            current_id = self._active_id(target.scope_key)
+            await self._runtime.binding_pointer_changed(previous_id, current_id)
+            return deleted
+
+    async def delete_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+        expected_native_thread_id: str | None,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, previous_id = self._require_exact_lifecycle_target(target)
+            if binding.native_thread_id != expected_native_thread_id:
+                raise ThreadDeleteTargetChanged(
+                    "会话的原生 Thread 已变化，本删除确认未执行。"
+                )
+        deleted = await self._runtime.delete_exact(
+            binding.id,
+            expected_native_thread_id=expected_native_thread_id,
+        )
+        async with self._scope_coordinator.hold(target.scope_key):
+            current_id = self._active_id(target.scope_key)
+            if previous_id == binding.id and current_id is None:
+                await self._runtime.binding_pointer_changed(binding.id, None)
+        return deleted
+
+    async def delete_archived_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+        expected_native_thread_id: str,
+    ) -> ThreadBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, previous_id = self._require_exact_lifecycle_target(target)
+            if binding.native_thread_id != expected_native_thread_id:
+                raise ThreadDeleteTargetChanged(
+                    "归档会话的原生 Thread 已变化，本删除确认未执行。"
+                )
+        deleted = await self._runtime.delete_archived_exact(
+            binding.id,
+            expected_native_thread_id=expected_native_thread_id,
+        )
+        async with self._scope_coordinator.hold(target.scope_key):
+            current_id = self._active_id(target.scope_key)
+            if previous_id == binding.id and current_id is None:
+                await self._runtime.binding_pointer_changed(binding.id, None)
+        return deleted
+
+    async def release_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+        runtime_precondition: RuntimePrecondition | None = None,
+    ) -> ReleasedBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, _ = self._require_exact(target)
+            self._require_runtime_precondition(binding.id, runtime_precondition)
+            disposition = await self._runtime.release_exact(binding.id)
+            return ReleasedBinding(binding, disposition)
+
+    async def stop_exact_binding(
+        self,
+        *,
+        target: ExactBindingTarget,
+        acknowledge: StopAcknowledger | None = None,
+        runtime_precondition: RuntimePrecondition | None = None,
+    ) -> StoppedBinding:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, _ = self._require_exact(target)
+            stop_kwargs: dict[str, object] = {"acknowledge": acknowledge}
+            if runtime_precondition is not None:
+                stop_kwargs.update(
+                    expected_activity_revision=(
+                        runtime_precondition.activity_revision
+                    ),
+                    expected_turn_id=runtime_precondition.physical_turn_id,
+                )
+            disposition = await self._runtime.stop_exact(
+                binding.id,
+                **stop_kwargs,
+            )
+            return StoppedBinding(binding, disposition)
+
+    async def recheck_exact_turn(
+        self,
+        *,
+        target: ExactBindingTarget,
+        runtime_precondition: RuntimePrecondition,
+    ) -> ActiveTurnSnapshot:
+        async with self._scope_coordinator.hold(target.scope_key):
+            binding, _ = self._require_exact(target)
+            turn_id = runtime_precondition.physical_turn_id
+            if turn_id is None:
+                raise RuntimeStateChanged("recheck requires an exact physical Turn")
+            return await self._runtime.recheck_turn_exact(
+                binding.id,
+                expected_activity_revision=runtime_precondition.activity_revision,
+                expected_turn_id=turn_id,
+            )
+
+    async def close_side(
+        self,
+        *,
+        target: CurrentSideTarget,
+    ) -> ClosedSide:
+        record = self._bindings.get_side_topic(target.side_id)
+        self._require_side_identity(record, target)
+        if record.state.terminal and self._runtime.side_snapshot_exact(record.id) is None:
+            return ClosedSide(record=record, outcome=None)
+        if record.state.terminal:
+            state = record.state
+        elif record.state is SideTopicState.CREATING:
+            state = SideTopicState.FAILED
+        else:
+            state = SideTopicState.CLOSED
+        try:
+            outcome = await self._runtime.close_side_exact(record.id, state=state)
+        except SideSessionNotFound:
+            current = self._bindings.get_side_topic(record.id)
+            self._require_side_identity(current, target)
+            if current.state is SideTopicState.OPEN:
+                terminal = SideTopicState.EXPIRED
+            elif current.state is SideTopicState.CREATING:
+                terminal = SideTopicState.FAILED
+            else:
+                return ClosedSide(
+                    record=current,
+                    outcome=None,
+                    missing_runtime_session=True,
+                )
+            try:
+                current = self._bindings.transition_side_topic(current.id, terminal)
+            except SideTopicConflict:
+                current = self._bindings.get_side_topic(current.id)
+            return ClosedSide(
+                record=current,
+                outcome=None,
+                missing_runtime_session=True,
+            )
+        return ClosedSide(
+            record=self._bindings.get_side_topic(record.id),
+            outcome=outcome,
+        )
+
+    @staticmethod
+    def _enrichment_deadline(deadline: float, seconds: float) -> float:
+        # Keep time for local rows, labels and Runtime projections if native I/O stalls.
+        now = asyncio.get_running_loop().time()
+        return now + min(seconds, max(0.0, (deadline - now) / 2))
+
+    async def _indexed_native_views(
+        self,
+        *,
+        deadline: float,
+        thread_ids: tuple[str, ...] | None = None,
+    ) -> dict[str, NativeThreadView] | None:
+        if thread_ids == ():
+            return {}
+        native_deadline = self._enrichment_deadline(deadline, _NATIVE_INDEX_READ_SECONDS)
+        try:
+            catalogs = []
+            async with asyncio.timeout_at(native_deadline):
+                for archived in (False, True):
+                    if thread_ids is None:
+                        catalog = await self._runtime.thread_catalog_exact(
+                            archived=archived, deadline=native_deadline,
+                            use_state_db_only=True,
+                        )
+                        catalogs.append(catalog.by_id())
+                    else:
+                        catalogs.append(await self._runtime.thread_metadata_exact(
+                            thread_ids, archived=archived, deadline=native_deadline,
+                            use_state_db_only=True,
+                        ))
+            active, archived = catalogs
+            if len(active.keys() | archived.keys()) > 100_000:
+                raise ValueError("management index exceeds the catalog limit")
+        except Exception as error:
+            # Native catalog enrichment cannot hide Channel-owned rows. Never
+            # fall back to rollout scans or infer Missing from an unavailable list.
+            logger.warning("management index unavailable error_type=%s", type(error).__name__)
+            return None
+        return {
+            thread_id: (
+                NativeThreadView(None, None)
+                if thread_id in active and thread_id in archived
+                else classify_native_thread_view(thread_id, active=active, archived=archived)
+            )
+            for thread_id in active.keys() | archived.keys()
+        }
+
+    async def _session_page(
+        self,
+        records: Sequence[BindingInventoryRecord],
+        *,
+        native: dict[str, NativeThreadView] | None,
+        next_cursor: BindingCursor | None,
+        deadline: float,
+    ) -> SessionInventoryPage:
+        views = await self._session_native_views(
+            tuple(record.binding for record in records), native=native, deadline=deadline,
+        )
+        labels = await self.resolve_chat_labels(
+            (record.scope.chat_id for record in records), deadline=deadline,
+        )
+        return SessionInventoryPage(
+            items=tuple(
+                SessionInventoryItem(
+                    record=record,
+                    native=views.get(record.binding.native_thread_id),
+                    chat=labels[record.scope.chat_id],
+                )
+                for record in records
+            ),
+            next_cursor=next_cursor,
+            catalog_available=native is not None,
+        )
+
+    async def _session_native_views(
+        self,
+        bindings: Sequence[ThreadBinding],
+        *,
+        native: dict[str, NativeThreadView] | None,
+        deadline: float,
+    ) -> dict[str, NativeThreadView]:
+        views = {
+            binding.native_thread_id: (native or {}).get(
+                binding.native_thread_id, NativeThreadView(None, None),
+            )
+            for binding in bindings if binding.native_thread_id is not None
+        }
+        # Only visible, unclassified rows need a summary. Reading one exact ID
+        # neither proves archive membership nor turns a read failure into Missing.
+        # Use the existing request deadline for the whole page, including queuing.
+
+        async def hydrate(thread_id: str) -> None:
+            try:
+                async with asyncio.timeout_at(deadline):
+                    await self._summary_read_limiter.acquire()
+                    if self._summary_reads_closed or asyncio.get_running_loop().time() >= deadline:
+                        self._summary_read_limiter.release()
+                        return
+                    task = asyncio.create_task(self._runtime.thread_summary_exact(thread_id))
+                    self._summary_reads.add(task)
+                    task.add_done_callback(self._summary_read_finished)
+                    metadata = await asyncio.shield(task)
+                views[thread_id] = NativeThreadView(None, metadata)
+            except Exception:
+                pass  # The exact row remains visible with unknown state and its ID.
+
+        unresolved = tuple(
+            thread_id for thread_id, view in views.items()
+            if view.state is None and view.metadata is None
+        )
+        await asyncio.gather(*(hydrate(thread_id) for thread_id in unresolved))
+        return views
+
+    def _summary_read_finished(self, task: asyncio.Task[NativeThreadMetadata]) -> None:
+        self._summary_reads.discard(task)
+        self._summary_read_limiter.release()
+        if not task.cancelled():
+            task.exception()  # Consume failures even after the page wait expired.
+
+    async def resolve_chat_labels(
+        self,
+        chat_ids: Iterable[str],
+        *,
+        deadline: float,
+    ) -> dict[str, ChatLabel]:
+        """Enrich a bounded management result page using the shared label cache."""
+        unique = tuple(dict.fromkeys(chat_ids))
+        resolver = self._chat_labels
+        if resolver is None:
+            return {
+                chat_id: ChatLabelResolver.fallback(chat_id)
+                for chat_id in unique
+            }
+        return await resolver.resolve_many(unique, deadline=deadline)
+
+    @staticmethod
+    def _query_seconds(deadline: float) -> float:
+        remaining = deadline - asyncio.get_running_loop().time()
+        if remaining <= 0:
+            raise TimeoutError("management query deadline elapsed")
+        return min(0.5, remaining)
+
+    @staticmethod
+    def _validated_snapshot_ids(
+        values: Sequence[str],
+        label: str,
+    ) -> tuple[str, ...]:
+        result = tuple(values)
+        if len(set(result)) != len(result):
+            raise ValueError(f"duplicate {label} snapshot ID")
+        if any(
+            not isinstance(value, str) or not value or value.strip() != value
+            for value in result
+        ):
+            raise ValueError(f"{label} snapshot IDs must be non-empty exact strings")
+        return result
+
+    @staticmethod
+    def _raise_project_create_error(alias: str, error: Exception) -> NoReturn:
+        if isinstance(error, StoredProjectNotFound):
+            raise UnknownProject(alias) from error
+        if isinstance(error, StoredProjectDisabled):
+            raise ProjectDisabled(f"Project {alias} 已停用，不能创建新会话。") from error
+        if isinstance(error, StoredProjectRevisionConflict):
+            raise StaleProject(
+                f"Project {alias} 已被其他操作修改，请刷新后重试。"
+            ) from error
+        raise AssertionError("unexpected Project create error") from error
+
+    def _require_current(self, target: CurrentBindingTarget) -> ThreadBinding:
+        binding = self._bindings.active_binding(target.scope_key)
+        if binding is None:
+            raise NoCurrentBinding(target.scope_key)
+        if binding.id != target.binding_id:
+            raise CurrentBindingChanged(target.binding_id)
+        return binding
+
+    def _require_runtime_precondition(
+        self,
+        binding_id: str,
+        expected: RuntimePrecondition | None,
+    ) -> None:
+        if expected is None:
+            return
+        snapshot = self._runtime.runtime_snapshot_exact(binding_id)
+        physical_turn_id = snapshot.turn.turn_id if snapshot.turn is not None else None
+        if (
+            snapshot.activity_revision != expected.activity_revision
+            or physical_turn_id != expected.physical_turn_id
+        ):
+            raise RuntimeStateChanged(binding_id)
+
+    def _require_exact(
+        self,
+        target: ExactBindingTarget,
+    ) -> tuple[ThreadBinding, str | None]:
+        current_id = self._active_id(target.scope_key)
+        if current_id != target.expected_active_binding_id:
+            raise ActivePointerChanged(target.scope_key)
+        binding = self._bindings.get(target.binding_id)
+        if binding.scope_key != target.scope_key:
+            raise BindingScopeMismatch(target.binding_id)
+        return binding, current_id
+
+    def _require_exact_lifecycle_target(
+        self,
+        target: ExactBindingTarget,
+    ) -> tuple[ThreadBinding, str | None]:
+        """Resolve an exact Thread without coupling it to the Scope pointer."""
+
+        current_id = self._active_id(target.scope_key)
+        binding = self._bindings.get(target.binding_id)
+        if binding.scope_key != target.scope_key:
+            raise BindingScopeMismatch(target.binding_id)
+        return binding, current_id
+
+    def _active_id(self, scope_key: str) -> str | None:
+        active = self._bindings.active_binding(scope_key)
+        return active.id if active is not None else None
+
+    @staticmethod
+    def _require_side_identity(
+        record: SideTopicRecord,
+        target: CurrentSideTarget,
+    ) -> None:
+        if (
+            record.app_id != target.app_id
+            or record.chat_id != target.chat_id
+            or record.topic_id != target.topic_id
+            or record.root_message_id != target.root_message_id
+        ):
+            raise SideIdentityMismatch(target.side_id)