The zipnative determinism contract

Reproducible output is a product feature with a written contract: what is guaranteed always, what is guaranteed per environment, and what compression: { deterministic: true } pins bit-for-bit on every runtime.

This document is the contract; it was written down before anyone depended on it, and the golden tests (tests/core/zip-determinism.test.ts, tests/codecs/deflate-pure.test.ts) enforce it byte-for-byte.

The three levels of guarantee#

1. Structurally deterministic — always. Entry order, header layout, flags, attributes, timestamps and Zip64 decisions never depend on the clock, randomness, locale or environment. Two createZip runs with identical inputs produce structurally identical archives everywhere.
2. Bitwise deterministic per environment — the default. Deflate compresses through the best available tier (node:zlib, or the pure-TS encoder elsewhere), so bytes are stable for a given runtime + zlib build, but may differ across environments.
3. Bitwise deterministic everywhere — compression: { deterministic: true }. The pure-TS encoder is pinned: SHA256(A) === SHA256(B) for identical inputs on every runtime (Node, browsers, Deno, Bun, Workers). This is the mode for content addressing, reproducible builds, caching and signatures.

Canonicalization rules (level 1, always)#

The frozen encoder contract (level 3)#

Under deterministic: true, deflate output bytes are produced by src/codecs/deflate-pure.ts and every constant in that file is frozen public API:

• hash function imul(3-byte window, 0x9E3779B1) >>> 17 over a 32 KiB window with head/prev chains;
• zlib's level configuration table (good/lazy/nice/chain for levels 1–9);
• unified one-step-lazy matching, deferred match wins ties, TOO_FAR = 4096;
• 65 534-symbol blocks, hash history never reset across blocks;
• Huffman construction: two-queue merge over leaves sorted (frequency ascending, symbol ascending), leaf preferred on equal cost, zlib overflow fix at 15 bits (7 for the code-length tree), reassignment in the same sorted order;
• block choice at exact bit cost with the tie order stored ≤ fixed ≤ dynamic.

Changing any of these changes emitted bytes and is a semver-major release. The golden SHA-256 tables in the test suite are the tripwire.

Documented determinism losses#

Verifying reproducibility#

import { createZip } from 'zipnative';

const build = () => {
    const zip = createZip({ compression: { deterministic: true } });
    zip.add('data.json', payload); // identical inputs...
    return zip.toBytes();
};
// ...identical bytes, on any runtime:
sha256(build()) === sha256(build());