BXM.net

BXM 0.1.0 Launches With Canon and Memo, Two Open Source Tools for Repeatable Results

Thu, 22 Oct 2026 00:00:00 +0000

BXM 0.1.0 is out. It’s two small command-line tools in one repository, open source under the Apache License 2.0, with builds for Linux, macOS and Windows.

They share one idea. Same input, same bytes, same result. Canon applies it to data and Memo applies it to work.

BXM Canon is a binary encoding with exactly one valid form for every value. Two programs that encode the same data get the same bytes, whatever order they wrote the keys in and however they spelled the numbers. A hash or a signature taken on one machine holds on every other. The decoder refuses any byte string that isn’t the one encoding of its value, so a second spelling can’t sneak in through the back door.

Why Signed JSON Breaks and How a Canonical Encoding Fixes It

Thu, 22 Oct 2026 00:00:00 +0000

Here’s a bug that shows up in almost every system that signs or hashes structured data. Service A builds a record, serializes it as JSON, hashes it and signs the hash. Service B receives the record, parses it, does some work, serializes it again and checks the signature. It fails. Nobody changed a single field.

What changed was the bytes. Service B’s JSON library wrote the keys in a different order. Or it wrote 1.0 as 1. Or it escaped é as é where A wrote the character itself. All three are valid JSON for the same data. A hash doesn’t care about data, though. It cares about bytes, and there are many ways to write the same JSON.

Why CI Pipelines Redo Work Nobody Changed and How a Command Memoizer Stops It

Thu, 22 Oct 2026 00:00:00 +0000

Watch a CI log for a week and count the steps that produced exactly the same output as last time. Code generation from schemas that didn’t change. Image resizing for assets nobody touched. Test fixtures rebuilt from the same seed data. A documentation site rendered from the same pages. Each step is a few seconds or a few minutes. On every push, on every branch, on every laptop, it adds up to hours a week of machines doing work they’ve already done.

A Config Diff of 128 Lines Hid Two Real Changes, and Canon Named Both in Two Lines

Thu, 22 Oct 2026 00:00:00 +0000

Here’s a familiar review. The config for a checkout service comes back from someone’s editor and the diff is a wall of red and green. The editor saved with four spaces instead of two, sorted the keys, and escaped the “ü” in the description. Somewhere in there, maybe, a value changed.

We built that situation on purpose. One service config of 66 lines covers the server, database, cache, limits, features, logging and deploy settings. The deploy tool writes it one way. An editor saves it another way and changes two values on the way: the database pool timeout drops from 30000 ms to 3000 ms, and the replica count turns from the integer 3 into the float 3.0.

BXM Canon 0.2.0 Brings the Same Bytes to JavaScript With One Rust Core Compiled to WebAssembly

Thu, 22 Oct 2026 00:00:00 +0000

BXM Canon 0.2.0 adds a JavaScript package. It runs in Node 18 and later and in browsers, and it gives exactly the bytes and hashes the bxm-canon command gives, because it is the same Rust code compiled to WebAssembly.

That matters more for Canon than for most libraries. A canonical encoding is only as good as the agreement between the programs that use it. If the Node service and the Go service each carry their own implementation, a single corner case they read differently, a float spelled one way or a key compared another, brings back the problem Canon exists to remove.

BXM Canon 0.3.0 Adds Python, With Ints, Floats and Bytes Kept Apart and the Same Hash as Every Other Build

Thu, 22 Oct 2026 00:00:00 +0000

BXM Canon 0.3.0 adds a Python package. It’s the same Rust core again, this time called through PyO3, with wheels for Linux, macOS and Windows and any Python from 3.9 up. A value hashed in Python gives the hash the command line, the C library and the JavaScript package give, because all of them run the same code.

Python turned out to be the most natural fit so far. JavaScript has one number type, so a JavaScript caller has to think about whether 1 should be an integer or a float. Python already keeps int and float apart, and it has a real bytes type, which is exactly what Canon distinguishes. So the Python package can take a value straight from your program, no text step in between.

Hashing 100,000 JSON Lines Found No Duplicates, Hashing Them With Canon Found 9,900

Thu, 22 Oct 2026 00:00:00 +0000

Event pipelines get the same event twice. A producer times out, retries, and the retry goes through a different service that writes JSON its own way. The usual dedupe is a hash of each line, and it quietly misses all of these.

We generated a stream of 100,000 JSON lines from a fixed seed, 13.1 MB in all. 90,000 are distinct purchase events. The other 10,000 are resends of earlier events, written by two other producers. One sorts the keys and escapes non-ASCII, so “Zürich” arrives as Z\u00fcrich. The other reverses the key order and adds spaces. For a twist, 100 of the resends come from a producer that writes the quantity as a float: 2.0 where the original said 2.

How BXM Was Tested With Two Million Damaged Inputs, Sixteen Processes and a Killed Run

Thu, 22 Oct 2026 00:00:00 +0000

Each BXM tool makes one main promise. Canon promises that every value has exactly one encoding. Memo promises that it never hands you a wrong or half-restored output. Most of the testing went into trying to break those two promises, and the results are recorded in the repository’s test/results folder by a script anyone can run again.

Canon

The property behind Canon is short to state: if the decoder accepts a byte string, encoding the decoded value gives back exactly the same bytes. If that holds, no value can have a second accepted spelling.

Memo in GitHub Actions Skipped a Rust Release Build and Caught Runners With Different Compilers

Thu, 22 Oct 2026 00:00:00 +0000

Most CI jobs build the same thing again and again. A docs fix or a typo in a README triggers the whole pipeline, and the release build runs as if the code had changed. This case study puts BXM Memo in front of one such step, a release build of the bxm-canon binary, and keeps Memo’s cache between jobs with actions/cache.

The workflow is in the repository as .github/workflows/case-study-memo.yml. Five jobs run one after another, each on a fresh GitHub-hosted runner. plain builds without Memo for the baseline. cold builds through Memo with an empty cache, warm changes nothing, docs edits the README, and source edits a Rust source file. The inputs are canon/src/**, Cargo.toml and Cargo.lock, and the salt is rustc --version, so a different compiler means a different result. We ran the whole workflow twice.

One Order Built in Python, JavaScript and by Hand Gives Three JSON Hashes and One Canon Hash

Thu, 22 Oct 2026 00:00:00 +0000

A checkout service written in Python signs each order before it hands it on. A fulfilment service written in JavaScript checks the signature before it ships anything. Both have the same order in memory. The question is whether they agree on its bytes.

We built one order three ways. Python filled a dict in the order its code reads, and json.dumps wrote it with its defaults: a space after every comma and colon, and “Zürich” escaped as Z\u00fcrich. JavaScript built the same object with its keys in another order, and JSON.stringify wrote it compactly with the ü left as it is. The third copy is a file written by hand, pretty-printed, with yet another key order, hashed with the bxm-canon command.

Replaying 13 Commits Through Memo Cut Test Time From 228 to 79 Seconds and Turned Up Two Flaky Tests

Thu, 22 Oct 2026 00:00:00 +0000

BXM’s repository has two packages with their own test suites: Canon, tested with cargo test, and Memo, tested with go test. Most commits touch one of them, or neither. A docs change or a new JavaScript build script doesn’t change either suite’s result, yet a plain CI job runs both every time.

So we replayed the repository’s own history. All 13 commits from 0.1.0 to the end of 0.3.0 were checked out one after another, and both suites ran at each one. That happened twice: once plain, and once with each suite behind Memo. Canon’s suite takes canon/** and the spec’s test vectors as inputs. Memo’s takes memo/**. Memo needs a declared output, so each suite writes its log to a file and that file is the output.

Why Did My Build Step Run Again, Six Cache Misses and What Memo Said About Each

Thu, 22 Oct 2026 00:00:00 +0000

A cache that misses without saying why is almost as annoying as no cache. Someone notices the step ran again, nobody knows why, and the cache key gets a random suffix “to be safe”. After that the cache never hits.

BXM Memo keeps the manifest of the last run of each named job. On a miss it compares the two and says what changed. We put that to work on a small report step: a Python script that totals sales per region from monthly CSV files into out/report.txt. The step runs through Memo with the script and data/*.csv as inputs, REPORT_CURRENCY as an environment variable that changes the result, and the Python version as the salt.

Why the Project Is Called BXM

Thu, 22 Oct 2026 00:00:00 +0000

BXM started as a three-letter name looking for a project, and ended up with two projects that each claim it.

Read one way, it’s Binary eXchange Messages: values written as bytes, passed between programs and languages, and agreed on byte for byte at both ends. That’s Canon.

Read the other way, it’s Build eXecution Memo: a note of what a build step did, kept so the step never has to do it again with the same inputs. That’s Memo.

About

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

BXM is two small tools that share one idea: same input, same bytes, same result. They live in one repository and on one site because they solve the same kind of problem from two ends.

BXM Canon is a binary encoding with exactly one valid form for every value. When two programs encode the same data, they get the same bytes, so a hash or a signature taken on one machine holds on every other. More about Canon.

BXM Canon

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

BXM Canon is a binary encoding with exactly one valid encoding for every value. Same data in, same bytes out, on any machine. The decoder refuses everything else, so “are these two the same?” becomes “are these bytes equal?”.

The Problem It Solves

Sign a JSON object on one machine and check the signature on another, and it can fail even though nothing changed. One side wrote the keys in another order. Or 1.0 came out as 1. Or a string used an escape the other side didn’t. Same data, different bytes, broken hash.

BXM Memo

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

BXM Memo skips a command when its inputs haven’t changed. Put bxm-memo run in front of a slow step, say what it reads and writes, and the next time the inputs match it restores the outputs instead of running the step. When the inputs don’t match, it says which one changed.

bxm-memo run -i 'proto/**/*.proto' -i gen.sh -o gen/ -- ./gen.sh

The Problem It Solves

Build and CI pipelines redo work whose inputs didn’t change: code generation, asset processing, test fixtures, site builds, data preparation. Each step is a few seconds or minutes, and it adds up on every push and every laptop.

Contact

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

Bug reports, feature requests and pull requests are welcome on GitHub. That’s the fastest way to get something fixed, and other people can see the answer.

For anything else, write to info@bxm.net.

The project would especially like to hear from:

People writing another Canon implementation, in any language, who find a corner of the spec that could be read two ways.
Teams trying Memo in CI, about what they wrapped, how much time it saved and what got in the way.
Anyone who signs or hashes structured data and has been bitten by two systems writing the same thing differently.

Download BXM

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

Each archive holds both tools, bxm-canon and bxm-memo, plus the Canon library and C header, the format spec with its test vectors, and the license files. The links always point to the latest release.

System	Download
Linux, x86-64	bxm-linux-amd64.tar.gz
Linux, ARM64	bxm-linux-arm64.tar.gz
macOS, Apple silicon	bxm-darwin-arm64.tar.gz
macOS, Intel	bxm-darwin-amd64.tar.gz
Windows, x86-64	bxm-windows-amd64.zip

To check a download, compare it with SHA256SUMS.

Canon for JavaScript

The bxm-canon package for Node 18+ and browsers is attached to every release:

Quick Start

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

Five minutes with each tool. First download the archive for your system and put bxm-canon and bxm-memo on your PATH.

BXM Canon

Write the same data two ways and hash both:

echo '{"name":"bxm","tags":["a","b"],"n":3}' > a.json
echo '{ "n": 3, "tags": ["a", "b"], "name": "bxm" }' > b.json

bxm-canon hash --text a.json
bxm-canon hash --text b.json

The two hashes are the same, because both files hold the same value and Canon has one encoding for it.

Reference

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

Every command and flag of both tools, and the Canon format in brief. The full format is in spec/CANON.md.

bxm-canon

bxm-canon encode [FILE] [-o OUT]     Canon text (JSON) in, canonical bytes out
bxm-canon decode [FILE] [--pretty]   canonical bytes in, Canon text out
bxm-canon fmt [FILE] [--pretty]      text in, the one normal text form out
bxm-canon check FILE...              exit 0 only if every file is canonical bytes
bxm-canon hash [FILE] [--text]       SHA-256 of the canonical bytes
bxm-canon diff A B [--text]          paths that differ between two values
bxm-canon version

FILE defaults to standard input, and - also means standard input. --text tells hash and diff that the inputs are Canon text rather than canonical bytes. -o writes to a file instead of standard output.

Use Cases

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

Where BXM earns its place, with a worked case study for each. Every case study is a script in the repository under examples/case-studies. Its recorded output is in test/results/case-studies, and you can run it again yourself.

BXM Canon

Signatures and hashes across languages. One service signs data and another checks it, each in its own language. With Canon both sides sign the same bytes, so the check only fails when the data changed. One order built in Python, JavaScript and by hand gave three JSON hashes and one Canon hash. Python’s signature over its JSON failed in JavaScript, and the one over the Canon bytes passed.