ProvelyProvely reads the real system after the agent acts, evaluates a versioned completion contract against that evidence, and returns one of five verdicts. The agent never decides.
The agent keeps its write credentials and makes the same API call. A separate verifier reads the provider with read-only credentials and signs a receipt. An agent report is E0, and E0 is never sufficient.
Where does the contract come from?
You pass the agent prompt, the context and the tools. Provely compiles the completion contract, and you confirm it before it runs. You never write the contract by hand.
A language model may propose the contract. The contract decides completion, and a language model judgement is never completion evidence. A part of the task that no contract can check is marked REQUIRES_REVIEW. Read intent compilation.
What are the five concepts that most agent stacks collapse?
Provely keeps five concepts apart in the data model, the API, and the interface.
In words
- Intent: what the user asked for.
- Action: what the agent attempted.
- Acknowledgement: what the provider returned at once.
- Outcome: the observable resulting state.
- Completion: the outcome satisfies the contract. Only this earns VERIFIED.
| Concept | Question it answers | Stripe refund example |
|---|---|---|
| Intent | What did the user ask for? | Refund USD 142.00 to customer cus_8k2. |
| Action | What did the agent attempt? | POST /v1/refunds with an idempotency key. |
| Acknowledgement | What did the provider return at once? | HTTP 200 and a refund object with status: pending. |
| Outcome | What state does the provider hold now? | status: succeeded on a readback. |
| Completion | Does the outcome satisfy the contract? | Amount, charge, and status match. No duplicate. VERIFIED. |
Which states can an operation be in?
An operation moves through one frozen state machine: CREATED, ACTION_STARTED, ACTION_ACCEPTED, OBSERVING, PENDING, and then one terminal state. The terminal states are VERIFIED, CONTRADICTED, FAILED, UNVERIFIABLE, EXPIRED, and HUMAN_REVIEW.
In words
- CREATED moves to ACTION_STARTED when the agent begins the action.
- ACTION_STARTED moves to ACTION_ACCEPTED when the provider acknowledges.
- ACTION_ACCEPTED moves to OBSERVING when the verifier starts to read evidence.
- OBSERVING moves to PENDING while the evidence is not sufficient.
- PENDING moves to VERIFIED, CONTRADICTED, FAILED, UNVERIFIABLE, EXPIRED, or HUMAN_REVIEW.
| Verdict | Meaning | Example |
|---|---|---|
| VERIFIED | Every positive postcondition holds and no negative one holds. | The refund shows succeeded for the right amount and charge. |
| PENDING | The operation can still make progress. | The refund shows pending or requires_action. |
| CONTRADICTED | The evidence shows an outcome the intent does not allow. | Two refunds exist for one operation. |
| FAILED | The provider reports a terminal failure. | The refund shows failed or canceled. |
| UNVERIFIABLE | The evidence never became sufficient. | The readback stayed unavailable until the deadline. |
| HUMAN_REVIEW | A person must decide. | The contract escalates a timeout to a person. |
What are the frozen safety rules?
- A false VERIFIED is the highest-severity defect. When evidence is not sufficient, the answer is UNVERIFIABLE.
- Progress is not failure. While an operation can still complete, the answer is PENDING, never FAILED.
- An agent assertion is never sufficient. E0 cannot support VERIFIED, alone or combined.
- Acknowledgement is never terminal success. HTTP 200 and an object id prove only that a request was accepted.
- Evidence must correlate with the exact operation. A matching state that already existed must not verify.
- The verifier reads with read-only credentials where the provider permits it. The agent never holds them.
A pre-existing refund for the same amount is the classic false proof. A search by amount finds it. A correlation by refund id and payment intent does not.
What does a false completion look like?
A Shopify refund shows it. The mutation succeeds, the Refund object exists, and the webhook fires. The money has not moved: the order transaction is still PENDING. Two promises, two contracts.
In words
- The refundCreate mutation succeeds.
- The Refund object exists and the refunds/create webhook fires. Neither proves that money moved.
- The OrderTransaction still shows PENDING.
- Money moved is not yet true. The financially_completed contract proves it. The created contract does not.
The Shopify page states the contracts and the evidence that separate the two promises.
Why is not all evidence equal?
Provely ranks evidence by its independence from the action path. E0 is the agent word. E5 is an external outcome, such as a bank credit. The runtime prefers the more independent level.
In words
- E0 agent assertion: never sufficient.
- E1 action response: proves acknowledgement, rarely completion.
- E2 provider readback: deterministic state, subject to stale reads.
- E3 provider event: strong timing, needs deduplication and ordering.
- E4 independent system: the provider plus your own ledger.
- E5 external outcome: a bank, a carrier, or a recipient acknowledgement.
What happens between the action and the answer?
In words
- begin: the agent opens an operation against a contract and gets an idempotency key.
- act: the agent makes the provider call with that key.
- action_result: the agent submits the provider acknowledgement.
- verify: the runtime reads the provider and evaluates the contract.
- receipt: the runtime signs the verdict with Ed25519.
const op = await provely.begin({
contract: 'stripe.refund.succeeded',
input: { charge_id, amount_cents: 14200 },
});
const refund = await stripe.refunds.create(
{ charge: charge_id, amount: 14200 },
{ idempotencyKey: op.idempotency_key },
);
await op.actionResult(refund);
const verification = await op.verify();
// verification.verdict is VERIFIED, PENDING, CONTRADICTED, FAILED, or UNVERIFIABLE.
// Report it exactly as returned.Which cases must every skill pass before it ships?
| Scenario | Required verdict |
|---|---|
| Action accepted, terminal success confirmed | VERIFIED |
| Action accepted, provider still transitional | PENDING |
| Provider reports terminal failure | FAILED |
| Correct resource, wrong amount or subject | CONTRADICTED |
| Duplicate side effect for one operation | CONTRADICTED |
| Readback stale inside the consistency window | PENDING |
| Evidence unavailable until the timeout | UNVERIFIABLE |
| Pre-existing matching state, no causal link | Must not verify |
| Webhook duplicated | No duplicate transition |
| Webhook out of order | Reconciled by provider semantics, not arrival order |
| Contract or provider version not supported | UNVERIFIABLE with reason version_unsupported |
Can a plugin change what VERIFIED means?
No. A plugin adds an evidence channel or an operator. The state machine, the verdicts, and the safety rules are frozen.
What does the agent say while the verdict is PENDING?
It says: "The action is accepted but not yet verified. Operation: <id>." Any caller can check that id later.