Computes reproducible JSON bytes and content digests at serialization boundaries.

Every artifact DocShell writes uses this encoding, and every collection digest is computed over it. Objects are sorted by UTF-8 key bytes; array order and native scalar types remain unchanged; no insignificant whitespace is emitted. The encoding preserves the original DocShell collection digest format. It is not an implementation of RFC 8785 (in particular, numbers use Jason's encoding).

Jason's JSON string escaping uses uppercase hexadecimal digits for control escapes. Its numbers also preserve distinctions such as 1.0, negative zero and integers outside JavaScript's exact range. Readers must retain original canonical bytes when their decoded number type loses those distinctions; re-encoding a JavaScript value is not equivalent proof.

One pass

Native JSON values are validated and encoded in a single walk, so a large artifact is never encoded, decoded and re-encoded. A subtree that is not native JSON — a struct with a Jason.Encoder implementation, or a map with atom keys — is encoded through Jason with strict object keys, decoded with duplicate-key rejection, and canonicalized in place. Protocol encoders keep their wire representation and atom/string key collisions fail before any information is discarded. The result is byte-identical to encoding the whole value through Jason first; only the subtrees that need the round trip pay for it.

When the fast walk meets a value it cannot prove valid, such as an invalid UTF-8 string or a tuple, the whole value takes the protocol path so the returned error is the one Jason reports.

encode_to_iodata/1 returns iodata that can be hashed and written without ever being flattened into one binary. digest_iodata/1 hashes such bytes, so a writer that already holds an artifact's canonical encoding does not encode it a second time to compute its digest.

All functions return tagged errors, including exceptions from host encoders. They neither coerce unsupported metadata nor hide encoding errors in inspected strings. Use DocShell.Json.normalize/1 when coercion is explicitly intended.