Skip to content

durability: conformance scorecard + journaled LLM calls - #19

Merged
minglong51 merged 2 commits into
mainfrom
feat/llm-response-journaling
Aug 22, 2026
Merged

durability: conformance scorecard + journaled LLM calls#19
minglong51 merged 2 commits into
mainfrom
feat/llm-response-journaling

Conversation

@minglong51

Copy link
Copy Markdown
Owner

What

Two commits that convert ThreadLang's honest durability positioning into a public asset, then strengthen the reality behind it:

  1. docs: score durability against the published seven criteria — new docs/durability-conformance.md scoring 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.

  2. feat: journal LLM responses per runrun_durable wraps the LLM client in a per-run journaling layer (journal_llm=True default; ephemeral run_program untouched). Each call's request fingerprint + response lands in a new llm_journal table (additive _SCHEMA entry, no migration); a resumed run replays fingerprint-matched responses instead of re-calling the provider. This is the per-agent-turn checkpointing phase-2-durability.md explicitly 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

  • Keying is (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 in journal.py and the LLD.
  • The wrapper preserves the runtime's getattr duck-typing: complete always, route/agent_step only when the wrapped client has them.
  • emit llm rides the wrapped client and is journaled too.
  • Zero runtime deps unchanged; no version bump.

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/threadlang all clean; LLD+HLD updated in the same PR per the design-doc contract.

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.
@minglong51
minglong51 merged commit 8301800 into main Aug 22, 2026
5 checks passed
@minglong51
minglong51 deleted the feat/llm-response-journaling branch August 22, 2026 19:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant