durability: conformance scorecard + journaled LLM calls - #19
Merged
Conversation
A conformance table (met/partial/out-of-scope-by-design, each verdict citing the module or doc section behind it) against the Diagrid critique's definition of durable execution. Formalizes the honest positioning already spread across README, production.md, and dsl-comparison.md; linked from the README support boundary.
run_durable now wraps the LLM client in a per-run journaling layer (journal_llm=True by default): each call's request fingerprint and response land in a new llm_journal table, and a resumed run replays fingerprint-matched responses instead of re-calling the provider. Across a hard crash, at most the single in-flight call of the interrupted step re-executes. Exactly-once remains out of scope. This is the per-agent-turn checkpointing phase-2-durability.md deferred. 7 new tests, 250 total pass; ruff/mypy clean; LLD+HLD updated in lockstep.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two commits that convert ThreadLang's honest durability positioning into a public asset, then strengthen the reality behind it:
docs: score durability against the published seven criteria— newdocs/durability-conformance.mdscoring v0.13.3 against the Diagrid critique's definition of durable execution (the argument currently being levelled at LangGraph/CrewAI/Google ADK). 3 met, 2 partial, 2 out-of-scope-by-design; every verdict cites the module or doc section behind it. Linked from the README support boundary.feat: journal LLM responses per run—run_durablewraps the LLM client in a per-run journaling layer (journal_llm=Truedefault; ephemeralrun_programuntouched). Each call's request fingerprint + response lands in a newllm_journaltable (additive_SCHEMAentry, no migration); a resumed run replays fingerprint-matched responses instead of re-calling the provider. This is the per-agent-turn checkpointingphase-2-durability.mdexplicitly deferred.Claim, stated precisely
Across a hard crash, the interrupted step's completed model calls replay from the journal and at most the single in-flight call re-executes (down from "every call in the step"). Exactly-once remains impossible client-side and stays scoped out; tool calls in the interrupted step remain at-least-once. README, production.md, and the conformance doc were all tightened to this wording in lockstep.
Notes for review
(run_id, request_fingerprint, occurrence)— no step_key column: the fingerprint is the step identity for distinct requests, and identical requests are semantically interchangeable. Documented injournal.pyand the LLD.getattrduck-typing:completealways,route/agent_steponly when the wrapped client has them.emit llmrides the wrapped client and is journaled too.Verification
250 tests pass (7 new: crash-mid-step replay counting provider calls, fingerprint-mismatch fallthrough, duck-typing preservation, AgentTurn round-trip, opt-out, route replay, terminal prune).
ruff check,ruff format --check,mypy src/threadlangall clean; LLD+HLD updated in the same PR per the design-doc contract.