Spec gap: graph state scoping (per-execution vs. per-route) is never defined #8

New issue

Open

opened 2026-05-27 05:24:58 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:24:58 +00:00

Member

Problem

§6.3 defines the graph state structure in detail but never specifies the lifetime and scope of a state instance:

Is state per-execution (a fresh GraphState created for every message that enters the graph)?
Is state per-route (a single shared GraphState instance persists across all invocations of the graph)?
Or is it per-session (some user-defined grouping)?

The checkpointing feature (§6.6) implies state can persist between invocations (checkpoints survive process restarts). The loop detection guards (§6.8) reference execution counts and message fingerprints in ways that imply per-execution isolation. But both can't be simultaneously true without a clear model.

The concurrency rules (§12.3) make this even more critical: if two messages arrive at __input__ and both are routed to the same graph, do they share state or each receive an isolated state object? With shared state, the second message sees the first message's changes. With isolated state, checkpointing across invocations is meaningless.

Impact on Library Implementation

This is one of the most fundamental implementation choices in the entire library. The state scoping model affects:

Memory layout and object lifecycle
Thread/async safety requirements
Checkpointing semantics
Correctness of multi-message processing

Decision Needed

Define the state lifecycle explicitly:

Per-execution: A new GraphState is created for every call to the graph. Checkpoints are for crash recovery only and are not automatically loaded on the next invocation.
Per-route (persistent): A single GraphState is shared across all invocations. Each new message is appended to the existing state.
Configurable: The graph route configuration includes a field (e.g., state_scope: per_execution | persistent) to choose the model.

References

§6.3 — Graph State
§6.6 — Checkpointing and Time Travel
§6.8 — Loop and Cycle Detection
§12.3 — Concurrency

## Problem §6.3 defines the graph state structure in detail but never specifies the **lifetime and scope** of a state instance: - Is state **per-execution** (a fresh `GraphState` created for every message that enters the graph)? - Is state **per-route** (a single shared `GraphState` instance persists across all invocations of the graph)? - Or is it **per-session** (some user-defined grouping)? The checkpointing feature (§6.6) implies state can persist between invocations (checkpoints survive process restarts). The loop detection guards (§6.8) reference execution counts and message fingerprints in ways that imply per-execution isolation. But both can't be simultaneously true without a clear model. The concurrency rules (§12.3) make this even more critical: if two messages arrive at `__input__` and both are routed to the same graph, do they share state or each receive an isolated state object? With shared state, the second message sees the first message's changes. With isolated state, checkpointing across invocations is meaningless. ## Impact on Library Implementation This is one of the most fundamental implementation choices in the entire library. The state scoping model affects: - Memory layout and object lifecycle - Thread/async safety requirements - Checkpointing semantics - Correctness of multi-message processing ## Decision Needed Define the state lifecycle explicitly: 1. **Per-execution**: A new `GraphState` is created for every call to the graph. Checkpoints are for crash recovery only and are not automatically loaded on the next invocation. 2. **Per-route (persistent)**: A single `GraphState` is shared across all invocations. Each new message is appended to the existing state. 3. **Configurable**: The graph route configuration includes a field (e.g., `state_scope: per_execution | persistent`) to choose the model. ## References - §6.3 — Graph State - §6.6 — Checkpointing and Time Travel - §6.8 — Loop and Cycle Detection - §12.3 — Concurrency

Rows
Columns