Beta Release Guarantees
Invariant guarantees only what the current runtime and store boundary enforce. This page is the canonical Beta contract; planned worker, retry, timer, and child-workflow behavior is excluded. When another page is ambiguous, this matrix and the Recovery Contract Matrix define the narrower supported interpretation.
Canonical Beta 2 Contract Matrix
| Guarantee | Beta 2 | Exact boundary |
|---|---|---|
| Atomic event + state + command-intent commit | Yes | A conforming store commits one structurally validated transition with OCC. |
| Optimistic concurrency control | Yes | Stale execution or Session revisions reject the entire commit. |
| Wait re-entry validation | Yes | A live or restored owned Session validates input against the registered committed .wait() boundary. |
| Model proposal authority pinning | Yes | Initial and recovery proposals must match the pre-inference reasoning frame and fresh action surface. |
| Cross-process automatic work redispatch | No | No public pending-command claim/ack worker exists. |
| Exactly-once external effects | No | External providers must enforce stable idempotency identity. |
| Automatic retries | No | Model retries explicitly in a bounded graph or schedule them in the host. |
| Cooperative cancellation | Yes | The runtime commits cancellation and may execute a declared compensation fragment. |
| Forced cancellation of external I/O | No | In-flight provider work can be ambiguous and compensation cannot erase external reality. |
1. Validated Input Becomes History
Workflow input and .wait() input are validated before a transition is committed. Invalid input:
- does not change execution revision,
- does not mutate state,
- does not enter the event log,
- leaves the execution at its current boundary.
The SDK exposes WorkflowInputValidationError, WaitInputValidationError, and WaitBoundaryConflictError for these cases.
2. The Kernel Is the Single Graph Authority
The pure kernel receives compiled IR, current state, and one incoming event. It determines the next state, derived events, and commands. Environmental handlers do not independently advance graph position.
3. Store Commits Are Atomic and Revision-Checked
A conforming RuntimeStore.commitTransition() atomically commits:
- appended runtime events,
- materialized execution state,
- new command intents,
- command acknowledgements.
The commit succeeds only for the expected revision. A stale writer cannot overwrite a newer transition.
Before any official adapter opens its database transaction, validateTransitionCommit() validates the complete structural proposal: one or more contiguous durable events, matching run/workflow identity, canonical IDs for newly written events, exact next revision, supported command records, an optional same-run Session binding, and JSON-serializable durable values. Invalid proposals perform no database mutation; OCC and constraints still run inside the transaction as defense in depth.
4. Event Identity and Revision Are Monotonic per Run
The Host/SDK creates one UUID runId; the pure kernel performs no random generation. Newly written events carry a strictly increasing seq within that run and use ``id = ${runId}:${seq}```. PostgreSQL additionally enforces UNIQUE (run_id, seq)`.
Execution revision advances once for every durable event, not once per commitTransition() call. An atomic commit containing events 8 through 10 moves revision 7 to revision 10. A rejected or rolled-back transition exposes none of its proposed events or revisions, and a retry starts again from the last committed revision.
Legacy histories remain readable and replayable with their original IDs. The runtime does not rewrite or backfill them merely to adopt the new identity format.
5. Capability Intent Precedes Invocation
With a configured store, the Session execution path commits a capability command before invoking its handler. Completion or failure is committed afterward.
If the process dies after an external system accepts the effect but before completion is committed, the provider outcome is ambiguous. The public Beta does not provide a recovery loop. Any store-specific implementation outside the public contract may invoke the effect again, so provider idempotency is required. Therefore:
Invariant provides durable, repeatable intent. Exactly-once external effects require idempotency support from the external system.
The runtime command identity and provider request identity are separate in the current handler contract. See the canonical effect identity example.
6. Reasoning Results and Agent Proposals Have Explicit Authority
Successful model output becomes a validated REASON_COMPLETED event. A model failure becomes REASON_FAILED and can follow a declared fallback edge. Replay consumes committed facts; it does not need to ask the model to recreate a committed result.
For app.agent(), the runtime captures one AgentReasoningAuthority frame before inference. Official adapters preserve every provider tool proposal in order. Zero proposals take the text path, exactly one may proceed to admission, and multiple proposals execute nothing. Before the single candidate can run, its original frame and the fresh runtime action surface must both authorize it. Session/run/boundary drift rejects as STALE_REASONING_FRAME.
Default traces reveal argument shape—not values—and validation path/code. Full reasoning-boundary capture is opt-in and may contain projected input and normalized provider output, so it requires an approved sensitive-data sink.
7. Cancellation Preserves History
session.cancelWorkflow() never erases prior facts. Without a cancellation fragment, the workflow becomes cancelled. With lifecycle.cancel, the kernel enters cancelling, dispatches the compensation graph, and terminates as cancelled or cancellation_failed.
Compensation creates new facts; it does not undo history or guarantee that an external system can reverse an effect.
8. Recovery Building Blocks Are Not Recovery Orchestration
File-backed SQLite and PostgreSQL persist state, event history, command intent, Session context, and leases. Runnable execution IDs are discovered from persisted execution and lease state.
The public RuntimeStore contract does not expose command claim/read or arbitrary-runId runnable-work attachment APIs, and the Beta does not ship a recovery scanner. These are durable storage primitives—not a complete public cross-process work-recovery workflow. Separately, loadOrCreateSession() and restoreSession() can reconstruct a registered active .wait() boundary through the Session's durable activeRunId. The authoritative status for every boundary is the Recovery Contract Matrix.
Mechanism Summary
| Guarantee | Current boundary |
|---|---|
| Invalid input cannot mutate execution truth | SDK validation + zero-commit rejection tests |
| Graph progress is kernel-derived | PureExecutionEngine |
| Transition commit is atomic and OCC-protected | RuntimeStore implementations |
| Capability intent is stored before invocation | Session execution path with configured storage |
| External effects are exactly once | Not guaranteed; provider idempotency is required |
| Agent proposals retain their reasoning authority | Initial and recovery admission frames + fresh authorization |
| Multiple provider tool proposals | All rejected; zero execution |
| Rejected values in default action traces | Excluded; only argument keys and validation path/code are emitted |
| Reason/capability fallback edges | Supported |
| Cancellation compensation | Supported and tested |
| Cross-process recovery | See the canonical Recovery Contract Matrix |
Next Steps
- Runtime Execution — Inspect mechanisms and the Beta support matrix.
- PostgreSQL — Review the production store schema.
- Cancellation & Compensation — Model explicit reversal behavior.