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. One stated exception: an explicit Date is written as a local-time DOS field by default (the Info-ZIP / 7-Zip convention), so it follows the process time zone unless dosTimeMode: 'utc' is set (1.1) or the date is omitted (DOS epoch).
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)#

Canonical compaction (level 1, 1.1)#

canonicalizeZip(bytes) and saveCompact({ canonical: true }) rewrite any archive — whoever produced it — into the canonical form without decompressing a payload, and the resulting bytes are part of this contract: the golden SHA-256 hashes in tests/parser/zip-canonical.test.ts pin canonicalizeZip() over two committed foreign fixtures (a bsdtar and a PowerShell archive), and changing them is semver-major.

analyzeDeterminism(bytes) reports which of these rules an archive already satisfies (epochTimestamps, canonicalOrder, utf8Flags, canonicalExtras, canonicalVersionMadeBy, noDataDescriptors — the last informational) and names every offending entry. It checks for the DOS epoch unless given the pinned date: analyzeDeterminism(bytes, { date, dosTimeMode }) is the verdict for an archive canonicalised with that date. The reproducible builds guide walks through measure → canonicalise → prove.

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());

For an archive you did not build, analyzeDeterminism(bytes) (1.1) says which rule it breaks and canonicalizeZip(bytes) rewrites it into the canonical form above — the reproducible builds guide.