patchr 0.1.0__py3-none-any.whl

picux/audit/__init__.py

@@ -0,0 +1,31 @@
+"""Audit and observability primitives."""
+
+from .activity import ActivityLog
+from .observability import (
+    BRIDGE_DONE,
+    DOMAIN_METRICS,
+    HARNESS_COLLISION,
+    PAY_SETTLED,
+    RESOLVE_WIN,
+    SIGNAL_ACCEPTED,
+    TASK_CREATED,
+    TASK_DONE,
+    DomainMetrics,
+)
+from .verification import EvidenceArtifact, ProofOfValueRecord, VerificationLedger
+
+__all__ = [
+    "ActivityLog",
+    "BRIDGE_DONE",
+    "DOMAIN_METRICS",
+    "DomainMetrics",
+    "EvidenceArtifact",
+    "HARNESS_COLLISION",
+    "PAY_SETTLED",
+    "ProofOfValueRecord",
+    "RESOLVE_WIN",
+    "SIGNAL_ACCEPTED",
+    "TASK_CREATED",
+    "TASK_DONE",
+    "VerificationLedger",
+]

picux/audit/activity.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+from picux.storage import Keyspace, PicuxPostgresStore
+
+logger = logging.getLogger("picux.audit.activity")
+
+
+class ActivityLog:
+    def __init__(
+        self,
+        redis,
+        *,
+        db: PicuxPostgresStore | None = None,
+        keys: Keyspace | None = None,
+        ttl: int = 60 * 60 * 24 * 30,
+    ) -> None:
+        self.redis = redis
+        self.db = db
+        self.keys = keys or Keyspace()
+        self.ttl = max(3600, int(ttl))
+
+    def log(
+        self,
+        *,
+        taskId: str,
+        userId: str,
+        level: str,
+        action: str,
+        detail: str,
+        meta: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        now = int(time.time())
+        entry = {
+            "ts": now,
+            "level": str(level or "info").upper(),
+            "action": str(action or "").strip(),
+            "detail": str(detail or "").strip(),
+            "meta": meta or {},
+        }
+        payload = json.dumps(entry, ensure_ascii=True, sort_keys=True)
+        try:
+            pipe = self.redis.pipeline()
+            pipe.rpush(self.keys.taskLog(taskId), payload)
+            pipe.expire(self.keys.taskLog(taskId), self.ttl)
+            pipe.zadd(self.keys.userLog(userId), {taskId: now})
+            pipe.expire(self.keys.userLog(userId), self.ttl)
+            pipe.execute()
+        except Exception:
+            logger.exception("activityLogWriteFailed taskId=%s", taskId)
+
+        if self.db is not None:
+            self.db.insertActivity(
+                taskId=taskId,
+                userId=userId,
+                level=entry["level"],
+                action=entry["action"],
+                detail=entry["detail"],
+                meta=entry["meta"],
+            )
+        return entry
+
+    def entries(self, taskId: str, *, limit: int = 100) -> list[dict[str, Any]]:
+        raw = self.redis.lrange(self.keys.taskLog(taskId), max(0, -int(limit)), -1)
+        out: list[dict[str, Any]] = []
+        for item in raw:
+            try:
+                parsed = json.loads(item)
+            except Exception:
+                continue
+            if isinstance(parsed, dict):
+                out.append(parsed)
+        return out
+
+    def recentTasks(self, userId: str, *, limit: int = 10) -> list[str]:
+        return [str(item) for item in self.redis.zrevrange(self.keys.userLog(userId), 0, max(0, int(limit) - 1))]
+
+    def timeline(self, taskId: str, *, includeThoughts: bool = False, limit: int = 100) -> str:
+        rows = self.entries(taskId, limit=limit)
+        lines = [f"TASK LOG: {taskId}"]
+        if not rows:
+            return "\n".join([*lines, "- no entries"])
+        for row in rows:
+            level = str(row.get("level", "INFO")).upper()
+            if level == "THOUGHT" and not includeThoughts:
+                continue
+            ts = int(row.get("ts", 0) or 0)
+            hhmm = time.strftime("%H:%M", time.gmtime(ts)) if ts else "--:--"
+            lines.append(f"{hhmm} {level} {row.get('action', 'ACTION')}: {row.get('detail', '-')}")
+        if len(lines) == 1:
+            lines.append("- no user-facing entries")
+        return "\n".join(lines)
+

picux/audit/observability.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Iterable
+
+from picux.storage import Keyspace
+
+
+TASK_CREATED = "taskCreated"
+TASK_DONE = "taskDone"
+RESOLVE_WIN = "resolveWin"
+BRIDGE_DONE = "bridgeDone"
+PAY_SETTLED = "paySettled"
+SIGNAL_ACCEPTED = "signalAccepted"
+HARNESS_COLLISION = "harnessCollision"
+
+DOMAIN_METRICS = (
+    TASK_CREATED,
+    TASK_DONE,
+    RESOLVE_WIN,
+    BRIDGE_DONE,
+    PAY_SETTLED,
+    SIGNAL_ACCEPTED,
+    HARNESS_COLLISION,
+)
+
+
+class DomainMetrics:
+    def __init__(self, redis, *, keys: Keyspace | None = None, ttl: int = 60 * 60 * 24 * 120) -> None:
+        self.redis = redis
+        self.keys = keys or Keyspace()
+        self.ttl = max(3600, int(ttl))
+
+    def inc(self, metric: str, amount: int = 1) -> None:
+        if metric not in DOMAIN_METRICS:
+            return
+        value = int(amount or 0)
+        if value <= 0:
+            return
+        key = self.keys.metric(metric)
+        pipe = self.redis.pipeline()
+        pipe.incrby(key, value)
+        pipe.expire(key, self.ttl)
+        pipe.set(f"{key}:updatedAt", str(int(time.time())), ex=self.ttl)
+        pipe.execute()
+
+    def snap(self, metrics: Iterable[str] = DOMAIN_METRICS) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for metric in metrics:
+            try:
+                out[metric] = int(self.redis.get(self.keys.metric(metric)) or 0)
+            except Exception:
+                out[metric] = 0
+        return out
+

picux/audit/verification/__init__.py

@@ -0,0 +1,21 @@
+"""Audit verification artifacts and proof ledger."""
+
+from .ledger import (
+    EvidenceArtifact,
+    ProofOfValueRecord,
+    VerificationLedger,
+    canonicalHash,
+    povChainHash,
+    receiptHash,
+    receiptId,
+)
+
+__all__ = [
+    "EvidenceArtifact",
+    "ProofOfValueRecord",
+    "VerificationLedger",
+    "canonicalHash",
+    "povChainHash",
+    "receiptHash",
+    "receiptId",
+]