Skip to content

Heddle v0.10.0

Choose a tag to compare

@hooman hooman released this 07 Nov 06:01
· 52 commits to main since this release
10b50d5

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:

  • WireEnvelope frame for all core messages. OrchestratorGoal,
    TaskMessage and TaskResult are bodies with the payload_types
    core.OrchestratorGoal, core.TaskMessage and core.TaskResult.
    heddle.core.envelope.wrap() builds a frame and parse() reads one
    in two steps: frame first, then the body chosen by payload_type.
  • Wire contract export and conformance fixtures.
    schemas/v1/wire_envelope.schema.json and the body schemas declare
    JSON Schema draft 2020-12. schemas/v1/fixtures/ holds valid and
    invalid messages, a manifest.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 new payload_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 body

A 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 (mcp extra). fastmcp 3.x is no longer
    supported.
  • pyarrow>=23.0.1 (lancedb extra), duckdb>=1.4.2,
    docling>=2.142.0, and the OpenTelemetry packages >=1.45.1.
  • The dev extra needs pytest>=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 on heddle-sdk main still 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.events is experimental and frozen. It ships, but
    receives no new features, and its delivery guarantees
    (acknowledge-before-process, sequence/CAS scope across aggregates)
    are unproven. Its events.* 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_context from their own span but do not copy
    other _ keys from the TaskMessage. The router's re-wrap of a
    forwarded task drops the origin, correlation_id and
    causation_id fields 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
    the docproc extra, and has_tables / sections metadata is
    always empty
    (heddle#58).

The CHANGELOG has the complete list of changes.