activegraph 1.0.0rc2__py3-none-any.whl

activegraph/runtime/config_errors.py

@@ -0,0 +1,124 @@
+"""Runtime-side configuration error leaves. v1.0 PR-F.
+
+Configuration errors fire when the caller constructs or calls the
+runtime with arguments that violate a static contract — wrong types,
+conflicting kwargs, out-of-range values, operations that require a
+specific backend that isn't attached, state that's already set and
+can't be re-set. The errors are caller-actionable: the developer
+either fixes the call or restructures their setup.
+
+Three classes here cover the audit:
+
+- :class:`InvalidRuntimeConfiguration` — most ValueError shapes
+  (conflicting args, missing required args, out-of-range values).
+  Multi-inherits :class:`ValueError` for back-compat.
+- :class:`InvalidArgumentType` — wrong-type values passed to
+  constructors. Multi-inherits :class:`TypeError`.
+- :class:`IncompatibleRuntimeState` — operations that require a
+  specific runtime state (e.g., fork requires a SQLite-backed
+  runtime; graph already has a store attached). Multi-inherits
+  :class:`RuntimeError`.
+
+See CONTRACT v1.0 PR-F for the audit table mapping each migrated
+raise site to its class.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from activegraph.errors import ConfigurationError
+
+
+class InvalidRuntimeConfiguration(ConfigurationError, ValueError):
+    """Caller-provided configuration is invalid (conflicting arguments,
+    missing required argument, out-of-range value).
+
+    Multi-inherits :class:`ValueError` so user code that catches the
+    builtin around runtime construction or method calls keeps working.
+
+    Construct with a one-line ``summary`` plus the three structured
+    fields. The recovery prose is per-call-site, not table-driven —
+    each configuration mistake has a different fix.
+    """
+
+    _doc_slug = "invalid-runtime-configuration"
+
+    def __init__(
+        self,
+        summary: str,
+        *,
+        what_failed: str,
+        why: str,
+        how_to_fix: str,
+        context: Optional[dict[str, Any]] = None,
+    ) -> None:
+        ConfigurationError.__init__(
+            self,
+            summary,
+            what_failed=what_failed,
+            why=why,
+            how_to_fix=how_to_fix,
+            context=context,
+        )
+
+
+class InvalidArgumentType(ConfigurationError, TypeError):
+    """A value passed to a constructor or method has the wrong type.
+
+    Multi-inherits :class:`TypeError`. Used when the framework's
+    contract is type-based (e.g., :class:`PostgresEventStore` accepts
+    a URL string, a psycopg.Connection, or a psycopg_pool.ConnectionPool —
+    anything else is refused at construction).
+    """
+
+    _doc_slug = "invalid-argument-type"
+
+    def __init__(
+        self,
+        summary: str,
+        *,
+        what_failed: str,
+        why: str,
+        how_to_fix: str,
+        context: Optional[dict[str, Any]] = None,
+    ) -> None:
+        ConfigurationError.__init__(
+            self,
+            summary,
+            what_failed=what_failed,
+            why=why,
+            how_to_fix=how_to_fix,
+            context=context,
+        )
+
+
+class IncompatibleRuntimeState(ConfigurationError, RuntimeError):
+    """An operation requires a runtime state that isn't satisfied —
+    either a state that must be set but isn't, or a state that mustn't
+    be set but is.
+
+    Examples: ``runtime.fork()`` requires a SQLite-backed runtime;
+    ``graph.attach_store()`` requires no existing store. Multi-inherits
+    :class:`RuntimeError` for back-compat.
+    """
+
+    _doc_slug = "incompatible-runtime-state"
+
+    def __init__(
+        self,
+        summary: str,
+        *,
+        what_failed: str,
+        why: str,
+        how_to_fix: str,
+        context: Optional[dict[str, Any]] = None,
+    ) -> None:
+        ConfigurationError.__init__(
+            self,
+            summary,
+            what_failed=what_failed,
+            why=why,
+            how_to_fix=how_to_fix,
+            context=context,
+        )

activegraph/runtime/diff.py

@@ -0,0 +1,145 @@
+"""Structural diff between two runs (typically parent vs fork).
+
+CONTRACT v0.5 #10: diff is structural only — divergent objects, divergent
+relations, and which event ranges belong to each side. Semantic comparison
+(e.g., "do these two claims express the same idea?") is a behavior's job,
+not the runtime's.
+
+Diff is computed by walking both graphs' final state and event logs. We
+ignore lifecycle events (`behavior.*`, `runtime.*`) when computing the
+event partition — they're scaffolding, not history.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from activegraph.core.event import Event
+from activegraph.core.graph import Graph, Object, Relation
+
+
+_LIFECYCLE_PREFIXES = ("behavior.", "relation_behavior.", "runtime.")
+
+
+def _is_lifecycle(e: Event) -> bool:
+    return any(e.type.startswith(p) for p in _LIFECYCLE_PREFIXES)
+
+
+@dataclass
+class DivergentObject:
+    id: str
+    in_parent: Optional[dict[str, Any]]  # to_dict snapshot or None
+    in_fork: Optional[dict[str, Any]]
+
+    def summary(self) -> str:
+        if self.in_parent is None:
+            return f"{self.id} only in fork"
+        if self.in_fork is None:
+            return f"{self.id} only in parent"
+        return f"{self.id} differs (parent v{self.in_parent.get('version')} ↔ fork v{self.in_fork.get('version')})"
+
+
+@dataclass
+class DivergentRelation:
+    id: str
+    in_parent: Optional[dict[str, Any]]
+    in_fork: Optional[dict[str, Any]]
+
+    def summary(self) -> str:
+        if self.in_parent is None:
+            r = self.in_fork
+            return f"{self.id} only in fork ({r['source']} --{r['type']}--> {r['target']})"
+        if self.in_fork is None:
+            r = self.in_parent
+            return f"{self.id} only in parent ({r['source']} --{r['type']}--> {r['target']})"
+        return f"{self.id} differs"
+
+
+@dataclass
+class Diff:
+    parent_run_id: str
+    fork_run_id: str
+    shared_events: list[Event] = field(default_factory=list)
+    parent_only_events: list[Event] = field(default_factory=list)
+    fork_only_events: list[Event] = field(default_factory=list)
+    divergent_objects: list[DivergentObject] = field(default_factory=list)
+    divergent_relations: list[DivergentRelation] = field(default_factory=list)
+
+    @property
+    def is_identical(self) -> bool:
+        return (
+            not self.parent_only_events
+            and not self.fork_only_events
+            and not self.divergent_objects
+            and not self.divergent_relations
+        )
+
+
+def compute_diff(parent: Graph, fork: Graph, parent_run_id: str, fork_run_id: str) -> Diff:
+    parent_events = [e for e in parent.events if not _is_lifecycle(e)]
+    fork_events = [e for e in fork.events if not _is_lifecycle(e)]
+
+    # Shared prefix: events that match by id, type AND payload. Same id with
+    # different content means the fork already diverged (logical ids are
+    # scoped to run_id — CONTRACT #12 — so collisions after the fork point
+    # are expected and must not be flattened into "shared".)
+    shared: list[Event] = []
+    i = 0
+    while i < len(parent_events) and i < len(fork_events):
+        a, b = parent_events[i], fork_events[i]
+        if a.id == b.id and a.type == b.type and a.payload == b.payload:
+            shared.append(a)
+            i += 1
+        else:
+            break
+    parent_only = parent_events[i:]
+    fork_only = fork_events[i:]
+
+    # Object divergence.
+    obj_diffs: list[DivergentObject] = []
+    parent_objs = {o.id: o for o in parent.all_objects()}
+    fork_objs = {o.id: o for o in fork.all_objects()}
+    for oid in sorted(set(parent_objs) | set(fork_objs)):
+        po = parent_objs.get(oid)
+        fo = fork_objs.get(oid)
+        pd = _normalize_object(po) if po else None
+        fd = _normalize_object(fo) if fo else None
+        if pd != fd:
+            obj_diffs.append(DivergentObject(id=oid, in_parent=pd, in_fork=fd))
+
+    # Relation divergence.
+    rel_diffs: list[DivergentRelation] = []
+    parent_rels = {r.id: r for r in parent.all_relations()}
+    fork_rels = {r.id: r for r in fork.all_relations()}
+    for rid in sorted(set(parent_rels) | set(fork_rels)):
+        pr = parent_rels.get(rid)
+        fr = fork_rels.get(rid)
+        pd = _normalize_relation(pr) if pr else None
+        fd = _normalize_relation(fr) if fr else None
+        if pd != fd:
+            rel_diffs.append(DivergentRelation(id=rid, in_parent=pd, in_fork=fd))
+
+    return Diff(
+        parent_run_id=parent_run_id,
+        fork_run_id=fork_run_id,
+        shared_events=shared,
+        parent_only_events=parent_only,
+        fork_only_events=fork_only,
+        divergent_objects=obj_diffs,
+        divergent_relations=rel_diffs,
+    )
+
+
+def _normalize_object(o: Object) -> dict[str, Any]:
+    """Strip provenance (timestamps, run_id) so equality is structural."""
+    d = o.to_dict()
+    d.pop("provenance", None)
+    return d
+
+
+def _normalize_relation(r: Relation) -> dict[str, Any]:
+    d = r.to_dict()
+    d.pop("provenance", None)
+    return d

activegraph/runtime/errors.py

@@ -0,0 +1,216 @@
+"""Replay errors. CONTRACT v0.5 #7 (replay strictness), CONTRACT v1.0 #C1
+(error format) — migrated to the ActiveGraphError hierarchy in v1.0 PR-A.
+
+`ReplayDivergenceError` is the canonical replay error and the reference
+error class for the v1.0 message rewrite series. Its message obeys the
+locked format (CONTRACT v1.0 #3); three distinct call sites in the
+runtime produce three distinct messages, discriminated by the inputs
+to ``__init__`` and snapshot-tested individually:
+
+  1. **prompt_hash_mismatch** — the LLM-cache prompt hash for a recorded
+     ``llm.requested`` event no longer matches the live re-run hash.
+     Something changed in the behavior code, prompt template, or a
+     tool's input arguments.
+  2. **type_mismatch** — an event at the same stream position has a
+     different ``type`` than recorded. The behavior graph produced a
+     different shape of work.
+  3. **length_mismatch** — the recorded stream and the live re-run
+     produced different numbers of events. A behavior was added, removed,
+     or short-circuits differently.
+
+The signature ``ReplayDivergenceError(event_id=..., expected=..., actual=...)``
+is preserved from v0.5 so existing call sites and tests stay valid; the
+discriminator is inferred from the inputs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from activegraph.errors import ReplayError
+
+
+_NO_RECORDED_EVENT_SENTINEL = "<no recorded event>"
+
+
+class ReplayDivergenceError(ReplayError):
+    """Raised when a replay (``replay_strict=True``) or a fork produces an
+    event stream that does not match the recorded log.
+
+    ``event_id`` pins the first divergence point so an operator can jump
+    directly to it. ``expected`` and ``actual`` describe what was
+    recorded vs. what the live re-run produced; one is ``None`` when the
+    re-run finished early or produced an extra event with no recorded
+    counterpart.
+    """
+
+    _doc_slug = "replay-divergence-error"
+
+    def __init__(
+        self,
+        *,
+        event_id: str,
+        expected: str,
+        actual: str | None,
+    ) -> None:
+        self.event_id = event_id
+        self.expected = expected
+        self.actual = actual
+        kind, summary, what_failed, why, how_to_fix = _build_message(
+            event_id=event_id, expected=expected, actual=actual
+        )
+        self.kind = kind
+        context: dict[str, Any] = {
+            "event_id": event_id,
+            "kind": kind,
+            "expected": expected,
+            "actual": actual,
+        }
+        super().__init__(
+            summary,
+            what_failed=what_failed,
+            why=why,
+            how_to_fix=how_to_fix,
+            context=context,
+        )
+
+
+def _build_message(
+    *, event_id: str, expected: str, actual: str | None
+) -> tuple[str, str, str, str, str]:
+    """Return ``(kind, summary, what_failed, why, how_to_fix)`` for the
+    three replay-divergence shapes. The discriminator is the input shape:
+
+      - ``expected`` starts with ``prompt_hash=`` -> prompt_hash_mismatch
+      - ``expected`` is ``"<no recorded event>"`` or ``actual is None`` ->
+        length_mismatch
+      - otherwise -> type_mismatch
+    """
+    if isinstance(expected, str) and expected.startswith("prompt_hash="):
+        return _prompt_hash_message(event_id, expected, actual)
+    if expected == _NO_RECORDED_EVENT_SENTINEL or actual is None:
+        return _length_message(event_id, expected, actual)
+    return _type_message(event_id, expected, actual)
+
+
+def _prompt_hash_message(
+    event_id: str, expected: str, actual: str | None,
+) -> tuple[str, str, str, str, str]:
+    actual_str = actual if actual is not None else "<no live response>"
+    return (
+        "prompt_hash_mismatch",
+        f"replay diverged at {event_id}: LLM prompt hash mismatch",
+        (
+            f"Event {event_id} (an `llm.requested` event in the recorded log) had a "
+            f"different prompt hash during this replay than the parent run recorded:\n"
+            f"  recorded:  {expected}\n"
+            f"  live:      {actual_str}"
+        ),
+        (
+            "The replay cache keys on the full prompt hash, so any change to an LLM "
+            "behavior's code, a prompt template, a system message, or a tool's input "
+            "arguments produces a mismatch. The framework refuses to silently substitute "
+            "a stale cached response under a new prompt — that would break the audit "
+            "trail the cache is designed to preserve."
+        ),
+        (
+            f"If the change was intentional (you edited a behavior or a prompt template),\n"
+            f"re-record the cache from the divergence point:\n"
+            f"    activegraph fork <parent-run> --at-event {event_id} --record\n"
+            f"\n"
+            f"If the change was unintentional, diff your code against the recorded run's\n"
+            f"pack version and revert the change:\n"
+            f"    activegraph inspect <parent-run> --pack-version\n"
+            f"\n"
+            f"To see the full recorded prompt for this event:\n"
+            f"    activegraph inspect <parent-run> --event {event_id}"
+        ),
+    )
+
+
+def _type_message(
+    event_id: str, expected: str, actual: str | None,
+) -> tuple[str, str, str, str, str]:
+    actual_str = actual if actual is not None else "<no live event>"
+    return (
+        "type_mismatch",
+        f"replay diverged at {event_id}: event type mismatch",
+        (
+            f"At the stream position pinned to event {event_id}, the live re-run "
+            f"produced a different event type than recorded:\n"
+            f"  recorded:  {expected!r}\n"
+            f"  live:      {actual_str!r}"
+        ),
+        (
+            "Strict replay compares the type stream of non-lifecycle events between the "
+            "recorded log and the live re-run. A type mismatch means the behavior graph "
+            "took a different branch — usually because a behavior's `where` filter, a "
+            "pattern subscription, or a conditional `graph.emit` changed since the "
+            "recorded run."
+        ),
+        (
+            f"Identify the behavior that produced event {event_id} in the recorded log:\n"
+            f"    activegraph inspect <parent-run> --event {event_id}\n"
+            f"\n"
+            f"Diff that behavior against your current source. If the change was\n"
+            f"intentional, re-run without `replay_strict=True` (or fork with --record\n"
+            f"from the divergence point). If unintentional, revert the behavior."
+        ),
+    )
+
+
+def _length_message(
+    event_id: str, expected: str, actual: str | None,
+) -> tuple[str, str, str, str, str]:
+    if actual is None:
+        return (
+            "length_mismatch",
+            f"replay diverged at {event_id}: live re-run finished early",
+            (
+                f"The recorded log contained event {event_id} (type {expected!r}) at this "
+                f"position, but the live re-run terminated before producing it.\n"
+                f"  recorded:  {expected!r}\n"
+                f"  live:      <no event produced>"
+            ),
+            (
+                "Strict replay requires the live re-run to produce the same number and "
+                "shape of non-lifecycle events as the recording. A short live re-run means "
+                "a behavior that fired in the recorded run no longer fires, or short-"
+                "circuits earlier — usually because a pattern subscription, a `where` "
+                "filter, or a guard condition was tightened since the recording."
+            ),
+            (
+                f"Identify the behavior that produced {event_id} in the recorded log:\n"
+                f"    activegraph inspect <parent-run> --event {event_id}\n"
+                f"\n"
+                f"Compare that behavior's current trigger conditions against the recorded\n"
+                f"run's. If the change was intentional, fork with --record from the\n"
+                f"divergence point to refresh the recording. If unintentional, revert."
+            ),
+        )
+    return (
+        "length_mismatch",
+        f"replay diverged at {event_id}: live re-run produced an unrecorded event",
+        (
+            f"At the position pinned to event {event_id}, the live re-run produced an "
+            f"event of type {actual!r}, but the recorded log had no event here.\n"
+            f"  recorded:  <no event recorded>\n"
+            f"  live:      {actual!r}"
+        ),
+        (
+            "Strict replay requires the live re-run's event stream to match the "
+            "recording position-for-position. An extra live event means a behavior "
+            "fires now that did not fire in the recorded run — usually because a new "
+            "behavior was added, or a pattern subscription was loosened."
+        ),
+        (
+            f"List the behaviors currently registered and compare against the recorded\n"
+            f"pack version:\n"
+            f"    activegraph inspect <parent-run> --behaviors\n"
+            f"\n"
+            f"If the new behavior is intentional, re-record from this position:\n"
+            f"    activegraph fork <parent-run> --at-event {event_id} --record\n"
+            f"\n"
+            f"If the behavior shouldn't fire here, tighten its trigger conditions."
+        ),
+    )