reactifact 0.12.0__tar.gz → 0.13.0__tar.gz

{reactifact-0.12.0/reactifact.egg-info → reactifact-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.12.0
+Version: 0.13.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
@@ -46,7 +46,7 @@ Dynamic: license-file
   <img src="docs/img/reactifact-hero.png" alt="reactifact — Agents that react to artifacts, not graphs" width="800">
 </p>
 
-**Event-driven agents for Python developers — tasks wake on typed artifacts, like Celery tasks wake on messages. No graph to draw.**
+**Auditable agents for Python.** Build **knowledge assistants** over docs, spreadsheets and the web — where the path per question isn't a graph you can draw. Every answer is computed, versioned and reproducible — not a string you have to trust.
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/bzdvdn/reactifact/graph/badge.svg)](https://codecov.io/gh/bzdvdn/reactifact)
@@ -56,29 +56,15 @@ Dynamic: license-file
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
 [![Docs](https://img.shields.io/badge/docs-bzdvdn.github.io%2Freactifact-blue)](https://bzdvdn.github.io/reactifact/)
 
-Python developers already know this model from Celery: define a **task**,
-declare what triggers it, let the runtime run it. reactifact applies it to agents — a task
-reacts to a **typed, versioned artifact** appearing in the context, not to a
-queue message you push or a graph edge you draw. The runtime derives what runs
-next from state.
+> **Is:** a Python library (3 core deps) · single-process · typed, versioned artifacts with provenance · deterministic replay · runs offline, no API key
+> **Isn't:** a managed platform · a distributed task queue · a pre-built agent/tool marketplace
 
-| Celery | reactifact |
-| --- | --- |
-| a task | `@produce(Model)` — a unit of work that writes an artifact |
-| `delay()` / `apply_async()` | you don't call it: creating the input artifact **is** the trigger |
-| routing key / queue | `Consume(Type)` — which artifact type wakes the task |
-| chain / group / chord | several `consumes` / `produces`; the runtime derives the order |
-| retries, `acks_late` | guards + `Budget`, an honest `None` instead of a wrong result |
-| result backend | the `Context` — typed, versioned artifacts |
-| worker | `Runtime` |
+A question like *"why did infra costs jump in Q2?"* needs a spreadsheet, a policy doc and a page off the web — and the *next* question needs a different subset. That is not one graph you can draw up front. You declare what artifacts exist and what agents can do with them; the runtime derives the order from state.
 
-Single process today (no broker, no worker pool) — the *model* is Celery-shaped,
-not its distributed runtime.
-
-On top of that model you get something a task queue doesn't: every artifact is
-**versioned with provenance**, so a run is reproducible (`context_hash`) and
-auditable (`audit.report`) for free. The model reasons; the arithmetic stays
-deterministic; every claim carries provenance.
+Every derived artifact then links to what produced it
+(`Answer —supported_by→ Evidence —extracted_from→ Doc`), so *"why did it say
+that?"* is a query, not a guess — and the run is reproducible (`context_hash`)
+and verifiable (`reactifact replay --verify`).
 
 ## On top: a provable answer
 
@@ -130,6 +116,14 @@ print(report_to_markdown(build_report(ctx, answer)))  # hash per artifact + edge
 print(context_hash(ctx))                              # reproducible fingerprint
 ```
 
+## Knowledge assistants, live
+
+The same shape over many sources, not a fixed path — the
+[`knowledge`](examples/knowledge) CLI answers a harder, multi-source question
+(docs + a CSV) with a real computed number and its sources, no LLM key required:
+
+![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
+
 ![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
 
 Two agents explore independently on their own forks and merge back automatically
@@ -137,6 +131,31 @@ Two agents explore independently on their own forks and merge back automatically
 
 ![forklab demo: two strategies (depth/breadth) investigate on separate forks and merge cleanly; a second run edits the same artifact on both forks and reactifact raises MergeConflict instead of guessing, then re-merges under an explicit policy.](docs/img/forklab-demo.gif)
 
+<details>
+<summary><strong>If you know Celery…</strong> — the programming model, not its distributed runtime</summary>
+
+Python developers already know this model from Celery: define a **task**,
+declare what triggers it, let the runtime run it. reactifact applies it to
+agents — a task reacts to a **typed, versioned artifact** appearing in the
+context, not to a queue message you push or a graph edge you draw. The runtime
+derives what runs next from state.
+
+| Celery | reactifact |
+| --- | --- |
+| a task | `@produce(Model)` — a unit of work that writes an artifact |
+| `delay()` / `apply_async()` | you don't call it: creating the input artifact **is** the trigger |
+| routing key / queue | `Consume(Type)` — which artifact type wakes the task |
+| chain / group / chord | several `consumes` / `produces`; the runtime derives the order |
+| result backend | the `Context` — typed, versioned artifacts |
+| worker | `Runtime` |
+
+**Not inherited:** a broker, a worker pool, `acks_late`/redelivery, cross-process
+exactly-once. reactifact is a library with an in-process runtime — the *model* is
+Celery-shaped, the deployment is not. (Session-backed runs do survive a restart;
+see [Durability & resume](docs/en/durability.md).)
+
+</details>
+
 ```bash
 pip install reactifact
 ```
@@ -203,12 +222,6 @@ print(answer.data.text)                     # "Refunds are available within 14 d
 print("supported_by:", evidence.data.text)  # provenance you can trace, not just a string in a log
 ```
 
-The same idea, live — the [`knowledge`](examples/knowledge) example's CLI answering a
-harder, multi-source question (docs + a CSV) with a real computed number and
-its sources, no LLM key required:
-
-![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
-
 ## How it works
 
 ```text
@@ -325,6 +338,7 @@ Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/co
 - `medic-lab` — hypothesis laboratory: competing hypotheses scored, HITL steering, honest report.
 - `devops` — HITL tool agents + LLM tool router + trace dashboard.
 - `repair` — budget-aware replanning (chat/data in Russian by design).
+- `chat` — minimal offline single-model multi-turn conversation (`Conversation` + bounded `ChatMemory`).
 - `forklab` — deterministic branch & merge: two strategies on their own forks, three-way merge.
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
 - `llm_ladder` — the workflow from one LLM call to state-changing patches (3 levels).
@@ -355,6 +369,14 @@ uv sync --extra dev --extra web
 .venv/bin/ruff check
 ```
 
+## Status & contributing
+
+Active, `0.13.x`, pre-1.0 — the API is stabilizing and `1.0` will freeze it
+(see the [roadmap](docs/roadmap.md)); releases follow
+[Keep a Changelog](CHANGELOG.md). Questions and design discussion live in
+[GitHub Discussions](https://github.com/bzdvdn/reactifact/discussions); a star,
+or a `good first issue`, helps more than you'd think.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

{reactifact-0.12.0 → reactifact-0.13.0}/README.md

@@ -2,7 +2,7 @@
   <img src="docs/img/reactifact-hero.png" alt="reactifact — Agents that react to artifacts, not graphs" width="800">
 </p>
 
-**Event-driven agents for Python developers — tasks wake on typed artifacts, like Celery tasks wake on messages. No graph to draw.**
+**Auditable agents for Python.** Build **knowledge assistants** over docs, spreadsheets and the web — where the path per question isn't a graph you can draw. Every answer is computed, versioned and reproducible — not a string you have to trust.
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/bzdvdn/reactifact/graph/badge.svg)](https://codecov.io/gh/bzdvdn/reactifact)
@@ -12,29 +12,15 @@
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
 [![Docs](https://img.shields.io/badge/docs-bzdvdn.github.io%2Freactifact-blue)](https://bzdvdn.github.io/reactifact/)
 
-Python developers already know this model from Celery: define a **task**,
-declare what triggers it, let the runtime run it. reactifact applies it to agents — a task
-reacts to a **typed, versioned artifact** appearing in the context, not to a
-queue message you push or a graph edge you draw. The runtime derives what runs
-next from state.
+> **Is:** a Python library (3 core deps) · single-process · typed, versioned artifacts with provenance · deterministic replay · runs offline, no API key
+> **Isn't:** a managed platform · a distributed task queue · a pre-built agent/tool marketplace
 
-| Celery | reactifact |
-| --- | --- |
-| a task | `@produce(Model)` — a unit of work that writes an artifact |
-| `delay()` / `apply_async()` | you don't call it: creating the input artifact **is** the trigger |
-| routing key / queue | `Consume(Type)` — which artifact type wakes the task |
-| chain / group / chord | several `consumes` / `produces`; the runtime derives the order |
-| retries, `acks_late` | guards + `Budget`, an honest `None` instead of a wrong result |
-| result backend | the `Context` — typed, versioned artifacts |
-| worker | `Runtime` |
+A question like *"why did infra costs jump in Q2?"* needs a spreadsheet, a policy doc and a page off the web — and the *next* question needs a different subset. That is not one graph you can draw up front. You declare what artifacts exist and what agents can do with them; the runtime derives the order from state.
 
-Single process today (no broker, no worker pool) — the *model* is Celery-shaped,
-not its distributed runtime.
-
-On top of that model you get something a task queue doesn't: every artifact is
-**versioned with provenance**, so a run is reproducible (`context_hash`) and
-auditable (`audit.report`) for free. The model reasons; the arithmetic stays
-deterministic; every claim carries provenance.
+Every derived artifact then links to what produced it
+(`Answer —supported_by→ Evidence —extracted_from→ Doc`), so *"why did it say
+that?"* is a query, not a guess — and the run is reproducible (`context_hash`)
+and verifiable (`reactifact replay --verify`).
 
 ## On top: a provable answer
 
@@ -86,6 +72,14 @@ print(report_to_markdown(build_report(ctx, answer)))  # hash per artifact + edge
 print(context_hash(ctx))                              # reproducible fingerprint
 ```
 
+## Knowledge assistants, live
+
+The same shape over many sources, not a fixed path — the
+[`knowledge`](examples/knowledge) CLI answers a harder, multi-source question
+(docs + a CSV) with a real computed number and its sources, no LLM key required:
+
+![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
+
 ![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
 
 Two agents explore independently on their own forks and merge back automatically
@@ -93,6 +87,31 @@ Two agents explore independently on their own forks and merge back automatically
 
 ![forklab demo: two strategies (depth/breadth) investigate on separate forks and merge cleanly; a second run edits the same artifact on both forks and reactifact raises MergeConflict instead of guessing, then re-merges under an explicit policy.](docs/img/forklab-demo.gif)
 
+<details>
+<summary><strong>If you know Celery…</strong> — the programming model, not its distributed runtime</summary>
+
+Python developers already know this model from Celery: define a **task**,
+declare what triggers it, let the runtime run it. reactifact applies it to
+agents — a task reacts to a **typed, versioned artifact** appearing in the
+context, not to a queue message you push or a graph edge you draw. The runtime
+derives what runs next from state.
+
+| Celery | reactifact |
+| --- | --- |
+| a task | `@produce(Model)` — a unit of work that writes an artifact |
+| `delay()` / `apply_async()` | you don't call it: creating the input artifact **is** the trigger |
+| routing key / queue | `Consume(Type)` — which artifact type wakes the task |
+| chain / group / chord | several `consumes` / `produces`; the runtime derives the order |
+| result backend | the `Context` — typed, versioned artifacts |
+| worker | `Runtime` |
+
+**Not inherited:** a broker, a worker pool, `acks_late`/redelivery, cross-process
+exactly-once. reactifact is a library with an in-process runtime — the *model* is
+Celery-shaped, the deployment is not. (Session-backed runs do survive a restart;
+see [Durability & resume](docs/en/durability.md).)
+
+</details>
+
 ```bash
 pip install reactifact
 ```
@@ -159,12 +178,6 @@ print(answer.data.text)                     # "Refunds are available within 14 d
 print("supported_by:", evidence.data.text)  # provenance you can trace, not just a string in a log
 ```
 
-The same idea, live — the [`knowledge`](examples/knowledge) example's CLI answering a
-harder, multi-source question (docs + a CSV) with a real computed number and
-its sources, no LLM key required:
-
-![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
-
 ## How it works
 
 ```text
@@ -281,6 +294,7 @@ Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/co
 - `medic-lab` — hypothesis laboratory: competing hypotheses scored, HITL steering, honest report.
 - `devops` — HITL tool agents + LLM tool router + trace dashboard.
 - `repair` — budget-aware replanning (chat/data in Russian by design).
+- `chat` — minimal offline single-model multi-turn conversation (`Conversation` + bounded `ChatMemory`).
 - `forklab` — deterministic branch & merge: two strategies on their own forks, three-way merge.
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
 - `llm_ladder` — the workflow from one LLM call to state-changing patches (3 levels).
@@ -311,6 +325,14 @@ uv sync --extra dev --extra web
 .venv/bin/ruff check
 ```
 
+## Status & contributing
+
+Active, `0.13.x`, pre-1.0 — the API is stabilizing and `1.0` will freeze it
+(see the [roadmap](docs/roadmap.md)); releases follow
+[Keep a Changelog](CHANGELOG.md). Questions and design discussion live in
+[GitHub Discussions](https://github.com/bzdvdn/reactifact/discussions); a star,
+or a `good first issue`, helps more than you'd think.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

{reactifact-0.12.0 → reactifact-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.12.0"
+version = "0.13.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"
@@ -99,7 +99,7 @@ reactifact = "reactifact.__main__:main"
 packages = { find = { where = ["."], include = ["reactifact*"], exclude = ["examples*", "tests*"] } }
 
 [tool.setuptools.package-data]
-reactifact = ["py.typed"]
+reactifact = ["py.typed", "skills/*/SKILL.md", "skills/*/references/*.md"]
 "reactifact.tracing" = ["templates/*.html", "templates/*.css"]
 
 [tool.pytest.ini_options]
@@ -152,3 +152,9 @@ python_version = "3.11"
 packages = ["reactifact", "examples"]
 strict = true
 warn_unused_ignores = true
+
+# pyright defaults its target to the interpreter it finds, which can resolve
+# below the 3.11 floor this package requires — making `StrEnum`/`datetime.UTC`
+# "unknown import symbol" and cascading into false positives on `RunOutcome`.
+[tool.pyright]
+pythonVersion = "3.11"

{reactifact-0.12.0 → reactifact-0.13.0}/reactifact/__init__.py

@@ -24,7 +24,7 @@ of the names you see by default even though they were always cheap to import
 from .agents import Agent, create_agent
 from .artifacts import Artifact
 from .branching import MergeConflict
-from .budget import Budget, RunOutcome, RunStats
+from .budget import Budget, BudgetTracker, RunOutcome, RunStats
 from .consume import Consume, consume
 from .context import Context, View
 from .effects import Effects, Handle
@@ -48,13 +48,15 @@ from .runtime import Runtime
 from .session import Session, SessionStore
 from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
+from .types import register as register_type
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
 
 __all__ = [
     "Agent",
     "Artifact",
     "Budget",
+    "BudgetTracker",
     "Consume",
     "Context",
     "Create",
@@ -97,5 +99,6 @@ __all__ = [
     "create_agent",
     "current_request",
     "produce",
+    "register_type",
     "tool",
 ]

{reactifact-0.12.0 → reactifact-0.13.0}/reactifact/artifacts.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
-import importlib
 import uuid
 from datetime import UTC, datetime
 from typing import Any, Generic, TypeVar
 
 from pydantic import BaseModel
 
+from .types import migrate_payload, resolve, type_id_of
+
 TData = TypeVar("TData", bound=BaseModel)
 ArtifactType = type[BaseModel]
 
@@ -31,12 +32,6 @@ def compute_dict_diff(old: dict[str, Any], new: dict[str, Any]) -> dict[str, Any
     return diff
 
 
-def _import_class(full_name: str) -> Any:
-    module_name, class_name = full_name.rsplit(".", 1)
-    module = importlib.import_module(module_name)
-    return getattr(module, class_name)
-
-
 class Artifact(Generic[TData]):
     """Wrapper around a Pydantic model with versioning."""
 
@@ -48,13 +43,21 @@ class Artifact(Generic[TData]):
     ):
         self.id = id or str(uuid.uuid4())
         self.data = data
-        self.data_type = f"{type(data).__module__}.{type(data).__qualname__}"
+        # Stable type id (reactifact.types): a registered `type_id`/`TYPE_ID`
+        # classvar, else the qualified name — so a rename/move can be tolerated
+        # via aliases instead of breaking a persisted session/replay.
+        self.data_type = type_id_of(type(data))
         self.created_at = datetime.now(UTC)
         self.updated_at = self.created_at
         self.created_by_commit = created_by_commit
         self._history: list[
             TData
         ] = []  # previous data versions (excluding the current one)
+        #: Absolute version counter — bumped by `update()`, independent of
+        #: `len(_history)`. `compact(keep_versions=…)` trims `_history` but must
+        #: not change `version` (it is part of `context_hash` and of commit
+        #: `Write`s), so it is tracked separately.
+        self._version = 0
         # Memoized to_dict(), keyed by version: re-derived on every save()
         # otherwise (session persistence saves after every commit, §reactifact.session)
         # even though most artifacts in a large context are unchanged since the
@@ -65,8 +68,22 @@ class Artifact(Generic[TData]):
         """Saves the current version to history and replaces the data."""
         self._history.append(self.data)
         self.data = new_data
+        self._version += 1
         self.updated_at = datetime.now(UTC)
 
+    def trim_history(self, keep: int) -> None:
+        """Keeps only the last `keep` previous versions (0 drops them all).
+
+        `version` (and so `context_hash`) is unaffected — only the ability to
+        inspect older versions via `history`/`get_all_versions`/`diff` is
+        bounded. Used by `Context.compact`.
+        """
+        if keep < 0:
+            raise ValueError("keep must be >= 0")
+        if len(self._history) > keep:
+            self._history = self._history[-keep:] if keep else []
+            self._dict_cache = None
+
     @property
     def history(self) -> list[TData]:
         """Returns a copy of the list of previous versions (excluding the current one)."""
@@ -75,7 +92,7 @@ class Artifact(Generic[TData]):
     @property
     def version(self) -> int:
         """Current version (0 – original, 1 – after the first update, etc.)"""
-        return len(self._history)
+        return self._version
 
     def get_all_versions(self) -> list[TData]:
         """Returns all data versions, including the current one, from oldest to newest."""
@@ -106,6 +123,7 @@ class Artifact(Generic[TData]):
             "id": self.id,
             "data_type": self.data_type,
             "data": self.data.model_dump(mode="json"),
+            "version": self._version,
             "created_at": self.created_at.isoformat(),
             "updated_at": self.updated_at.isoformat(),
             "history": [v.model_dump(mode="json") for v in self._history],
@@ -116,14 +134,21 @@ class Artifact(Generic[TData]):
 
     @classmethod
     def from_dict(cls, d: dict[str, Any]) -> Artifact[Any]:
-        model_class = _import_class(d["data_type"])
-        data = model_class.model_validate(d["data"])
+        data_type = d["data_type"]
+        model_class = resolve(data_type)
+        data: Any = model_class.model_validate(migrate_payload(data_type, d["data"]))
         artifact = cls(
             data=data, id=d["id"], created_by_commit=d.get("created_by_commit")
         )
         artifact.created_at = datetime.fromisoformat(d["created_at"])
         artifact.updated_at = datetime.fromisoformat(d["updated_at"])
-        artifact._history = [model_class.model_validate(h) for h in d["history"]]
+        history: list[Any] = [
+            model_class.model_validate(migrate_payload(data_type, h))
+            for h in d["history"]
+        ]
+        artifact._history = history
+        # Older payloads predate the explicit counter — fall back to history len.
+        artifact._version = int(d.get("version", len(artifact._history)))
         return artifact
 
     def __repr__(self) -> str:

reactifact-0.13.0/reactifact/authz.py

@@ -0,0 +1,112 @@
+"""Authorization — a principal and a permission policy for a run (§57).
+
+reactifact has no server, so unlike a hosted platform it can enforce access in
+the library itself, at the points that actually matter: which artifact types an
+agent may create/update/delete, which agent may run, and which tool may
+execute. `RuntimeResources(principal=..., authorizer=...)` turns it on.
+
+    from reactifact.authz import PermissionPolicy, Principal
+
+    resources = RuntimeResources(
+        principal=Principal("alice", capabilities=("analyst",)),
+        authorizer=PermissionPolicy(grants={"analyst": {"run:*", "create:Answer"}}),
+    )
+
+A principal is whoever the run acts for (an end user, a tenant, a service).
+The default is `None`, and with no authorizer every action is allowed — authz
+is opt-in and does not change existing behavior. Denials raise
+`AuthorizationError` from `Runtime.arun()` (or that agent's generation is
+dropped when `isolate_errors=True`).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+
+class Principal(BaseModel):
+    """Who a run acts for: an id plus the capabilities it holds.
+
+    Kept a plain model so it composes with artifacts and sessions (it can be
+    seeded as an artifact, loaded from a session, or restored by a `SeedIdentity`
+    recipe) rather than living only in `RuntimeResources`.
+    """
+
+    id: str
+    capabilities: tuple[str, ...] = ()
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AuthorizationError(PermissionError):
+    """Raised when a principal may not perform an action on a resource."""
+
+    def __init__(
+        self, action: str, resource: str, principal: Principal | None = None
+    ) -> None:
+        self.action = action
+        self.resource = resource
+        self.principal = principal
+        who = principal.id if principal is not None else "anonymous"
+        super().__init__(f"principal {who!r} may not {action} {resource!r}")
+
+
+@runtime_checkable
+class Authorizer(Protocol):
+    """Structural interface: `authorize(principal, action, resource) -> bool`."""
+
+    def authorize(
+        self, principal: Principal | None, action: str, resource: str
+    ) -> bool: ...
+
+
+def _permission_matches(pattern: str, action: str, resource: str) -> bool:
+    """Matches `"action:resource"`, `"action:*"`, `"*:resource"` or `"*"`."""
+    if pattern == "*":
+        return True
+    if ":" not in pattern:
+        return pattern == action
+    allowed_action, _, allowed_resource = pattern.partition(":")
+    return (allowed_action in ("*", action)) and (allowed_resource in ("*", resource))
+
+
+@dataclass
+class PermissionPolicy:
+    """Capability-based permissions: a capability grants `action:resource` patterns.
+
+    `grants` maps a capability name to the patterns it allows, e.g.
+    `{"analyst": {"run:*", "create:Answer"}, "admin": {"*"}}`. A principal is
+    allowed an action when any of its capabilities grants a matching pattern.
+    With `default_allow=False` (the default) an anonymous/unknown principal is
+    denied; set it `True` to allow by default and use the grants as the
+    allowlist an audit needs.
+    """
+
+    grants: Mapping[str, Iterable[str]] = field(default_factory=dict)
+    default_allow: bool = False
+
+    def authorize(
+        self, principal: Principal | None, action: str, resource: str
+    ) -> bool:
+        if principal is None:
+            return self.default_allow
+        for capability in principal.capabilities:
+            for pattern in self.grants.get(capability, ()):
+                if _permission_matches(pattern, action, resource):
+                    return True
+        return self.default_allow
+
+    def require(self, principal: Principal | None, action: str, resource: str) -> None:
+        if not self.authorize(principal, action, resource):
+            raise AuthorizationError(action, resource, principal)
+
+
+__all__ = [
+    "AuthorizationError",
+    "Authorizer",
+    "PermissionPolicy",
+    "Principal",
+]

{reactifact-0.12.0 → reactifact-0.13.0}/reactifact/branching.py

@@ -57,6 +57,7 @@ def clone_context(source: Context) -> Context:
             created_by_commit=artifact.created_by_commit,
         )
         new_artifact._history = [v.model_copy(deep=True) for v in artifact._history]
+        new_artifact._version = artifact._version
         new_artifact.created_at = artifact.created_at
         new_artifact.updated_at = artifact.updated_at
         new_ws._artifacts[artifact.id] = new_artifact