Skip to content

v0.1.5

Latest

Choose a tag to compare

@3leapsdave 3leapsdave released this 10 Nov 14:07
Immutable release. Only release title and notes can be modified.
v0.1.5
96cd3c9

v0.1.5

The command-line binary is renamed from canon to canonprims, and gains
three jcs modes: golden vectors, strict NDJSON prefixes framed as one
canonical array, and canonical sets. The helpers behind them are public in
the Rust crate canonprims-json and the Go package canon. The Go package
path, the crate names, the language bindings and the conformance corpus are
unchanged.

What it ships

  • Rust crates canonprims-core and canonprims-json (crates.io).
  • Go module github.com/3leaps/canonprims (package canon), standard
    library only and cgo-free.
  • canonprims command for linux amd64/arm64, darwin arm64 and windows
    amd64/arm64, in archives named canonprims-0.1.5-<platform>.
  • Python package canonprims (PyPI): an abi3 wheel per platform for
    CPython 3.10 and later, on linux amd64/arm64 (manylinux2014, glibc 2.17 or
    later), darwin arm64 and windows amd64/arm64. No source distribution.
  • npm package @3leaps/canonprims: one WebAssembly module with no
    imports, embedded in an ES module with no runtime dependencies. Tested on
    Node.js 20 and 22.

The wheels and the npm package are release assets: built and tested in the
tag workflow, listed in both checksum manifests and covered by both
signatures. The packages on PyPI and npm are these exact files.

Command line

The binary is canonprims; the name in version output and in diagnostics
is canonprims. Its subcommands, flags, output and exit codes are those of
canon 0.1.4 except that numeric options (--max-*, --head) now accept
only ASCII decimal digits: a sign, space or _ is a usage error (exit 2).
Of these, 0.1.4 accepted a leading + (for example +5). New jcs modes:

  • --vector: one canonical JSON object, then a newline:
    {"byte_length":N,"canonical":"...","digest":"sha256:...","scheme":"jcs/rfc8785"}.
    The object is itself canonical; canonical is the canonical bytes as a
    JSON string.
  • --ndjson-array [--head N]: the input is LF-terminated NDJSON lines (no
    CR LF, no empty or whitespace-only line, no unterminated line). Each line
    is canonicalized one level below --max-depth and the lines form one
    canonical array, in order. With --head N exactly the first N lines are
    used: the command answers once they have arrived, so a writer may keep the
    stream open, and nothing after them is parsed. Input is read through a
    buffer, so bytes after the selected lines may be consumed from a pipe or
    shared descriptor. The selected lines must fit in --max-bytes.
  • --sort-set: the array's elements are sorted by their canonical bytes
    (unsigned, byte by byte); two elements with the same canonical bytes are
    refused with duplicate_set_element, and a non-array with not_an_array.
    With --check, the input must already be that sorted canonical set.

--vector, --digest and --check are mutually exclusive;
--ndjson-array cannot be combined with --check; --head requires
--ndjson-array. Numeric options accept only ASCII decimal digits.

Library

Rust canonprims-json: vector, Vector (from_canonical, canonical,
byte_length, digest, scheme, to_json), ndjson_elements,
canonicalize_ndjson, sort_canonical_set, check_canonical_set and
assemble_canonical_set. Go canon: VectorOf, VectorOfCanonical,
Vector, NDJSONElements, CanonicalizeNDJSON, SortCanonicalSet,
CheckCanonicalSet and AssembleCanonicalSet (the zero Go Vector holds
no bytes and its JSON is nil). Their behaviour, including
the order in which defects are reported, is specified in
docs/spec/jcs-rfc8785.md ("Composition helpers").

Code::ALL (Rust) and the binding CODES lists still name only the scheme
codes; the two set codes are in Code::SET.

Release machinery

  • The release workflow packages the canonprims binary as
    canonprims-X.Y.Z-<platform>.{tar.gz,zip}; its pin in
    config/release/release-workflow.sha256 is updated.
  • scripts/release-common.sh expects canon-X.Y.Z-<platform> archives for
    releases 0.1.0 through 0.1.4 and canonprims-X.Y.Z-<platform> from 0.1.5,
    so staging and verifying a published older release is unchanged.

Conformance

  • Corpus conformance/canonical-json/v0, 180 cases, unchanged.
    MANIFEST.json sha256:
    de3ac543580ddb90f7e3a6e72239097274d3635ea783f302a9260b5a7d0c8d90.
  • Rust and Go agree byte for byte on the corpus and on generated input:
    crosscheck seeds 20261022 and 20261023, 5000 inputs each, on every
    native CI cell. The same seeds also generate inputs shaped for the new
    helpers, and the two drivers agree on every helper.
  • Each binding runs the whole corpus against its installed package (the
    wheel, or the packed npm tarball), and its corpus results and its output on
    the same crosscheck seeds equal Rust's byte for byte.

Verification

canonprims canonicalizes and digests; it verifies no signatures, so it
embeds no key. To verify this release, check the signed tag v0.1.5 and the
signed checksum manifests against the public pins committed in the tagged
commit (docs/security/); see docs/security/README.md. A wheel or the npm
tarball downloaded from PyPI or npm has the SHA-256 listed for it in
SHA256SUMS.