memkernel-mcp 0.1.0__py3-none-any.whl

memkernel/clients/adapter.py

@@ -0,0 +1,296 @@
+"""Client adapters for agent harnesses.
+
+* :class:`MemKernelClient` — in-process, agent-scoped handle on a
+  :class:`~memkernel.kernel.MemKernel` (lowest latency; for Python harnesses).
+* :class:`McpStdioClient` — speaks MCP to a ``memkernel-server`` subprocess,
+  exactly like Cursor, Claude Code or Codex do. Many such clients (one per
+  process) can share a single database file.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+from memkernel.core.events import EventEnvelope, EventType, new_event, validate_agent_id, validate_branch_id
+from memkernel.kernel import DEFAULT_BRANCH, LeaseGrant, MemKernel
+from memkernel.memory.gc import GCResult
+
+
+class LeaseUnavailableError(RuntimeError):
+    def __init__(self, grant: LeaseGrant) -> None:
+        super().__init__(
+            f"lease on {grant.resource!r} is held by {grant.holder_agent_id!r} "
+            f"for another {grant.expires_in_seconds}s"
+        )
+        self.grant = grant
+
+
+@dataclass
+class LeaseHandle:
+    """Yielded by :meth:`MemKernelClient.lease`. ``lost`` becomes true if a
+    heartbeat fails; stop writing and re-acquire when it does."""
+
+    grant: LeaseGrant
+    _lost: asyncio.Event = field(default_factory=asyncio.Event)
+
+    @property
+    def fencing_token(self) -> int:
+        assert self.grant.fencing_token is not None
+        return self.grant.fencing_token
+
+    @property
+    def lost(self) -> bool:
+        return self._lost.is_set()
+
+
+class MemKernelClient:
+    """Agent-scoped view of a kernel: fixed ``agent_id``, switchable branch."""
+
+    def __init__(self, kernel: MemKernel, agent_id: str, branch: str = DEFAULT_BRANCH) -> None:
+        self.kernel = kernel
+        self.agent_id = validate_agent_id(agent_id)
+        self.branch = validate_branch_id(branch)
+
+    async def checkout(self, branch: str) -> None:
+        await self.kernel.store.get_branch(branch)  # raises if missing
+        self.branch = branch
+
+    # ---------------------------------------------------------------- writes
+
+    async def init_task(self, directive: str, constraints: list[str] | None = None) -> EventEnvelope:
+        return await self.kernel.init_task(
+            branch_id=self.branch, agent_id=self.agent_id, directive=directive, constraints=constraints
+        )
+
+    async def decide(self, key: str, value: str, rationale: str) -> EventEnvelope:
+        return await self.kernel.append_decision(
+            branch_id=self.branch, agent_id=self.agent_id, key=key, value=value, rationale=rationale
+        )
+
+    async def log_execution(
+        self, command: str, exit_code: int, output: str = "", facts: dict[str, Any] | None = None
+    ) -> EventEnvelope:
+        return await self.kernel.log_execution(
+            branch_id=self.branch,
+            agent_id=self.agent_id,
+            command=command,
+            exit_code=exit_code,
+            output=output,
+            facts=facts,
+        )
+
+    async def note(self, text: str) -> EventEnvelope:
+        return await self.kernel.note(branch_id=self.branch, agent_id=self.agent_id, note=text)
+
+    async def fenced_write(
+        self, event_type: EventType, payload: dict[str, Any], *, resource: str, fencing_token: int
+    ) -> EventEnvelope:
+        """Append only while holding the current lease on ``resource``."""
+        return await self.kernel.fenced_append(
+            new_event(event_type, branch_id=self.branch, agent_id=self.agent_id, payload=payload),
+            resource=resource,
+            fencing_token=fencing_token,
+        )
+
+    # ----------------------------------------------------------------- reads
+
+    async def query_state(self, *, include_ephemeral: bool = False, branch: str | None = None) -> dict[str, Any]:
+        return await self.kernel.query_state(branch or self.branch, include_ephemeral=include_ephemeral)
+
+    async def context(self, branch: str | None = None) -> str:
+        return await self.kernel.context(branch or self.branch)
+
+    async def history(self, limit: int = 30) -> list[dict[str, Any]]:
+        return await self.kernel.history(self.branch, limit=limit)
+
+    # --------------------------------------------------------------- timeline
+
+    async def fork_investigation(self, name: str, *, at_event_id: int | None = None) -> EventEnvelope:
+        """Fork the current branch and switch to the fork."""
+        event = await self.kernel.fork(
+            source_branch=self.branch,
+            new_branch=name,
+            agent_id=self.agent_id,
+            at_event_id=at_event_id,
+            reason="investigation",
+        )
+        self.branch = name
+        return event
+
+    async def rollback(self, target_event_id: int, reason: str = "") -> EventEnvelope:
+        return await self.kernel.rollback(
+            branch_id=self.branch, target_event_id=target_event_id, agent_id=self.agent_id, reason=reason
+        )
+
+    async def diff(self, other_branch: str) -> dict[str, Any]:
+        return await self.kernel.diff(self.branch, other_branch)
+
+    async def gc(self, *, force: bool = True) -> GCResult:
+        return await self.kernel.gc(self.branch, force=force)
+
+    # ----------------------------------------------------------------- leases
+
+    async def acquire(self, resource: str, ttl_seconds: float = 30) -> LeaseGrant:
+        return await self.kernel.acquire_lease(
+            branch_id=self.branch, agent_id=self.agent_id, resource=resource, ttl_seconds=ttl_seconds
+        )
+
+    async def release(self, resource: str, fencing_token: int) -> bool:
+        return await self.kernel.release_lease(
+            branch_id=self.branch, agent_id=self.agent_id, resource=resource, fencing_token=fencing_token
+        )
+
+    @asynccontextmanager
+    async def lease(
+        self,
+        resource: str,
+        *,
+        ttl_seconds: float = 30,
+        wait_seconds: float = 0,
+        poll_interval: float = 0.25,
+        heartbeat: bool = True,
+    ) -> AsyncIterator[LeaseHandle]:
+        """Hold a lease for the duration of the block, heartbeating every
+        ``ttl_seconds / 3`` and releasing on exit. Waits up to
+        ``wait_seconds`` for a contended lease, then raises
+        :class:`LeaseUnavailableError`."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + max(0.0, wait_seconds)
+        while True:
+            grant = await self.acquire(resource, ttl_seconds)
+            if grant.acquired:
+                break
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                raise LeaseUnavailableError(grant)
+            await asyncio.sleep(max(0.01, min(poll_interval, remaining)))
+
+        handle = LeaseHandle(grant)
+
+        async def beat() -> None:
+            while True:
+                await asyncio.sleep(ttl_seconds / 3)
+                if not await self.kernel.heartbeat_lease(resource=grant.resource, fencing_token=handle.fencing_token):
+                    handle._lost.set()
+                    return
+
+        task = asyncio.create_task(beat()) if heartbeat else None
+        try:
+            yield handle
+        finally:
+            if task is not None:
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+            await self.release(grant.resource, handle.fencing_token)
+
+
+# ------------------------------------------------------------ MCP over stdio
+
+
+class McpToolError(RuntimeError):
+    def __init__(self, tool: str, message: str) -> None:
+        super().__init__(f"{tool}: {message}")
+        self.tool = tool
+
+
+class McpStdioClient:
+    """MCP client that spawns ``python -m memkernel.server.mcp_server``.
+
+    Usage::
+
+        async with McpStdioClient(agent_id="cursor-ide", db_path="mem.db") as c:
+            await c.call("memkernel_append_decision", decision_key="db",
+                         decision_value="postgres", rationale="...")
+    """
+
+    def __init__(
+        self,
+        *,
+        agent_id: str,
+        db_path: str,
+        branch: str = DEFAULT_BRANCH,
+        gc_threshold: int | None = None,
+        command: str | None = None,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> None:
+        self.agent_id = validate_agent_id(agent_id)
+        server_env = {
+            "MEMKERNEL_DB": os.path.abspath(db_path),
+            "MEMKERNEL_AGENT_ID": self.agent_id,
+            "MEMKERNEL_BRANCH": validate_branch_id(branch),
+        }
+        if gc_threshold is not None:
+            server_env["MEMKERNEL_GC_THRESHOLD"] = str(int(gc_threshold))
+        for passthrough in ("PYTHONPATH", "MEMKERNEL_TOKENIZER", "MEMKERNEL_LOG_LEVEL", "TIKTOKEN_CACHE_DIR"):
+            if passthrough in os.environ:
+                server_env[passthrough] = os.environ[passthrough]
+        server_env.update(env or {})
+        self._command = command or sys.executable
+        self._args = args if args is not None else ["-m", "memkernel.server.mcp_server"]
+        self._env = server_env
+        self._cwd = cwd
+        self._stack: AsyncExitStack | None = None
+        self._session: Any = None
+
+    async def __aenter__(self) -> "McpStdioClient":
+        from mcp import ClientSession, StdioServerParameters
+        from mcp.client.stdio import stdio_client
+
+        params = StdioServerParameters(command=self._command, args=self._args, env=self._env, cwd=self._cwd)
+        stack = AsyncExitStack()
+        try:
+            # Server logs go to our stderr, unless it is not a real file
+            # (pytest capture, Jupyter, some IDE consoles): then discard them.
+            errlog: Any = sys.stderr
+            try:
+                errlog.fileno()
+            except (AttributeError, OSError, ValueError):
+                errlog = stack.enter_context(open(os.devnull, "w", encoding="utf-8"))
+            read, write = await stack.enter_async_context(stdio_client(params, errlog=errlog))
+            session = await stack.enter_async_context(ClientSession(read, write))
+            await session.initialize()
+        except BaseException:
+            await stack.aclose()
+            raise
+        self._stack, self._session = stack, session
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        if self._stack is not None:
+            stack, self._stack, self._session = self._stack, None, None
+            await stack.aclose()
+
+    async def list_tools(self) -> list[str]:
+        result = await self._require_session().list_tools()
+        return sorted(tool.name for tool in result.tools)
+
+    async def call(self, tool: str, **arguments: Any) -> Any:
+        """Call a tool; returns decoded JSON when the result is JSON, else text.
+        Raises :class:`McpToolError` when the server reports a tool error."""
+        result = await self._require_session().call_tool(tool, arguments)
+        text = "\n".join(c.text for c in result.content if getattr(c, "type", None) == "text")
+        is_error = getattr(result, "is_error", None)
+        if is_error is None:  # mcp 1.x field name
+            is_error = getattr(result, "isError", False)
+        if is_error:
+            raise McpToolError(tool, text)
+        try:
+            return json.loads(text)
+        except ValueError:
+            return text
+
+    def _require_session(self) -> Any:
+        if self._session is None:
+            raise RuntimeError("McpStdioClient is not connected; use 'async with'")
+        return self._session

memkernel/core/__init__.py

@@ -0,0 +1 @@
+"""Core layer: event taxonomy, append-only store, lineage algebra and leases."""

memkernel/core/branch.py

@@ -0,0 +1,161 @@
+"""Git-like lineage algebra: live-timeline folding, rollback planning, diff
+and hash-chain verification.
+
+Everything here is a pure function over lists of envelopes. The store runs
+these functions inside its transactions; keeping them pure makes the branch
+semantics testable without a database and identical on every replica.
+
+Definitions
+-----------
+* **Raw lineage** ``L(b)``: every event reachable from branch ``b`` in log
+  order — the parent's raw lineage up to the fork point, then ``b``'s own
+  events. Forks copy no rows (copy-on-write lineage).
+* **Live timeline** ``live(L)``: left fold of ``L`` where a
+  ``ROLLBACK_TRIGGERED`` event targeting ``t`` truncates the live list to the
+  prefix ending at ``t`` and then appends itself (so rollbacks stay auditable).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from memkernel.core.events import GENESIS_HASH, EventEnvelope, EventType
+from memkernel.memory.state_view import materialize_live
+
+
+class LineageError(RuntimeError):
+    """The stored lineage violates a structural invariant."""
+
+
+def fold_live(raw: list[EventEnvelope]) -> list[EventEnvelope]:
+    """Compute the live timeline of a raw lineage."""
+    live: list[EventEnvelope] = []
+    position: dict[int, int] = {}
+    for event in raw:
+        if event.event_type is EventType.ROLLBACK_TRIGGERED:
+            target = event.payload.get("target_event_id")
+            pos = position.get(target) if isinstance(target, int) else None
+            if pos is None:
+                raise LineageError(
+                    f"rollback event {event.event_id} targets {target!r}, "
+                    "which is not live at that point in the lineage"
+                )
+            for dropped in live[pos + 1 :]:
+                del position[dropped.event_id]  # type: ignore[arg-type]
+            del live[pos + 1 :]
+        position[event.event_id] = len(live)  # type: ignore[index]
+        live.append(event)
+    return live
+
+
+def plan_rollback(live: list[EventEnvelope], target_event_id: int) -> tuple[EventEnvelope, list[int]]:
+    """Validate a rollback target and return ``(target, reverted_event_ids)``.
+
+    Only live events are valid targets: an event that is already reverted
+    cannot be restored by rolling "forward" to it — fork from it instead.
+    """
+    for index, event in enumerate(live):
+        if event.event_id == target_event_id:
+            return event, [e.event_id for e in live[index + 1 :]]  # type: ignore[misc]
+    raise ValueError(
+        f"event {target_event_id} is not on the live timeline of this branch; "
+        "to recover a reverted or foreign event, fork a new branch from it"
+    )
+
+
+def merge_base(raw_a: list[EventEnvelope], raw_b: list[EventEnvelope]) -> EventEnvelope | None:
+    """Last event shared by two raw lineages (their longest common prefix)."""
+    base = None
+    for a, b in zip(raw_a, raw_b):
+        if a.event_id != b.event_id:
+            break
+        base = a
+    return base
+
+
+def _summary(e: EventEnvelope) -> dict[str, Any]:
+    return {
+        "event_id": e.event_id,
+        "sequence": e.sequence,
+        "agent_id": e.agent_id,
+        "event_type": e.event_type.value,
+    }
+
+
+def diff_lineages(
+    branch_a: str, raw_a: list[EventEnvelope], branch_b: str, raw_b: list[EventEnvelope]
+) -> dict[str, Any]:
+    """Divergence report between two branches.
+
+    Returns the merge base, the live events each side has beyond it, and a
+    key-by-key comparison of materialized decisions and workspace facts.
+    """
+    base = merge_base(raw_a, raw_b)
+    base_seq = (base.sequence or 0) if base is not None else 0
+    live_a, live_b = fold_live(raw_a), fold_live(raw_b)
+    state_a, state_b = materialize_live(live_a), materialize_live(live_b)
+
+    def compare(left: dict[str, Any], right: dict[str, Any], field: str) -> dict[str, Any]:
+        conflicts, only_left, only_right = [], {}, {}
+        for key in sorted(left.keys() | right.keys()):
+            if key not in right:
+                only_left[key] = left[key]
+            elif key not in left:
+                only_right[key] = right[key]
+            elif left[key][field] != right[key][field]:
+                conflicts.append({"key": key, branch_a: left[key], branch_b: right[key]})
+        return {"conflicts": conflicts, "only_in_a": only_left, "only_in_b": only_right}
+
+    decisions = compare(state_a.sections()["decisions"], state_b.sections()["decisions"], "value")
+    facts = compare(
+        state_a.sections()["active_workspace_facts"],
+        state_b.sections()["active_workspace_facts"],
+        "value",
+    )
+    ahead_a = [_summary(e) for e in live_a if (e.sequence or 0) > base_seq]
+    ahead_b = [_summary(e) for e in live_b if (e.sequence or 0) > base_seq]
+    rollbacks = {
+        branch: [
+            {"event_id": e.event_id, "target_event_id": e.payload.get("target_event_id")}
+            for e in raw
+            if e.event_type is EventType.ROLLBACK_TRIGGERED and (e.sequence or 0) > base_seq
+        ]
+        for branch, raw in ((branch_a, raw_a), (branch_b, raw_b))
+    }
+    return {
+        "branch_a": branch_a,
+        "branch_b": branch_b,
+        "merge_base_event_id": base.event_id if base is not None else None,
+        "merge_base_sequence": base_seq,
+        "ahead_a": ahead_a,
+        "ahead_b": ahead_b,
+        "rollbacks_since_base": rollbacks,
+        "conflicting_decisions": decisions["conflicts"],
+        "decisions_only_in_a": decisions["only_in_a"],
+        "decisions_only_in_b": decisions["only_in_b"],
+        "conflicting_facts": facts["conflicts"],
+        "identical_state": state_a.core_sections() == state_b.core_sections(),
+    }
+
+
+def verify_lineage(raw: list[EventEnvelope]) -> list[str]:
+    """Check sequence contiguity, parent pointers and the SHA-256 hash chain.
+
+    Returns a list of human-readable violations (empty means intact).
+    """
+    problems: list[str] = []
+    prev_hash = GENESIS_HASH
+    prev_id: int | None = None
+    for index, event in enumerate(raw, start=1):
+        if event.sequence != index:
+            problems.append(f"event {event.event_id}: sequence {event.sequence} != expected {index}")
+        if event.parent_event_id != prev_id:
+            problems.append(
+                f"event {event.event_id}: parent_event_id {event.parent_event_id} != predecessor {prev_id}"
+            )
+        expected = event.compute_hash(prev_hash)
+        if event.hash != expected:
+            problems.append(f"event {event.event_id}: hash mismatch (content or chain tampered)")
+        prev_hash = event.hash or ""
+        prev_id = event.event_id
+    return problems

memkernel/core/events.py

@@ -0,0 +1,209 @@
+"""Immutable event taxonomy and envelope schema.
+
+Every state change in MemKernel is an :class:`EventEnvelope` appended to a
+branch's log. Envelopes are frozen pydantic models; the store assigns
+``event_id``, ``sequence`` and ``hash`` at append time and returns a new
+envelope rather than mutating the caller's copy.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+#: Hard cap on the serialized size of an event's ``payload`` and, separately,
+#: its ``metadata``. Protects the log and every agent's context from flooding.
+MAX_EVENT_BYTES = 256 * 1024
+
+BRANCH_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$")
+AGENT_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$")
+
+GENESIS_HASH = "0" * 64
+
+
+class EventType(str, Enum):
+    """Canonical event taxonomy."""
+
+    AGENT_TASK_INIT = "AGENT_TASK_INIT"
+    """Initial task directive and constraints for an agent."""
+    ARCHITECTURAL_DECISION = "ARCHITECTURAL_DECISION"
+    """Canonical, durable design choice keyed by ``decision_key``."""
+    FILE_CLAIM_ACQUIRED = "FILE_CLAIM_ACQUIRED"
+    """A lease on a resource was granted (carries the fencing token)."""
+    FILE_CLAIM_RELEASED = "FILE_CLAIM_RELEASED"
+    """A lease on a resource was released."""
+    TOOL_EXECUTION_LOG = "TOOL_EXECUTION_LOG"
+    """Ephemeral diagnostic / terminal output. Eligible for compaction."""
+    AGENT_SCRATCHPAD = "AGENT_SCRATCHPAD"
+    """Ephemeral intermediate reasoning turn. Eligible for compaction."""
+    SEMANTIC_SNAPSHOT = "SEMANTIC_SNAPSHOT"
+    """GC checkpoint holding distilled facts, decisions and blockers."""
+    BRANCH_FORKED = "BRANCH_FORKED"
+    """Audit record written as the first event of a forked branch."""
+    ROLLBACK_TRIGGERED = "ROLLBACK_TRIGGERED"
+    """Compensating event: the live timeline is truncated to its target."""
+
+
+#: Event types whose content is transient and may be compacted by GC.
+EPHEMERAL_TYPES: frozenset[EventType] = frozenset(
+    {EventType.TOOL_EXECUTION_LOG, EventType.AGENT_SCRATCHPAD}
+)
+
+#: Event types that only describe timeline structure, not workspace state.
+CONTROL_TYPES: frozenset[EventType] = frozenset(
+    {EventType.BRANCH_FORKED, EventType.ROLLBACK_TRIGGERED}
+)
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def canonical_json(value: Any) -> str:
+    """Deterministic JSON encoding used for storage and hashing."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def validate_branch_id(branch_id: str) -> str:
+    if not isinstance(branch_id, str) or not BRANCH_ID_PATTERN.fullmatch(branch_id):
+        raise ValueError(
+            f"invalid branch_id {branch_id!r}: expected 1-128 chars of [A-Za-z0-9._/-], "
+            "starting with a letter or digit"
+        )
+    return branch_id
+
+
+def validate_agent_id(agent_id: str) -> str:
+    if not isinstance(agent_id, str) or not AGENT_ID_PATTERN.fullmatch(agent_id):
+        raise ValueError(
+            f"invalid agent_id {agent_id!r}: expected 1-128 chars of [A-Za-z0-9._:@-], "
+            "starting with a letter or digit"
+        )
+    return agent_id
+
+
+class EventEnvelope(BaseModel):
+    """Immutable event record.
+
+    Fields assigned by the store (``event_id``, ``sequence``, ``hash``) are
+    ``None`` on envelopes that have not been persisted yet.
+
+    ``parent_event_id`` is the lineage predecessor (the branch head at append
+    time). When a caller supplies it, the store treats it as an optimistic
+    concurrency precondition: the append fails with
+    :class:`~memkernel.core.store.StaleHeadError` if the head has moved.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", use_enum_values=False)
+
+    event_id: int | None = Field(default=None, ge=1)
+    sequence: int | None = Field(default=None, ge=1)
+    timestamp: datetime = Field(default_factory=utcnow)
+    branch_id: str
+    agent_id: str
+    parent_event_id: int | None = Field(default=None, ge=1)
+    event_type: EventType
+    payload: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    hash: str | None = None
+
+    @field_validator("branch_id")
+    @classmethod
+    def _check_branch(cls, v: str) -> str:
+        return validate_branch_id(v)
+
+    @field_validator("agent_id")
+    @classmethod
+    def _check_agent(cls, v: str) -> str:
+        return validate_agent_id(v)
+
+    @field_validator("timestamp")
+    @classmethod
+    def _utc(cls, v: datetime) -> datetime:
+        if v.tzinfo is None:
+            raise ValueError("timestamp must be timezone-aware (UTC)")
+        return v.astimezone(timezone.utc)
+
+    @field_validator("payload", "metadata")
+    @classmethod
+    def _json_safe(cls, v: dict[str, Any]) -> dict[str, Any]:
+        try:
+            encoded = canonical_json(v)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"payload/metadata must be JSON-serializable: {exc}") from exc
+        if len(encoded.encode("utf-8")) > MAX_EVENT_BYTES:
+            raise ValueError(
+                f"payload/metadata exceeds {MAX_EVENT_BYTES} bytes; store large artifacts "
+                "outside MemKernel and reference them by path or digest"
+            )
+        # Round-trip so the in-memory value is exactly what gets persisted
+        # (tuples become lists, etc.), keeping hashes reproducible.
+        return json.loads(encoded)
+
+    @property
+    def timestamp_iso(self) -> str:
+        return self.timestamp.isoformat(timespec="microseconds")
+
+    @property
+    def is_ephemeral(self) -> bool:
+        return self.event_type in EPHEMERAL_TYPES
+
+    def hash_material(self, prev_hash: str) -> str:
+        """Canonical byte string covered by this event's hash-chain link."""
+        return canonical_json(
+            {
+                "prev": prev_hash,
+                "event_id": self.event_id,
+                "sequence": self.sequence,
+                "timestamp": self.timestamp_iso,
+                "branch_id": self.branch_id,
+                "agent_id": self.agent_id,
+                "parent_event_id": self.parent_event_id,
+                "event_type": self.event_type.value,
+                "payload": self.payload,
+                "metadata": self.metadata,
+            }
+        )
+
+    def compute_hash(self, prev_hash: str) -> str:
+        return hashlib.sha256(self.hash_material(prev_hash).encode("utf-8")).hexdigest()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_id": self.event_id,
+            "sequence": self.sequence,
+            "timestamp": self.timestamp_iso,
+            "branch_id": self.branch_id,
+            "agent_id": self.agent_id,
+            "parent_event_id": self.parent_event_id,
+            "event_type": self.event_type.value,
+            "payload": self.payload,
+            "metadata": self.metadata,
+            "hash": self.hash,
+        }
+
+
+def new_event(
+    event_type: EventType,
+    *,
+    branch_id: str,
+    agent_id: str,
+    payload: dict[str, Any] | None = None,
+    metadata: dict[str, Any] | None = None,
+    parent_event_id: int | None = None,
+) -> EventEnvelope:
+    """Convenience constructor for an unpersisted envelope."""
+    return EventEnvelope(
+        event_type=event_type,
+        branch_id=branch_id,
+        agent_id=agent_id,
+        payload=payload or {},
+        metadata=metadata or {},
+        parent_event_id=parent_event_id,
+    )