Repository navigation
Heddle v0.12.0
Heddle v0.12.0 — Release Notes
- Date: 2026-11-07
- Previous version: v0.11.0 (2026-11-07)
- Breaking changes: Yes. Some message text that v0.11.0 accepted is now
rejected, and the NATS bus refuses to sendNaN(see Migration). The
exported schemas are unchanged. - Total commits since v0.11.0: 4 (excluding merge commits, including the release commit)
Summary
v0.12.0 settles how wire message text is read. Until now the contract did not
say what a JSON object with a repeated member name means, and implementations
disagreed: Python's json and Jackson keep the last value, Swift's
JSONDecoder keeps the first, and .NET rejected some cases but not others. A
message with two payload_type members could therefore be routed one way by a
Python actor and another way by an SDK. Python also accepted, and sent, NaN.
The rule is now part of the v1 contract (schemas/v1/fixtures/README.md,
"Message text"). Wire text follows two rules from I-JSON (RFC 7493), and a
violation is a frame-layer rejection:
- Member names are unique in every object, at every depth.
- Numbers are finite: no
NaNorInfinity, and no number with a fraction
or exponent that overflows a double. Integer literals keep their exact value.
Text nested too deeply to decode is also a frame rejection, and it no longer
ends a subscription. Three new invalid fixtures pin the rule, bringing the total
to 27.
The .NET, Swift and JVM SDKs on heddle-sdk main follow the same rules
(heddle-sdk#7) and pass all 27 fixtures.
Migration
1. Message text the bus now rejects
NATSBus now decodes with heddle.core.wire_json.loads. A message that
repeats a member name, or contains NaN, Infinity or a number like 1e400,
is logged as nats.malformed_message_skipped and skipped (Invariant 8). Before
this release it was decoded, and the last repeated value won.
A producer that writes ordinary JSON with standard libraries is unaffected.
2. The bus refuses to send NaN
NATSBus.publish and request serialize with allow_nan=False. A message
containing float("nan") or float("inf") now raises ValueError at the
sender, instead of producing text that every receiver drops. If a worker's
output can contain such values, replace them (for example with null) before
returning.
3. Decoding wire text yourself
If your code reads bus messages from raw bytes, decode with
heddle.core.wire_json.loads before heddle.core.envelope.parse. It raises
WireJSONError, a ValueError, for text that breaks the rules.
Other changes
- Raised the stated minimums
lancedb>=0.16.0andfastapi>=0.133.0to the
versions a lowest-direct resolve actually reaches. What installers get does
not change. - The MCP server builds
ToolAnnotationswith the MCP SDK v2 snake_case field
names. The JSON sent to MCP clients is unchanged.
Known limitations
heddle.contrib.eventsdecodes leniently. Its JetStream readers use
Pydantic's JSON parser, which keeps the last repeated name and acceptsNaN.
This is tracked in heddle#81
for the planned events refactor. The module remains experimental and frozen
(heddle#55).- The language SDKs are conformant on
mainbut unpublished. heddle-sdk has
no tagged release or NuGet package yet. A manual live check (heddle router plus
.NET, Swift and JVM echo workers over NATS 2.10) passed on 2026-11-07. CI still
does not run a live broker. - Document processing: the default OCR engines are not installed by the
docprocextra, andhas_tables/sectionsmetadata is always empty
(heddle#58).
The CHANGELOG has the complete list of changes.