activegraph 1.0.0rc2__py3-none-any.whl

activegraph/runtime/scheduler.py

@@ -0,0 +1,206 @@
+"""Event-count scheduler for `activate_after`. CONTRACT v0.7 #13.
+
+The decision: v0.7's `activate_after` is event-count only, never
+wall-clock. Wall-clock would require a clock-source abstraction and
+break determinism under replay. Event-count is deterministic across
+replay, composes with the tick model, and the escape hatch ("user
+drives `runtime.tick()` and injects timer.fired events") is the v1+
+extension point if anyone needs wall-clock.
+
+How it works:
+
+  * When a triggering event matches a behavior with `activate_after=N`,
+    the runtime calls `scheduler.schedule(...)` instead of invoking
+    the behavior directly. A `behavior.scheduled` event is emitted.
+
+  * The scheduler tracks each pending invocation with a fire-at-event
+    counter (= current_event_count + N).
+
+  * After every non-lifecycle event the runtime processes, it calls
+    `scheduler.due(graph)` which returns the pending entries whose
+    fire counters have been reached.
+
+  * For each due entry, the runtime RE-CHECKS the `where=` clause
+    against the latest graph state before invoking. If it no longer
+    holds, the invocation is silently skipped (no extra event). If it
+    holds, the behavior fires normally.
+
+Parsing `activate_after`:
+  * int → number of events
+  * str "N" or "N events" / "N event" → N events
+  * anything else → ValueError at registration time
+
+Anything wall-clock (e.g. "5 minutes") is intentionally rejected with
+a clear message pointing at CONTRACT v0.7 #13.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class ScheduledEntry:
+    behavior_name: str
+    behavior_index: int  # registry index — preserves CONTRACT #10 order
+    triggering_event_id: str
+    fire_at_event_count: int
+    where_recheck_path: Optional[str]  # behavior's `where=` payload path is kept
+    scheduled_event_id: str  # the behavior.scheduled event id
+
+
+@dataclass
+class DelayedQueue:
+    """Pending `activate_after` invocations. FIFO within the same fire tick."""
+
+    entries: list[ScheduledEntry] = field(default_factory=list)
+
+    def push(self, entry: ScheduledEntry) -> None:
+        self.entries.append(entry)
+
+    def pop_due(self, current_event_count: int) -> list[ScheduledEntry]:
+        due: list[ScheduledEntry] = []
+        kept: list[ScheduledEntry] = []
+        for e in self.entries:
+            if e.fire_at_event_count <= current_event_count:
+                due.append(e)
+            else:
+                kept.append(e)
+        self.entries = kept
+        return due
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+
+_DURATION_RE = re.compile(
+    r"^\s*(\d+)\s*(events?)?\s*$", re.IGNORECASE
+)
+_WALL_CLOCK_WORDS = {
+    "second", "seconds", "ms", "millisecond", "milliseconds",
+    "minute", "minutes", "min", "mins",
+    "hour", "hours", "day", "days", "week", "weeks",
+}
+
+
+from activegraph.errors import RegistrationError as _RegistrationError
+
+
+class InvalidActivateAfter(_RegistrationError, ValueError):
+    """``activate_after=`` on a @behavior / @llm_behavior decorator was
+    passed an unparseable or out-of-range value.
+
+    Multi-inherits :class:`ValueError` for back-compat with user code
+    catching the builtin around behavior registration.
+    """
+
+    _doc_slug = "invalid-activate-after"
+
+    def __init__(self, *, spec: Any, kind: str, hint: str) -> None:
+        self.spec = spec
+        self.kind = kind
+        self.hint = hint
+        from activegraph.errors import RegistrationError as _R
+        _R.__init__(
+            self,
+            f"activate_after={spec!r} is invalid ({kind})",
+            what_failed=(
+                f"A behavior decorator was given `activate_after={spec!r}`, "
+                f"which the scheduler refused as {kind}."
+            ),
+            why=(
+                "`activate_after` schedules a behavior to fire N events after "
+                "its triggering event. The runtime evaluates the schedule "
+                "against the event log (not wall-clock) so replay produces "
+                "identical timing — wall-clock units are intentionally out "
+                "of scope (CONTRACT v0.7 #13). An unparseable value would "
+                "make scheduling silently wrong, which would corrupt the "
+                "audit trail at every replay."
+            ),
+            how_to_fix=hint,
+            context={"spec": repr(spec), "kind": kind},
+        )
+
+
+def parse_activate_after(spec: Any) -> int:
+    """Parse `activate_after=` into an integer event count.
+
+    Accepts:
+      - int N (N >= 1)
+      - str "N", "N event", "N events"
+
+    Rejects:
+      - 0 or negative
+      - any wall-clock unit (seconds, minutes, ...): wall-clock is
+        intentionally out of scope for v0.7 (see CONTRACT v0.7 #13).
+    """
+    if isinstance(spec, bool):
+        # bool is an int in Python — guard against accidental True/False.
+        raise InvalidActivateAfter(
+            spec=spec,
+            kind="bool not int",
+            hint=(
+                "Pass an integer event count instead:\n"
+                "    activate_after=5\n"
+                "or a string with the 'events' unit:\n"
+                "    activate_after='5 events'"
+            ),
+        )
+    if isinstance(spec, int):
+        n = spec
+    elif isinstance(spec, str):
+        s = spec.strip().lower()
+        # Detect wall-clock units and reject with a CONTRACT-pointing message.
+        for word in _WALL_CLOCK_WORDS:
+            if word in s.split():
+                raise InvalidActivateAfter(
+                    spec=spec,
+                    kind="wall-clock unit",
+                    hint=(
+                        f"Wall-clock units (seconds/minutes/hours) are not "
+                        f"supported. Express the delay as an event count:\n"
+                        f"    activate_after=5\n"
+                        f"    activate_after='5 events'\n"
+                        f"\n"
+                        f"If you genuinely need wall-clock scheduling, file "
+                        f"an issue — the v1+ contract leaves room for it "
+                        f"behind a separate primitive (see CONTRACT v0.7 #23)."
+                    ),
+                )
+        m = _DURATION_RE.match(s)
+        if not m:
+            raise InvalidActivateAfter(
+                spec=spec,
+                kind="unparseable string",
+                hint=(
+                    "Use one of:\n"
+                    "    activate_after=5\n"
+                    "    activate_after='5'\n"
+                    "    activate_after='5 events'\n"
+                    "    activate_after='5 event'"
+                ),
+            )
+        n = int(m.group(1))
+    else:
+        raise InvalidActivateAfter(
+            spec=spec,
+            kind=f"type {type(spec).__name__}",
+            hint=(
+                "Pass an int or a string. Example:\n"
+                "    activate_after=5\n"
+                "    activate_after='5 events'"
+            ),
+        )
+    if n < 1:
+        raise InvalidActivateAfter(
+            spec=spec,
+            kind="must be >= 1",
+            hint=(
+                "`activate_after` schedules N events after the trigger. "
+                "Zero or negative N has no defined meaning. The minimum "
+                "is 1 (fire on the very next event after the trigger)."
+            ),
+        )
+    return n

activegraph/runtime/view_builder.py

@@ -0,0 +1,65 @@
+"""Construct a View for a behavior invocation. CONTRACT #11."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from activegraph.behaviors.base import Behavior, RelationBehavior
+from activegraph.core.event import Event
+from activegraph.core.graph import Graph
+from activegraph.core.view import View
+
+
+DEFAULT_RECENT_EVENTS = 50
+
+
+def build_view(
+    behavior: Behavior | RelationBehavior, event: Event, graph: Graph
+) -> View:
+    spec = behavior.view_spec
+    if not spec:
+        return View(
+            objects=graph.all_objects(),
+            relations=graph.all_relations(),
+            events=graph.events[-DEFAULT_RECENT_EVENTS:],
+        )
+
+    around_path = spec.get("around")
+    depth = spec.get("depth", 1)
+    include_types: Optional[list[str]] = spec.get("include_types")
+    recent_events: int = spec.get("recent_events", DEFAULT_RECENT_EVENTS)
+
+    if around_path:
+        center_id = _resolve_event_path(around_path, event)
+        objs, rels = graph.neighborhood(center_id, depth=depth) if center_id else ([], [])
+    else:
+        objs = graph.all_objects()
+        rels = graph.all_relations()
+
+    if include_types:
+        type_set = set(include_types)
+        objs = [o for o in objs if o.type in type_set]
+
+    return View(
+        objects=objs,
+        relations=rels,
+        events=graph.events[-recent_events:] if recent_events > 0 else [],
+    )
+
+
+def _resolve_event_path(expr: str, event: Event) -> Any:
+    """Resolve `event.payload.object.id` against an Event."""
+    parts = expr.split(".")
+    if not parts or parts[0] != "event":
+        return None
+    cur: Any = event
+    for p in parts[1:]:
+        if isinstance(cur, dict):
+            cur = cur.get(p)
+        elif hasattr(cur, p):
+            cur = getattr(cur, p)
+        else:
+            return None
+        if cur is None:
+            return None
+    return cur

activegraph/store/__init__.py

@@ -0,0 +1,41 @@
+"""Pluggable event-log stores. CONTRACT v0.5 #2, v0.8 #1–#2.
+
+Implementations:
+- InMemoryEventStore (v0.5): volatile, used by tests and ephemeral runs.
+- SQLiteEventStore   (v0.5): durable single-file. Default for solo work.
+- PostgresEventStore (v0.8): shared-state, multi-process. Opt-in dep.
+
+The EventStore protocol lives in ``store.base``. Custom backends conform
+to that protocol; nothing in the runtime imports concrete stores directly.
+The ``open_store(url, run_id)`` entry point picks the right driver from a
+connection URL (sqlite:///... or postgres://...).
+"""
+
+from activegraph.store.base import EventStore, RunRecord, replay_into
+from activegraph.store.errors import (
+    CorruptedEventPayloadError,
+    DuplicateEventError,
+    EventNotFoundError,
+    SchemaVersionMismatch,
+)
+from activegraph.store.memory import InMemoryEventStore
+from activegraph.store.serde import NonSerializableEventError
+from activegraph.store.sqlite import SQLiteEventStore
+from activegraph.store.url import InvalidStoreURL, StoreURL, open_store, parse_store_url
+
+__all__ = [
+    "CorruptedEventPayloadError",
+    "DuplicateEventError",
+    "EventNotFoundError",
+    "EventStore",
+    "InMemoryEventStore",
+    "InvalidStoreURL",
+    "NonSerializableEventError",
+    "RunRecord",
+    "SQLiteEventStore",
+    "SchemaVersionMismatch",
+    "StoreURL",
+    "open_store",
+    "parse_store_url",
+    "replay_into",
+]

activegraph/store/base.py

@@ -0,0 +1,66 @@
+"""EventStore interface + run metadata. CONTRACT v0.5 #2 and #6.
+
+An EventStore is a per-run, append-only view onto an event log. Multiple
+runs may share a backing file (SQLite); the EventStore instance is scoped
+to one `run_id` and only sees that run's events.
+
+Methods are deliberately minimal — append, iterate, count, lookup,
+truncate-after. No queries, no indexes beyond what the backend ships. This
+is an event log, not a database.
+
+The accompanying `RunRecord` is the canonical row in the `runs` table:
+parent linkage for forks, an optional label, and the original goal/frame.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Iterator, Optional, Protocol
+
+from activegraph.core.event import Event
+
+
+@dataclass
+class RunRecord:
+    run_id: str
+    parent_run_id: Optional[str]
+    forked_at_event_id: Optional[str]
+    label: Optional[str]
+    created_at: str
+    goal: Optional[str]
+    frame_id: Optional[str]
+
+
+class EventStore(Protocol):
+    """Append-only per-run event log. CONTRACT v0.5 #2."""
+
+    run_id: str
+
+    def append(self, event: Event) -> None: ...
+
+    def iter_events(
+        self,
+        after: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> Iterator[Event]: ...
+
+    def get_event(self, event_id: str) -> Optional[Event]: ...
+
+    def count(self) -> int: ...
+
+    def truncate_after(self, event_id: str) -> None: ...
+
+    def close(self) -> None: ...
+
+
+def replay_into(graph, events: Iterable[Event]) -> int:
+    """Apply a stream of events to a Graph without firing listeners.
+
+    The single replay entry point — used by `Runtime.load` and `Runtime.fork`.
+    Returns the number of events replayed.
+    """
+    n = 0
+    for ev in events:
+        graph._replay_event(ev)  # noqa: SLF001 — internal seam by design
+        n += 1
+    return n

activegraph/store/conformance.py

@@ -0,0 +1,161 @@
+"""EventStore conformance suite. CONTRACT v0.8 #18.
+
+A reusable pytest-compatible base class that exercises any EventStore
+implementation against the protocol. Concrete subclasses override
+``make_store(run_id)`` and ``cleanup()``; the tests run identically.
+
+The InMemory, SQLite, and (with testcontainers) Postgres stores all run
+through this suite. Any future store implementation gets free coverage
+by subclassing.
+
+The suite intentionally avoids pytest fixtures and yields plain
+``unittest.TestCase``-style methods, so it works under any test runner.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+import pytest
+
+from activegraph.core.event import Event
+
+
+class EventStoreConformance(ABC):
+    """Mix into a pytest test class to inherit the full suite.
+
+    Subclasses MUST implement:
+
+        def make_store(self, run_id: str) -> EventStore: ...
+        def cleanup(self) -> None: ...
+
+    Tests are method names starting with ``test_``. They are picked up
+    by pytest automatically when the concrete subclass is collected.
+
+    The base class is abstract (no ``test_`` methods callable on it)
+    by virtue of ``make_store`` raising on the abstract class. pytest
+    will still try to collect it; the ``__test__ = False`` attribute
+    prevents that.
+    """
+
+    __test__ = False  # do not collect the base; subclasses override.
+
+    @abstractmethod
+    def make_store(self, run_id: str) -> Any:
+        """Return a fresh EventStore for ``run_id``. Called per test."""
+
+    def cleanup(self) -> None:
+        """Tear down any resources after a test. Default: no-op."""
+
+    # ---- helpers ----
+
+    def _ev(self, eid: str, type_: str = "object.created", payload: dict | None = None) -> Event:
+        return Event(
+            id=eid,
+            type=type_,
+            payload=payload or {"k": "v"},
+            actor="test",
+            frame_id=None,
+            caused_by=None,
+            timestamp="2026-01-01T00:00:00Z",
+        )
+
+    # ---- the suite ----
+
+    def test_append_then_iter_in_order(self) -> None:
+        try:
+            store = self.make_store("run_conformance_1")
+            for i in range(5):
+                store.append(self._ev(f"evt_{i}"))
+            ids = [e.id for e in store.iter_events()]
+            assert ids == [f"evt_{i}" for i in range(5)]
+        finally:
+            self.cleanup()
+
+    def test_count(self) -> None:
+        try:
+            store = self.make_store("run_conformance_2")
+            assert store.count() == 0
+            store.append(self._ev("evt_a"))
+            store.append(self._ev("evt_b"))
+            assert store.count() == 2
+        finally:
+            self.cleanup()
+
+    def test_get_event_known_and_unknown(self) -> None:
+        try:
+            store = self.make_store("run_conformance_3")
+            store.append(self._ev("evt_known"))
+            got = store.get_event("evt_known")
+            assert got is not None
+            assert got.id == "evt_known"
+            assert store.get_event("evt_missing") is None
+        finally:
+            self.cleanup()
+
+    def test_iter_after_skips_inclusive_boundary(self) -> None:
+        try:
+            store = self.make_store("run_conformance_4")
+            for i in range(4):
+                store.append(self._ev(f"evt_{i}"))
+            tail = [e.id for e in store.iter_events(after="evt_1")]
+            assert tail == ["evt_2", "evt_3"]
+        finally:
+            self.cleanup()
+
+    def test_iter_until_includes_boundary(self) -> None:
+        try:
+            store = self.make_store("run_conformance_5")
+            for i in range(4):
+                store.append(self._ev(f"evt_{i}"))
+            head = [e.id for e in store.iter_events(until="evt_2")]
+            assert head == ["evt_0", "evt_1", "evt_2"]
+        finally:
+            self.cleanup()
+
+    def test_truncate_after_drops_tail(self) -> None:
+        try:
+            store = self.make_store("run_conformance_6")
+            for i in range(5):
+                store.append(self._ev(f"evt_{i}"))
+            store.truncate_after("evt_2")
+            ids = [e.id for e in store.iter_events()]
+            assert ids == ["evt_0", "evt_1", "evt_2"]
+        finally:
+            self.cleanup()
+
+    def test_payload_round_trip_preserves_structure(self) -> None:
+        try:
+            store = self.make_store("run_conformance_7")
+            payload = {
+                "nested": {"k": [1, 2, {"a": "b"}]},
+                "unicode": "café — 🚀",
+                "empty": [],
+                "null_in_value": None,
+            }
+            store.append(self._ev("evt_payload", payload=payload))
+            got = store.get_event("evt_payload")
+            assert got is not None
+            assert got.payload == payload
+        finally:
+            self.cleanup()
+
+    def test_duplicate_id_in_same_run_is_rejected(self) -> None:
+        try:
+            store = self.make_store("run_conformance_8")
+            store.append(self._ev("evt_dup"))
+            with pytest.raises(Exception):
+                store.append(self._ev("evt_dup"))
+        finally:
+            self.cleanup()
+
+    def test_close_is_idempotent(self) -> None:
+        try:
+            store = self.make_store("run_conformance_9")
+            store.append(self._ev("evt_a"))
+            store.close()
+            # Closing twice should not raise.
+            store.close()
+        finally:
+            self.cleanup()

activegraph/store/errors.py

@@ -0,0 +1,84 @@
+"""Storage-layer error leaves. v1.0 PR-C — StorageError category.
+
+The classes here are the v1.0-format leaves under
+:class:`activegraph.errors.StorageError`. The two pre-v1.0 storage
+errors (:class:`NonSerializableEventError` in ``serde.py`` and
+:class:`InvalidStoreURL` in ``url.py``) stay in their topic modules
+and are re-parented in this PR; everything new lives here.
+
+Multi-inheritance with Python builtins (KeyError, ValueError) is used
+where existing user code conventionally catches the builtin —
+``except KeyError`` around a store lookup, ``except ValueError`` around
+event insertion. Preserves the catch site.
+
+DB-driver errors (sqlite3.OperationalError, psycopg.OperationalError)
+are NOT wrapped in this PR. The failure modes are driver-specific and
+the recovery prose varies enough per mode (WAL contention, auth, host
+unreachable, db missing, conn dropped) that a dedicated DB-error PR
+will cover them with the right per-mode "Why:" and "How to fix:"
+prose. Flagged in CONTRACT v1.0 PR-C section, not silently dropped.
+"""
+
+from __future__ import annotations
+
+from activegraph.errors import StorageError
+
+
+class SchemaVersionMismatch(StorageError):
+    """The store's recorded ``schema_version`` doesn't match what this
+    activegraph build expects.
+
+    Fires on store open. The store file is intact; it was just written
+    by a different (older or newer) activegraph build. Recovery is
+    one of three things: upgrade activegraph, downgrade the store via
+    migration, or migrate the run to a fresh store with the current
+    build.
+    """
+
+    _doc_slug = "schema-version-mismatch"
+
+
+class EventNotFoundError(StorageError, KeyError):
+    """An event id wasn't found in the run's event log.
+
+    Multi-inherits :class:`KeyError` so user code that does
+    ``except KeyError`` around store lookups keeps working. Fires from
+    every ``store.get_event(event_id)`` and from the fork primitive
+    when ``--at-event`` names a missing id.
+    """
+
+    _doc_slug = "event-not-found-error"
+
+
+class DuplicateEventError(StorageError, ValueError):
+    """Two events with the same id were appended to the same run.
+
+    Multi-inherits :class:`ValueError` for back-compat with user code
+    catching ValueError around appends. Fires only on programmer error:
+    the runtime's id generator is monotonic so duplicates shouldn't
+    arise in normal use. Common cause: hand-constructing events with
+    fixed ids in a test fixture.
+    """
+
+    _doc_slug = "duplicate-event-error"
+
+
+class CorruptedEventPayloadError(StorageError):
+    """A stored event payload couldn't be decoded as JSON.
+
+    Fires at load-time when a row's payload column contains invalid
+    JSON. Distinct from :class:`NonSerializableEventError`, which fires
+    at emit-time when a Python value can't be encoded to JSON.
+    Corruption-on-load means the bytes on disk don't parse — a
+    different failure mode requiring a different recovery.
+    """
+
+    _doc_slug = "corrupted-event-payload-error"
+
+
+__all__ = [
+    "SchemaVersionMismatch",
+    "EventNotFoundError",
+    "DuplicateEventError",
+    "CorruptedEventPayloadError",
+]