Summary
There are two session layers that have never been joined. grapharc.session is durable: status, the event queue, approval holds and the audit trail live in SQLite, graph state lives in the kernel's checkpointer, and it is verified to resume across genuinely separate processes. The HTTP API does not use it. grapharc/server/runtime.py:370 defines InProcessRuntime, whose sessions die with the process, never evict, and record message and approval events without delivering them into a running graph.
Tracked in ROADMAP.md §12.3 and named in README as the last remaining "built and unreachable" seam.
Why this matters
An approval that is recorded but never delivered is the worst possible failure mode for a human-in-the-loop gate: the operator sees their decision accepted and the graph never learns of it. Human approval that actually reaches the running graph is what makes graph engineering safe to point at production rather than at a demo, and right now the durable machinery that does this correctly is reachable only from Python, not from the API people would deploy.
Where in the code
grapharc/server/runtime.py:370 — InProcessRuntime, the throwaway implementationgrapharc/server/runtime.py:3 — the docstring stating app.py talks only to the SessionRuntime protocol (this is the seam you can exploit)grapharc/server/app.py — the FastAPI surface, SSE streaming, and the endpointsgrapharc/session/store.py — the durable store; note :187 (approving one hold must never release another) and :390-397 (a hold surviving a crash must be released deliberately)grapharc/session/runtime.py — the durable turn drivergrapharc/server/errors.py:68 — an existing note about which savers InProcessRuntime covers
What to change
app.py already depends on a SessionRuntime protocol, so the shape of the work is "implement that protocol over grapharc.session" — but the hard parts are semantic, not structural:
- Approval delivery. An approval posted over HTTP must actually release the hold and let the graph continue. This is the whole point; everything else is secondary.
- Async. A durable session turn is currently synchronous. The kernel has
astream; FastAPI is async. Decide whether you make the turn async or run it off the event loop, and do not block the loop either way. - Runner identity. A runner claim is a claim, not a lease — nothing reclaims a session whose runner died holding it. Over HTTP, with workers restarting, this becomes load-bearing. Either fix it here or state precisely why it is out of scope (see the separate lease issue).
- Graph registry. A resuming process must register the graph in its own registry or it gets
UnknownGraphError rather than a guess. Decide how a web worker does that. - SSE and the trace must not diverge. There is an existing test asserting the stream and the trace file are the same record, including for answers over 2,000 characters and values JSON cannot hold. That invariant must survive the swap.
- Eviction and lifetime.
InProcessRuntime never evicts. A durable store needs a real answer for session lifetime.
Migration path matters: propose whether InProcessRuntime is deleted, kept behind a flag, or kept for tests.
How to verify
uv run pytest tests/test_server.py tests/test_session.py -q
uv run pytest -q
uv run ruff check .
The decisive test is cross-process, mirroring the existing session test: one process creates a session over HTTP and runs until a gated node holds; a second process serves the API, sees the hold, accepts an approval over HTTP, and the graph completes — with each node appearing exactly once in an append-only log.
Acceptance criteria
Skill level — experience required
This is the largest open piece of work in the repository and it spans four subsystems: the kernel's checkpointer, the durable session store, the FastAPI surface, and the trace. It also requires real comfort with async Python and with cross-process correctness — the bugs here are the kind that only appear under a restart or a race. Please open a design comment on this issue before writing code so the semantics above can be agreed first. If you have built durable job or workflow systems before, this is the one to take.
Summary
There are two session layers that have never been joined.
grapharc.sessionis durable: status, the event queue, approval holds and the audit trail live in SQLite, graph state lives in the kernel's checkpointer, and it is verified to resume across genuinely separate processes. The HTTP API does not use it.grapharc/server/runtime.py:370definesInProcessRuntime, whose sessions die with the process, never evict, and recordmessageandapprovalevents without delivering them into a running graph.Tracked in
ROADMAP.md§12.3 and named in README as the last remaining "built and unreachable" seam.Why this matters
An approval that is recorded but never delivered is the worst possible failure mode for a human-in-the-loop gate: the operator sees their decision accepted and the graph never learns of it. Human approval that actually reaches the running graph is what makes graph engineering safe to point at production rather than at a demo, and right now the durable machinery that does this correctly is reachable only from Python, not from the API people would deploy.
Where in the code
grapharc/server/runtime.py:370—InProcessRuntime, the throwaway implementationgrapharc/server/runtime.py:3— the docstring statingapp.pytalks only to theSessionRuntimeprotocol (this is the seam you can exploit)grapharc/server/app.py— the FastAPI surface, SSE streaming, and the endpointsgrapharc/session/store.py— the durable store; note:187(approving one hold must never release another) and:390-397(a hold surviving a crash must be released deliberately)grapharc/session/runtime.py— the durable turn drivergrapharc/server/errors.py:68— an existing note about which saversInProcessRuntimecoversWhat to change
app.pyalready depends on aSessionRuntimeprotocol, so the shape of the work is "implement that protocol overgrapharc.session" — but the hard parts are semantic, not structural:astream; FastAPI is async. Decide whether you make the turn async or run it off the event loop, and do not block the loop either way.UnknownGraphErrorrather than a guess. Decide how a web worker does that.InProcessRuntimenever evicts. A durable store needs a real answer for session lifetime.Migration path matters: propose whether
InProcessRuntimeis deleted, kept behind a flag, or kept for tests.How to verify
uv run pytest tests/test_server.py tests/test_session.py -q uv run pytest -q uv run ruff check .The decisive test is cross-process, mirroring the existing session test: one process creates a session over HTTP and runs until a gated node holds; a second process serves the API, sees the hold, accepts an approval over HTTP, and the graph completes — with each node appearing exactly once in an append-only log.
Acceptance criteria
ROADMAP.md§12.3 and the README seam paragraph are updateduv run pytestgreen,uv run ruff check .cleanSkill level — experience required
This is the largest open piece of work in the repository and it spans four subsystems: the kernel's checkpointer, the durable session store, the FastAPI surface, and the trace. It also requires real comfort with async Python and with cross-process correctness — the bugs here are the kind that only appear under a restart or a race. Please open a design comment on this issue before writing code so the semantics above can be agreed first. If you have built durable job or workflow systems before, this is the one to take.