patchr 0.1.0__py3-none-any.whl

picux/storage/events.py

@@ -0,0 +1,989 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import time
+from typing import Any
+
+
+EVENT_STATUSES = {"queued", "acked", "failed", "canceled"}
+SUBSCRIPTION_STATUSES = {"active", "paused", "disabled"}
+SUBSCRIPTION_TRANSPORTS = {"poll", "webhook", "a2a", "mcp"}
+DELIVERY_STATUSES = {"queued", "claimed", "delivered", "failed", "canceled"}
+
+
+class EventBook:
+    """External integration event outbox with optional durable backing."""
+
+    def __init__(
+        self,
+        *,
+        backing: Any | None = None,
+        subscriptionBook: "EventSubscriptionBook | None" = None,
+        deliveryBook: "EventDeliveryBook | None" = None,
+    ) -> None:
+        self.backing = backing
+        self.subscriptionBook = subscriptionBook
+        self.deliveryBook = deliveryBook
+        self._records: dict[str, dict[str, Any]] = {}
+
+    def recordEvent(self, payload: dict[str, Any]) -> dict[str, Any]:
+        eventType = str(payload.get("type", payload.get("event", "")) or "").strip()
+        if not eventType:
+            return {"ok": False, "error": "missing:type"}
+        now = int(payload.get("createdAt", 0) or time.time())
+        eventId = str(payload.get("eventId", "") or _stableId(eventType, payload, now))
+        current = self.getEvent(eventId)
+        createdAt = current.get("event", {}).get("createdAt", now) if current.get("ok") else now
+        event = {
+            "type": eventType,
+            "subject": str(payload.get("subject", "") or ""),
+            "source": str(payload.get("source", "picux") or "picux"),
+            "target": str(payload.get("target", "") or ""),
+            "payload": payload.get("payload", {}) if isinstance(payload.get("payload"), dict) else {},
+        }
+        subscriptions = self._matchedSubscriptionRecords(event)
+        record = {
+            "eventId": eventId,
+            "type": eventType,
+            "subject": event["subject"],
+            "source": event["source"],
+            "target": event["target"],
+            "status": _status(payload.get("status", "queued")),
+            "payload": copy.deepcopy(payload.get("payload", {}) if isinstance(payload.get("payload"), dict) else {}),
+            "subscriptions": [str(record.get("subId", "") or "") for record in subscriptions if record.get("subId")],
+            "ack": copy.deepcopy(payload.get("ack", {}) if isinstance(payload.get("ack"), dict) else {}),
+            "createdAt": int(createdAt or now),
+            "updatedAt": int(payload.get("updatedAt", now) or now),
+            "ackAt": int(payload.get("ackAt", 0) or 0),
+        }
+        self._saveRecord(record)
+        deliveries = self._recordDeliveries(record, subscriptions)
+        result = {"ok": True, "event": copy.deepcopy(record)}
+        if deliveries:
+            result["deliveries"] = deliveries
+        return result
+
+    def getEvent(self, eventId: str) -> dict[str, Any]:
+        eventId = str(eventId or "")
+        record = self._records.get(eventId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchIntegrationEvent"):
+            record = self.backing.fetchIntegrationEvent(eventId)
+            if record:
+                self._records[eventId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "eventNotFound", "eventId": eventId}
+        return {"ok": True, "event": copy.deepcopy(record)}
+
+    def listEvents(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        eventType = str(filters.get("type", filters.get("event", "")) or "")
+        source = str(filters.get("source", "") or "")
+        target = str(filters.get("target", "") or "")
+        subject = str(filters.get("subject", "") or "")
+        status = str(filters.get("status", "") or "")
+        records = list(self._records.values())
+        if eventType:
+            records = [record for record in records if record.get("type") == eventType]
+        if source:
+            records = [record for record in records if record.get("source") == source]
+        if target:
+            records = [record for record in records if record.get("target") == target]
+        if subject:
+            records = [record for record in records if record.get("subject") == subject]
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("eventId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "events": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def ackEvent(self, eventId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getEvent(eventId)
+        if not current.get("ok"):
+            return current
+        now = int(time.time())
+        payload = payload or {}
+        record = current["event"]
+        ack = payload.get("ack", payload) if isinstance(payload.get("ack", payload), dict) else {}
+        merged = {
+            **record,
+            "status": "acked",
+            "ack": copy.deepcopy(ack),
+            "ackAt": int(payload.get("ackAt", now) or now),
+            "updatedAt": int(payload.get("updatedAt", now) or now),
+        }
+        self._saveRecord(merged)
+        return {"ok": True, "event": copy.deepcopy(merged)}
+
+    def _saveRecord(self, record: dict[str, Any]) -> None:
+        eventId = str(record.get("eventId", "") or "")
+        if not eventId:
+            return
+        self._records[eventId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertIntegrationEvent"):
+            self.backing.upsertIntegrationEvent(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listIntegrationEvents"):
+            return
+        for record in self.backing.listIntegrationEvents():
+            eventId = str(record.get("eventId", "") or "")
+            if eventId:
+                self._records[eventId] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+    def _matchedSubscriptionRecords(self, event: dict[str, Any]) -> list[dict[str, Any]]:
+        if self.subscriptionBook is None:
+            return []
+        result = self.subscriptionBook.matchEvent(event)
+        if not result.get("ok"):
+            return []
+        return [
+            copy.deepcopy(record)
+            for record in result.get("subscriptions", [])
+            if isinstance(record, dict) and record.get("subId")
+        ]
+
+    def _recordDeliveries(self, event: dict[str, Any], subscriptions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        if self.deliveryBook is None:
+            return []
+        deliveries: list[dict[str, Any]] = []
+        for subscription in subscriptions:
+            result = self.deliveryBook.createForEvent(event, subscription)
+            if result.get("ok") and isinstance(result.get("delivery"), dict):
+                deliveries.append(copy.deepcopy(result["delivery"]))
+        return deliveries
+
+
+class EventSubscriptionBook:
+    """Event interest registry for external apps, services, and agents."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+
+    def createSubscription(self, payload: dict[str, Any]) -> dict[str, Any]:
+        clientId = str(payload.get("clientId", payload.get("target", "")) or "").strip()
+        eventTypes = _cleanList(payload.get("eventTypes", payload.get("types", [])))
+        errors = _subscriptionErrors(clientId=clientId, eventTypes=eventTypes, payload=payload)
+        subId = str(payload.get("subId", "") or _subscriptionId(clientId, eventTypes, payload))
+        record = self._record(payload, subId=subId, clientId=clientId, eventTypes=eventTypes)
+        if errors:
+            return {"ok": False, "errors": errors, "subscription": record}
+        self._saveRecord(record)
+        return {"ok": True, "subscription": copy.deepcopy(record)}
+
+    def getSubscription(self, subId: str) -> dict[str, Any]:
+        subId = str(subId or "")
+        record = self._records.get(subId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchEventSubscription"):
+            record = self.backing.fetchEventSubscription(subId)
+            if record:
+                self._records[subId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "subscriptionNotFound", "subId": subId}
+        return {"ok": True, "subscription": copy.deepcopy(record)}
+
+    def listSubscriptions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        clientId = str(filters.get("clientId", "") or "")
+        eventType = str(filters.get("eventType", filters.get("type", "")) or "")
+        status = str(filters.get("status", "") or "")
+        transport = str(filters.get("transport", "") or "")
+        records = list(self._records.values())
+        if clientId:
+            records = [record for record in records if record.get("clientId") == clientId]
+        if eventType:
+            records = [record for record in records if eventType in record.get("eventTypes", []) or "*" in record.get("eventTypes", [])]
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        if transport:
+            records = [record for record in records if record.get("transport") == transport]
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("subId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "subscriptions": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def updateSubscription(self, subId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getSubscription(subId)
+        if not current.get("ok"):
+            return current
+        record = current["subscription"]
+        eventTypes = _cleanList(updates.get("eventTypes", updates.get("types", record.get("eventTypes", []))))
+        merged = self._record(
+            {**record, **updates},
+            subId=subId,
+            clientId=str(updates.get("clientId", record.get("clientId", "")) or ""),
+            eventTypes=eventTypes,
+            createdAt=int(record.get("createdAt", 0) or 0),
+        )
+        errors = _subscriptionErrors(clientId=merged["clientId"], eventTypes=eventTypes, payload=merged)
+        if errors:
+            return {"ok": False, "errors": errors, "subscription": merged}
+        self._saveRecord(merged)
+        return {"ok": True, "subscription": copy.deepcopy(merged)}
+
+    def matchEvent(self, event: dict[str, Any]) -> dict[str, Any]:
+        self._loadBacking()
+        eventType = str(event.get("type", event.get("event", "")) or "")
+        target = str(event.get("target", "") or "")
+        source = str(event.get("source", "") or "")
+        subject = str(event.get("subject", "") or "")
+        matches: list[dict[str, Any]] = []
+        for record in self._records.values():
+            filters = record.get("filters", {}) if isinstance(record.get("filters"), dict) else {}
+            if record.get("status") != "active":
+                continue
+            if eventType not in record.get("eventTypes", []) and "*" not in record.get("eventTypes", []):
+                continue
+            if record.get("target") and record.get("target") != target:
+                continue
+            if filters.get("source") and filters.get("source") != source:
+                continue
+            if filters.get("subject") and filters.get("subject") != subject:
+                continue
+            matches.append(copy.deepcopy(record))
+        matches.sort(key=lambda item: str(item.get("subId", "")))
+        return {"ok": True, "subscriptions": matches, "count": len(matches)}
+
+    def _record(
+        self,
+        payload: dict[str, Any],
+        *,
+        subId: str,
+        clientId: str,
+        eventTypes: list[str],
+        createdAt: int | None = None,
+    ) -> dict[str, Any]:
+        now = int(time.time())
+        return {
+            "subId": subId,
+            "clientId": clientId,
+            "eventTypes": eventTypes,
+            "target": str(payload.get("target", clientId) or ""),
+            "transport": _transport(payload.get("transport", "poll")),
+            "endpoint": str(payload.get("endpoint", "") or ""),
+            "status": _subStatus(payload.get("status", "active")),
+            "filters": copy.deepcopy(payload.get("filters", {}) if isinstance(payload.get("filters"), dict) else {}),
+            "meta": copy.deepcopy(payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {}),
+            "createdAt": int(createdAt or payload.get("createdAt", now) or now),
+            "updatedAt": int(payload.get("updatedAt", now) or now),
+        }
+
+    def _saveRecord(self, record: dict[str, Any]) -> None:
+        subId = str(record.get("subId", "") or "")
+        if not subId:
+            return
+        self._records[subId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertEventSubscription"):
+            self.backing.upsertEventSubscription(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listEventSubscriptions"):
+            return
+        for record in self.backing.listEventSubscriptions():
+            subId = str(record.get("subId", "") or "")
+            if subId:
+                self._records[subId] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+class EventDeliveryBook:
+    """Delivery attempt ledger for matched event subscriptions."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+
+    def createForEvent(self, event: dict[str, Any], subscription: dict[str, Any]) -> dict[str, Any]:
+        eventId = str(event.get("eventId", "") or "")
+        subId = str(subscription.get("subId", "") or "")
+        if eventId and subId:
+            current = self.getDelivery(_deliveryId(eventId, subId, 1))
+            if current.get("ok"):
+                return current
+        return self.createDelivery(
+            {
+                "eventId": eventId,
+                "subId": subId,
+                "clientId": subscription.get("clientId", ""),
+                "transport": subscription.get("transport", "poll"),
+                "endpoint": subscription.get("endpoint", ""),
+                "meta": {
+                    "eventType": event.get("type", ""),
+                    "subject": event.get("subject", ""),
+                    "target": event.get("target", ""),
+                },
+            }
+        )
+
+    def createDelivery(self, payload: dict[str, Any]) -> dict[str, Any]:
+        eventId = str(payload.get("eventId", "") or "").strip()
+        subId = str(payload.get("subId", "") or "").strip()
+        attempt = _attempt(payload.get("attempt", 1))
+        errors = _deliveryErrors(eventId=eventId, subId=subId, payload=payload)
+        deliveryId = str(payload.get("deliveryId", "") or _deliveryId(eventId, subId, attempt))
+        now = int(payload.get("createdAt", 0) or time.time())
+        current = self.getDelivery(deliveryId)
+        createdAt = current.get("delivery", {}).get("createdAt", now) if current.get("ok") else now
+        status = _deliveryStatus(payload.get("status", "queued"))
+        record = {
+            "deliveryId": deliveryId,
+            "eventId": eventId,
+            "subId": subId,
+            "clientId": str(payload.get("clientId", "") or ""),
+            "transport": _transport(payload.get("transport", "poll")),
+            "endpoint": str(payload.get("endpoint", "") or ""),
+            "status": status,
+            "attempt": attempt,
+            "claimedBy": str(payload.get("claimedBy", "") or ""),
+            "lastError": str(payload.get("lastError", "") or ""),
+            "meta": copy.deepcopy(payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {}),
+            "createdAt": int(createdAt or now),
+            "updatedAt": int(payload.get("updatedAt", now) or now),
+            "nextAttemptAt": _nextAttemptAt(payload, now) if status == "queued" else 0,
+            "claimedAt": int(payload.get("claimedAt", 0) or 0),
+            "leaseExpiresAt": int(payload.get("leaseExpiresAt", 0) or 0),
+            "deliveredAt": int(payload.get("deliveredAt", 0) or 0),
+        }
+        if errors:
+            return {"ok": False, "errors": errors, "delivery": record}
+        self._saveRecord(record)
+        return {"ok": True, "delivery": copy.deepcopy(record)}
+
+    def getDelivery(self, deliveryId: str) -> dict[str, Any]:
+        deliveryId = str(deliveryId or "")
+        record = self._records.get(deliveryId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchEventDelivery"):
+            record = self.backing.fetchEventDelivery(deliveryId)
+            if record:
+                self._records[deliveryId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "deliveryNotFound", "deliveryId": deliveryId}
+        return {"ok": True, "delivery": copy.deepcopy(record)}
+
+    def listDeliveries(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        records = self._filtered(filters)
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("deliveryId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "deliveries": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def deliveryStats(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        now = int(filters.get("now", 0) or time.time())
+        records = self._filtered(filters)
+        ready = [record for record in records if record.get("status") == "queued" and _isDue(record, now)]
+        scheduled = [record for record in records if record.get("status") == "queued" and not _isDue(record, now)]
+        expired = [
+            record
+            for record in records
+            if record.get("status") == "claimed" and 0 < int(record.get("leaseExpiresAt", 0) or 0) <= now
+        ]
+        activeClaims = [
+            record
+            for record in records
+            if record.get("status") == "claimed"
+            and (int(record.get("leaseExpiresAt", 0) or 0) <= 0 or int(record.get("leaseExpiresAt", 0) or 0) > now)
+        ]
+        return {
+            "ok": True,
+            "stats": {
+                "total": len(records),
+                "ready": len(ready),
+                "scheduled": len(scheduled),
+                "expired": len(expired),
+                "activeClaims": len(activeClaims),
+                "byStatus": _countBy(records, "status"),
+                "byTransport": _countBy(records, "transport"),
+                "byClient": _countBy(records, "clientId"),
+            },
+            "count": len(records),
+        }
+
+    def readyDeliveries(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        now = int(filters.get("now", 0) or time.time())
+        records = self._claimable(self._claimFilters(filters), now)
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("deliveryId", ""))))
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "deliveries": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+            "total": len(records),
+        }
+
+    def deliveryChain(self, deliveryId: str, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        self._loadBacking()
+        filters = filters or {}
+        record = current["delivery"]
+        eventId = str(record.get("eventId", "") or "")
+        subId = str(record.get("subId", "") or "")
+        records = self._filtered({"eventId": eventId, "subId": subId})
+        records.sort(key=lambda item: (int(item.get("attempt", 1) or 1), int(item.get("createdAt", 0) or 0), str(item.get("deliveryId", ""))))
+        limit = _limit(filters.get("limit", 100))
+        root = records[0] if records else {}
+        latest = records[-1] if records else {}
+        attempts = [copy.deepcopy(item) for item in records[:limit]]
+        return {
+            "ok": True,
+            "deliveryId": str(deliveryId or ""),
+            "eventId": eventId,
+            "subId": subId,
+            "rootDeliveryId": str(root.get("deliveryId", "") or ""),
+            "latestDeliveryId": str(latest.get("deliveryId", "") or ""),
+            "deliveries": attempts,
+            "count": min(len(records), limit),
+            "total": len(records),
+        }
+
+    def claimNext(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        filters = self._claimFilters(payload)
+        if self._backingEnabled() and hasattr(self.backing, "claimEventDelivery"):
+            claimed = self.backing.claimEventDelivery(payload)
+            if claimed:
+                deliveryId = str(claimed.get("deliveryId", "") or "")
+                if deliveryId:
+                    self._records[deliveryId] = copy.deepcopy(claimed)
+                return {"ok": True, "delivery": copy.deepcopy(claimed)}
+            return {"ok": False, "error": "deliveryNotFound", "filters": {key: value for key, value in filters.items() if value}}
+        else:
+            self._loadBacking()
+        now = int(time.time())
+        records = self._claimable(filters, now)
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("deliveryId", ""))))
+        if not records:
+            return {"ok": False, "error": "deliveryNotFound", "filters": {key: value for key, value in filters.items() if value}}
+        claimedBy = str(payload.get("claimedBy", payload.get("workerId", "")) or "")
+        return self.updateDelivery(
+            records[0]["deliveryId"],
+            {
+                "status": "claimed",
+                "claimedBy": claimedBy,
+                "leaseExpiresAt": _leaseExpiresAt(payload, now),
+            },
+        )
+
+    def claimBatch(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        limit = _limit(payload.get("limit", payload.get("count", 10)))
+        claimed: list[dict[str, Any]] = []
+        if self._backingEnabled() and hasattr(self.backing, "claimEventDelivery"):
+            for _ in range(limit):
+                result = self.backing.claimEventDelivery(payload)
+                if not result:
+                    break
+                deliveryId = str(result.get("deliveryId", "") or "")
+                if deliveryId:
+                    self._records[deliveryId] = copy.deepcopy(result)
+                claimed.append(copy.deepcopy(result))
+            return {"ok": True, "deliveries": claimed, "count": len(claimed), "total": len(claimed)}
+        self._loadBacking()
+        now = int(time.time())
+        records = self._claimable(self._claimFilters(payload), now)
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("deliveryId", ""))))
+        for record in records[:limit]:
+            result = self.updateDelivery(
+                str(record.get("deliveryId", "") or ""),
+                {
+                    "status": "claimed",
+                    "claimedBy": str(payload.get("claimedBy", payload.get("workerId", "")) or ""),
+                    "leaseExpiresAt": _leaseExpiresAt(payload, now),
+                },
+            )
+            if result.get("ok") and isinstance(result.get("delivery"), dict):
+                claimed.append(copy.deepcopy(result["delivery"]))
+        return {"ok": True, "deliveries": claimed, "count": len(claimed), "total": len(records)}
+
+    def retryDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        record = current["delivery"]
+        if record.get("status") not in {"failed", "canceled"}:
+            return {"ok": False, "error": "invalid:retryStatus", "delivery": copy.deepcopy(record)}
+        meta = record.get("meta", {}) if isinstance(record.get("meta"), dict) else {}
+        if isinstance(payload.get("meta"), dict):
+            meta = {**meta, **payload["meta"]}
+        meta["parentDeliveryId"] = str(record.get("deliveryId", "") or deliveryId)
+        return self.createDelivery(
+            {
+                "eventId": record.get("eventId", ""),
+                "subId": record.get("subId", ""),
+                "clientId": payload.get("clientId", record.get("clientId", "")),
+                "transport": payload.get("transport", record.get("transport", "poll")),
+                "endpoint": payload.get("endpoint", record.get("endpoint", "")),
+                "status": "queued",
+                "attempt": _attempt(payload.get("attempt", int(record.get("attempt", 1) or 1) + 1)),
+                "nextAttemptAt": payload.get("nextAttemptAt", 0),
+                "delaySeconds": payload.get("delaySeconds", ""),
+                "meta": meta,
+            }
+        )
+
+    def failDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        record = current["delivery"]
+        if record.get("status") in {"delivered", "canceled"}:
+            return {"ok": False, "error": "invalid:failStatus", "delivery": copy.deepcopy(record)}
+        workerId = str(payload.get("workerId", payload.get("claimedBy", "")) or "")
+        claimedBy = str(record.get("claimedBy", "") or "")
+        if record.get("status") == "claimed" and workerId and claimedBy and workerId != claimedBy:
+            return {"ok": False, "error": "invalid:claimOwner", "delivery": copy.deepcopy(record)}
+        if record.get("status") == "failed":
+            failed = copy.deepcopy(record)
+        else:
+            updates: dict[str, Any] = {"status": "failed"}
+            if "lastError" in payload:
+                updates["lastError"] = str(payload.get("lastError", "") or "")
+            if isinstance(payload.get("meta"), dict):
+                updates["meta"] = payload["meta"]
+            failedResult = self.updateDelivery(deliveryId, updates)
+            if not failedResult.get("ok"):
+                return failedResult
+            failed = failedResult["delivery"]
+        result: dict[str, Any] = {"ok": True, "delivery": copy.deepcopy(failed)}
+        if not _retryEnabled(payload.get("retry", True)):
+            result["retry"] = {"scheduled": False, "reason": "disabled"}
+            return result
+        maxAttempts = _maxAttempts(payload.get("maxAttempts", 3))
+        if int(failed.get("attempt", 1) or 1) >= maxAttempts:
+            result["retry"] = {"scheduled": False, "reason": "maxAttempts", "maxAttempts": maxAttempts}
+            return result
+        nextAttempt = _attempt(payload.get("attempt", int(failed.get("attempt", 1) or 1) + 1))
+        if nextAttempt > maxAttempts:
+            result["retry"] = {"scheduled": False, "reason": "maxAttempts", "maxAttempts": maxAttempts}
+            return result
+        retryPayload = {
+            key: payload[key]
+            for key in ("clientId", "transport", "endpoint", "attempt", "nextAttemptAt", "delaySeconds")
+            if key in payload
+        }
+        retryMeta = payload.get("retryMeta", {})
+        if isinstance(retryMeta, dict):
+            retryPayload["meta"] = retryMeta
+        retried = self.retryDelivery(deliveryId, retryPayload)
+        if not retried.get("ok"):
+            return {"ok": False, "error": retried.get("error", "retryFailed"), "delivery": copy.deepcopy(failed), "retry": retried}
+        result["retry"] = {"scheduled": True, "delivery": retried["delivery"], "maxAttempts": maxAttempts}
+        return result
+
+    def completeDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        record = current["delivery"]
+        if record.get("status") == "delivered":
+            return {"ok": True, "delivery": copy.deepcopy(record)}
+        if record.get("status") != "claimed":
+            return {"ok": False, "error": "invalid:completeStatus", "delivery": copy.deepcopy(record)}
+        workerId = str(payload.get("workerId", payload.get("claimedBy", "")) or "")
+        claimedBy = str(record.get("claimedBy", "") or "")
+        if workerId and claimedBy and workerId != claimedBy:
+            return {"ok": False, "error": "invalid:claimOwner", "delivery": copy.deepcopy(record)}
+        updates: dict[str, Any] = {"status": "delivered"}
+        if "deliveredAt" in payload:
+            updates["deliveredAt"] = int(payload.get("deliveredAt", 0) or 0)
+        if "lastError" in payload:
+            updates["lastError"] = str(payload.get("lastError", "") or "")
+        if isinstance(payload.get("meta"), dict):
+            updates["meta"] = payload["meta"]
+        return self.updateDelivery(deliveryId, updates)
+
+    def cancelDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        record = current["delivery"]
+        if record.get("status") == "canceled":
+            return {"ok": True, "delivery": copy.deepcopy(record)}
+        if record.get("status") == "delivered":
+            return {"ok": False, "error": "invalid:cancelStatus", "delivery": copy.deepcopy(record)}
+        workerId = str(payload.get("workerId", payload.get("claimedBy", "")) or "")
+        claimedBy = str(record.get("claimedBy", "") or "")
+        if record.get("status") == "claimed" and workerId and claimedBy and workerId != claimedBy:
+            return {"ok": False, "error": "invalid:claimOwner", "delivery": copy.deepcopy(record)}
+        updates: dict[str, Any] = {"status": "canceled"}
+        if "lastError" in payload:
+            updates["lastError"] = str(payload.get("lastError", "") or "")
+        elif "reason" in payload:
+            updates["lastError"] = str(payload.get("reason", "") or "")
+        if isinstance(payload.get("meta"), dict):
+            updates["meta"] = payload["meta"]
+        return self.updateDelivery(deliveryId, updates)
+
+    def renewLease(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        record = current["delivery"]
+        if record.get("status") != "claimed":
+            return {"ok": False, "error": "invalid:leaseStatus", "delivery": copy.deepcopy(record)}
+        claimedBy = str(payload.get("claimedBy", payload.get("workerId", "")) or "")
+        if claimedBy and claimedBy != str(record.get("claimedBy", "") or ""):
+            return {"ok": False, "error": "invalid:leaseOwner", "delivery": copy.deepcopy(record)}
+        now = int(time.time())
+        return self.updateDelivery(deliveryId, {"leaseExpiresAt": _leaseExpiresAt(payload, now)})
+
+    def releaseDelivery(self, deliveryId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        record = current["delivery"]
+        if record.get("status") != "claimed":
+            return {"ok": False, "error": "invalid:releaseStatus", "delivery": copy.deepcopy(record)}
+        updates: dict[str, Any] = {
+            "status": "queued",
+            "claimedBy": "",
+            "claimedAt": 0,
+            "leaseExpiresAt": 0,
+        }
+        if payload.get("lastError"):
+            updates["lastError"] = str(payload.get("lastError", "") or "")
+        if isinstance(payload.get("meta"), dict):
+            updates["meta"] = payload["meta"]
+        if payload.get("nextAttemptAt") or payload.get("delaySeconds"):
+            updates["nextAttemptAt"] = _nextAttemptAt(payload, int(time.time()))
+        return self.updateDelivery(deliveryId, updates)
+
+    def sweepExpiredLeases(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = payload or {}
+        if self._backingEnabled() and hasattr(self.backing, "sweepEventDeliveryLeases"):
+            records = self.backing.sweepEventDeliveryLeases(payload)
+            for record in records:
+                deliveryId = str(record.get("deliveryId", "") or "")
+                if deliveryId:
+                    self._records[deliveryId] = copy.deepcopy(record)
+            return {"ok": True, "deliveries": [copy.deepcopy(record) for record in records], "count": len(records)}
+        self._loadBacking()
+        now = int(payload.get("now", 0) or time.time())
+        records = self._expiredLeases(self._claimFilters(payload), now)
+        limit = _limit(payload.get("limit", 100))
+        swept: list[dict[str, Any]] = []
+        for record in records[:limit]:
+            result = self.releaseDelivery(
+                str(record.get("deliveryId", "") or ""),
+                {"lastError": str(payload.get("lastError", record.get("lastError", "")) or "")},
+            )
+            if result.get("ok") and isinstance(result.get("delivery"), dict):
+                swept.append(copy.deepcopy(result["delivery"]))
+        return {"ok": True, "deliveries": swept, "count": len(swept)}
+
+    def updateDelivery(self, deliveryId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getDelivery(deliveryId)
+        if not current.get("ok"):
+            return current
+        now = int(time.time())
+        record = current["delivery"]
+        status = _deliveryStatus(updates.get("status", record.get("status", "queued")))
+        claimedAt = int(updates.get("claimedAt", record.get("claimedAt", 0)) or 0)
+        leaseExpiresAt = int(updates.get("leaseExpiresAt", record.get("leaseExpiresAt", 0)) or 0)
+        nextAttemptAt = int(updates.get("nextAttemptAt", record.get("nextAttemptAt", 0)) or 0)
+        deliveredAt = int(updates.get("deliveredAt", record.get("deliveredAt", 0)) or 0)
+        if "delaySeconds" in updates:
+            nextAttemptAt = _nextAttemptAt(updates, now)
+        if status == "claimed" and not claimedAt:
+            claimedAt = now
+        if status == "claimed" and not leaseExpiresAt:
+            leaseExpiresAt = _leaseExpiresAt(updates, now)
+        if status != "claimed":
+            leaseExpiresAt = 0
+        if status != "queued":
+            nextAttemptAt = 0
+        if status == "delivered" and not deliveredAt:
+            deliveredAt = now
+        meta = record.get("meta", {}) if isinstance(record.get("meta"), dict) else {}
+        if isinstance(updates.get("meta"), dict):
+            meta = {**meta, **updates["meta"]}
+        merged = {
+            **record,
+            "status": status,
+            "attempt": _attempt(updates.get("attempt", record.get("attempt", 1))),
+            "claimedBy": str(updates.get("claimedBy", record.get("claimedBy", "")) or ""),
+            "lastError": str(updates.get("lastError", record.get("lastError", "")) or ""),
+            "meta": meta,
+            "updatedAt": int(updates.get("updatedAt", now) or now),
+            "nextAttemptAt": nextAttemptAt,
+            "claimedAt": claimedAt,
+            "leaseExpiresAt": leaseExpiresAt,
+            "deliveredAt": deliveredAt,
+        }
+        errors = _deliveryErrors(eventId=merged["eventId"], subId=merged["subId"], payload=merged)
+        if errors:
+            return {"ok": False, "errors": errors, "delivery": merged}
+        self._saveRecord(merged)
+        return {"ok": True, "delivery": copy.deepcopy(merged)}
+
+    def _saveRecord(self, record: dict[str, Any]) -> None:
+        deliveryId = str(record.get("deliveryId", "") or "")
+        if not deliveryId:
+            return
+        self._records[deliveryId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertEventDelivery"):
+            self.backing.upsertEventDelivery(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listEventDeliveries"):
+            return
+        for record in self.backing.listEventDeliveries():
+            deliveryId = str(record.get("deliveryId", "") or "")
+            if deliveryId:
+                self._records[deliveryId] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+    def _filtered(self, filters: dict[str, Any]) -> list[dict[str, Any]]:
+        eventId = str(filters.get("eventId", "") or "")
+        subId = str(filters.get("subId", "") or "")
+        clientId = str(filters.get("clientId", "") or "")
+        status = str(filters.get("status", "") or "")
+        transport = str(filters.get("transport", "") or "")
+        records = list(self._records.values())
+        if eventId:
+            records = [record for record in records if record.get("eventId") == eventId]
+        if subId:
+            records = [record for record in records if record.get("subId") == subId]
+        if clientId:
+            records = [record for record in records if record.get("clientId") == clientId]
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        if transport:
+            records = [record for record in records if record.get("transport") == transport]
+        return [copy.deepcopy(record) for record in records]
+
+    @staticmethod
+    def _claimFilters(payload: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "eventId": payload.get("eventId", ""),
+            "subId": payload.get("subId", ""),
+            "clientId": payload.get("clientId", ""),
+            "transport": payload.get("transport", ""),
+        }
+
+    def _claimable(self, filters: dict[str, Any], now: int) -> list[dict[str, Any]]:
+        records = self._filtered(filters)
+        return [
+            record
+            for record in records
+            if (record.get("status") == "queued" and _isDue(record, now))
+            or (record.get("status") == "claimed" and 0 < int(record.get("leaseExpiresAt", 0) or 0) <= now)
+        ]
+
+    def _expiredLeases(self, filters: dict[str, Any], now: int) -> list[dict[str, Any]]:
+        records = self._filtered(filters)
+        records = [
+            record
+            for record in records
+            if record.get("status") == "claimed" and 0 < int(record.get("leaseExpiresAt", 0) or 0) <= now
+        ]
+        records.sort(key=lambda item: (int(item.get("leaseExpiresAt", 0) or 0), str(item.get("deliveryId", ""))))
+        return records
+
+
+def _stableId(eventType: str, payload: dict[str, Any], createdAt: int) -> str:
+    base = {
+        "type": eventType,
+        "subject": str(payload.get("subject", "") or ""),
+        "source": str(payload.get("source", "picux") or "picux"),
+        "target": str(payload.get("target", "") or ""),
+        "payload": payload.get("payload", {}) if isinstance(payload.get("payload"), dict) else {},
+        "createdAt": int(createdAt or 0),
+    }
+    digest = hashlib.sha256(json.dumps(base, ensure_ascii=True, sort_keys=True).encode("utf-8")).hexdigest()
+    return f"evt_{digest[:24]}"
+
+
+def _status(value: Any) -> str:
+    status = str(value or "queued")
+    return status if status in EVENT_STATUSES else "queued"
+
+
+def _subStatus(value: Any) -> str:
+    status = str(value or "active")
+    return status if status in SUBSCRIPTION_STATUSES else "active"
+
+
+def _transport(value: Any) -> str:
+    transport = str(value or "poll")
+    return transport if transport in SUBSCRIPTION_TRANSPORTS else "poll"
+
+
+def _deliveryStatus(value: Any) -> str:
+    status = str(value or "queued")
+    return status if status in DELIVERY_STATUSES else "queued"
+
+
+def _cleanList(value: Any) -> list[str]:
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, (list, tuple, set)):
+        return []
+    cleaned: list[str] = []
+    for item in value:
+        text = str(item or "").strip()
+        if text and text not in cleaned:
+            cleaned.append(text)
+    return cleaned
+
+
+def _subscriptionErrors(*, clientId: str, eventTypes: list[str], payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if not clientId:
+        errors.append("missing:clientId")
+    if not eventTypes:
+        errors.append("missing:eventTypes")
+    if str(payload.get("status", "active") or "active") not in SUBSCRIPTION_STATUSES:
+        errors.append("invalid:status")
+    if str(payload.get("transport", "poll") or "poll") not in SUBSCRIPTION_TRANSPORTS:
+        errors.append("invalid:transport")
+    return errors
+
+
+def _subscriptionId(clientId: str, eventTypes: list[str], payload: dict[str, Any]) -> str:
+    base = {
+        "clientId": clientId,
+        "eventTypes": eventTypes,
+        "target": str(payload.get("target", clientId) or ""),
+        "transport": str(payload.get("transport", "poll") or "poll"),
+        "endpoint": str(payload.get("endpoint", "") or ""),
+    }
+    digest = hashlib.sha256(json.dumps(base, ensure_ascii=True, sort_keys=True).encode("utf-8")).hexdigest()
+    return f"sub_{digest[:24]}"
+
+
+def _deliveryId(eventId: str, subId: str, attempt: int) -> str:
+    base = {"eventId": eventId, "subId": subId, "attempt": int(attempt or 1)}
+    digest = hashlib.sha256(json.dumps(base, ensure_ascii=True, sort_keys=True).encode("utf-8")).hexdigest()
+    return f"delv_{digest[:24]}"
+
+
+def _deliveryErrors(*, eventId: str, subId: str, payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if not eventId:
+        errors.append("missing:eventId")
+    if not subId:
+        errors.append("missing:subId")
+    if str(payload.get("status", "queued") or "queued") not in DELIVERY_STATUSES:
+        errors.append("invalid:status")
+    if str(payload.get("transport", "poll") or "poll") not in SUBSCRIPTION_TRANSPORTS:
+        errors.append("invalid:transport")
+    if _attempt(payload.get("attempt", 1)) < 1:
+        errors.append("invalid:attempt")
+    return errors
+
+
+def _attempt(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 1
+    return max(1, parsed)
+
+
+def _leaseSeconds(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 300
+    return max(1, min(parsed, 86400))
+
+
+def _leaseExpiresAt(payload: dict[str, Any], now: int) -> int:
+    explicit = int(payload.get("leaseExpiresAt", 0) or 0)
+    if explicit:
+        return explicit
+    return now + _leaseSeconds(payload.get("leaseSeconds", 300))
+
+
+def _delaySeconds(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 0
+    return max(0, min(parsed, 2592000))
+
+
+def _retryEnabled(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() not in {"0", "false", "no", "off", "disabled"}
+
+
+def _maxAttempts(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 3
+    return max(1, min(parsed, 100))
+
+
+def _nextAttemptAt(payload: dict[str, Any], now: int) -> int:
+    explicit = int(payload.get("nextAttemptAt", 0) or 0)
+    if explicit:
+        return explicit
+    delay = _delaySeconds(payload.get("delaySeconds", 0))
+    return now + delay if delay else 0
+
+
+def _isDue(record: dict[str, Any], now: int) -> bool:
+    nextAttemptAt = int(record.get("nextAttemptAt", 0) or 0)
+    return nextAttemptAt <= 0 or nextAttemptAt <= now
+
+
+def _countBy(records: list[dict[str, Any]], key: str) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for record in records:
+        value = str(record.get(key, "") or "")
+        if not value:
+            continue
+        counts[value] = counts.get(value, 0) + 1
+    return counts
+
+
+def _limit(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 500))