patchr 0.1.0__py3-none-any.whl

picux/audit/verification/ledger.py

@@ -0,0 +1,633 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+ALLOWED_RECEIPT_STATUS = {"settled", "rejected", "frozen"}
+Clock = Callable[[], datetime | str]
+
+
+def canonicalHash(payload: dict[str, Any]) -> str:
+    """Return a stable digest for agent-readable audit payloads."""
+
+    return hashlib.sha256(_canonicalJson(payload).encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class EvidenceArtifact:
+    artifactId: str
+    kind: str
+    source: str
+    payload: dict[str, Any]
+    payloadHash: str
+    createdAt: str
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def fromPayload(
+        cls,
+        payload: dict[str, Any],
+        *,
+        clock: Clock,
+    ) -> "EvidenceArtifact":
+        kind = str(payload.get("kind", payload.get("type", "evidence")) or "evidence")
+        source = str(payload.get("source", payload.get("uri", "inline")) or "inline")
+        body = payload.get("payload") if isinstance(payload.get("payload"), dict) else payload.get("data", {})
+        if not isinstance(body, dict):
+            body = {"value": body}
+        meta = payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {}
+        createdAt = _time(clock)
+        base = {
+            "kind": kind,
+            "source": source,
+            "payload": body,
+            "meta": meta,
+        }
+        return cls(
+            artifactId="art_" + canonicalHash(base)[:24],
+            kind=kind,
+            source=source,
+            payload=body,
+            payloadHash=canonicalHash(body),
+            createdAt=createdAt,
+            meta=meta,
+        )
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "artifactId": self.artifactId,
+            "kind": self.kind,
+            "source": self.source,
+            "payload": self.payload,
+            "payloadHash": self.payloadHash,
+            "createdAt": self.createdAt,
+            "meta": self.meta,
+        }
+
+
+@dataclass(frozen=True)
+class ProofOfValueRecord:
+    povId: str
+    taskId: str
+    domain: str
+    rules: tuple[str, ...]
+    value: dict[str, Any]
+    artifacts: tuple[dict[str, Any], ...]
+    prevHash: str
+    chainHash: str
+    createdAt: str
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def fromPayload(cls, payload: dict[str, Any], *, clock: Clock, prevHash: str = "") -> "ProofOfValueRecord":
+        taskId = str(payload.get("taskId", "") or "")
+        domain = str(payload.get("domain", "") or "")
+        rules = tuple(str(item) for item in payload.get("rules", []) if str(item).strip())
+        value = payload.get("value") if isinstance(payload.get("value"), dict) else {}
+        meta = payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {}
+        artifacts = tuple(_normalizeArtifact(item) for item in payload.get("artifacts", []) if isinstance(item, dict))
+        createdAt = _time(clock)
+        base = {
+            "taskId": taskId,
+            "domain": domain,
+            "rules": list(rules),
+            "value": value,
+            "artifacts": list(artifacts),
+            "prevHash": prevHash,
+            "createdAt": createdAt,
+            "meta": meta,
+        }
+        chainHash = canonicalHash(base)
+        return cls(
+            povId="pov_" + chainHash[:24],
+            taskId=taskId,
+            domain=domain,
+            rules=rules,
+            value=value,
+            artifacts=artifacts,
+            prevHash=prevHash,
+            chainHash=chainHash,
+            createdAt=createdAt,
+            meta=meta,
+        )
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "povId": self.povId,
+            "taskId": self.taskId,
+            "domain": self.domain,
+            "rules": list(self.rules),
+            "value": self.value,
+            "artifacts": list(self.artifacts),
+            "prevHash": self.prevHash,
+            "chainHash": self.chainHash,
+            "createdAt": self.createdAt,
+            "meta": self.meta,
+        }
+
+
+class VerificationLedger:
+    """Deterministic audit ledger for evidence, proof-of-value, receipts, and proof packs."""
+
+    def __init__(self, *, clock: Clock | None = None, backing: Any | None = None) -> None:
+        self.clock = clock or (lambda: datetime.now(timezone.utc))
+        self.backing = backing
+        self._artifacts: dict[str, dict[str, Any]] = {}
+        self._pov: dict[str, dict[str, Any]] = {}
+        self._proofPacks: dict[str, dict[str, Any]] = {}
+        self._chainTail = ""
+
+    def recordEvidence(self, payload: dict[str, Any]) -> dict[str, Any]:
+        artifact = EvidenceArtifact.fromPayload(payload, clock=self.clock).toMap()
+        self._artifacts[artifact["artifactId"]] = artifact
+        if self._backingEnabled() and hasattr(self.backing, "insertEvidence"):
+            self.backing.insertEvidence(artifact)
+        return {"ok": True, "artifact": artifact}
+
+    def recordPov(self, payload: dict[str, Any]) -> dict[str, Any]:
+        errors = _povInputErrors(payload)
+        if errors:
+            return {"ok": False, "errors": errors}
+        normalized = dict(payload)
+        normalized["artifacts"] = self._resolveArtifacts(payload.get("artifacts", []))
+        prevHash = str(payload.get("prevHash", self._chainTail) or "")
+        pov = ProofOfValueRecord.fromPayload(normalized, clock=self.clock, prevHash=prevHash).toMap()
+        self._pov[pov["povId"]] = pov
+        self._chainTail = pov["chainHash"]
+        return {"ok": True, "pov": pov}
+
+    def verifyReceipt(self, payload: dict[str, Any]) -> dict[str, Any]:
+        receipt = payload.get("receipt") if isinstance(payload.get("receipt"), dict) else payload
+        pov = payload.get("pov") if isinstance(payload.get("pov"), dict) else {}
+        if not pov and receipt.get("povRef"):
+            pov = self._pov.get(str(receipt.get("povRef")), {})
+
+        errors = self._receiptErrors(receipt, pov)
+        return {
+            "ok": not errors,
+            "receiptId": str(receipt.get("receiptId", "") or ""),
+            "povId": str(pov.get("povId", "") or receipt.get("povRef", "") or ""),
+            "errors": errors,
+            "hash": receiptHash(receipt),
+        }
+
+    def verifyChain(self, records: list[dict[str, Any]]) -> dict[str, Any]:
+        errors: list[str] = []
+        prevHash = ""
+        for index, record in enumerate(records):
+            expectedPrev = str(record.get("prevHash", "") or "")
+            if expectedPrev != prevHash:
+                errors.append(f"chainBreak:{index}")
+            expected = povChainHash(record)
+            if str(record.get("chainHash", "") or "") != expected:
+                errors.append(f"hashMismatch:{index}")
+            prevHash = str(record.get("chainHash", "") or "")
+        return {"ok": not errors, "errors": errors, "count": len(records)}
+
+    def createProofPack(self, payload: dict[str, Any]) -> dict[str, Any]:
+        artifacts = self._resolveArtifacts(payload.get("artifacts", []))
+        povRecords = self._resolvePov(payload.get("pov", payload.get("povRecords", [])))
+        receipts = _cleanDicts(payload.get("receipts", []))
+        decisions = _cleanDicts(payload.get("decisions", payload.get("decisionLogs", [])))
+        actors = _cleanDicts(payload.get("actors", []))
+        snapshots = _cleanDicts(payload.get("sourceSnapshots", payload.get("snapshots", [])))
+        typedEvidence = _cleanDicts(payload.get("typedEvidence", payload.get("vaultEvidence", [])))
+        fraudIndicators = _cleanDicts(payload.get("fraudIndicators", []))
+        sourceClasses = _cleanDicts(payload.get("sourceClasses", []))
+        caseOpsTimeline = _cleanDicts(payload.get("caseOpsTimeline", []))
+        timeline = _proofTimeline(payload, artifacts, povRecords, receipts, decisions, snapshots)
+        share = _proofShare(payload.get("share", {}))
+        createdAt = _time(self.clock)
+        base = {
+            "status": str(payload.get("status", "ready") or "ready"),
+            "taskId": str(payload.get("taskId", "") or ""),
+            "domain": str(payload.get("domain", "") or ""),
+            "title": str(payload.get("title", "Portable case file") or "Portable case file"),
+            "summary": str(payload.get("summary", "") or ""),
+            "artifacts": artifacts,
+            "pov": povRecords,
+            "receipts": receipts,
+            "decisions": decisions,
+            "actors": actors,
+            "timeline": timeline,
+            "vault": {
+                "kind": "autoAuditVault",
+                "sourceSnapshots": snapshots,
+                "decisionLogs": decisions,
+                "complaintEvidence": artifacts,
+                "typedEvidence": typedEvidence,
+                "fraudIndicators": fraudIndicators,
+                "sourceClasses": sourceClasses,
+                "pov": povRecords,
+            },
+            "share": share,
+            "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+            "caseOpsTimeline": caseOpsTimeline,
+            "createdAt": createdAt,
+        }
+        chainHash = canonicalHash(base)
+        packId = _proofPackId(payload.get("packId", ""), chainHash)
+        proofCard = _proofCard(payload, packId, chainHash, base)
+        pack = {"packId": packId, **base, "proofCard": proofCard, "chainHash": chainHash}
+        self._proofPacks[packId] = pack
+        return {"ok": True, "proofPack": pack}
+
+    def getPov(self, povId: str) -> dict[str, Any]:
+        pov = self._pov.get(povId)
+        if not pov:
+            return {"ok": False, "error": "povNotFound", "povId": povId}
+        return {"ok": True, "pov": pov}
+
+    def getEvidence(self, artifactId: str) -> dict[str, Any]:
+        artifactId = str(artifactId or "")
+        artifact = self._artifacts.get(artifactId)
+        if artifact is None and self._backingEnabled() and hasattr(self.backing, "fetchEvidence"):
+            artifact = self.backing.fetchEvidence(artifactId)
+            if artifact:
+                self._artifacts[artifactId] = artifact
+        if not artifact:
+            return {"ok": False, "error": "artifactNotFound", "artifactId": artifactId}
+        return {"ok": True, "artifact": artifact}
+
+    def listEvidence(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadEvidence()
+        filters = filters or {}
+        kind = str(filters.get("kind", "") or "")
+        source = str(filters.get("source", "") or "")
+        payloadHash = str(filters.get("payloadHash", "") or "")
+        records = list(self._artifacts.values())
+        if kind:
+            records = [record for record in records if record.get("kind") == kind]
+        if source:
+            records = [record for record in records if record.get("source") == source]
+        if payloadHash:
+            records = [record for record in records if record.get("payloadHash") == payloadHash]
+        records.sort(key=lambda item: (str(item.get("createdAt", "")), str(item.get("artifactId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "artifacts": [dict(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def getProofPack(self, packId: str) -> dict[str, Any]:
+        packId = str(packId or "")
+        proofPack = self._proofPacks.get(packId)
+        if not proofPack:
+            return {"ok": False, "error": "proofPackNotFound", "packId": packId}
+        return {"ok": True, "proofPack": dict(proofPack)}
+
+    def listProofPacks(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        filters = filters or {}
+        taskId = str(filters.get("taskId", "") or "")
+        domain = str(filters.get("domain", "") or "")
+        status = str(filters.get("status", "") or "")
+        records = list(self._proofPacks.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 status:
+            records = [record for record in records if record.get("status") == status]
+        records.sort(key=lambda item: (str(item.get("createdAt", "")), str(item.get("packId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "proofPacks": [dict(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def _loadEvidence(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listEvidence"):
+            return
+        for artifact in self.backing.listEvidence():
+            artifactId = str(artifact.get("artifactId", "") or "")
+            if artifactId:
+                self._artifacts[artifactId] = artifact
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+    def _resolveArtifacts(self, artifacts: Any) -> list[dict[str, Any]]:
+        resolved: list[dict[str, Any]] = []
+        if not isinstance(artifacts, list):
+            return resolved
+        for item in artifacts:
+            if isinstance(item, str) and item in self._artifacts:
+                resolved.append(self._artifacts[item])
+            elif isinstance(item, dict):
+                artifactId = str(item.get("artifactId", "") or "")
+                resolved.append(self._artifacts.get(artifactId, _normalizeArtifact(item)))
+        return resolved
+
+    def _resolvePov(self, records: Any) -> list[dict[str, Any]]:
+        resolved: list[dict[str, Any]] = []
+        if isinstance(records, dict):
+            records = [records]
+        if isinstance(records, str):
+            records = [records]
+        if not isinstance(records, list):
+            return resolved
+        for item in records:
+            if isinstance(item, str) and item in self._pov:
+                resolved.append(dict(self._pov[item]))
+            elif isinstance(item, dict):
+                povId = str(item.get("povId", "") or "")
+                resolved.append(dict(self._pov.get(povId, item)))
+        return resolved
+
+    @staticmethod
+    def _receiptErrors(receipt: dict[str, Any], pov: dict[str, Any]) -> list[str]:
+        errors: list[str] = []
+        if not receipt:
+            return ["missing:receipt"]
+        if str(receipt.get("receiptId", "") or "") != receiptId(receipt):
+            errors.append("receiptHashMismatch")
+        if str(receipt.get("status", "") or "") not in ALLOWED_RECEIPT_STATUS:
+            errors.append("invalid:status")
+        if not str(receipt.get("taskId", "") or ""):
+            errors.append("missing:taskId")
+        if not str(receipt.get("mandateId", "") or ""):
+            errors.append("missing:mandateId")
+
+        povRef = str(receipt.get("povRef", "") or "")
+        povId = str(pov.get("povId", "") or "")
+        if povRef and povId and povRef != povId:
+            errors.append("povMismatch")
+        if pov and str(pov.get("taskId", "") or "") and str(receipt.get("taskId", "") or "") != str(
+            pov.get("taskId", "") or ""
+        ):
+            errors.append("taskMismatch")
+        value = pov.get("value", {}) if isinstance(pov.get("value"), dict) else {}
+        amount = value.get("amount")
+        currency = str(value.get("currency", "") or "")
+        receiptAmount = _amount(receipt.get("amount", 0.0))
+        povAmount = _amount(amount)
+        if amount is not None and (receiptAmount is None or povAmount is None):
+            errors.append("invalid:amount")
+        elif amount is not None and round(receiptAmount or 0.0, 2) != round(povAmount or 0.0, 2):
+            errors.append("amountMismatch")
+        if currency and str(receipt.get("currency", "") or "").upper() != currency.upper():
+            errors.append("currencyMismatch")
+        return errors
+
+
+def receiptHash(receipt: dict[str, Any]) -> str:
+    return canonicalHash(receiptBase(receipt))
+
+
+def receiptId(receipt: dict[str, Any]) -> str:
+    return "rcpt_" + receiptHash(receipt)[:24]
+
+
+def receiptBase(receipt: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "mandateId": str(receipt.get("mandateId", "") or ""),
+        "taskId": str(receipt.get("taskId", "") or ""),
+        "status": str(receipt.get("status", "") or ""),
+        "amount": receipt.get("amount", 0.0),
+        "currency": str(receipt.get("currency", "") or ""),
+        "povRef": str(receipt.get("povRef", "") or ""),
+        "errors": receipt.get("errors", []) if isinstance(receipt.get("errors", []), list) else [],
+        "createdAt": str(receipt.get("createdAt", "") or ""),
+    }
+
+
+def povChainHash(record: dict[str, Any]) -> str:
+    base = {
+        "taskId": str(record.get("taskId", "") or ""),
+        "domain": str(record.get("domain", "") or ""),
+        "rules": list(record.get("rules", []) if isinstance(record.get("rules"), list) else []),
+        "value": record.get("value", {}) if isinstance(record.get("value"), dict) else {},
+        "artifacts": list(record.get("artifacts", []) if isinstance(record.get("artifacts"), list) else []),
+        "prevHash": str(record.get("prevHash", "") or ""),
+        "createdAt": str(record.get("createdAt", "") or ""),
+        "meta": record.get("meta", {}) if isinstance(record.get("meta"), dict) else {},
+    }
+    return canonicalHash(base)
+
+
+def _canonicalJson(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
+
+
+def _normalizeArtifact(item: dict[str, Any]) -> dict[str, Any]:
+    if "artifactId" in item and "payloadHash" in item:
+        return item
+    payload = item.get("payload") if isinstance(item.get("payload"), dict) else item
+    return {
+        "artifactId": str(item.get("artifactId", "") or "art_" + canonicalHash(payload)[:24]),
+        "kind": str(item.get("kind", "evidence") or "evidence"),
+        "source": str(item.get("source", "inline") or "inline"),
+        "payload": payload,
+        "payloadHash": canonicalHash(payload),
+        "createdAt": str(item.get("createdAt", "") or ""),
+        "meta": item.get("meta", {}) if isinstance(item.get("meta"), dict) else {},
+    }
+
+
+def _proofTimeline(
+    payload: dict[str, Any],
+    artifacts: list[dict[str, Any]],
+    povRecords: list[dict[str, Any]],
+    receipts: list[dict[str, Any]],
+    decisions: list[dict[str, Any]],
+    snapshots: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    entries = _cleanDicts(payload.get("timeline", []))
+    for artifact in artifacts:
+        entries.append(
+            {
+                "at": str(artifact.get("createdAt", "") or ""),
+                "kind": "evidence",
+                "ref": str(artifact.get("artifactId", "") or ""),
+                "label": str(artifact.get("kind", "evidence") or "evidence"),
+                "source": str(artifact.get("source", "") or ""),
+            }
+        )
+    for pov in povRecords:
+        entries.append(
+            {
+                "at": str(pov.get("createdAt", "") or ""),
+                "kind": "pov",
+                "ref": str(pov.get("povId", "") or ""),
+                "label": str(pov.get("domain", "proof") or "proof"),
+            }
+        )
+    for receipt in receipts:
+        entries.append(
+            {
+                "at": str(receipt.get("createdAt", "") or ""),
+                "kind": "receipt",
+                "ref": str(receipt.get("receiptId", "") or ""),
+                "label": str(receipt.get("status", "receipt") or "receipt"),
+            }
+        )
+    for decision in decisions:
+        entries.append(
+            {
+                "at": str(decision.get("at", decision.get("createdAt", "")) or ""),
+                "kind": "decision",
+                "ref": str(decision.get("decisionId", decision.get("ref", "")) or ""),
+                "label": str(decision.get("label", decision.get("reason", "decision")) or "decision"),
+            }
+        )
+    for snapshot in snapshots:
+        entries.append(
+            {
+                "at": str(snapshot.get("capturedAt", snapshot.get("at", "")) or ""),
+                "kind": "sourceSnapshot",
+                "ref": str(snapshot.get("snapshotId", snapshot.get("url", "")) or ""),
+                "label": str(snapshot.get("label", "source snapshot") or "source snapshot"),
+            }
+        )
+    return sorted(entries, key=lambda item: (str(item.get("at", "")), str(item.get("kind", "")), str(item.get("ref", ""))))
+
+
+def _proofShare(value: Any) -> dict[str, Any]:
+    raw = value if isinstance(value, dict) else {}
+    formats = raw.get("formats", ["json"]) if isinstance(raw.get("formats", ["json"]), list) else ["json"]
+    share = {
+        "type": str(raw.get("type", "portableCaseFile") or "portableCaseFile"),
+        "label": str(raw.get("label", "From opaque workflow to portable case file.") or ""),
+        "audience": str(raw.get("audience", "external") or "external"),
+        "redacted": bool(raw.get("redacted", True)),
+        "formats": _cleanStrings(formats),
+    }
+    if raw.get("url"):
+        share["url"] = str(raw.get("url") or "")
+    return share
+
+
+def _proofCard(payload: dict[str, Any], packId: str, chainHash: str, base: dict[str, Any]) -> dict[str, Any]:
+    raw = payload.get("proofCard", {}) if isinstance(payload.get("proofCard"), dict) else {}
+    openQuestions = _cleanStrings(raw.get("openQuestions", payload.get("openQuestions", [])))
+    escalation = raw.get("escalation", payload.get("escalation", {}))
+    escalation = escalation if isinstance(escalation, dict) else {}
+    if openQuestions and "recommended" not in escalation:
+        escalation = {"recommended": True, "routeDomain": "proxy", "reason": "openQuestions"}
+    elif not escalation:
+        escalation = {"recommended": False, "routeDomain": "", "reason": ""}
+    evidenceStatus = str(raw.get("evidenceStatus", payload.get("evidenceStatus", "")) or "")
+    if not evidenceStatus:
+        evidenceStatus = _evidenceStatus(base)
+    confidence = raw.get("confidence", payload.get("confidence", None))
+    if confidence is None:
+        confidence = _proofConfidence(base, openQuestions, escalation)
+    cardBase = {
+        "packId": packId,
+        "packHash": chainHash,
+        "title": str(raw.get("title", base.get("title", "Proof card")) or "Proof card"),
+        "summary": str(raw.get("summary", base.get("summary", "")) or ""),
+        "evidenceStatus": evidenceStatus,
+        "confidence": round(max(0.0, min(1.0, float(confidence or 0.0))), 3),
+        "openQuestions": openQuestions,
+        "recommendedRestraint": str(raw.get("recommendedRestraint", payload.get("recommendedRestraint", _restraint(openQuestions, escalation))) or ""),
+        "escalation": escalation,
+    }
+    cardHash = canonicalHash(cardBase)
+    cardId = "card_" + cardHash[:24]
+    return {
+        "cardId": cardId,
+        "kind": "proofCard",
+        **cardBase,
+        "cite": f"picux:proofPack:{packId}#{chainHash[:12]}",
+        "embed": {"href": f"/v1/audit/proofPacks/{packId}", "format": "application/json"},
+        "post": {
+            "title": cardBase["title"],
+            "summary": cardBase["summary"],
+            "evidenceStatus": evidenceStatus,
+            "confidence": cardBase["confidence"],
+        },
+        "cardHash": cardHash,
+    }
+
+
+def _evidenceStatus(base: dict[str, Any]) -> str:
+    if base.get("artifacts") and base.get("pov"):
+        return "verified"
+    if base.get("artifacts"):
+        return "sourceBound"
+    return "needsEvidence"
+
+
+def _proofConfidence(base: dict[str, Any], openQuestions: list[str], escalation: dict[str, Any]) -> float:
+    confidence = 0.35
+    if base.get("artifacts"):
+        confidence += 0.25
+    if base.get("pov"):
+        confidence += 0.20
+    if base.get("decisions"):
+        confidence += 0.10
+    if openQuestions:
+        confidence -= min(0.20, 0.05 * len(openQuestions))
+    if escalation.get("recommended"):
+        confidence -= 0.10
+    return confidence
+
+
+def _restraint(openQuestions: list[str], escalation: dict[str, Any]) -> str:
+    if escalation.get("recommended"):
+        return "escalateBeforePublishing"
+    if openQuestions:
+        return "citeWithOpenQuestions"
+    return "shareableWithSource"
+
+
+def _cleanDicts(value: Any) -> list[dict[str, Any]]:
+    if isinstance(value, dict):
+        return [dict(value)]
+    if not isinstance(value, list):
+        return []
+    return [dict(item) for item in value if isinstance(item, dict)]
+
+
+def _cleanStrings(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value if str(item).strip()]
+
+
+def _proofPackId(value: Any, chainHash: str) -> str:
+    raw = str(value or "")
+    if raw.startswith("pack_") and len(raw) == 29 and all(char in "0123456789abcdef" for char in raw[5:]):
+        return raw
+    return "pack_" + chainHash[:24]
+
+
+def _povInputErrors(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if not str(payload.get("taskId", "") or ""):
+        errors.append("missing:taskId")
+    if not str(payload.get("domain", "") or ""):
+        errors.append("missing:domain")
+    return errors
+
+
+def _amount(value: Any) -> float | None:
+    try:
+        return float(value or 0.0)
+    except (TypeError, ValueError):
+        return None
+
+
+def _limit(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 500))
+
+
+def _time(clock: Clock) -> str:
+    value = clock()
+    if isinstance(value, datetime):
+        return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    return str(value)

picux/benchmarks/__init__.py

@@ -0,0 +1,5 @@
+"""Local benchmark evidence primitives."""
+
+from .local import LocalBenchmark
+
+__all__ = ["LocalBenchmark"]