pramana-core 0.0.1__tar.gz

pramana_core-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.pyc
+.pramana/
+.pytest_cache/
+web/node_modules/
+web/dist/
+# Secrets. The trailing slash this line used to have (`.env/`) matched only a
+# *directory* named .env, never the file — which is how .env ended up committed
+# in a1434d1 with a live Postgres password and S3 keys in it. Adding it here
+# does not remove it from history: those credentials must be rotated, and the
+# commit purged, separately.
+.env
+.env.*
+!.env.example

pramana_core-0.0.1/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.5
+Name: pramana-core
+Version: 0.0.1
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42
+Requires-Dist: pramana-proto

pramana_core-0.0.1/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "pramana-core"
+version = "0.0.1"
+requires-python = ">=3.12"
+dependencies = ["pramana-proto", "cryptography>=42"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pramana_core"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[dependency-groups]
+dev = ["pytest"]

pramana_core-0.0.1/src/pramana_core/chain.py

@@ -0,0 +1,36 @@
+"""Server-side hash chain (docs/plan.md §3.4, D2). The SDK never computes
+prev_hash/this_hash — only the log writer (services/ingest) does, using these
+functions, under a per-trace lock.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pramana_proto.v1.event_pb2 import Event
+
+from pramana_core.event_json import event_to_dict
+from pramana_core.hashing import canonical_json_bytes, sha256_hex
+
+GENESIS_HASH = ""
+
+
+def event_fields_for_hash(event_dict: dict[str, Any], prev_hash: str) -> dict[str, Any]:
+    """The exact recipe verify-cli must replicate against a JSON-dict-shaped
+    event (docs/plan.md M4): drop this_hash, override prev_hash, hash the
+    rest. Split out from `compute_this_hash` so both the live proto path and
+    a pure-JSON verifier hash identically off one definition.
+    """
+    fields = dict(event_dict)
+    fields.pop("this_hash", None)
+    fields["prev_hash"] = prev_hash
+    return fields
+
+
+def compute_this_hash(event: Event, prev_hash: str) -> str:
+    """sha256(canonical(event minus this_hash)), per docs/LLD.md §6.
+    prev_hash is taken as a parameter (not read from `event`) so the caller
+    cannot accidentally hash a stale/forged prev_hash field.
+    """
+    fields = event_fields_for_hash(event_to_dict(event), prev_hash)
+    return sha256_hex(canonical_json_bytes(fields))

pramana_core-0.0.1/src/pramana_core/errors.py

@@ -0,0 +1,24 @@
+"""Domain errors. `Divergence` is not an Error subclass by accident — it is a
+signal (docs/LLD.md §4b: "divergence is a product feature"), not a fault.
+"""
+
+from __future__ import annotations
+
+
+class PramanaError(Exception):
+    """Base for genuine faults."""
+
+
+class ReplayError(PramanaError):
+    """Replay cannot proceed at all (e.g. no recorded event at this position)."""
+
+
+class Divergence(Exception):
+    """Replayed input != recorded input. Raised only under HARD_STOP policy;
+    under CONTINUE_AND_FLAG it is recorded, not raised.
+    """
+
+    def __init__(self, call_site_id: str, call_site_ordinal: int, message: str = ""):
+        self.call_site_id = call_site_id
+        self.call_site_ordinal = call_site_ordinal
+        super().__init__(message or f"divergence at {call_site_id}#{call_site_ordinal}")

pramana_core-0.0.1/src/pramana_core/event_json.py

@@ -0,0 +1,19 @@
+"""The one Event-to-dict conversion (docs/plan.md §3.1: "JSON API keys ==
+proto field names"). Shared by services/api and services/evidence so an
+evidence bundle's event shape is byte-identical to what the query API
+already serves — verify-cli re-hashes this exact shape, so any drift here
+would make a legitimate bundle look tampered.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.protobuf.json_format import MessageToDict
+from pramana_proto.v1.event_pb2 import Event
+
+
+def event_to_dict(event: Event) -> dict[str, Any]:
+    # dict(...): MessageToDict types as Any (google.protobuf has no stubs
+    # here) — the wrapper gives mypy a concrete dict[Any, Any] to return.
+    return dict(MessageToDict(event, preserving_proto_field_name=True, always_print_fields_with_no_presence=True))

pramana_core-0.0.1/src/pramana_core/hashing.py

@@ -0,0 +1,43 @@
+"""The one canonical-bytes + hash primitive. Shared by the SDK canonicalizer
+(input_hash, docs/plan.md §3.2) and the server-side chain hasher (this_hash,
+docs/plan.md §3.4). Do not duplicate this logic anywhere else.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from typing import Any
+
+
+class NonFiniteValueError(ValueError):
+    """Raised when a NaN/Infinity value would otherwise be silently coerced."""
+
+
+def _reject_non_finite(obj: Any) -> Any:
+    if isinstance(obj, float) and not math.isfinite(obj):
+        raise NonFiniteValueError(f"non-finite float in canonicalized payload: {obj!r}")
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            _reject_non_finite(k)
+            _reject_non_finite(v)
+    elif isinstance(obj, (list, tuple)):
+        for v in obj:
+            _reject_non_finite(v)
+    return obj
+
+
+def canonical_json_bytes(obj: Any) -> bytes:
+    """Steps 3-5 of docs/plan.md §3.2: sort_keys json dumps, reject NaN/Infinity,
+    utf-8 encode. Redaction and per-vendor exclusion (steps 1-2) are the caller's
+    job — they are adapter-specific, not generic.
+    """
+    _reject_non_finite(obj)
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()

pramana_core-0.0.1/src/pramana_core/ids.py

@@ -0,0 +1,19 @@
+"""uuid v7 (time-sortable), per docs/LLD.md §1 event_id. Python's stdlib gains
+`uuid.uuid7()` in 3.14; this workspace targets 3.12+, so a small stdlib-only
+implementation (RFC 9562) stands in until the floor is raised.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+
+
+def uuid7() -> str:
+    ts_ms = time.time_ns() // 1_000_000
+    rand = os.urandom(10)
+    b = bytearray(ts_ms.to_bytes(6, "big") + rand)
+    b[6] = (b[6] & 0x0F) | 0x70  # version 7
+    b[8] = (b[8] & 0x3F) | 0x80  # RFC 4122 variant
+    return str(uuid.UUID(bytes=bytes(b)))

pramana_core-0.0.1/src/pramana_core/logging.py

@@ -0,0 +1,107 @@
+"""Structured JSON request logging, shared by every http.server-based service.
+
+Both services overrode `log_message` to a no-op and imported no logging
+library at all (docs/plan.md §21.6) — silence was fine until something broke,
+at which point there was nothing to read. One JSON object per line on stdout
+is enough: every container platform (Cloud Run, ECS, plain Docker) already
+collects stdout, and Cloud-Logging-style backends parse JSON lines into
+queryable fields for free — no vendor, no dependency, no cost.
+
+Never feed this payload contents, prompts, or the Authorization header —
+request_id, tenant_id, method, path, status, and duration_ms are the fields a
+caller should set.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import time
+import uuid
+from typing import Any
+
+
+class _JsonFormatter(logging.Formatter):
+    def __init__(self, service: str) -> None:
+        super().__init__()
+        self._service = service
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
+            "level": record.levelname,
+            "service": self._service,
+            "message": record.getMessage(),
+        }
+        for key in ("request_id", "tenant_id", "method", "path", "status", "duration_ms", "exception"):
+            value = getattr(record, key, None)
+            if value is not None:
+                payload[key] = value
+        return json.dumps(payload)
+
+
+def configure_json_logging(service: str) -> logging.Logger:
+    """Idempotent: safe to call more than once (tests, or a re-exec) without
+    stacking duplicate handlers and doubling every line.
+    """
+    logger = logging.getLogger(service)
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(_JsonFormatter(service))
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+        logger.propagate = False
+    return logger
+
+
+class RequestLoggingMixin:
+    """Mix into a `BaseHTTPRequestHandler` subclass, ahead of it in the MRO,
+    so this class's `handle_one_request`/`log_message` are the ones that run.
+
+    Set the class attribute `logger` (from `configure_json_logging`) on the
+    concrete handler. Set `self._log_tenant = tenant_id` once auth resolves,
+    if the route has a tenant, so it lands on the request's own log line
+    instead of a separate one.
+    """
+
+    logger: logging.Logger
+
+    def handle_one_request(self) -> None:
+        # Runs once per request even on a keep-alive connection serving
+        # several — resets the clock and identity per request rather than
+        # for the whole TCP connection.
+        self._req_start = time.monotonic()
+        self._log_tenant: str | None = None
+        self._req_id = uuid.uuid4().hex[:12]
+        super().handle_one_request()  # type: ignore[misc]
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        # BaseHTTPRequestHandler.log_request calls this as
+        # log_message('"%s" %s %s', requestline, code, size) — args[1] is the
+        # status code stdlib already parsed out for us.
+        status = args[1] if len(args) > 1 else None
+        duration_ms = round((time.monotonic() - getattr(self, "_req_start", time.monotonic())) * 1000, 1)
+        self.logger.info(
+            "request",
+            extra={
+                "request_id": getattr(self, "_req_id", None),
+                "tenant_id": getattr(self, "_log_tenant", None),
+                "method": getattr(self, "command", None),
+                "path": getattr(self, "path", None),
+                "status": status,
+                "duration_ms": duration_ms,
+            },
+        )
+
+    def log_exception(self, exc: BaseException) -> None:
+        self.logger.error(
+            "unhandled exception",
+            extra={
+                "request_id": getattr(self, "_req_id", None),
+                "tenant_id": getattr(self, "_log_tenant", None),
+                "method": getattr(self, "command", None),
+                "path": getattr(self, "path", None),
+                "exception": type(exc).__name__,
+            },
+        )

pramana_core-0.0.1/src/pramana_core/merkle.py

@@ -0,0 +1,41 @@
+"""Merkle root over a segment's this_hashes (docs/LLD.md §6, docs/plan.md M4).
+
+RFC 6962 (Certificate Transparency) tree shape, not the naive "duplicate the
+last node when odd" construction — the naive version has a known
+second-preimage weakness (a non-leaf node's hash can be replayed as if it
+were a leaf). RFC 6962's domain-separated prefixes (0x00 leaf, 0x01 node)
+close that off.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def _leaf_hash(data: bytes) -> bytes:
+    return hashlib.sha256(b"\x00" + data).digest()
+
+
+def _node_hash(left: bytes, right: bytes) -> bytes:
+    return hashlib.sha256(b"\x01" + left + right).digest()
+
+
+def _mth(leaves: list[bytes]) -> bytes:
+    n = len(leaves)
+    if n == 0:
+        return hashlib.sha256(b"").digest()
+    if n == 1:
+        return leaves[0]
+    k = 1
+    while k * 2 < n:
+        k *= 2
+    return _node_hash(_mth(leaves[:k]), _mth(leaves[k:]))
+
+
+def merkle_root(leaf_hashes_hex: list[str]) -> str:
+    """leaf_hashes_hex are the pre-existing this_hash hex strings (already
+    sha256 digests); this hashes them again as RFC 6962 leaves — the input
+    to a leaf is arbitrary bytes, not necessarily unhashed data.
+    """
+    leaves = [_leaf_hash(bytes.fromhex(h)) for h in leaf_hashes_hex]
+    return _mth(leaves).hex()

pramana_core-0.0.1/src/pramana_core/metrics.py

@@ -0,0 +1,66 @@
+"""docs/plan.md §5.2 / §12 item 4: `pramana_<component>_<metric>_<unit>`
+naming, wired to something real for the first time. A Prometheus text
+exposition writer, not the `prometheus_client` dependency — the format is a
+handful of lines (https://prometheus.io/docs/instrumenting/exposition_formats/)
+and every other transport in this repo is stdlib `http.server`; a dependency
+buys nothing here that hand-rolling doesn't already give for free.
+
+One process-wide registry per process (ingest and api each import this
+module and get their own, since they're separate processes) — a counter
+survives for the life of the process, same as any in-memory Prometheus
+client would give you.
+"""
+
+from __future__ import annotations
+
+import threading
+
+_lock = threading.Lock()
+_counters: dict[str, Counter] = {}
+
+
+class Counter:
+    """Monotonic counter, thread-safe — both servers here are
+    ThreadingHTTPServer, so increments can race from concurrent requests.
+    """
+
+    def __init__(self, name: str, help_text: str):
+        self.name = name
+        self.help_text = help_text
+        self._value = 0
+        self._lock = threading.Lock()
+
+    def inc(self, amount: int = 1) -> None:
+        with self._lock:
+            self._value += amount
+
+    @property
+    def value(self) -> int:
+        return self._value
+
+
+def counter(name: str, help_text: str) -> Counter:
+    """Registers `name` on first call; returns the same Counter on every
+    later call with that name — call sites don't need to hold onto a module-
+    level reference themselves, though most will for the `.inc()` call.
+    """
+    with _lock:
+        existing = _counters.get(name)
+        if existing is not None:
+            return existing
+        c = Counter(name, help_text)
+        _counters[name] = c
+        return c
+
+
+def render_text() -> bytes:
+    """Prometheus text exposition format. Just counters today — a gauge or
+    histogram type is a `# TYPE` line away whenever one is actually needed."""
+    with _lock:
+        snapshot = list(_counters.values())
+    lines = []
+    for c in snapshot:
+        lines.append(f"# HELP {c.name} {c.help_text}")
+        lines.append(f"# TYPE {c.name} counter")
+        lines.append(f"{c.name} {c.value}")
+    return ("\n".join(lines) + "\n").encode()

pramana_core-0.0.1/src/pramana_core/sequencer.py

@@ -0,0 +1,61 @@
+"""Merge multiple agents' event streams into one deterministic total order
+consistent with the vector-clock partial order (docs/LLD.md §5, docs/plan.md
+repo layout: "sequencer — inline in ingest until then" — this runs at
+replay/query time, not the write path; see services/ingest for why the
+write path stays arrival-order).
+
+Kahn's algorithm: topological sort on the happens-before DAG, tie-broken by
+(trace_id, agent_id, logical_seq) whenever multiple events are simultaneously
+"ready" (docs/LLD.md §5: "tie-break by (trace_id, agent_id, logical_seq) for
+determinism").
+"""
+
+from __future__ import annotations
+
+from pramana_proto.v1.event_pb2 import Event
+
+from pramana_core.vclock import VectorClock
+
+
+def _tie_break_key(event: Event) -> tuple[str, str, int]:
+    return (event.trace_id, event.agent_id, event.logical_seq)
+
+
+def total_order(events: list[Event]) -> list[Event]:
+    """`events` are anything with `.vclock` (packed bytes), `.trace_id`,
+    `.agent_id`, `.logical_seq` — i.e. proto Event objects. Pairwise
+    happens-before is used to build edges: O(n^2) comparisons, which is fine
+    at the scale a single trace's events actually reach; optimize only if a
+    benchmark says otherwise (docs/plan.md §3.6's own standard).
+    """
+    n = len(events)
+    clocks = [VectorClock.from_bytes(e.vclock) for e in events]
+
+    # successors[i] = set of j such that i happens-before j
+    successors: list[set[int]] = [set() for _ in range(n)]
+    in_degree = [0] * n
+    for i in range(n):
+        for j in range(n):
+            if i != j and clocks[i].happens_before(clocks[j]):
+                successors[i].add(j)
+                in_degree[j] += 1
+
+    remaining = set(range(n))
+    ordered: list[Event] = []
+    while remaining:
+        ready = sorted(
+            (i for i in remaining if in_degree[i] == 0),
+            key=lambda i: _tie_break_key(events[i]),
+        )
+        if not ready:
+            # A cycle would mean corrupted/inconsistent vclocks (e.g. a
+            # MSG_RECV that never merged its sender's clock). Not a normal
+            # outcome — surface it rather than silently truncating the order.
+            raise ValueError("cycle detected in happens-before relation — inconsistent vector clocks")
+        chosen = ready[0]
+        ordered.append(events[chosen])
+        remaining.discard(chosen)
+        for j in successors[chosen]:
+            in_degree[j] -= 1
+
+    return ordered

pramana_core-0.0.1/src/pramana_core/signing.py

@@ -0,0 +1,50 @@
+"""Ed25519 sign/verify (docs/LLD.md §6, docs/plan.md M4). Stdlib has no
+modern asymmetric crypto, so this is the one new dependency: `cryptography`.
+
+Trust model: the signature proves the platform's private key signed this
+data — nothing more. A public key found *inside* a bundle is not trusted for
+verification; the verifier must already hold the platform's public key from
+an out-of-band channel (this is what makes offline, no-server verification
+meaningful — see verify-cli).
+"""
+
+from __future__ import annotations
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+
+def generate_keypair() -> tuple[bytes, bytes]:
+    """Returns (private_key_bytes, public_key_bytes), both raw 32-byte encodings."""
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    priv_bytes = private_key.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    pub_bytes = public_key.public_bytes(
+        encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw
+    )
+    return priv_bytes, pub_bytes
+
+
+def public_key_from_private(private_key_bytes: bytes) -> bytes:
+    public_key = Ed25519PrivateKey.from_private_bytes(private_key_bytes).public_key()
+    return public_key.public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw)
+
+
+def sign(private_key_bytes: bytes, message: bytes) -> bytes:
+    return Ed25519PrivateKey.from_private_bytes(private_key_bytes).sign(message)
+
+
+def verify(public_key_bytes: bytes, message: bytes, signature: bytes) -> bool:
+    try:
+        Ed25519PublicKey.from_public_bytes(public_key_bytes).verify(signature, message)
+        return True
+    except InvalidSignature:
+        return False

pramana_core-0.0.1/src/pramana_core/vclock.py

@@ -0,0 +1,49 @@
+"""Vector clocks for cross-agent causal ordering (docs/LLD.md §5, the moat).
+
+Rules, maintained per agent:
+  1. Local event:        vclock[self] += 1
+  2. On MSG_SEND:        tick (rule 1), then attach the ticked clock to the message
+  3. On MSG_RECV:        vclock = elementwise_max(vclock, msg.vclock), then vclock[self] += 1
+
+Packed as canonical JSON (sorted-key), not a bespoke binary format — this is
+Phase 2's first cut; a real varint packing is a measured optimization for
+later, not a default (docs/plan.md §3.6's own reasoning applied here).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from pramana_core.hashing import canonical_json_bytes
+
+
+@dataclass(frozen=True)
+class VectorClock:
+    counts: dict[str, int] = field(default_factory=dict)
+
+    def tick(self, agent_id: str) -> VectorClock:
+        return VectorClock({**self.counts, agent_id: self.counts.get(agent_id, 0) + 1})
+
+    def merge(self, other: VectorClock) -> VectorClock:
+        agents = set(self.counts) | set(other.counts)
+        return VectorClock({a: max(self.counts.get(a, 0), other.counts.get(a, 0)) for a in agents})
+
+    def happens_before(self, other: VectorClock) -> bool:
+        """self -> other: every component of self <= other, and at least one strictly less."""
+        agents = set(self.counts) | set(other.counts)
+        le_all = all(self.counts.get(a, 0) <= other.counts.get(a, 0) for a in agents)
+        lt_some = any(self.counts.get(a, 0) < other.counts.get(a, 0) for a in agents)
+        return le_all and lt_some
+
+    def concurrent_with(self, other: VectorClock) -> bool:
+        return self != other and not self.happens_before(other) and not other.happens_before(self)
+
+    def to_bytes(self) -> bytes:
+        return canonical_json_bytes(self.counts)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> VectorClock:
+        if not data:
+            return cls()
+        return cls(json.loads(data))

pramana_core-0.0.1/src/pramana_core/wsgi.py

@@ -0,0 +1,146 @@
+"""Runs an existing `http.server.BaseHTTPRequestHandler` subclass under any
+WSGI server (docs/plan.md §21.4), so gunicorn can host `pramana-api` and
+`pramana-ingest` in production without `ThreadingHTTPServer`'s unbounded
+thread-per-connection model, no request timeout, and no graceful shutdown.
+
+Both services' routing — auth, RBAC, CORS, error handling — already lives on
+their `Handler` classes and is covered by ~300 tests exercising it over real
+HTTP. Re-deriving that logic a second time as plain WSGI functions would risk
+the two implementations silently drifting apart the first time one of them
+changes. Instead, this drives the *same* `Handler` class through a loopback,
+in-memory "socket" — `socketserver.StreamRequestHandler` only needs a few
+methods off whatever object it's given (`makefile` for reading, `sendall` for
+writing), which is a much smaller surface than reimplementing routing.
+
+The one property this must not break: a handler that checks Content-Length
+*before* reading the body (ingest's whole size-cap exists to stop a
+decompression bomb from being read into memory at all) must still get to run
+that check before any of the body is pulled from the real WSGI input stream.
+So the body is read lazily, on demand, exactly like a real socket would
+deliver it — never buffered up front by this adapter.
+"""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Callable, Iterable
+from http.server import BaseHTTPRequestHandler
+from typing import Any
+
+
+class _LazyBodyReader(io.RawIOBase):
+    """`.readline()` is served from the pre-built header block (small, fixed
+    size); once that's exhausted, `.read(n)` falls through to the real WSGI
+    body stream, pulling exactly the `n` bytes the handler asks for and no
+    more — the same shape a real socket read has.
+    """
+
+    def __init__(self, header_block: bytes, wsgi_input: Any):
+        self._buf = header_block
+        self._pos = 0
+        self._wsgi_input = wsgi_input
+
+    def readable(self) -> bool:
+        return True
+
+    def readline(self, limit: int | None = -1) -> bytes:
+        if self._pos < len(self._buf):
+            end = self._buf.find(b"\n", self._pos)
+            end = len(self._buf) if end == -1 else end + 1
+            if limit is not None and limit >= 0:
+                end = min(end, self._pos + limit)
+            line = self._buf[self._pos : end]
+            self._pos = end
+            return line
+        return bytes(self._wsgi_input.readline() if limit is None or limit < 0 else self._wsgi_input.readline(limit))
+
+    def read(self, size: int = -1) -> bytes:
+        if self._pos < len(self._buf):
+            remaining = self._buf[self._pos :]
+            self._pos = len(self._buf)
+            if size < 0:
+                return bytes(remaining) + bytes(self._wsgi_input.read())
+            if len(remaining) >= size:
+                # Only reachable if a caller reads less than a full line at a
+                # time during header parsing, which http.client doesn't do —
+                # kept correct anyway rather than assumed unreachable.
+                leftover, consumed = remaining[size:], remaining[:size]
+                self._buf = leftover + self._buf[len(self._buf) :]
+                self._pos = 0
+                return consumed
+            return bytes(remaining) + bytes(self._wsgi_input.read(size - len(remaining)))
+        return bytes(self._wsgi_input.read() if size < 0 else self._wsgi_input.read(size))
+
+
+class _FakeConnection:
+    """Enough of a socket for `socketserver.StreamRequestHandler.setup()`:
+    `.makefile()` for the read side. The write side never calls `.makefile`
+    at all — `BaseHTTPRequestHandler`'s default `wbufsize = 0` makes
+    `StreamRequestHandler` wrap this object directly in a `_SocketWriter`,
+    which calls `.sendall()` — so that's the only write method needed here.
+    """
+
+    def __init__(self, header_block: bytes, wsgi_input: Any):
+        self._reader = _LazyBodyReader(header_block, wsgi_input)
+        self.response = bytearray()
+
+    def makefile(self, mode: str, *args: Any, **kwargs: Any) -> Any:
+        if "r" not in mode:
+            raise AssertionError(f"unexpected makefile mode {mode!r} — see module docstring")
+        return self._reader
+
+    def sendall(self, data: bytes) -> None:
+        self.response.extend(data)
+
+
+def _environ_to_header_block(environ: dict[str, Any]) -> bytes:
+    method = environ["REQUEST_METHOD"]
+    path = environ.get("PATH_INFO", "") or "/"
+    qs = environ.get("QUERY_STRING", "")
+    target = f"{path}?{qs}" if qs else path
+    lines = [f"{method} {target} HTTP/1.1"]
+    for key, value in environ.items():
+        if key.startswith("HTTP_"):
+            header = key[len("HTTP_") :].replace("_", "-").title()
+            lines.append(f"{header}: {value}")
+    if environ.get("CONTENT_TYPE"):
+        lines.append(f"Content-Type: {environ['CONTENT_TYPE']}")
+    if environ.get("CONTENT_LENGTH"):
+        lines.append(f"Content-Length: {environ['CONTENT_LENGTH']}")
+    # Exactly one request per WSGI call — nothing here models keep-alive, and
+    # this line is what makes handle()'s request loop stop after the first.
+    lines.append("Connection: close")
+    return ("\r\n".join(lines) + "\r\n\r\n").encode("latin-1")
+
+
+def make_wsgi_app(
+    handler_cls: type[BaseHTTPRequestHandler], server: Any
+) -> Callable[[dict[str, Any], Callable[..., Any]], Iterable[bytes]]:
+    """`handler_cls` is a `BaseHTTPRequestHandler` subclass, e.g. one of this
+    project's `make_handler(...)` results. `server` only needs to satisfy
+    whatever the handler class actually reads off `self.server` — neither
+    service's routes do, today.
+    """
+
+    def app(environ: dict[str, Any], start_response: Callable[..., Any]) -> Iterable[bytes]:
+        header_block = _environ_to_header_block(environ)
+        conn = _FakeConnection(header_block, environ["wsgi.input"])
+        client_address = (environ.get("REMOTE_ADDR", ""), 0)
+        # `conn` duck-types the small slice of `socket.socket` that
+        # StreamRequestHandler.setup() actually calls (see class docstring) —
+        # it is not one, hence the cast-by-Any rather than a real socket.
+        handler_cls(conn, client_address, server)  # type: ignore[arg-type]
+
+        status_line, _, rest = bytes(conn.response).partition(b"\r\n")
+        raw_headers, _, body = rest.partition(b"\r\n\r\n")
+        status = status_line.decode("latin-1").split(" ", 1)[1]  # "HTTP/1.1 200 OK" -> "200 OK"
+        headers = []
+        for line in raw_headers.split(b"\r\n"):
+            if not line:
+                continue
+            name, _, value = line.partition(b":")
+            headers.append((name.decode("latin-1").strip(), value.decode("latin-1").strip()))
+        start_response(status, headers)
+        return [body]
+
+    return app

pramana_core-0.0.1/tests/test_chain.py

@@ -0,0 +1,42 @@
+from pramana_core.chain import compute_this_hash
+from pramana_proto.v1.event_pb2 import LLM_CALL, Event
+
+
+def make_event(**overrides) -> Event:
+    defaults = {
+        "event_id": "e1",
+        "tenant_id": "t1",
+        "trace_id": "run-1",
+        "agent_id": "agent-1",
+        "call_site_id": "cs1",
+        "logical_seq": 1,
+        "kind": LLM_CALL,
+        "input_hash": "ih1",
+        "payload_ref": "pr1",
+        "ts_wall_ns": 123,
+        "call_site_ordinal": 0,
+    }
+    defaults.update(overrides)
+    return Event(**defaults)
+
+
+def test_same_event_and_prev_hash_hash_equal():
+    e = make_event()
+    assert compute_this_hash(e, "prev-abc") == compute_this_hash(e, "prev-abc")
+
+
+def test_different_prev_hash_changes_this_hash():
+    e = make_event()
+    assert compute_this_hash(e, "prev-a") != compute_this_hash(e, "prev-b")
+
+
+def test_this_hash_field_on_event_is_ignored_as_input():
+    e1 = make_event()
+    e2 = make_event(this_hash="whatever-junk")
+    assert compute_this_hash(e1, "p") == compute_this_hash(e2, "p")
+
+
+def test_tampering_any_field_changes_hash():
+    base = compute_this_hash(make_event(), "p")
+    tampered = compute_this_hash(make_event(input_hash="different"), "p")
+    assert base != tampered

pramana_core-0.0.1/tests/test_hashing.py

@@ -0,0 +1,31 @@
+import math
+
+import pytest
+from pramana_core.hashing import NonFiniteValueError, canonical_json_bytes, sha256_hex
+
+
+def test_key_order_does_not_affect_bytes():
+    a = canonical_json_bytes({"b": 1, "a": 2})
+    b = canonical_json_bytes({"a": 2, "b": 1})
+    assert a == b
+
+
+def test_unicode_is_preserved_not_escaped():
+    out = canonical_json_bytes({"name": "café"})
+    assert "café".encode() in out
+
+
+def test_rejects_nan():
+    with pytest.raises(NonFiniteValueError):
+        canonical_json_bytes({"x": float("nan")})
+
+
+def test_rejects_infinity_nested():
+    with pytest.raises(NonFiniteValueError):
+        canonical_json_bytes({"x": [1, {"y": math.inf}]})
+
+
+def test_sha256_hex_is_deterministic():
+    data = canonical_json_bytes({"a": 1})
+    assert sha256_hex(data) == sha256_hex(data)
+    assert len(sha256_hex(data)) == 64

pramana_core-0.0.1/tests/test_ids.py

@@ -0,0 +1,19 @@
+import time
+import uuid
+
+from pramana_core.ids import uuid7
+
+
+def test_uuid7_is_valid_uuid_version_7():
+    u = uuid.UUID(uuid7())
+    assert u.version == 7
+
+
+def test_uuid7_is_time_sortable():
+    # one per millisecond — uuid7 only orders at millisecond granularity;
+    # ties within the same millisecond break on random bits, not time.
+    ids = []
+    for _ in range(5):
+        ids.append(uuid7())
+        time.sleep(0.002)
+    assert ids == sorted(ids)

pramana_core-0.0.1/tests/test_merkle.py

@@ -0,0 +1,42 @@
+import hashlib
+
+from pramana_core.merkle import merkle_root
+
+
+def h(s: str) -> str:
+    return hashlib.sha256(s.encode()).hexdigest()
+
+
+def test_empty_is_deterministic():
+    assert merkle_root([]) == merkle_root([])
+
+
+def test_single_leaf():
+    root = merkle_root([h("a")])
+    assert len(root) == 64
+    assert root != h("a")  # leaf hash is domain-separated, not the raw hash
+
+
+def test_order_matters():
+    root1 = merkle_root([h("a"), h("b")])
+    root2 = merkle_root([h("b"), h("a")])
+    assert root1 != root2
+
+
+def test_deterministic_across_calls():
+    leaves = [h("a"), h("b"), h("c"), h("d"), h("e")]
+    assert merkle_root(leaves) == merkle_root(leaves)
+
+
+def test_changing_one_leaf_changes_root():
+    leaves = [h("a"), h("b"), h("c")]
+    tampered = [h("a"), h("TAMPERED"), h("c")]
+    assert merkle_root(leaves) != merkle_root(tampered)
+
+
+def test_non_power_of_two_leaf_counts():
+    # RFC 6962 shape handles any n, not just powers of 2.
+    for n in range(1, 12):
+        leaves = [h(str(i)) for i in range(n)]
+        root = merkle_root(leaves)
+        assert len(root) == 64

pramana_core-0.0.1/tests/test_metrics.py

@@ -0,0 +1,32 @@
+"""docs/plan.md §12 item 4."""
+
+from __future__ import annotations
+
+from pramana_core import metrics
+
+
+def test_counter_starts_at_zero_and_increments():
+    c = metrics.counter(f"test_counter_{id(object())}", "a test counter")
+    assert c.value == 0
+    c.inc()
+    c.inc(4)
+    assert c.value == 5
+
+
+def test_counter_is_a_singleton_per_name():
+    name = f"test_singleton_{id(object())}"
+    a = metrics.counter(name, "help a")
+    b = metrics.counter(name, "help b")  # help text ignored on re-registration
+    a.inc(3)
+    assert b.value == 3
+    assert a is b
+
+
+def test_render_text_includes_help_type_and_value():
+    name = f"test_render_{id(object())}"
+    c = metrics.counter(name, "renders correctly")
+    c.inc(7)
+    text = metrics.render_text().decode()
+    assert f"# HELP {name} renders correctly" in text
+    assert f"# TYPE {name} counter" in text
+    assert f"{name} 7" in text

pramana_core-0.0.1/tests/test_sequencer.py

@@ -0,0 +1,128 @@
+import pytest
+from pramana_core.sequencer import total_order
+from pramana_core.vclock import VectorClock
+from pramana_proto.v1.event_pb2 import LLM_CALL, MSG_RECV, MSG_SEND, Event
+
+
+def make_event(agent_id, seq, vclock: VectorClock, trace_id="t", **overrides):
+    defaults = {
+        "event_id": f"{agent_id}-{seq}",
+        "tenant_id": "t1",
+        "trace_id": trace_id,
+        "agent_id": agent_id,
+        "call_site_id": "cs1",
+        "call_site_ordinal": seq,
+        "logical_seq": seq,
+        "kind": LLM_CALL,
+        "input_hash": "ih",
+        "payload_ref": "pr",
+        "ts_wall_ns": seq,
+        "vclock": vclock.to_bytes(),
+    }
+    defaults.update(overrides)
+    return Event(**defaults)
+
+
+def test_single_agent_local_events_stay_in_program_order():
+    vc = VectorClock()
+    events = []
+    for i in range(5):
+        vc = vc.tick("a")
+        events.append(make_event("a", i, vc))
+
+    # shuffle input order — total_order must still recover program order
+    ordered = total_order([events[3], events[0], events[4], events[1], events[2]])
+    assert [e.event_id for e in ordered] == [e.event_id for e in events]
+
+
+def test_message_send_before_receive_lld_worked_example():
+    # A:[1,0,0] --handoff--> B:[1,1,0] --tool--> C:[1,1,1] --result--> A:[2,1,1]
+    vc_a1 = VectorClock().tick("A")
+    send = make_event("A", 0, vc_a1, kind=MSG_SEND)
+
+    vc_b1 = VectorClock().merge(vc_a1).tick("B")
+    recv_b = make_event("B", 0, vc_b1, kind=MSG_RECV)
+
+    vc_c1 = VectorClock().merge(vc_b1).tick("C")
+    recv_c = make_event("C", 0, vc_c1, kind=MSG_RECV)
+
+    vc_a2 = vc_a1.merge(vc_c1).tick("A")
+    result_a = make_event("A", 1, vc_a2, kind=MSG_RECV)
+
+    ordered = total_order([result_a, recv_c, send, recv_b])
+    assert [e.event_id for e in ordered] == ["A-0", "B-0", "C-0", "A-1"]
+
+
+def test_concurrent_events_break_ties_by_trace_agent_seq():
+    vc_a = VectorClock({"a": 5})  # unrelated components — neither happens-before the other
+    vc_b = VectorClock({"b": 5})
+    event_a = make_event("a", 0, vc_a)
+    event_b = make_event("b", 0, vc_b)
+
+    ordered = total_order([event_b, event_a])
+    assert [e.event_id for e in ordered] == ["a-0", "b-0"]  # "a" < "b" lexicographically
+
+
+def test_two_independent_agents_interleave_by_tie_break_when_concurrent():
+    # No messages exchanged — every event is concurrent with every event of
+    # the other agent. Order must still be fully deterministic.
+    events_a = []
+    vc = VectorClock()
+    for i in range(3):
+        vc = vc.tick("agent_a")
+        events_a.append(make_event("agent_a", i, vc))
+
+    events_b = []
+    vc = VectorClock()
+    for i in range(3):
+        vc = vc.tick("agent_b")
+        events_b.append(make_event("agent_b", i, vc))
+
+    ordered = total_order(events_a + events_b)
+    # agent_a's events sort before agent_b's (tie-break on agent_id), each
+    # internally in program order (real causal edges within the agent).
+    assert [e.event_id for e in ordered] == [
+        "agent_a-0", "agent_a-1", "agent_a-2", "agent_b-0", "agent_b-1", "agent_b-2",
+    ]
+
+
+def test_result_is_deterministic_regardless_of_input_order():
+    vc_a1 = VectorClock().tick("A")
+    send = make_event("A", 0, vc_a1, kind=MSG_SEND)
+    vc_b1 = VectorClock().merge(vc_a1).tick("B")
+    recv = make_event("B", 0, vc_b1, kind=MSG_RECV)
+
+    order1 = [e.event_id for e in total_order([send, recv])]
+    order2 = [e.event_id for e in total_order([recv, send])]
+    assert order1 == order2 == ["A-0", "B-0"]
+
+
+def test_cycle_is_detected_not_silently_resolved():
+    # Two events that (incorrectly) each claim to happen-before the other —
+    # not producible by correctly-maintained vclocks, but the algorithm must
+    # not silently drop or misorder events if it ever sees corrupted data.
+    class FakeClock:
+        def __init__(self, other):
+            self.other = other
+
+        def happens_before(self, o):
+            return o is self.other
+
+    a = make_event("a", 0, VectorClock({"a": 1}))
+    b = make_event("b", 0, VectorClock({"b": 1}))
+
+    import pramana_core.sequencer as sequencer_module
+
+    original = sequencer_module.VectorClock.from_bytes
+    fake_a, fake_b = FakeClock(None), FakeClock(None)
+    fake_a.other, fake_b.other = fake_b, fake_a
+
+    def fake_from_bytes(data):
+        return fake_a if data == a.vclock else fake_b
+
+    sequencer_module.VectorClock.from_bytes = staticmethod(fake_from_bytes)
+    try:
+        with pytest.raises(ValueError):
+            total_order([a, b])
+    finally:
+        sequencer_module.VectorClock.from_bytes = original

pramana_core-0.0.1/tests/test_signing.py

@@ -0,0 +1,26 @@
+from pramana_core.signing import generate_keypair, sign, verify
+
+
+def test_valid_signature_verifies():
+    priv, pub = generate_keypair()
+    sig = sign(priv, b"hello")
+    assert verify(pub, b"hello", sig) is True
+
+
+def test_tampered_message_fails():
+    priv, pub = generate_keypair()
+    sig = sign(priv, b"hello")
+    assert verify(pub, b"goodbye", sig) is False
+
+
+def test_wrong_public_key_fails():
+    priv, _ = generate_keypair()
+    _, other_pub = generate_keypair()
+    sig = sign(priv, b"hello")
+    assert verify(other_pub, b"hello", sig) is False
+
+
+def test_keys_are_32_bytes_raw():
+    priv, pub = generate_keypair()
+    assert len(priv) == 32
+    assert len(pub) == 32

pramana_core-0.0.1/tests/test_signing_extra.py

@@ -0,0 +1,6 @@
+from pramana_core.signing import generate_keypair, public_key_from_private
+
+
+def test_public_key_from_private_matches_generated_pair():
+    priv, pub = generate_keypair()
+    assert public_key_from_private(priv) == pub

pramana_core-0.0.1/tests/test_vclock.py

@@ -0,0 +1,74 @@
+from pramana_core.vclock import VectorClock
+
+
+def test_tick_increments_own_component():
+    vc = VectorClock().tick("a")
+    assert vc.counts == {"a": 1}
+    vc = vc.tick("a")
+    assert vc.counts == {"a": 2}
+
+
+def test_tick_does_not_mutate_original():
+    vc = VectorClock({"a": 1})
+    vc2 = vc.tick("a")
+    assert vc.counts == {"a": 1}
+    assert vc2.counts == {"a": 2}
+
+
+def test_merge_takes_elementwise_max():
+    a = VectorClock({"a": 3, "b": 1})
+    b = VectorClock({"a": 1, "b": 5, "c": 2})
+    merged = a.merge(b)
+    assert merged.counts == {"a": 3, "b": 5, "c": 2}
+
+
+def test_happens_before_true_case():
+    a = VectorClock({"a": 1})
+    b = a.tick("a").merge(VectorClock({"b": 1})).tick("b")
+    assert a.happens_before(b)
+    assert not b.happens_before(a)
+
+
+def test_concurrent_events_are_neither_before_nor_after():
+    a = VectorClock({"a": 1, "b": 0})
+    b = VectorClock({"a": 0, "b": 1})
+    assert a.concurrent_with(b)
+    assert not a.happens_before(b)
+    assert not b.happens_before(a)
+
+
+def test_identical_clocks_are_not_happens_before_or_concurrent():
+    a = VectorClock({"a": 1})
+    b = VectorClock({"a": 1})
+    assert not a.happens_before(b)
+    assert not a.concurrent_with(b)
+
+
+def test_pack_unpack_round_trip():
+    vc = VectorClock({"agent_a": 3, "agent_b": 7})
+    assert VectorClock.from_bytes(vc.to_bytes()) == vc
+
+
+def test_empty_bytes_unpacks_to_empty_clock():
+    assert VectorClock.from_bytes(b"") == VectorClock()
+
+
+def test_message_send_receive_scenario_from_lld():
+    # A:[1,0,0] --handoff--> B:[1,1,0] --tool--> C:[1,1,1] --result--> A:[2,1,1]
+    # docs/LLD.md §5 worked example.
+    a = VectorClock().tick("A")
+    assert a.counts == {"A": 1}
+
+    b = VectorClock().merge(a).tick("B")
+    assert b.counts == {"A": 1, "B": 1}
+
+    c = VectorClock().merge(b).tick("C")
+    assert c.counts == {"A": 1, "B": 1, "C": 1}
+
+    a2 = a.merge(c).tick("A")
+    assert a2.counts == {"A": 2, "B": 1, "C": 1}
+
+    assert a.happens_before(b)
+    assert b.happens_before(c)
+    assert a.happens_before(a2)
+    assert c.happens_before(a2)

pramana_core-0.0.1/tests/test_wsgi.py

@@ -0,0 +1,139 @@
+import io
+from http.server import BaseHTTPRequestHandler
+
+from pramana_core.wsgi import make_wsgi_app
+
+
+def _environ(method="GET", path="/", body=b"", headers=None, query=""):
+    env = {
+        "REQUEST_METHOD": method,
+        "PATH_INFO": path,
+        "QUERY_STRING": query,
+        "wsgi.input": io.BytesIO(body),
+        "CONTENT_LENGTH": str(len(body)) if body else "",
+    }
+    for k, v in (headers or {}).items():
+        env[f"HTTP_{k.upper().replace('-', '_')}"] = v
+    return env
+
+
+class _EchoHandler(BaseHTTPRequestHandler):
+    def log_message(self, fmt, *args):
+        pass
+
+    def do_GET(self):
+        if self.path.startswith("/headers"):
+            got = self.headers.get("X-Probe", "")
+            body = got.encode()
+        else:
+            body = b"hello"
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", "0"))
+        body = self.rfile.read(length)
+        self.send_response(201)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_DELETE(self):
+        self.send_response(404)
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+
+def _call(app, environ):
+    captured = {}
+
+    def start_response(status, headers):
+        captured["status"] = status
+        captured["headers"] = dict(headers)
+
+    body = b"".join(app(environ, start_response))
+    return captured["status"], captured["headers"], body
+
+
+def test_get_round_trips_status_headers_and_body():
+    app = make_wsgi_app(_EchoHandler, server=None)
+    status, headers, body = _call(app, _environ("GET", "/"))
+    assert status == "200 OK"
+    assert headers["Content-Type"] == "text/plain"
+    assert body == b"hello"
+
+
+def test_request_headers_reach_the_handler():
+    app = make_wsgi_app(_EchoHandler, server=None)
+    _, _, body = _call(app, _environ("GET", "/headers", headers={"X-Probe": "hi-there"}))
+    assert body == b"hi-there"
+
+
+def test_post_body_round_trips():
+    app = make_wsgi_app(_EchoHandler, server=None)
+    status, _, body = _call(app, _environ("POST", "/v1/whatever", body=b"payload-bytes"))
+    assert status == "201 Created"
+    assert body == b"payload-bytes"
+
+
+def test_query_string_reaches_the_handler():
+    class _QueryHandler(BaseHTTPRequestHandler):
+        def log_message(self, fmt, *args):
+            pass
+
+        def do_GET(self):
+            body = self.path.encode()
+            self.send_response(200)
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+    app = make_wsgi_app(_QueryHandler, server=None)
+    _, _, body = _call(app, _environ("GET", "/v1/traces", query="limit=2&before=100"))
+    assert body == b"/v1/traces?limit=2&before=100"
+
+
+def test_a_route_that_never_reads_the_body_never_touches_wsgi_input():
+    """The property the whole adapter exists to preserve: ingest's
+    Content-Length cap runs before the body is read, so a route that 413s
+    before calling self.rfile.read(...) must not have pulled any body bytes
+    out of the real WSGI input stream at all.
+    """
+
+    class _NeverReadsBody(BaseHTTPRequestHandler):
+        def log_message(self, fmt, *args):
+            pass
+
+        def do_POST(self):
+            self.send_response(413)
+            self.send_header("Content-Length", "0")
+            self.end_headers()
+
+    class _TrackedInput(io.BytesIO):
+        def __init__(self, data):
+            super().__init__(data)
+            self.read_calls = 0
+
+        def read(self, size=-1):
+            self.read_calls += 1
+            return super().read(size)
+
+    tracked = _TrackedInput(b"x" * 1000)
+    environ = _environ("POST", "/v1/events:batch", body=b"")
+    environ["wsgi.input"] = tracked
+    environ["CONTENT_LENGTH"] = "1000"
+
+    app = make_wsgi_app(_NeverReadsBody, server=None)
+    status, _, _ = _call(app, environ)
+
+    assert status.startswith("413 ")  # exact reason phrase changed between Python versions
+    assert tracked.read_calls == 0
+
+
+def test_delete_status_with_no_message_still_parses():
+    app = make_wsgi_app(_EchoHandler, server=None)
+    status, _, _ = _call(app, _environ("DELETE", "/x"))
+    assert status == "404 Not Found"