# ZIP byte identity / ZIP 的字节一致性 / ZIP のバイト一致

Experiment date: 2026-10-19.

## Run / 运行 / 実行

After extracting the experiment bundle:

```sh
python3 zip-byte-identity.py > reproduced.json
```

To also generate the twelve sample ZIPs in a new directory:

```sh
python3 zip-byte-identity.py --write-zips generated > reproduced.json
```

`generated` must not exist. This prevents overwriting an existing directory.
By default the script only prints JSON; shell redirection writes the result.
Only the Python standard library is used. The script uses Python 3.9+ syntax;
the recorded run used CPython 3.12.14, zlib compile/runtime version 1.2.12,
and macOS 27.0.1 arm64. Other versions and platforms were not tested.

中文：输入由脚本固定生成，data.txt 为 39000 字节，readme.txt 为 35 字节。
九个普通变体的成员路径和全部解码字节相同；六种改动产生不同整包与 SHA-256。
重复运行及基础 DOS 时间增加一秒的变体与基准整包相同。另有三个边界：内容
改变、路径改名、同名条目。结果 JSON 保存完整摘要与字段，不依赖表里的短前缀。

日本語：入力はスクリプトで固定して生成します。data.txt は 39000 バイト、
readme.txt は 35 バイトです。九つの通常の変種ではパスとデコード後の全バイトが
同じですが、六種類の変更で ZIP 全体と SHA-256 が異なります。同じ設定での
再生成と、基本の DOS 時刻を一秒進めた変種は、基準と全バイトが同じです。
さらに内容変更、改名、同名エントリーの三つの境界を確認します。

## Bundle contents

- `zip-byte-identity.py`: complete fixture, generator, comparator and checks.
- `zip-byte-identity-results.json`: recorded results, full SHA-256 values,
  per-member fields, environment information and checks.
- `zip-byte-identity-README.md`: this file.
- `samples/`: twelve generated ZIP files listed below.

All sample ZIPs contain only tiny, synthetic text files. They were not taken
from a project directory. The main experiment is written to BytesIO, without
reading source-file timestamps, local directory listings or random data.

| Sample | Change from baseline |
| --- | --- |
| baseline | sorted names, fixed 2026-10-19 20:00:00, Unix regular-file mode 0644, DEFLATE level 6, no extra fields or comment |
| repeat | same generation settings again |
| time_plus_2s | timestamp seconds changed from 00 to 02 |
| reverse_order | entry write order reversed |
| mode_0600 | stored Unix file mode changed to 0600 |
| archive_comment | archive comment set to ASCII `build B` |
| stored | ZIP_STORED instead of DEFLATE |
| deflate_level_1 | DEFLATE level 1 instead of level 6 |
| time_plus_1s | timestamp seconds changed from 00 to 01; decoded as 00 in these basic headers |
| changed_payload | append `changed` and LF to data.txt |
| renamed_member | data.txt renamed to renamed.txt, same file bytes |
| duplicate_member | a second entry named readme.txt; content_manifest explicitly rejects it |

The baseline size in the recorded environment is 2596 bytes and its SHA-256 is:

```text
93dbdb90f3d2edc4c805c97df441dc36754ce48602b0f17243c3049a374bb6f0
```

Consult the JSON for all full hashes. The program compares actual archive
bytes as well as full hashes; short hash prefixes in the article are display
labels, not the comparison rule. It also compares the full uncompressed
payload bytes for the nine ordinary variants and checks their CRCs.

## What is and is not compared

The content manifest includes member paths, uncompressed lengths and SHA-256
of uncompressed bytes, sorted by path. It rejects duplicate member names
before mapping by name. This function is an illustration for known regular
files, not a complete archive equivalence checker or ZIP security scanner.
It does not normalize text, compare filesystem links or directory metadata,
check extended attributes, or test how operating systems restore permissions.
The decoded fields of the generated ZIP are recorded separately in the JSON.

Reproducing the same output on a different Python/zlib combination is not
guaranteed. Output sizes and compressed bytes can depend on the runtime.
The experiment does not benchmark compression performance, extract to a
production directory, validate encrypted or large archives, or certify a
reproducible build of a real software project.

## Primary references checked on 2026-10-19

- PKWARE ZIP application note, sections 4.3 and 4.4, including basic DOS
  timestamp precision and archive fields:
  https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
- Python 3.12 zipfile, ZipInfo, writestr and duplicate-name member access:
  https://docs.python.org/3.12/library/zipfile.html
- Python 3.12 hashlib, byte input and digests:
  https://docs.python.org/3.12/library/hashlib.html
- Reproducible Builds, definition:
  https://reproducible-builds.org/docs/definition/
- Reproducible Builds, archive metadata:
  https://reproducible-builds.org/docs/archives/

## Articles

- 中文：https://gumi.ink/posts/2026-10-19-zip-files-and-byte-identity/
- 日本語：https://gumi.ink/ja/posts/2026-10-19-zip-files-and-byte-identity/
