langgraph-ledger 0.2.0__py3-none-any.whl

langgraph_ledger/__init__.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""Public API of langgraph-ledger."""
+from __future__ import annotations
+
+from .analysis import analyze_log
+from .callbacks import DshTraceCallbackHandler
+from .checkpointer import TracingCheckpointSaver
+from .dag import RunDAG, build_dag, build_dag_from_file
+from .events import EVENT_KINDS, FORMAT_VERSION
+from .hashing import (canonical_json, checkpoint_label, event_id, sha256_hex,
+                      tool_call_label)
+from .recorder import (TracePayloadError, TraceRecorder, active_recorder,
+                       bind_recorder, current_recorder, emit_event, read_log,
+                       recorder_for)
+from .repair import close_orphaned_run, find_orphaned_runs, repair_all
+from .replay import ReplayError, replay_messages
+from .rollback import find_checkpoint_by_label, fork_thread, time_travel_config
+from .verify import VerifyReport, verify_log, verify_thread
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    # recording
+    "TraceRecorder", "TracePayloadError", "bind_recorder", "current_recorder",
+    "active_recorder", "emit_event", "read_log", "recorder_for",
+    # integration
+    "TracingCheckpointSaver", "DshTraceCallbackHandler",
+    # labels / hashing
+    "canonical_json", "sha256_hex", "event_id", "tool_call_label",
+    "checkpoint_label", "EVENT_KINDS", "FORMAT_VERSION",
+    # dag / rollback / audit
+    "RunDAG", "build_dag", "build_dag_from_file",
+    "fork_thread", "time_travel_config", "find_checkpoint_by_label",
+    "verify_log", "verify_thread", "VerifyReport", "analyze_log",
+    # crash recovery / replay
+    "find_orphaned_runs", "close_orphaned_run", "repair_all",
+    "replay_messages", "ReplayError",
+]

langgraph_ledger/__main__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""Enable `python -m langgraph_ledger <command>`."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

langgraph_ledger/analysis.py

@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+"""Failure analysis over a recorded log.
+
+Because every tool call carries a content-addressed label, exact-repeat loops
+(the agent calling the same tool with the same input over and over) fall out
+for free. Combined with error events and node timings this gives a compact
+first-stop failure report:
+
+    python -m langgraph_ledger analyze <log.jsonl>
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import events as ev
+from .recorder import read_log
+
+__all__ = ["analyze_log"]
+
+
+def analyze_log(path: str | Path) -> dict[str, Any]:
+    """Summarize one thread log: counts, errors, loops, timeline, checkpoints."""
+    by_kind: dict[str, int] = {}
+    errors: list[dict[str, Any]] = []
+    tool_labels: dict[str, dict[str, Any]] = {}
+    checkpoints = 0
+    interrupted_runs = 0
+    models: dict[str, int] = {}
+    node_ms: dict[str, int] = {}
+    first_ts: str | None = None
+    last_ts: str | None = None
+    unknown: dict[str, int] = {}
+
+    prev_call_label: str | None = None
+    streaks: list[dict[str, Any]] = []
+    streak: dict[str, Any] | None = None
+
+    for e in read_log(path):
+        kind = str(e.get("kind") or "")
+        payload = e.get("payload") or {}
+        seq = e.get("seq")
+        first_ts = first_ts or e.get("ts")
+        last_ts = e.get("ts") or last_ts
+        if kind in ev.EVENT_KINDS:
+            by_kind[kind] = by_kind.get(kind, 0) + 1
+        else:
+            unknown[kind] = unknown.get(kind, 0) + 1
+
+        if kind == ev.KIND_TOOL_CALL:
+            label = str(payload.get("label") or "")
+            name = str(payload.get("name") or "")
+            slot = tool_labels.setdefault(label, {"name": name, "count": 0, "seqs": []})
+            slot["count"] += 1
+            slot["seqs"].append(seq)
+            if label == prev_call_label:
+                if streak is None:
+                    streak = {"label": label, "name": name, "start_seq": seq, "length": 2}
+                else:
+                    streak["length"] += 1
+            else:
+                if streak is not None:
+                    streaks.append(streak)
+                    streak = None
+            prev_call_label = label
+        elif kind == ev.KIND_TOOL_RESULT:
+            if not payload.get("ok"):
+                errors.append({"seq": seq, "kind": kind,
+                               "name": payload.get("name"),
+                               "error": payload.get("error")})
+        elif kind == ev.KIND_LLM_CALL and payload.get("error"):
+            errors.append({"seq": seq, "kind": kind, "node": payload.get("node"),
+                           "error": payload.get("error")})
+        if kind == ev.KIND_LLM_CALL and payload.get("model"):
+            m = str(payload["model"])
+            models[m] = models.get(m, 0) + 1
+        elif kind == ev.KIND_NODE_END and not payload.get("ok", True):
+            errors.append({"seq": seq, "kind": kind, "run_id": payload.get("run_id"),
+                           "error": payload.get("error")})
+        if kind == ev.KIND_NODE_END and payload.get("node"):
+            node = str(payload["node"])
+            node_ms[node] = node_ms.get(node, 0) + int(payload.get("ms") or 0)
+        elif kind == ev.KIND_RUN_END and payload.get("status") == "interrupted":
+            interrupted_runs += 1
+        elif kind == ev.KIND_ERROR:
+            errors.append({"seq": seq, "kind": kind, "where": payload.get("where"),
+                           "error": payload.get("error")})
+        elif kind == ev.KIND_STATE_SNAPSHOT:
+            checkpoints += 1
+            prev_call_label = None
+
+    if streak is not None:
+        streaks.append(streak)
+
+    loops = [{"label": k, "name": v["name"], "count": v["count"], "seqs": v["seqs"]}
+             for k, v in tool_labels.items() if v["count"] > 1]
+
+    return {
+        "log": str(path),
+        "events": sum(by_kind.values()) + sum(unknown.values()),
+        "by_kind": by_kind,
+        "unknown_kinds": unknown,
+        "checkpoints": checkpoints,
+        "interrupted_runs": interrupted_runs,
+        "models": models,
+        "node_time_ms": node_ms,
+        "errors": errors,
+        "error_count": len(errors),
+        "repeated_tool_calls": loops,
+        "consecutive_repeat_streaks": streaks,
+        "first_ts": first_ts,
+        "last_ts": last_ts,
+    }

langgraph_ledger/callbacks.py

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""LangChain/LangGraph callback handler that feeds the trace recorder.
+
+Attach to any LangGraph run:
+
+    graph.invoke(input, config={**config, "callbacks": [DshTraceCallbackHandler()]})
+
+LangChain propagates callbacks into every node, LLM call and tool call, so a
+single handler sees the whole run. Node boundaries are recognized through
+LangGraph's ``langgraph_node`` metadata; LLM/tool activity is paired by run id
+— the tool *result* carries the same content label as its call, not just a
+run-id echo.
+
+``record_full=True`` opts into persisting full prompt/response/input/output
+text alongside the digests (required for replay). Default off: digests only.
+
+All emit calls are fail-soft unless the recorder is strict: tracing never
+breaks the run.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+from uuid import UUID
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+from . import events as ev
+from .hashing import tool_call_label
+from .recorder import current_recorder
+
+__all__ = ["DshTraceCallbackHandler"]
+
+
+class DshTraceCallbackHandler(BaseCallbackHandler):
+    """Emit dsh-style trace events for node / LLM / tool activity."""
+
+    def __init__(self, recorder: Any = None, *, record_full: bool = False) -> None:
+        super().__init__()
+        #: Optional explicit recorder; falls back to the context-bound one.
+        self.recorder = recorder
+        #: Opt-in: persist full text next to digests (replay prerequisite).
+        self.record_full = bool(record_full)
+        self._starts: dict[str, float] = {}
+        self._llm_open: dict[str, dict[str, Any]] = {}
+        #: run_id -> {label, name, node} so the result can echo the call's label
+        self._tool_open: dict[str, dict[str, Any]] = {}
+        #: run_id -> node name, so node/end keeps its identity
+        self._node_open: dict[str, str] = {}
+        #: run_id -> {"steps": int} for the top-level graph run (run brackets —
+        #: the crash-recovery anchor: an unclosed run/start means "died here")
+        self._run_open: dict[str, dict[str, Any]] = {}
+
+    # -- plumbing --------------------------------------------------------------
+
+    def _rec(self) -> Any:
+        return self.recorder if self.recorder is not None else current_recorder()
+
+    def _emit(self, kind: str, payload: Any) -> bool:
+        rec = self._rec()
+        return rec.emit(kind, payload) if rec is not None else False
+
+    @staticmethod
+    def _node(metadata: dict | None) -> str:
+        return str((metadata or {}).get("langgraph_node") or "")
+
+    @staticmethod
+    def _model_of(serialized: dict | None, metadata: dict | None,
+                  llm_output: dict | None = None) -> str:
+        """Best-effort model identity: langsmith metadata → serialized → llm_output."""
+        for source in ((metadata or {}).get("ls_model_name"),
+                       (serialized or {}).get("name"),
+                       (serialized or {}).get("id", [None])[-1]
+                       if isinstance((serialized or {}).get("id"), list) else None,
+                       (llm_output or {}).get("model_name")):
+            if source:
+                return str(source)
+        return ""
+
+    def _mark(self, run_id: UUID) -> None:
+        self._starts[str(run_id)] = time.monotonic()
+
+    def _ms_since(self, run_id: UUID) -> int:
+        start = self._starts.pop(str(run_id), None)
+        return int((time.monotonic() - start) * 1000) if start is not None else 0
+
+    # -- node boundaries (LangGraph chain runs carrying langgraph_node) ---------
+
+    def on_chain_start(self, serialized: dict | None, inputs: Any, *,
+                       run_id: UUID, parent_run_id: UUID | None = None,
+                       metadata: dict | None = None, **kwargs: Any) -> None:
+        node = self._node(metadata)
+        if not node:
+            if parent_run_id is None:
+                # the top-level graph invocation — open a run bracket
+                self._mark(run_id)
+                self._run_open[str(run_id)] = {"steps": 0}
+                self._emit(ev.KIND_RUN_START, ev.run_start_payload(
+                    graph=str(kwargs.get("name") or "")))
+            return
+        self._mark(run_id)
+        self._node_open[str(run_id)] = node
+        self._emit(ev.KIND_NODE_START, ev.node_boundary_payload(node=node, run_id=str(run_id)))
+
+    def _close_run(self, run_id: UUID, *, status: str, error: str = "") -> None:
+        opened = self._run_open.pop(str(run_id), None)
+        if opened is None:
+            return
+        ms = self._ms_since(run_id)
+        self._emit(ev.KIND_RUN_END, ev.run_end_payload(
+            status=status, error=error, steps=opened["steps"], ms=ms))
+
+    def _close_node(self, run_id: UUID, *, ok: bool, error: str = "") -> None:
+        node = self._node_open.pop(str(run_id), None)
+        if node is None:
+            return
+        ms = self._ms_since(run_id)
+        payload = {**ev.node_boundary_payload(node=node, run_id=str(run_id)),
+                   "ms": ms, "ok": ok}
+        if error:
+            payload["error"] = error
+        self._emit(ev.KIND_NODE_END, payload)
+        for opened in self._run_open.values():
+            opened["steps"] += 1
+
+    def on_chain_end(self, outputs: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        if str(run_id) in self._run_open:
+            self._close_run(run_id, status="completed")
+            return
+        self._close_node(run_id, ok=True)
+
+    def on_chain_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        if str(run_id) in self._run_open:
+            self._close_run(run_id, status="error",
+                            error=f"{type(error).__name__}: {error}")
+            return
+        self._close_node(run_id, ok=False, error=f"{type(error).__name__}: {error}")
+
+    # -- LLM calls ----------------------------------------------------------------
+
+    def on_llm_start(self, serialized: dict | None, prompts: list[str], *,
+                     run_id: UUID, metadata: dict | None = None, **kwargs: Any) -> None:
+        self._mark(run_id)
+        self._llm_open[str(run_id)] = {
+            "text": "\n".join(prompts),
+            "model": self._model_of(serialized, metadata),
+            "node": self._node(metadata),
+        }
+
+    def on_chat_model_start(self, serialized: dict | None, messages: Any, *,
+                            run_id: UUID, metadata: dict | None = None, **kwargs: Any) -> None:
+        self._mark(run_id)
+        flat = "\n".join(f"{getattr(m, 'type', '?')}: {getattr(m, 'content', m)}"
+                         for batch in (messages or []) for m in (batch or []))
+        self._llm_open[str(run_id)] = {
+            "text": flat,
+            "model": self._model_of(serialized, metadata),
+            "node": self._node(metadata),
+        }
+
+    def on_llm_end(self, response: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        ms = self._ms_since(run_id)
+        info = self._llm_open.pop(str(run_id), {})
+        text = ""
+        usage = None
+        try:
+            text = "\n".join(getattr(g, "text", "") or str(getattr(g, "message", ""))
+                             for gen in (response.generations or [])
+                             for g in (gen or []))
+            usage = (response.llm_output or {}).get("token_usage")
+            if not info.get("model"):
+                info["model"] = self._model_of(None, None, response.llm_output)
+        except AttributeError:
+            pass
+        self._emit(ev.KIND_LLM_CALL, ev.llm_call_payload(
+            node=info.get("node", ""), model=info.get("model", ""),
+            prompt=info.get("text", ""), response=text, ms=ms, usage=usage,
+            record_full=self.record_full))
+
+    def on_llm_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        ms = self._ms_since(run_id)
+        info = self._llm_open.pop(str(run_id), {})
+        self._emit(ev.KIND_LLM_CALL, ev.llm_call_payload(
+            node=info.get("node", ""), model=info.get("model", ""),
+            prompt=info.get("text", ""), response="", ms=ms,
+            error=f"{type(error).__name__}: {error}",
+            record_full=self.record_full))
+
+    # -- tool calls (hash-labeled; result echoes the call's label) -----------------
+
+    def on_tool_start(self, serialized: dict | None, input_str: str, *,
+                      run_id: UUID, parent_run_id: UUID | None = None,
+                      metadata: dict | None = None, **kwargs: Any) -> None:
+        self._mark(run_id)
+        name = str((serialized or {}).get("name") or "")
+        tool_input = kwargs.get("inputs", input_str)
+        canonical_input = tool_input if isinstance(tool_input, (dict, list)) else input_str
+        label = tool_call_label(name, canonical_input)
+        self._tool_open[str(run_id)] = {"label": label, "name": name,
+                                        "node": self._node(metadata)}
+        self._emit(ev.KIND_TOOL_CALL, ev.tool_call_payload(
+            label=label, node=self._node(metadata), name=name,
+            tool_input=canonical_input, run_id=str(run_id),
+            parent_run_id=str(parent_run_id) if parent_run_id else "",
+            record_full=self.record_full))
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        ms = self._ms_since(run_id)
+        opened = self._tool_open.pop(str(run_id), {})
+        self._emit(ev.KIND_TOOL_RESULT, ev.tool_result_payload(
+            label=opened.get("label", ""), name=opened.get("name", ""),
+            ok=True, ms=ms, output=output, run_id=str(run_id),
+            record_full=self.record_full))
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        ms = self._ms_since(run_id)
+        opened = self._tool_open.pop(str(run_id), {})
+        self._emit(ev.KIND_TOOL_RESULT, ev.tool_result_payload(
+            label=opened.get("label", ""), name=opened.get("name", ""),
+            ok=False, ms=ms, error=f"{type(error).__name__}: {error}",
+            run_id=str(run_id), record_full=self.record_full))

langgraph_ledger/checkpointer.py

@@ -0,0 +1,213 @@
+# -*- coding: utf-8 -*-
+"""A drop-in wrapper that adds dsh-grade traceability to ANY LangGraph checkpointer.
+
+Wraps an existing ``BaseCheckpointSaver`` (in-memory, SQLite, Postgres, Redis,
+…) and, while passing every call through unchanged:
+
+- hashes every checkpoint on write (content-addressed ``cp_*`` label + full
+  sha256) and records its parent — this is the checkpoint DAG edge;
+- records pending writes per task with digested values;
+- emits all of it into the hash-chained append-only event log.
+
+Behavioral contract of the wrapped saver is preserved exactly: return values,
+exceptions and ordering all pass through. Trace failures are fail-soft and
+never reach the caller.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, AsyncIterator, Iterator, Sequence
+
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    ChannelProtocol,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    RunnableConfig,
+    SerializerProtocol,
+)
+
+from . import events as ev
+from .hashing import checkpoint_label, sha256_hex
+from .recorder import TraceRecorder, current_recorder, recorder_for
+
+__all__ = ["TracingCheckpointSaver", "normalized_checkpoint_digest"]
+
+
+def normalized_checkpoint_digest(serde: SerializerProtocol,
+                                 checkpoint: Checkpoint) -> tuple[str, str]:
+    """(full sha256 hex, cp_* label) over the *roundtrip-normalized* checkpoint.
+
+    The object handed to ``put`` may contain fields that do not survive
+    serialization. Hashing ``dumps(loads(dumps(cp)))`` makes the write-time
+    digest equal to the read-time digest — the property ``verify_thread``
+    relies on to prove no post-hoc drift.
+    """
+    try:
+        tag1, blob1 = serde.dumps_typed(checkpoint)
+        restored = serde.loads_typed((tag1, blob1))
+        tag2, blob2 = serde.dumps_typed(restored)
+        if isinstance(blob2, str):
+            blob2 = blob2.encode("utf-8")
+        return sha256_hex(tag2.encode() + b"\x00" + blob2), checkpoint_label(blob2)
+    except Exception:  # noqa: BLE001 — digest must never break a write
+        return "", ""
+
+
+def _cfg_ids(config: RunnableConfig) -> tuple[str, str, str | None]:
+    conf = (config or {}).get("configurable") or {}
+    return (str(conf.get("thread_id") or "anonymous"),
+            str(conf.get("checkpoint_ns") or ""),
+            conf.get("checkpoint_id"))
+
+
+class TracingCheckpointSaver(BaseCheckpointSaver):
+    """Wrap any BaseCheckpointSaver with hash-labeled, hash-chained tracing."""
+
+    def __init__(self, inner: BaseCheckpointSaver, *,
+                 trace_root: str | Path,
+                 recorder: TraceRecorder | None = None,
+                 enabled: bool = True) -> None:
+        super().__init__(serde=inner.serde)
+        self.inner = inner
+        self.trace_root = Path(trace_root)
+        self._default_recorder = recorder
+        self.enabled = bool(enabled)
+
+    # -- recorder resolution ------------------------------------------------------
+
+    def recorder_for(self, thread_id: str) -> TraceRecorder:
+        return recorder_for(self.trace_root, thread_id, enabled=self.enabled)
+
+    def _rec_for(self, thread_id: str) -> TraceRecorder | None:
+        bound = self._default_recorder or current_recorder()
+        if bound is not None:
+            return bound if bound.enabled else None
+        if not self.enabled:
+            return None
+        return self.recorder_for(thread_id)
+
+    # -- checkpoint hashing ---------------------------------------------------------
+
+    def _checkpoint_digest(self, checkpoint: Checkpoint) -> tuple[str, str]:
+        """(full sha256 hex, short cp_* label) — roundtrip-normalized."""
+        return normalized_checkpoint_digest(self.serde, checkpoint)
+
+    def _emit_snapshot(self, out_config: RunnableConfig,
+                       metadata: CheckpointMetadata) -> None:
+        """Hash the *stored* form: re-read the just-written checkpoint and digest
+        its reconstruction — the same object verify_thread will see later."""
+        thread_id, _ns, _parent = _cfg_ids(out_config)
+        rec = self._rec_for(thread_id)
+        if rec is None:
+            return
+        tup = self.inner.get_tuple(out_config)
+        if tup is None:
+            return
+        full, label = self._checkpoint_digest(tup.checkpoint)
+        md = dict(metadata or {})
+        parent_id = (tup.parent_config or {}).get("configurable", {}).get("checkpoint_id")
+        rec.emit(ev.KIND_STATE_SNAPSHOT, ev.state_snapshot_payload(
+            checkpoint_id=str(tup.checkpoint.get("id") or ""),
+            checkpoint_sha256=full, label=label,
+            parent_checkpoint_id=str(parent_id) if parent_id else None,
+            step=md.get("step"), source=str(md.get("source") or "")))
+
+    # -- pass-through with tracing ---------------------------------------------------
+
+    def put(self, config: RunnableConfig, checkpoint: Checkpoint,
+            metadata: CheckpointMetadata, new_versions: Any) -> RunnableConfig:
+        out = self.inner.put(config, checkpoint, metadata, new_versions)
+        try:
+            self._emit_snapshot(out, metadata)
+        except Exception:  # noqa: BLE001 — observation never breaks the run
+            pass
+        return out
+
+    def _trace_writes(self, config: RunnableConfig, writes: Sequence[tuple[str, Any]],
+                      task_id: str) -> None:
+        try:
+            thread_id, _ns, checkpoint_id = _cfg_ids(config)
+            rec = self._rec_for(thread_id)
+            if rec is not None:
+                digested = []
+                for channel, value in writes:
+                    try:
+                        _t, blob = self.serde.dumps_typed(value)
+                        digest = sha256_hex(blob if isinstance(blob, bytes)
+                                            else str(blob).encode("utf-8"))
+                        size = len(blob)
+                    except Exception:  # noqa: BLE001
+                        digest, size = "", 0
+                    digested.append({"channel": str(channel), "sha256": digest,
+                                     "size": int(size)})
+                rec.emit(ev.KIND_CHECKPOINT_WRITES, ev.checkpoint_writes_payload(
+                    checkpoint_id=str(checkpoint_id) if checkpoint_id else None,
+                    task_id=task_id, writes=digested))
+        except Exception:  # noqa: BLE001
+            pass
+
+    def put_writes(self, config: RunnableConfig, writes: Sequence[tuple[str, Any]],
+                   task_id: str, task_path: str = "") -> None:
+        self.inner.put_writes(config, writes, task_id, task_path)
+        self._trace_writes(config, writes, task_id)
+
+    # -- pure delegation ---------------------------------------------------------------
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        return self.inner.get_tuple(config)
+
+    def list(self, config: RunnableConfig | None, *,
+             filter: dict | None = None, before: RunnableConfig | None = None,
+             limit: int | None = None) -> Iterator[CheckpointTuple]:
+        yield from self.inner.list(config, filter=filter, before=before, limit=limit)
+
+    def delete_thread(self, thread_id: str) -> None:
+        self.inner.delete_thread(thread_id)
+
+    # -- async: delegate to the inner saver's async path --------------------------------
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        return await self.inner.aget_tuple(config)
+
+    async def alist(self, config: RunnableConfig | None, *,
+                    filter: dict | None = None, before: RunnableConfig | None = None,
+                    limit: int | None = None) -> AsyncIterator[CheckpointTuple]:
+        async for tup in self.inner.alist(config, filter=filter, before=before, limit=limit):
+            yield tup
+
+    async def aput(self, config: RunnableConfig, checkpoint: Checkpoint,
+                   metadata: CheckpointMetadata, new_versions: Any) -> RunnableConfig:
+        out = await self.inner.aput(config, checkpoint, metadata, new_versions)
+        try:
+            tup = await self.inner.aget_tuple(out)
+            if tup is not None:
+                thread_id, _ns, _p = _cfg_ids(out)
+                rec = self._rec_for(thread_id)
+                if rec is not None:
+                    full, label = self._checkpoint_digest(tup.checkpoint)
+                    md = dict(metadata or {})
+                    parent_id = (tup.parent_config or {}).get(
+                        "configurable", {}).get("checkpoint_id")
+                    rec.emit(ev.KIND_STATE_SNAPSHOT, ev.state_snapshot_payload(
+                        checkpoint_id=str(tup.checkpoint.get("id") or ""),
+                        checkpoint_sha256=full, label=label,
+                        parent_checkpoint_id=str(parent_id) if parent_id else None,
+                        step=md.get("step"), source=str(md.get("source") or "")))
+        except Exception:  # noqa: BLE001
+            pass
+        return out
+
+    async def aput_writes(self, config: RunnableConfig, writes: Sequence[tuple[str, Any]],
+                          task_id: str, task_path: str = "") -> None:
+        await self.inner.aput_writes(config, writes, task_id, task_path)
+        self._trace_writes(config, writes, task_id)
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        await self.inner.adelete_thread(thread_id)
+
+    # -- convenience -----------------------------------------------------------------------
+
+    def register_channel(self, channel: ChannelProtocol, key: str) -> None:
+        self.inner.register_channel(channel, key)

langgraph_ledger/cli.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""CLI: verify / analyze / dag / repair / replay a recorded trace log.
+
+    python -m langgraph_ledger verify  <thread.jsonl>
+    python -m langgraph_ledger analyze <thread.jsonl>
+    python -m langgraph_ledger dag     <thread.jsonl> [--mermaid]
+    python -m langgraph_ledger repair  <thread.jsonl | trace-root/>
+    python -m langgraph_ledger replay  <thread.jsonl>
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .analysis import analyze_log
+from .dag import build_dag_from_file
+from .repair import close_orphaned_run, repair_all
+from .replay import replay_messages
+from .verify import verify_log
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="langgraph_ledger",
+                                     description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("verify", "analyze", "dag", "replay"):
+        p = sub.add_parser(name)
+        p.add_argument("log", help="path to a thread .jsonl trace log")
+        if name == "dag":
+            p.add_argument("--mermaid", action="store_true",
+                           help="print a Mermaid flowchart instead of JSON")
+    p = sub.add_parser("repair", help="close crash-orphaned runs "
+                       "(a single log or a whole trace-root directory)")
+    p.add_argument("target", help="a thread .jsonl log or a trace-root directory")
+    args = parser.parse_args(argv)
+
+    if args.command == "repair":
+        target = Path(args.target)
+        if target.is_dir():
+            summary = repair_all(target)
+        elif target.is_file():
+            summary = close_orphaned_run(target)
+        else:
+            print(f"target not found: {target}", file=sys.stderr)
+            return 2
+        print(json.dumps(summary, ensure_ascii=False, indent=2))
+        return 0
+
+    if not Path(args.log).is_file():
+        print(f"log not found: {args.log}", file=sys.stderr)
+        return 2
+
+    if args.command == "verify":
+        report = verify_log(args.log)
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return 0 if report else 1
+    if args.command == "analyze":
+        print(json.dumps(analyze_log(args.log), ensure_ascii=False, indent=2))
+        return 0
+    if args.command == "replay":
+        print(json.dumps(replay_messages(args.log), ensure_ascii=False, indent=2))
+        return 0
+    dag = build_dag_from_file(args.log)
+    print(dag.to_mermaid() if args.mermaid else json.dumps(dag.to_dict(), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())