activegraph 1.1.0__tar.gz → 1.3.0__tar.gz

{activegraph-1.1.0/activegraph.egg-info → activegraph-1.3.0}/PKG-INFO

@@ -1,10 +1,14 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.1.0
+Version: 1.3.0
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/yoheinakajima/activegraph
+Project-URL: Documentation, https://docs.activegraph.ai/
+Project-URL: Repository, https://github.com/yoheinakajima/activegraph
+Project-URL: Changelog, https://docs.activegraph.ai/about/changelog/
+Project-URL: Issues, https://github.com/yoheinakajima/activegraph/issues
 Keywords: graph,agents,event-sourcing,runtime
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -32,6 +36,10 @@ Requires-Dist: pydantic>=2; extra == "openai"
 Provides-Extra: sqlite
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
+Provides-Extra: falkordb
+Requires-Dist: falkordb>=1.0; extra == "falkordb"
+Provides-Extra: falkordb-embedded
+Requires-Dist: falkordblite>=0.10; extra == "falkordb-embedded"
 Provides-Extra: prometheus
 Requires-Dist: prometheus_client>=0.20; extra == "prometheus"
 Provides-Extra: opentelemetry
@@ -303,23 +311,34 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations
 - Not a rules engine, exactly. Rules engines forward-chain over
   facts. This event-sources over a graph and supports LLM behaviors
   as first-class.
-- Not a production graph database. The default store is SQLite,
-  optionally Postgres. For a high-throughput graph backend, plug one
-  in behind the `EventStore` protocol.
+- Not a production graph database. The event log lives in SQLite
+  (default) or Postgres behind the `EventStore` protocol; the
+  materialized graph lives behind the `GraphStore` protocol —
+  in-memory by default, or [FalkorDB](https://docs.activegraph.ai/guides/using-falkordb/)
+  for a real, traversable graph backend. For a different
+  high-throughput store, plug one in behind either protocol.
 - Not magic. Bad behaviors produce bad graphs. The runtime makes the
   badness inspectable, not absent.
 
 ## Status
 
-**v1.0 (stable)** (2026-05). The first-time-user gate per
-[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally)
-ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
-output fix and a README "Concepts at a glance" index. See
-[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
-per-version migration notes.
+**v1.2.0 (stable)** (2026-07). v1.0 shipped in May 2026 after a
+three-rc external user-test gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally);
+v1.1.0 and v1.2.0 followed. See [CHANGELOG.md](CHANGELOG.md) for the
+full v0 → v1.2 history and per-version migration notes.
 
 Major shipped milestones:
 
+- **v1.2** — the `GraphStore` seam: the materialized projection
+  becomes pluggable, with `FalkorDBGraphStore` (native edges, Cypher
+  query push-down) as the first external backend, contributed by
+  [@dudizimber](https://github.com/dudizimber); the test suite
+  becomes a CI gate.
+- **v1.1** — bounded LLM retries for transient provider failures,
+  `inspect --memo` / `inspect --search`, `fork --set`, OpenAI
+  tool-shape parity, `OpenTelemetryMetrics`, and the
+  spec-vs-impl drift gates.
 - **v1.0** — error hierarchy rewrite with per-error reference
   pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
@@ -340,8 +359,9 @@ Major shipped milestones:
   patches with optimistic concurrency, views, frames, policies,
   budgets, the trace.
 
-Roadmap items planned for v1.1 are tracked in
-[CONTRACT.md § v1.1](CONTRACT.md).
+Roadmap items for the current cycle are tracked in
+[ROADMAP.md](ROADMAP.md); unscheduled candidates live in
+[FUTURE_IDEAS.md](FUTURE_IDEAS.md).
 
 ## License
 

{activegraph-1.1.0 → activegraph-1.3.0}/README.md

@@ -240,23 +240,34 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations
 - Not a rules engine, exactly. Rules engines forward-chain over
   facts. This event-sources over a graph and supports LLM behaviors
   as first-class.
-- Not a production graph database. The default store is SQLite,
-  optionally Postgres. For a high-throughput graph backend, plug one
-  in behind the `EventStore` protocol.
+- Not a production graph database. The event log lives in SQLite
+  (default) or Postgres behind the `EventStore` protocol; the
+  materialized graph lives behind the `GraphStore` protocol —
+  in-memory by default, or [FalkorDB](https://docs.activegraph.ai/guides/using-falkordb/)
+  for a real, traversable graph backend. For a different
+  high-throughput store, plug one in behind either protocol.
 - Not magic. Bad behaviors produce bad graphs. The runtime makes the
   badness inspectable, not absent.
 
 ## Status
 
-**v1.0 (stable)** (2026-05). The first-time-user gate per
-[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally)
-ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
-output fix and a README "Concepts at a glance" index. See
-[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
-per-version migration notes.
+**v1.2.0 (stable)** (2026-07). v1.0 shipped in May 2026 after a
+three-rc external user-test gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally);
+v1.1.0 and v1.2.0 followed. See [CHANGELOG.md](CHANGELOG.md) for the
+full v0 → v1.2 history and per-version migration notes.
 
 Major shipped milestones:
 
+- **v1.2** — the `GraphStore` seam: the materialized projection
+  becomes pluggable, with `FalkorDBGraphStore` (native edges, Cypher
+  query push-down) as the first external backend, contributed by
+  [@dudizimber](https://github.com/dudizimber); the test suite
+  becomes a CI gate.
+- **v1.1** — bounded LLM retries for transient provider failures,
+  `inspect --memo` / `inspect --search`, `fork --set`, OpenAI
+  tool-shape parity, `OpenTelemetryMetrics`, and the
+  spec-vs-impl drift gates.
 - **v1.0** — error hierarchy rewrite with per-error reference
   pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
@@ -277,8 +288,9 @@ Major shipped milestones:
   patches with optimistic concurrency, views, frames, policies,
   budgets, the trace.
 
-Roadmap items planned for v1.1 are tracked in
-[CONTRACT.md § v1.1](CONTRACT.md).
+Roadmap items for the current cycle are tracked in
+[ROADMAP.md](ROADMAP.md); unscheduled candidates live in
+[FUTURE_IDEAS.md](FUTURE_IDEAS.md).
 
 ## License
 

{activegraph-1.1.0 → activegraph-1.3.0}/activegraph/__init__.py

@@ -42,6 +42,11 @@ from activegraph.llm.errors import LLMBehaviorError, MissingProviderError
 from activegraph.policy import Policy
 from activegraph.runtime.budget import Budget
 from activegraph.runtime.diff import Diff, DivergentObject, DivergentRelation
+from activegraph.runtime.promote import (
+    PromoteConflict,
+    PromotePlan,
+    PromoteResult,
+)
 from activegraph.runtime.config_errors import (
     IncompatibleRuntimeState,
     InvalidArgumentType,
@@ -52,6 +57,8 @@ from activegraph.runtime.exec_errors import (
     ApprovalNotFoundError,
     InternalEvaluatorError,
     InvalidPatchLifecycleState,
+    PromoteConflictError,
+    PromoteLineageError,
     RuntimeContextRequiredError,
 )
 from activegraph.runtime.patterns import UnsupportedPatternError
@@ -61,7 +68,10 @@ from activegraph.store import (
     DuplicateEventError,
     EventNotFoundError,
     EventStore,
+    FalkorDBGraphStore,
+    GraphStore,
     InMemoryEventStore,
+    InMemoryGraphStore,
     InvalidStoreURL,
     NonSerializableEventError,
     RunRecord,
@@ -142,11 +152,14 @@ __all__ = [
     "EventNotFoundError",
     "EventStore",
     "ExecutionError",
+    "FalkorDBGraphStore",
     "Frame",
     "FrozenClock",
     "Graph",
+    "GraphStore",
     "IDGen",
     "InMemoryEventStore",
+    "InMemoryGraphStore",
     "IncompatibleRuntimeState",
     "InternalEvaluatorError",
     "InvalidActivateAfter",
@@ -184,6 +197,11 @@ __all__ = [
     "PendingApproval",
     "Policy",
     "PrometheusMetrics",
+    "PromoteConflict",
+    "PromoteConflictError",
+    "PromoteLineageError",
+    "PromotePlan",
+    "PromoteResult",
     "Relation",
     "RelationBehavior",
     "RegistrationError",
@@ -224,4 +242,4 @@ __all__ = [
     "tool",
 ]
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"

activegraph-1.3.0/activegraph/_signature.py

@@ -0,0 +1,222 @@
+"""Registration-time handler-signature validation.
+
+Shared by the ``@behavior`` / ``@relation_behavior`` / ``@llm_behavior``
+decorators (both the global registry in
+:mod:`activegraph.behaviors.decorators` and the pack-scoped variants in
+:mod:`activegraph.packs`) and the ``@tool`` decorators.
+
+Rationale (July 2026 agent-readiness review): a handler with the wrong
+arity — ``def h(ctx)``, ``def h(event, ctx)`` — previously registered
+fine and failed at first invocation with a ``TypeError`` swallowed into
+a ``behavior.failed`` event, painful to notice during pack development.
+Validating at decoration time names the mistake at the line that made
+it, matching the precedent set by ``@llm_behavior``'s
+``output_schema=`` strict validation (CONTRACT v1.0.3 #2).
+
+The check is deliberately permissive:
+
+  * Objects without an inspectable signature (builtins, some callables,
+    mocks with ``(*args, **kwargs)``) pass through unvalidated — the
+    goal is catching the common authoring mistake, not gatekeeping
+    every callable Python can construct.
+  * ``*args`` satisfies any positional arity.
+  * Extra parameters beyond the contract are allowed when the call can
+    still succeed: they need a default, or — for behaviors, where the
+    pack loader injects typed settings by keyword
+    (``packs/loader.py:_wrap_with_injection``) — a type annotation
+    that marks them as injection candidates.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+
+def validate_handler_signature(
+    fn: Any,
+    *,
+    expected_params: tuple[str, ...],
+    decorator: str,
+    allow_annotated_extras: bool,
+) -> None:
+    """Raise ``TypeError`` when ``fn`` cannot be invoked with the
+    decorator's positional calling convention.
+
+    ``expected_params`` names the contract's positional parameters
+    (documentation for the error message; only arity is checked, not
+    names). ``decorator`` is the user-facing decorator name for the
+    message (e.g. ``"@tool"``). ``allow_annotated_extras=True`` treats
+    a type annotation on an extra parameter as evidence it will be
+    keyword-injected at call time (the pack settings pattern
+    ``*, settings: MyPackSettings``); ``False`` (tools) requires extras
+    to carry defaults, because tools are always invoked as exactly
+    ``fn(args, ctx)``.
+
+    Callables whose signature cannot be inspected are skipped, and
+    ``*args`` / ``**kwargs`` satisfy the positional / extra checks
+    respectively — the validation is a loud guard for the common
+    mistake, not an exhaustive gate.
+    """
+    if not callable(fn):
+        raise TypeError(
+            f"{decorator} must decorate a callable, got "
+            f"{type(fn).__name__}."
+        )
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):
+        return
+
+    params = list(sig.parameters.values())
+    has_var_positional = any(
+        p.kind is inspect.Parameter.VAR_POSITIONAL for p in params
+    )
+    positional = [
+        p
+        for p in params
+        if p.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        )
+    ]
+    n_expected = len(expected_params)
+    expected_sig = f"({', '.join(expected_params)})"
+
+    if len(positional) < n_expected and not has_var_positional:
+        found = (
+            f"({', '.join(p.name for p in positional)})"
+            if positional
+            else "()"
+        )
+        raise TypeError(
+            f"{decorator} function {_name_of(fn)!r} must accept "
+            f"{n_expected} positional parameters {expected_sig}, but its "
+            f"signature is {found}.\n"
+            f"\n"
+            f"The runtime invokes it as fn{expected_sig}. "
+            f"{_extra_hint(decorator)}\n"
+            f"\n"
+            f"Example:\n"
+            f"    {decorator}(...)\n"
+            f"    def {_example_name(fn)}{expected_sig}: ..."
+        )
+
+    problems: list[str] = []
+    for p in positional[n_expected:]:
+        if _extra_is_satisfiable(p, allow_annotated_extras):
+            continue
+        problems.append(p.name)
+    for p in params:
+        if p.kind is not inspect.Parameter.KEYWORD_ONLY:
+            continue
+        if _extra_is_satisfiable(p, allow_annotated_extras):
+            continue
+        problems.append(p.name)
+
+    if problems:
+        if allow_annotated_extras:
+            fix = (
+                "give it a default value, or annotate it with your "
+                "pack's settings class so the pack loader injects it "
+                "(e.g. `*, settings: MyPackSettings`)"
+            )
+        else:
+            fix = "give it a default value or remove it"
+        raise TypeError(
+            f"{decorator} function {_name_of(fn)!r} has required "
+            f"parameter(s) beyond the {expected_sig} contract that the "
+            f"runtime will never pass: {', '.join(problems)}.\n"
+            f"\n"
+            f"The runtime invokes it as fn{expected_sig}, so every "
+            f"extra parameter must be optional at call time — {fix}."
+        )
+
+
+def infer_tool_input_schema(fn: Any) -> Any:
+    """Infer a tool's ``input_schema`` from its first parameter's
+    type annotation, or return ``None``.
+
+    v1.3: with ``input_schema=None``, ``@tool`` previously sent the
+    model an empty parameters schema (``{"type": "object",
+    "properties": {}}``) even when the function body plainly declared
+    its shape via ``def fetch(args: FetchArgs, ctx)``. Inference
+    closes that gap: when the first positional parameter is annotated
+    with a Pydantic ``BaseModel`` subclass, that class becomes the
+    tool's ``input_schema`` — the model sees real parameters and the
+    runtime validates arguments before invocation, exactly as if
+    ``input_schema=FetchArgs`` had been passed explicitly.
+
+    Anything else — no annotation, a non-model annotation
+    (``dict``, ``Any``), an uninspectable callable — returns ``None``
+    and the tool behaves exactly as before. Explicit ``input_schema=``
+    always wins; the decorators only call this when it was omitted.
+    """
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):
+        return None
+    positional = [
+        p
+        for p in sig.parameters.values()
+        if p.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        )
+    ]
+    if not positional:
+        return None
+    annotation = positional[0].annotation
+    if annotation is inspect.Parameter.empty:
+        return None
+    # PEP 563 / `from __future__ import annotations` leaves string
+    # annotations; resolve through get_type_hints (module-global
+    # visibility), the same tolerance the pack loader's settings
+    # injection applies.
+    if isinstance(annotation, str):
+        import typing
+
+        try:
+            hints = typing.get_type_hints(fn)
+        except Exception:
+            return None
+        annotation = hints.get(positional[0].name)
+        if annotation is None:
+            return None
+    try:
+        from pydantic import BaseModel
+    except ImportError:  # pragma: no cover — Pydantic is a hard dep
+        return None
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+    return None
+
+
+def _extra_is_satisfiable(
+    p: inspect.Parameter, allow_annotated_extras: bool
+) -> bool:
+    if p.default is not inspect.Parameter.empty:
+        return True
+    if allow_annotated_extras and p.annotation is not inspect.Parameter.empty:
+        return True
+    return False
+
+
+def _name_of(fn: Any) -> str:
+    return getattr(fn, "__name__", repr(fn))
+
+
+def _example_name(fn: Any) -> str:
+    name = getattr(fn, "__name__", "my_handler")
+    return name if name.isidentifier() else "my_handler"
+
+
+def _extra_hint(decorator: str) -> str:
+    if decorator == "@tool":
+        return (
+            "`args` is the validated input model (or a plain dict when "
+            "no input_schema is set) and `ctx` is the ToolContext."
+        )
+    return "See the behavior-handler contract in docs/concepts/behaviors."

{activegraph-1.1.0 → activegraph-1.3.0}/activegraph/behaviors/base.py

@@ -20,12 +20,15 @@ from typing import TYPE_CHECKING, Any, Callable, Optional
 
 if TYPE_CHECKING:
     from activegraph.core.event import Event
-    from activegraph.core.graph import Graph
+    from activegraph.core.graph import Graph, Relation
     from activegraph.frame import Frame
     from activegraph.llm.prompt import AssembledPrompt
+    from activegraph.runtime.runtime import Context
 
 
-def _llm_behavior_fn_placeholder(event, graph, ctx) -> None:  # pragma: no cover
+def _llm_behavior_fn_placeholder(
+    event: "Event", graph: "Graph", ctx: "Context"
+) -> None:  # pragma: no cover
     raise RuntimeError(
         "LLMBehavior.fn invoked directly. The runtime owns LLM behavior "
         "invocation via _invoke_llm; calling .run() bypasses prompt "
@@ -35,6 +38,18 @@ def _llm_behavior_fn_placeholder(event, graph, ctx) -> None:  # pragma: no cover
 
 @dataclass
 class Behavior:
+    """Metadata plus the callable for an event-driven behavior.
+
+    A Behavior is data, not magic: ``on`` (event types), ``where``
+    (payload filter), ``pattern`` (Cypher-subset subscription),
+    ``activate_after`` (event-count delay), and ``view_spec`` (what
+    the runtime builds into ``ctx.view``) describe *when* it fires;
+    the 3-arg ``fn`` — invoked as ``fn(event, graph, ctx)`` — is
+    *what* runs. Instances come from ``@behavior`` or a pack; the
+    runtime introspects the metadata to match events, and nothing
+    here executes on its own.
+    """
+
     name: str
     fn: Callable[..., None]
     on: list[str] = field(default_factory=list)
@@ -51,12 +66,22 @@ class Behavior:
     # CONTRACT v0.7 #13. Event-count delay. None = fire immediately.
     activate_after: Optional[int] = None
 
-    def run(self, event, graph, ctx) -> None:
+    def run(self, event: "Event", graph: "Graph", ctx: "Context") -> None:
         self.fn(event, graph, ctx)
 
 
 @dataclass
 class RelationBehavior:
+    """A behavior that fires once per matching relation edge.
+
+    Same metadata surface as :class:`Behavior` plus
+    ``relation_type``: when a triggering event touches a relation of
+    that type, the 4-arg ``fn`` runs as
+    ``fn(relation, event, graph, ctx)`` — once per (event, relation)
+    pair. Deliberately not a subclass of ``Behavior``; the runtime
+    dispatches the two kinds separately.
+    """
+
     name: str
     fn: Callable[..., None]
     relation_type: str
@@ -72,7 +97,9 @@ class RelationBehavior:
     pattern_matcher: Any = None
     activate_after: Optional[int] = None
 
-    def run(self, relation, event, graph, ctx) -> None:
+    def run(
+        self, relation: "Relation", event: "Event", graph: "Graph", ctx: "Context"
+    ) -> None:
         self.fn(relation, event, graph, ctx)
 
 
@@ -98,7 +125,7 @@ class LLMBehavior(Behavior):
     # at registration time. Existing call sites that pass an explicit
     # string keep working unchanged.
     model: Optional[str] = None
-    output_schema: Optional[type] = None
+    output_schema: Optional[type[Any]] = None
     deterministic: bool = False
     max_tokens: int = 4096
     temperature: float = 0.7
@@ -106,7 +133,7 @@ class LLMBehavior(Behavior):
     timeout_seconds: float = 60.0
     prompt_template: Optional[str] = None
     # v0.7
-    tools: list = field(default_factory=list)
+    tools: list[Any] = field(default_factory=list)  # Tool | str names
     max_tool_turns: int = 6
 
     def build_prompt(
@@ -115,6 +142,7 @@ class LLMBehavior(Behavior):
         graph: "Graph",
         *,
         frame: Optional["Frame"] = None,
+        structured_output_mode: str = "prompt",
     ) -> "AssembledPrompt":
         """Assemble the prompt that would be sent for this event.
 
@@ -161,4 +189,5 @@ class LLMBehavior(Behavior):
             top_p=self.top_p,
             deterministic=self.deterministic,
             prompt_template=self.prompt_template,
+            structured_output_mode=structured_output_mode,
         )

{activegraph-1.1.0 → activegraph-1.3.0}/activegraph/behaviors/decorators.py

@@ -94,7 +94,15 @@ def clear_registry() -> list[Union[Behavior, RelationBehavior]]:
 
 
 def get_registry() -> list[Union[Behavior, RelationBehavior]]:
-    """Snapshot of the global behavior registry (a shallow copy)."""
+    """Snapshot of the global behavior registry (a shallow copy).
+
+    Decoration with ``@behavior`` / ``@relation_behavior`` /
+    ``@llm_behavior`` appends to a module-level list; this returns a
+    copy, so callers can filter or iterate without mutating
+    registration state. ``Runtime`` snapshots it at construction when
+    ``behaviors=`` is omitted — later registrations don't leak into
+    already-built runtimes.
+    """
     return list(_REGISTRY)
 
 
@@ -152,7 +160,7 @@ def behavior(
     *,
     pattern: Optional[str] = None,
     activate_after: Any = None,
-) -> Callable[[Callable], Behavior]:
+) -> Callable[[Callable[..., None]], Behavior]:
     """Decorate a function as an event-driven behavior.
 
     v0.7 additions (both keyword-only):
@@ -175,7 +183,16 @@ def behavior(
     if activate_after is not None:
         delay_n = _parse_aa(activate_after)
 
-    def wrap(fn: Callable) -> Behavior:
+    def wrap(fn: Callable[..., None]) -> Behavior:
+        # v1.3: arity check at decoration time (see activegraph/_signature.py).
+        from activegraph._signature import validate_handler_signature
+
+        validate_handler_signature(
+            fn,
+            expected_params=("event", "graph", "ctx"),
+            decorator="@behavior",
+            allow_annotated_extras=True,
+        )
         b = Behavior(
             name=name or fn.__name__,
             fn=fn,
@@ -215,9 +232,9 @@ def llm_behavior(
     priority: int = 0,
     pattern: Optional[str] = None,
     activate_after: Any = None,
-    tools: Optional[list] = None,
+    tools: Optional[list[Any]] = None,
     max_tool_turns: int = 6,
-) -> Callable[[Callable], LLMBehavior]:
+) -> Callable[[Callable[..., None]], LLMBehavior]:
     """Decorate a function as an LLM-driven behavior.
 
     The decorated function's signature is
@@ -281,7 +298,16 @@ def llm_behavior(
     # call; failing here names the cause at the @llm_behavior line.
     _validate_output_schema(output_schema)
 
-    def wrap(fn: Callable) -> LLMBehavior:
+    def wrap(fn: Callable[..., None]) -> LLMBehavior:
+        # v1.3: arity check at decoration time (see activegraph/_signature.py).
+        from activegraph._signature import validate_handler_signature
+
+        validate_handler_signature(
+            fn,
+            expected_params=("event", "graph", "ctx", "llm_output"),
+            decorator="@llm_behavior",
+            allow_annotated_extras=True,
+        )
         b = LLMBehavior(
             name=name or fn.__name__,
             fn=_llm_behavior_fn_placeholder,
@@ -331,7 +357,7 @@ def relation_behavior(
     *,
     pattern: Optional[str] = None,
     activate_after: Any = None,
-) -> Callable[[Callable], RelationBehavior]:
+) -> Callable[[Callable[..., None]], RelationBehavior]:
     """Decorate a function as a relation behavior — fires once per matching edge.
 
     v0.7: also accepts `pattern=` and `activate_after=` per CONTRACT
@@ -348,7 +374,16 @@ def relation_behavior(
     if activate_after is not None:
         delay_n = _parse_aa(activate_after)
 
-    def wrap(fn: Callable) -> RelationBehavior:
+    def wrap(fn: Callable[..., None]) -> RelationBehavior:
+        # v1.3: arity check at decoration time (see activegraph/_signature.py).
+        from activegraph._signature import validate_handler_signature
+
+        validate_handler_signature(
+            fn,
+            expected_params=("relation", "event", "graph", "ctx"),
+            decorator="@relation_behavior",
+            allow_annotated_extras=True,
+        )
         rb = RelationBehavior(
             name=name or fn.__name__,
             fn=fn,