reactifact 0.6.0__py3-none-any.whl

reactifact/cli/scenario.py

@@ -0,0 +1,94 @@
+"""`reactifact scenario` — run `reactifact.testing` scenarios.
+
+A separate track from `pytest`: scenarios are `@scenario`-decorated functions
+(usually wrapping `ScenarioLab.run()`) living in ordinary modules, imported by
+dotted path exactly like `reactifact graph <module:Attr>` resolves agents — no
+`test_*.py` naming, no pytest collection, so a plain `pytest` run never needs a
+model key or a network connection. Point this at one or more modules and it
+imports them, runs whatever they registered, and reports PASS/FAIL/SKIP.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import inspect
+import os
+import time
+
+from ..testing.exceptions import ScenarioSkip
+from ..testing.record import MODE_ENV_VAR
+from ..testing.registry import ScenarioCase, collect
+
+
+async def _run_one(case: ScenarioCase) -> tuple[str, str]:
+    """Returns `(status, detail)` — status is one of PASS/FAIL/ERROR/SKIP."""
+    try:
+        result = case.func()
+        if inspect.isawaitable(result):
+            await result
+    except ScenarioSkip as exc:
+        return "SKIP", str(exc)
+    except AssertionError as exc:
+        return "FAIL", str(exc)
+    except Exception as exc:  # noqa: BLE001 — report, don't crash the run
+        return "ERROR", f"{type(exc).__name__}: {exc}"
+    return "PASS", ""
+
+
+def cmd_scenario(args: argparse.Namespace) -> int:
+    if args.mode is not None:
+        os.environ[MODE_ENV_VAR] = args.mode
+
+    cases = collect(args.modules)
+    if args.filter:
+        cases = [c for c in cases if args.filter in c.name]
+    if not cases:
+        print("no scenarios found (check the module path and -k filter)")
+        return 1
+
+    counts = {"PASS": 0, "FAIL": 0, "ERROR": 0, "SKIP": 0}
+    for case in cases:
+        started = time.monotonic()
+        status, detail = asyncio.run(_run_one(case))
+        elapsed = time.monotonic() - started
+        counts[status] += 1
+        line = f"{status:<5} {case.name} ({elapsed:.2f}s)"
+        print(line)
+        if detail:
+            print(f"      {detail}")
+
+    total = len(cases)
+    print(
+        f"\n{total} scenario(s): {counts['PASS']} passed, {counts['FAIL']} failed, "
+        f"{counts['ERROR']} errored, {counts['SKIP']} skipped"
+    )
+    return 1 if counts["FAIL"] or counts["ERROR"] else 0
+
+
+def add_parser(sub: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    p_scenario = sub.add_parser(
+        "scenario", help="run reactifact.testing scenarios (separate from pytest)"
+    )
+    p_scenario.add_argument(
+        "modules",
+        nargs="+",
+        help='dotted module path(s) to import, e.g. "examples.repair.scenarios"',
+    )
+    p_scenario.add_argument(
+        "-k",
+        "--filter",
+        default=None,
+        help="only run scenarios whose name contains this substring",
+    )
+    p_scenario.add_argument(
+        "--mode",
+        choices=["live", "record", "replay"],
+        default=None,
+        help=(
+            "sets REACTIFACT_SCENARIO_MODE for scenarios built with "
+            "reactifact.testing.mode_from_env() — most scenarios default to "
+            "'live' or opt out entirely without it"
+        ),
+    )
+    p_scenario.set_defaults(func=cmd_scenario)

reactifact/cli/trace.py

@@ -0,0 +1,45 @@
+"""`reactifact trace` — run diagram from a trace store (SQLite)."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def cmd_trace(args: argparse.Namespace) -> int:
+    import asyncio
+    import sqlite3
+
+    from ..tracing import TraceStore
+    from ..viz import trace_to_mermaid
+
+    store = TraceStore(args.path)
+
+    async def _run() -> int:
+        trace_id = args.run_id
+        try:
+            if trace_id is None:
+                result = await store.query(limit=1)
+                if not result["items"]:
+                    print("no traces found")
+                    return 1
+                trace_id = result["items"][0]["id"]
+            trace = await store.get(trace_id)
+        except sqlite3.OperationalError:
+            print(f"no trace store found at {args.path!r}")
+            return 1
+        if trace is None:
+            print(f"trace {trace_id!r} not found")
+            return 1
+        print(trace_to_mermaid(trace))
+        return 0
+
+    return asyncio.run(_run())
+
+
+def add_parser(sub: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    p_trace = sub.add_parser("trace", help="run diagram from a trace store")
+    p_trace.add_argument("path", help="trace SQLite db")
+    p_trace.add_argument(
+        "run_id", nargs="?", default=None, help="run id (default: latest)"
+    )
+    p_trace.set_defaults(func=cmd_trace)

reactifact/commit.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from .patches import Operation, operation_from_dict
+
+
+@dataclass
+class Read:
+    """A record of a consumed artifact: the runtime builds links from consumes.
+
+    Records the fact that the artifact was read at a specific revision
+    (git-like ancestor).
+    """
+
+    artifact_id: str
+    version: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"artifact_id": self.artifact_id, "version": self.version}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Read:
+        return cls(artifact_id=d["artifact_id"], version=d["version"])
+
+
+@dataclass
+class Write:
+    """A record of an artifact produced/changed by a single commit."""
+
+    artifact_id: str
+    version: int
+    op_type: str  # create | update | delete
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "artifact_id": self.artifact_id,
+            "version": self.version,
+            "op_type": self.op_type,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Write:
+        return cls(
+            artifact_id=d["artifact_id"],
+            version=d["version"],
+            op_type=d["op_type"],
+        )
+
+
+@dataclass
+class Commit:
+    """A record of one applied patch.
+
+    Commits form a git-like chain: each commit knows its parent, was executed
+    against a specific Context version and carries a reads/writes trace.
+    """
+
+    author: str
+    message: str
+    operations: list[Operation]
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    parent_id: str | None = None
+    context_version: int | None = None
+    reads: list[Read] = field(default_factory=list)
+    writes: list[Write] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "author": self.author,
+            "message": self.message,
+            "timestamp": self.timestamp.isoformat(),
+            "operations": [op.to_dict() for op in self.operations],
+            "parent_id": self.parent_id,
+            "context_version": self.context_version,
+            "reads": [r.to_dict() for r in self.reads],
+            "writes": [w.to_dict() for w in self.writes],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Commit:
+        return cls(
+            author=d["author"],
+            message=d["message"],
+            operations=[operation_from_dict(op) for op in d["operations"]],
+            id=d["id"],
+            timestamp=datetime.fromisoformat(d["timestamp"]),
+            parent_id=d.get("parent_id"),
+            context_version=d.get("context_version"),
+            reads=[Read.from_dict(r) for r in d.get("reads", [])],
+            writes=[Write.from_dict(w) for w in d.get("writes", [])],
+        )

reactifact/commit_log.py

@@ -0,0 +1,235 @@
+"""reactifact.commit_log — the git-like commit chain (§12).
+
+Extracted out of `Context`: `CommitLog` owns the ordered list of applied
+`Commit`s, the current version/head, and the pure "replay commits into a
+state snapshot" logic (`replay_state`/`replay_relations`) that `checkout`,
+`diff`, and staleness detection all build on. It knows nothing about the
+live artifact/relation stores — `Context` still owns those and asks the log
+to replay itself when it needs a past or reconstructed state.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from .commit import Commit
+from .patches import Create, Delete, Link, Relation, Unlink, Update
+from .relations import RelationKey
+
+
+class CommitLog:
+    """The applied-commit chain: append, replay, roll back (§12).
+
+    Alongside the commit list, maintains two incrementally-updated indices so
+    `producing_commit`/`dependents_of` stay O(1)/O(dependents) instead of
+    scanning every commit on every call (the two hot paths behind
+    `Context.stale_artifacts()`/`_dependents_of()`):
+
+    - `_last_write_commit`: artifact_id → the commit that last wrote it.
+    - `_dependents`: artifact_id → the set of artifact ids whose *current*
+      producing commit reads it (i.e. "who depends on me right now").
+      `_producing_read_ids` tracks each artifact's current read-set so a
+      later rewrite can remove its stale edges before adding the new ones.
+    """
+
+    __slots__ = (
+        "_commits",
+        "_version",
+        "_head_id",
+        "_last_write_commit",
+        "_dependents",
+        "_producing_read_ids",
+        "_dict_cache",
+    )
+
+    def __init__(self) -> None:
+        self._commits: list[Commit] = []
+        self._version: int = 0
+        self._head_id: str | None = None
+        self._last_write_commit: dict[str, Commit] = {}
+        self._dependents: dict[str, set[str]] = {}
+        self._producing_read_ids: dict[str, set[str]] = {}
+        # Memoized Commit.to_dict(), keyed by commit id: a commit is immutable
+        # once appended (writes/reads/operations never change afterward), so
+        # this can never go stale — see `to_dict()`.
+        self._dict_cache: dict[str, dict[str, Any]] = {}
+
+    @property
+    def version(self) -> int:
+        """Current version (number of applied commits)."""
+        return self._version
+
+    @property
+    def head_id(self) -> str | None:
+        """Id of the last commit (HEAD)."""
+        return self._head_id
+
+    def append(self, commit: Commit) -> None:
+        """Fills in parent/version and moves head (was `Context.log_commit`)."""
+        commit.parent_id = self._head_id
+        commit.context_version = self._version + 1
+        self._commits.append(commit)
+        self._head_id = commit.id
+        self._version += 1
+        self._index_commit(commit)
+
+    def _index_commit(self, commit: Commit) -> None:
+        """Updates `_last_write_commit`/`_dependents` for one appended commit."""
+        for write in commit.writes:
+            aid = write.artifact_id
+            old_sources = self._producing_read_ids.get(aid)
+            if old_sources:
+                for src in old_sources:
+                    deps = self._dependents.get(src)
+                    if deps is not None:
+                        deps.discard(aid)
+                        if not deps:
+                            del self._dependents[src]
+            self._last_write_commit[aid] = commit
+            new_sources = {r.artifact_id for r in commit.reads}
+            self._producing_read_ids[aid] = new_sources
+            for src in new_sources:
+                self._dependents.setdefault(src, set()).add(aid)
+
+    def _rebuild_indices(self) -> None:
+        """Full rebuild from `_commits` — used after a bulk rewrite (truncate,
+        copy, deserialize) where per-commit incremental updates don't apply."""
+        self._last_write_commit = {}
+        self._dependents = {}
+        self._producing_read_ids = {}
+        for commit in self._commits:
+            self._index_commit(commit)
+
+    def history(self) -> list[Commit]:
+        """Ordered chain of commits from the oldest to head."""
+        return list(self._commits)
+
+    def __len__(self) -> int:
+        return len(self._commits)
+
+    def commits_from(self, index: int) -> list[Commit]:
+        """Commits at `index` and after (used by `checkout` to find what a
+        rollback would undo)."""
+        return self._commits[index:]
+
+    def commits_upto(self, upto_version: int) -> list[Commit]:
+        """Commits before `upto_version` (used by the replay methods)."""
+        return self._commits[:upto_version]
+
+    def producing_commit(self, artifact_id: str) -> Commit | None:
+        """The last commit that wrote the artifact (create or update)."""
+        return self._last_write_commit.get(artifact_id)
+
+    def dependents_of(self, artifact_id: str) -> set[str]:
+        """Artifact ids whose current producing commit reads `artifact_id`.
+
+        Structural only (ignores versions) — the caller still checks whether
+        the dependency is actually stale right now. Scoped to this artifact's
+        real dependents, not every artifact in the context.
+        """
+        return set(self._dependents.get(artifact_id, ()))
+
+    def truncate(self, version: int) -> None:
+        """Rolls the log back to `version`: drops later commits, moves head.
+
+        `version=0` means "before any commit" (no head).
+        """
+        if version == 0:
+            self._head_id = None
+        else:
+            self._head_id = self._commits[version - 1].id
+        del self._commits[version:]
+        self._version = version
+        self._rebuild_indices()
+        live_ids = {c.id for c in self._commits}
+        self._dict_cache = {
+            cid: d for cid, d in self._dict_cache.items() if cid in live_ids
+        }
+
+    def replay_state(self, upto_version: int) -> dict[str, Any]:
+        """Replays the artifact state by applying commits up to and including
+        the version."""
+        state: dict[str, Any] = {}
+        for commit in self.commits_upto(upto_version):
+            for op in commit.operations:
+                if isinstance(op, Create) and op.artifact_id is not None:
+                    state[op.artifact_id] = op.data.model_copy(deep=True)
+                elif isinstance(op, Update):
+                    state[op.artifact_id] = op.new_data.model_copy(deep=True)
+                elif isinstance(op, Delete):
+                    state.pop(op.artifact_id, None)
+        return state
+
+    def replay_relations(self, upto_version: int) -> dict[RelationKey, Relation]:
+        """Replays the link graph from commits up to and including the version."""
+        relations: dict[RelationKey, Relation] = {}
+        for commit in self.commits_upto(upto_version):
+            for op in commit.operations:
+                if isinstance(op, Link):
+                    key = (op.artifact_id, op.relation, op.target_id)
+                    relations[key] = Relation(*key)
+                elif isinstance(op, Unlink):
+                    for key in list(relations.keys()):
+                        if key[0] != op.artifact_id:
+                            continue
+                        if op.relation is not None and key[1] != op.relation:
+                            continue
+                        if op.target_id is not None and key[2] != op.target_id:
+                            continue
+                        del relations[key]
+        return relations
+
+    def copy(self) -> CommitLog:
+        clone = CommitLog()
+        clone._commits = copy.deepcopy(self._commits)
+        clone._version = self._version
+        clone._head_id = self._head_id
+        # Deep-copied commits are new objects — re-derive the indices instead
+        # of copying dicts that would still point at the originals.
+        clone._rebuild_indices()
+        # A commit's serialized form only depends on its (unchanged-by-copy)
+        # field values, keyed by its (unchanged-by-copy) id — safe to carry
+        # the cache over instead of re-serializing on the clone's first save.
+        clone._dict_cache = dict(self._dict_cache)
+        return clone
+
+    def to_dict(self) -> list[dict[str, Any]]:
+        """Serializes the commit chain, memoized per commit id.
+
+        A commit is immutable once appended (`writes` is filled in before
+        `Context.log_commit()` and never touched again), so re-serializing an
+        already-serialized commit on every `Context.to_dict()`/session save
+        is pure waste for a long-lived context — only new commits since the
+        last call actually get `Commit.to_dict()` called on them.
+        """
+        result = []
+        for c in self._commits:
+            cached = self._dict_cache.get(c.id)
+            if cached is None:
+                cached = c.to_dict()
+                self._dict_cache[c.id] = cached
+            result.append(cached)
+        return result
+
+    @classmethod
+    def from_dict(
+        cls,
+        commits: list[dict[str, Any]],
+        *,
+        version: int | None,
+        head_id: str | None,
+    ) -> CommitLog:
+        log = cls()
+        log._commits = [Commit.from_dict(cd) for cd in commits]
+        log._version = version if version is not None else len(log._commits)
+        log._head_id = (
+            head_id
+            if head_id is not None
+            else (log._commits[-1].id if log._commits else None)
+        )
+        log._rebuild_indices()
+        return log
+
+
+__all__ = ["CommitLog"]

reactifact/consume.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from .artifacts import Artifact, ArtifactType
+from .events import EventType
+from .triggers import Trigger
+
+
+class Consume:
+    """Describes the consumed artifact type, condition and triggering events.
+
+    All parameters can be set as class attributes (for inheritance)
+    or passed to the constructor.
+    """
+
+    artifact_type: ArtifactType | None = None
+    condition: Callable[[Artifact[Any]], bool] | None = None
+    event_types: Sequence[EventType] = (
+        EventType.ARTIFACT_CREATED,
+        EventType.ARTIFACT_UPDATED,
+    )
+
+    def __init__(
+        self,
+        artifact_type: ArtifactType | None = None,
+        condition: Callable[[Artifact[Any]], bool] | None = None,
+        event_types: Sequence[EventType] | None = None,
+    ):
+        self.artifact_type = artifact_type or self.__class__.artifact_type
+        if self.artifact_type is None:
+            raise ValueError(
+                "artifact_type must be provided either as class attribute or constructor argument"
+            )
+
+        self.condition = (
+            condition if condition is not None else self.__class__.condition
+        )
+        self.event_types = list(
+            event_types if event_types is not None else self.__class__.event_types
+        )
+
+    def to_triggers(self) -> list[Trigger]:
+        """Converts into a list of triggers for automatic reaction."""
+        return [
+            Trigger(event_type, self.artifact_type, self.condition)
+            for event_type in self.event_types
+        ]
+
+    @classmethod
+    def by_status(
+        cls,
+        artifact_type: ArtifactType,
+        status: str,
+        event_types: Sequence[EventType] = (
+            EventType.ARTIFACT_CREATED,
+            EventType.ARTIFACT_UPDATED,
+        ),
+    ) -> Consume:
+        """Creates a Consume with a condition on the equality of the status field."""
+        return cls(
+            artifact_type,
+            condition=lambda art: getattr(art.data, "status", None) == status,
+            event_types=event_types,
+        )
+
+    @classmethod
+    def by_field(
+        cls,
+        artifact_type: ArtifactType,
+        field: str,
+        value: Any,
+        event_types: Sequence[EventType] = (
+            EventType.ARTIFACT_CREATED,
+            EventType.ARTIFACT_UPDATED,
+        ),
+    ) -> Consume:
+        """Creates a Consume with a condition on the equality of an arbitrary field."""
+        return cls(
+            artifact_type,
+            condition=lambda art: getattr(art.data, field, None) == value,
+            event_types=event_types,
+        )
+
+
+def consume(
+    artifact_type: ArtifactType,
+    condition: Callable[[Artifact[Any]], bool] | None = None,
+    event_types: Sequence[EventType] = (
+        EventType.ARTIFACT_CREATED,
+        EventType.ARTIFACT_UPDATED,
+    ),
+) -> Consume:
+    """Factory for quickly creating a Consume."""
+    return Consume(artifact_type, condition, event_types)