patchr 0.1.0__py3-none-any.whl

picux/storage/providers.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import re
+import time
+from typing import Any
+
+
+class LocalProviderBook:
+    """Private local-service contact cache for HUNT -> PROXY workflows."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+
+    def saveLead(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._save(payload, status=str(payload.get("status", "lead") or "lead"))
+
+    def saveVerified(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._save(payload, status="verified")
+
+    def getProvider(self, providerId: str) -> dict[str, Any]:
+        providerId = str(providerId or "").strip()
+        record = self._records.get(providerId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchLocalProvider"):
+            record = self.backing.fetchLocalProvider(providerId)
+            if record:
+                self._records[providerId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "providerNotFound", "providerId": providerId}
+        return {"ok": True, "provider": copy.deepcopy(record)}
+
+    def find(self, *, service: str = "", location: str = "", verifiedOnly: bool = True, limit: int = 10) -> dict[str, Any]:
+        self._loadBacking()
+        serviceKey = _norm(service)
+        locationKey = _norm(location)
+        records = list(self._records.values())
+        if verifiedOnly:
+            records = [item for item in records if item.get("status") == "verified"]
+        if serviceKey:
+            records = [item for item in records if serviceKey in _norm(item.get("service", "")) or serviceKey in _norm(item.get("entity", ""))]
+        if locationKey:
+            records = [item for item in records if _locationMatch(locationKey, _norm(" ".join(str(item.get(key, "")) for key in ("location", "address", "area"))))]
+        records.sort(key=lambda item: (item.get("status") == "verified", float(item.get("rating", 0.0) or 0.0), int(item.get("updatedAt", 0) or 0)), reverse=True)
+        limited = records[: max(1, min(int(limit or 10), 50))]
+        return {"ok": True, "providers": [copy.deepcopy(record) for record in limited], "count": len(limited)}
+
+    def toPlaces(self, *, service: str = "", location: str = "", limit: int = 10) -> list[dict[str, Any]]:
+        found = self.find(service=service, location=location, verifiedOnly=True, limit=limit)
+        places = []
+        for record in found.get("providers", []):
+            places.append(
+                {
+                    "placeId": str(record.get("providerId", "") or record.get("contactRef", "")),
+                    "name": str(record.get("name", "") or ""),
+                    "category": str(record.get("category", service) or service),
+                    "address": str(record.get("address", "") or ""),
+                    "phone": str(record.get("phone", "") or ""),
+                    "website": str(record.get("website", "") or ""),
+                    "rating": record.get("rating", 0),
+                    "lat": record.get("lat", 0),
+                    "lng": record.get("lng", 0),
+                    "distanceKm": record.get("distanceKm", 0),
+                    "source": "verifiedProviders",
+                    "sourceUrl": str(record.get("sourceUrl", "") or ""),
+                    "sourceBound": True,
+                    "entity": str(record.get("service", service) or service),
+                    "contactRef": str(record.get("contactRef", record.get("providerId", "")) or ""),
+                    "verified": True,
+                    "availability": record.get("availability", {}) if isinstance(record.get("availability"), dict) else {},
+                }
+            )
+        return places
+
+    def _save(self, payload: dict[str, Any], *, status: str) -> dict[str, Any]:
+        if not isinstance(payload, dict):
+            return {"ok": False, "error": "invalid:provider"}
+        providerId = str(payload.get("providerId", payload.get("contactRef", "")) or "").strip()
+        if not providerId:
+            providerId = "provider_" + hashlib.sha256(json.dumps(payload, sort_keys=True, default=str).encode("utf-8")).hexdigest()[:24]
+        now = int(time.time())
+        current = self._records.get(providerId, {})
+        createdAt = int(current.get("createdAt", now) or now)
+        record = {
+            **copy.deepcopy(current),
+            "providerId": providerId,
+            "contactRef": str(payload.get("contactRef", current.get("contactRef", providerId)) or providerId),
+            "status": status,
+            "service": str(payload.get("service", payload.get("entity", current.get("service", ""))) or ""),
+            "entity": str(payload.get("entity", payload.get("service", current.get("entity", ""))) or ""),
+            "location": str(payload.get("location", payload.get("area", current.get("location", ""))) or ""),
+            "area": str(payload.get("area", payload.get("location", current.get("area", ""))) or ""),
+            "name": str(payload.get("name", current.get("name", "")) or ""),
+            "category": str(payload.get("category", current.get("category", "")) or ""),
+            "address": str(payload.get("address", current.get("address", "")) or ""),
+            "phone": str(payload.get("phone", current.get("phone", "")) or ""),
+            "website": str(payload.get("website", current.get("website", "")) or ""),
+            "rating": _float(payload.get("rating", current.get("rating", 0))),
+            "lat": _float(payload.get("lat", current.get("lat", 0))),
+            "lng": _float(payload.get("lng", current.get("lng", 0))),
+            "distanceKm": _float(payload.get("distanceKm", current.get("distanceKm", 0))),
+            "source": str(payload.get("source", current.get("source", "")) or ""),
+            "sourceUrl": str(payload.get("sourceUrl", current.get("sourceUrl", "")) or ""),
+            "availability": payload.get("availability", current.get("availability", {})) if isinstance(payload.get("availability", current.get("availability", {})), dict) else {},
+            "proof": payload.get("proof", current.get("proof", {})) if isinstance(payload.get("proof", current.get("proof", {})), dict) else {},
+            "meta": payload.get("meta", current.get("meta", {})) if isinstance(payload.get("meta", current.get("meta", {})), dict) else {},
+            "createdAt": createdAt,
+            "updatedAt": now,
+        }
+        self._records[providerId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertLocalProvider"):
+            self.backing.upsertLocalProvider(record)
+        return {"ok": True, "provider": copy.deepcopy(record)}
+
+    def _loadBacking(self) -> None:
+        if not self._backingEnabled() or not hasattr(self.backing, "listLocalProviders"):
+            return
+        for record in self.backing.listLocalProviders():
+            if isinstance(record, dict) and str(record.get("providerId", "") or ""):
+                self._records[str(record["providerId"])] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+def _norm(value: Any) -> str:
+    text = re.sub(r"[^a-z0-9]+", " ", str(value or "").lower())
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _locationMatch(needle: str, haystack: str) -> bool:
+    if not needle:
+        return True
+    if needle in haystack:
+        return True
+    needleParts = [part for part in needle.split() if len(part) > 2]
+    return bool(needleParts) and all(part in haystack for part in needleParts[:3])
+
+
+def _float(value: Any) -> float:
+    try:
+        return float(value or 0.0)
+    except Exception:
+        return 0.0

picux/storage/proxy.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import copy
+import time
+from typing import Any
+
+
+PROXY_STATUSES = {
+    "requested",
+    "awaitingProxy",
+    "notified",
+    "inProgress",
+    "submitted",
+    "pending",
+    "confirmedSuccess",
+    "confirmedFailure",
+    "canceled",
+    "overdue",
+}
+PROXY_KINDS = {"review", "logistics", "call", "message", "approval", "custom"}
+
+
+class ProxyBook:
+    """Proxy mission storage with callback reference indexes."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+        self._refs: dict[str, str] = {}
+
+    def saveMission(self, payload: dict[str, Any], *, status: str = "awaitingProxy") -> dict[str, Any]:
+        proxyId = str(payload.get("proxyId", payload.get("missionId", "")) or "")
+        if not proxyId:
+            return {"ok": False, "error": "missing:proxyId"}
+        errors = _missionErrors(payload)
+        if errors:
+            return {"ok": False, "error": "invalid:proxyMission", "errors": errors}
+        current = self.getMission(proxyId)
+        now = int(time.time())
+        createdAt = current.get("mission", {}).get("createdAt", now) if current.get("ok") else now
+        record = _recordFromPayload({**payload, "proxyId": proxyId}, status=status, createdAt=createdAt, updatedAt=now)
+        self._saveRecord(record)
+        return {"ok": True, "mission": copy.deepcopy(record)}
+
+    def getMission(self, proxyId: str) -> dict[str, Any]:
+        proxyId = str(proxyId or "")
+        record = self._records.get(proxyId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchProxyMission"):
+            record = self.backing.fetchProxyMission(proxyId)
+            if record:
+                self._saveRecord(record, persist=False)
+        if not record:
+            return {"ok": False, "error": "proxyMissionNotFound", "proxyId": proxyId}
+        return {"ok": True, "mission": copy.deepcopy(record)}
+
+    def getMissionByRef(self, payload: dict[str, Any]) -> dict[str, Any]:
+        proxyId = self.resolveProxyId(payload)
+        return self.getMission(proxyId) if proxyId else {"ok": False, "error": "proxyMissionNotFound", "proxyId": ""}
+
+    def resolveProxyId(self, payload: dict[str, Any]) -> str:
+        for key in ("proxyId", "missionId"):
+            value = str(payload.get(key, "") or "")
+            if value:
+                return value
+        refs = payload.get("refs", {}) if isinstance(payload.get("refs"), dict) else {}
+        for key in ("requestId", "providerTaskId", "externalRef", "connectorRunId"):
+            value = str(payload.get(key, refs.get(key, "")) or "")
+            if not value:
+                continue
+            found = self._refs.get(f"{key}:{value}")
+            if found:
+                return found
+            if self._backingEnabled() and hasattr(self.backing, "fetchProxyMissionByRef"):
+                record = self.backing.fetchProxyMissionByRef(key, value)
+                if record:
+                    self._saveRecord(record, persist=False)
+                    proxyId = str(record.get("proxyId", "") or "")
+                    if proxyId:
+                        return proxyId
+        return ""
+
+    def listMissions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        records = list(self._records.values())
+        for key in ("taskId", "userId", "status", "kind"):
+            value = str(filters.get(key, "") or "")
+            if value:
+                records = [record for record in records if str(record.get(key, "") or "") == value]
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("proxyId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "missions": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def submitOutcome(self, proxyId: str, payload: dict[str, Any], outcome: dict[str, Any]) -> dict[str, Any]:
+        current = self.getMission(proxyId)
+        if not current.get("ok"):
+            return current
+        now = int(time.time())
+        mission = current["mission"]
+        status = _status(outcome.get("status", payload.get("status", "submitted")))
+        merged = {
+            **mission,
+            "status": status,
+            "outcome": copy.deepcopy(outcome),
+            "resume": copy.deepcopy(outcome.get("resume", {}) if isinstance(outcome.get("resume"), dict) else {}),
+            "updatedAt": int(payload.get("updatedAt", now) or now),
+        }
+        refs = _refs({**mission, **payload})
+        if refs:
+            merged["refs"] = refs
+        self._saveRecord(merged)
+        return {"ok": True, "mission": copy.deepcopy(merged), "outcome": copy.deepcopy(outcome)}
+
+    def submitOutcomeByRef(self, payload: dict[str, Any], outcome: dict[str, Any]) -> dict[str, Any]:
+        proxyId = self.resolveProxyId(payload)
+        if not proxyId:
+            return {"ok": False, "error": "proxyMissionNotFound", "proxyId": ""}
+        return self.submitOutcome(proxyId, payload, outcome)
+
+    def _saveRecord(self, record: dict[str, Any], *, persist: bool = True) -> None:
+        proxyId = str(record.get("proxyId", "") or "")
+        if not proxyId:
+            return
+        self._records[proxyId] = copy.deepcopy(record)
+        for key, value in record.get("refs", {}).items():
+            clean = str(value or "")
+            if clean:
+                self._refs[f"{key}:{clean}"] = proxyId
+        if persist and self._backingEnabled() and hasattr(self.backing, "upsertProxyMission"):
+            self.backing.upsertProxyMission(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listProxyMissions"):
+            return
+        for record in self.backing.listProxyMissions():
+            proxyId = str(record.get("proxyId", "") or "")
+            if proxyId:
+                self._saveRecord(record, persist=False)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+def _recordFromPayload(payload: dict[str, Any], *, status: str, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    brief = _dict(payload.get("brief", {}))
+    context = _dict(payload.get("context", {}))
+    return {
+        "proxyId": str(payload.get("proxyId", "") or ""),
+        "status": _status(payload.get("status", status)),
+        "domain": "proxy",
+        "kind": _kind(payload.get("kind", payload.get("missionType", brief.get("missionType", "custom")))),
+        "taskId": str(payload.get("taskId", context.get("taskId", "")) or ""),
+        "userId": str(payload.get("userId", context.get("userId", "")) or ""),
+        "resolveId": str(payload.get("resolveId", context.get("resolveId", "")) or ""),
+        "reason": str(payload.get("reason", brief.get("reason", "humanIntervention")) or "humanIntervention"),
+        "brief": brief,
+        "context": context,
+        "decisionFork": _dict(payload.get("decisionFork", brief.get("decisionFork", {}))),
+        "logistics": _dict(payload.get("logistics", brief.get("logistics", {}))),
+        "proofReq": _cleanList(payload.get("proofReq", brief.get("proofReq", []))),
+        "caseOpsTimeline": _cleanDicts(payload.get("caseOpsTimeline", brief.get("caseOpsTimeline", []))),
+        "route": _dict(payload.get("route", {})),
+        "channelMsg": _dict(payload.get("channelMsg", brief.get("channelMsg", {}))),
+        "voiceCall": _dict(payload.get("voiceCall", brief.get("voiceCall", {}))),
+        "refs": _refs(payload),
+        "bridgeAction": _dict(payload.get("bridgeAction", {})),
+        "bridgeRun": _dict(payload.get("bridgeRun", {})),
+        "outcome": _dict(payload.get("outcome", {})),
+        "resume": _dict(payload.get("resume", {})),
+        "createdAt": int(createdAt or updatedAt),
+        "updatedAt": int(updatedAt or createdAt),
+    }
+
+
+def _missionErrors(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if _kind(payload.get("kind", payload.get("missionType", "custom"))) not in PROXY_KINDS:
+        errors.append("invalid:kind")
+    if not _dict(payload.get("brief", {})) and not _dict(payload.get("context", {})) and not str(payload.get("task", payload.get("goal", "")) or ""):
+        errors.append("missing:context")
+    return errors
+
+
+def _refs(payload: dict[str, Any]) -> dict[str, str]:
+    raw = payload.get("refs", {}) if isinstance(payload.get("refs"), dict) else {}
+    refs: dict[str, str] = {}
+    for key in ("requestId", "providerTaskId", "externalRef", "connectorRunId"):
+        value = str(payload.get(key, raw.get(key, "")) or "")
+        if value:
+            refs[key] = value
+    return refs
+
+
+def _dict(value: Any) -> dict[str, Any]:
+    return copy.deepcopy(value) if isinstance(value, dict) else {}
+
+
+def _cleanList(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    out = []
+    for item in value:
+        clean = str(item or "").strip()
+        if clean and clean not in out:
+            out.append(clean)
+    return out
+
+
+def _cleanDicts(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        return []
+    return [copy.deepcopy(item) for item in value if isinstance(item, dict)]
+
+
+def _kind(value: Any) -> str:
+    kind = str(value or "custom")
+    return kind if kind in PROXY_KINDS else kind
+
+
+def _status(value: Any) -> str:
+    status = str(value or "awaitingProxy")
+    return status if status in PROXY_STATUSES else "submitted"
+
+
+def _limit(value: Any) -> int:
+    try:
+        return max(1, min(500, int(value)))
+    except Exception:
+        return 100

picux/storage/receipts.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+class ReceiptBook:
+    """Receipt and proof export boundary with optional durable backing."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._receipts: dict[str, dict[str, Any]] = {}
+        self._pov: dict[str, dict[str, Any]] = {}
+
+    def saveReceipt(self, receipt: dict[str, Any]) -> dict[str, Any]:
+        receiptId = str(receipt.get("receiptId", "") or "")
+        if not receiptId:
+            return {"ok": False, "error": "missing:receiptId"}
+        stored = copy.deepcopy(receipt)
+        self._receipts[receiptId] = stored
+        if self._backingEnabled() and hasattr(self.backing, "insertReceipt"):
+            self.backing.insertReceipt(stored)
+        return {"ok": True, "receiptId": receiptId}
+
+    def getReceipt(self, receiptId: str) -> dict[str, Any]:
+        receiptId = str(receiptId or "")
+        receipt = self._receipts.get(receiptId)
+        if receipt is None and self._backingEnabled() and hasattr(self.backing, "fetchReceipt"):
+            receipt = self.backing.fetchReceipt(receiptId)
+            if receipt:
+                self._receipts[receiptId] = copy.deepcopy(receipt)
+        if not receipt:
+            return {"ok": False, "error": "receiptNotFound", "receiptId": receiptId}
+        return {"ok": True, "receipt": copy.deepcopy(receipt)}
+
+    def listReceipts(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadReceipts()
+        filters = filters or {}
+        status = str(filters.get("status", "") or "")
+        mandateId = str(filters.get("mandateId", "") or "")
+        taskId = str(filters.get("taskId", "") or "")
+        records = list(self._receipts.values())
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        if mandateId:
+            records = [record for record in records if record.get("mandateId") == mandateId]
+        if taskId:
+            records = [record for record in records if record.get("taskId") == taskId]
+        records.sort(key=lambda item: (str(item.get("createdAt", "")), str(item.get("receiptId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "receipts": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def savePov(self, pov: dict[str, Any]) -> dict[str, Any]:
+        povId = str(pov.get("povId", "") or "")
+        if not povId:
+            return {"ok": False, "error": "missing:povId"}
+        stored = copy.deepcopy(pov)
+        self._pov[povId] = stored
+        if self._backingEnabled() and hasattr(self.backing, "insertPov"):
+            self.backing.insertPov(stored)
+        return {"ok": True, "povId": povId}
+
+    def getPov(self, povId: str) -> dict[str, Any]:
+        povId = str(povId or "")
+        pov = self._pov.get(povId)
+        if pov is None and self._backingEnabled() and hasattr(self.backing, "fetchPov"):
+            pov = self.backing.fetchPov(povId)
+            if pov:
+                self._pov[povId] = copy.deepcopy(pov)
+        if not pov:
+            return {"ok": False, "error": "povNotFound", "povId": povId}
+        return {"ok": True, "pov": copy.deepcopy(pov)}
+
+    def listPov(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadPov()
+        filters = filters or {}
+        taskId = str(filters.get("taskId", "") or "")
+        domain = str(filters.get("domain", "") or "")
+        userId = str(filters.get("userId", "") or "")
+        records = list(self._pov.values())
+        if taskId:
+            records = [record for record in records if record.get("taskId") == taskId]
+        if domain:
+            records = [record for record in records if record.get("domain") == domain]
+        if userId:
+            records = [record for record in records if _povUserId(record) == userId]
+        records.sort(key=lambda item: (str(item.get("createdAt", "")), str(item.get("povId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "pov": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def _loadReceipts(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listReceipts"):
+            return
+        for receipt in self.backing.listReceipts():
+            receiptId = str(receipt.get("receiptId", "") or "")
+            if receiptId:
+                self._receipts[receiptId] = copy.deepcopy(receipt)
+
+    def _loadPov(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listPov"):
+            return
+        for pov in self.backing.listPov():
+            povId = str(pov.get("povId", "") or "")
+            if povId:
+                self._pov[povId] = copy.deepcopy(pov)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+def _povUserId(record: dict[str, Any]) -> str:
+    meta = record.get("meta", {}) if isinstance(record.get("meta"), dict) else {}
+    return str(record.get("userId", meta.get("userId", "")) or "")
+
+
+def _limit(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 500))

picux/storage/signals.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import copy
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+
+class SignalBook:
+    """Community signal records with optional durable backing."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+
+    def saveSignal(self, signal: Any, analysis: Any) -> dict[str, Any]:
+        signalMap = _toMap(signal)
+        analysisMap = _toMap(analysis)
+        signalId = str(signalMap.get("signalId", analysisMap.get("signalId", "")) or "")
+        if not signalId:
+            return {"ok": False, "error": "missing:signalId"}
+
+        current = self.getSignal(signalId)
+        observedAt = str(signalMap.get("observedAt", "") or "")
+        now = _epoch(observedAt) or int(time.time())
+        createdAt = current.get("record", {}).get("createdAt", now) if current.get("ok") else now
+        record = {
+            "signalId": signalId,
+            "entity": str(analysisMap.get("entity", signalMap.get("entity", "unknown")) or "unknown"),
+            "confidence": _confidence(analysisMap.get("confidence", signalMap.get("confidence", 0.0))),
+            "sourcePlatform": _sourcePlatform(signalMap, analysisMap),
+            "query": str(analysisMap.get("query", signalMap.get("query", "")) or ""),
+            "signal": copy.deepcopy(signalMap),
+            "analysis": copy.deepcopy(analysisMap),
+            "createdAt": int(createdAt or now),
+            "updatedAt": now,
+        }
+        self._saveRecord(record)
+        return {"ok": True, "record": copy.deepcopy(record)}
+
+    def getSignal(self, signalId: str) -> dict[str, Any]:
+        signalId = str(signalId or "")
+        record = self._records.get(signalId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchSignal"):
+            record = self.backing.fetchSignal(signalId)
+            if record:
+                self._records[signalId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "signalNotFound", "signalId": signalId}
+        return {"ok": True, "record": copy.deepcopy(record)}
+
+    def listSignals(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        entity = str(filters.get("entity", "") or "")
+        sourcePlatform = str(filters.get("sourcePlatform", "") or "")
+        query = str(filters.get("query", "") or "")
+        minConfidence = _optionalFloat(filters.get("minConfidence"))
+        records = list(self._records.values())
+        if entity:
+            records = [record for record in records if record.get("entity") == entity]
+        if sourcePlatform:
+            records = [record for record in records if record.get("sourcePlatform") == sourcePlatform]
+        if query:
+            records = [record for record in records if record.get("query") == query]
+        if minConfidence is not None:
+            records = [record for record in records if _confidence(record.get("confidence", 0.0)) >= minConfidence]
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("signalId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "signals": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def _saveRecord(self, record: dict[str, Any]) -> None:
+        signalId = str(record.get("signalId", "") or "")
+        if not signalId:
+            return
+        self._records[signalId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertSignal"):
+            self.backing.upsertSignal(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listSignals"):
+            return
+        for record in self.backing.listSignals():
+            signalId = str(record.get("signalId", "") or "")
+            if signalId:
+                self._records[signalId] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+def _toMap(value: Any) -> dict[str, Any]:
+    if hasattr(value, "toMap"):
+        mapped = value.toMap()
+        return mapped if isinstance(mapped, dict) else {}
+    return copy.deepcopy(value) if isinstance(value, dict) else {}
+
+
+def _sourcePlatform(signal: dict[str, Any], analysis: dict[str, Any]) -> str:
+    source = signal.get("source", {}) if isinstance(signal.get("source"), dict) else {}
+    analysisSource = analysis.get("source", {}) if isinstance(analysis.get("source"), dict) else {}
+    return str(source.get("platform", analysisSource.get("platform", "")) or "")
+
+
+def _epoch(value: Any) -> int:
+    if isinstance(value, (int, float)):
+        return int(value or 0)
+    raw = str(value or "").strip()
+    if not raw:
+        return 0
+    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())
+
+
+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))
+
+
+def _optionalFloat(value: Any) -> float | None:
+    if value is None or value == "":
+        return None
+    return _confidence(value)
+
+
+def _limit(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 500))