patchr 0.1.0__py3-none-any.whl

picux/storage/postgres.py

@@ -0,0 +1,2049 @@
+from __future__ import annotations
+
+import json
+import logging
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Iterator
+
+from picux.config import PicuxSettings
+from picux.core import Domain, ProtocolTask, ProtocolTaskStatus, ProtocolUser
+
+logger = logging.getLogger("picux.storage.postgres")
+
+try:
+    import psycopg
+except Exception:  # pragma: no cover - optional dependency
+    psycopg = None
+
+
+class PicuxPostgresStore:
+    """Optional Postgres persistence for protocol-grade state and audit logs."""
+
+    def __init__(self, dsn: str = "", *, ensure: bool = True) -> None:
+        self.dsn = (dsn or "").strip()
+        self.enabled = bool(self.dsn and psycopg is not None)
+        if self.enabled and ensure:
+            self.ensureSchema()
+
+    @classmethod
+    def fromEnv(cls) -> "PicuxPostgresStore":
+        return cls(PicuxSettings.fromEnv().postgresDsn)
+
+    @contextmanager
+    def conn(self) -> Iterator[Any]:
+        if not self.enabled:
+            raise RuntimeError("postgresDisabled")
+        db = psycopg.connect(self.dsn)
+        try:
+            yield db
+            db.commit()
+        finally:
+            db.close()
+
+    def ddl(self) -> list[str]:
+        return [
+            """
+            CREATE TABLE IF NOT EXISTS picux_users (
+                user_id TEXT PRIMARY KEY,
+                channel TEXT NOT NULL DEFAULT 'api',
+                trust INTEGER NOT NULL DEFAULT 1,
+                refs JSONB NOT NULL DEFAULT '{}'::jsonb,
+                prefs JSONB NOT NULL DEFAULT '{}'::jsonb,
+                meta JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_users_channel ON picux_users (channel)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_agents (
+                agent_id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                domains JSONB NOT NULL DEFAULT '[]'::jsonb,
+                caps JSONB NOT NULL DEFAULT '[]'::jsonb,
+                endpoint TEXT NOT NULL DEFAULT '',
+                trust INTEGER NOT NULL DEFAULT 1,
+                status TEXT NOT NULL DEFAULT 'active',
+                meta JSONB NOT NULL DEFAULT '{}'::jsonb,
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_agents_status ON picux_agents (status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_agents_domains ON picux_agents USING GIN (domains)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_agents_caps ON picux_agents USING GIN (caps)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_a2a_envelopes (
+                msg_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL DEFAULT 'queued',
+                from_agent TEXT NOT NULL DEFAULT '',
+                to_agent TEXT NOT NULL DEFAULT '',
+                trace_id TEXT NOT NULL DEFAULT '',
+                task_id TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_a2a_envelopes_to_status ON picux_a2a_envelopes (to_agent, status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_a2a_envelopes_trace ON picux_a2a_envelopes (trace_id)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_mandates (
+                mandate_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL DEFAULT 'pendingVerification',
+                issuer_id TEXT NOT NULL DEFAULT '',
+                mandate JSONB NOT NULL DEFAULT '{}'::jsonb,
+                validation JSONB NOT NULL DEFAULT '{}'::jsonb,
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_mandates_status ON picux_mandates (status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_mandates_issuer ON picux_mandates (issuer_id)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_tasks (
+                task_id TEXT PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                domain TEXT NOT NULL,
+                status TEXT NOT NULL,
+                channel TEXT NOT NULL DEFAULT 'api',
+                mandate_id TEXT NOT NULL DEFAULT '',
+                in_data JSONB NOT NULL DEFAULT '{}'::jsonb,
+                out_data JSONB NOT NULL DEFAULT '{}'::jsonb,
+                needs_approval BOOLEAN NOT NULL DEFAULT FALSE,
+                ext_ref TEXT NOT NULL DEFAULT '',
+                error_msg TEXT NOT NULL DEFAULT '',
+                meta JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                approval_by BIGINT
+            )
+            """,
+            "ALTER TABLE picux_tasks ADD COLUMN IF NOT EXISTS needs_approval BOOLEAN NOT NULL DEFAULT FALSE",
+            "ALTER TABLE picux_tasks ADD COLUMN IF NOT EXISTS ext_ref TEXT NOT NULL DEFAULT ''",
+            "ALTER TABLE picux_tasks ADD COLUMN IF NOT EXISTS error_msg TEXT NOT NULL DEFAULT ''",
+            "ALTER TABLE picux_tasks ADD COLUMN IF NOT EXISTS approval_by BIGINT",
+            "CREATE INDEX IF NOT EXISTS idx_picux_tasks_user_created ON picux_tasks (user_id, created_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_tasks_domain_status ON picux_tasks (domain, status)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_activity_logs (
+                id BIGSERIAL PRIMARY KEY,
+                task_id TEXT NOT NULL,
+                user_id TEXT NOT NULL,
+                level TEXT NOT NULL,
+                action TEXT NOT NULL,
+                detail TEXT NOT NULL,
+                meta JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_activity_task_created ON picux_activity_logs (task_id, created_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_activity_user_created ON picux_activity_logs (user_id, created_at DESC)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_activity_events (
+                id BIGSERIAL PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                task_id TEXT NOT NULL DEFAULT '',
+                event TEXT NOT NULL,
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_events_user_created ON picux_activity_events (user_id, created_at DESC)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_event_subscriptions (
+                sub_id TEXT PRIMARY KEY,
+                client_id TEXT NOT NULL,
+                target TEXT NOT NULL DEFAULT '',
+                transport TEXT NOT NULL DEFAULT 'poll',
+                endpoint TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'active',
+                event_types JSONB NOT NULL DEFAULT '[]'::jsonb,
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_event_subscriptions_client ON picux_event_subscriptions (client_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_event_subscriptions_status_transport ON picux_event_subscriptions (status, transport)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_integration_events (
+                event_id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                subject TEXT NOT NULL DEFAULT '',
+                source TEXT NOT NULL DEFAULT 'picux',
+                target TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'queued',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                ack_at TIMESTAMPTZ
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_integration_events_type_status ON picux_integration_events (type, status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_integration_events_target_created ON picux_integration_events (target, created_at DESC)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_event_deliveries (
+                delivery_id TEXT PRIMARY KEY,
+                event_id TEXT NOT NULL,
+                sub_id TEXT NOT NULL,
+                client_id TEXT NOT NULL DEFAULT '',
+                transport TEXT NOT NULL DEFAULT 'poll',
+                endpoint TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'queued',
+                attempt INTEGER NOT NULL DEFAULT 1,
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                next_attempt_at TIMESTAMPTZ,
+                claimed_at TIMESTAMPTZ,
+                lease_expires_at TIMESTAMPTZ,
+                delivered_at TIMESTAMPTZ
+            )
+            """,
+            "ALTER TABLE picux_event_deliveries ADD COLUMN IF NOT EXISTS next_attempt_at TIMESTAMPTZ",
+            "ALTER TABLE picux_event_deliveries ADD COLUMN IF NOT EXISTS lease_expires_at TIMESTAMPTZ",
+            "CREATE INDEX IF NOT EXISTS idx_picux_event_deliveries_event ON picux_event_deliveries (event_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_event_deliveries_sub_status ON picux_event_deliveries (sub_id, status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_event_deliveries_client_status ON picux_event_deliveries (client_id, status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_event_deliveries_status_lease ON picux_event_deliveries (status, lease_expires_at)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_event_deliveries_status_next_attempt ON picux_event_deliveries (status, next_attempt_at)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_bridge_connectors (
+                connector_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL DEFAULT 'active',
+                domain TEXT NOT NULL DEFAULT 'bridge',
+                kind TEXT NOT NULL DEFAULT 'api',
+                endpoint TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_bridge_connectors_status ON picux_bridge_connectors (status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_bridge_connectors_domain_kind ON picux_bridge_connectors (domain, kind)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_bridge_connection_sessions (
+                session_id TEXT PRIMARY KEY,
+                connector_id TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'active',
+                subject_id TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_bridge_sessions_connector_status ON picux_bridge_connection_sessions (connector_id, status)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_channel_threads (
+                thread_id TEXT PRIMARY KEY,
+                case_id TEXT NOT NULL DEFAULT '',
+                conversation_id TEXT NOT NULL DEFAULT '',
+                channel TEXT NOT NULL DEFAULT 'api',
+                provider TEXT NOT NULL DEFAULT '',
+                provider_thread_id TEXT NOT NULL DEFAULT '',
+                connector_id TEXT NOT NULL DEFAULT '',
+                session_id TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'active',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_channel_threads_case ON picux_channel_threads (case_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_channel_threads_conversation ON picux_channel_threads (conversation_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_channel_threads_provider_ref ON picux_channel_threads (provider, provider_thread_id)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_touchpoints (
+                touchpoint_id TEXT PRIMARY KEY,
+                thread_id TEXT NOT NULL DEFAULT '',
+                case_id TEXT NOT NULL DEFAULT '',
+                conversation_id TEXT NOT NULL DEFAULT '',
+                channel TEXT NOT NULL DEFAULT 'api',
+                provider TEXT NOT NULL DEFAULT '',
+                connector_id TEXT NOT NULL DEFAULT '',
+                direction TEXT NOT NULL DEFAULT 'inbound',
+                status TEXT NOT NULL DEFAULT 'received',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_touchpoints_thread_created ON picux_touchpoints (thread_id, created_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_touchpoints_case_created ON picux_touchpoints (case_id, created_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_touchpoints_conversation_created ON picux_touchpoints (conversation_id, created_at DESC)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_provider_actions (
+                action_id TEXT PRIMARY KEY,
+                case_id TEXT NOT NULL DEFAULT '',
+                conversation_id TEXT NOT NULL DEFAULT '',
+                thread_id TEXT NOT NULL DEFAULT '',
+                connector_id TEXT NOT NULL DEFAULT '',
+                session_id TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'queued',
+                action TEXT NOT NULL DEFAULT '',
+                resource TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_provider_actions_connector_status ON picux_provider_actions (connector_id, status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_provider_actions_case ON picux_provider_actions (case_id)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_provider_callbacks (
+                callback_id TEXT PRIMARY KEY,
+                case_id TEXT NOT NULL DEFAULT '',
+                conversation_id TEXT NOT NULL DEFAULT '',
+                thread_id TEXT NOT NULL DEFAULT '',
+                connector_id TEXT NOT NULL DEFAULT '',
+                session_id TEXT NOT NULL DEFAULT '',
+                provider TEXT NOT NULL DEFAULT '',
+                provider_event_id TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'received',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                received_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_provider_callbacks_provider_event ON picux_provider_callbacks (provider, provider_event_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_provider_callbacks_conversation ON picux_provider_callbacks (conversation_id)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_case_workspaces (
+                case_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL DEFAULT 'open',
+                owner_id TEXT NOT NULL DEFAULT '',
+                conversation_id TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_case_workspaces_status ON picux_case_workspaces (status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_case_workspaces_owner ON picux_case_workspaces (owner_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_case_workspaces_conversation ON picux_case_workspaces (conversation_id)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_case_events (
+                event_id TEXT PRIMARY KEY,
+                case_id TEXT NOT NULL DEFAULT '',
+                type TEXT NOT NULL DEFAULT '',
+                actor TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_case_events_case_created ON picux_case_events (case_id, created_at DESC)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_portal_sessions (
+                portal_session_id TEXT PRIMARY KEY,
+                case_id TEXT NOT NULL DEFAULT '',
+                conversation_id TEXT NOT NULL DEFAULT '',
+                connector_id TEXT NOT NULL DEFAULT '',
+                provider TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'active',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_portal_sessions_case ON picux_portal_sessions (case_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_portal_sessions_connector ON picux_portal_sessions (connector_id, status)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_portal_actions (
+                portal_action_id TEXT PRIMARY KEY,
+                portal_session_id TEXT NOT NULL DEFAULT '',
+                case_id TEXT NOT NULL DEFAULT '',
+                conversation_id TEXT NOT NULL DEFAULT '',
+                connector_id TEXT NOT NULL DEFAULT '',
+                provider TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL DEFAULT 'queued',
+                kind TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_portal_actions_session ON picux_portal_actions (portal_session_id)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_portal_actions_case_status ON picux_portal_actions (case_id, status)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_pov_events (
+                event_id TEXT PRIMARY KEY,
+                user_id TEXT NOT NULL DEFAULT '',
+                task_id TEXT NOT NULL DEFAULT '',
+                domain TEXT NOT NULL,
+                value_amount NUMERIC(12,2) NOT NULL DEFAULT 0,
+                currency TEXT NOT NULL DEFAULT 'USD',
+                summary TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                occurred_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_pov_user_occurred ON picux_pov_events (user_id, occurred_at DESC)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_community_signals (
+                signal_id TEXT PRIMARY KEY,
+                entity TEXT NOT NULL DEFAULT 'unknown',
+                confidence NUMERIC(5,4) NOT NULL DEFAULT 0,
+                source_platform TEXT NOT NULL DEFAULT '',
+                query TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_community_signals_entity ON picux_community_signals (entity)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_community_signals_source_query ON picux_community_signals (source_platform, query)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_evidence_artifacts (
+                artifact_id TEXT PRIMARY KEY,
+                kind TEXT NOT NULL DEFAULT '',
+                source TEXT NOT NULL DEFAULT '',
+                payload_hash TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_evidence_kind_source ON picux_evidence_artifacts (kind, source)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_evidence_payload_hash ON picux_evidence_artifacts (payload_hash)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_escrows (
+                escrow_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL DEFAULT 'pending',
+                mandate_id TEXT NOT NULL DEFAULT '',
+                task_id TEXT NOT NULL DEFAULT '',
+                amount NUMERIC(12,2) NOT NULL DEFAULT 0,
+                currency TEXT NOT NULL DEFAULT 'USD',
+                pov_ref TEXT NOT NULL DEFAULT '',
+                receipt_id TEXT NOT NULL DEFAULT '',
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_escrows_status ON picux_escrows (status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_escrows_mandate_task ON picux_escrows (mandate_id, task_id)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_proxy_missions (
+                proxy_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL DEFAULT 'awaitingProxy',
+                kind TEXT NOT NULL DEFAULT 'custom',
+                task_id TEXT NOT NULL DEFAULT '',
+                user_id TEXT NOT NULL DEFAULT '',
+                resolve_id TEXT NOT NULL DEFAULT '',
+                refs JSONB NOT NULL DEFAULT '{}'::jsonb,
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_picux_proxy_missions_status ON picux_proxy_missions (status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_proxy_missions_task_status ON picux_proxy_missions (task_id, status)",
+            "CREATE INDEX IF NOT EXISTS idx_picux_proxy_missions_refs ON picux_proxy_missions USING GIN (refs)",
+            """
+            CREATE TABLE IF NOT EXISTS picux_receipts (
+                receipt_id TEXT PRIMARY KEY,
+                task_id TEXT NOT NULL DEFAULT '',
+                mandate_id TEXT NOT NULL DEFAULT '',
+                status TEXT NOT NULL,
+                payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS picux_schema_migrations (
+                version TEXT PRIMARY KEY,
+                applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+            """,
+        ]
+
+    def ensureSchema(self) -> None:
+        if not self.enabled:
+            return
+        with self.conn() as db:
+            with db.cursor() as cur:
+                for stmt in self.ddl():
+                    cur.execute(stmt)
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-09-001",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-001",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-002",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-003",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-004",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-005",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-006",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-007",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-008",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-009",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-010",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-011",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-012",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-10-013",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-14-001",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-14-002",),
+                )
+                cur.execute(
+                    "INSERT INTO picux_schema_migrations (version) VALUES (%s) ON CONFLICT (version) DO NOTHING",
+                    ("2026-05-14-003",),
+                )
+
+    def upsertUser(self, user: ProtocolUser) -> None:
+        if not self.enabled:
+            return
+        sql = (
+            "INSERT INTO picux_users (user_id, channel, trust, refs, prefs, meta, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s::jsonb, %s::jsonb, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (user_id) DO UPDATE SET "
+            "channel = EXCLUDED.channel, trust = EXCLUDED.trust, refs = EXCLUDED.refs, "
+            "prefs = EXCLUDED.prefs, meta = EXCLUDED.meta, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        user.userId,
+                        user.channel,
+                        user.trust,
+                        json.dumps(user.refs, ensure_ascii=True),
+                        json.dumps(user.prefs, ensure_ascii=True),
+                        json.dumps(user.meta, ensure_ascii=True),
+                        int(user.createdAt or 0),
+                        int(user.updatedAt or 0),
+                    ),
+                )
+
+    def upsertTask(self, task: ProtocolTask) -> None:
+        if not self.enabled:
+            return
+        sql = (
+            "INSERT INTO picux_tasks "
+            "(task_id, user_id, domain, status, channel, mandate_id, in_data, out_data, needs_approval, "
+            "ext_ref, error_msg, meta, created_at, updated_at, approval_by) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, %s, %s, %s, %s::jsonb, "
+            "TO_TIMESTAMP(%s), TO_TIMESTAMP(%s), %s) "
+            "ON CONFLICT (task_id) DO UPDATE SET "
+            "user_id = EXCLUDED.user_id, domain = EXCLUDED.domain, status = EXCLUDED.status, "
+            "channel = EXCLUDED.channel, mandate_id = EXCLUDED.mandate_id, in_data = EXCLUDED.in_data, "
+            "out_data = EXCLUDED.out_data, needs_approval = EXCLUDED.needs_approval, ext_ref = EXCLUDED.ext_ref, "
+            "error_msg = EXCLUDED.error_msg, meta = EXCLUDED.meta, updated_at = EXCLUDED.updated_at, "
+            "approval_by = EXCLUDED.approval_by"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        task.taskId,
+                        task.userId,
+                        task.domain.value,
+                        task.status.value,
+                        task.channel,
+                        task.mandateId,
+                        json.dumps(task.inData, ensure_ascii=True),
+                        json.dumps(task.outData, ensure_ascii=True),
+                        task.needsApproval,
+                        task.extRef,
+                        task.errorMsg,
+                        json.dumps(task.meta, ensure_ascii=True),
+                        int(task.createdAt or 0),
+                        int(task.updatedAt or 0),
+                        task.approvalBy,
+                    ),
+                )
+
+    def upsertAgent(self, agent: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        agentId = str(agent.get("agentId", "") or "")
+        if not agentId:
+            return
+        domains = agent.get("domains", []) if isinstance(agent.get("domains"), list) else []
+        caps = agent.get("caps", []) if isinstance(agent.get("caps"), list) else []
+        meta = agent.get("meta", {}) if isinstance(agent.get("meta"), dict) else {}
+        sql = (
+            "INSERT INTO picux_agents "
+            "(agent_id, name, domains, caps, endpoint, trust, status, meta, payload, updated_at) "
+            "VALUES (%s, %s, %s::jsonb, %s::jsonb, %s, %s, %s, %s::jsonb, %s::jsonb, NOW()) "
+            "ON CONFLICT (agent_id) DO UPDATE SET "
+            "name = EXCLUDED.name, domains = EXCLUDED.domains, caps = EXCLUDED.caps, "
+            "endpoint = EXCLUDED.endpoint, trust = EXCLUDED.trust, status = EXCLUDED.status, "
+            "meta = EXCLUDED.meta, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        agentId,
+                        str(agent.get("name", agentId) or agentId),
+                        json.dumps(domains, ensure_ascii=True),
+                        json.dumps(caps, ensure_ascii=True),
+                        str(agent.get("endpoint", "") or ""),
+                        int(agent.get("trust", 1) or 1),
+                        str(agent.get("status", "active") or "active"),
+                        json.dumps(meta, ensure_ascii=True),
+                        json.dumps(agent or {}, ensure_ascii=True),
+                    ),
+                )
+
+    def fetchAgent(self, agentId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_agents WHERE agent_id = %s", (agentId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listAgents(self) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_agents ORDER BY agent_id")
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertEnvelope(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        msgId = str(record.get("msgId", "") or "")
+        if not msgId:
+            return
+        sql = (
+            "INSERT INTO picux_a2a_envelopes "
+            "(msg_id, status, from_agent, to_agent, trace_id, task_id, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (msg_id) DO UPDATE SET "
+            "status = EXCLUDED.status, from_agent = EXCLUDED.from_agent, to_agent = EXCLUDED.to_agent, "
+            "trace_id = EXCLUDED.trace_id, task_id = EXCLUDED.task_id, payload = EXCLUDED.payload, "
+            "updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        msgId,
+                        str(record.get("status", "queued") or "queued"),
+                        str(record.get("fromAgent", "") or ""),
+                        str(record.get("toAgent", "") or ""),
+                        str(record.get("traceId", "") or ""),
+                        str(record.get("taskId", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchEnvelope(self, msgId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_a2a_envelopes WHERE msg_id = %s", (msgId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listEnvelopes(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_a2a_envelopes ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertMandate(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        mandateId = str(record.get("mandateId", "") or "")
+        if not mandateId:
+            return
+        mandate = record.get("mandate", {}) if isinstance(record.get("mandate"), dict) else {}
+        issuer = mandate.get("issuer", {}) if isinstance(mandate.get("issuer"), dict) else {}
+        validation = record.get("validation", {}) if isinstance(record.get("validation"), dict) else {}
+        sql = (
+            "INSERT INTO picux_mandates "
+            "(mandate_id, status, issuer_id, mandate, validation, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s::jsonb, %s::jsonb, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (mandate_id) DO UPDATE SET "
+            "status = EXCLUDED.status, issuer_id = EXCLUDED.issuer_id, mandate = EXCLUDED.mandate, "
+            "validation = EXCLUDED.validation, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        mandateId,
+                        str(record.get("status", "pendingVerification") or "pendingVerification"),
+                        str(issuer.get("entityId", "") or ""),
+                        json.dumps(mandate, ensure_ascii=True),
+                        json.dumps(validation, ensure_ascii=True),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchMandate(self, mandateId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_mandates WHERE mandate_id = %s", (mandateId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listMandates(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_mandates ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertEscrow(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        escrowId = str(record.get("escrowId", "") or "")
+        if not escrowId:
+            return
+        amount = record.get("amount", {}) if isinstance(record.get("amount"), dict) else {}
+        sql = (
+            "INSERT INTO picux_escrows "
+            "(escrow_id, status, mandate_id, task_id, amount, currency, pov_ref, receipt_id, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (escrow_id) DO UPDATE SET "
+            "status = EXCLUDED.status, mandate_id = EXCLUDED.mandate_id, task_id = EXCLUDED.task_id, "
+            "amount = EXCLUDED.amount, currency = EXCLUDED.currency, pov_ref = EXCLUDED.pov_ref, "
+            "receipt_id = EXCLUDED.receipt_id, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        escrowId,
+                        str(record.get("status", "pending") or "pending"),
+                        str(record.get("mandateId", "") or ""),
+                        str(record.get("taskId", "") or ""),
+                        self._amount(amount.get("amount", 0.0)),
+                        str(amount.get("currency", "USD") or "USD"),
+                        str(record.get("povRef", "") or ""),
+                        str(record.get("receiptId", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchEscrow(self, escrowId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_escrows WHERE escrow_id = %s", (escrowId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listEscrows(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_escrows ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertProxyMission(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        proxyId = str(record.get("proxyId", "") or "")
+        if not proxyId:
+            return
+        refs = record.get("refs", {}) if isinstance(record.get("refs"), dict) else {}
+        sql = (
+            "INSERT INTO picux_proxy_missions "
+            "(proxy_id, status, kind, task_id, user_id, resolve_id, refs, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (proxy_id) DO UPDATE SET "
+            "status = EXCLUDED.status, kind = EXCLUDED.kind, task_id = EXCLUDED.task_id, "
+            "user_id = EXCLUDED.user_id, resolve_id = EXCLUDED.resolve_id, refs = EXCLUDED.refs, "
+            "payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        proxyId,
+                        str(record.get("status", "awaitingProxy") or "awaitingProxy"),
+                        str(record.get("kind", "custom") or "custom"),
+                        str(record.get("taskId", "") or ""),
+                        str(record.get("userId", "") or ""),
+                        str(record.get("resolveId", "") or ""),
+                        json.dumps(refs, ensure_ascii=True),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchProxyMission(self, proxyId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_proxy_missions WHERE proxy_id = %s", (proxyId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def fetchProxyMissionByRef(self, refName: str, refValue: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        refName = str(refName or "")
+        refValue = str(refValue or "")
+        if refName not in {"requestId", "providerTaskId", "externalRef", "connectorRunId"} or not refValue:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_proxy_missions WHERE refs @> %s::jsonb ORDER BY created_at DESC LIMIT 1",
+                    (json.dumps({refName: refValue}, ensure_ascii=True),),
+                )
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listProxyMissions(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_proxy_missions ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def fetchTask(self, taskId: str) -> ProtocolTask | None:
+        if not self.enabled:
+            return None
+        sql = (
+            "SELECT task_id, user_id, domain, status, channel, mandate_id, "
+            "in_data::text, out_data::text, needs_approval, ext_ref, error_msg, meta::text, "
+            "EXTRACT(EPOCH FROM created_at)::bigint, EXTRACT(EPOCH FROM updated_at)::bigint, approval_by "
+            "FROM picux_tasks WHERE task_id = %s"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(sql, (taskId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return self._taskFromRow(row)
+
+    def listTasks(self, *, limit: int = 500) -> list[ProtocolTask]:
+        if not self.enabled:
+            return []
+        sql = (
+            "SELECT task_id, user_id, domain, status, channel, mandate_id, "
+            "in_data::text, out_data::text, needs_approval, ext_ref, error_msg, meta::text, "
+            "EXTRACT(EPOCH FROM created_at)::bigint, EXTRACT(EPOCH FROM updated_at)::bigint, approval_by "
+            "FROM picux_tasks ORDER BY created_at DESC LIMIT %s"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(sql, (max(1, min(int(limit or 500), 500)),))
+                rows = cur.fetchall()
+        tasks: list[ProtocolTask] = []
+        for row in rows:
+            tasks.append(self._taskFromRow(row))
+        return tasks
+
+    def durableWriteReadCheck(self, task: ProtocolTask) -> dict[str, Any]:
+        if not self.enabled:
+            return {"ok": False, "skipped": True, "reason": "postgresDisabled"}
+        self.upsertTask(task)
+        fetched = self.fetchTask(task.taskId)
+        return {
+            "ok": bool(fetched and fetched.taskId == task.taskId and fetched.domain == task.domain),
+            "skipped": False,
+            "taskId": task.taskId,
+        }
+
+    def insertActivity(self, *, taskId: str, userId: str, level: str, action: str, detail: str, meta: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        sql = (
+            "INSERT INTO picux_activity_logs (task_id, user_id, level, action, detail, meta) "
+            "VALUES (%s, %s, %s, %s, %s, %s::jsonb)"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(sql, (taskId, userId, level, action, detail, json.dumps(meta or {}, ensure_ascii=True)))
+
+    def insertEvent(self, *, userId: str, taskId: str, event: str, payload: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        sql = "INSERT INTO picux_activity_events (user_id, task_id, event, payload) VALUES (%s, %s, %s, %s::jsonb)"
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(sql, (userId, taskId, event, json.dumps(payload or {}, ensure_ascii=True)))
+
+    def upsertIntegrationEvent(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        eventId = str(record.get("eventId", "") or "")
+        if not eventId:
+            return
+        ackAt = int(record.get("ackAt", 0) or 0)
+        sql = (
+            "INSERT INTO picux_integration_events "
+            "(event_id, type, subject, source, target, status, payload, created_at, updated_at, ack_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s), "
+            "CASE WHEN %s > 0 THEN TO_TIMESTAMP(%s) ELSE NULL END) "
+            "ON CONFLICT (event_id) DO UPDATE SET "
+            "type = EXCLUDED.type, subject = EXCLUDED.subject, source = EXCLUDED.source, target = EXCLUDED.target, "
+            "status = EXCLUDED.status, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at, ack_at = EXCLUDED.ack_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        eventId,
+                        str(record.get("type", "") or ""),
+                        str(record.get("subject", "") or ""),
+                        str(record.get("source", "picux") or "picux"),
+                        str(record.get("target", "") or ""),
+                        str(record.get("status", "queued") or "queued"),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                        ackAt,
+                        ackAt,
+                    ),
+                )
+
+    def fetchIntegrationEvent(self, eventId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_integration_events WHERE event_id = %s", (eventId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listIntegrationEvents(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_integration_events ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertEventSubscription(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        subId = str(record.get("subId", "") or "")
+        if not subId:
+            return
+        eventTypes = record.get("eventTypes", []) if isinstance(record.get("eventTypes"), list) else []
+        sql = (
+            "INSERT INTO picux_event_subscriptions "
+            "(sub_id, client_id, target, transport, endpoint, status, event_types, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (sub_id) DO UPDATE SET "
+            "client_id = EXCLUDED.client_id, target = EXCLUDED.target, transport = EXCLUDED.transport, "
+            "endpoint = EXCLUDED.endpoint, status = EXCLUDED.status, event_types = EXCLUDED.event_types, "
+            "payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        subId,
+                        str(record.get("clientId", "") or ""),
+                        str(record.get("target", "") or ""),
+                        str(record.get("transport", "poll") or "poll"),
+                        str(record.get("endpoint", "") or ""),
+                        str(record.get("status", "active") or "active"),
+                        json.dumps(eventTypes, ensure_ascii=True),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchEventSubscription(self, subId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_event_subscriptions WHERE sub_id = %s", (subId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listEventSubscriptions(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_event_subscriptions ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertEventDelivery(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        deliveryId = str(record.get("deliveryId", "") or "")
+        if not deliveryId:
+            return
+        nextAttemptAt = int(record.get("nextAttemptAt", 0) or 0)
+        claimedAt = int(record.get("claimedAt", 0) or 0)
+        leaseExpiresAt = int(record.get("leaseExpiresAt", 0) or 0)
+        deliveredAt = int(record.get("deliveredAt", 0) or 0)
+        sql = (
+            "INSERT INTO picux_event_deliveries "
+            "(delivery_id, event_id, sub_id, client_id, transport, endpoint, status, attempt, payload, "
+            "created_at, updated_at, next_attempt_at, claimed_at, lease_expires_at, delivered_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s), "
+            "CASE WHEN %s > 0 THEN TO_TIMESTAMP(%s) ELSE NULL END, "
+            "CASE WHEN %s > 0 THEN TO_TIMESTAMP(%s) ELSE NULL END, "
+            "CASE WHEN %s > 0 THEN TO_TIMESTAMP(%s) ELSE NULL END, "
+            "CASE WHEN %s > 0 THEN TO_TIMESTAMP(%s) ELSE NULL END) "
+            "ON CONFLICT (delivery_id) DO UPDATE SET "
+            "event_id = EXCLUDED.event_id, sub_id = EXCLUDED.sub_id, client_id = EXCLUDED.client_id, "
+            "transport = EXCLUDED.transport, endpoint = EXCLUDED.endpoint, status = EXCLUDED.status, "
+            "attempt = EXCLUDED.attempt, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at, "
+            "next_attempt_at = EXCLUDED.next_attempt_at, claimed_at = EXCLUDED.claimed_at, "
+            "lease_expires_at = EXCLUDED.lease_expires_at, delivered_at = EXCLUDED.delivered_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        deliveryId,
+                        str(record.get("eventId", "") or ""),
+                        str(record.get("subId", "") or ""),
+                        str(record.get("clientId", "") or ""),
+                        str(record.get("transport", "poll") or "poll"),
+                        str(record.get("endpoint", "") or ""),
+                        str(record.get("status", "queued") or "queued"),
+                        int(record.get("attempt", 1) or 1),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                        nextAttemptAt,
+                        nextAttemptAt,
+                        claimedAt,
+                        claimedAt,
+                        leaseExpiresAt,
+                        leaseExpiresAt,
+                        deliveredAt,
+                        deliveredAt,
+                    ),
+                )
+
+    def fetchEventDelivery(self, deliveryId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_event_deliveries WHERE delivery_id = %s", (deliveryId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listEventDeliveries(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_event_deliveries ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertConnector(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        connectorId = str(record.get("connectorId", "") or "")
+        if not connectorId:
+            return
+        sql = (
+            "INSERT INTO picux_bridge_connectors "
+            "(connector_id, status, domain, kind, endpoint, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (connector_id) DO UPDATE SET "
+            "status = EXCLUDED.status, domain = EXCLUDED.domain, kind = EXCLUDED.kind, "
+            "endpoint = EXCLUDED.endpoint, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        connectorId,
+                        str(record.get("status", "active") or "active"),
+                        str(record.get("domain", "bridge") or "bridge"),
+                        str(record.get("kind", "api") or "api"),
+                        str(record.get("endpoint", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchConnector(self, connectorId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_bridge_connectors", "connector_id", connectorId)
+
+    def listConnectors(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_bridge_connectors", "created_at", limit=limit)
+
+    def upsertConnectionSession(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        sessionId = str(record.get("sessionId", "") or "")
+        if not sessionId:
+            return
+        sql = (
+            "INSERT INTO picux_bridge_connection_sessions "
+            "(session_id, connector_id, status, subject_id, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (session_id) DO UPDATE SET "
+            "connector_id = EXCLUDED.connector_id, status = EXCLUDED.status, subject_id = EXCLUDED.subject_id, "
+            "payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        sessionId,
+                        str(record.get("connectorId", "") or ""),
+                        str(record.get("status", "active") or "active"),
+                        str(record.get("subjectId", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchConnectionSession(self, sessionId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_bridge_connection_sessions", "session_id", sessionId)
+
+    def listConnectionSessions(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_bridge_connection_sessions", "created_at", limit=limit)
+
+    def upsertChannelThread(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        threadId = str(record.get("threadId", "") or "")
+        if not threadId:
+            return
+        sql = (
+            "INSERT INTO picux_channel_threads "
+            "(thread_id, case_id, conversation_id, channel, provider, provider_thread_id, connector_id, session_id, status, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (thread_id) DO UPDATE SET "
+            "case_id = EXCLUDED.case_id, conversation_id = EXCLUDED.conversation_id, channel = EXCLUDED.channel, "
+            "provider = EXCLUDED.provider, provider_thread_id = EXCLUDED.provider_thread_id, connector_id = EXCLUDED.connector_id, "
+            "session_id = EXCLUDED.session_id, status = EXCLUDED.status, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        threadId,
+                        str(record.get("caseId", "") or ""),
+                        str(record.get("conversationId", "") or ""),
+                        str(record.get("channel", "api") or "api"),
+                        str(record.get("provider", "") or ""),
+                        str(record.get("providerThreadId", "") or ""),
+                        str(record.get("connectorId", "") or ""),
+                        str(record.get("sessionId", "") or ""),
+                        str(record.get("status", "active") or "active"),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchChannelThread(self, threadId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_channel_threads", "thread_id", threadId)
+
+    def findChannelThread(self, refs: dict[str, Any]) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        providerThreadId = str(refs.get("providerThreadId", "") or "")
+        conversationId = str(refs.get("conversationId", "") or "")
+        caseId = str(refs.get("caseId", "") or "")
+        channel = str(refs.get("channel", "") or "")
+        provider = str(refs.get("provider", "") or "")
+        where = []
+        params: list[Any] = []
+        if providerThreadId:
+            where.append("provider_thread_id = %s")
+            params.append(providerThreadId)
+        elif conversationId:
+            where.append("conversation_id = %s")
+            params.append(conversationId)
+            if channel:
+                where.append("channel = %s")
+                params.append(channel)
+            if provider:
+                where.append("provider = %s")
+                params.append(provider)
+        elif caseId and channel:
+            where.extend(["case_id = %s", "channel = %s"])
+            params.extend([caseId, channel])
+        if not where:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    f"SELECT payload::text FROM picux_channel_threads WHERE {' AND '.join(where)} ORDER BY updated_at DESC LIMIT 1",
+                    tuple(params),
+                )
+                row = cur.fetchone()
+        return json.loads(row[0] or "{}") if row else None
+
+    def listChannelThreads(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_channel_threads", "updated_at", limit=limit)
+
+    def upsertTouchpoint(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        touchpointId = str(record.get("touchpointId", "") or "")
+        if not touchpointId:
+            return
+        sql = (
+            "INSERT INTO picux_touchpoints "
+            "(touchpoint_id, thread_id, case_id, conversation_id, channel, provider, connector_id, direction, status, payload, created_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (touchpoint_id) DO UPDATE SET "
+            "thread_id = EXCLUDED.thread_id, case_id = EXCLUDED.case_id, conversation_id = EXCLUDED.conversation_id, "
+            "channel = EXCLUDED.channel, provider = EXCLUDED.provider, connector_id = EXCLUDED.connector_id, "
+            "direction = EXCLUDED.direction, status = EXCLUDED.status, payload = EXCLUDED.payload"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        touchpointId,
+                        str(record.get("threadId", "") or ""),
+                        str(record.get("caseId", "") or ""),
+                        str(record.get("conversationId", "") or ""),
+                        str(record.get("channel", "api") or "api"),
+                        str(record.get("provider", "") or ""),
+                        str(record.get("connectorId", "") or ""),
+                        str(record.get("direction", "inbound") or "inbound"),
+                        str(record.get("status", "received") or "received"),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                    ),
+                )
+
+    def fetchTouchpoint(self, touchpointId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_touchpoints", "touchpoint_id", touchpointId)
+
+    def listTouchpoints(self, *, threadId: str = "", caseId: str = "", conversationId: str = "", limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        where = []
+        params: list[Any] = []
+        for value, column in ((threadId, "thread_id"), (caseId, "case_id"), (conversationId, "conversation_id")):
+            clean = str(value or "")
+            if clean:
+                where.append(f"{column} = %s")
+                params.append(clean)
+        whereSql = f"WHERE {' AND '.join(where)} " if where else ""
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    f"SELECT payload::text FROM picux_touchpoints {whereSql}ORDER BY created_at DESC LIMIT %s",
+                    (*params, max(1, min(int(limit or 500), 500))),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertProviderAction(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        actionId = str(record.get("actionId", "") or "")
+        if not actionId:
+            return
+        sql = (
+            "INSERT INTO picux_provider_actions "
+            "(action_id, case_id, conversation_id, thread_id, connector_id, session_id, status, action, resource, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (action_id) DO UPDATE SET "
+            "case_id = EXCLUDED.case_id, conversation_id = EXCLUDED.conversation_id, thread_id = EXCLUDED.thread_id, "
+            "connector_id = EXCLUDED.connector_id, session_id = EXCLUDED.session_id, status = EXCLUDED.status, "
+            "action = EXCLUDED.action, resource = EXCLUDED.resource, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        actionId,
+                        str(record.get("caseId", "") or ""),
+                        str(record.get("conversationId", "") or ""),
+                        str(record.get("threadId", "") or ""),
+                        str(record.get("connectorId", "") or ""),
+                        str(record.get("sessionId", "") or ""),
+                        str(record.get("status", "queued") or "queued"),
+                        str(record.get("action", "") or ""),
+                        str(record.get("resource", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchProviderAction(self, actionId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_provider_actions", "action_id", actionId)
+
+    def listProviderActions(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_provider_actions", "updated_at", limit=limit)
+
+    def upsertProviderCallback(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        callbackId = str(record.get("callbackId", "") or "")
+        if not callbackId:
+            return
+        sql = (
+            "INSERT INTO picux_provider_callbacks "
+            "(callback_id, case_id, conversation_id, thread_id, connector_id, session_id, provider, provider_event_id, status, payload, received_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (callback_id) DO UPDATE SET "
+            "case_id = EXCLUDED.case_id, conversation_id = EXCLUDED.conversation_id, thread_id = EXCLUDED.thread_id, "
+            "connector_id = EXCLUDED.connector_id, session_id = EXCLUDED.session_id, provider = EXCLUDED.provider, "
+            "provider_event_id = EXCLUDED.provider_event_id, status = EXCLUDED.status, payload = EXCLUDED.payload"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        callbackId,
+                        str(record.get("caseId", "") or ""),
+                        str(record.get("conversationId", "") or ""),
+                        str(record.get("threadId", "") or ""),
+                        str(record.get("connectorId", "") or ""),
+                        str(record.get("sessionId", "") or ""),
+                        str(record.get("provider", "") or ""),
+                        str(record.get("providerEventId", "") or ""),
+                        str(record.get("status", "received") or "received"),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("receivedAt", 0) or 0),
+                    ),
+                )
+
+    def listProviderCallbacks(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_provider_callbacks", "received_at", limit=limit)
+
+    def upsertCaseWorkspace(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        caseId = str(record.get("caseId", "") or "")
+        if not caseId:
+            return
+        sql = (
+            "INSERT INTO picux_case_workspaces "
+            "(case_id, status, owner_id, conversation_id, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (case_id) DO UPDATE SET "
+            "status = EXCLUDED.status, owner_id = EXCLUDED.owner_id, conversation_id = EXCLUDED.conversation_id, "
+            "payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        caseId,
+                        str(record.get("status", "open") or "open"),
+                        str(record.get("ownerId", "") or ""),
+                        str(record.get("conversationId", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchCaseWorkspace(self, caseId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_case_workspaces", "case_id", caseId)
+
+    def listCaseWorkspaces(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_case_workspaces", "updated_at", limit=limit)
+
+    def upsertCaseEvent(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        eventId = str(record.get("eventId", "") or "")
+        if not eventId:
+            return
+        sql = (
+            "INSERT INTO picux_case_events "
+            "(event_id, case_id, type, actor, status, payload, created_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (event_id) DO UPDATE SET "
+            "case_id = EXCLUDED.case_id, type = EXCLUDED.type, actor = EXCLUDED.actor, "
+            "status = EXCLUDED.status, payload = EXCLUDED.payload"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        eventId,
+                        str(record.get("caseId", "") or ""),
+                        str(record.get("type", "") or ""),
+                        str(record.get("actor", "") or ""),
+                        str(record.get("status", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                    ),
+                )
+
+    def listCaseEvents(self, *, caseId: str = "", limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        params: list[Any] = []
+        where = ""
+        if caseId:
+            where = "WHERE case_id = %s "
+            params.append(str(caseId))
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    f"SELECT payload::text FROM picux_case_events {where}ORDER BY created_at ASC LIMIT %s",
+                    (*params, max(1, min(int(limit or 500), 500))),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertPortalSession(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        sessionId = str(record.get("portalSessionId", "") or "")
+        if not sessionId:
+            return
+        sql = (
+            "INSERT INTO picux_portal_sessions "
+            "(portal_session_id, case_id, conversation_id, connector_id, provider, status, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (portal_session_id) DO UPDATE SET "
+            "case_id = EXCLUDED.case_id, conversation_id = EXCLUDED.conversation_id, connector_id = EXCLUDED.connector_id, "
+            "provider = EXCLUDED.provider, status = EXCLUDED.status, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        sessionId,
+                        str(record.get("caseId", "") or ""),
+                        str(record.get("conversationId", "") or ""),
+                        str(record.get("connectorId", "") or ""),
+                        str(record.get("provider", "") or ""),
+                        str(record.get("status", "active") or "active"),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchPortalSession(self, sessionId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_portal_sessions", "portal_session_id", sessionId)
+
+    def listPortalSessions(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_portal_sessions", "updated_at", limit=limit)
+
+    def upsertPortalAction(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        actionId = str(record.get("portalActionId", "") or "")
+        if not actionId:
+            return
+        sql = (
+            "INSERT INTO picux_portal_actions "
+            "(portal_action_id, portal_session_id, case_id, conversation_id, connector_id, provider, status, kind, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (portal_action_id) DO UPDATE SET "
+            "portal_session_id = EXCLUDED.portal_session_id, case_id = EXCLUDED.case_id, conversation_id = EXCLUDED.conversation_id, "
+            "connector_id = EXCLUDED.connector_id, provider = EXCLUDED.provider, status = EXCLUDED.status, kind = EXCLUDED.kind, "
+            "payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        actionId,
+                        str(record.get("portalSessionId", "") or ""),
+                        str(record.get("caseId", "") or ""),
+                        str(record.get("conversationId", "") or ""),
+                        str(record.get("connectorId", "") or ""),
+                        str(record.get("provider", "") or ""),
+                        str(record.get("status", "queued") or "queued"),
+                        str(record.get("kind", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchPortalAction(self, actionId: str) -> dict[str, Any] | None:
+        return self._fetchJsonPayload("picux_portal_actions", "portal_action_id", actionId)
+
+    def listPortalActions(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        return self._listJsonPayloads("picux_portal_actions", "updated_at", limit=limit)
+
+    def claimEventDelivery(self, filters: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        filters = filters or {}
+        where = [
+            "((status = %s AND (next_attempt_at IS NULL OR next_attempt_at <= NOW())) "
+            "OR (status = %s AND lease_expires_at IS NOT NULL AND lease_expires_at <= NOW()))"
+        ]
+        params: list[Any] = ["queued", "claimed"]
+        for field, column in (
+            ("eventId", "event_id"),
+            ("subId", "sub_id"),
+            ("clientId", "client_id"),
+            ("transport", "transport"),
+        ):
+            value = str(filters.get(field, "") or "")
+            if value:
+                where.append(f"{column} = %s")
+                params.append(value)
+        whereSql = " AND ".join(where)
+        claimedBy = str(filters.get("claimedBy", filters.get("workerId", "")) or "")
+        now = int(datetime.now(tz=timezone.utc).timestamp())
+        leaseExpiresAt = now + self._leaseSeconds(filters.get("leaseSeconds", 300))
+        explicitLease = int(filters.get("leaseExpiresAt", 0) or 0)
+        if explicitLease:
+            leaseExpiresAt = explicitLease
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    f"SELECT payload::text FROM picux_event_deliveries WHERE {whereSql} "
+                    "ORDER BY created_at ASC, delivery_id ASC LIMIT 1 FOR UPDATE SKIP LOCKED",
+                    tuple(params),
+                )
+                row = cur.fetchone()
+                if not row:
+                    return None
+                record = json.loads(row[0] or "{}")
+                record["status"] = "claimed"
+                record["claimedBy"] = claimedBy
+                record["claimedAt"] = now
+                record["leaseExpiresAt"] = leaseExpiresAt
+                record["nextAttemptAt"] = 0
+                record["updatedAt"] = now
+                cur.execute(
+                    "UPDATE picux_event_deliveries SET status = %s, payload = %s::jsonb, "
+                    "updated_at = TO_TIMESTAMP(%s), claimed_at = TO_TIMESTAMP(%s), "
+                    "lease_expires_at = TO_TIMESTAMP(%s), next_attempt_at = NULL WHERE delivery_id = %s",
+                    (
+                        "claimed",
+                        json.dumps(record, ensure_ascii=True),
+                        now,
+                        now,
+                        leaseExpiresAt,
+                        str(record.get("deliveryId", "") or ""),
+                    ),
+                )
+        return record
+
+    def sweepEventDeliveryLeases(self, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        filters = filters or {}
+        where = ["status = %s", "lease_expires_at IS NOT NULL", "lease_expires_at <= NOW()"]
+        params: list[Any] = ["claimed"]
+        for field, column in (
+            ("eventId", "event_id"),
+            ("subId", "sub_id"),
+            ("clientId", "client_id"),
+            ("transport", "transport"),
+        ):
+            value = str(filters.get(field, "") or "")
+            if value:
+                where.append(f"{column} = %s")
+                params.append(value)
+        whereSql = " AND ".join(where)
+        limit = max(1, min(int(filters.get("limit", 100) or 100), 500))
+        lastError = str(filters.get("lastError", "") or "")
+        now = int(datetime.now(tz=timezone.utc).timestamp())
+        swept: list[dict[str, Any]] = []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    f"SELECT payload::text FROM picux_event_deliveries WHERE {whereSql} "
+                    "ORDER BY lease_expires_at ASC, delivery_id ASC LIMIT %s FOR UPDATE SKIP LOCKED",
+                    tuple(params + [limit]),
+                )
+                rows = cur.fetchall()
+                for row in rows:
+                    record = json.loads(row[0] or "{}")
+                    record["status"] = "queued"
+                    record["claimedBy"] = ""
+                    record["claimedAt"] = 0
+                    record["leaseExpiresAt"] = 0
+                    record["updatedAt"] = now
+                    if lastError:
+                        record["lastError"] = lastError
+                    cur.execute(
+                        "UPDATE picux_event_deliveries SET status = %s, payload = %s::jsonb, "
+                        "updated_at = TO_TIMESTAMP(%s), claimed_at = NULL, lease_expires_at = NULL "
+                        "WHERE delivery_id = %s",
+                        (
+                            "queued",
+                            json.dumps(record, ensure_ascii=True),
+                            now,
+                            str(record.get("deliveryId", "") or ""),
+                        ),
+                    )
+                    swept.append(record)
+        return swept
+
+    def insertEvidence(self, artifact: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        artifactId = str(artifact.get("artifactId", "") or "")
+        if not artifactId:
+            return
+        sql = (
+            "INSERT INTO picux_evidence_artifacts (artifact_id, kind, source, payload_hash, payload, created_at) "
+            "VALUES (%s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (artifact_id) DO UPDATE SET "
+            "kind = EXCLUDED.kind, source = EXCLUDED.source, payload_hash = EXCLUDED.payload_hash, "
+            "payload = EXCLUDED.payload"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        artifactId,
+                        str(artifact.get("kind", "") or ""),
+                        str(artifact.get("source", "") or ""),
+                        str(artifact.get("payloadHash", "") or ""),
+                        json.dumps(artifact or {}, ensure_ascii=True),
+                        self._epoch(artifact.get("createdAt", "")),
+                    ),
+                )
+
+    def fetchEvidence(self, artifactId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_evidence_artifacts WHERE artifact_id = %s", (artifactId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listEvidence(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_evidence_artifacts ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def upsertSignal(self, record: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        signalId = str(record.get("signalId", "") or "")
+        if not signalId:
+            return
+        sql = (
+            "INSERT INTO picux_community_signals "
+            "(signal_id, entity, confidence, source_platform, query, payload, created_at, updated_at) "
+            "VALUES (%s, %s, %s, %s, %s, %s::jsonb, TO_TIMESTAMP(%s), TO_TIMESTAMP(%s)) "
+            "ON CONFLICT (signal_id) DO UPDATE SET "
+            "entity = EXCLUDED.entity, confidence = EXCLUDED.confidence, source_platform = EXCLUDED.source_platform, "
+            "query = EXCLUDED.query, payload = EXCLUDED.payload, updated_at = EXCLUDED.updated_at"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        signalId,
+                        str(record.get("entity", "unknown") or "unknown"),
+                        self._confidence(record.get("confidence", 0.0)),
+                        str(record.get("sourcePlatform", "") or ""),
+                        str(record.get("query", "") or ""),
+                        json.dumps(record or {}, ensure_ascii=True),
+                        int(record.get("createdAt", 0) or 0),
+                        int(record.get("updatedAt", 0) or 0),
+                    ),
+                )
+
+    def fetchSignal(self, signalId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_community_signals WHERE signal_id = %s", (signalId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listSignals(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_community_signals ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def insertReceipt(self, receipt: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        receiptId = str(receipt.get("receiptId", "") or "")
+        if not receiptId:
+            return
+        sql = (
+            "INSERT INTO picux_receipts (receipt_id, task_id, mandate_id, status, payload) "
+            "VALUES (%s, %s, %s, %s, %s::jsonb) "
+            "ON CONFLICT (receipt_id) DO UPDATE SET "
+            "task_id = EXCLUDED.task_id, mandate_id = EXCLUDED.mandate_id, "
+            "status = EXCLUDED.status, payload = EXCLUDED.payload"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        receiptId,
+                        str(receipt.get("taskId", "") or ""),
+                        str(receipt.get("mandateId", "") or ""),
+                        str(receipt.get("status", "") or ""),
+                        json.dumps(receipt or {}, ensure_ascii=True),
+                    ),
+                )
+
+    def fetchReceipt(self, receiptId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_receipts WHERE receipt_id = %s", (receiptId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listReceipts(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_receipts ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def insertPov(self, pov: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        povId = str(pov.get("povId", "") or "")
+        if not povId:
+            return
+        value = pov.get("value", {}) if isinstance(pov.get("value"), dict) else {}
+        meta = pov.get("meta", {}) if isinstance(pov.get("meta"), dict) else {}
+        sql = (
+            "INSERT INTO picux_pov_events "
+            "(event_id, user_id, task_id, domain, value_amount, currency, summary, payload) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s::jsonb) "
+            "ON CONFLICT (event_id) DO UPDATE SET "
+            "task_id = EXCLUDED.task_id, domain = EXCLUDED.domain, value_amount = EXCLUDED.value_amount, "
+            "currency = EXCLUDED.currency, summary = EXCLUDED.summary, payload = EXCLUDED.payload"
+        )
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    sql,
+                    (
+                        povId,
+                        str(pov.get("userId", meta.get("userId", "")) or ""),
+                        str(pov.get("taskId", "") or ""),
+                        str(pov.get("domain", "") or ""),
+                        self._amount(value.get("amount", 0.0)),
+                        str(value.get("currency", "USD") or "USD"),
+                        str(meta.get("summary", "") or ""),
+                        json.dumps(pov or {}, ensure_ascii=True),
+                    ),
+                )
+
+    def fetchPov(self, povId: str) -> dict[str, Any] | None:
+        if not self.enabled:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute("SELECT payload::text FROM picux_pov_events WHERE event_id = %s", (povId,))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def listPov(self, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    "SELECT payload::text FROM picux_pov_events ORDER BY created_at DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    def _fetchJsonPayload(self, table: str, column: str, value: str) -> dict[str, Any] | None:
+        if not self.enabled or not value:
+            return None
+        allowedTables = {
+            "picux_bridge_connectors",
+            "picux_bridge_connection_sessions",
+            "picux_channel_threads",
+            "picux_touchpoints",
+            "picux_provider_actions",
+            "picux_case_workspaces",
+            "picux_portal_sessions",
+            "picux_portal_actions",
+        }
+        allowedColumns = {"connector_id", "session_id", "thread_id", "touchpoint_id", "action_id", "case_id", "portal_session_id", "portal_action_id"}
+        if table not in allowedTables or column not in allowedColumns:
+            return None
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(f"SELECT payload::text FROM {table} WHERE {column} = %s", (str(value),))
+                row = cur.fetchone()
+        if not row:
+            return None
+        return json.loads(row[0] or "{}")
+
+    def _listJsonPayloads(self, table: str, orderColumn: str, *, limit: int = 500) -> list[dict[str, Any]]:
+        if not self.enabled:
+            return []
+        allowedTables = {
+            "picux_bridge_connectors",
+            "picux_bridge_connection_sessions",
+            "picux_channel_threads",
+            "picux_provider_actions",
+            "picux_provider_callbacks",
+            "picux_case_workspaces",
+            "picux_portal_sessions",
+            "picux_portal_actions",
+        }
+        allowedOrder = {"created_at", "updated_at", "received_at"}
+        if table not in allowedTables or orderColumn not in allowedOrder:
+            return []
+        with self.conn() as db:
+            with db.cursor() as cur:
+                cur.execute(
+                    f"SELECT payload::text FROM {table} ORDER BY {orderColumn} DESC LIMIT %s",
+                    (max(1, min(int(limit or 500), 500)),),
+                )
+                rows = cur.fetchall()
+        return [json.loads(row[0] or "{}") for row in rows]
+
+    @staticmethod
+    def _amount(value: Any) -> float:
+        try:
+            return float(value or 0.0)
+        except (TypeError, ValueError):
+            return 0.0
+
+    @staticmethod
+    def _confidence(value: Any) -> float:
+        try:
+            parsed = float(value or 0.0)
+        except (TypeError, ValueError):
+            return 0.0
+        return max(0.0, min(parsed, 1.0))
+
+    @staticmethod
+    def _epoch(value: Any) -> int:
+        if isinstance(value, (int, float)):
+            return int(value or 0)
+        raw = str(value or "").strip()
+        if raw.endswith("Z"):
+            raw = raw[:-1] + "+00:00"
+        try:
+            parsed = datetime.fromisoformat(raw)
+        except Exception:
+            return 0
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return int(parsed.timestamp())
+
+    @staticmethod
+    def _taskFromRow(row: tuple[Any, ...]) -> ProtocolTask:
+        domain = str(row[2])
+        status = str(row[3])
+        if len(row) >= 15:
+            needsApproval = bool(row[8])
+            extRef = str(row[9] or "")
+            errorMsg = str(row[10] or "")
+            meta = json.loads(row[11] or "{}")
+            createdAt = int(row[12] or 0)
+            updatedAt = int(row[13] or 0)
+            approvalBy = int(row[14]) if row[14] else None
+        else:
+            needsApproval = False
+            extRef = ""
+            errorMsg = ""
+            meta = json.loads(row[8] if isinstance(row[8], str) and row[8] else "{}")
+            createdAt = PicuxPostgresStore._int(row[9])
+            updatedAt = PicuxPostgresStore._int(row[10])
+            approvalBy = None
+        return ProtocolTask(
+            taskId=str(row[0]),
+            userId=str(row[1]),
+            domain=Domain(domain) if domain in Domain._value2member_map_ else Domain.UNKNOWN,
+            status=ProtocolTaskStatus(status)
+            if status in ProtocolTaskStatus._value2member_map_
+            else ProtocolTaskStatus.PENDING,
+            channel=str(row[4]),
+            mandateId=str(row[5]),
+            inData=json.loads(row[6] or "{}"),
+            outData=json.loads(row[7] or "{}"),
+            needsApproval=needsApproval,
+            extRef=extRef,
+            errorMsg=errorMsg,
+            meta=meta,
+            createdAt=createdAt,
+            updatedAt=updatedAt,
+            approvalBy=approvalBy,
+        )
+
+    @staticmethod
+    def _int(value: Any) -> int:
+        try:
+            return int(value or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    @staticmethod
+    def _leaseSeconds(value: Any) -> int:
+        try:
+            parsed = int(value)
+        except (TypeError, ValueError):
+            return 300
+        return max(1, min(parsed, 86400))