axiongraph 0.0.1__py3-none-any.whl

axiongraph/__init__.py

@@ -0,0 +1,59 @@
+"""AxionGraph — append-only execution-graph event model and deterministic reducer.
+
+The bare ``axiongraph`` import is the core API; ``axiongraph.store_local`` exposes the
+zero-service reference stores. This mirrors the TypeScript package's ``.`` and ``/store-local``
+subpath exports."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from axiongraph_core import (
+    Anomaly,
+    AnomalyKind,
+    EdgePayload,
+    EdgeStatus,
+    GraphEvent,
+    GraphEventType,
+    GraphState,
+    GraphStore,
+    GraphVocabulary,
+    NodePayload,
+    OnAnomaly,
+    ValidationResult,
+    canonicalize,
+    empty_state,
+    example_vocabulary,
+    reduce,
+    reduce_all,
+    subgraph,
+    validate,
+)
+
+try:
+    __version__ = version("axiongraph")
+except PackageNotFoundError:  # pragma: no cover - only during local source runs
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Anomaly",
+    "AnomalyKind",
+    "EdgePayload",
+    "EdgeStatus",
+    "GraphEvent",
+    "GraphEventType",
+    "GraphState",
+    "GraphStore",
+    "GraphVocabulary",
+    "NodePayload",
+    "OnAnomaly",
+    "ValidationResult",
+    "__version__",
+    "canonicalize",
+    "empty_state",
+    "example_vocabulary",
+    "reduce",
+    "reduce_all",
+    "subgraph",
+    "validate",
+]

axiongraph/store_local.py

@@ -0,0 +1,7 @@
+"""The ``axiongraph.store_local`` subpath: zero-service reference GraphStore adapters."""
+
+from __future__ import annotations
+
+from axiongraph_store_local import InMemoryStore, SqliteStore
+
+__all__ = ["InMemoryStore", "SqliteStore"]

axiongraph-0.0.1.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: axiongraph
+Version: 0.0.1
+Summary: Invisible events. Replayable graphs. An append-only execution-graph event model and deterministic reducer — provider-agnostic, storage is a port.
+Project-URL: Homepage, https://github.com/cachetronaut/axiongraph-py
+Project-URL: Repository, https://github.com/cachetronaut/axiongraph-py
+Project-URL: Issues, https://github.com/cachetronaut/axiongraph-py/issues
+License: MIT
+License-File: LICENSE
+Keywords: agentic,agents,ai,ai-agents,append-only,audit,axiongraph,dag,deterministic,directed-graph,event-log,event-sourcing,event-store,execution-graph,genai,graph,graph-events,graph-state,graph-store,immutable,langgraph,lineage,llm,multi-agent,observability,orchestration,provenance,reducer,replay,snapshot,sqlite,telemetry,tracing,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# AxionGraph (Python)
+
+> Invisible events. Replayable graphs.
+
+AxionGraph is an append-only event model and deterministic reducer for execution graphs.
+It records graph events from agents, tools, workflows, and connectors, then folds them into
+portable graph state for storage, replay, testing, and visualization.
+
+This is the Python mirror of [`axiongraph` on npm](https://www.npmjs.com/package/axiongraph);
+the two cores are kept in lockstep by shared cross-language parity fixtures.
+
+```python
+from axiongraph import reduce_all
+
+events = [
+    {"id": "evt_01", "runId": "run_01", "seq": 1, "ts": "2026-06-02T12:00:00.000Z",
+     "type": "node_created", "node": {"id": "agent_research", "kind": "agent", "label": "Research Agent"}},
+    {"id": "evt_02", "runId": "run_01", "seq": 2, "ts": "2026-06-02T12:00:01.000Z",
+     "type": "node_created", "node": {"id": "tool_web", "kind": "tool", "label": "Web Search"}},
+    {"id": "evt_03", "runId": "run_01", "seq": 3, "ts": "2026-06-02T12:00:02.000Z",
+     "type": "edge_created",
+     "edge": {"id": "edge_01", "kind": "called_tool", "from": "agent_research", "to": "tool_web", "status": "completed"}},
+]
+
+state = reduce_all("run_01", events)
+print(len(state.nodes))  # 2
+print(len(state.edges))  # 1
+```
+
+## Core ideas
+
+- Append-only events are the source of truth; graph state is derived by folding them.
+- The reducer is pure and deterministic — identical event logs fold to byte-identical state.
+- A monotonic `seq` per run defines order; wall-clock `ts` is advisory.
+- Node/edge `kind` is an open taxonomy; supply a `GraphVocabulary` to reject unknown kinds.
+- Storage is a port (`GraphStore`); rendering and realtime transport are consumer concerns.
+- Event/payload shapes use the same wire keys as the TypeScript package (`runId`, `from`) so
+  the same events flow across both runtimes.
+
+## One package, opt-in extras
+
+AxionGraph ships as a single `axiongraph` distribution. The core API is the top-level import;
+optional backends are installed as extras (`pip install axiongraph[...]`). The local stores
+need no extra — `sqlite3` is in the standard library.
+
+| Import | Description |
+| --- | --- |
+| `axiongraph` | Event model, deterministic reducer, canonicalizer, vocabulary machinery, and the `GraphStore` port. |
+| `axiongraph.store_local` | Zero-service reference adapters: an in-memory store and a `sqlite3`-backed durable store. |
+
+## Install
+
+```sh
+pip install axiongraph        # or: uv add axiongraph
+```
+
+## Storing and replaying events
+
+```python
+from axiongraph.store_local import SqliteStore  # or InMemoryStore
+
+store = SqliteStore("./run.db")        # ":memory:" by default
+await store.append(events)             # idempotent on (runId, seq)
+state = await store.snapshot("run_01")
+```
+
+Both `InMemoryStore` and `SqliteStore` satisfy the same `GraphStore` protocol and are
+interchangeable; any future adapter that passes the shared contract suite drops in the same way.
+
+## Development
+
+Python 3.11+ and [uv](https://docs.astral.sh/uv/). The repo is an internal package set
+(`packages/core`, `packages/store-local`) assembled by hatchling into the one `axiongraph`
+distribution.
+
+```sh
+uv sync --dev
+uv run ruff check . && uv run ruff format --check .
+uv run ty check
+uv run pytest
+```
+
+## Status
+
+Early development. The reducer and reference stores are implemented and pass the same
+parity fixtures as the TypeScript package.
+
+## License
+
+MIT

axiongraph-0.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+axiongraph/__init__.py,sha256=ASWHmnNJWbMARmWxDe04q5QS08M6_Ugb6Vmc6LKKVgM,1287
+axiongraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+axiongraph/store_local.py,sha256=TpF6Eun0Q4Eu9NyOgC7i_-ljKj67iyITBeLnwCHzU58,233
+axiongraph_core/__init__.py,sha256=DfVJFh4dWrPpqfYyz8n3BdUAYR24fFYmLrUsr_an0wA,975
+axiongraph_core/canonical.py,sha256=OXVBJ75eJSvWi9anlbhEx4Utw-7c3sU0xPg9YwOlmqU,1031
+axiongraph_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+axiongraph_core/reducer.py,sha256=0UNhdt42mo16dLVKuslwlnslLLSVPY8QdL9xhbYeyKI,3865
+axiongraph_core/store.py,sha256=R9mY9lyxo51t-YAznp22cnZiH6AaBmMDGPKGQ7QI0mk,1239
+axiongraph_core/types.py,sha256=FroEsilc9aP-QEWKkmEiW-ynlP91tg1YVTDoKV-ksvc,1809
+axiongraph_core/vocabulary.py,sha256=p5UGBMf6hGba95mSrGz4APvFyL5ovUk45Hw7S3EibEU,2217
+axiongraph_store_local/__init__.py,sha256=MMhML7xCxNDGq-vWfOFm3o32UpxfGBrM4lHPPGmE4b0,331
+axiongraph_store_local/in_memory.py,sha256=LcVbViCDwzgcypFHFHTEmgttTAfm1lmKaEo35FKdNTg,1238
+axiongraph_store_local/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+axiongraph_store_local/sqlite.py,sha256=9XeYpedeQyEvAjxkDF7K7vaDFlmyvVPlGPnCz2-9N3Y,2156
+axiongraph-0.0.1.dist-info/METADATA,sha256=CRU1k7ege739Yd6Je911VFW9l9mTAnLgTNo5oixEbd4,4776
+axiongraph-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+axiongraph-0.0.1.dist-info/licenses/LICENSE,sha256=sY7MtwwAOv-F1CsV_S47AsnkT_IPK2ifi1WBbsjLF-Q,1069
+axiongraph-0.0.1.dist-info/RECORD,,

axiongraph-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

axiongraph-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cachetronaut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axiongraph_core/__init__.py

@@ -0,0 +1,39 @@
+"""axiongraph-core — the append-only event model, deterministic reducer, canonicalizer,
+vocabulary machinery, and the GraphStore port. Published as part of the ``axiongraph`` package."""
+
+from __future__ import annotations
+
+from .canonical import canonicalize
+from .reducer import Anomaly, AnomalyKind, OnAnomaly, empty_state, reduce, reduce_all, subgraph
+from .store import GraphStore
+from .types import (
+    EdgePayload,
+    EdgeStatus,
+    GraphEvent,
+    GraphEventType,
+    GraphState,
+    NodePayload,
+)
+from .vocabulary import GraphVocabulary, ValidationResult, example_vocabulary, validate
+
+__all__ = [
+    "Anomaly",
+    "AnomalyKind",
+    "EdgePayload",
+    "EdgeStatus",
+    "GraphEvent",
+    "GraphEventType",
+    "GraphState",
+    "GraphStore",
+    "GraphVocabulary",
+    "NodePayload",
+    "OnAnomaly",
+    "ValidationResult",
+    "canonicalize",
+    "empty_state",
+    "example_vocabulary",
+    "reduce",
+    "reduce_all",
+    "subgraph",
+    "validate",
+]

axiongraph_core/canonical.py

@@ -0,0 +1,26 @@
+"""Deterministic, key-sorted JSON for a state. Identical event logs fold to byte-identical
+output (spec D5) — this is the contract the cross-language parity fixtures pin.
+
+Mirrors the TypeScript ``canonicalize``: a ``{runId, seq, nodes, edges}`` shape with nodes and
+edges sorted by id, then ``json.dumps`` with sorted keys and no whitespace (matching
+``JSON.stringify`` over a recursively key-sorted value)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from .types import GraphState
+
+
+def canonicalize(state: GraphState) -> str:
+    """Return the canonical, byte-stable JSON string for ``state``."""
+    nodes = sorted(state.nodes.values(), key=lambda node: node["id"])
+    edges = sorted(state.edges.values(), key=lambda edge: cast(dict[str, Any], edge)["id"])
+    shape: dict[str, Any] = {
+        "runId": state.run_id,
+        "seq": state.seq,
+        "nodes": nodes,
+        "edges": edges,
+    }
+    return json.dumps(shape, sort_keys=True, separators=(",", ":"), ensure_ascii=False)

axiongraph_core/reducer.py

@@ -0,0 +1,101 @@
+"""The deterministic reducer. Pure and side-effect free (spec D5): no clock, no I/O,
+no randomness. Identical event sequences fold to identical state."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, replace
+from typing import Any, Literal, cast
+
+from .types import EdgePayload, GraphEvent, GraphState, NodePayload
+
+AnomalyKind = Literal["wrong_run", "stale_seq", "update_unknown_node", "update_unknown_edge"]
+
+
+@dataclass(frozen=True)
+class Anomaly:
+    """Something the reducer noticed but did not apply. Observation only, never raised."""
+
+    kind: AnomalyKind
+    event: GraphEvent
+
+
+OnAnomaly = Callable[[Anomaly], None]
+
+
+def empty_state(run_id: str) -> GraphState:
+    """The fold's seed. ``seq`` starts at 0; the first applied event must have ``seq >= 1``."""
+    return GraphState(run_id=run_id, nodes={}, edges={}, seq=0)
+
+
+def _report(on_anomaly: OnAnomaly | None, kind: AnomalyKind, event: GraphEvent) -> None:
+    if on_anomaly is not None:
+        on_anomaly(Anomaly(kind=kind, event=event))
+
+
+def reduce(state: GraphState, event: GraphEvent, on_anomaly: OnAnomaly | None = None) -> GraphState:
+    """Apply one event. Events for another run, or with a non-increasing ``seq``, are
+    ignored idempotently (spec D3). Updates to unknown ids are dropped (spec D6)."""
+    if event["runId"] != state.run_id:
+        _report(on_anomaly, "wrong_run", event)
+        return state
+    if event["seq"] <= state.seq:
+        _report(on_anomaly, "stale_seq", event)
+        return state
+
+    event_type = event["type"]
+
+    if event_type == "node_created":
+        nodes = dict(state.nodes)
+        node = cast(NodePayload, event["node"])
+        nodes[node["id"]] = node
+        return replace(state, nodes=nodes, seq=event["seq"])
+
+    if event_type == "node_updated":
+        update = event["node"]
+        existing = state.nodes.get(update["id"])
+        if existing is None:
+            _report(on_anomaly, "update_unknown_node", event)
+            return replace(state, seq=event["seq"])
+        nodes = dict(state.nodes)
+        nodes[update["id"]] = cast(NodePayload, {**existing, **update})
+        return replace(state, nodes=nodes, seq=event["seq"])
+
+    if event_type == "edge_created":
+        edges = dict(state.edges)
+        edge = cast(EdgePayload, event["edge"])
+        edges[edge["id"]] = edge
+        return replace(state, edges=edges, seq=event["seq"])
+
+    if event_type == "edge_updated":
+        update = event["edge"]
+        existing = state.edges.get(update["id"])
+        if existing is None:
+            _report(on_anomaly, "update_unknown_edge", event)
+            return replace(state, seq=event["seq"])
+        edges = dict(state.edges)
+        edges[update["id"]] = cast(EdgePayload, {**existing, **update})
+        return replace(state, edges=edges, seq=event["seq"])
+
+    return state
+
+
+def reduce_all(
+    run_id: str, events: Iterable[GraphEvent], on_anomaly: OnAnomaly | None = None
+) -> GraphState:
+    """Fold an event log into state. Sorted by ``seq`` first, so arrival order does not matter."""
+    state = empty_state(run_id)
+    for event in sorted(events, key=lambda candidate: candidate["seq"]):
+        state = reduce(state, event, on_anomaly)
+    return state
+
+
+def subgraph(state: GraphState, keep_node: Callable[[NodePayload], bool]) -> GraphState:
+    """Derive a filtered view: keep matching nodes and any edge whose endpoints both survive."""
+    nodes = {node_id: node for node_id, node in state.nodes.items() if keep_node(node)}
+    edges: dict[str, EdgePayload] = {}
+    for edge_id, edge in state.edges.items():
+        endpoints: dict[str, Any] = cast(dict[str, Any], edge)
+        if endpoints["from"] in nodes and endpoints["to"] in nodes:
+            edges[edge_id] = edge
+    return replace(state, nodes=nodes, edges=edges)

axiongraph_core/store.py

@@ -0,0 +1,28 @@
+"""The :class:`GraphStore` port (spec D4): the seam between the event model and any backend.
+Core defines the protocol; adapters (``axiongraph.store_local``, and later convex/neo4j/postgres)
+implement it. Writes are append-only and idempotent on ``(runId, seq)`` (ties back to spec D3)."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from typing import Protocol, runtime_checkable
+
+from .types import GraphEvent, GraphState
+
+
+@runtime_checkable
+class GraphStore(Protocol):
+    """Append-only event storage. Realtime fan-out (an optional ``subscribe``) is where the
+    hosted product lives; the local adapter omits it. Core never assumes a realtime transport."""
+
+    async def append(self, events: Sequence[GraphEvent]) -> None:
+        """Append events. Idempotent on ``(runId, seq)``: re-appending a known seq is a no-op."""
+        ...
+
+    def read_events(self, run_id: str, since_seq: int = 0) -> AsyncIterator[GraphEvent]:
+        """Read a run's events in ``seq`` order, optionally only those after ``since_seq``."""
+        ...
+
+    async def snapshot(self, run_id: str) -> GraphState:
+        """The reduced state for a run. May be a live fold or a materialized cache."""
+        ...

axiongraph_core/types.py

@@ -0,0 +1,62 @@
+"""The append-only event model. The event log is the source of truth (spec D1);
+live :class:`GraphState` is always a fold over events, never mutated in place.
+
+The wire shapes mirror the TypeScript contracts and use the same camelCase keys
+(``runId``, ``from``) so the cross-language parity fixtures are byte-identical.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, NotRequired, TypedDict
+
+GraphEventType = Literal["node_created", "node_updated", "edge_created", "edge_updated"]
+
+EdgeStatus = Literal["proposed", "active", "completed", "failed", "blocked"]
+
+
+class NodePayload(TypedDict):
+    """A node. ``metadata`` is present only when supplied (open taxonomy, spec D2)."""
+
+    id: str
+    kind: str
+    label: str
+    metadata: NotRequired[dict[str, Any]]
+
+
+# ``from`` is a reserved word, so the edge shape needs the functional TypedDict syntax.
+EdgePayload = TypedDict(
+    "EdgePayload",
+    {
+        "id": str,
+        "kind": str,
+        "from": str,
+        "to": str,
+        "status": EdgeStatus,
+        "metadata": NotRequired[dict[str, Any]],
+    },
+)
+
+
+class GraphEvent(TypedDict):
+    """A single append-only event. ``node`` / ``edge`` carry full payloads for
+    ``*_created`` and partial payloads (``id`` plus changed fields) for ``*_updated``."""
+
+    id: str
+    runId: str
+    seq: int
+    ts: str
+    type: GraphEventType
+    actor: NotRequired[str]
+    node: NotRequired[dict[str, Any]]
+    edge: NotRequired[dict[str, Any]]
+
+
+@dataclass(frozen=True)
+class GraphState:
+    """The reduced live state: two id-keyed maps plus the last applied sequence."""
+
+    run_id: str
+    nodes: dict[str, NodePayload] = field(default_factory=dict)
+    edges: dict[str, EdgePayload] = field(default_factory=dict)
+    seq: int = 0

axiongraph_core/vocabulary.py

@@ -0,0 +1,79 @@
+"""Open-taxonomy machinery (spec D2). Core ships the machinery and a neutral example set;
+it never hard-codes a domain's vocabulary into the model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .types import GraphEvent
+
+
+@dataclass(frozen=True)
+class GraphVocabulary:
+    """A declared closed vocabulary of allowed node and edge kinds."""
+
+    node_kinds: frozenset[str]
+    edge_kinds: frozenset[str]
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """The typed result of :func:`validate`. ``validate`` never raises on bad input."""
+
+    ok: bool
+    reason: str | None = None
+
+
+def validate(event: GraphEvent, vocab: GraphVocabulary) -> ValidationResult:
+    """Reject ``*_created`` events whose kind is outside the supplied vocabulary."""
+    if event["type"] == "node_created":
+        kind = event["node"]["kind"]
+        if kind not in vocab.node_kinds:
+            return ValidationResult(ok=False, reason=f"unknown node kind: {kind}")
+    if event["type"] == "edge_created":
+        kind = event["edge"]["kind"]
+        if kind not in vocab.edge_kinds:
+            return ValidationResult(ok=False, reason=f"unknown edge kind: {kind}")
+    return ValidationResult(ok=True)
+
+
+# A neutral example vocabulary for docs and tests. Reveals no product domain.
+example_vocabulary = GraphVocabulary(
+    node_kinds=frozenset(
+        {
+            "human",
+            "agent",
+            "task",
+            "delegation",
+            "connector",
+            "tool",
+            "artifact",
+            "source",
+            "approval",
+            "policy_decision",
+            "budget_check",
+            "error",
+            "model_call",
+        }
+    ),
+    edge_kinds=frozenset(
+        {
+            "created_task",
+            "delegated_to",
+            "handoff_to",
+            "called_tool",
+            "called_connector",
+            "used_model",
+            "read_source",
+            "created_artifact",
+            "requested_approval",
+            "approved_by",
+            "denied_by",
+            "blocked_by_policy",
+            "blocked_by_budget",
+            "derived_from",
+            "cited_source",
+            "failed_with",
+        }
+    ),
+)

axiongraph_store_local/__init__.py

@@ -0,0 +1,9 @@
+"""axiongraph-store-local — zero-service reference GraphStore adapters (in-memory + sqlite).
+Published as the ``axiongraph.store_local`` subpath of the ``axiongraph`` package."""
+
+from __future__ import annotations
+
+from .in_memory import InMemoryStore
+from .sqlite import SqliteStore
+
+__all__ = ["InMemoryStore", "SqliteStore"]

axiongraph_store_local/in_memory.py

@@ -0,0 +1,31 @@
+"""A dict-backed GraphStore for tests and ephemeral runs (spec D4). Append-only and
+idempotent on ``(runId, seq)``. No durability; everything lives in process memory."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+
+from axiongraph_core import GraphEvent, GraphState, reduce_all
+
+
+class InMemoryStore:
+    """A :class:`~axiongraph_core.GraphStore` backed by per-run lists kept sorted by ``seq``."""
+
+    def __init__(self) -> None:
+        self._logs: dict[str, list[GraphEvent]] = {}
+
+    async def append(self, events: Sequence[GraphEvent]) -> None:
+        for event in events:
+            log = self._logs.setdefault(event["runId"], [])
+            if any(existing["seq"] == event["seq"] for existing in log):
+                continue  # idempotent on (runId, seq)
+            log.append(event)
+            log.sort(key=lambda candidate: candidate["seq"])
+
+    async def read_events(self, run_id: str, since_seq: int = 0) -> AsyncIterator[GraphEvent]:
+        for event in self._logs.get(run_id, []):
+            if event["seq"] > since_seq:
+                yield event
+
+    async def snapshot(self, run_id: str) -> GraphState:
+        return reduce_all(run_id, self._logs.get(run_id, []))

axiongraph_store_local/sqlite.py

@@ -0,0 +1,53 @@
+"""A durable single-file GraphStore backed by the stdlib ``sqlite3`` (spec D4). One ``events``
+table keyed on ``(run_id, seq)``; ``append`` uses ``INSERT OR IGNORE`` so it is idempotent on
+``(runId, seq)``. No server, survives restarts. Snapshots live-fold the log."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import AsyncIterator, Sequence
+from typing import cast
+
+from axiongraph_core import GraphEvent, GraphState, reduce_all
+
+
+class SqliteStore:
+    """A :class:`~axiongraph_core.GraphStore` persisted to a single SQLite database file."""
+
+    def __init__(self, location: str = ":memory:") -> None:
+        """``location`` is a file path, or ``":memory:"`` (default) for an ephemeral database."""
+        self._db = sqlite3.connect(location)
+        self._db.execute(
+            "CREATE TABLE IF NOT EXISTS events ("
+            "  run_id  TEXT    NOT NULL,"
+            "  seq     INTEGER NOT NULL,"
+            "  payload TEXT    NOT NULL,"
+            "  PRIMARY KEY (run_id, seq)"
+            ")"
+        )
+
+    async def append(self, events: Sequence[GraphEvent]) -> None:
+        self._db.executemany(
+            "INSERT OR IGNORE INTO events (run_id, seq, payload) VALUES (?, ?, ?)",
+            [(event["runId"], event["seq"], json.dumps(event)) for event in events],
+        )
+        self._db.commit()
+
+    async def read_events(self, run_id: str, since_seq: int = 0) -> AsyncIterator[GraphEvent]:
+        rows = self._db.execute(
+            "SELECT payload FROM events WHERE run_id = ? AND seq > ? ORDER BY seq",
+            (run_id, since_seq),
+        ).fetchall()
+        for (payload,) in rows:
+            yield cast(GraphEvent, json.loads(payload))
+
+    async def snapshot(self, run_id: str) -> GraphState:
+        rows = self._db.execute(
+            "SELECT payload FROM events WHERE run_id = ? ORDER BY seq", (run_id,)
+        ).fetchall()
+        return reduce_all(run_id, [cast(GraphEvent, json.loads(payload)) for (payload,) in rows])
+
+    def close(self) -> None:
+        """Release the underlying database handle. Not part of the ``GraphStore`` port."""
+        self._db.close()