# Stateful and hybrid integrations

Use this reference when a resource, decision, or workflow survives one request.

## Minimum state model

Define:

- stable business and provider identities;
- actors and exact command authority;
- allowed states and transitions;
- expected aggregate version;
- idempotency key and changed-intent conflict behavior;
- event time, receipt time, and ordering rules;
- immutable events and outbox handoff;
- timeout, retry, unknown-outcome, and reconciliation paths;
- privacy class, retention, deletion, and redaction;
- human decisions, separation of duties, cancellation, and terminal states;
- metrics, alerts, recovery, rollback, and independent release evidence.

## Ownership boundary

- Provider state: use only exact documented/observed provider identities and status evidence.
- Application state: own user intent, policies, approvals, workflow continuity, audit, and derived decisions.
- Hybrid state: persist the mapping and reconcile both sides; never let model memory bridge the boundary.

## Retry rule

Retry safe reads within a bounded policy. For a state-changing operation with an uncertain outcome, reconcile by stable business/provider identity before replay. Reuse the same idempotency identity only for the exact same intent; changed intent must conflict.

## Required tests

Cover the complete path plus exact replay, changed-intent conflict, stale version, invalid transition, timeout, provider denial, partial result, reordered/late event, unknown outcome, independent review, cancellation, restart recovery, and secret/private-data rejection.

Use the canonical journey workshop and maintained mini-app rather than inventing lifecycle events or provider writes.

