# Outcomes

What each result status means and how to handle it.

`kaji.execute()` resolves with an `ExecutionResult`:

```ts
type ExecutionResult<Result> =
  | { status: "succeeded"; result: Result; evidence: ExecutionEvidence }
  | {
      status: "denied" | "rejected" | "failed" | "cancelled";
      error: unknown;
      evidence: ExecutionEvidence;
    }
  | { status: "unknown"; error: unknown; evidence: ExecutionEvidence };
```

## Statuses

- **`succeeded`**: the action ran and returned `result`. Use the result.
- **`denied`**: `authorize` did not return `true`, or threw. The action did not run. Show a permission error.
- **`rejected`**: approval was required and not given. The action did not run. Ask for approval or show an error.
- **`failed`**: a definite failure, either a reused key with different input, a `knownFailure()`, or an unexpected internal error before the action started. Handle the error, and retry only if it is safe.
- **`cancelled`**: cancelled before the action started. Nothing ran. If the cancellation came before Kaji claimed the request, nothing is saved and you can retry with the same `idempotencyKey`. If it came after, Kaji saves `cancelled`, and the same key returns it again: use a new key.
- **`unknown`**: the action started but Kaji cannot tell whether it finished. Check the provider before retrying.

`failed` does not say whether a retry would work. That depends on your application.

## Unknown

You get `unknown` when:

- `execute` throws or rejects after it starts, because the side effect may already have happened.
- The request is aborted and `execute` then rejects.
- Kaji cannot save the final result to the store.
- An identical request was already in progress, and this call stopped waiting for it (its signal aborted or `timeoutMs` elapsed). The original may still complete. Retry with the same key to read its result.

Do not retry blindly, and do not treat `unknown` as `failed`. Use `outcome.evidence` and your provider's records to find out what happened. Sending the same request again returns the saved `unknown` and does not run the action again. (A call that stopped waiting is different: nothing was saved for it, and retrying returns the original's real result once it finishes.) Start a new request, with a new `idempotencyKey`, only after you know it is safe.

## Known failures

Throw `knownFailure(cause)` from `execute` when you know the action did not take effect, for example when the provider rejected the request before doing anything. Kaji returns `failed`.

```ts
execute: async (input, context) => {
  try {
    return await provider.refund(input, {
      idempotencyKey: context.idempotencyKey,
      signal: context.signal,
    });
  } catch (cause) {
    if (providerRejectedBeforeCommit(cause)) throw knownFailure(cause);
    throw cause;
  }
},
```

Kaji never guesses this from an error type or message.

## Request errors

`kaji.execute()` rejects, with no status, when the request cannot start at all: an empty `principalId` or `idempotencyKey`, input that fails validation (`InvalidInputError`), input Kaji cannot fingerprint (`UnfingerprintableValueError`), or a store that fails to claim the request (`KajiConfigurationError`).

## Handling

```ts
const outcome = await kaji.execute(refundPayment, request);

switch (outcome.status) {
  case "succeeded":
    return showReceipt(outcome.result);
  case "denied":
    return showPermissionError(outcome.error);
  case "rejected":
    return showApprovalError(outcome.error);
  case "failed":
    return handleFailure(outcome.error);
  case "cancelled":
    return showCancelled(outcome.error);
  case "unknown":
    return checkWithProvider(outcome.evidence);
}
```