resume-guard 1.0.0__tar.gz

resume_guard-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TextForAgents LLC
+
+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.

resume_guard-1.0.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: resume-guard
+Version: 1.0.0
+Summary: Resume-effect reconciliation for checkpointed agent runs: checkpoint-keyed effect ledger, read-only probe, Ed25519-signed resume verdicts.
+Author: TextForAgents LLC
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Dynamic: license-file
+
+# resume_guard
+
+Resume-effect reconciliation for checkpointed agent runs — by TextForAgents LLC.
+
+Before a checkpointed agent run resumes, ask what already landed. An effect
+ledger keyed to checkpoint identity, a read-only probe of the target system
+when the ledger is silent, and an Ed25519-signed verdict — SAFE /
+RESUME-WITH-SKIPS / DO-NOT-RESUME — so a resumed node never re-sends the paid
+call, re-books the booking, or records an approval against work the human
+never saw.
+
+## Quickstart
+
+```python
+from resume_guard import EffectLedger, TargetSystem, Reconciler, GuardedEffects
+
+ledger = EffectLedger("effects.db")
+target = TargetSystem("target.json")
+rec = Reconciler(ledger, {"paid_job": target})
+guard = GuardedEffects(ledger, rec)
+
+receipt, how = guard.run_effect("run-1", "ns-1", "book_and_pay",
+                                "submit-job", "paid_job",
+                                lambda eid: target.submit(eid, {"job": "gpu-job-1"}))
+# kill the process here; on resume the same call returns ("...", "injected")
+# and the effect function is never called again.
+verdict = rec.verdict("run-1", "ns-1", "book_and_pay",
+                      [{"effect_key": "submit-job", "kind": "paid_job"}])
+assert verdict["verdict"]["state"] == "RESUME-WITH-SKIPS"
+assert Reconciler.verify(verdict)
+print("exactly one execution:", target.submit_calls == 1)
+```
+
+Hosted service: Solo $9/mo per operator (first month free, one-time trial) ·
+Team $29/mo · per-verdict API $0.005 (x402). Support: support@textforagents.com

resume_guard-1.0.0/README.md

@@ -0,0 +1,35 @@
+# resume_guard
+
+Resume-effect reconciliation for checkpointed agent runs — by TextForAgents LLC.
+
+Before a checkpointed agent run resumes, ask what already landed. An effect
+ledger keyed to checkpoint identity, a read-only probe of the target system
+when the ledger is silent, and an Ed25519-signed verdict — SAFE /
+RESUME-WITH-SKIPS / DO-NOT-RESUME — so a resumed node never re-sends the paid
+call, re-books the booking, or records an approval against work the human
+never saw.
+
+## Quickstart
+
+```python
+from resume_guard import EffectLedger, TargetSystem, Reconciler, GuardedEffects
+
+ledger = EffectLedger("effects.db")
+target = TargetSystem("target.json")
+rec = Reconciler(ledger, {"paid_job": target})
+guard = GuardedEffects(ledger, rec)
+
+receipt, how = guard.run_effect("run-1", "ns-1", "book_and_pay",
+                                "submit-job", "paid_job",
+                                lambda eid: target.submit(eid, {"job": "gpu-job-1"}))
+# kill the process here; on resume the same call returns ("...", "injected")
+# and the effect function is never called again.
+verdict = rec.verdict("run-1", "ns-1", "book_and_pay",
+                      [{"effect_key": "submit-job", "kind": "paid_job"}])
+assert verdict["verdict"]["state"] == "RESUME-WITH-SKIPS"
+assert Reconciler.verify(verdict)
+print("exactly one execution:", target.submit_calls == 1)
+```
+
+Hosted service: Solo $9/mo per operator (first month free, one-time trial) ·
+Team $29/mo · per-verdict API $0.005 (x402). Support: support@textforagents.com

resume_guard-1.0.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "resume-guard"
+version = "1.0.0"
+description = "Resume-effect reconciliation for checkpointed agent runs: checkpoint-keyed effect ledger, read-only probe, Ed25519-signed resume verdicts."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = ["cryptography>=41"]
+authors = [{name = "TextForAgents LLC"}]
+
+[tool.setuptools.packages.find]
+include = ["resume_guard*"]

resume_guard-1.0.0/resume_guard/__init__.py

@@ -0,0 +1,21 @@
+"""Resume-effect reconciliation (EXP-023, P23) — production build.
+
+Effect ledger keyed to checkpoint identity + signed resume verdicts.
+"""
+from .ledger import EffectLedger, derive_effect_id
+from .target import TargetSystem, TargetUnreachable, TargetAmbiguous
+from .reconciler import Reconciler, TIER_PROBE_CAPS
+from .guard import GuardedEffects
+from .audit import audit_journal
+from .probes import IdempotencyProbe, DictStoreProbe, HttpReadOnlyProbe
+from .adapters import LangGraphAdapter, CopilotJournalReader
+from .keys import generate_key, load_key, pinned_set, key_id_for
+
+__all__ = [
+    "EffectLedger", "derive_effect_id", "TargetSystem",
+    "TargetUnreachable", "TargetAmbiguous", "Reconciler",
+    "TIER_PROBE_CAPS", "GuardedEffects", "audit_journal",
+    "IdempotencyProbe", "DictStoreProbe", "HttpReadOnlyProbe",
+    "LangGraphAdapter", "CopilotJournalReader",
+    "generate_key", "load_key", "pinned_set", "key_id_for",
+]

resume_guard-1.0.0/resume_guard/adapters.py

@@ -0,0 +1,60 @@
+"""Per-framework adapters (packet 04 hardening item 2).
+
+Adapters translate framework checkpoint shapes into the framework-
+neutral core's (run_id, checkpoint_ns, node) identity. No framework
+types and no framework verdict logic live in the core; adapters hold
+only shape translation.
+"""
+import json
+
+
+class LangGraphAdapter:
+    """LangGraph checkpointer hook shape (proven by harness_langgraph.py).
+
+    LangGraph checkpoints carry config.configurable.thread_id and
+    checkpoint metadata; a checkpointer hook receives (config,
+    checkpoint) pairs. This adapter extracts the neutral identity
+    from those plain dict shapes — it imports nothing from langgraph.
+    """
+    def identity_from_config(self, config, node):
+        cfg = (config or {}).get("configurable", {})
+        run_id = cfg.get("thread_id") or cfg.get("run_id") or ""
+        ns = cfg.get("checkpoint_ns") or ""
+        if not run_id:
+            raise ValueError("langgraph config missing thread_id")
+        return run_id, ns, node
+
+    def identity_from_checkpoint(self, checkpoint, node):
+        ck = checkpoint or {}
+        run_id = ck.get("id") or ck.get("thread_id") or ""
+        ns = ck.get("checkpoint_ns") or ck.get("ns") or ""
+        if not run_id:
+            raise ValueError("checkpoint missing id")
+        return str(run_id), str(ns), node
+
+    def declared_from_checkpoint(self, checkpoint, node):
+        """Effects a node declared, read from checkpoint channel values."""
+        vals = (checkpoint or {}).get("channel_values", {}) or {}
+        raw = vals.get("declared_effects", [])
+        return [{"effect_key": e["effect_key"], "kind": e["kind"]}
+                for e in raw if e.get("node", node) == node]
+
+
+class CopilotJournalReader:
+    """Copilot dynamic-workflow journal reader: parses a journal
+    (JSON-lines text, list of dicts, or file-like lines) into the
+    journal-completeness audit's [{node, effect_key, kind}] shape."""
+    def read(self, journal):
+        entries = []
+        if isinstance(journal, str):
+            lines = [ln for ln in journal.splitlines() if ln.strip()]
+            items = [json.loads(ln) for ln in lines]
+        else:
+            items = list(journal)
+        for it in items:
+            node = it.get("node") or it.get("step") or it.get("name")
+            key = it.get("effect_key") or it.get("key") or it.get("idempotency_key")
+            kind = it.get("kind") or it.get("effect_kind") or "paid_job"
+            if node and key:
+                entries.append({"node": node, "effect_key": key, "kind": kind})
+        return entries

resume_guard-1.0.0/resume_guard/audit.py

@@ -0,0 +1,68 @@
+"""Journal-completeness audit — the crash-side inverse (CARD-022
+evidence 2): a runtime refused resume because the run never settled
+at a controlled checkpoint, even though its journal held complete
+records of the steps that finished.
+
+The audit certifies each journaled step independently: a step is
+certified iff its effect is proven landed by the ledger or by a
+target probe. A signed certificate is issued only when EVERY step
+certifies; otherwise the report names the uncertified steps and no
+certificate is issued (partial credit is reported, never certified).
+"""
+import json
+import time
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey)
+
+
+def _canonical(obj):
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+
+
+def audit_journal(ledger, targets, run_id, checkpoint_ns, journal,
+                  signing_key=None):
+    """journal: [{node, effect_key, kind}] — steps the killed run's
+    journal claims completed. Returns a report dict; 'certificate'
+    is present only on full certification."""
+    key = signing_key or Ed25519PrivateKey.generate()
+    steps = []
+    all_ok = True
+    for entry in journal:
+        eid_row = ledger.get_by_identity(run_id, checkpoint_ns,
+                                         entry["node"],
+                                         entry["effect_key"])
+        status = "uncertified"
+        evidence = None
+        if eid_row and eid_row["status"] == "LANDED":
+            status, evidence = "certified", "ledger:landed"
+        else:
+            target = targets.get(entry["kind"])
+            if target is not None:
+                try:
+                    from .ledger import derive_effect_id
+                    eid = derive_effect_id(run_id, checkpoint_ns,
+                                           entry["node"],
+                                           entry["effect_key"])
+                    if target.lookup(eid) is not None:
+                        status, evidence = "certified", "probe:landed"
+                except Exception as e:
+                    evidence = "probe_failed: %s" % e
+            if evidence is None:
+                evidence = "no evidence of landing"
+        if status != "certified":
+            all_ok = False
+        steps.append({"node": entry["node"],
+                      "effect_key": entry["effect_key"],
+                      "status": status, "evidence": evidence})
+    report = {"run_id": run_id, "checkpoint_ns": checkpoint_ns,
+              "audited": time.time(), "steps": steps,
+              "certified": all_ok}
+    if all_ok:
+        sig = key.sign(_canonical(report))
+        from .keys import key_id_for
+        pub = key.public_key().public_bytes_raw()
+        report["certificate"] = {
+            "signature": sig.hex(), "key_id": key_id_for(pub),
+            "public_key": pub.hex()}
+    return report

resume_guard-1.0.0/resume_guard/guard.py

@@ -0,0 +1,56 @@
+"""Wrapper SDK: the code a node actually calls.
+
+run_effect() is the whole integration surface:
+  - First execution: claim INTENT (durable) -> execute -> record
+    LANDED (durable) -> return the fresh result.
+  - On resume (node re-executes from its first line, per LangGraph
+    semantics): the ledger already holds LANDED, so the recorded
+    result is injected and the effect function is NEVER called again.
+  - Concurrent duplicate resume: the atomic intent claim means only
+    one caller executes; the other reconciles against the ledger /
+    probe instead of executing.
+"""
+import time
+
+from .ledger import derive_effect_id
+
+
+class EffectAlreadyInFlight(Exception):
+    pass
+
+
+class GuardedEffects:
+    def __init__(self, ledger, reconciler=None):
+        self.ledger = ledger
+        self.reconciler = reconciler
+
+    def run_effect(self, run_id, checkpoint_ns, node, effect_key, kind,
+                   fn, wait_seconds=5.0):
+        eid = derive_effect_id(run_id, checkpoint_ns, node, effect_key)
+        row = self.ledger.get(eid)
+        if row and row["status"] == "LANDED":
+            return row["result"], "injected"
+        eid2, existing = self.ledger.claim_intent(
+            run_id, checkpoint_ns, node, effect_key, kind)
+        if existing is not None:
+            if existing["status"] == "LANDED":
+                return existing["result"], "injected"
+            # Another caller holds INTENT. Two cases look identical
+            # here — a LIVE concurrent resume mid-execution, and a
+            # crash between intent and landed — and they demand
+            # opposite handling, so the guard never executes on
+            # probe-absence (audit fix, EXP-023 session 1: a
+            # probe-takeover path let 6 of 8 concurrent resumes
+            # execute). Wait for the live holder to land; if nobody
+            # lands it, raise — crash recovery is the reconciler's
+            # verdict decision, not a guard takeover.
+            deadline = time.time() + wait_seconds
+            while time.time() < deadline:
+                row = self.ledger.get(eid)
+                if row and row["status"] == "LANDED":
+                    return row["result"], "injected"
+                time.sleep(0.01)
+            raise EffectAlreadyInFlight(eid)
+        result = fn(eid)
+        self.ledger.record_landed(eid, result)
+        return result, "executed"

resume_guard-1.0.0/resume_guard/keys.py

@@ -0,0 +1,40 @@
+"""Production signing-key management (packet 04 hardening item 1).
+
+The production Ed25519 private key is generated on the droplet and
+held ONLY in the product's own env/secrets file (mode 0600) as
+RESUME_GUARD_SIGNING_KEY_HEX, together with RESUME_GUARD_KEY_ID.
+Rotation: generate a new key, move the old {key_id: public_key_hex}
+into RESUME_GUARD_PREVIOUS_KEYS (JSON), and operators pin by key_id —
+verdicts signed under a retired key-id still verify against the
+pinned set, and a key that silently changes fails verification
+because the pinned public key will not match.
+"""
+import hashlib
+import json
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey)
+
+
+def key_id_for(public_bytes):
+    return "ed25519-" + hashlib.sha256(public_bytes).hexdigest()[:16]
+
+
+def generate_key():
+    key = Ed25519PrivateKey.generate()
+    pub = key.public_key().public_bytes_raw()
+    return {"private_key_hex": key.private_bytes_raw().hex(),
+            "public_key_hex": pub.hex(), "key_id": key_id_for(pub)}
+
+
+def load_key(private_key_hex):
+    key = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(private_key_hex))
+    pub = key.public_key().public_bytes_raw()
+    return key, key_id_for(pub), pub.hex()
+
+
+def pinned_set(current_key_id, current_public_hex, previous_json=""):
+    pinned = {current_key_id: current_public_hex}
+    if previous_json:
+        pinned.update(json.loads(previous_json))
+    return pinned

resume_guard-1.0.0/resume_guard/ledger.py

@@ -0,0 +1,147 @@
+"""Effect ledger keyed to checkpoint identity.
+
+Durability is the point: the framework default (async checkpoint
+writes) is exactly what loses the record that a paid call happened
+(CARD-022, 3/3 in the repro). This ledger uses sqlite WAL with
+synchronous=FULL, and every state transition is committed before the
+caller proceeds — INTENT is durable *before* the effect executes,
+LANDED is durable before the node continues.
+
+Concurrency shape (audit fix, EXP-023 session 1): resumes happen in
+DIFFERENT processes in real deployments, so the database file — not
+an in-process object — is the shared state. Every operation opens
+its own connection (WAL + busy_timeout serializes writers at the DB
+level), and the effects PRIMARY KEY is the atomic claim. The first
+implementation shared one connection across threads; the stress
+harness showed statement-level crosstalk on the shared connection
+(InterfaceError, and a loser's connection-wide rollback() deleting
+the winner's uncommitted INTENT — 86/200 trials double-executed).
+Per-operation connections: 0/200.
+"""
+import hashlib
+import json
+import sqlite3
+import time
+
+
+def derive_effect_id(run_id, checkpoint_ns, node, effect_key):
+    raw = "|".join([run_id, checkpoint_ns, node, effect_key])
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+class LedgerCorrupt(Exception):
+    pass
+
+
+class EffectLedger:
+    def __init__(self, path):
+        self.path = path
+        try:
+            db = self._connect()
+            try:
+                db.execute(
+                    "CREATE TABLE IF NOT EXISTS effects ("
+                    " effect_id TEXT PRIMARY KEY,"
+                    " run_id TEXT, checkpoint_ns TEXT, node TEXT,"
+                    " effect_key TEXT, kind TEXT, status TEXT,"
+                    " result_json TEXT, source TEXT, updated REAL)")
+                db.execute(
+                    "CREATE TABLE IF NOT EXISTS checkpoints ("
+                    " run_id TEXT, checkpoint_ns TEXT,"
+                    " discovery_pin TEXT, updated REAL,"
+                    " PRIMARY KEY (run_id, checkpoint_ns))")
+                db.commit()
+            finally:
+                db.close()
+        except sqlite3.DatabaseError as e:
+            raise LedgerCorrupt(str(e)) from e
+
+    def _connect(self):
+        db = sqlite3.connect(self.path, timeout=10.0)
+        db.execute("PRAGMA journal_mode=WAL")
+        db.execute("PRAGMA synchronous=FULL")
+        db.execute("PRAGMA busy_timeout=10000")
+        return db
+
+    def close(self):
+        pass  # per-operation connections; nothing held open
+
+    # -- checkpoint discovery pin (EXCHANGE-034) ----------------------
+    def pin_discovery(self, run_id, checkpoint_ns, discovery_pin):
+        db = self._connect()
+        try:
+            db.execute(
+                "INSERT OR REPLACE INTO checkpoints VALUES (?,?,?,?)",
+                (run_id, checkpoint_ns, discovery_pin, time.time()))
+            db.commit()
+        finally:
+            db.close()
+
+    def discovery_pin(self, run_id, checkpoint_ns):
+        db = self._connect()
+        try:
+            cur = db.execute(
+                "SELECT discovery_pin FROM checkpoints WHERE run_id=? AND checkpoint_ns=?",
+                (run_id, checkpoint_ns))
+            row = cur.fetchone()
+            return row[0] if row else None
+        finally:
+            db.close()
+
+    # -- effect lifecycle ----------------------------------------------
+    def claim_intent(self, run_id, checkpoint_ns, node, effect_key, kind):
+        """Atomically claim the right to execute this effect.
+
+        Returns (effect_id, existing_row_or_None). The PRIMARY KEY
+        insert on a fresh connection IS the claim: exactly one
+        caller (thread or process) wins it; everyone else gets the
+        existing row and must NOT execute.
+        """
+        eid = derive_effect_id(run_id, checkpoint_ns, node, effect_key)
+        db = self._connect()
+        try:
+            try:
+                db.execute(
+                    "INSERT INTO effects VALUES (?,?,?,?,?,?, 'INTENT', NULL, 'ledger', ?)",
+                    (eid, run_id, checkpoint_ns, node, effect_key, kind,
+                     time.time()))
+                db.commit()
+                return eid, None
+            except sqlite3.IntegrityError:
+                db.rollback()
+        finally:
+            db.close()
+        return eid, self.get(eid)
+
+    def record_landed(self, effect_id, result, source="ledger"):
+        db = self._connect()
+        try:
+            db.execute(
+                "UPDATE effects SET status='LANDED', result_json=?, source=?, updated=? WHERE effect_id=?",
+                (json.dumps(result, sort_keys=True), source, time.time(),
+                 effect_id))
+            db.commit()
+        finally:
+            db.close()
+
+    def get(self, effect_id):
+        db = self._connect()
+        try:
+            cur = db.execute(
+                "SELECT effect_id, run_id, checkpoint_ns, node, effect_key,"
+                " kind, status, result_json, source FROM effects WHERE effect_id=?",
+                (effect_id,))
+            row = cur.fetchone()
+        finally:
+            db.close()
+        if row is None:
+            return None
+        return {"effect_id": row[0], "run_id": row[1],
+                "checkpoint_ns": row[2], "node": row[3],
+                "effect_key": row[4], "kind": row[5], "status": row[6],
+                "result": json.loads(row[7]) if row[7] else None,
+                "source": row[8]}
+
+    def get_by_identity(self, run_id, checkpoint_ns, node, effect_key):
+        return self.get(derive_effect_id(run_id, checkpoint_ns, node,
+                                         effect_key))

resume_guard-1.0.0/resume_guard/probes.py

@@ -0,0 +1,59 @@
+"""Read-only probe framework (packet 04 hardening item 3).
+
+A probe can ONLY look up an effect by idempotency key. By
+construction there is no submit/execute/run method on any probe
+class, so a probe can never cause an effect (lab invariant: 50
+probes -> 0 submissions). Effect classes whose only lookup is not
+read-only get NO probe here; the reconciler holds those as
+DO-NOT-RESUME on a silent ledger.
+"""
+import json
+import urllib.request
+
+from .target import TargetUnreachable, TargetAmbiguous
+
+
+class IdempotencyProbe:
+    """Base probe: subclasses implement _fetch(key) -> receipt|None.
+    The public surface is lookup() only."""
+    def lookup(self, idempotency_key):
+        return self._fetch(idempotency_key)
+
+    def _fetch(self, idempotency_key):  # pragma: no cover
+        raise NotImplementedError
+
+
+class DictStoreProbe(IdempotencyProbe):
+    """Probe over a durable JSON store keyed by idempotency key —
+    the generic shape for booking/charge/submission status stores."""
+    def __init__(self, store):
+        self._store = store  # mapping, treated read-only
+
+    def _fetch(self, idempotency_key):
+        rec = self._store.get(idempotency_key)
+        return dict(rec) if rec else None
+
+
+class HttpReadOnlyProbe(IdempotencyProbe):
+    """Probe that performs an HTTP GET ONLY (urllib with an explicit
+    GET; no other method exists in this class). Non-200 -> unreachable,
+    409/ambiguous payload -> ambiguous: both fail closed upstream."""
+    def __init__(self, base_url, timeout=5.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _fetch(self, idempotency_key):
+        url = self.base_url + "/" + idempotency_key
+        req = urllib.request.Request(url, method="GET")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                data = json.loads(r.read().decode())
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return None
+            raise TargetUnreachable("probe HTTP %s" % e.code) from e
+        except Exception as e:
+            raise TargetUnreachable(str(e)) from e
+        if isinstance(data, dict) and data.get("ambiguous"):
+            raise TargetAmbiguous("target cannot confirm or deny")
+        return data

resume_guard-1.0.0/resume_guard/reconciler.py

@@ -0,0 +1,194 @@
+"""The reconciler: before a node re-executes, decide whether it may.
+
+Verdict states:
+  SAFE             — no declared effect landed; re-execution is safe.
+  RESUME-WITH-SKIPS— some effects already landed; inject their recorded
+                     results instead of re-running them.
+  DO-NOT-RESUME    — ambiguous effect state, probe failure, discovery
+                     drift, or corrupt ledger; a human gets the
+                     evidence packet.
+
+Evidence order per effect: (1) the effect ledger; (2) if the ledger
+is silent or holds only INTENT, a probe of the target system keyed by
+the effect's idempotency key (EXCHANGE-031). A probe that finds the
+effect backfills the ledger (source='probe') so the next resume is
+ledger-cheap. Probing never executes anything.
+
+Precondition (EXCHANGE-034): if the checkpoint carries a discovery
+pin and the current discovery digest differs, any verdict escalates
+to DO-NOT-RESUME — the recorded effects were produced under different
+instructions than the ones now framing the agent.
+
+Verdicts are Ed25519-signed over their canonical JSON; verify()
+rejects any tampering.
+"""
+import json
+import time
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey)
+from cryptography.exceptions import InvalidSignature
+
+from .ledger import derive_effect_id, LedgerCorrupt
+from .target import TargetUnreachable, TargetAmbiguous
+
+
+def _canonical(obj):
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+
+
+TIER_PROBE_CAPS = {"solo": 20, "team": 100}
+
+
+def key_id_for(public_bytes):
+    import hashlib
+    return "ed25519-" + hashlib.sha256(public_bytes).hexdigest()[:16]
+
+
+class Reconciler:
+    def __init__(self, ledger, targets, signing_key=None, key_id=None):
+        """targets: {kind: TargetSystem-like with .lookup(key)}"""
+        self.ledger = ledger
+        self.targets = targets
+        self.key = signing_key or Ed25519PrivateKey.generate()
+        self.key_id = key_id or key_id_for(
+            self.key.public_key().public_bytes_raw())
+
+    # ---------------------------------------------------------------
+    def verdict(self, run_id, checkpoint_ns, node, declared_effects,
+                current_discovery_digest=None, tier=None, probe_cap=None):
+        """declared_effects: [{effect_key, kind}] for the node about
+        to re-execute."""
+        body = {"run_id": run_id, "checkpoint_ns": checkpoint_ns,
+                "node": node, "issued": time.time(), "effects": [],
+                "state": None, "reasons": []}
+        try:
+            pin = self.ledger.discovery_pin(run_id, checkpoint_ns)
+        except Exception as e:  # corrupt ledger: fail closed
+            body["state"] = "DO-NOT-RESUME"
+            body["reasons"].append("ledger_unreadable: %s" % e)
+            return self._sign(body)
+        if pin is not None and current_discovery_digest is not None \
+                and pin != current_discovery_digest:
+            body["state"] = "DO-NOT-RESUME"
+            body["reasons"].append("discovery_drift: checkpoint pin "
+                                   "does not match current discovery "
+                                   "digest (EXCHANGE-034)")
+            for eff in declared_effects:
+                body["effects"].append(
+                    {"effect_key": eff["effect_key"], "action": "hold"})
+            return self._sign(body)
+
+        # Flat-tier probe caps (packet 03/04): ledger hits are free;
+        # only effects needing a probe count against the cap. Effects
+        # beyond the cap are NOT probed: they are named as
+        # DO-NOT-RESUME evidence (fail-closed, exactly as lab-designed).
+        if probe_cap is None and tier is not None:
+            probe_cap = TIER_PROBE_CAPS.get(str(tier).lower())
+        probes_used = [0]
+
+        def _one(eff):
+            eid = derive_effect_id(run_id, checkpoint_ns, node,
+                                   eff["effect_key"])
+            try:
+                row = self.ledger.get(eid)
+            except Exception:
+                row = None
+            needs_probe = not (row and row["status"] == "LANDED")
+            if needs_probe and probe_cap is not None:
+                if probes_used[0] >= probe_cap:
+                    return {"effect_key": eff["effect_key"],
+                            "kind": eff["kind"], "effect_id": eid,
+                            "action": "hold",
+                            "evidence": "probe_cap_exceeded: unprobed "
+                            "remainder is DO-NOT-RESUME evidence "
+                            "(cap=%d)" % probe_cap}
+                probes_used[0] += 1
+            return self._reconcile_one(run_id, checkpoint_ns, node, eff)
+
+        any_skip = False
+        any_ambiguous = False
+        for eff in declared_effects:
+            entry = _one(eff)
+            body["effects"].append(entry)
+            if entry["action"] == "skip":
+                any_skip = True
+            elif entry["action"] == "hold":
+                any_ambiguous = True
+        if any_ambiguous:
+            body["state"] = "DO-NOT-RESUME"
+            body["reasons"].append("ambiguous effect state — see "
+                                   "per-effect evidence")
+        elif any_skip:
+            body["state"] = "RESUME-WITH-SKIPS"
+        else:
+            body["state"] = "SAFE"
+        return self._sign(body)
+
+    def _reconcile_one(self, run_id, checkpoint_ns, node, eff):
+        key = eff["effect_key"]
+        kind = eff["kind"]
+        eid = derive_effect_id(run_id, checkpoint_ns, node, key)
+        out = {"effect_key": key, "kind": kind, "effect_id": eid}
+        try:
+            row = self.ledger.get(eid)
+        except Exception as e:
+            out.update(action="hold", evidence="ledger_unreadable: %s" % e)
+            return out
+        if row and row["status"] == "LANDED":
+            out.update(action="skip", evidence="ledger:landed",
+                       result=row["result"])
+            return out
+        # Ledger silent or INTENT-only: probe the target (EXCHANGE-031).
+        target = self.targets.get(kind)
+        if target is None:
+            out.update(action="hold",
+                       evidence="no probe surface for kind %s" % kind)
+            return out
+        try:
+            receipt = target.lookup(eid)
+        except (TargetUnreachable, TargetAmbiguous) as e:
+            out.update(action="hold", evidence="probe_failed: %s" % e)
+            return out
+        if receipt is not None:
+            # Ground truth: it landed. Backfill so the next verdict
+            # is ledger-cheap, then skip with the probed result.
+            if row is None:
+                self.ledger.claim_intent(run_id, checkpoint_ns, node,
+                                         key, kind)
+            self.ledger.record_landed(eid, receipt, source="probe")
+            out.update(action="skip", evidence="probe:landed",
+                       result=receipt)
+            return out
+        out.update(action="rerun", evidence="probe:absent")
+        return out
+
+    # ---------------------------------------------------------------
+    def _sign(self, body):
+        sig = self.key.sign(_canonical(body))
+        return {"verdict": body, "signature": sig.hex(), "key_id": self.key_id,
+                "public_key": self.key.public_key().public_bytes_raw().hex()}
+
+    @staticmethod
+    def verify(signed, pinned=None):
+        """Verify a signed verdict. If `pinned` is given ({key_id:
+        public_key_hex} — the operator's pinned key set, which is how
+        rotation is handled: old key-ids stay verifiable), the
+        verdict's key_id must be in the set and its public_key must
+        match the pinned value."""
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+            Ed25519PublicKey)
+        try:
+            if pinned is not None:
+                kid = signed.get("key_id")
+                if kid not in pinned:
+                    return False
+                if pinned[kid] != signed["public_key"]:
+                    return False
+            pub = Ed25519PublicKey.from_public_bytes(
+                bytes.fromhex(signed["public_key"]))
+            pub.verify(bytes.fromhex(signed["signature"]),
+                       _canonical(signed["verdict"]))
+            return True
+        except (InvalidSignature, Exception):
+            return False

resume_guard-1.0.0/resume_guard/target.py

@@ -0,0 +1,71 @@
+"""Durable test-double target system (paid job submission API shape).
+
+Stands in for the external systems agent nodes act on (submit a paid
+job, book, charge). It is a *double*, not a mock of our own code: it
+keeps its own durable store, dedupes submissions by idempotency key
+the way a well-behaved provider API does, and exposes a read-only
+lookup by idempotency key — the probe surface EXCHANGE-031 requires.
+Fault modes (unreachable / ambiguous) are switchable for adversarial
+tests. Nothing here is a production system.
+"""
+import json
+import os
+import threading
+
+
+class TargetUnreachable(Exception):
+    pass
+
+
+class TargetAmbiguous(Exception):
+    pass
+
+
+class TargetSystem:
+    def __init__(self, path):
+        self.path = path
+        self._lock = threading.Lock()
+        self.mode = "ok"  # ok | unreachable | ambiguous
+        self.submit_calls = 0
+        self.probe_calls = 0
+        self._store = {}
+        if os.path.exists(path):
+            with open(path) as f:
+                self._store = json.load(f)
+
+    def _persist(self):
+        tmp = self.path + ".tmp"
+        with open(tmp, "w") as f:
+            json.dump(self._store, f)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, self.path)
+
+    def submit(self, idempotency_key, payload):
+        """A side effect. Deduped by idempotency key at the provider,
+        but every raw call is counted so tests can detect a guard
+        layer that failed to prevent re-execution."""
+        with self._lock:
+            if self.mode == "unreachable":
+                raise TargetUnreachable("target unreachable")
+            self.submit_calls += 1
+            if idempotency_key in self._store:
+                return dict(self._store[idempotency_key])
+            receipt = {"receipt_id": "rcpt-" + idempotency_key[:12],
+                       "idempotency_key": idempotency_key,
+                       "payload": payload, "status": "submitted"}
+            self._store[idempotency_key] = receipt
+            self._persist()
+            return dict(receipt)
+
+    def lookup(self, idempotency_key):
+        """The probe: read-only. Returns the receipt, None if the
+        effect never landed, raises on unreachable/ambiguous."""
+        with self._lock:
+            if self.mode == "unreachable":
+                raise TargetUnreachable("target unreachable")
+            if self.mode == "ambiguous":
+                raise TargetAmbiguous("target cannot confirm or deny")
+            self.probe_calls += 1
+            rec = self._store.get(idempotency_key)
+            return dict(rec) if rec else None

resume_guard-1.0.0/resume_guard.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: resume-guard
+Version: 1.0.0
+Summary: Resume-effect reconciliation for checkpointed agent runs: checkpoint-keyed effect ledger, read-only probe, Ed25519-signed resume verdicts.
+Author: TextForAgents LLC
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Dynamic: license-file
+
+# resume_guard
+
+Resume-effect reconciliation for checkpointed agent runs — by TextForAgents LLC.
+
+Before a checkpointed agent run resumes, ask what already landed. An effect
+ledger keyed to checkpoint identity, a read-only probe of the target system
+when the ledger is silent, and an Ed25519-signed verdict — SAFE /
+RESUME-WITH-SKIPS / DO-NOT-RESUME — so a resumed node never re-sends the paid
+call, re-books the booking, or records an approval against work the human
+never saw.
+
+## Quickstart
+
+```python
+from resume_guard import EffectLedger, TargetSystem, Reconciler, GuardedEffects
+
+ledger = EffectLedger("effects.db")
+target = TargetSystem("target.json")
+rec = Reconciler(ledger, {"paid_job": target})
+guard = GuardedEffects(ledger, rec)
+
+receipt, how = guard.run_effect("run-1", "ns-1", "book_and_pay",
+                                "submit-job", "paid_job",
+                                lambda eid: target.submit(eid, {"job": "gpu-job-1"}))
+# kill the process here; on resume the same call returns ("...", "injected")
+# and the effect function is never called again.
+verdict = rec.verdict("run-1", "ns-1", "book_and_pay",
+                      [{"effect_key": "submit-job", "kind": "paid_job"}])
+assert verdict["verdict"]["state"] == "RESUME-WITH-SKIPS"
+assert Reconciler.verify(verdict)
+print("exactly one execution:", target.submit_calls == 1)
+```
+
+Hosted service: Solo $9/mo per operator (first month free, one-time trial) ·
+Team $29/mo · per-verdict API $0.005 (x402). Support: support@textforagents.com

resume_guard-1.0.0/resume_guard.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+resume_guard/__init__.py
+resume_guard/adapters.py
+resume_guard/audit.py
+resume_guard/guard.py
+resume_guard/keys.py
+resume_guard/ledger.py
+resume_guard/probes.py
+resume_guard/reconciler.py
+resume_guard/target.py
+resume_guard.egg-info/PKG-INFO
+resume_guard.egg-info/SOURCES.txt
+resume_guard.egg-info/dependency_links.txt
+resume_guard.egg-info/requires.txt
+resume_guard.egg-info/top_level.txt

resume_guard-1.0.0/resume_guard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

resume_guard-1.0.0/resume_guard.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=41

resume_guard-1.0.0/resume_guard.egg-info/top_level.txt

@@ -0,0 +1 @@
+resume_guard

resume_guard-1.0.0/setup.cfg

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

resume_guard-1.0.0/setup.py

@@ -0,0 +1 @@
+from setuptools import setup; setup()