Skip to content

stability.md

Latest commit

 

History

History
59 lines (43 loc) · 3.87 KB

stability.md

File metadata and controls

59 lines (43 loc) · 3.87 KB

API Stability Tiers

statekit is v1.0 with a stability commitment, but not every package has the same maturity. This page makes the tiers explicit so you can pick the right tools and know what to pin.

Tier 1 — Stable (semver-protected)

These are the load-bearing parts of the library. We follow semver: no breaking changes within v1.x.

  • Builder API — statekit.NewMachine, MachineBuilder, StateBuilder, TransitionBuilder, RegionBuilder
  • Core types — Event, State, StateID, EventType, Action, Guard, MachineConfig
  • Interpreter — NewInterpreter, Start, Send, State, Matches, Done, Stop, Close, UpdateContext
  • Reflection DSL — MachineDef, StateNode, CompoundNode, FinalNode, ActionRegistry, FromStruct
  • Snapshots — Snapshot, Restore, InterpreterSnapshot
  • Hierarchy + parallel + history + delayed transitions — all builder methods that produce these
  • Plugin system — plugin.Plugin, all hook interfaces, Composite
  • Static analysis — lint.Lint, lint.Linter, Diagnostic, all rule constants
  • Visualization — viz.ParseNativeJSON, export.NativeExporter, ASCII / Mermaid / HTML / TUI renderers
  • Testing utilities — statetest
  • HTTP integration — http.MachineHandler, http.MachineRegistry, middleware
  • OpenTelemetry tracing — otel.TracingInterpreter, otel.TracingHook
  • Prometheus metrics — metrics.MetricsInterpreter
  • Health checks — health package
  • Code generation — generate package + statekit generate CLI
  • Clock injection — Clock, Timer, SystemClock, FakeClock, WithClock

Tier 2 — Experimental (may change in v1.x)

These features ship in v1.0 but explore problem spaces where the right shape isn't fully settled. We may iterate on the API in a future minor release based on real-world usage. Pin the exact version if you depend on them in production today.

  • Actor model — Spawn, SpawnWithContext, ActorRef, SendTo, SendParent, supervision strategies (SupervisionEscalate, SupervisionRecover, SupervisionRestart, SupervisionStop)
  • Persistent interpreter — PersistentInterpreter, EventStore, SnapshotStore, MemoryEventStore, MemorySnapshotStore
  • Distributed execution — DistributedInterpreter, StreamLock, ClusterMembership, StreamRouter, MemoryStreamLock, ConsistentHashRouter
  • Machine composition — InvokeMachine, MachineInvokeBuilder, WithChildMachine
  • MCP integration — mcp.NewServer, mcp.ExposeInterpreter, registry, tools/resources
  • AI plugins — aiplugin.TokenCounter, aiplugin.PromptRecorder

Why experimental

  • Actor model overlaps with the InvokeMachine builder helper for child machine composition. The right shape (one mechanism vs two) is an open question.
  • Distributed + Persistent features compete with mature workflow engines (Temporal, Cadence). Real-world use will tell us whether to deepen these or position statekit as in-process-only.
  • MCP / aiplugin are recent additions tracking a fast-moving ecosystem (MCP spec, agent runtimes). API may evolve as norms settle.

What "experimental" means concretely

  • Bug fixes: yes, always.
  • API additions: yes.
  • API breaking changes: only in a clearly-numbered minor (v1.1, v1.2, ...) with deprecation warnings for at least one release.
  • Removal: only after a deprecation cycle, never inside a patch release.

If you depend on a Tier 2 feature in production, pin to a specific minor version (e.g., v1.2.x) and read release notes before bumping.

Tier 3 — Internal

The internal/ packages (internal/ir, internal/parser) are not subject to semver. They can change in any release.

See also