crashresume 0.1.0__tar.gz

crashresume-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calasdan-sketch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crashresume-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: crashresume
+Version: 0.1.0
+Summary: Conformance harness that proves an agent survives crash/restart without losing state or replaying effects
+Author: calasdan-sketch
+License-Expression: MIT
+Keywords: agents,conformance,crash,resume,idempotency,pytest,recovery
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# crashresume
+
+**Prove your agent survives a crash.** A conformance harness that kills and restarts a subject at every side-effect boundary, then checks the three invariants that decide whether a resume is safe:
+
+| Invariant | Meaning |
+|---|---|
+| `state_lost` | after restart, persisted state is gone while the baseline had state |
+| `effect_replayed` | the same idempotency key fired twice (e.g. a double charge) |
+| `resume_diverged` | the resumed run finished in a different state than the baseline |
+
+Real agent frameworks hit exactly these failures: streamed state vanishes on cancel, a payment succeeds but the client times out, the resumed run re-issues the payment. `crashresume` makes that testable without a framework — the subject is any object with a `step(input)` method.
+
+## Install
+
+```bash
+pip install crashresume
+```
+
+## Usage
+
+```python
+from crashresume import conform
+
+def make_agent(ctx):                 # called once per (re)start — model a fresh process
+    return MyAgent(ctx, store=DB)    # your persistence lives in DB
+
+report = conform(make_agent, inputs=["job-1", "job-2", "job-3"])
+assert report.passed, str(report)
+```
+
+Your agent records side effects through the harness-owned context:
+
+```python
+class MyAgent:
+    def __init__(self, ctx, store):
+        self.ctx = ctx
+        self.store = store
+        self.done = set(store.load("done"))
+
+    def step(self, job):
+        if job in self.done:
+            return                       # resume-safe: skip what already committed
+        self.ctx.effect("charge", job, key=f"charge:{job}")
+        self.done.add(job)
+        self.store.save("done", self.done)
+```
+
+The harness runs a baseline, then re-runs crashing right after each recorded effect (side effect committed, process dead before checkpoint — the nastiest real-world case), restarts via your factory, and compares state and effect logs.
+
+### Per-scenario state (important)
+
+Each crash point is an **independent scenario** — your factory is called from scratch each time. Durable state that must survive a restart but must not leak between scenarios should be keyed by `ctx.run_id` (the baseline uses `"run"`; crash point *k* and its resume share `"run-<k>"`):
+
+```python
+stores = {}
+
+def make_agent(ctx):
+    store = stores.setdefault(ctx.run_id, Store())   # fresh per scenario
+    return MyAgent(ctx, store)                        # durable within the scenario
+```
+
+If your durable store is a real database, reset its fixture per scenario the same way.
+
+## pytest plugin
+
+A `conform` fixture is registered automatically:
+
+```python
+def test_agent_is_crash_safe(conform):
+    conform(lambda ctx: MyAgent(ctx, store=DB), inputs=["a", "b", "c"])
+```
+
+## CLI demo
+
+```bash
+crashresume --selftest   # runs a conforming agent plus two broken ones and verifies the findings
+```
+
+## Notes
+
+- Subjects that record no effects through `ctx` pass trivially — route real side effects through `ctx.effect` or the harness cannot observe them.
+- `state_lost` vs `resume_diverged`: an empty state after restart is "lost"; a non-empty but different final state is "diverged". Expose a `state()` method to opt into state comparison.
+- Works with any persistence: SQLite, Redis, files, LangGraph checkpoints.
+
+## License
+
+MIT-style: use it, ship it, no warranty.

crashresume-0.1.0/README.md

@@ -0,0 +1,87 @@
+# crashresume
+
+**Prove your agent survives a crash.** A conformance harness that kills and restarts a subject at every side-effect boundary, then checks the three invariants that decide whether a resume is safe:
+
+| Invariant | Meaning |
+|---|---|
+| `state_lost` | after restart, persisted state is gone while the baseline had state |
+| `effect_replayed` | the same idempotency key fired twice (e.g. a double charge) |
+| `resume_diverged` | the resumed run finished in a different state than the baseline |
+
+Real agent frameworks hit exactly these failures: streamed state vanishes on cancel, a payment succeeds but the client times out, the resumed run re-issues the payment. `crashresume` makes that testable without a framework — the subject is any object with a `step(input)` method.
+
+## Install
+
+```bash
+pip install crashresume
+```
+
+## Usage
+
+```python
+from crashresume import conform
+
+def make_agent(ctx):                 # called once per (re)start — model a fresh process
+    return MyAgent(ctx, store=DB)    # your persistence lives in DB
+
+report = conform(make_agent, inputs=["job-1", "job-2", "job-3"])
+assert report.passed, str(report)
+```
+
+Your agent records side effects through the harness-owned context:
+
+```python
+class MyAgent:
+    def __init__(self, ctx, store):
+        self.ctx = ctx
+        self.store = store
+        self.done = set(store.load("done"))
+
+    def step(self, job):
+        if job in self.done:
+            return                       # resume-safe: skip what already committed
+        self.ctx.effect("charge", job, key=f"charge:{job}")
+        self.done.add(job)
+        self.store.save("done", self.done)
+```
+
+The harness runs a baseline, then re-runs crashing right after each recorded effect (side effect committed, process dead before checkpoint — the nastiest real-world case), restarts via your factory, and compares state and effect logs.
+
+### Per-scenario state (important)
+
+Each crash point is an **independent scenario** — your factory is called from scratch each time. Durable state that must survive a restart but must not leak between scenarios should be keyed by `ctx.run_id` (the baseline uses `"run"`; crash point *k* and its resume share `"run-<k>"`):
+
+```python
+stores = {}
+
+def make_agent(ctx):
+    store = stores.setdefault(ctx.run_id, Store())   # fresh per scenario
+    return MyAgent(ctx, store)                        # durable within the scenario
+```
+
+If your durable store is a real database, reset its fixture per scenario the same way.
+
+## pytest plugin
+
+A `conform` fixture is registered automatically:
+
+```python
+def test_agent_is_crash_safe(conform):
+    conform(lambda ctx: MyAgent(ctx, store=DB), inputs=["a", "b", "c"])
+```
+
+## CLI demo
+
+```bash
+crashresume --selftest   # runs a conforming agent plus two broken ones and verifies the findings
+```
+
+## Notes
+
+- Subjects that record no effects through `ctx` pass trivially — route real side effects through `ctx.effect` or the harness cannot observe them.
+- `state_lost` vs `resume_diverged`: an empty state after restart is "lost"; a non-empty but different final state is "diverged". Expose a `state()` method to opt into state comparison.
+- Works with any persistence: SQLite, Redis, files, LangGraph checkpoints.
+
+## License
+
+MIT-style: use it, ship it, no warranty.

crashresume-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "crashresume"
+version = "0.1.0"
+description = "Conformance harness that proves an agent survives crash/restart without losing state or replaying effects"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "calasdan-sketch" }]
+keywords = ["agents", "conformance", "crash", "resume", "idempotency", "pytest", "recovery"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Framework :: Pytest",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.scripts]
+crashresume = "crashresume.cli:main"
+
+[project.entry-points.pytest11]
+crashresume = "crashresume.pytest_plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]

crashresume-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

crashresume-0.1.0/src/crashresume/__init__.py

@@ -0,0 +1,23 @@
+"""crashresume — prove an agent survives crash/restart without losing state or replaying effects."""
+
+from .core import (
+    ConformanceReport,
+    Context,
+    Effect,
+    EffectLog,
+    Finding,
+    InjectedCrash,
+    conform,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "conform",
+    "Context",
+    "Effect",
+    "EffectLog",
+    "Finding",
+    "InjectedCrash",
+    "ConformanceReport",
+    "__version__",
+]

crashresume-0.1.0/src/crashresume/cli.py

@@ -0,0 +1,126 @@
+"""crashresume CLI: a self-test demo that exercises good and bad agents."""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any, Dict
+
+from . import __version__
+from .core import Context, InjectedCrash, conform
+
+
+class _Store:
+    """Stand-in for durable storage shared across process restarts."""
+
+    def __init__(self) -> None:
+        self.data: Dict[str, Any] = {}
+
+
+class _Stores:
+    """Per-scenario durable stores, isolated by ctx.run_id (see README)."""
+
+    def __init__(self) -> None:
+        self.d: Dict[str, _Store] = {}
+
+    def get(self, ctx) -> "_Store":
+        return self.d.setdefault(ctx.run_id, _Store())
+
+
+class GoodAgent:
+    """Persists after every input and reconciles against committed effects."""
+
+    def __init__(self, ctx: Context, store: _Store) -> None:
+        self.ctx = ctx
+        self.store = store
+        self.done = set(store.data.get("done", set()))
+
+    def step(self, item: str) -> None:
+        key = f"process:{item}"
+        if item in self.done or key in self.ctx.effects.keys():
+            self.done.add(item)
+            self.store.data["done"] = set(self.done)
+            return
+        self.ctx.effect("process", item, key=key)
+        self.done.add(item)
+        self.store.data["done"] = set(self.done)
+
+    def state(self):
+        return {"done": sorted(self.store.data.get("done", set()))}
+
+
+class ReplayAgent:
+    """Persists state but re-issues effects for everything on resume."""
+
+    def __init__(self, ctx: Context, store: _Store) -> None:
+        self.ctx = ctx
+        self.store = store
+
+    def step(self, item: str) -> None:
+        self.ctx.effect("process", item, key=f"process:{item}")  # always fires
+        self.store.data.setdefault("done", set()).add(item)
+
+    def state(self):
+        return {"done": sorted(self.store.data.get("done", set()))}
+
+
+class LostAgent:
+    """Loses its checkpoint and wrongly believes the stream is exhausted."""
+
+    def __init__(self, ctx: Context, store: _Store) -> None:
+        self.ctx = ctx
+        self.store = store
+
+    def step(self, item: str) -> None:
+        if self.store.data.get("exhausted"):
+            return
+        self.ctx.effect("process", item, key=f"process:{item}")
+        self.store.data.setdefault("done", []).append(item)
+
+    def state(self):
+        return {"done": list(self.store.data.get("done", []))}
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="crashresume", description=__doc__.splitlines()[0])
+    ap.add_argument("--version", action="version", version=f"crashresume {__version__}")
+    ap.add_argument("--selftest", action="store_true", help="run the built-in good/bad agent demo")
+    args = ap.parse_args(argv)
+    if not args.selftest:
+        ap.print_help()
+        return 0
+
+    inputs = ["a", "b", "c"]
+    ok = True
+
+    good_stores = _Stores()
+    good = conform(lambda ctx: GoodAgent(ctx, good_stores.get(ctx)), inputs)
+    print("GoodAgent (persist + reconcile against committed effects):")
+    print(" ", good)
+    ok &= good.passed
+
+    replay_stores = _Stores()
+    replay = conform(lambda ctx: ReplayAgent(ctx, replay_stores.get(ctx)), inputs)
+    print("ReplayAgent (re-fires effects on resume):")
+    print(" ", replay)
+    ok &= not replay.passed and any(f.kind == "effect_replayed" for f in replay.findings)
+
+    lost_stores = _Stores()
+
+    def make_lost(ctx):
+        store = lost_stores.get(ctx)
+        if ctx.run_id != "run":  # checkpoint lost in the crash
+            store.data["done"] = []
+            store.data["exhausted"] = True
+        return LostAgent(ctx, store)
+
+    lost = conform(make_lost, inputs)
+    print("LostAgent (checkpoint lost, wrongly believes stream is done):")
+    print(" ", lost)
+    ok &= not lost.passed and any(f.kind == "state_lost" for f in lost.findings)
+
+    print("\nselftest:", "PASS" if ok else "FAIL")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

crashresume-0.1.0/src/crashresume/core.py

@@ -0,0 +1,229 @@
+"""Crash/restart conformance: run a subject, then re-run it crashing at every
+side-effect boundary, and check the three invariants that matter:
+
+* ``state_lost``       — after restart, the subject's persisted state is empty/gone
+                         while the baseline run had state
+* ``effect_replayed``  — the same idempotency key was issued twice, or the final
+                         effect log contains effects the baseline never produced
+* ``resume_diverged``  — the resumed run finished in a different state than the
+                         baseline run
+
+The subject is any object with a ``step(input)`` method. The harness owns the
+side-effect channel: subjects record effects through ``ctx.effect(...)``, which
+is where crashes get injected. Persistence across restart is the subject's job —
+the factory is called again to model a fresh process.
+"""
+from __future__ import annotations
+
+import itertools
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterable, List, Optional, Sequence
+
+
+class InjectedCrash(RuntimeError):
+    """Raised inside the subject to simulate a process death at a side effect."""
+
+
+@dataclass(frozen=True)
+class Effect:
+    kind: str
+    payload: Any = None
+    key: Optional[str] = None
+    seq: int = 0
+
+
+class EffectLog:
+    """Durable record of side effects, shared across restarts of one run."""
+
+    def __init__(self) -> None:
+        self._effects: List[Effect] = []
+
+    def record(self, kind: str, payload: Any = None, key: Optional[str] = None) -> Effect:
+        e = Effect(kind=kind, payload=payload, key=key, seq=len(self._effects))
+        self._effects.append(e)
+        return e
+
+    @property
+    def effects(self) -> List[Effect]:
+        return list(self._effects)
+
+    def keys(self) -> List[str]:
+        return [e.key for e in self._effects if e.key is not None]
+
+
+class Context:
+    """Handed to the factory on every (re)start; subjects record effects via it.
+
+    ``run_id`` is the scenario namespace: the baseline run uses ``"run"``;
+    crash point *k* and its resume share ``"run-<k>"``. State that must survive
+    a restart but must NOT leak from one scenario into the next should be keyed
+    by ``ctx.run_id`` (e.g. an in-memory ``stores.setdefault(ctx.run_id, ...)``).
+    """
+
+    def __init__(self, run_id: str, log: EffectLog, crash_at: Optional[int] = None) -> None:
+        self.run_id = run_id
+        self.effects = log
+        self._log = log
+        self._crash_at = crash_at
+        self._count = 0
+
+    def effect(self, kind: str, payload: Any = None, key: Optional[str] = None) -> Effect:
+        """Record a side effect. The crash is injected right after this call,
+        modelling: side effect committed, process died before the checkpoint."""
+        e = self._log.record(kind, payload, key)
+        self._count += 1
+        if self._crash_at is not None and self._count >= self._crash_at:
+            raise InjectedCrash(f"crash injected after effect #{self._count} ({kind})")
+        return e
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str          # state_lost | effect_replayed | effect_lost | resume_diverged | resume_crashed
+    crash_after: int   # which effect boundary the crash was injected at
+    detail: str
+
+
+@dataclass
+class ConformanceReport:
+    crash_points: int = 0
+    findings: List[Finding] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return not self.findings
+
+    def __bool__(self) -> bool:
+        return self.passed
+
+    def __str__(self) -> str:
+        head = (
+            f"conformance: {self.crash_points} crash point(s) tested, "
+            f"{len(self.findings)} finding(s)"
+        )
+        if not self.findings:
+            return head + " — PASS"
+        body = "\n".join(
+            f"  [{f.kind}] crash after effect #{f.crash_after}: {f.detail}"
+            for f in self.findings
+        )
+        return head + "\n" + body
+
+
+def _is_empty(value: Any) -> bool:
+    """Deep emptiness: None, empty containers, or containers whose contents are
+    all empty. Numbers are never empty (0 is data, not absence)."""
+    if value is None or value is False:
+        return True
+    if isinstance(value, str):
+        return value == ""
+    if isinstance(value, dict):
+        return all(_is_empty(v) for v in value.values())
+    if isinstance(value, (list, tuple, set)):
+        return len(value) == 0 or all(_is_empty(v) for v in value)
+    return False
+
+
+def _snapshot(agent: Any) -> Any:
+    """Best-effort observable state of a subject."""
+    state = getattr(agent, "state", None)
+    if callable(state):
+        return state()
+    if hasattr(agent, "__dict__"):
+        return {k: v for k, v in vars(agent).items() if not k.startswith("_") and k != "ctx"}
+    return None
+
+
+def _run(factory: Callable[[Context], Any], inputs: Sequence[Any], log: EffectLog,
+         run_id: str, crash_at: Optional[int] = None) -> Any:
+    agent = factory(Context(run_id, log, crash_at=crash_at))
+    for item in inputs:
+        agent.step(item)
+    return agent
+
+
+def conform(
+    factory: Callable[[Context], Any],
+    inputs: Iterable[Any],
+    run_id: str = "run",
+) -> ConformanceReport:
+    """Run ``factory(ctx) -> subject`` to completion, then re-run it crashing at
+    every effect boundary and compare against the baseline.
+
+    Each crash point is an independent scenario: the factory is called again
+    from scratch (baseline state included). Key per-scenario durable state by
+    ``ctx.run_id`` so scenarios don't contaminate each other — see Context.
+    """
+    inputs = list(inputs)
+
+    baseline_log = EffectLog()
+    baseline_agent = _run(factory, inputs, baseline_log, run_id)
+    base_state = _snapshot(baseline_agent)
+    base_effects = baseline_log.effects
+    base_keys = [e.key for e in base_effects if e.key]
+
+    report = ConformanceReport(crash_points=len(base_effects))
+    if not base_effects:
+        # Nothing to crash against: subject records no side effects through ctx.
+        return report
+
+    counter = itertools.count(1)
+    for k in range(1, len(base_effects) + 1):
+        run_id_k = f"{run_id}-{next(counter)}"
+        log = EffectLog()
+        try:
+            _run(factory, inputs, log, run_id_k, crash_at=k)
+        except InjectedCrash:
+            pass  # expected
+
+        # restart: fresh process model, same durable log
+        try:
+            agent = factory(Context(run_id_k, log))
+            for item in inputs:
+                agent.step(item)
+            final_state = _snapshot(agent)
+        except InjectedCrash:
+            report.findings.append(Finding("resume_crashed", k, "resume run raised InjectedCrash again"))
+            continue
+
+        final_effects = log.effects
+        final_keys = [e.key for e in final_effects if e.key]
+
+        # 1. duplicate idempotency keys in the final log
+        seen: set = set()
+        for key in final_keys:
+            if key in seen:
+                report.findings.append(Finding("effect_replayed", k, f"key {key!r} issued more than once"))
+            seen.add(key)
+
+        # 2. keyed effects the baseline never issued (beyond one occurrence)
+        extra = [key for key in final_keys if final_keys.count(key) > base_keys.count(key)]
+        for key in sorted(set(extra)):
+            if not any(f.kind == "effect_replayed" and key in f.detail for f in report.findings):
+                report.findings.append(Finding("effect_replayed", k, f"key {key!r} appears more often than in baseline"))
+
+        # 3. keyed effects that vanished
+        for key in sorted(set(base_keys) - set(final_keys)):
+            report.findings.append(Finding("effect_lost", k, f"key {key!r} never re-issued after resume"))
+
+        # 4. state invariants (only when the subject exposes comparable state).
+        #    A subject that reconciles against the committed effect log may start
+        #    from an empty checkpoint and still converge — that is fine. We flag
+        #    state only when the loss survives the whole resume: final state is
+        #    empty while the baseline had state (state_lost), or non-empty but
+        #    different (resume_diverged).
+        if base_state is not None and final_state is not None:
+            if _is_empty(final_state) and not _is_empty(base_state):
+                report.findings.append(
+                    Finding("state_lost", k, f"final state {final_state!r} is empty but baseline state was {base_state!r}")
+                )
+            elif final_state != base_state:
+                report.findings.append(
+                    Finding(
+                        "resume_diverged",
+                        k,
+                        f"final state {final_state!r} != baseline {base_state!r}",
+                    )
+                )
+
+    return report

crashresume-0.1.0/src/crashresume/pytest_plugin.py

@@ -0,0 +1,24 @@
+"""pytest integration: a ``conform`` fixture that asserts and returns a report."""
+from __future__ import annotations
+
+import pytest
+
+from . import core
+
+
+@pytest.fixture
+def conform():
+    """``conform(factory, inputs)`` — assert crash/restart conformance.
+
+    Usage inside a test::
+
+        def test_agent_is_conformant(conform, make_agent):
+            conform(lambda ctx: make_agent(ctx), inputs=["a", "b", "c"])
+    """
+
+    def run(factory, inputs, run_id: str = "run") -> core.ConformanceReport:
+        report = core.conform(factory, inputs, run_id=run_id)
+        assert report.passed, str(report)
+        return report
+
+    return run

crashresume-0.1.0/src/crashresume.egg-info/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: crashresume
+Version: 0.1.0
+Summary: Conformance harness that proves an agent survives crash/restart without losing state or replaying effects
+Author: calasdan-sketch
+License-Expression: MIT
+Keywords: agents,conformance,crash,resume,idempotency,pytest,recovery
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# crashresume
+
+**Prove your agent survives a crash.** A conformance harness that kills and restarts a subject at every side-effect boundary, then checks the three invariants that decide whether a resume is safe:
+
+| Invariant | Meaning |
+|---|---|
+| `state_lost` | after restart, persisted state is gone while the baseline had state |
+| `effect_replayed` | the same idempotency key fired twice (e.g. a double charge) |
+| `resume_diverged` | the resumed run finished in a different state than the baseline |
+
+Real agent frameworks hit exactly these failures: streamed state vanishes on cancel, a payment succeeds but the client times out, the resumed run re-issues the payment. `crashresume` makes that testable without a framework — the subject is any object with a `step(input)` method.
+
+## Install
+
+```bash
+pip install crashresume
+```
+
+## Usage
+
+```python
+from crashresume import conform
+
+def make_agent(ctx):                 # called once per (re)start — model a fresh process
+    return MyAgent(ctx, store=DB)    # your persistence lives in DB
+
+report = conform(make_agent, inputs=["job-1", "job-2", "job-3"])
+assert report.passed, str(report)
+```
+
+Your agent records side effects through the harness-owned context:
+
+```python
+class MyAgent:
+    def __init__(self, ctx, store):
+        self.ctx = ctx
+        self.store = store
+        self.done = set(store.load("done"))
+
+    def step(self, job):
+        if job in self.done:
+            return                       # resume-safe: skip what already committed
+        self.ctx.effect("charge", job, key=f"charge:{job}")
+        self.done.add(job)
+        self.store.save("done", self.done)
+```
+
+The harness runs a baseline, then re-runs crashing right after each recorded effect (side effect committed, process dead before checkpoint — the nastiest real-world case), restarts via your factory, and compares state and effect logs.
+
+### Per-scenario state (important)
+
+Each crash point is an **independent scenario** — your factory is called from scratch each time. Durable state that must survive a restart but must not leak between scenarios should be keyed by `ctx.run_id` (the baseline uses `"run"`; crash point *k* and its resume share `"run-<k>"`):
+
+```python
+stores = {}
+
+def make_agent(ctx):
+    store = stores.setdefault(ctx.run_id, Store())   # fresh per scenario
+    return MyAgent(ctx, store)                        # durable within the scenario
+```
+
+If your durable store is a real database, reset its fixture per scenario the same way.
+
+## pytest plugin
+
+A `conform` fixture is registered automatically:
+
+```python
+def test_agent_is_crash_safe(conform):
+    conform(lambda ctx: MyAgent(ctx, store=DB), inputs=["a", "b", "c"])
+```
+
+## CLI demo
+
+```bash
+crashresume --selftest   # runs a conforming agent plus two broken ones and verifies the findings
+```
+
+## Notes
+
+- Subjects that record no effects through `ctx` pass trivially — route real side effects through `ctx.effect` or the harness cannot observe them.
+- `state_lost` vs `resume_diverged`: an empty state after restart is "lost"; a non-empty but different final state is "diverged". Expose a `state()` method to opt into state comparison.
+- Works with any persistence: SQLite, Redis, files, LangGraph checkpoints.
+
+## License
+
+MIT-style: use it, ship it, no warranty.

crashresume-0.1.0/src/crashresume.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/crashresume/__init__.py
+src/crashresume/cli.py
+src/crashresume/core.py
+src/crashresume/pytest_plugin.py
+src/crashresume.egg-info/PKG-INFO
+src/crashresume.egg-info/SOURCES.txt
+src/crashresume.egg-info/dependency_links.txt
+src/crashresume.egg-info/entry_points.txt
+src/crashresume.egg-info/top_level.txt
+tests/test_core.py
+tests/test_plugin.py

crashresume-0.1.0/src/crashresume.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

crashresume-0.1.0/src/crashresume.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+crashresume = crashresume.cli:main
+
+[pytest11]
+crashresume = crashresume.pytest_plugin

crashresume-0.1.0/src/crashresume.egg-info/top_level.txt

@@ -0,0 +1 @@
+crashresume

crashresume-0.1.0/tests/test_core.py

@@ -0,0 +1,258 @@
+"""Core conformance-engine tests.
+
+Every factory here keys its durable store by ``ctx.run_id`` so that each crash
+scenario starts from the same initial state as the baseline — the documented
+isolation protocol.
+"""
+from crashresume import ConformanceReport, Context, EffectLog, InjectedCrash, conform
+
+
+class Store:
+    def __init__(self):
+        self.data = {}
+
+
+class Stores:
+    """Per-scenario stores, isolated by run_id."""
+
+    def __init__(self):
+        self.d = {}
+
+    def get(self, ctx):
+        return self.d.setdefault(ctx.run_id, Store())
+
+
+class GoodAgent:
+    def __init__(self, ctx: Context, store: Store):
+        self.ctx, self.store = ctx, store
+        self.done = set(store.data.get("done", set()))
+
+    def step(self, item):
+        key = f"process:{item}"
+        if item in self.done or key in self.ctx.effects.keys():
+            self.done.add(item)
+            self.store.data["done"] = set(self.done)
+            return
+        self.ctx.effect("process", item, key=key)
+        self.done.add(item)
+        self.store.data["done"] = set(self.done)
+
+    def state(self):
+        return {"done": sorted(self.store.data.get("done", set()))}
+
+
+class LazyAgent:
+    def __init__(self, ctx: Context, store: Store):
+        self.ctx = ctx
+        self.done = []
+
+    def step(self, item):
+        self.ctx.effect("process", item, key=f"process:{item}")
+        self.done.append(item)
+
+    def state(self):
+        return {"done": list(self.done)}
+
+
+class ReplayAgent:
+    def __init__(self, ctx: Context, store: Store):
+        self.ctx, self.store = ctx, store
+
+    def step(self, item):
+        self.ctx.effect("process", item, key=f"process:{item}")
+        self.store.data.setdefault("done", set()).add(item)
+
+    def state(self):
+        return {"done": sorted(self.store.data.get("done", set()))}
+
+
+class UnkeyedAgent:
+    """No idempotency keys; harness falls back to state comparison only."""
+
+    def __init__(self, ctx: Context, store: Store):
+        self.ctx, self.store = ctx, store
+        self.n = store.data.get("n", 0)
+
+    def step(self, item):
+        if self.n >= 3:
+            return
+        self.ctx.effect("process", item)
+        self.n += 1
+        self.store.data["n"] = self.n
+
+    def state(self):
+        return {"n": self.n}
+
+
+def test_good_agent_passes():
+    stores = Stores()
+    report = conform(lambda ctx: GoodAgent(ctx, stores.get(ctx)), ["a", "b", "c"])
+    assert isinstance(report, ConformanceReport)
+    assert report.passed, str(report)
+    assert report.crash_points == 3
+
+
+def test_lazy_agent_flagged_as_replay():
+    stores = Stores()
+    report = conform(lambda ctx: LazyAgent(ctx, stores.get(ctx)), ["a", "b"])
+    assert not report.passed
+    assert any(f.kind == "effect_replayed" for f in report.findings)
+
+
+def test_replay_agent_flagged():
+    stores = Stores()
+    report = conform(lambda ctx: ReplayAgent(ctx, stores.get(ctx)), ["a", "b"])
+    assert not report.passed
+    assert any(f.kind == "effect_replayed" for f in report.findings)
+
+
+def test_unkeyed_agent_still_conforms_when_count_stable():
+    stores = Stores()
+    report = conform(lambda ctx: UnkeyedAgent(ctx, stores.get(ctx)), ["a", "b", "c", "d"])
+    assert report.passed, str(report)
+
+
+def test_no_effects_trivially_passes():
+    class Silent:
+        def step(self, item):
+            pass
+
+    report = conform(lambda ctx: Silent(), ["x"])
+    assert report.passed and report.crash_points == 0
+
+
+def test_state_lost_when_subject_stops_reading_after_lost_checkpoint():
+    # classic offset-commit failure: checkpoint lost, subject wrongly believes
+    # the stream is exhausted -> final state empty though baseline had state
+    stores = Stores()
+
+    class Agent:
+        def __init__(self, ctx, store):
+            self.ctx, self.store = ctx, store
+
+        def step(self, item):
+            if self.store.data.get("exhausted"):
+                return
+            self.ctx.effect("e", item, key=item)
+            self.store.data.setdefault("done", []).append(item)
+
+        def state(self):
+            return {"done": list(self.store.data.get("done", []))}
+
+    def factory(ctx):
+        store = stores.get(ctx)
+        if ctx.run_id != "run":  # simulate: checkpoint lost in the crash
+            store.data["done"] = []
+            store.data["exhausted"] = True
+        return Agent(ctx, store)
+
+    report = conform(factory, ["a", "b"])
+    assert any(f.kind == "state_lost" for f in report.findings), str(report)
+
+
+def test_resume_diverged_when_final_state_differs():
+    stores = Stores()
+
+    class Agent:
+        def __init__(self, ctx, store):
+            self.ctx, self.store = ctx, store
+
+        def step(self, item):
+            key = f"e:{item}"
+            if key in self.ctx.effects.keys():
+                return
+            self.ctx.effect("e", item, key=key)
+            self.store.data.setdefault("done", []).append(item)
+
+        def state(self):
+            return {"done": sorted(self.store.data.get("done", []))}
+
+    def factory(ctx):
+        store = stores.get(ctx)
+        if ctx.run_id != "run":
+            store.data["done"] = ["ghost"]  # corrupted but non-empty checkpoint
+        return Agent(ctx, store)
+
+    report = conform(factory, ["a", "b"])
+    assert any(f.kind == "resume_diverged" for f in report.findings), str(report)
+
+
+def test_crash_injected_at_every_boundary():
+    stores = Stores()
+    seen = []
+
+    class Recorder:
+        def __init__(self, ctx, store):
+            self.ctx, self.store = ctx, store
+            self.done = set(store.data.get("done", set()))
+
+        def step(self, item):
+            if item in self.done or item in self.ctx.effects.keys():
+                self.done.add(item)
+                self.store.data["done"] = set(self.done)
+                return
+            seen.append((self.ctx.run_id, tuple(self.ctx.effects.keys())))
+            self.ctx.effect("e", item, key=item)
+            self.done.add(item)
+            self.store.data["done"] = set(self.done)
+
+    conform(lambda ctx: Recorder(ctx, stores.get(ctx)), ["1", "2"])
+    run_ids = [r[0] for r in seen]
+    assert len(set(run_ids)) >= 3
+
+
+def test_report_str_lists_findings():
+    stores = Stores()
+    report = conform(lambda ctx: ReplayAgent(ctx, stores.get(ctx)), ["a"])
+    text = str(report)
+    assert "effect_replayed" in text and "crash after effect #1" in text
+
+
+def test_effect_log_shared_across_restart():
+    log = EffectLog()
+    ctx = Context("r", log)
+    ctx.effect("a", key="k1")
+    assert log.keys() == ["k1"]
+
+
+def test_injected_crash_raised_after_recording():
+    log = EffectLog()
+    ctx = Context("r", log, crash_at=1)
+    try:
+        ctx.effect("charge", key="pay:1")
+        raised = False
+    except InjectedCrash:
+        raised = True
+    assert raised and log.keys() == ["pay:1"]
+
+
+def test_scenarios_are_isolated():
+    # the baseline must not poison crash scenarios via shared durable state
+    stores = Stores()
+    starts = []
+
+    class Agent:
+        def __init__(self, ctx, store):
+            self.ctx, self.store = ctx, store
+            self.done = set(store.data.get("done", set()))
+            starts.append((ctx.run_id, sorted(self.done)))
+
+        def step(self, item):
+            key = f"e:{item}"
+            if key in self.ctx.effects.keys():
+                self.store.data.setdefault("done", set()).add(item)  # heal from log
+                return
+            self.ctx.effect("e", item, key=key)
+            self.store.data.setdefault("done", set()).add(item)
+
+        def state(self):
+            return {"done": sorted(self.store.data.get("done", set()))}
+
+    report = conform(lambda ctx: Agent(ctx, stores.get(ctx)), ["a", "b"])
+    assert report.passed, str(report)
+    # the FIRST construction of every scenario starts from an empty checkpoint
+    # (resumes within a scenario may see that scenario's crash-run state)
+    first_seen = {}
+    for rid, done in starts:
+        first_seen.setdefault(rid, done)
+    assert all(done == [] for done in first_seen.values())

crashresume-0.1.0/tests/test_plugin.py

@@ -0,0 +1,54 @@
+"""The pytest plugin ships a working fixture — exercise it from a real test run."""
+PLUGIN = """
+STORES = {}
+
+
+def store_for(ctx):
+    return STORES.setdefault(ctx.run_id, {"done": set()})
+
+
+def test_conform_fixture_passes(conform):
+    class Agent:
+        def __init__(self, ctx):
+            self.ctx = ctx
+            self.store = store_for(ctx)
+            self.done = set(self.store["done"])
+
+        def step(self, item):
+            if item in self.done or item in self.ctx.effects.keys():
+                self.done.add(item)
+                self.store["done"] = set(self.done)
+                return
+            self.ctx.effect("e", item, key=item)
+            self.done.add(item)
+            self.store["done"] = set(self.done)
+
+        def state(self):
+            return {"done": sorted(self.store["done"])}
+
+    conform(lambda ctx: Agent(ctx), ["a", "b"])
+
+
+def test_conform_fixture_fails_on_replay(conform):
+    class Agent:
+        def __init__(self, ctx):
+            self.ctx = ctx
+
+        def step(self, item):
+            self.ctx.effect("e", item, key=item)
+
+    import pytest
+    with pytest.raises(AssertionError):
+        conform(lambda ctx: Agent(ctx), ["a"])
+"""
+
+
+def test_plugin_fixture_registered_and_asserting(tmp_path, pytester):
+    pytester.makepyfile(PLUGIN)
+    # Expose the shipped fixture via conftest instead of -p: when the package is
+    # pip-installed (CI), its pytest11 entry point already registers the plugin,
+    # and an explicit -p load makes pluggy reject the double registration.
+    # The conftest import works in both installed and PYTHONPATH-only runs.
+    pytester.makeconftest("from crashresume.pytest_plugin import conform  # noqa: F401")
+    result = pytester.runpytest()
+    assert result.ret == 0