activegraph 1.2.0__tar.gz → 1.4.0__tar.gz

{activegraph-1.2.0/activegraph.egg-info → activegraph-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.2.0
+Version: 1.4.0
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License-Expression: Apache-2.0

{activegraph-1.2.0 → activegraph-1.4.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
@@ -190,6 +197,11 @@ __all__ = [
     "PendingApproval",
     "Policy",
     "PrometheusMetrics",
+    "PromoteConflict",
+    "PromoteConflictError",
+    "PromoteLineageError",
+    "PromotePlan",
+    "PromoteResult",
     "Relation",
     "RelationBehavior",
     "RegistrationError",
@@ -230,4 +242,4 @@ __all__ = [
     "tool",
 ]
 
-__version__ = "1.2.0"
+__version__ = "1.4.0"

activegraph-1.4.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.2.0 → activegraph-1.4.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.2.0 → activegraph-1.4.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,

{activegraph-1.2.0 → activegraph-1.4.0}/activegraph/cli/main.py

@@ -1,6 +1,6 @@
 """activegraph CLI entry point. CONTRACT v0.8 #12–#13.
 
-Subcommands: inspect, replay, fork, diff, export-trace, migrate.
+Subcommands: inspect, replay, fork, diff, promote, export-trace, migrate.
 
 Each one is a thin wrapper around a library API. The CLI does no
 business logic — it parses arguments, calls into Python, and formats
@@ -129,7 +129,7 @@ def _list_runs_or_die(url: str):
 @click.group(context_settings={"help_option_names": ["-h", "--help"]})
 @click.version_option(message="activegraph %(version)s")
 def cli() -> None:
-    """Inspect, replay, fork, diff, export, and migrate activegraph runs."""
+    """Inspect, replay, fork, diff, promote, export, and migrate activegraph runs."""
 
 
 # ---- quickstart ---------------------------------------------------------
@@ -866,6 +866,125 @@ def cmd_diff(url: str, run_a: str, run_b: str, as_json: bool) -> None:
             click.echo(f"  - {r.summary()}")
 
 
+# ---- promote ------------------------------------------------------------
+
+
+@cli.command("promote")
+@click.argument("url")
+@click.option("--run-id", required=True, help="Destination (parent) run.")
+@click.option("--from-run", required=True, help="Source (fork) run.")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Compute and print the plan without applying anything.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def cmd_promote(
+    url: str, run_id: str, from_run: str, dry_run: bool, as_json: bool
+) -> None:
+    """Apply a fork's net structural delta to its parent (CONTRACT v1.3 #4).
+
+    Fail-closed and atomic: any conflict between the fork's delta and
+    the parent's own post-fork changes aborts with nothing applied
+    (exit 5, the divergence code) — a conflicted --dry-run also exits
+    5 so scripts can gate on it. Fork lineage is verified from the
+    store's runs table.
+    """
+    from activegraph.runtime.exec_errors import (
+        PromoteConflictError,
+        PromoteLineageError,
+    )
+    from activegraph.runtime.runtime import Runtime
+    from activegraph.store.url import InvalidStoreURL, parse_store_url
+
+    try:
+        parse_store_url(url)
+    except InvalidStoreURL as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(EXIT_USAGE_ERROR)
+
+    # Validate both run ids against the runs table BEFORE Runtime.load:
+    # load upserts a run row for whatever id it's given, so loading a
+    # mistyped id would insert a phantom empty run and then fail with
+    # a misleading lineage error.
+    known_runs = {r.run_id for r in _list_runs_or_die(url)}
+    for label_, rid in (("--run-id", run_id), ("--from-run", from_run)):
+        if rid not in known_runs:
+            click.echo(
+                f"{label_} {rid!r}: no such run in {url} "
+                f"(activegraph inspect {url} --runs lists them)",
+                err=True,
+            )
+            raise SystemExit(EXIT_NOT_FOUND)
+
+    try:
+        parent = Runtime.load(url, run_id=run_id)
+        fork = Runtime.load(url, run_id=from_run)
+    except FileNotFoundError as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(EXIT_NOT_FOUND)
+    except __import__("sqlite3").OperationalError as e:
+        click.echo(f"{url}: {e}", err=True)
+        raise SystemExit(EXIT_NOT_FOUND)
+
+    try:
+        outcome = parent.promote(fork, dry_run=dry_run)
+    except PromoteLineageError as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(EXIT_NOT_FOUND)
+    except PromoteConflictError as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(EXIT_DIVERGENCE)
+
+    plan = outcome if dry_run else outcome.plan
+    summary = {
+        "from_run": plan.from_run,
+        "into_run": plan.into_run,
+        "forked_at_event": plan.forked_at_event,
+        "computed_against": plan.computed_against,
+        "dry_run": dry_run,
+        "objects_created": [o["id"] for o in plan.object_creates],
+        "objects_patched": [o["id"] for o in plan.object_patches],
+        "objects_removed": list(plan.object_removes),
+        "relations_created": [r["id"] for r in plan.relation_creates],
+        "relations_removed": list(plan.relation_removes),
+        "conflicts": [
+            {"kind": c.kind, "entity": c.entity, "id": c.id, "detail": c.detail}
+            for c in plan.conflicts
+        ],
+        "warnings": list(plan.warnings),
+    }
+    if not dry_run:
+        summary["marker_event_id"] = outcome.marker_event_id
+        summary["applied_event_ids"] = list(outcome.applied_event_ids)
+    if as_json:
+        click.echo(_json.dumps(summary))
+        if dry_run and plan.conflicts:
+            raise SystemExit(EXIT_DIVERGENCE)
+        return
+    verb = "would promote" if dry_run else "promoted"
+    click.echo(f"{verb} {plan.from_run} -> {plan.into_run}:")
+    for key in (
+        "objects_created",
+        "objects_patched",
+        "objects_removed",
+        "relations_created",
+        "relations_removed",
+    ):
+        ids = summary[key]
+        if ids:
+            click.echo(f"  {key:20s} {', '.join(ids)}")
+    for w in plan.warnings:
+        click.echo(f"  warning: {w}")
+    if dry_run and plan.conflicts:
+        click.echo("conflicts (promote would fail):")
+        for c in plan.conflicts:
+            click.echo(f"  - [{c.kind}] {c.entity} {c.id}: {c.detail}")
+        # Scripts gate on the exit code: a conflicted dry run is the
+        # same signal as a conflicted apply, minus the mutation.
+        raise SystemExit(EXIT_DIVERGENCE)
+
+
 # ---- export-trace -------------------------------------------------------
 
 

{activegraph-1.2.0 → activegraph-1.4.0}/activegraph/core/clock.py

@@ -6,7 +6,13 @@ from datetime import datetime, timezone
 
 
 class Clock:
-    """Real wall-clock UTC. ISO 8601 second precision, Z suffix."""
+    """Real wall-clock UTC. ISO 8601 second precision, Z suffix.
+
+    The default time source for event timestamps. The runtime reads
+    time only through this interface, so deterministic runs swap in
+    :class:`FrozenClock` or :class:`TickingClock` and replay never
+    depends on the machine clock.
+    """
 
     def now(self) -> str:
         return (
@@ -17,7 +23,13 @@ class Clock:
 
 
 class FrozenClock(Clock):
-    """Always returns the same timestamp. For tests and snapshots."""
+    """Always returns the same timestamp. For tests and snapshots.
+
+    Every ``now()`` call yields the constructor's ``t`` unchanged, so
+    an event log written under a FrozenClock is byte-for-byte
+    reproducible. Use :class:`TickingClock` when a test needs ordering
+    across timestamps rather than strict equality.
+    """
 
     def __init__(self, t: str = "2026-05-15T10:32:01Z") -> None:
         self._t = t
@@ -27,8 +39,13 @@ class FrozenClock(Clock):
 
 
 class TickingClock(Clock):
-    """Monotonically advances by `step` seconds on every call. For tests that
-    care about ordering but don't want wall-clock noise."""
+    """Monotonically advances by ``step`` seconds on every call.
+
+    For tests that care about ordering but don't want wall-clock
+    noise: timestamps increase deterministically from the start value,
+    so before/after assertions hold without sleeping or freezing time
+    entirely.
+    """
 
     def __init__(
         self,

{activegraph-1.2.0 → activegraph-1.4.0}/activegraph/core/event.py

@@ -13,6 +13,16 @@ from typing import Any, Optional
 
 @dataclass(frozen=True)
 class Event:
+    """One immutable record in the append-only log. CONTRACT #3.
+
+    An event is a fact: ``type`` names what happened, ``payload``
+    carries the data, ``actor`` says who caused it, ``caused_by``
+    links the causal parent event, and ``frame_id`` scopes it to a
+    mission frame. Events are never modified after ``emit`` —
+    objects, relations, patches, and views are all projections
+    derived from the sequence of these records (CONTRACT #2).
+    """
+
     id: str
     type: str
     payload: dict[str, Any] = field(default_factory=dict)