Repository navigation
Heddle v0.10.0
Heddle v0.10.0 — Release Notes
- Date: 2026-11-06
- Previous version: v0.9.2 (2026-05-11)
- Breaking changes: Yes. The wire format changes (see Migration §1–§2), and several dependency minimums rise (§4).
- Total commits since v0.9.2: 75 (excluding merge commits, including the release commit)
Summary
v0.10.0 moves every message on the Heddle bus onto one frame, the
WireEnvelope, and publishes that frame as the v1 wire contract.
Goals, tasks and results each travel as a typed body inside a
common frame. The frame carries identity, causation, timestamps and
open _-prefixed metadata (the Middleware Lane). schemas/v1/ now
exports the frame schema plus one schema per core body, together with
19 language-neutral conformance fixtures. An SDK in any language can
use them to prove it speaks the contract.
This is a breaking wire change. A v0.10.0 process cannot exchange
messages with a v0.9.x process, and it cannot exchange them with the
current .NET, Swift or JVM SDKs either (see Known limitations).
Headline changes:
WireEnvelopeframe for all core messages.OrchestratorGoal,
TaskMessageandTaskResultare bodies with thepayload_types
core.OrchestratorGoal,core.TaskMessageandcore.TaskResult.
heddle.core.envelope.wrap()builds a frame andparse()reads one
in two steps: frame first, then the body chosen bypayload_type.- Wire contract export and conformance fixtures.
schemas/v1/wire_envelope.schema.jsonand the body schemas declare
JSON Schema draft 2020-12.schemas/v1/fixtures/holds valid and
invalid messages, amanifest.json, and a README of comparison and
versioning rules. CI holds the Python runtime to the same verdict on
every fixture. - Body versioning rule. Receivers must accept unknown body fields
and may drop them. Within v1, bodies grow only by optional fields with
defaults; a breaking body change needs a newpayload_type. The frame
stays strict: unknown top-level keys are rejected unless they start
with_. - Generic JetStream primitives in
heddle.bus.jetstream(publish
with compare-and-set, pull consumers, stream setup), shared by
heddle.contrib.events. - Dependency security. The lock was refreshed to clear 99 known
advisories, and published minimum versions were raised so that
pip install heddle-ai[...]cannot resolve a vulnerable direct
dependency.
Migration
1. Messages on the bus are WireEnvelope frames
If you only use Heddle's own workers, router, orchestrators, CLI and
Workshop, every component is updated together; upgrade all processes
at once. Mixed v0.9.x and v0.10.0 deployments do not interoperate.
If your code publishes or consumes bus messages directly:
from heddle.core.envelope import parse, wrap
from heddle.core.messages import TaskMessage
msg = TaskMessage(worker_type="summarizer", input={"text": "..."})
data = wrap("core.TaskMessage", msg).model_dump(mode="json") # publish this
envelope, body = parse(data) # on receipt: frame, then typed bodyA process that parses envelopes of arbitrary types should
import heddle.bootstrap once at startup so that every built-in
payload_type is registered. An unregistered type raises KeyError.
2. Field changes in the core bodies
| Before (v0.9.2) | After (v0.10.0) |
|---|---|
TaskMessage.payload |
TaskMessage.input |
TaskMessage.created_at |
frame occurred_at / recorded_at |
TaskResult.completed_at |
frame occurred_at / recorded_at (processing_time_ms stays on the body) |
OrchestratorGoal.created_at |
frame occurred_at / recorded_at |
3. heddle.contrib.events renames (experimental package)
EventEnvelope, CommandMessage and RejectionEnvelope are renamed to
Event, Command and Rejection, and they ride the WireEnvelope
as events.* bodies. Their own timestamp fields move to the frame.
EventLog.subscribe is now async and returns an AsyncIterator.
See the CHANGELOG for the full list.
4. Raised dependency minimums
These are the minimums installers see, because uv.lock is not
shipped. The notable ones are:
fastmcp>=4.1.2(mcpextra). fastmcp 3.x is no longer
supported.pyarrow>=23.0.1(lancedbextra),duckdb>=1.4.2,
docling>=2.142.0, and the OpenTelemetry packages>=1.45.1.- The
devextra needspytest>=9.0.3.
5. Deprecated: HEDDLE_TRACE
HEDDLE_TRACE is renamed to HEDDLE_PIPELINE_VERBOSE. The old name
still works and logs a one-time deprecation warning.
Known limitations
- The language SDKs are not compatible yet. The .NET, Swift and
JVM SDKs onheddle-sdkmainstill speak the pre-WireEnvelope
flat format. Migration and conformance against the new fixtures are
tracked in
heddle-sdk#4 and
heddle-sdk#5. heddle.contrib.eventsis experimental and frozen. It ships, but
receives no new features, and its delivery guarantees
(acknowledge-before-process, sequence/CAS scope across aggregates)
are unproven. Itsevents.*bodies are not part of the exported
contract. The CHANGELOG calls its Sprint 3 work a "production
runtime"; read that as the intended design, not a certification.
See heddle#55.- CI does not exercise a live NATS/JetStream broker. Integration
tests are excluded from CI, so green CI does not certify broker
restart, redelivery, or cross-language behavior. _keys are not carried through every hop. Workers set the
result frame's_trace_contextfrom their own span but do not copy
other_keys from the TaskMessage. The router's re-wrap of a
forwarded task drops theorigin,correlation_idand
causation_idfields and any_keys other than the trace context.- The Python runtime accepts more than the schemas allow. For
example, it accepts a timestamp without a UTC offset, or a number
sent as a string. Send what the schemas allow; stricter parsing is
planned. - Document processing: the default OCR engines are not installed by
thedocprocextra, andhas_tables/sectionsmetadata is
always empty
(heddle#58).
The CHANGELOG has the complete list of changes.