Check before acting

By default, Threadify checks a step just after you report it, and your code carries on without waiting. When an action has consequences you can’t undo, such as a refund, a payment or an agent’s tool call, use a wait. There are two kinds:

Wait	Use it to
`waitFor(step)`	Get permission before doing the work
`success(..., { waitFor: true })`	Get the contract’s verdict after reporting the work

Before the action

const grant = await thread.waitFor('refund', { timeout: 10000 });

// Only reached if the contract allows a refund now.
const receipt = await issueRefund();

await thread.step('refund').addContext(receipt).success();

waitFor checks your role, the step’s prerequisites, the allowed order and the thread’s state. If everything is satisfied, it gives you a grant: permission for one attempt at that step. If a prerequisite is still missing, it waits for it until the timeout. If waitFor throws or times out, don’t do the work. The next report of that step on the same thread object is linked to the grant automatically. A grant only covers the order and the parties. It can’t check data you haven’t sent yet, so content rules are still checked when you report the step.

After reporting the outcome

const result = await thread.step('refund')
  .addContext({ reference: 'PAY-123', amount: 42, currency: 'GBP', receipt: 'RF-12345678' })
  .success('Refund recorded', { waitFor: true, timeout: 10000 });

console.log(result.stepId, result.validation.decision); // "passed"

This works with .failed() too. The step is sent once, and the call returns when Threadify has checked it. If it broke the contract, the call throws with the violation attached. This tells you whether the work was allowed. It can’t undo the work. For that, ask before acting.

Fresh approval for every attempt

Sometimes every attempt needs its own approval. Use must succeed before each invocation:

Feature: repeatable_refund
Version: 1

Rule: Approve an attempt
  When step "approval" is submitted
  Then owner must be "processor"
  And this step is an entry point

Rule: Refund
  When step "refund" is submitted
  Then owner must be "processor"
  And step "approval" must succeed before each invocation

Rule: Finish
  When step "finished" is submitted
  Then owner must be "processor"
  And step "refund" must have succeeded
  And this step is terminal

Each grant uses up the approval, whether the refund then succeeds, fails or is abandoned. Two callers can’t share one approval. A repeatable step can’t be the terminal step, so the contract finishes with a separate finished step.

Recovery

You decided not to act. Release the grant:

await grant.cancel();

This doesn’t give back an approval the grant used up. A permission response was lost (for example, the network dropped). Ask again with the same invocation ID instead of requesting a new grant:

const grant = await thread.waitFor('refund', { invocationId: savedInvocationId });

The ID is on the error. If your process might crash between asking and acting, choose the ID yourself, save it first, and pass it on the first request too. A validation wait timed out after the step was recorded. The error carries the stepId. Wait again without reporting the step twice:

await thread.waitForValidation('refund', error.stepId, { timeout: 30000 });

Grants don’t expire on their own. If a process crashes holding one, recover it with its invocation ID and either use it or cancel it. Threadify makes sure each attempt is recorded once. It can’t make the action itself safe to repeat, so use your payment provider’s or tool’s own idempotency key as well.

Go and Python

	JavaScript	Go	Python
Permission	`thread.waitFor(name, { timeout })`	`thread.WaitFor(ctx, name, &threadify.WaitOptions{Timeout: 10 * time.Second})`	`await thread.wait_for(name, WaitOptions(timeout=10))`
Verdict after reporting	`.success(msg, { waitFor: true })`	`.Success(ctx, msg, threadify.ReportOptions{WaitFor: true})`	`.success(msg, wait_for=True)`
Resume a verdict	`thread.waitForValidation(name, stepId)`	`thread.WaitForValidation(ctx, name, stepID, nil)`	`await thread.wait_for_validation(name, step_id)`
Release a grant	`await grant.cancel()`	`grant.Cancel(ctx)`	`await grant.cancel()`
Timeout unit	milliseconds	`time.Duration`	seconds

In Go, cancelling the ctx cancels the wait. In Python, cancel the task.

With OpenTelemetry

If an operation is already traced, get the grant with the SDK, then put these attributes on the operation’s span instead of reporting a separate step:

threadify.thread_id
threadify.step_name
threadify.invocation_id

Exporting spans on its own can’t stop anything; the span is only sent after the operation has run. See OpenTelemetry.

Get started

Concepts

Contracts

SDKs

Integrations

Operate

GraphQL API