reactifact 0.9.1__tar.gz → 0.10.0__tar.gz

{reactifact-0.9.1/reactifact.egg-info → reactifact-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.9.1
+Version: 0.10.0
 Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/bzdvdn/reactifact
@@ -250,6 +250,9 @@ uv run python ./examples/devops/web.py         # HITL ops assistant + trace dash
 Classic-pattern ports run as one-liners too:
 `python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
 
+Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/bzdvdn/reactifact/blob/master/examples/quickstart.ipynb)
+— `examples/quickstart.ipynb` covers the four `quick` cases (`agent`/`rag`/`tools_agent`/`chat_agent`), offline by default.
+
 ## Examples (in-repo, not shipped)
 
 - `knowledge` — multi-source chat: search → evidence → claim verification → answer, with CSV calculation.
@@ -267,8 +270,11 @@ Classic-pattern ports run as one-liners too:
 
 - [English](docs/en/index.md) · [Русский](docs/ru/index.md) — concepts, sources,
   providers, recipes, patterns, observability, eval, branching, replay, viz/CLI, API.
-- [Quickstart](docs/en/quickstart.md) — three runnable snippets: tool-calling
-  agent, retrieval over your docs, session-persisted chat bot.
+- [Quickstart](docs/en/quickstart.md) — the four `quick` cases (structured call,
+  RAG, tools, chat) in a few lines; also as a
+  [Colab notebook](examples/quickstart.ipynb).
+- [Migrating](docs/en/migrating.md) — from LangGraph / CrewAI / LlamaIndex /
+  plain Python: concept map, port-one-node, interop, checklist.
 - [Why reactifact](docs/en/why-reactifact.md) — the *design argument*: why effects, why no graph, why determinism.
 - [Comparison](docs/en/comparison.md) — reactifact vs LangGraph/CrewAI, feature by feature, and when *not* to use reactifact.
 - [Tutorial · llm-ladder](docs/en/examples.md#tutorial-ladder) — learn the workflow.

{reactifact-0.9.1 → reactifact-0.10.0}/README.md

@@ -206,6 +206,9 @@ uv run python ./examples/devops/web.py         # HITL ops assistant + trace dash
 Classic-pattern ports run as one-liners too:
 `python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
 
+Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/bzdvdn/reactifact/blob/master/examples/quickstart.ipynb)
+— `examples/quickstart.ipynb` covers the four `quick` cases (`agent`/`rag`/`tools_agent`/`chat_agent`), offline by default.
+
 ## Examples (in-repo, not shipped)
 
 - `knowledge` — multi-source chat: search → evidence → claim verification → answer, with CSV calculation.
@@ -223,8 +226,11 @@ Classic-pattern ports run as one-liners too:
 
 - [English](docs/en/index.md) · [Русский](docs/ru/index.md) — concepts, sources,
   providers, recipes, patterns, observability, eval, branching, replay, viz/CLI, API.
-- [Quickstart](docs/en/quickstart.md) — three runnable snippets: tool-calling
-  agent, retrieval over your docs, session-persisted chat bot.
+- [Quickstart](docs/en/quickstart.md) — the four `quick` cases (structured call,
+  RAG, tools, chat) in a few lines; also as a
+  [Colab notebook](examples/quickstart.ipynb).
+- [Migrating](docs/en/migrating.md) — from LangGraph / CrewAI / LlamaIndex /
+  plain Python: concept map, port-one-node, interop, checklist.
 - [Why reactifact](docs/en/why-reactifact.md) — the *design argument*: why effects, why no graph, why determinism.
 - [Comparison](docs/en/comparison.md) — reactifact vs LangGraph/CrewAI, feature by feature, and when *not* to use reactifact.
 - [Tutorial · llm-ladder](docs/en/examples.md#tutorial-ladder) — learn the workflow.

{reactifact-0.9.1 → reactifact-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.9.1"
+version = "0.10.0"
 description = "Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -118,6 +118,9 @@ fail_under = 85
 target-version = "py311"
 line-length = 88
 src = ["reactifact", "examples"]
+# Notebooks are Colab artifacts (IPython magics, top-level await) — not package
+# code; don't lint/format them.
+extend-exclude = ["*.ipynb"]
 
 [tool.ruff.lint]
 select = [

{reactifact-0.9.1 → reactifact-0.10.0}/reactifact/__init__.py

@@ -42,13 +42,14 @@ from .providers import (
     LLMResponseChunk,
     Message,
 )
-from .resources import RuntimeResources
+from .request import current_request
+from .resources import ResourceKey, ResourceScope, RuntimeResources
 from .runtime import Runtime
 from .session import Session, SessionStore
 from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
 
-__version__ = "0.9.1"
+__version__ = "0.10.0"
 
 __all__ = [
     "Agent",
@@ -74,6 +75,8 @@ __all__ = [
     "Produce",
     "ProduceCall",
     "Relation",
+    "ResourceKey",
+    "ResourceScope",
     "RunOutcome",
     "RunStats",
     "Runtime",
@@ -92,6 +95,7 @@ __all__ = [
     "View",
     "consume",
     "create_agent",
+    "current_request",
     "produce",
     "tool",
 ]

reactifact-0.10.0/reactifact/_httpx.py

@@ -0,0 +1,87 @@
+"""Loop-aware `httpx.AsyncClient` ownership for providers and sinks.
+
+`httpx.AsyncClient` binds its connection pool (and internal locks) to the event
+loop it was created on. A provider/sink instance that caches the client forever
+and is then reused on a *different* loop — pytest gives each test its own loop,
+a CLI calls `asyncio.run(...)` more than once, uvicorn reloads — raises
+`RuntimeError: Event loop is closed` (or "bound to a different event loop") on
+the second use.
+
+`LoopBoundClient` keeps the client **lazy** (created on first use, as before)
+but **rebinds it to the current running loop**: when the loop changes, a fresh
+client is created. The previous client's loop is already gone, so it is dropped
+rather than awaited (its pool died with the loop). An injected `client=` (tests,
+a custom transport) is returned as-is and never recreated.
+
+Typical use inside a provider:
+
+    self._http = LoopBoundClient(
+        lambda: httpx.AsyncClient(timeout=self._timeout, headers=self._headers)
+    )
+
+    async def complete(self, ...):
+        response = await self._http.get().post(url, json=payload)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import Any, cast
+
+import httpx
+
+
+class LoopBoundClient:
+    """Owns an `httpx.AsyncClient` bound to the current event loop."""
+
+    def __init__(
+        self,
+        factory: Callable[[], httpx.AsyncClient],
+        *,
+        client: Any | None = None,
+    ):
+        self._factory = factory
+        self._fixed = client
+        self._client: httpx.AsyncClient | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    def get(self) -> httpx.AsyncClient:
+        """The client for the running loop (created/recreated as needed)."""
+        if self._fixed is not None:
+            return cast("httpx.AsyncClient", self._fixed)
+        loop = asyncio.get_running_loop()
+        if self._client is None or self._loop is not loop:
+            self._client = self._factory()
+            self._loop = loop
+        return self._client
+
+    async def aclose(self) -> None:
+        """Closes the current client, if it belongs to the running loop.
+
+        A client whose owner loop is closed (or is a different, still-running
+        loop) cannot be awaited here; it is dropped — nothing can safely close
+        it from this loop. The injected `client=`, if any, is left to its owner.
+        """
+        client, loop = self._client, self._loop
+        self._client = None
+        self._loop = None
+        if client is None:
+            return
+        try:
+            current = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        if loop is not None and loop is not current:
+            return
+        await client.aclose()
+
+    def raw(self) -> Any | None:
+        """The injected client if there is one, else the current one (or None)."""
+        return self._fixed if self._fixed is not None else self._client
+
+
+__all__ = ["LoopBoundClient"]

reactifact-0.10.0/reactifact/audit.py

@@ -0,0 +1,255 @@
+"""reactifact.audit — answer provenance and reproducibility (§34, §55, §56).
+
+Two things an auditable agent needs, both offline and dependency-free:
+
+1. `build_report(context, answer)` — a self-contained record of *why* an answer
+   exists: the answer's content hash, the provenance chain behind it
+   (`supported_by` / `derived_from` / `materialized_from` / …), each artifact's
+   version, author and content hash, and the source locators it rests on.
+   Exportable as JSON (machine-checkable) or Markdown (human/regulator-readable).
+
+2. `context_hash(context)` — a sha256 over the run's canonical state
+   (artifacts + relations + version). Two runs that produce the same state hash
+   the same; recording it with a `ReplayLLM` recording turns "is this run
+   reproducible?" into a string comparison (`reactifact replay --verify <hash>`,
+   and the `fintech_audit` example).
+
+Hashes are sha256 over canonical (sorted, JSON-safe) content, so the *hash*
+fields are reproducible: the same state yields the same `context_sha256` and
+per-artifact hashes, run to run. The report also carries `created_at` values
+for a human reader, so the full JSON is not byte-identical across runs — the
+fingerprint is.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+from .artifacts import Artifact
+from .context import Context
+
+#: Relations followed by default when walking an answer's provenance chain.
+DEFAULT_RELATIONS: tuple[str, ...] = (
+    "supported_by",
+    "derived_from",
+    "extracted_from",
+    "materialized_from",
+    "resolved_from",
+    "calculated_from",
+    "refuted_by",
+    "contradicted_by",
+)
+
+
+def _canonical(value: Any) -> str:
+    """Canonical JSON for hashing (sorted keys; pydantic models dumped)."""
+    if isinstance(value, BaseModel):
+        payload: Any = value.model_dump(mode="json")
+    else:
+        payload = value
+    return json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str)
+
+
+def data_hash(value: Any) -> str:
+    """sha256 of a value's canonical JSON — a stable content fingerprint."""
+    return hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest()
+
+
+def artifact_hash(artifact: Artifact[Any]) -> str:
+    """Content hash of one artifact's data (its type + id are not included)."""
+    return data_hash(artifact.data)
+
+
+def context_hash(context: Context) -> str:
+    """sha256 over the run's canonical state: version, artifacts, relations.
+
+    Includes each artifact's id, type, version and content hash, plus every
+    relation edge — everything that makes two runs' states the same or
+    different. Timestamps are deliberately excluded, so a re-run that reaches
+    the same state hashes identically.
+    """
+    artifacts = [
+        {
+            "id": artifact.id,
+            "type": type(artifact.data).__name__,
+            "version": artifact.version,
+            "sha256": artifact_hash(artifact),
+        }
+        for artifact in sorted(context.list_artifacts(), key=lambda a: a.id)
+    ]
+    relations = sorted(
+        (rel.source_id, rel.relation, rel.target_id) for rel in context.relations()
+    )
+    payload = {
+        "version": context.version,
+        "artifacts": artifacts,
+        "relations": relations,
+    }
+    return hashlib.sha256(_canonical(payload).encode("utf-8")).hexdigest()
+
+
+class ProvenanceEntry(BaseModel):
+    """One artifact in an answer's provenance chain, with its content hash."""
+
+    artifact_id: str
+    data_type: str
+    version: int
+    sha256: str
+    produced_by: str = ""
+    created_at: datetime | None = None
+
+
+class AuditReport(BaseModel):
+    """A reproducible record of an answer and the evidence behind it."""
+
+    session_id: str = ""
+    context_version: int
+    context_sha256: str
+    answer: ProvenanceEntry
+    provenance: list[ProvenanceEntry] = []
+    relations: list[tuple[str, str, str]] = []
+    sources: list[str] = []
+
+
+def _entry(artifact: Artifact[Any], produced_by: str) -> ProvenanceEntry:
+    return ProvenanceEntry(
+        artifact_id=artifact.id,
+        data_type=type(artifact.data).__name__,
+        version=artifact.version,
+        sha256=artifact_hash(artifact),
+        produced_by=produced_by,
+        created_at=artifact.created_at,
+    )
+
+
+def _producers(context: Context) -> dict[str, str]:
+    """artifact_id → author of the commit that last wrote it (from history)."""
+    producers: dict[str, str] = {}
+    for commit in context.history():
+        for write in commit.writes:
+            producers[write.artifact_id] = commit.author
+    return producers
+
+
+def _resolve_answer(context: Context, answer: Artifact[Any] | str) -> Artifact[Any]:
+    if isinstance(answer, Artifact):
+        return answer
+    artifact = context.get(answer)
+    if artifact is None:
+        raise KeyError(f"answer artifact {answer!r} not found in context")
+    return artifact
+
+
+def build_report(
+    context: Context,
+    answer: Artifact[Any] | str,
+    *,
+    relations: Sequence[str] | None = None,
+    session_id: str = "",
+) -> AuditReport:
+    """Walks the provenance chain behind `answer` into a verifiable report.
+
+    Breadth-first over `context.relations()`, following `relations` (all by
+    default), so every artifact that contributed to the answer is included with
+    its content hash and producing author. `SourceRef` locators in the chain
+    become `sources`.
+    """
+    followed = set(relations) if relations is not None else set(DEFAULT_RELATIONS)
+    answer_artifact = _resolve_answer(context, answer)
+    producers = _producers(context)
+
+    entries: list[ProvenanceEntry] = []
+    edges: list[tuple[str, str, str]] = []
+    sources: list[str] = []
+    visited: set[str] = set()
+    queue = [answer_artifact]
+    while queue:
+        artifact = queue.pop(0)
+        if artifact.id in visited:
+            continue
+        visited.add(artifact.id)
+        entries.append(_entry(artifact, producers.get(artifact.id, "")))
+        locator = getattr(artifact.data, "locator", None)
+        if isinstance(locator, str) and locator and locator not in sources:
+            sources.append(locator)
+        for rel in context.relations(source_id=artifact.id):
+            if rel.relation not in followed:
+                continue
+            edges.append((rel.source_id, rel.relation, rel.target_id))
+            target = context.get(rel.target_id)
+            if target is not None and target.id not in visited:
+                queue.append(target)
+
+    return AuditReport(
+        session_id=session_id,
+        context_version=context.version,
+        context_sha256=context_hash(context),
+        answer=entries[0],
+        provenance=entries[1:],
+        relations=edges,
+        sources=sources,
+    )
+
+
+def report_to_json(report: AuditReport, *, indent: int | None = 2) -> str:
+    """The report as canonical JSON (sorted keys → reproducible bytes)."""
+    return json.dumps(
+        report.model_dump(mode="json"),
+        indent=indent,
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+
+
+def report_to_markdown(report: AuditReport) -> str:
+    """The report as Markdown — for a PR comment, a ticket, or a regulator."""
+    lines = [
+        "# Audit report",
+        "",
+        f"- context version: {report.context_version}",
+        f"- context sha256: `{report.context_sha256}`",
+        f"- session: {report.session_id or '(none)'}",
+        "",
+        "## Answer",
+        "",
+        f"- `{report.answer.artifact_id}` ({report.answer.data_type}, "
+        f"v{report.answer.version})",
+        f"- sha256: `{report.answer.sha256}`",
+        f"- produced by: {report.answer.produced_by or '(seed)'}",
+        "",
+        "## Provenance",
+        "",
+        "| artifact | type | v | sha256 | produced by |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for entry in [report.answer, *report.provenance]:
+        lines.append(
+            f"| `{entry.artifact_id}` | {entry.data_type} | {entry.version} | "
+            f"`{entry.sha256[:12]}…` | {entry.produced_by or '(seed)'} |"
+        )
+    if report.relations:
+        lines += ["", "## Edges", ""]
+        lines += [f"- `{s}` —{r}→ `{t}`" for s, r, t in report.relations]
+    if report.sources:
+        lines += ["", "## Sources", ""]
+        lines += [f"- `{source}`" for source in report.sources]
+    return "\n".join(lines) + "\n"
+
+
+__all__ = [
+    "DEFAULT_RELATIONS",
+    "AuditReport",
+    "ProvenanceEntry",
+    "artifact_hash",
+    "build_report",
+    "context_hash",
+    "data_hash",
+    "report_to_json",
+    "report_to_markdown",
+]

{reactifact-0.9.1 → reactifact-0.10.0}/reactifact/chat.py

@@ -18,7 +18,13 @@ from __future__ import annotations
 import asyncio
 import inspect
 import logging
-from collections.abc import AsyncGenerator, AsyncIterator, Callable, Sequence
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterator,
+    Callable,
+    Mapping,
+    Sequence,
+)
 from contextlib import asynccontextmanager
 from typing import Any, Literal
 
@@ -35,15 +41,24 @@ from .session import Session, SessionStore
 logger = logging.getLogger("reactifact.chat")
 
 
+#: The three frame kinds of the canonical chat (start / progress / terminal).
+ChatEventKind = Literal["session", "status", "message"]
+
+
 class ChatEvent(BaseModel):
     """One frame of a chat turn, transport-neutral.
 
     `kind` is the wire contract of the canonical chat:
     ``session`` (start), ``status`` (progress announcement) or ``message``
-    (terminal reply).
+    (terminal reply). It is a closed `Literal`, so the schema is
+    introspectable (`ChatEvent.model_json_schema()`) and a typo is a type
+    error, not a frame a client silently ignores. To *rename* these on the
+    wire for a client that speaks a different vocabulary, configure
+    `reactifact.web.create_chat_router(event_names=…)` — don't fork the
+    router.
     """
 
-    kind: str
+    kind: ChatEventKind
     session_id: str = ""
     message: str = ""
     waiting: bool = False
@@ -68,6 +83,7 @@ async def run_message(
     create_message: Callable[..., str] | None = None,
     status_kinds: Sequence[str] = ("status",),
     fallback_reply: str = "No reply assembled.",
+    request: Mapping[str, Any] | None = None,
 ) -> AsyncIterator[ChatEvent]:
     """Run one user turn: create the input artifact, stream status events,
     emit the terminal reply.
@@ -111,7 +127,7 @@ async def run_message(
 
     last: str | None = None
     try:
-        async for event in runtime.astream():
+        async for event in runtime.astream(request=request):
             if event.kind not in forwarded:
                 continue
             if event.message == last:
@@ -342,13 +358,26 @@ class ChatAssistant:
             session_save_policy=self._session_save_policy,
         )
 
-    async def stream(self, text: str, session_id: str = "") -> AsyncIterator[ChatEvent]:
+    async def stream(
+        self,
+        text: str,
+        session_id: str = "",
+        *,
+        request: Mapping[str, Any] | None = None,
+    ) -> AsyncIterator[ChatEvent]:
         """Stream one turn: ``session`` → ``status``… → ``message``.
 
         Never raises for app-level failures: session open / runtime crash /
         reply hook all degrade to the fallback `message` and are logged via the
         `reactifact.chat` logger, so a web layer never delivers a 500 mid-stream.
 
+        **Cancellation contract:** closing/`aclose()`-ing the returned generator
+        (what a dropped SSE client does to the server's streaming task) cancels
+        the in-flight turn — the `CancelledError` unwinds through `run_message`
+        to `Runtime.astream`, whose `finally` cancels the runner task, so a slow
+        agent or LLM call is stopped rather than left burning tokens. `stream`
+        still saves the session in its own `finally` first.
+
         Turns on the same `session_id` are serialized (`_locked_session`): a
         second concurrent call for the same session waits for the first to
         finish instead of racing it to `session.save()` (§59 — no silent lost
@@ -382,6 +411,7 @@ class ChatAssistant:
                     status_kinds=self._status_kinds,
                     fallback_reply=self._fallback_reply,
                     session_id=session_id,
+                    request=request,
                 ):
                     yield event
             finally:
@@ -405,10 +435,16 @@ class ChatAssistant:
                             session_id,
                         )
 
-    async def invoke(self, text: str, session_id: str = "") -> dict[str, Any]:
+    async def invoke(
+        self,
+        text: str,
+        session_id: str = "",
+        *,
+        request: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
         """Run one turn and return the terminal reply (aggregated stream)."""
         message: dict[str, Any] = {}
-        async for event in self.stream(text, session_id=session_id):
+        async for event in self.stream(text, session_id=session_id, request=request):
             if event.kind == "message":
                 message = dict(event.payload) or {"reply": self._fallback_reply}
         return message
@@ -434,6 +470,7 @@ class ChatAssistant:
 __all__ = [
     "ChatAssistant",
     "ChatEvent",
+    "ChatEventKind",
     "default_session_state",
     "run_message",
 ]

{reactifact-0.9.1 → reactifact-0.10.0}/reactifact/checkpoints.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import copy
 import json
 import sqlite3
 import time
@@ -46,6 +47,34 @@ class KVBackend(ABC):
         """Releases held resources (a pooled connection, ...). No-op by default."""
 
 
+class InMemoryKVBackend(KVBackend):
+    """Dict-backed KV store — no files, no external service.
+
+    The zero-config backend: ideal for tests, notebooks, and short-lived
+    scripts where a session only needs to survive within one process. State
+    is lost on exit (use `FileKVBackend`/`SQLiteKVBackend` to persist). Values
+    are deep-copied on the way in and out so callers can never alias the
+    stored state, matching the serialization boundary the file/SQL backends
+    impose.
+    """
+
+    def __init__(self) -> None:
+        self._data: dict[str, dict[str, Any]] = {}
+
+    async def set(self, key: str, data: dict[str, Any]) -> None:
+        self._data[key] = copy.deepcopy(data)
+
+    async def get(self, key: str) -> dict[str, Any] | None:
+        data = self._data.get(key)
+        return copy.deepcopy(data) if data is not None else None
+
+    async def delete(self, key: str) -> None:
+        self._data.pop(key, None)
+
+    async def keys(self) -> list[str]:
+        return list(self._data)
+
+
 class FileKVBackend(KVBackend):
     """File KV backend: one JSON file per key in a directory.
 

{reactifact-0.9.1 → reactifact-0.10.0}/reactifact/cli/replay.py

@@ -37,6 +37,17 @@ async def _cmd_replay(args: argparse.Namespace) -> int:
     )
     for tname, count in sorted(summary["by_type"].items()):
         print(f"  {tname}: {count}")
+    if args.verify is not None or args.hash:
+        from ..audit import context_hash
+
+        digest = context_hash(context)
+        print(f"context sha256: {digest}")
+        if args.verify is not None:
+            if digest == args.verify:
+                print("verified: state matches the expected hash")
+            else:
+                print(f"MISMATCH: expected {args.verify}")
+                return 1
     if args.diagram:
         from ..viz import context_to_mermaid
 
@@ -63,6 +74,15 @@ def add_parser(sub: argparse._SubParsersAction[argparse.ArgumentParser]) -> None
         "--version", type=int, default=None, help="replay to this commit"
     )
     p_replay.add_argument("--backend", choices=["file", "sqlite"], default="auto")
+    p_replay.add_argument(
+        "--hash", action="store_true", help="print the context's content hash"
+    )
+    p_replay.add_argument(
+        "--verify",
+        default=None,
+        metavar="HASH",
+        help="exit non-zero unless the context hash equals HASH (reproducibility check)",
+    )
     p_replay.add_argument(
         "--diagram", action="store_true", help="also print the provenance graph"
     )

{reactifact-0.9.1 → reactifact-0.10.0}/reactifact/effects.py

@@ -125,6 +125,33 @@ class Effects:
             return None
         return self.create(data, id=id)
 
+    def create_once_from(
+        self,
+        source: Artifact[Any] | Handle | str,
+        data: Any,
+        *,
+        prefix: str | None = None,
+    ) -> Handle | None:
+        """Idempotent create whose id is derived from another artifact (§42).
+
+        Folds the single most common way a re-derivable id is built by hand —
+        `f"answer:{question.id}"`, `f"review:{pr.id}"` — into the call, so a
+        produce doesn't have to invent the id string (nor get it subtly wrong
+        between its guard and its `create`):
+
+            answer = self.effects.create_once_from(question, Answer(...))
+            if answer is None:
+                return None  # already answered this question
+
+        `prefix` defaults to the created model's class name, lowercased
+        (`Answer` → `answer:{source_id}`). `source` may be an `Artifact`, an
+        effects `Handle`, or a plain id string. `None` back means an artifact
+        with the derived id already exists — skip, exactly like `create_once`.
+        """
+        source_id = _id_of(source)
+        artifact_id = f"{prefix or type(data).__name__.lower()}:{source_id}"
+        return self.create_once(data, id=artifact_id)
+
     def upsert(self, data: Any, *, id: str) -> Handle:
         """Explicit create-or-refresh: same effect as `create(data, id=id)`.