Skip to content

Heddle v0.12.0

Choose a tag to compare

@hooman hooman released this 07 Nov 19:32
· 32 commits to main since this release
52ef0a5

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 send NaN (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 NaN or Infinity, 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.0 and fastapi>=0.133.0 to the
    versions a lowest-direct resolve actually reaches. What installers get does
    not change.
  • The MCP server builds ToolAnnotations with the MCP SDK v2 snake_case field
    names. The JSON sent to MCP clients is unchanged.

Known limitations

  • heddle.contrib.events decodes leniently. Its JetStream readers use
    Pydantic's JSON parser, which keeps the last repeated name and accepts NaN.
    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 main but 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
    docproc extra, and has_tables / sections metadata is always empty
    (heddle#58).

The CHANGELOG has the complete list of changes.