# Source Trace: Portable Durable Agent Graph Runtime

Pinned source: `langchain-ai/langgraph` at `076e2a3627206f5a1aef573aaca4a01e5af897ca`.

| Subsystem | Evidence | Mapping Claim |
|---|---|---|
| StateGraph state schema | `libs/langgraph/langgraph/graph/state.py:130-144` says nodes communicate by shared state, node signature is `State -> Partial<State>`, state keys may have reducers, and builder must be compiled before execution. | OBSERVED(libs/langgraph/langgraph/graph/state.py:130-144): A clean-room runtime should expose a typed state schema and node functions that return partial state updates. |
| State/input/output/context schema | `libs/langgraph/langgraph/graph/state.py:215-269` initializes `state_schema`, default `input_schema`/`output_schema`, optional `context_schema`, schemas, channels, managed values, nodes, edges, branches. | OBSERVED(libs/langgraph/langgraph/graph/state.py:215-269): Builder state tracks node registry, edge registry, branch registry, schemas, channels, and compile state. |
| Schema to channels | `libs/langgraph/langgraph/graph/state.py:342-365` calls `_get_channels(schema)`, rejects managed channels in input/output schemas, and stores channels by key. | OBSERVED(libs/langgraph/langgraph/graph/state.py:342-365): State keys become channels. Managed state is distinct from normal persisted channels. |
| Node defaults | `libs/langgraph/langgraph/graph/state.py:271-334` defines default retry, cache, error handler, and timeout policies; per-node options take precedence and defaults apply at compile time. | OBSERVED(libs/langgraph/langgraph/graph/state.py:271-334): Default policies exist, but clean-room Buildprint marks retry/cache/timeouts as optional or out of scope unless explicitly implemented. |
| Add node API | `libs/langgraph/langgraph/graph/state.py:375-441`, `:517-582`, `:662-735` document inferred or named node registration, metadata, retry/cache, destinations, and timeout. | OBSERVED(libs/langgraph/langgraph/graph/state.py:375-441): Builder accepts callable/runnable nodes and can infer names. |
| Add node validation | `libs/langgraph/langgraph/graph/state.py:751-907` warns after compile, rejects duplicate/reserved/invalid names, infers input schema and `Command[Literal[...]]` destinations, and stores a `StateNodeSpec`. | OBSERVED(libs/langgraph/langgraph/graph/state.py:751-907): Clean-room compile should reject duplicate/reserved node names and preserve declared input schema. |
| Directed edges | `libs/langgraph/langgraph/graph/state.py:915-967` adds directed edges, supports one start or multiple starts, rejects `END` as start and `START` as end, validates known nodes for multi-start edges. | OBSERVED(libs/langgraph/langgraph/graph/state.py:915-967): Edges are directed; multi-start edges wait for all starts. |
| Conditional edges | `libs/langgraph/langgraph/graph/state.py:969-1017` registers a condition runnable and optional path map; returned `END` stops execution; visualization is broad without path hints. | OBSERVED(libs/langgraph/langgraph/graph/state.py:969-1017): Conditional routing maps state/context-derived route labels to destination nodes or end. |
| Entrypoint/finish | `libs/langgraph/langgraph/graph/state.py:1066-1114` maps entrypoint to `START -> node`, conditional entrypoint to conditional edge from `START`, and finish point to `node -> END`. | OBSERVED(libs/langgraph/langgraph/graph/state.py:1066-1114): `START` and `END` are sentinel graph boundaries. |
| Validation | `libs/langgraph/langgraph/graph/state.py:1116-1162` validates known sources, requires at least one edge from `START`, validates branch targets, edge targets, and interrupt node names, then marks compiled. | OBSERVED(libs/langgraph/langgraph/graph/state.py:1116-1162): Compile must fail invalid graphs before runtime execution. |
| Compile | `libs/langgraph/langgraph/graph/state.py:1164-1219` documents compilation to `CompiledStateGraph`, Runnable support, checkpointer behavior, thread_id requirement, and pause/resume/replay memory. | OBSERVED(libs/langgraph/langgraph/graph/state.py:1164-1219): Builder compiles to an executable runtime; checkpointer is fully versioned short-term memory keyed by `thread_id`. |
| Compile construction | `libs/langgraph/langgraph/graph/state.py:1243-1388` validates graph, selects output and stream channels, applies defaults, constructs `CompiledStateGraph`, attaches nodes, edges, waiting edges, and branches. | OBSERVED(libs/langgraph/langgraph/graph/state.py:1243-1388): Compile lowers the builder into a Pregel-backed runtime with channels and attached edges/branches. |
| Compiled graph | `libs/langgraph/langgraph/graph/state.py:1391-1515` shows `CompiledStateGraph` extends `Pregel`; node attachment maps node outputs into channel writes and treats dict or `Command` as state updates. | OBSERVED(libs/langgraph/langgraph/graph/state.py:1391-1515): Compiled state graph is a Pregel runtime specialized for state update mapping. |
| Pregel concept | `libs/langgraph/langgraph/pregel/main.py:448-521` describes actors and channels, Bulk Synchronous Parallel steps, plan/execute/update phases, and notes Graph API compiles down to Pregel. | OBSERVED(libs/langgraph/langgraph/pregel/main.py:448-521): Runtime execution is step/superstep based with channel updates made visible next step. |
| Pregel protocol | `libs/langgraph/langgraph/pregel/protocol.py:47-105`, `:107-193`, `:195-231` define state access/update, sync/async stream, and sync invoke surfaces. | OBSERVED(libs/langgraph/langgraph/pregel/protocol.py:47-105): Executable runtime surface includes get/update state, invoke, stream, and async variants. |
| Runtime stream | `libs/langgraph/langgraph/pregel/main.py:2587-2695` documents `stream` input/config/context, interrupt controls, durability, subgraphs, and stream mode output shapes. | OBSERVED(libs/langgraph/langgraph/pregel/main.py:2587-2695): Stream is the primary event surface. |
| Invoke | `libs/langgraph/langgraph/pregel/main.py:3750-3849` documents `invoke`, same durability choices as stream, and return shape: latest output for `values`, chunks for other modes. | OBSERVED(libs/langgraph/langgraph/pregel/main.py:3750-3849): Invoke can be layered over stream. |
| Durability modes | `libs/langgraph/langgraph/types.py:87-93` and `libs/langgraph/langgraph/pregel/main.py:2676-2683` define `sync`, `async`, and `exit` persistence timing. | OBSERVED(libs/langgraph/langgraph/types.py:87-93): Durability is a runtime option. Buildprint selects simple synchronous/in-memory durability plus simulations. |
| Superstep task runner | `libs/langgraph/langgraph/pregel/_runner.py:135-188`, `:277-349` executes Pregel tasks concurrently, commits writes, yields output, interrupts/halts on failures, and waits for all done callbacks. | OBSERVED(libs/langgraph/langgraph/pregel/_runner.py:135-188): LangGraph has richer concurrency; clean-room scope should not claim Pregel performance or concurrency parity. |
| Loop state | `libs/langgraph/langgraph/pregel/_loop.py:155-260` tracks step, checkpointer, channels, pending writes, checkpoint config, checkpoint metadata, task map, status, and updated channels. | OBSERVED(libs/langgraph/langgraph/pregel/_loop.py:155-260): Runtime state includes current checkpoint, pending writes, tasks, and step status. |
| Pending writes persistence | `libs/langgraph/langgraph/pregel/_loop.py:448-490` extends in-memory pending writes and calls `checkpointer.put_writes` unless durability is `exit`. | OBSERVED(libs/langgraph/langgraph/pregel/_loop.py:448-490): Intermediate task writes may be persisted before checkpoint commit. |
| Pending write replay | `libs/langgraph/langgraph/pregel/_loop.py:715-729` restores successful channel writes from checkpoint pending writes, skipping control/error/interrupt/resume signals. | OBSERVED(libs/langgraph/langgraph/pregel/_loop.py:715-729): Recovery can keep successful writes from a failed/interrupted superstep. |
| State output mapping | `libs/langgraph/langgraph/pregel/_io.py:100-174` maps values and updates stream chunks from channel state and task writes. | OBSERVED(libs/langgraph/langgraph/pregel/_io.py:100-174): `values` are channel snapshots; `updates` are per-node write results. |
| Channel contract | `libs/langgraph/langgraph/channels/base.py:19-99` defines value/update/checkpoint types and an `update(values)` method called at the end of each step. | OBSERVED(libs/langgraph/langgraph/channels/base.py:19-99): State mutation is channel-mediated, not raw dict mutation. |
| LastValue channel | `libs/langgraph/langgraph/channels/last_value.py:20-67` stores last value and rejects multiple values per step, suggesting Annotated/reducer for concurrent updates. | OBSERVED(libs/langgraph/langgraph/channels/last_value.py:20-67): Default channel is single-writer-per-step. |
| Reducer channel | `libs/langgraph/langgraph/channels/binop.py:51-109` stores result of applying a binary operator to current value and each update. | OBSERVED(libs/langgraph/langgraph/channels/binop.py:51-109): Reducers aggregate multiple writes to a key. |
| Version tracking | `libs/langgraph/langgraph/pregel/_algo.py:261-345` updates `versions_seen`, channel versions, consumes triggers, applies writes, and returns updated channels. | OBSERVED(libs/langgraph/langgraph/pregel/_algo.py:261-345): Runtime uses channel versions and per-node versions seen for scheduling. |
| Stream modes | `libs/langgraph/langgraph/types.py:120-134` enumerates `values`, `updates`, `custom`, `messages`, `checkpoints`, `tasks`, and `debug`. | OBSERVED(libs/langgraph/langgraph/types.py:120-134): Buildprint should specify these modes, while message/tool streaming can use a deterministic local source or remain outside core. |
| Stream event payloads | `libs/langgraph/langgraph/types.py:142-209` defines task, task result, checkpoint task, and checkpoint payload shapes. | OBSERVED(libs/langgraph/langgraph/types.py:142-209): Events include task lifecycle and checkpoint state snapshots. |
| v3 stream run | `libs/langgraph/langgraph/pregel/main.py:3580-3635` and `libs/langgraph/langgraph/stream/run_stream.py:30-49`, `:158-189` describe experimental v3 `GraphRunStream`, values/messages projections, output, interrupted, and interrupts. | OBSERVED(libs/langgraph/langgraph/pregel/main.py:3580-3635): Buildprint can mention projection-style event stream as non-core unless implemented. |
| Checkpoint shape | `libs/checkpoint/langgraph/checkpoint/base/__init__.py:92-123` defines checkpoint fields: `v`, `id`, `ts`, `channel_values`, `channel_versions`, `versions_seen`, `updated_channels`. | OBSERVED(libs/checkpoint/langgraph/checkpoint/base/__init__.py:92-123): Clean-room checkpoint records state values and version metadata. |
| Checkpoint tuple | `libs/checkpoint/langgraph/checkpoint/base/__init__.py:139-147` defines `CheckpointTuple(config, checkpoint, metadata, parent_config, pending_writes)`. | OBSERVED(libs/checkpoint/langgraph/checkpoint/base/__init__.py:139-147): Restore/list APIs return checkpoint plus config, metadata, parent, and pending writes. |
| BaseCheckpointSaver | `libs/checkpoint/langgraph/checkpoint/base/__init__.py:176-209`, `:227-318`, `:417-509`, `:692-722` define saver purpose, `thread_id`, serde, sync/async get/list/put/put_writes/delete methods, next versions, and allowlist wrapper. | OBSERVED(libs/checkpoint/langgraph/checkpoint/base/__init__.py:176-209): Saver API is a contract. Buildprint implements only in-memory sync subset plus safety gate. |
| InMemorySaver | `libs/checkpoint/langgraph/checkpoint/memory/__init__.py:33-48`, `:68-83`, `:236-317`, `:427-510` stores checkpoints/writes/blobs in memory, fetches latest or by `checkpoint_id`, returns pending writes, and saves writes by task id. | OBSERVED(libs/checkpoint/langgraph/checkpoint/memory/__init__.py:33-48): In-memory saver is adequate evidence for portable testing, not production storage parity. |
| Thread/checkpoint config | `libs/checkpoint/langgraph/checkpoint/memory/__init__.py:250-316`, `:449-470`, `libs/checkpoint/langgraph/checkpoint/base/__init__.py:752-754` use `configurable.thread_id`, `checkpoint_ns`, and `checkpoint_id`. | OBSERVED(libs/checkpoint/langgraph/checkpoint/memory/__init__.py:250-316): Thread identity and checkpoint identity are config-level concepts. |
| Serializer warning | `libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py:82-95` warns not to use on untrusted objects; attacker-controlled checkpoint DB may trigger code execution; strict msgpack/allowlist can restrict deserialization. | OBSERVED(libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py:82-95): Buildprint must include a serializer safety gate and untrusted-data warning. |
| Serializer allowlist | `libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py:107-126`, `:566-629` configures permissive vs strict msgpack and blocks or warns for non-allowlisted types. | OBSERVED(libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py:107-126): Safety gate can be modeled as allowed type tags only. |
| Pickle risk | `libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py:278-310` uses pickle only when `pickle_fallback` is enabled. | OBSERVED(libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py:278-310): Buildprint should default to no pickle and test rejection of unsafe serializer modes. |
| Interrupt type | `libs/langgraph/langgraph/types.py:540-568` defines interrupt value/id. | OBSERVED(libs/langgraph/langgraph/types.py:540-568): Interrupts are resumable payloads with stable IDs. |
| State snapshot/tasks | `libs/langgraph/langgraph/types.py:587-651` defines `PregelTask` and `StateSnapshot` with values, next nodes, config, metadata, parent config, tasks, and pending interrupts. | OBSERVED(libs/langgraph/langgraph/types.py:587-651): Runtime should expose snapshots including next tasks and interrupts. |
| Send | `libs/langgraph/langgraph/types.py:654-743` sends a custom arg to a target node at next step; used in conditional edges for map-reduce style fanout. | OBSERVED(libs/langgraph/langgraph/types.py:654-743): `Send` is routing/task fanout payload, but full fanout can be simplified. |
| Command | `libs/langgraph/langgraph/types.py:748-798` supports graph target, state update, resume payloads, and goto node(s)/Send(s). | OBSERVED(libs/langgraph/langgraph/types.py:748-798): Command is the clean-room surface for update/resume/goto. |
| interrupt() | `libs/langgraph/langgraph/types.py:801-924` pauses with `GraphInterrupt`, requires checkpointer, resumes with `Command`, and re-executes node logic on resume. | OBSERVED(libs/langgraph/langgraph/types.py:801-924): Interrupt/resume requires persisted state. |
| Optional ReAct | `libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py:274-318` defines deprecated `create_react_agent` agent graph factory. | OBSERVED(libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py:274-318): Prebuilt ReAct is adjacency, not core Buildprint scope. |
| Optional ToolNode | `libs/prebuilt/langgraph/prebuilt/tool_node.py:622-700` executes tools, supports state/store/runtime injection, parallel execution, errors, message/list/direct tool call inputs, and Command outputs. | OBSERVED(libs/prebuilt/langgraph/prebuilt/tool_node.py:622-700): Optional local ToolNode-style demo can be non-core. |
| Optional ValidationNode | `libs/prebuilt/langgraph/prebuilt/tool_validator.py:43-95` defines deprecated validation-only node for last AIMessage tool requests. | OBSERVED(libs/prebuilt/langgraph/prebuilt/tool_validator.py:43-95): ValidationNode is optional adjacency and should not drive the core runtime. |