Dataoad GitHub
v0.1.0 · Alpha · Open source

Execution contracts for side-effecting AI actions.

An open-source Python library and failure harness for the moment after an agent asks: did that action actually happen?

A timeout does not prove an action failed.

A successful tool call does not necessarily prove the intended external effect occurred.

Try v0.1.0 in 5 minutes Inspect v0.1.0
  • Python 3.11+
  • Apache-2.0
  • Local-first
  • Typed

The dangerous gap is between

response received ≠ external effect known

The evidence model

Three states. No optimistic guesses.

Dataoad separates execution signals from evidence about the intended external effect. Ambiguity is a result, not an error to hide.

01

CONFIRMED

Sufficient trustworthy evidence says the intended effect happened.

Default: do not retry.
02

FAILED

Sufficient evidence says the intended effect did not happen.

Retry only when policy and evidence permit.
03

UNKNOWN

There is not enough trustworthy evidence to know what happened.

Default: never automatically retry.

retry_on_unknown=True is an explicit, warning-emitting escape hatch. It can duplicate real-world side effects.

The execution contract

Coordinate the claim. Preserve the evidence.

The durable receipt connects an idempotency claim, the attempted mutation, and later read-only verification without pretending a network response is external truth.

Replay

Same key and request return the existing receipt.

Conflict

Same key with a different request fails before mutation.

Identity

Verification binds evidence to the intended external effect.

Local claim deduplication coordinates callers sharing a ledger. It does not make a remote API idempotent.

  1. 01
    Durable claim key + request hash
  2. 02
    Mutation attempt side effect may occur
  3. 03
    Evidence receipt never erase ambiguity
  4. 04
    Read-only verification reconcile external truth
reconcile.py Python 
# A timeout remains explicit.
result = await runner.execute(...)

if result.status is UNKNOWN:
    result = await runner.reconcile(
        result.receipt.action_id,
        verifier,
    )

The fault harness

Break it before an agent gets the tool.

The bundled payment example injects deterministic failures on both sides of commit and reports only what those scenarios establish.

Adversarial scenarios

  • 01 duplicate replay
  • 02 concurrent duplicates
  • 03 same-key / different-payload conflict
  • 04 timeout before and after commit
  • 05 unavailable or unhealthy verification
  • 06 wrong external identity
  • 07 contradictory evidence
  • 08 stranded-claim recovery
Install the library From PyPI, pinned to v0.1.0 
python -m pip install dataoad==0.1.0
Run the complete harness From a repository checkout 
git clone --branch v0.1.0 --depth 1 https://github.com/getdatoad/datoad.git
cd datoad
python -m pip install .
dataoad test examples/payment_timeout_after_commit.py
Final classification SAFE UNDER TESTED CONDITIONS

Deterministic scenarios only—not formal verification or a universal safety claim.

Agent-native distribution

Put the safety contract inside your coding agent.

The same skills-only plugin works in Codex and Claude Code. It audits mutation adapters, idempotency, ambiguous failures, and verifier evidence without adding an MCP server or authorizing a live side effect.

01

Codex

public repo

Add Dataoad as a marketplace, install the plugin, then start a new task so Codex can discover the bundled skill. 

codex plugin marketplace add getdatoad/datoad --ref main
codex plugin add dataoad-safety@dataoad
Try it Use $audit-side-effecting-action to audit this payment adapter.
02

Claude Code

native plugin

Dataoad also ships Claude Code's native plugin and marketplace manifests. The reusable skill is shared; only the packaging and invocation syntax differ. 

claude plugin marketplace add getdatoad/datoad@main
claude plugin install dataoad-safety@dataoad
Invoke directly /dataoad-safety:audit-side-effecting-action

Auditing remains read-only unless you explicitly request a code change. Neither plugin treats testing as permission to charge, refund, email, deploy, or perform another live mutation.

Honest boundaries

What v0.1.0 does—and doesn’t claim.

Dataoad is an early, local-first contract and test harness. Its value is making uncertainty visible, not promising it away.

What it does

  • Explicit external-effect evidence states
  • Durable local receipts with memory or SQLite
  • Replay and request-conflict semantics
  • Read-only reconciliation contracts
  • Deterministic concurrency and failure injection

What it does not claim

  • Exactly-once execution
  • Remote provider idempotency
  • Production readiness
  • Multi-host coordination or provider integrations
  • Formal verification or universal safety

v0.1 external breakage phase

Break the contract.

Built from failure modes practitioners described. Find the race, missing invariant, or real workflow that breaks the model.

Open a hostile issue Report a broken invariant Read the full contract

What real-world action would break Dataoad's assumptions?