checkpoint: spec v0.8 checkpointing (proposal 0008) — phase 5

Land the checkpointing capability. Adds `openarmature.checkpoint` with
the typed Checkpointer Protocol, CheckpointRecord/NodePosition/
CheckpointSummary shapes, the three §10.10 error categories, and two
reference backends — InMemoryCheckpointer and SQLiteCheckpointer (WAL
mode, upsert retention, pickle|json serialization knob).

Engine integration: GraphBuilder.with_checkpointer registers a backend
at compile time; CompiledGraph.invoke gains correlation_id and
resume_invocation kwargs. Saves fire after every successful merge for
outermost-graph and subgraph-internal nodes, gated off inside fan-out
instances (§10.7 atomic-restart). Resume loads the record, restores
outermost state from parent_states[0], threads any deeper saved
states into the matching subgraph descents, and fast-forwards past
nodes whose namespace matches saved completed_positions.

Bumps the spec submodule to v0.8.2 — picks up fixture 019 (subgraph
depth-3 regression) and the fixture 029 namespace convention fix.

Test coverage: 6 of 8 §10 conformance fixtures pass; 027 and 028 are
deferred (need resume-aware test seams in the conformance adapter;
engine paths covered by unit tests). 23 unit tests cover backend
round-trip + durability + serialization mismatch, error categories,
schema_version round-trip, default-off behavior, the fan-out save
gate, inner-node parent_states preservation, and correlation_id
preservation across resume.

Author: chris-colinsky

openarmature-spec

@@ -0,0 +1,45 @@
+"""openarmature.checkpoint — checkpointing capability per spec proposal 0008.
+
+Public surface: the typed :class:`Checkpointer` Protocol,
+:class:`CheckpointRecord` / :class:`NodePosition` /
+:class:`CheckpointSummary` shapes, the three §10.10 error categories,
+and two reference backends (in-memory and SQLite).
+
+Users register a backend at graph build time via
+``GraphBuilder.with_checkpointer(...)``; the engine then fires saves
+at every ``completed`` event for outermost-graph nodes and
+subgraph-internal nodes per §10.3, and ``invoke(resume_invocation=X)``
+loads + restores from a prior record per §10.4.
+"""
+
+from .backends import InMemoryCheckpointer, SerializationMode, SQLiteCheckpointer
+from .errors import (
+    CheckpointError,
+    CheckpointNotFound,
+    CheckpointRecordInvalid,
+    CheckpointSaveFailed,
+)
+from .protocol import (
+    CHECKPOINT_SCHEMA_VERSION,
+    Checkpointer,
+    CheckpointFilter,
+    CheckpointRecord,
+    CheckpointSummary,
+    NodePosition,
+)
+
+__all__ = [
+    "CHECKPOINT_SCHEMA_VERSION",
+    "CheckpointError",
+    "CheckpointFilter",
+    "CheckpointNotFound",
+    "CheckpointRecord",
+    "CheckpointRecordInvalid",
+    "CheckpointSaveFailed",
+    "CheckpointSummary",
+    "Checkpointer",
+    "InMemoryCheckpointer",
+    "NodePosition",
+    "SQLiteCheckpointer",
+    "SerializationMode",
+]

src/openarmature/checkpoint/__init__.py

@@ -0,0 +1,22 @@
+"""Concrete Checkpointer backends.
+
+Each backend satisfies the
+:class:`openarmature.checkpoint.Checkpointer` Protocol. The current
+catalog ships :class:`InMemoryCheckpointer` (no durability; tests +
+short-lived runs) and :class:`SQLiteCheckpointer` (single-host
+durable). Sibling-package adapters for Temporal, DBOS, Restate, and
+Redis are informative per spec §10.11 — not specified here.
+
+Users typically import from the package root::
+
+    from openarmature.checkpoint import InMemoryCheckpointer, SQLiteCheckpointer
+"""
+
+from .memory import InMemoryCheckpointer
+from .sqlite import SerializationMode, SQLiteCheckpointer
+
+__all__ = [
+    "InMemoryCheckpointer",
+    "SQLiteCheckpointer",
+    "SerializationMode",
+]

src/openarmature/checkpoint/backends/__init__.py

@@ -0,0 +1,64 @@
+"""In-memory Checkpointer (spec §10.11).
+
+Keeps records in a Python ``dict`` keyed by ``invocation_id``. NOT
+durable across process crashes — useful for tests, short-lived runs,
+and development. Accepts any state shape (the dict holds the
+:class:`CheckpointRecord` directly; nothing is serialized).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterable
+
+from ..protocol import CheckpointFilter, CheckpointRecord, CheckpointSummary
+
+
+class InMemoryCheckpointer:
+    """Dict-backed Checkpointer.
+
+    **Durability:** none. Records live for the lifetime of this
+    instance only; restarting the process loses everything.
+    Appropriate for unit tests, the dev loop, and short-lived
+    in-process pipelines that don't need crash recovery.
+
+    **State shape:** any. The record is held by reference, so the
+    Pydantic state instance the engine produces is what comes back
+    from :meth:`load` — no serialization round-trip. (This is the
+    feature: tests can assert on the saved state's identity.)
+    """
+
+    def __init__(self) -> None:
+        self._records: dict[str, CheckpointRecord] = {}
+        self._lock = asyncio.Lock()
+
+    async def save(self, invocation_id: str, record: CheckpointRecord) -> None:
+        async with self._lock:
+            self._records[invocation_id] = record
+
+    async def load(self, invocation_id: str) -> CheckpointRecord | None:
+        async with self._lock:
+            return self._records.get(invocation_id)
+
+    async def list(self, filter: CheckpointFilter | None = None) -> Iterable[CheckpointSummary]:
+        async with self._lock:
+            records = list(self._records.values())
+        summaries = [
+            CheckpointSummary(
+                invocation_id=r.invocation_id,
+                correlation_id=r.correlation_id,
+                last_saved_at=r.last_saved_at,
+                completed_node_count=len(r.completed_positions),
+            )
+            for r in records
+        ]
+        if filter is None or filter.correlation_id is None:
+            return summaries
+        return [s for s in summaries if s.correlation_id == filter.correlation_id]
+
+    async def delete(self, invocation_id: str) -> None:
+        async with self._lock:
+            self._records.pop(invocation_id, None)
+
+
+__all__ = ["InMemoryCheckpointer"]