State Capsule: definition and contract

A State Capsule declares the product conditions required to execute a Journey Version. It reconstructs the actor, role, permissions, plan, data, flags, authentication, locale, timezone, theme, viewport, clock, and allowed side effects that determine whether the intended outcome can occur.

Why state is part of the contract

Replaying the same clicks does not reproduce the same product behavior when account permissions, plan capacity, test data, feature flags, locale, or clock differ. Without explicit state, failures are often misclassified as product regressions or dismissed as flaky automation.

A State Capsule makes those dependencies reviewable before the Run starts and inspectable afterward.

What a State Capsule should declare

• actor identity class and workspace role;
• authentication method without embedding reusable secrets;
• plan and entitlement state;
• deterministic data or seed references;
• relevant feature flags and experiments;
• locale, timezone, direction, theme, and motion preferences;
• browser and viewport context;
• fixed or bounded clock behavior;
• allowed external and product side effects;
• cleanup and isolation requirements.

State Capsule versus stored session

A stored browser session may be one input to state reconstruction. It is not the whole State Capsule. The capsule also explains which actor that session represents, where it is valid, when it expires, which data and permissions it expects, and what the Run may change.

Secrets remain protected configuration. The capsule retains the policy and provenance needed to understand their use, not plaintext credentials.

Example: invite a teammate near the plan limit

One State Capsule may represent an owner with two available seats. Another may represent the same owner at the seat limit. The path can be identical while the valid outcomes differ: the first creates an invitation; the second presents a capacity consequence without pretending the Journey succeeded.

The resulting Observation records which state actually executed. Review can then distinguish a product failure from a state, policy, target, or infrastructure failure. See Runs and verification for the execution surface.