Skip to content

Dataoad v0.1.0

Pre-release
Pre-release

Choose a tag to compare

View all tags
@atikakernel atikakernel released this 23 Aug 18:24
· 74 commits to main since this release
v0.1.0
5993f98

Dataoad v0.1.0 is the first public alpha of an open-source execution contract and deterministic failure harness for side-effecting AI agent actions.

A timeout does not prove an action failed.

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

Naive retry
calls=2
charges=2

Dataoad
execution=UNKNOWN
verification=CONFIRMED
final=CONFIRMED
calls=1
charges=1

Try it

Dataoad requires Python 3.11 or newer.

Install the exact release wheel:

python -m pip install https://github.com/getdatoad/datoad/releases/download/v0.1.0/dataoad-0.1.0-py3-none-any.whl
python -c "from importlib.metadata import version; print(version('dataoad'))"

To run the bundled deterministic fault harness:

git clone --depth 1 --branch v0.1.0 https://github.com/getdatoad/datoad.git
cd datoad
python -m venv .venv

Activate the virtual environment for your shell, then run:

python -m pip install .
dataoad test examples/payment_timeout_after_commit.py

The example is included in repository checkouts and the source distribution, but not in the wheel.

Contract enforced by v0.1.0

  • CONFIRMED, FAILED, and UNKNOWN are distinct evidence states.
  • Ordinary execution errors remain UNKNOWN when the external effect may already have happened.
  • The default policy never automatically retries UNKNOWN.
  • retry_on_unknown=True is an explicit, warned escape hatch that can duplicate side effects.
  • Same-action, same-key, same-request claims replay without invoking the mutation again.
  • Reusing a claim with a different semantic request or provider reference fails as an explicit conflict.
  • Negative verification becomes FAILED only with healthy, conclusive, retry-safe evidence bound to the correct external identity.
  • Contradictory concurrent verification evidence is merged conservatively as UNKNOWN.
  • Lost acknowledgements from durable ledger transitions are never treated as proof that the write did not happen.
  • The safety harness accepts only exact boolean check results; truthy non-booleans cannot produce a passing report.

These properties apply within Dataoad's documented ledger, request, adapter, and verifier contracts. They are not universal guarantees about an external provider.

Deterministic fault harness

The bundled payment suite exercises normal success, explicit pre-side-effect failure, replay and concurrent duplicates, request conflicts, timeouts before and after commit, UNKNOWN retry protection, verifier outages, unhealthy false negatives, wrong external identity, and preservation of earlier ambiguous evidence.

A successful run reports:

SAFE UNDER TESTED CONDITIONS

That classification applies only to the deterministic scenarios executed. It is not formal verification or a universal safety claim.

Compatibility

  • Python 3.11+ package metadata
  • Release CI on Python 3.11 and 3.12
  • Pure-Python py3-none-any wheel
  • No third-party runtime dependencies
  • In-memory and local SQLite ledgers
  • Typed package with py.typed
  • Apache License 2.0

Python versions outside the release CI matrix are not yet claimed as tested.

Important limits

Dataoad v0.1.0 is alpha software for inspection, failure testing, and local integration work.

It does not guarantee exactly-once execution, make arbitrary third-party APIs idempotent, replace provider-side idempotency, provide hosted or multi-host coordination, automatically steal stranded in-flight claims, prove a custom verifier is correct, or include provider integrations, queues, dashboards, authentication, or multi-tenancy.

All cooperating callers must share the same ledger and use a stable action name, idempotency key, complete semantic request, and correct provider reference. Hard process loss may leave a PENDING claim requiring explicit read-only recovery.

Break the contract

Please report a race, failure mode, or integration assumption that Dataoad gets wrong through the broken execution invariant form.

Call out explicitly if the behavior can cause a duplicate side effect, false CONFIRMED, false FAILED, unsafe retry, or false passing harness output. Remove credentials, customer data, provider tokens, and other secrets before posting.

Full contract and examples: https://github.com/getdatoad/datoad#readme

Assets 5
Loading