Compatibility & versioning

Hopskip is Draft 0.1, pre-1.0. This page is what you can depend on today. Three surfaces carry a distinct stability contract; everything else churns freely until GA.

The three stable surfaces

Surface	Contract	Status
Workflow ABI (`hopskip:workflow@x`)	Frozen per version; additions are new versioned modules	In effect now
Dispatch protobuf (`hopskip.dispatch.v1`)	Additive-only	In effect
Event envelope (`hopskip.event.v1.EventEnvelope`)	Additive-only	Arming at M1

Workflow ABI - `hopskip:workflow@x`

This is the tightest contract and the only one already fully armed with automated enforcement. hopskip:workflow@0.1’s import surface is seven imports and does not gain an eighth:

now            random_seed    sleep          invoke_activity
await_result   emit_searchable  log

The canonical (name, param count, result count) list is asserted byte-for-byte by a test that fails loudly if the surface drifts from seven. Additions ship as a new versioned module (hopskip:workflow@0.2, and so on), never by widening @0.1. This is what lets histories remain interchangeable across SDKs and across time.

Dispatch protobuf - `hopskip.dispatch.v1`

The worker/Core dispatch protocol is additive-only: new fields may be added, existing fields never change meaning or number. A worker built against an older minor can talk to a newer Core and vice versa.

Event envelope - `hopskip.event.v1.EventEnvelope`

The envelope carries the protocol fields every event needs before anything consumes them: prev-hash, OIDC principal, schema_id, HLC timestamp, fencing token, partition sequence. Its contract is additive-only and arms at milestone M1. Envelope changes after data exists are migrations, so the wire format is treated as near-frozen.

Everything else churns

None of these promises extends to anything not named above. These move freely until GA:

the snapshot wire format,
WIT contract shapes,
replay-engine internals,
the CLI and registry, and
SDK ergonomics beyond the ABI boundary: the package names and helper APIs in the SDK guides are illustrative of intent and will change.

Deploying across versions

Within a workflow version, hop deploy gates on replay-breaking changes by diffing the compiled control-flow graph against the deployed one. When a change would break in-flight workflows, you have two options:

Ship it as a new versioned workflow type, leaving in-flight instances on the old version, or
Provide a state migration.

Because events are self-describing and tagged with a schema_id, there are no offline schema migrations against the store itself. See Event store & audit.

The determinism guarantee is not negotiable

One invariant sits above the version policy: replay divergence, snapshot/replay divergence, or fuzz nondeterminism is a release blocker with no override path. Compatibility gating exists to protect it. See Determinism & the sandbox.