PraisonAI 4.6.71__tar.gz → 4.6.74__tar.gz

{praisonai-4.6.71 → praisonai-4.6.74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.71
+Version: 4.6.74
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.6.71
+Requires-Dist: praisonaiagents>=1.6.74
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.71 → praisonai-4.6.74}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.71
+Version: 4.6.74
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.6.71
+Requires-Dist: praisonaiagents>=1.6.74
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.71 → praisonai-4.6.74}/PraisonAI.egg-info/SOURCES.txt

@@ -76,6 +76,7 @@ praisonai/bots/_dlq.py
 praisonai/bots/_durable_adapter.py
 praisonai/bots/_email_utils.py
 praisonai/bots/_http_approval.py
+praisonai/bots/_identity.py
 praisonai/bots/_ingress.py
 praisonai/bots/_mirror.py
 praisonai/bots/_outbox.py
@@ -201,6 +202,8 @@ praisonai/cli/commands/flow.py
 praisonai/cli/commands/gateway.py
 praisonai/cli/commands/github.py
 praisonai/cli/commands/hooks.py
+praisonai/cli/commands/identity.py
+praisonai/cli/commands/init.py
 praisonai/cli/commands/kanban.py
 praisonai/cli/commands/knowledge.py
 praisonai/cli/commands/langextract.py
@@ -252,6 +255,7 @@ praisonai/cli/commands/validate.py
 praisonai/cli/commands/version.py
 praisonai/cli/commands/workflow.py
 praisonai/cli/configuration/__init__.py
+praisonai/cli/configuration/config.schema.json
 praisonai/cli/configuration/credentials.py
 praisonai/cli/configuration/loader.py
 praisonai/cli/configuration/paths.py
@@ -442,6 +446,7 @@ praisonai/cli/interactive/frontends/rich_frontend.py
 praisonai/cli/interactive/frontends/textual_frontend.py
 praisonai/cli/output/__init__.py
 praisonai/cli/output/console.py
+praisonai/cli/output/event_bridge.py
 praisonai/cli/session/__init__.py
 praisonai/cli/session/unified.py
 praisonai/cli/state/__init__.py
@@ -762,12 +767,16 @@ praisonai/scheduler/_dispatch.py
 praisonai/scheduler/agent_scheduler.py
 praisonai/scheduler/async_agent_scheduler.py
 praisonai/scheduler/base.py
+praisonai/scheduler/blueprint_catalogue.py
+praisonai/scheduler/condition_gate.py
 praisonai/scheduler/daemon_manager.py
 praisonai/scheduler/deployment.py
 praisonai/scheduler/enhanced_executor.py
 praisonai/scheduler/executor.py
+praisonai/scheduler/run_policy.py
 praisonai/scheduler/shared.py
 praisonai/scheduler/state_manager.py
+praisonai/scheduler/suggestion_engine.py
 praisonai/scheduler/yaml_loader.py
 praisonai/security/__init__.py
 praisonai/security/audit.py

{praisonai-4.6.71 → praisonai-4.6.74}/PraisonAI.egg-info/requires.txt

@@ -1,7 +1,7 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.6.71
+praisonaiagents>=1.6.74
 python-dotenv>=0.19.0
 litellm<2,>=1.83.14
 PyYAML>=6.0

{praisonai-4.6.71 → praisonai-4.6.74}/praisonai/_dev/parity/docs_generator.py

@@ -184,6 +184,40 @@ FEATURE_CATEGORIES = {
     'resource': 'Sandbox',  # ResourceLimits is part of sandbox execution
 }
 
+# Doc categories excluded from Python "Documentation Without Features" orphan reporting.
+# These pages document infra, other SDKs, or user-facing tooling outside praisonaiagents exports.
+PYTHON_DOC_ORPHAN_EXCLUSIONS = frozenset({
+    'Deployment',  # docs/deploy — CI/infra guidance, not Python SDK feature exports
+    'AI SDK',      # TypeScript SDK pages; tracked in docs/js/ parity separately
+})
+
+# Map doc-only category display names to SDK feature display names for parity matching.
+DOC_FEATURE_CATEGORY_ALIASES = {
+    'Callbacks': 'Hooks',
+    'Middleware': 'Hooks',
+    'Vector Store': 'Knowledge',
+    'Token Management': 'Context Management',
+    'Jobs': 'Workflows',
+    'Chat': 'Agent',
+    'Streaming': 'LLM',
+    'Scheduler': 'Tools',
+    'Storage': 'Database',
+    'Process': 'Workflows',
+}
+
+# Module-path hints when export names do not match FEATURE_CATEGORIES prefixes.
+MODULE_PATH_CATEGORY = (
+    ('deep_research_agent', 'deep-research'),
+    ('hooks', 'hook'),
+    ('streaming', 'stream'),
+    ('scheduler', 'scheduler'),
+    ('storage', 'storage'),
+    ('process', 'process'),
+    ('context.tokens', 'token'),
+    ('chat_handler', 'chat'),
+    ('chat_mixin', 'chat'),
+)
+
 
 # Minimum lines for a doc to be considered "real" (not a stub)
 MIN_DOC_LINES = 50
@@ -257,8 +291,14 @@ class DocsParityGenerator:
             current = current.parent
         return Path("/Users/praison/praisonai-package")
     
-    def _categorize_feature(self, feature_name: str) -> str:
-        """Map a feature name to its category."""
+    def _categorize_feature(self, feature_name: str, module_path: str = '') -> str:
+        """Map a feature name (and optional module path) to its category."""
+        if module_path:
+            path = module_path.replace('praisonaiagents.', '')
+            for hint, prefix in MODULE_PATH_CATEGORY:
+                if hint in path:
+                    return prefix
+
         normalized = normalize_topic(feature_name)
         
         # Try to find a matching prefix
@@ -305,7 +345,8 @@ class DocsParityGenerator:
         
         for export in exports:
             name = export.name if hasattr(export, 'name') else str(export)
-            category = self._categorize_feature(name)
+            module_path = export.module_path if hasattr(export, 'module_path') else ''
+            category = self._categorize_feature(name, module_path)
             if category not in groups:
                 groups[category] = []
             groups[category].append(name)
@@ -357,6 +398,9 @@ class DocsParityGenerator:
                 if prefix == 'other':
                     continue
                 display_name = FEATURE_CATEGORIES.get(prefix, prefix.title())
+                if display_name in PYTHON_DOC_ORPHAN_EXCLUSIONS:
+                    continue
+                display_name = DOC_FEATURE_CATEGORY_ALIASES.get(display_name, display_name)
                 if display_name not in result:
                     result[display_name] = ([], 0)
                 existing_names, existing_lines = result[display_name]

{praisonai-4.6.71 → praisonai-4.6.74}/praisonai/_lockmap.py

@@ -5,6 +5,7 @@ re-implementing the dict-of-Lock pattern.
 """
 from __future__ import annotations
 import asyncio
+import threading
 import time
 import weakref
 from collections import OrderedDict
@@ -17,9 +18,11 @@ class LockMap:
     Provides a lock per key with LRU eviction and TTL-based cleanup to prevent
     unbounded memory growth in long-running applications.
     
-    Note: Safe for use within a single asyncio event loop (cooperative
-    multitasking means no interleaving between non-awaited calls), but NOT
-    safe for concurrent access from multiple OS threads.
+    Buckets are keyed by event loop (one loop per OS thread). Structural
+    mutations of the bucket/loop maps are guarded by a ``threading.Lock`` so
+    the same instance can be safely shared across multiple OS threads, each
+    running its own event loop. Per-loop buckets are only ever touched from
+    their owning loop, so intra-loop access remains lock-free.
     """
 
     def __init__(self, *, max_entries: int = 10_000, ttl_seconds: float = 3600.0):
@@ -32,6 +35,8 @@ class LockMap:
         # Bucket locks by event loop to avoid cross-loop issues
         self._buckets: Dict[int, "OrderedDict[Hashable, tuple[asyncio.Lock, float]]"] = {}
         self._loop_refs: Dict[int, weakref.ref] = {}
+        # Guards structural mutations of _buckets / _loop_refs across OS threads.
+        self._struct_lock = threading.Lock()
         self._max = max_entries
         self._ttl = ttl_seconds
 
@@ -47,16 +52,25 @@ class LockMap:
         # Get the current running loop
         loop = asyncio.get_running_loop()
         loop_id = id(loop)
-        
-        # Clean up dead loops
-        self._cleanup_dead_loops()
-        
-        # Get or create bucket for this loop
-        if loop_id not in self._buckets:
-            self._buckets[loop_id] = OrderedDict()
-            self._loop_refs[loop_id] = weakref.ref(loop)
-        
-        bucket = self._buckets[loop_id]
+
+        # Fast path: a bucket for this loop already exists. The bucket is only
+        # ever mutated by its owning loop's thread, so a single dict read is
+        # safe under CPython's GIL without taking the cross-thread struct lock.
+        bucket = self._buckets.get(loop_id)
+        if bucket is None:
+            # Slow path: structural mutation shared across threads needs the lock.
+            with self._struct_lock:
+                # Clean up dead loops (only on first-touch to avoid per-call cost)
+                self._cleanup_dead_loops_locked()
+
+                # Re-check after acquiring the lock (another thread may have raced).
+                bucket = self._buckets.get(loop_id)
+                if bucket is None:
+                    bucket = OrderedDict()
+                    self._buckets[loop_id] = bucket
+                    self._loop_refs[loop_id] = weakref.ref(loop)
+
+        # From here on only this loop's owning thread touches the bucket.
         now = time.monotonic()
         
         entry = bucket.get(key)
@@ -99,27 +113,31 @@ class LockMap:
             bucket.popitem(last=False)
             break
     
-    def _cleanup_dead_loops(self) -> None:
-        """Remove buckets for event loops that no longer exist."""
-        dead_loops = []
-        for loop_id, ref in self._loop_refs.items():
-            loop = ref()
-            if loop is None or loop.is_closed():
-                dead_loops.append(loop_id)
-        
+    def _cleanup_dead_loops_locked(self) -> None:
+        """Remove buckets for event loops that no longer exist.
+
+        Caller must hold ``self._struct_lock``.
+        """
+        dead_loops = [
+            loop_id
+            for loop_id, ref in self._loop_refs.items()
+            if (loop := ref()) is None or loop.is_closed()
+        ]
         for loop_id in dead_loops:
-            del self._loop_refs[loop_id]
-            if loop_id in self._buckets:
-                del self._buckets[loop_id]
+            self._loop_refs.pop(loop_id, None)
+            self._buckets.pop(loop_id, None)
 
     def drop(self, key: Hashable) -> None:
         """Manually remove a lock for the given key."""
         # Get the current running loop
         loop = asyncio.get_running_loop()
         loop_id = id(loop)
-        if loop_id in self._buckets:
-            self._buckets[loop_id].pop(key, None)
+        with self._struct_lock:
+            bucket = self._buckets.get(loop_id)
+        if bucket is not None:
+            bucket.pop(key, None)
 
     def size(self) -> int:
         """Return current number of cached locks across all buckets."""
-        return sum(len(bucket) for bucket in self._buckets.values())
+        with self._struct_lock:
+            return sum(len(bucket) for bucket in self._buckets.values())

{praisonai-4.6.71 → praisonai-4.6.74}/praisonai/agents_generator.py

@@ -1,25 +1,41 @@
 # praisonai/agents_generator.py
 
 import sys
-from typing import Dict, Any, Optional, List
-from .version import __version__
-import yaml, os
-from rich import print
-import inspect
-from pathlib import Path
-import importlib
-import importlib.util
 import os
+import inspect
 import logging
 import re
 import keyword
 import difflib
+import importlib
+import importlib.util
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+
+from .version import __version__
 
 # Import new architecture components
 from .framework_adapters.base import FrameworkAdapter
-from .framework_adapters.registry import FrameworkAdapterRegistry, get_default_registry
 from .tool_registry import ToolRegistry
 
+
+def _rich_print(*args, **kwargs):
+    """Lazy alias for rich.print — pays the import cost only on first use."""
+    from rich import print as _rp
+    return _rp(*args, **kwargs)
+
+
+def _yaml_safe_load(stream):
+    """Lazy alias for yaml.safe_load."""
+    import yaml
+    return yaml.safe_load(stream)
+
+
+def _get_default_adapter_registry():
+    """Lazy import for the adapter registry — defers entry-point discovery."""
+    from .framework_adapters.registry import get_default_registry
+    return get_default_registry()
+
 # Import availability flags
 # Compatibility imports - now handled by centralized detection
 # (inbuilt_tools still defines these but they're read-only compatibility)
@@ -233,7 +249,7 @@ class AgentsGenerator:
         
         # DI-friendly: tests/multi-tenant runtimes pass their own registry;
         # CLI users get the process default.
-        self._adapter_registry = adapter_registry or get_default_registry()
+        self._adapter_registry = adapter_registry or _get_default_adapter_registry()
         
         # Defer framework adapter creation until YAML is loaded
         # This fixes the issue where empty framework string fails before YAML framework is read
@@ -543,15 +559,15 @@ class AgentsGenerator:
     def _load_config(self):
         """Load configuration from agent file or agent_yaml."""
         if self.agent_yaml:
-            config = yaml.safe_load(self.agent_yaml)
+            config = _yaml_safe_load(self.agent_yaml)
         else:
             if self.agent_file in ('/app/api:app', 'api:app'):
                 self.agent_file = 'agents.yaml'
             try:
                 with open(self.agent_file, 'r') as f:
-                    config = yaml.safe_load(f)
+                    config = _yaml_safe_load(f)
             except FileNotFoundError:
-                print(f"File not found: {self.agent_file}")
+                _rich_print(f"File not found: {self.agent_file}")
                 return None
         
         # Apply CLI config overrides to both paths (agent_yaml and agent_file)

{praisonai-4.6.71 → praisonai-4.6.74}/praisonai/bots/__init__.py

@@ -18,6 +18,7 @@ if TYPE_CHECKING:
     from .bot import Bot
     from .botos import BotOS
     from ._session import BotSessionManager
+    from ._identity import StoreBackedIdentityResolver
     from ._dlq import InboundDLQ, DLQEntry
     from ._ingress import InboundJournal, JournalEntry
     from ._slack_approval import SlackApproval
@@ -81,6 +82,9 @@ def __getattr__(name: str):
     if name == "BotSessionManager":
         from ._session import BotSessionManager
         return BotSessionManager
+    if name == "StoreBackedIdentityResolver":
+        from ._identity import StoreBackedIdentityResolver
+        return StoreBackedIdentityResolver
     # N4 — inbound dead-letter queue
     if name == "InboundDLQ":
         from ._dlq import InboundDLQ
@@ -130,6 +134,7 @@ __all__ = [
     "TelegramBot", "DiscordBot", "SlackBot", "WhatsAppBot", "LinearBot", "EmailBot", "AgentMailBot",
     "Bot", "BotOS",
     "BotSessionManager",
+    "StoreBackedIdentityResolver",
     "InboundDLQ", "DLQEntry",
     "InboundJournal", "JournalEntry",
     "OutboundQueue", "OutboundEntry",

{praisonai-4.6.71 → praisonai-4.6.74}/praisonai/bots/_config_schema.py

@@ -76,10 +76,50 @@ class SessionResetConfigSchema(BaseModel):
         return self
 
 
+class SessionCompactionConfigSchema(BaseModel):
+    """Schema for session history compaction configuration.
+
+    When enabled, older turns in a long-lived bot/gateway session are
+    summarised (rather than hard-truncated) once the history exceeds the
+    configured budget, so context survives across weeks-long conversations
+    and restarts. Disabled by default to preserve legacy behaviour.
+    """
+    enabled: bool = False
+    strategy: str = "summarize"  # truncate | sliding | summarize | smart | prune | llm_summarize
+    max_messages: int = 100  # Approx. compaction threshold (converted to a token budget; max_history remains a hard cap)
+    max_tokens: Optional[int] = None  # Optional token-based budget (overrides messages)
+    keep_recent: int = 10  # Number of most-recent messages kept verbatim
+
+    @field_validator("strategy")
+    @classmethod
+    def validate_strategy(cls, v: str) -> str:
+        allowed = {"truncate", "sliding", "summarize", "smart", "prune", "llm_summarize"}
+        if v not in allowed:
+            raise ValueError(
+                f"Invalid compaction strategy '{v}'. Must be one of: {', '.join(sorted(allowed))}"
+            )
+        return v
+
+    @field_validator("max_messages")
+    @classmethod
+    def validate_max_messages(cls, v: int) -> int:
+        if v < 1:
+            raise ValueError("max_messages must be at least 1")
+        return v
+
+    @field_validator("keep_recent")
+    @classmethod
+    def validate_keep_recent(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError("keep_recent must be non-negative")
+        return v
+
+
 class SessionConfigSchema(BaseModel):
     """Schema for session configuration."""
     max_history: int = 100
     reset: Optional[SessionResetConfigSchema] = None
+    compaction: Optional[SessionCompactionConfigSchema] = None
 
 
 class StreamingConfigSchema(BaseModel):
@@ -156,6 +196,7 @@ class ChannelConfigSchema(BaseModel):
     user_allowed_commands: Optional[str] = None  # Comma-separated list of allowed commands
     routes: Dict[str, str] = Field(default_factory=dict)  # Context -> agent_id mapping
     routing: Optional[Dict[str, str]] = None  # Alias for routes
+    bindings: List[Dict[str, Any]] = Field(default_factory=list)  # Priority-ordered route bindings (Issue #2225)
     webhook_url: Optional[str] = None
     webhook_port: int = 8080
     streaming: Optional[StreamingConfigSchema] = None

praisonai-4.6.74/praisonai/bots/_identity.py

@@ -0,0 +1,199 @@
+"""
+Store-backed cross-platform identity resolver (wrapper implementation).
+
+The core SDK ships the ``IdentityResolverProtocol`` and lightweight
+in-memory / file-backed resolvers (``praisonaiagents.session.identity``).
+This module provides a *heavy* implementation that reuses the wrapper's
+persistence and **pairing** data so a linked/paired user shares one
+session, history and memory across channels **by default**.
+
+``StoreBackedIdentityResolver``:
+
+1. Keeps an explicit, persisted ``(platform, user_id) -> canonical_id``
+   link map (inherited from the core ``FileIdentityResolver``).
+2. Falls back to the gateway pairing store: when two channels were paired
+   under the same label/canonical id, they resolve to that id.
+3. Otherwise returns the per-platform id ``f"{platform}:{user_id}"`` — a
+   safe, non-merging default identical to the core resolver.
+
+Construction::
+
+    from praisonai.bots import StoreBackedIdentityResolver
+
+    resolver = StoreBackedIdentityResolver.from_env()
+    botos = BotOS(agent=agent, platforms=[...], identity_resolver=resolver)
+
+    # Link two channels to one canonical id
+    resolver.link("telegram", "12345", "alice")
+    resolver.link("whatsapp", "+44...", "alice")
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+from praisonaiagents.session.identity import FileIdentityResolver
+
+logger = logging.getLogger(__name__)
+
+
+class StoreBackedIdentityResolver(FileIdentityResolver):
+    """File-backed identity resolver augmented with pairing data.
+
+    Inherits the thread-safe, atomically-persisted link map from
+    :class:`praisonaiagents.session.identity.FileIdentityResolver` and adds
+    an optional read-through to a gateway :class:`PairingStore` so that
+    already-paired channels are recognised without an explicit ``link()``.
+
+    Resolution order for ``resolve(platform, user_id)``:
+
+    1. An explicit link registered via :meth:`link` (highest priority).
+    2. The pairing store's label for ``(user_id, platform)`` when that
+       channel is paired and carries a non-empty label (treated as the
+       canonical id) — lets paired users share a session out of the box.
+    3. ``f"{platform}:{user_id}"`` — the safe per-platform fallback.
+
+    Args:
+        path: JSON file for the explicit link map. Defaults to the core
+            resolver default (``$PRAISONAI_IDENTITY_PATH`` or
+            ``~/.praisonai/identity.json``).
+        pairing_store: Optional object exposing ``is_paired`` /
+            ``list_paired`` (e.g. ``praisonai.gateway.pairing.PairingStore``).
+            When ``None``, behaviour matches the plain file resolver.
+        use_pairing_label: When ``True`` (default) a paired channel's
+            ``label`` is used as its canonical id. Set ``False`` to ignore
+            labels and rely solely on explicit links.
+    """
+
+    def __init__(
+        self,
+        path: Optional[Path | str] = None,
+        pairing_store: Optional[Any] = None,
+        use_pairing_label: bool = True,
+    ) -> None:
+        super().__init__(path=path)
+        self._pairing_store = pairing_store
+        self._use_pairing_label = use_pairing_label
+
+    @classmethod
+    def from_env(
+        cls,
+        path: Optional[Path | str] = None,
+        store_dir: Optional[str] = None,
+        use_pairing_label: bool = True,
+    ) -> "StoreBackedIdentityResolver":
+        """Build a resolver wired to the default gateway pairing store.
+
+        The pairing store is loaded lazily and any failure (e.g. optional
+        deps unavailable) degrades gracefully to a plain file resolver.
+
+        Args:
+            path: Override for the explicit link-map JSON path.
+            store_dir: Override for the pairing store directory.
+            use_pairing_label: Forwarded to ``__init__``.
+        """
+        pairing_store = None
+        try:
+            from praisonai.gateway.pairing import PairingStore
+
+            pairing_store = PairingStore(store_dir=store_dir)
+        except Exception as e:  # pragma: no cover — optional/degraded path
+            logger.warning(
+                "StoreBackedIdentityResolver: pairing store unavailable, "
+                "falling back to link-map only: %s",
+                e,
+            )
+        return cls(
+            path=path,
+            pairing_store=pairing_store,
+            use_pairing_label=use_pairing_label,
+        )
+
+    def resolve(self, platform: str, platform_user_id: str) -> str:
+        # 1. Explicit links take precedence. The parent returns the
+        #    per-platform fallback when no explicit link exists; detect
+        #    that so we can consult the pairing store before giving up.
+        fallback = f"{platform}:{platform_user_id}"
+        with self._lock:
+            explicit = self._links.get((platform, platform_user_id))
+        if explicit is not None:
+            return explicit
+
+        # 2. Pairing-store read-through: a paired channel's label is the
+        #    canonical id shared across channels paired under it.
+        if self._pairing_store is not None and self._use_pairing_label:
+            try:
+                canonical = self._canonical_from_pairing(platform, platform_user_id)
+                if canonical:
+                    return canonical
+            except Exception as e:  # pragma: no cover — defensive
+                logger.warning("identity pairing lookup failed: %s", e)
+
+        # 3. Safe per-platform fallback.
+        return fallback
+
+    def link_paired(self) -> int:
+        """Materialise pairing-store labels as explicit links.
+
+        Scans the pairing store and registers an explicit link for every
+        paired channel whose label is non-empty, so paired users keep a
+        stable canonical id even if the pairing store later changes.
+
+        Returns the number of links created/updated.
+        """
+        if self._pairing_store is None:
+            return 0
+        count = 0
+        try:
+            paired = self._pairing_store.list_paired()
+        except Exception as e:  # pragma: no cover — defensive
+            logger.warning("identity link_paired failed to list pairings: %s", e)
+            return 0
+        for ch in paired:
+            label = getattr(ch, "label", "") or ""
+            channel_type = getattr(ch, "channel_type", "")
+            channel_id = getattr(ch, "channel_id", "")
+            if label and channel_type and channel_id:
+                # Write in-memory only; flush once after the loop to avoid
+                # N atomic disk writes when materialising many pairings.
+                with self._lock:
+                    self._links[(channel_type, channel_id)] = label
+                count += 1
+        if count:
+            self._flush()
+        return count
+
+    def all_links(self) -> list[tuple[str, str, str]]:
+        """Return every explicit link as ``(platform, user_id, canonical)``."""
+        with self._lock:
+            return [
+                (platform, user_id, canonical)
+                for (platform, user_id), canonical in self._links.items()
+            ]
+
+    def _canonical_from_pairing(
+        self, platform: str, platform_user_id: str
+    ) -> Optional[str]:
+        """Return the pairing label (canonical id) for a paired channel."""
+        store = self._pairing_store
+        # Fast path: most messages come from unpaired users. ``is_paired`` is
+        # an O(1) dict lookup, so short-circuit before the O(n) scan below.
+        is_paired = getattr(store, "is_paired", None)
+        if callable(is_paired) and not is_paired(platform_user_id, platform):
+            return None
+        list_paired = getattr(store, "list_paired", None)
+        if not callable(list_paired):
+            return None
+        for ch in list_paired():
+            if (
+                getattr(ch, "channel_id", None) == platform_user_id
+                and getattr(ch, "channel_type", None) == platform
+            ):
+                label = getattr(ch, "label", "") or ""
+                return label or None
+        return None
+
+
+__all__ = ["StoreBackedIdentityResolver"]