xfh 0.1.0__tar.gz

xfh-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, xfh contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

xfh-0.1.0/NOTICE

@@ -0,0 +1,10 @@
+Parts of the XPK codec implementations are derived from Ancient:
+
+    Copyright (c) 2017-2025, Teemu Suutari
+    https://github.com/temisu/ancient
+
+Ancient is distributed under the BSD 2-Clause License. Its copyright and
+license terms are retained in the relevant source modules.
+
+Historical XFH and XPK source code is used as format documentation and test
+oracle material only. It is not included in this distribution.

xfh-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: xfh
+Version: 0.1.0
+Summary: Recover Amiga XPK files, including files written through XFH
+Keywords: amiga,compression,data-recovery,xpk,xfh
+Author: xfh contributors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-Expression: BSD-2-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Archiving :: Compression
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: build>=1.2 ; extra == "dev"
+Requires-Dist: coverage>=7.6 ; extra == "dev"
+Requires-Dist: flit_core>=3.10 ; extra == "dev"
+Requires-Dist: hypothesis>=6.100 ; extra == "dev"
+Requires-Dist: pre-commit>=4 ; extra == "dev"
+Requires-Dist: pytest>=8 ; extra == "dev"
+Requires-Dist: pytest-cov>=6 ; extra == "dev"
+Requires-Dist: ruff>=0.9 ; extra == "dev"
+Requires-Dist: twine>=6 ; extra == "dev"
+Project-URL: Issues, https://github.com/bitplane/xfh/issues
+Project-URL: Repository, https://github.com/bitplane/xfh
+Provides-Extra: dev
+
+# xfh
+
+`xfh` is a pure-Python data-recovery library and command-line tool for files
+compressed with the Amiga XPK system, including files written transparently
+through DiskExpander.
+
+The project is under active format-recovery work. It currently supports the
+later `XPKF` container, the DiskExpander 2.1 wrapper, and 41 codec identifiers
+in pure Python. Historical compatibility identifiers `CBR1` (CBR0) and `FRHT`
+(RAKE) are accepted as exact stream-format aliases. See the
+[codec support table](https://github.com/bitplane/xfh/blob/master/docs/codec-support.md)
+for the evidence and limitations behind each codec.
+
+## Installation
+
+`xfh` requires Python 3.10 or newer and has no runtime dependencies. After the
+first release is published to PyPI, install it with:
+
+```console
+python -m pip install xfh
+```
+
+Until then, install a checkout directly:
+
+```console
+python -m pip install .
+```
+
+## Quick start
+
+Inspect a stream before writing anything, strictly verify it, and then unpack
+it:
+
+```console
+xfh info packed-file
+xfh verify packed-file
+xfh unpack packed-file recovered-file
+```
+
+Existing output files are not overwritten unless `--force` is supplied.
+Decompression is limited to 256 MiB by default; use `--max-output-size` to set
+an appropriate byte limit for a known larger file.
+
+For a damaged stream, salvage mode writes only the prefix decoded before the
+first failing chunk. Its exit status is `4` when recovery is incomplete:
+
+```console
+xfh unpack damaged-file recovered-prefix --salvage --report recovery.json
+```
+
+The public Python API accepts bytes-like input:
+
+```python
+from pathlib import Path
+
+import xfh
+
+packed = Path("packed-file").read_bytes()
+info = xfh.inspect(packed)
+plain = xfh.decompress(packed, limits=xfh.Limits(max_output_size=512 * 1024 * 1024))
+Path("recovered-file").write_bytes(plain)
+
+print(info.codec, len(plain))
+```
+
+Use `xfh.decompress_file()` when writing to disk: it uses an atomic destination
+write and refuses to replace an existing file by default.
+
+## Recovery and stability
+
+Strict decoding validates the container, declared sizes, checksums, chunk
+output sizes, and initial-byte prefix where the format provides them. It either
+returns the complete declared output or raises an `xfh.XfhError` subclass.
+Password-protected streams are detected but not decoded.
+
+Salvage is deliberately opt-in. Its output can be useful evidence, but an
+incomplete result is not proof that every returned byte represents an intact
+original file. Keep the source media and packed files unchanged, work on
+copies, review the recovery report, and validate recovered data with tools
+specific to its file type.
+
+This is alpha software reconstructed from historical implementations and
+surviving samples. Codec support varies in strength from headless-UAE packer
+fixtures to source-derived decoder tests; the support table records that
+distinction. The API and command-line interface may change before 1.0.
+
+## Development
+
+Development follows the template workflow:
+
+```console
+make dev
+make test
+make coverage
+make lint
+make dist
+```
+
+See [the original investigation](https://github.com/bitplane/xfh/blob/master/docs/research/initial-findings.md)
+for the provenance of the project and
+[the format notes](https://github.com/bitplane/xfh/blob/master/docs/format.md)
+for current support boundaries. The
+[oracle matrix](https://github.com/bitplane/xfh/blob/master/docs/oracle-matrix.md)
+records results from the isolated original Amiga implementation.
+

xfh-0.1.0/README.md

@@ -0,0 +1,104 @@
+# xfh
+
+`xfh` is a pure-Python data-recovery library and command-line tool for files
+compressed with the Amiga XPK system, including files written transparently
+through DiskExpander.
+
+The project is under active format-recovery work. It currently supports the
+later `XPKF` container, the DiskExpander 2.1 wrapper, and 41 codec identifiers
+in pure Python. Historical compatibility identifiers `CBR1` (CBR0) and `FRHT`
+(RAKE) are accepted as exact stream-format aliases. See the
+[codec support table](https://github.com/bitplane/xfh/blob/master/docs/codec-support.md)
+for the evidence and limitations behind each codec.
+
+## Installation
+
+`xfh` requires Python 3.10 or newer and has no runtime dependencies. After the
+first release is published to PyPI, install it with:
+
+```console
+python -m pip install xfh
+```
+
+Until then, install a checkout directly:
+
+```console
+python -m pip install .
+```
+
+## Quick start
+
+Inspect a stream before writing anything, strictly verify it, and then unpack
+it:
+
+```console
+xfh info packed-file
+xfh verify packed-file
+xfh unpack packed-file recovered-file
+```
+
+Existing output files are not overwritten unless `--force` is supplied.
+Decompression is limited to 256 MiB by default; use `--max-output-size` to set
+an appropriate byte limit for a known larger file.
+
+For a damaged stream, salvage mode writes only the prefix decoded before the
+first failing chunk. Its exit status is `4` when recovery is incomplete:
+
+```console
+xfh unpack damaged-file recovered-prefix --salvage --report recovery.json
+```
+
+The public Python API accepts bytes-like input:
+
+```python
+from pathlib import Path
+
+import xfh
+
+packed = Path("packed-file").read_bytes()
+info = xfh.inspect(packed)
+plain = xfh.decompress(packed, limits=xfh.Limits(max_output_size=512 * 1024 * 1024))
+Path("recovered-file").write_bytes(plain)
+
+print(info.codec, len(plain))
+```
+
+Use `xfh.decompress_file()` when writing to disk: it uses an atomic destination
+write and refuses to replace an existing file by default.
+
+## Recovery and stability
+
+Strict decoding validates the container, declared sizes, checksums, chunk
+output sizes, and initial-byte prefix where the format provides them. It either
+returns the complete declared output or raises an `xfh.XfhError` subclass.
+Password-protected streams are detected but not decoded.
+
+Salvage is deliberately opt-in. Its output can be useful evidence, but an
+incomplete result is not proof that every returned byte represents an intact
+original file. Keep the source media and packed files unchanged, work on
+copies, review the recovery report, and validate recovered data with tools
+specific to its file type.
+
+This is alpha software reconstructed from historical implementations and
+surviving samples. Codec support varies in strength from headless-UAE packer
+fixtures to source-derived decoder tests; the support table records that
+distinction. The API and command-line interface may change before 1.0.
+
+## Development
+
+Development follows the template workflow:
+
+```console
+make dev
+make test
+make coverage
+make lint
+make dist
+```
+
+See [the original investigation](https://github.com/bitplane/xfh/blob/master/docs/research/initial-findings.md)
+for the provenance of the project and
+[the format notes](https://github.com/bitplane/xfh/blob/master/docs/format.md)
+for current support boundaries. The
+[oracle matrix](https://github.com/bitplane/xfh/blob/master/docs/oracle-matrix.md)
+records results from the isolated original Amiga implementation.

xfh-0.1.0/docs/codec-support.md

@@ -0,0 +1,32 @@
+# Codec support and evidence
+
+`xfh` currently recognizes 41 XPK identifiers. “Amiga pack” means at least one
+fixture was created and unpacked by the original Amiga libraries under
+headless UAE, then decoded byte-exactly by Python. “Derived” means the decoder
+is covered by source-derived or transformed fixtures but an original packer
+artifact is not yet available.
+
+| Evidence | Codecs |
+| --- | --- |
+| Original Amiga pack/unpack | ACCA, BLZW, BZP2, CBR0, DLTA, DUKE, FAST, FBR2, FRLE, GZIP, HFMN, HUFF, ILZR, IMPL, LHLB, LZBS, LZW2, LZW3, LZW4, LZW5, MASH, NONE, NUKE, RAKE, RDCN, RLEN, SDHC, SHRI, SLZ3, SQSH, ZENO |
+| Exact historical aliases | CBR1, FRHT |
+| Derived or transformed | ARTM, CRM2, CRMS, CYB2, PWPK, SHR3, SMPL, TDCS |
+
+The important remaining evidence gaps are:
+
+- CYB2 needs a genuine file created through XpkCybPrefs; its standalone
+  library does not expose packing modes and rejects hand-built containers.
+- TDCS needs an original library or authentic packed sample.
+- ARTM and SHR3 need preserved original libraries.
+- SMPL’s original packer selected raw chunks for every tested vector, so its
+  compressed-stream test remains source-derived.
+
+PWPK has a positive stream produced by the original Amiga PPMC tool and
+cross-checked with Ancient. CRM2 and CRMS have positive streams generated and
+decoded by an independent Crunch-Mania implementation. They remain in the
+derived row because the committed XPK envelopes were constructed outside the
+original XPK master library.
+
+The preservation archive contains further codecs that are not implemented
+yet. Wrapper/backend formats are being prioritized before encryption,
+authentication, and preference-system formats.

xfh-0.1.0/docs/format.md

@@ -0,0 +1,35 @@
+# Format notes
+
+## XPKF
+
+`xfh` validates the 36-byte global header, optional extended header, short and
+long chunk headers, header XORs, payload XORs, four-byte alignment, declared
+sizes, and the terminal chunk before decoding. Integers are big-endian.
+
+## DiskExpander 2.1 stream
+
+The recovered files begin with `01 80 63 68 05 61 01 0a`, followed by the
+unpacked size, a packed-length field (measured from byte 8), and an eight-byte
+NUL-padded sublibrary name such as `xpkNUKE`. It is not a later `XPKF`
+stream.
+
+The second length is the absolute offset of a chunk-boundary table at the end
+of the file. The table is a sequence of big-endian 32-bit offsets. It begins
+with 24, ends with its own file offset, and therefore describes every chunk as
+a pair of adjacent boundaries. Each chunk starts with a big-endian 16-bit
+compressed-stream length followed by exactly that many codec bytes.
+The length value `0xffff` is a raw-block sentinel; in that case exactly
+10,000 uncompressed bytes follow.
+
+DiskExpander's `Block 10` setting divides unpacked data into decimal 10,000-byte
+chunks; the final chunk contains the remainder. Its bundled `xpkNUKE.library`
+identifies itself as NUKE 1.0 and is byte-identical to the public XPK 2.4-era
+library. Passing only the bytes after each two-byte chunk length to the NUKE
+decoder recovers the known 130-byte `Cancel.gads` sample to its 204-byte
+plaintext exactly.
+
+The identification comes from the recovered startup command
+`DiskExpander ... Compressor NUKE Block 10 Table 1000 ...`, the `$VER:
+DiskExpander 2.1` strings in its executable and handlers, and matching wrapper
+magic in those handlers. It is distinct from XFH and from the later `XPKF`
+container.

xfh-0.1.0/docs/oracle-matrix.md

@@ -0,0 +1,121 @@
+# Original-code oracle matrix
+
+The isolated oracle uses FS-UAE 3.2.35, Workbench 3.1, xpkmaster 4.16
+(21-Aug-1997), and recovered compressor libraries. ROMs, Amiga binaries,
+private files, logs, and the complete workspace are not distributed.
+
+`xQuery` reported these mode ranges:
+
+| Codec | Default | Ranges |
+| --- | ---: | --- |
+| NONE | 50 | 0–100 |
+| NUKE | 50 | 0–100 |
+| FAST | 50 | 0–79, 80–100 |
+| RAKE | 100 | 0–25, 26–50, 51–75, 76–100 |
+| HUFF | 50 | 0–100 |
+| SHRI | 100 | 0–14, 15–28, 29–42, 43–56, 57–70, 71–84, 85–100 |
+| DLTA | 100 | 0–100 |
+| SMPL | 50 | 0–100 |
+| HFMN | 0 | 0–100 |
+| MASH | 100 | 0–100 |
+| SQSH | 100 | 0–100 |
+| LZBS | 100 | 0, 1–10, 11–20, 21–30, 31–40, 41–50, 51–60, 61–70, 71–80, 81–90, 91–100 |
+| SLZ3 | 100 | 0–100 |
+| SDHC | 50 | 0–7, 8–15, 16–23, 24–31, 32–39, 40–47, 48–55, 56–63, 64–71, 72–79, 80–87, 88–100 |
+| LHLB | 100 | 0–100 |
+| BZP2 | 40 | 0–19, 20–29, 30–39, 40–49, 50–59, 60–69, 70–79, 80–89, 90–100 |
+| GZIP | 65 | 0–9, 10–19, 20–29, 30–39, 40–49, 50–59, 60–69, 70–79, 80–89, 90–100 |
+| IMPL | 100 | 0–10, 11–30, 31–50, 51–75, 76–98, 99–100 |
+
+The matrix exercised every numeric mode on a canonical text vector and every
+range boundary/default on deterministic pattern and size vectors:
+
+- 990 byte-exact pack/unpack successes;
+- 36 empty-input cases exposing an original-tool defect: a 36-byte XPKF header
+  is emitted, then rejected by the same master library;
+- one HUFF case which hangs after reporting successful compression, followed
+  by 11 deliberately unrun HUFF cases;
+- zero round-trip mismatches among completed non-empty cases.
+
+All 1,026 emitted containers begin with `XPKF`. Small representative fixtures
+for all six codecs are committed as reviewable hexadecimal files and validate
+the current pure-Python implementations.
+
+A second isolated run added `CBR0`, `RLEN`, `FRLE`, `RDCN`, `BLZW`, and
+`DUKE`. Across the completed non-empty cases, all 372 original packed/plain
+artifacts decode byte-exactly in Python. Compact acceptance containers for
+each codec are committed as hexadecimal fixtures. The historical packers are
+run in separate or short-lived emulator sessions because repeated use can
+crash the original Amiga process; this is an oracle limitation rather than an
+accepted decoder failure.
+
+A third set covers `DLTA`, `SMPL`, `HFMN`, `MASH`, and `SQSH`. Short isolated
+runs produced 35 byte-exact original pack/unpack artifacts across modes 0,
+default, and 100. Python directly decoded all 20 generated compressed DLTA,
+HFMN, MASH, and SQSH containers. The SMPL packer selected raw XPK chunks for
+all 15 vectors, so its decoder additionally has a source-derived synthetic
+prefix-code test rather than claiming compressed oracle coverage. DLTA hangs
+on a one-byte input and HFMN hangs on one broad byte-pattern input; those
+original-packer defects are excluded from the safe fixture stage.
+
+Every compact committed acceptance container is recorded in the public
+manifest with its input, output, size, and SHA-256 hashes. Known hanging
+packer/vector pairs are machine-readable exclusions and are never emitted
+into a guest stage. `oracle.py verify-python` performs the direct comparison
+and records its results as JSON.
+
+The CyberYAFA `LZW2`–`LZW5` variants are now backed by preserved original
+libraries and headless UAE fixtures across every reported mode boundary.
+`SHR3` remains source-derived because no corresponding original library has
+been located; it is additionally tested by converting both packed chunks from
+the 64 KiB SHRI continuation fixture to its headerless chunk representation.
+
+Preserved original `ACCA`, `FBR2`, `ILZR`, and `ZENO` libraries were also
+located and exercised under UAE. Together with the LZW family, 157 generated
+artifacts round-trip in the original master library and decode byte-exactly in
+Python. Compact fixtures, private library hashes, and the preservation archive
+hash are linked in the public manifest; the binaries themselves are not
+redistributed. `ARTM` remains source-derived because its original library has
+not been located. Compact source-derived XPK containers for these codecs were
+also independently compared byte-for-byte with Ancient 2.3.0 where Ancient
+supports the emitted variant.
+
+The next batch adds `LZBS`, `SLZ3`, `TDCS`, `LHLB`, `SDHC`, and `CYB2`.
+Preserved `LZBS`, `SLZ3`, and `SDHC` packers produced 83 completed artifacts
+across every reported mode boundary; Python decoded all of them byte-exactly.
+Low-mode LZBS output also confirmed that its original depacker stops a final
+literal run at the declared output size even when the packer rounds that run
+up. Representative original-Amiga fixtures for all three codecs are committed.
+
+`LHLB` initially appeared unpack-only because its required `lh.library` was
+missing. Installing the original Aminet dependency exposes its 0–100 packing
+range; a mode-100 artifact now round-trips in the Amiga master library and
+decodes byte-exactly in Python. The dependency hash is recorded in the public
+manifest, but the binary is not redistributed.
+
+`CYB2` still reports no packing modes. Its preserved library also requires
+`xpkcybhandle.library`; with that dependency and its `CYB1` companion installed,
+the original library continues to reject source-constructed CYB2 containers
+before unpacking. Consequently CYB2 remains source-derived rather than being
+mislabelled as original-Amiga verified. `TDCS` has no library in the
+preservation archive. Both retain synthetic success and malformed-stream
+coverage.
+
+Preserved BZP2, GZIP, and IMPL packers generated representative compressed
+fixtures that round-trip under headless UAE and decode byte-exactly in Python.
+The complete boundary/default matrix now contains 36 BZP2, 42 GZIP, 24 IMPL,
+and six LHLB byte-exact successes with no Python mismatches.
+
+PWPK, CRM2, and CRMS expose no packing modes in the preserved XPK libraries.
+An original Amiga PPMC utility generated the positive PowerPacker stream used
+by the PWPK fixture, which was also checked with Ancient. CRM2 and CRMS use
+positive streams generated and decoded by an independent Crunch-Mania
+implementation. Their XPK envelopes remain source-derived and are labelled
+accordingly.
+
+FS-UAE runs behind Xvfb with Mesa software rendering, so oracle generation
+does not map a window onto the host desktop.
+
+The recovered private wrapper beginning `01 80 63 68 05 61 01 0a` was not
+recognized as packed data by the original master library. That result rules
+out using generated XPKF files to infer its outer framing.

xfh-0.1.0/docs/release-checklist.md

@@ -0,0 +1,77 @@
+# Release checklist
+
+This checklist covers an `xfh` release. CI modernization is intentionally
+deferred to `example-python-project` so it can be back-ported consistently
+across repositories.
+
+## Prepare
+
+- Confirm the intended version and supported Python versions.
+- Confirm the `xfh` distribution name is still available on PyPI. A missing
+  project page does not reserve a name; only a successful upload does.
+- Create the PyPI project/account configuration, enable two-factor
+  authentication, and prefer a narrowly scoped trusted publisher or project
+  token.
+- Update `project.version` in `pyproject.toml`.
+- Check that the codec support table and recovery limitations match the code.
+- Review `git diff`, `git status`, and the commits included since the previous
+  release.
+
+## Validate
+
+Run the repository checks from a clean checkout:
+
+```console
+make coverage
+make lint
+make dist
+```
+
+Then verify the built artifacts rather than the source checkout:
+
+```console
+python -m venv ~/tmp/xfh-release-venv
+~/tmp/xfh-release-venv/bin/python -m pip install dist/xfh-*.whl
+~/tmp/xfh-release-venv/bin/xfh --help
+~/tmp/xfh-release-venv/bin/python -c "import xfh; print(xfh.__file__)"
+```
+
+- Inspect the wheel and source archive file lists for missing or private data.
+- Confirm `twine check dist/*` passes.
+- Exercise `info`, `verify`, and `unpack` against a known fixture with the
+  installed wheel.
+- Confirm strict failure, output-size limiting, overwrite refusal, and salvage
+  exit status/reporting still behave as documented.
+
+## Publish
+
+- Upload to TestPyPI first when changing packaging or publishing credentials.
+- Install the exact TestPyPI artifact in a fresh environment and repeat the
+  smoke test.
+- Tag the reviewed release commit with the exact project version, such as
+  `0.1.0`, and push the tag.
+- Upload exactly the already-reviewed artifacts to PyPI; do not rebuild between
+  TestPyPI and PyPI.
+- Create a GitHub release from the tag with concise release notes.
+
+The first PyPI upload bootstraps the project and therefore needs a temporary
+account-wide token:
+
+```console
+read -rsp "PyPI token: " PYPI_TOKEN && echo
+export PYPI_TOKEN
+make release
+unset PYPI_TOKEN
+```
+
+After that upload, replace it with a token scoped to the new `xfh` project.
+For a TestPyPI upload, additionally set `PYPI_REPOSITORY_URL` to the TestPyPI
+legacy upload endpoint.
+
+## Verify
+
+- Confirm the PyPI metadata, project links, license, Python requirement, wheel,
+  and source archive render correctly.
+- Install from PyPI in a fresh environment and repeat the fixture smoke test.
+- Confirm the GitHub tag and release point to the published source.
+- Announce material recovery limitations alongside the release.

xfh-0.1.0/docs/research/initial-findings.md

@@ -0,0 +1,107 @@
+# Initial XFH / xpkNUKE recovery notes
+
+## The job
+
+`~/Documents/amiga/amiga.ddr.img` is a 3-partition Amiga drive image. Its
+third partition, **dh2 `SHITE`**, ran **XFH** — the AmigaOS *xpk File
+Handler*, a DOS handler that transparently compresses everything written to
+a directory or partition via `xpkmaster.library`. **2,356 of its 5,276
+files** are compressed with the **xpkNUKE** sublibrary and cannot currently
+be read.
+
+| partition | sector range | crunched | total |
+|---|---|---|---|
+| dh1 `WORKBENCH` | 1536 + 82944 | 1 | 4,459 |
+| dh0 `WORK` | 84480 + 411648 | 0 | 7,433 |
+| **dh2 `SHITE`** | **496128 + 217344** | **2,356** | **5,276** |
+
+Goal: read them. The headline prize is `kaos/shit/` — 63 files of digitised
+animation frames from 1991–1995 by Matt Benson, Dave Gary, James Benson and
+John Hayes, including a claymation wombat with six arms, one of which falls
+off mid-animation. But it is 2,356 files in total, across `Other`, `Games`,
+`t`, `GadToolsBox`, `Legion`, `GMS` and more.
+
+## Why it is XFH and not someone crunching files
+
+- **252 crunched files in `t/`** — the temp directory. Nobody hand-crunches
+  temp files.
+- `.info` icons of ~300 bytes are crunched, where compression is pointless.
+- It spans a dozen unrelated drawers, and is confined to one partition.
+
+No `xpkmaster.library` and no XFH handler survive on the drive (only
+`xfdmaster`, bundled with virus checkers, which is the unrelated *decrunch*
+library). So the handler binary is not available to disassemble.
+
+## The container, as far as it is decoded
+
+Verified byte-exactly against `samples/matt1.info` (310 bytes on disk):
+
+```
++0   01 80 63 68 05 61 01 0a   constant magic, identical in every file
++8   ULONG   unpacked length            (460 for matt1.info)
++12  ULONG   length of everything from +8 onward
+                                        (302; and 302 + 8 = 310 = file size)
++16  "xpkNUKE\0"                8 bytes, NUL-padded
++24  compressed data
+```
+
+Sample sizes:
+
+| file | on disk | unpacked (from +8) |
+|---|---|---|
+| `matt1.info` | 310 | 460 |
+| `wombat1.pic` | 12,492 | 19,844 |
+| `wombat` | 112,134 | 122,780 |
+| `wombat2` | 190,746 | 206,006 |
+
+**Unsolved:** for `wombat` the arithmetic leaves 560 bytes unaccounted for
+(file − 8 − declared length). 560 = 35 × 16, and an XPK chunk header is 16
+bytes, so the payload is probably chunked with per-chunk headers. The small
+single-chunk files fit the simple layout; the large ones do not.
+
+## What has been ruled out
+
+**`ancient` (temisu, `apt install ancient`, installed) does NOT read these.**
+It implements xpkNUKE correctly, but expects an `XPKF` *stream*. These are
+XFH's container. Keep it installed anyway — it handles DMS and LhA, which
+the corpus is full of.
+
+`tools/try_xpkf.py` wraps the payload from +24 in a synthetic `XPKF` header
+and brute-forces all 256 header-checksum values, looking for one `ancient`
+will accept. It finds none, so the payload is not a bare XPK chunk stream —
+or the assumed 36-byte `XPKF` header layout is wrong. Worth retrying with
+other header lengths and with reconstructed chunk headers.
+
+## The lever: known plaintext, in quantity
+
+**382 filenames exist both crunched on dh2 and uncrunched on dh0/dh1.**
+Pick one whose uncrunched size matches the crunched file's declared unpacked
+length and you have a verified plaintext/ciphertext pair to develop and
+check against. Reproduce with:
+
+```bash
+# tools/amigapeek.ts <image> <path-filter> <first-sector> <blocks>
+# prints "size  path  <first 24 bytes as text>" per file
+npx tsx tools/amigapeek.ts ~/Documents/amiga/amiga.ddr.img "" 496128 217344 > peek-dh2.txt
+npx tsx tools/amigapeek.ts ~/Documents/amiga/amiga.ddr.img "" 84480 411648 > peek-dh0.txt
+grep xpkNUKE peek-dh2.txt | awk '{print $2}' | awk -F/ '{print $NF}' | LC_ALL=C sort -u > c.txt
+grep -v xpkNUKE peek-dh0.txt | awk '{print $2}' | awk -F/ '{print $NF}' | LC_ALL=C sort -u > u.txt
+LC_ALL=C comm -12 c.txt u.txt
+```
+
+## Tools here
+
+Run from `~/src/tmp/amos/amos-ts` (they import from its `src/`):
+
+- `tools/amigaget.ts <img> <path> <out> [sector] [blocks]` — extract one file
+- `tools/amigapeek.ts <img> <filter> [sector] [blocks]` — list files + first bytes
+- `tools/amigadates.ts <img> [--sector N] [--blocks N]` — real AmigaDOS
+  datestamps, tick precision
+- `tools/abk2png.ts <file.abk> <prefix>` — render an AMOS sprite/icon bank
+  (handles the `AmBs` multi-bank wrapper)
+- `tools/try_xpkf.py <file>` — the failed XPKF-wrapping experiment
+
+## Where this is written up
+
+`~/src/tmp/amos/dating-amos-games.md`, section "Blocked: dh2 ran an XPK
+filesystem packer".