provalume 0.1.0__py3-none-any.whl

provalume/__init__.py

@@ -0,0 +1,133 @@
+"""Provalume — verified, git-aware memory for autonomous software agents.
+
+    Facts your agents proved, not things they said.
+
+Provalume records what agents did and which evidence proved it, then re-injects a
+bounded, labelled digest of that record into future prompts. Trust is granted by
+deterministic evidence — a command that returned, a reviewer who was not the
+author, a commit that landed — never by assertion.
+
+    from provalume import Provalume
+
+    pv = Provalume.open(project_id="my-project")
+
+    pv.record_verification(
+        command="pytest -n auto tests/integration",
+        passed=False,
+        excerpt="deadlock in db fixture teardown",
+    )
+
+    warning = pv.preflight(command="pytest -n auto tests/integration")
+    if warning.matched:
+        print(warning.summary)
+
+    digest = pv.recall("integration tests").digest(char_budget=2000)
+    print(digest.text)      # always banner-first, always within budget
+
+What this module re-exports is the public API, stable within a minor release
+series. Everything else — ``provalume.store``, ``provalume.policy``,
+``provalume.writers``, ``provalume.retrieval``, ``provalume.interchange``, and
+the ``provalume.mcp`` internals — is internal and may change without notice
+(ADR-0017).
+"""
+
+from __future__ import annotations
+
+from provalume.errors import (
+    BudgetExceeded,
+    EmbedderUnavailable,
+    IntegrityError,
+    InterchangeError,
+    PathConfinementError,
+    PolicyViolation,
+    ProvalumeError,
+    SchemaVersionError,
+    ScopeError,
+    SignatureError,
+    StoreError,
+    TrustError,
+    UnknownRecordVersion,
+    ValidationError,
+)
+from provalume.schemas import (
+    DIGEST_BANNER,
+    Applicability,
+    Digest,
+    Event,
+    EventFilter,
+    EventType,
+    Explanation,
+    IntegrationState,
+    Memory,
+    MemoryFilter,
+    MemoryType,
+    PreflightMatch,
+    PreflightResult,
+    Provenance,
+    RankingPolicy,
+    RecallQuery,
+    RecallResult,
+    ResolutionStatus,
+    ReviewState,
+    Scope,
+    ScopeLevel,
+    ScoreBreakdown,
+    Source,
+    Transition,
+    TrustState,
+    VerificationState,
+)
+from provalume.sdk.client import Provalume, RecallResponse
+
+try:  # pragma: no cover - depends on install state, not on logic
+    from importlib.metadata import version
+
+    __version__ = version("provalume")
+except Exception:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "DIGEST_BANNER",
+    "Applicability",
+    "BudgetExceeded",
+    "Digest",
+    "EmbedderUnavailable",
+    "Event",
+    "EventFilter",
+    "EventType",
+    "Explanation",
+    "IntegrationState",
+    "IntegrityError",
+    "InterchangeError",
+    "Memory",
+    "MemoryFilter",
+    "MemoryType",
+    "PathConfinementError",
+    "PolicyViolation",
+    "PreflightMatch",
+    "PreflightResult",
+    "Provalume",
+    "ProvalumeError",
+    "Provenance",
+    "RankingPolicy",
+    "RecallQuery",
+    "RecallResponse",
+    "RecallResult",
+    "ResolutionStatus",
+    "ReviewState",
+    "SchemaVersionError",
+    "Scope",
+    "ScopeError",
+    "ScopeLevel",
+    "ScoreBreakdown",
+    "SignatureError",
+    "Source",
+    "StoreError",
+    "Transition",
+    "TrustError",
+    "TrustState",
+    "UnknownRecordVersion",
+    "ValidationError",
+    "VerificationState",
+    "__version__",
+]

provalume/_ids.py

@@ -0,0 +1,112 @@
+"""Collision-resistant, time-sortable identifiers.
+
+Provalume needs identifiers that are:
+
+* **time-sortable**, so JSONL exports append near the end of the file and Git
+  diffs stay append-mostly rather than churning (ADR-0011);
+* **collision-resistant across machines**, because two people can record events
+  offline and later merge without coordination (ADR-0002);
+* **URL- and filename-safe**, and readable enough to paste into a bug report.
+
+This is a ULID: 48 bits of millisecond timestamp followed by 80 bits of
+randomness, Crockford base32 encoded to 26 characters. The implementation is
+about forty lines, so it is here rather than in a dependency.
+
+The ULID is the *identity* of a record. It is deliberately not derived from
+content: two genuinely distinct events with identical payloads (the same command
+failing twice in the same millisecond) must not collide. Content-based dedup is a
+separate concern handled by ``payload_hash`` in :mod:`provalume.interchange.hashing`.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+# Crockford base32: no I, L, O, or U, so a transcribed identifier is hard to
+# garble and impossible to turn into an accidental word.
+_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_DECODE = {c: i for i, c in enumerate(_ALPHABET)}
+
+_TIME_CHARS = 10
+_RANDOM_CHARS = 16
+ULID_LENGTH = _TIME_CHARS + _RANDOM_CHARS
+
+_MAX_TIME_MS = (1 << 48) - 1
+
+
+def _encode(value: int, length: int) -> str:
+    chars = []
+    for _ in range(length):
+        chars.append(_ALPHABET[value & 0x1F])
+        value >>= 5
+    return "".join(reversed(chars))
+
+
+def new_id(*, timestamp_ms: int | None = None) -> str:
+    """Return a new 26-character ULID.
+
+    ``timestamp_ms`` is for tests and deterministic replay only; production
+    callers leave it unset.
+    """
+    ts = int(time.time() * 1000) if timestamp_ms is None else timestamp_ms
+    if not 0 <= ts <= _MAX_TIME_MS:
+        msg = f"timestamp out of ULID range: {ts}"
+        raise ValueError(msg)
+    randomness = int.from_bytes(os.urandom(10), "big")
+    return _encode(ts, _TIME_CHARS) + _encode(randomness, _RANDOM_CHARS)
+
+
+def is_valid(value: str) -> bool:
+    """Return whether ``value`` is a well-formed ULID."""
+    if len(value) != ULID_LENGTH:
+        return False
+    return all(c in _DECODE for c in value)
+
+
+def timestamp_ms(value: str) -> int:
+    """Extract the embedded millisecond timestamp from a ULID."""
+    if not is_valid(value):
+        msg = f"not a valid identifier: {value!r}"
+        raise ValueError(msg)
+    result = 0
+    for c in value[:_TIME_CHARS]:
+        result = (result << 5) | _DECODE[c]
+    return result
+
+
+class MonotonicIdFactory:
+    """Generates ULIDs that strictly increase, even within one millisecond.
+
+    Plain :func:`new_id` sorts correctly across milliseconds but two IDs minted
+    in the same millisecond have an arbitrary relative order. Where insertion
+    order must be recoverable from the ID alone — journal append being the case
+    that matters — this factory increments the random component instead of
+    redrawing it, so ordering holds at sub-millisecond resolution.
+
+    Not thread-safe by design: Provalume is single-writer (ADR-0003).
+    """
+
+    def __init__(self) -> None:
+        self._last_ms = -1
+        self._last_random = 0
+
+    def new_id(self, *, timestamp_ms: int | None = None) -> str:
+        ts = int(time.time() * 1000) if timestamp_ms is None else timestamp_ms
+        if ts == self._last_ms:
+            self._last_random += 1
+            if self._last_random >= (1 << 80):
+                # Overflowing 80 bits inside one millisecond is not reachable in
+                # practice; step the clock rather than emit a duplicate.
+                ts += 1
+                self._last_ms = ts
+                self._last_random = int.from_bytes(os.urandom(10), "big")
+        else:
+            # A clock that moved backwards must not produce descending IDs.
+            ts = max(ts, self._last_ms)
+            if ts == self._last_ms:
+                self._last_random += 1
+            else:
+                self._last_ms = ts
+                self._last_random = int.from_bytes(os.urandom(10), "big")
+        return _encode(ts, _TIME_CHARS) + _encode(self._last_random, _RANDOM_CHARS)

provalume/_time.py

@@ -0,0 +1,91 @@
+"""Timestamp handling.
+
+One format, everywhere: RFC 3339 in UTC with millisecond precision and a literal
+``Z`` suffix.
+
+    2026-07-25T14:32:01.482Z
+
+Fixed precision matters more than it looks. Timestamps are part of the canonical
+JSON that gets hashed (:mod:`provalume.interchange.hashing`), so a value that
+serialises as ``…:01.482Z`` on one machine and ``…:01.482000Z`` on another would
+hash differently for identical data and break cross-machine duplicate detection.
+
+Millisecond precision is chosen to match the ULID timestamp component, so an
+event's identifier and its ``recorded_at`` cannot disagree about which
+millisecond it belongs to.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta, timezone
+
+_RFC3339 = re.compile(
+    r"^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?"
+    r"(Z|[+-]\d{2}:\d{2})$"
+)
+
+
+def now() -> str:
+    """Current time as a canonical RFC 3339 UTC string."""
+    return to_rfc3339(datetime.now(UTC))
+
+
+def to_rfc3339(value: datetime) -> str:
+    """Format a datetime canonically. Naive input is assumed to be UTC."""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=UTC)
+    value = value.astimezone(UTC)
+    return f"{value.strftime('%Y-%m-%dT%H:%M:%S')}.{value.microsecond // 1000:03d}Z"
+
+
+def parse(value: str) -> datetime:
+    """Parse an RFC 3339 timestamp into an aware UTC datetime.
+
+    Accepts any valid RFC 3339 offset and any sub-second precision, so records
+    produced by other tooling still import; :func:`to_rfc3339` is what normalises
+    them on the way to storage.
+    """
+    match = _RFC3339.match(value)
+    if match is None:
+        msg = f"not an RFC 3339 timestamp: {value!r}"
+        raise ValueError(msg)
+    year, month, day, hour, minute, second = (int(match.group(i)) for i in range(1, 7))
+    fraction = match.group(7) or ""
+    microsecond = int(fraction.ljust(6, "0")[:6]) if fraction else 0
+    offset = match.group(8)
+    tz: timezone
+    if offset == "Z":
+        tz = UTC
+    else:
+        sign = 1 if offset[0] == "+" else -1
+        tz_hours, tz_minutes = int(offset[1:3]), int(offset[4:6])
+        tz = timezone(timedelta(minutes=sign * (tz_hours * 60 + tz_minutes)))
+    return datetime(year, month, day, hour, minute, second, microsecond, tz).astimezone(UTC)
+
+
+def normalize(value: str) -> str:
+    """Round-trip a timestamp into canonical form.
+
+    Used at admission so that everything stored is byte-identical in format
+    regardless of how a caller expressed it.
+    """
+    return to_rfc3339(parse(value))
+
+
+def age_days(recorded_at: str, *, reference: str | None = None) -> float:
+    """Age in fractional days, used by the recency component of ranking.
+
+    Never negative: a record whose timestamp is in the future — clock skew, or a
+    caller passing a bad ``occurred_at`` — is treated as brand new rather than
+    given a recency score above 1.0, which would let a forged future timestamp
+    win every ranking.
+    """
+    then = parse(recorded_at)
+    ref = parse(reference) if reference else datetime.now(UTC)
+    return max(0.0, (ref - then).total_seconds() / 86400.0)
+
+
+def is_before(left: str, right: str) -> bool:
+    """Whether ``left`` is strictly earlier than ``right``."""
+    return parse(left) < parse(right)

provalume/cli/__init__.py

@@ -0,0 +1 @@
+"""Internal package. Not public API (ADR-0017)."""