Release Notes on Dwarf

v0.14.0

Mon, 01 Jan 0001 00:00:00 +0000

v0.14.0 — A Daily Archive for Closed Flows, Lists by State, Continue by Key

Upcoming release: these notes may change before it is published on GitHub Releases.

Closed flows now move to an archive about a minute after they close, kept by the day for a retention you set and dropped a day at a time, so the live tables that every step reads hold the open flows and little else. An archived flow reads by its key as before. The lists are named by a flow’s state - ListOpen and ListClosed - and SetFlowExpiration can end flows that would otherwise never close. This release edits migrations that earlier releases shipped, so existing databases cannot be upgraded in place: start v0.14.0 on fresh databases (see Upgrading). Nothing detects an old database: Startup succeeds on one, and ListOpen then fails on every call.

v0.13.0

Mon, 01 Jan 0001 00:00:00 +0000

v0.13.0 — The Creation Hour in Every Flow and Step Key

Released 2026-10-31. GitHub release.

Flow and step keys carry the flow’s creation hour, and a step key names its flow. This is groundwork for retaining ended flows cheaply. This release edits migrations that earlier releases shipped, so existing databases cannot be upgraded in place: start v0.13.0 on fresh databases (see Upgrading).

Breaking Changes

Flow keys are {shard}-{hour}-{flowID}-{token}. {hour} is the flow’s creation hour, in whole hours since 2000-01-01 00:00 UTC, taken from the database clock. This applies everywhere a flow key appears:

v0.12.0

Mon, 01 Jan 0001 00:00:00 +0000

v0.12.0 — Reducers That Fold Everywhere, History Stored Once, Priority Bands That Spill

Released 2026-10-23. GitHub release.

v0.12.0 makes a reduced field mean the same thing wherever a task writes it. Every write to a field with a reducer is a contribution, folded through the reducer at every hand-off: the next step, the fan-in, the final state and Continue. A task writes only what it adds, and the outcome no longer depends on the graph’s shape. An agent loop’s history is stored once: a field under append, or a list a task keeps rewriting but only extends, is kept as references to the rows that hold its elements rather than as the whole history at every step. Priorities are now five bands that spill, so a better band no longer starves a worse one while workers sit idle. Beneath that, the engine does fewer round trips per step, a shard is dispatched by two replicas at a budgeted pool, and a step whose transition was lost to a crash is replayed rather than stranded.

v0.11.0

Mon, 01 Jan 0001 00:00:00 +0000

v0.11.0 — Graceful Cancel, Budget-Bound Shard Connections, Measured Pool Sizing

Released 2026-09-28. GitHub release.

v0.11.0 gives a flow a way to stop gracefully. The immediate, unconditional stop is renamed Terminate, and Cancel now delivers the cancellation to every step in progress as an error on its node’s onError transition, so a workflow can compensate, clean up, or carry on. The flow ends cancelled, failed, or completed, depending on what its handlers do. Beneath that, a shard’s connection budget no longer grows with the fleet. A few replicas per shard dispatch it and split its budget, and every other replica holds a two-connection reader pool there, so a host scaled wide for its own traffic can no longer over-connect the database. Pool sizes come from measured sweeps on six database sizes instead of a model, sleeping steps get an index of their own so they stop slowing every scheduling pass, and graph validation rejects field names that a when expression could never reference.

v0.10.5

Mon, 01 Jan 0001 00:00:00 +0000

v0.10.5 — Update Dependencies

Released 2026-08-03. GitHub release.

Update dependencies to latest, including Sequel v1.11.1 which changes the sequel_pool_wait_count and sequel_pool_wait_duration_seconds gauges to counters and renames them appropriately.

v0.10.3

Mon, 01 Jan 0001 00:00:00 +0000

v0.10.3 — A Fan-Out Node Can Route to END Instead of Fanning Out

Released 2026-08-03. GitHub release.

Fixes a non-terminating loop. A node that both fans out over an array and carries a withGoto/onError edge to END — the shape a task-driven loop takes, “fan out over what is pending, or end the flow when there is nothing left to do” — now ends the flow when the task steers to END.

v0.10.2

Mon, 01 Jan 0001 00:00:00 +0000

v0.10.2 — NewEngineUnderTest Takes a Test Name, Not a testing.TB

Released 2026-08-03. GitHub release.

Test-support change only. engine.NewEngineUnderTest is now keyed by a plain test name instead of a testing.TB, so a host can stand up an isolated engine under its own harness — one that has no *testing.T to hand over. A name was all the constructor ever needed from one.

No schema migrations. No change to dispatch, scheduling, recovery, pool sizing, or anything else on the production path.

v0.10.0

Mon, 01 Jan 0001 00:00:00 +0000

v0.10.0 — Replicas Coordinate Through the Database, and Size Themselves

Released 2026-08-02. GitHub release.

This release rebuilds how a Dwarf fleet finds work, divides resources, and carries state. Both the API and the database schema change. Dwarf is v0.x, so upgrading is a maintenance window, not a rolling deploy — see docs/upgrading.md.

Breaking Changes

Host loses SignalPeers. The engine now sends nothing to its peers at all; hosts implement two methods, LoadGraph and ExecuteTask. Three signal kinds existed here and all three were deleted after measurement — a per-step work doorbell, a per-flow stop broadcast, and a fleet-membership nudge — because in each case the poll the engine already runs converges faster than the message.
SetShard(ShardSpec{Index, DSN, VirtualCPUs}) replaces SetDSN / SetNumShards / SetWorkersPerConn. You declare facts about each shard’s server; the engine derives the tuning. New SetEngineID pins a replica identity so restarts don’t inflate the observed fleet count.
workflow.State is a type, not a map[string]any — on FlowOutcome.State, Flow.Snapshot(), baggage, and interrupt/subgraph payloads. It holds each field as raw JSON and decodes on read. Flow.Delete → Flow.Del; Flow.SetState, Flow.Transform, MergeState, Graph.HasFanIn and the Duration() helpers are gone; Render() no longer returns an error; typed getters panic on a mistyped read instead of quietly returning a zero value.
NewEngineUnderTest(t) / SetTestName replace RunInTest / SetInTest.
Schema: a new dwarf_peers registry, new step columns (state_refs, engine_id), fixed-width CHAR tokens and statuses widened to VARCHAR, and SQL Server JSON payloads stored as VARBINARY — which ends a silent corruption of non-ASCII payloads on that dialect. The baseline migrations are edited in place, so a database created by v0.9.x cannot be migrated forward — recreate it.

Coordination Is the Database, and Nothing Else

Replicas discover each other through a dwarf_peers registry read per shard, not through the host’s transport. From one reading a replica derives two different numbers with deliberately opposite risk postures: how many ways to divide a shard’s connection budget (over-count and you collapse a database) and which replicas demonstrably dispatch work (over-count and you strand it). A replica that goes blind holds its last good reading rather than acting on silence.

v0.9.5

Mon, 01 Jan 0001 00:00:00 +0000

v0.9.5 — Seamster Extraction and Graph.Validate Race Fix

Released 2026-07-07. GitHub release.

This release fixes a concurrency bug in graph validation and moves the engine’s test-only instrumentation into a standalone module. Both live in one commit (0c113c3).

Fixed

Data race in workflow.Graph.Validate. Validate() built the fan-out to fan-in convergence map as a side effect stored on the graph. Because a graph is loaded once and shared across concurrent Create calls, two validations (or a validation racing a MarshalJSON) wrote and read that field at the same time, which the race detector flagged and which could corrupt the map. Validate() is now pure over the graph’s immutable definition and stores nothing on the graph.

Changed

Fan-in routing is now derived at dispatch, not persisted. The fan-out to fan-in map is a pure function of the graph structure, so the engine computes it per flow from the frozen graph definition (new internal package internal/faninmap) and caches it beside the parsed graph. It is no longer written into the stored graph JSON, so a workflow graph carries only its author-defined shape over the wire.

v0.9.4

Mon, 01 Jan 0001 00:00:00 +0000

v0.9.4 — Maintenance Release. No API or Behavior Changes to the Engine

Released 2026-07-06. GitHub release.

Fixes

Test stability: Fixed a MySQL-timing flake in TestFault_PollSizingErr. The faultPollSizingErr fault is now armed sticky rather than one-shot, so the background timerLoop’s own poll can no longer consume the fault before the test’s explicit poll — the poll reliably clamps to the near-term error-retry interval instead of occasionally sleeping the full maxPollInterval.

Dependencies

Bumped github.com/microbus-io/sequel v1.10.6 → v1.10.7.
Bumped golang.org/x/text v0.38.0 → v0.39.0 (indirect).

Docs

Removed the stale Go Report Card badge from README.md.

v0.9.3

Mon, 01 Jan 0001 00:00:00 +0000

v0.9.3 — Poll Operation

Released 2026-07-05. GitHub release.

The engine now exposes Poll(ctx, flowKey) alongside Await. Like Await, it blocks up to the context deadline for a flow to stop, but where Await treats a deadline expiring before the flow stops as a timeout error, Poll instead returns the flow’s current outcome — non-terminal, with Stopped() reporting false — and no error. This makes it the natural fit for bridging an open-ended durable flow to a bounded request (for example, answering an HTTP long-poll within its time budget and re-polling on the next request) without conflating “not done yet” with a real failure. The returned FlowOutcome gains a Stopped() helper to distinguish a terminal/interrupted outcome from one still running. As always, the underlying flow keeps running on the engine independent of the caller; a ctx timeout never tears it down.