ncarnate 2.2.1__tar.gz → 2.2.2__tar.gz

ncarnate-2.2.2/.github/workflows/ci.yml

@@ -0,0 +1,157 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# The pip-based jobs (test, test-windows-degraded, build) install no system
+# HDF libraries on purpose: the netCDF4 wheels bundle libhdf5/libnetcdf, and
+# the pyhdf >= 0.11.6 manylinux wheels bundle libhdf4 (verified against PyPI
+# 2026-07-08 for cp310-cp313). Platforms without a pyhdf wheel (e.g.
+# linux-aarch64) need a system libhdf4 for the sdist build instead. The
+# one deliberate exception is test-conda-forge, which provisions the whole
+# runtime stack (incl. a system-HDF4-linked pyhdf) from conda-forge to prove
+# the *supported* install channel delivers full HDF4 capability (KD-L7, G2).
+
+jobs:
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        # Minor-pinned so a future ruff release can't red a green branch with
+        # no code change (new lint rules land in version bumps). Bump
+        # deliberately; keep in step with the version developers run locally.
+        run: python -m pip install "ruff==0.15.*"
+      - name: Run ruff
+        run: ruff check .
+
+  test:
+    name: pytest (${{ matrix.os }} py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        # Smoke the self-contained-wheel install story (pyhdf + netCDF4 +
+        # pyproj, no system HDF libs) on macOS too. Windows is deliberately
+        # excluded from the *full* matrix: pyhdf's Windows wheel ships no
+        # HDF4 runtime, so the HDF4 fixtures can't run there. Windows-pip
+        # instead gets the dedicated degraded-capability job below
+        # (KD-L4/KD-L7), which pins exactly what must keep working — and
+        # exactly how the HDF4 path must refuse — without a usable pyhdf.
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with test extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+      - name: Run tests (offline; raw-granule marks self-skip)
+        run: python -m pytest -q
+
+  test-windows-degraded:
+    name: pytest degraded-capability (windows pip)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
+        with:
+          python-version: "3.12"
+      - name: Install package with test extras (pip wheels only)
+        # pyhdf's Windows wheel *installs* but cannot *import* (it ships no
+        # HDF4 runtime) — which is precisely the degraded environment this
+        # job exists to pin (KD-L4/KD-L7, gate G2).
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+      - name: Degraded-capability contract (tests/test_optional_hdf4.py)
+        # The purpose-built matrix: import / --help / --version / detection /
+        # netCDF recompression / audits all work without a usable pyhdf; an
+        # HDF4 attempt refuses with the stable HDF4_RUNTIME_UNAVAILABLE
+        # message before output creation, never an import traceback.
+        run: python -m pytest tests/test_optional_hdf4.py -q
+
+  test-conda-forge:
+    name: pytest full-capability (conda-forge)
+    runs-on: ubuntu-latest
+    # conda-forge is the *supported* HDF4 install channel (the refusal and
+    # the README point Windows/aarch64 users at `conda install -c
+    # conda-forge ncarnate`). This lane proves that channel actually
+    # delivers the full HDF4/HDF-EOS2 capability — a promise the pip matrix
+    # cannot make, since it relies on the bundled-libhdf4 pyhdf wheels
+    # rather than the conda-forge pyhdf built against a system HDF4
+    # (KD-L7 / priority step 2.5; gate G2 cannot close without it).
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+      - name: Provision a conda-forge full-capability environment
+        uses: mamba-org/setup-micromamba@d7c9bd84e824b79d2af72a2d4196c7f4300d3476  # v3.0.0
+        with:
+          environment-name: ncarnate-cf
+          # The runtime stack comes wholly from conda-forge — pyhdf here is
+          # built against a real HDF4 library, unlike the pip wheel's
+          # bundled runtime. Pin Python; float the rest to what the channel
+          # currently ships (the point is the channel's promise, not a
+          # frozen resolution).
+          condarc: |
+            channels:
+              - conda-forge
+            channel_priority: strict
+          create-args: >-
+            python=3.12
+            pyhdf
+            netCDF4
+            numpy
+            pyproj
+            tqdm
+            pytest
+      - name: Install ncarnate from source without replacing native deps
+        # --no-deps: install only ncarnate; the native stack (pyhdf,
+        # netCDF4, numpy, pyproj, tqdm) stays the conda-forge build. Build
+        # isolation still fetches the hatchling backend into a throwaway
+        # env, which never touches the runtime dependencies above.
+        run: python -m pip install -e . --no-deps
+      - name: Prove the conda-forge HDF4 runtime imports
+        run: |
+          python -c "from ncarnate.hdf4_runtime import require_hdf4_runtime; require_hdf4_runtime(); print('conda-forge HDF4 runtime OK')"
+      - name: Full suite — HDF4 import, conversion, audit, manifest on real fixtures
+        # The committed HDF4/HDF-EOS2 fixtures drive real conversions here
+        # (unlike the pip matrix's bundled-wheel path), exercising the
+        # supported channel end to end. Raw-granule tests self-skip offline.
+        run: python -m pytest -q
+
+  build:
+    name: build + twine check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install build twine
+      - name: Build sdist + wheel
+        run: python -m build
+      - name: Check distributions
+        run: twine check dist/*
+      - name: Validate distributions
+        run: >-
+          python tools/validate_distributions.py
+          --allowed-email dev@erickshepherd.com
+          --allowed-email ca@trufo.ai
+          dist/*

{ncarnate-2.2.1 → ncarnate-2.2.2}/.github/workflows/publish.yml

@@ -31,8 +31,8 @@ jobs:
     name: Build sdist + wheel
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
         with:
           python-version: "3.12"
       - name: Build
@@ -40,7 +40,8 @@ jobs:
           python -m pip install --upgrade build twine
           python -m build
           python -m twine check dist/*
-      - uses: actions/upload-artifact@v4
+          python tools/validate_distributions.py --allowed-email dev@erickshepherd.com --allowed-email ca@trufo.ai dist/*
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f  # v6.0.0
         with:
           name: dist
           path: dist/
@@ -54,11 +55,11 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131  # v7.0.0
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247  # v1.14.1
         with:
           repository-url: https://test.pypi.org/legacy/
           skip-existing: true  # re-dispatching a dry run for an existing version won't fail
@@ -72,8 +73,8 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131  # v7.0.0
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247  # v1.14.1

{ncarnate-2.2.1 → ncarnate-2.2.2}/.gitignore

@@ -15,6 +15,7 @@ venv/
 
 # Local scratch.
 tmp/
+brand/_work/
 
 # Audit orchestration sidecars (ephemeral analysis).
 docs/audits/*.run.log

{ncarnate-2.2.1 → ncarnate-2.2.2}/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [2.2.2] - 2026-07-21
+
+Maintenance release with packaging and CI updates. Conversion, recompression,
+audit, and verification behavior are unchanged.
+
+### Changed
+- Standardized package metadata and normalized bundled test fixtures.
+- Added automated distribution-policy validation.
+- Pinned GitHub Actions to reviewed immutable commits and current Node 24 action
+  releases.
+- Kept the bundled conda recipe on the last published PyPI artifact; its version
+  and source hash will be advanced together in a post-publication update after
+  the definitive 2.2.2 sdist exists.
+
 ## [2.2.1] - 2026-07-12
 
 A documentation and branding patch. **No functional changes** to conversion,

{ncarnate-2.2.1 → ncarnate-2.2.2}/CITATION.cff

@@ -9,10 +9,10 @@ type: software
 authors:
   - family-names: "Shepherd"
     given-names: "Erick Edward"
-    email: "Contact@ErickShepherd.com"
+    email: "dev@erickshepherd.com"
     orcid: "https://orcid.org/0000-0002-4750-6100"
-version: "2.2.1"
-date-released: "2026-07-12"
+version: "2.2.2"
+date-released: "2026-07-21"
 doi: "10.5281/zenodo.21288802"
 license: MIT
 repository-code: "https://github.com/ErickShepherd/ncarnate"

{ncarnate-2.2.1 → ncarnate-2.2.2}/CODE_OF_CONDUCT.md

@@ -57,7 +57,7 @@ an individual is officially representing the community in public spaces.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-**Contact@ErickShepherd.com**. All complaints will be reviewed and investigated
+**dev@erickshepherd.com**. All complaints will be reviewed and investigated
 promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

ncarnate-2.2.1/README.md → ncarnate-2.2.2/PKG-INFO

@@ -1,3 +1,40 @@
+Metadata-Version: 2.4
+Name: ncarnate
+Version: 2.2.2
+Summary: Convert HDF4/HDF-EOS2 (MODIS, AMSR-E) to CF-annotated netCDF4 and losslessly recompress netCDF/HDF5 files.
+Project-URL: Homepage, https://github.com/ErickShepherd/ncarnate
+Project-URL: Documentation, https://ncarnate.readthedocs.io/en/stable/
+Project-URL: Source, https://github.com/ErickShepherd/ncarnate
+Project-URL: Changelog, https://github.com/ErickShepherd/ncarnate/releases
+Project-URL: Issues, https://github.com/ErickShepherd/ncarnate/issues
+Author-email: Erick Shepherd <dev@erickshepherd.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: AMSR-E,CF conventions,GIS,HDF-EOS,HDF-EOS2,HDF4,HDF5,MODIS,atmospheric science,compression,geolocation,grid,netCDF,netCDF4,recompression,remote sensing,swath,xarray
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: netcdf4>=1.6
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyhdf>=0.11.6
+Requires-Dist: pyproj>=3.6
+Requires-Dist: tqdm>=4.66
+Provides-Extra: test
+Requires-Dist: build>=1.0; extra == 'test'
+Requires-Dist: hatchling>=1.27; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup-dark.png">
@@ -41,7 +78,7 @@ Reach for ncarnate if you are trying to:
 - **Shrink an archive of scientific files** without risking the science: every
   output is verified value-for-value against its source before it replaces
   anything, and stored values round-trip value-identically (bit-for-bit for
-  integer and packed data; NaN- and signed-zero-insensitive for floating-point/complex).
+  integer and packed data; NaN- and signed-zero-insensitive for floating point).
 - **Batch-convert a directory tree** of legacy granules to modern netCDF4 in one
   command.
 
@@ -50,13 +87,19 @@ Reach for ncarnate if you are trying to:
 Converting or recompressing a file changes *storage*, never *science data*:
 
 - Every variable's stored values are preserved **value-identically** — bit-for-bit
-  for integer and packed data; for floating-point and complex data, distinct NaN
+  for integer and packed data; for floating-point data, distinct NaN
   bit-patterns and `-0.0`/`+0.0` compare equal. Packed integers stay packed;
   `scale_factor`/`add_offset`/`_FillValue` are carried across as declarations,
   never applied.
-- Every dimension (including unlimited-ness), attribute (including its type), and
-  group survives. HDF-EOS2 `StructMetadata` is preserved verbatim; names netCDF
-  cannot hold are sanitized with the original recorded in a companion attribute.
+- Every dimension (including unlimited-ness), attribute (including its exact
+  storage type — an `NC_STRING` scalar stays `NC_STRING`, verified via netCDF-C
+  type inquiry), and group survives. HDF-EOS2 `StructMetadata` is preserved
+  verbatim; names netCDF cannot hold are sanitized with the original recorded in
+  a companion attribute.
+- **Complex-valued variables (`complex64`/`complex128`) are excluded** from the
+  fidelity guarantee: netCDF stores them as compound types, which ncarnate
+  **refuses loudly** with the stable `UNSUPPORTED_TYPE` error rather than
+  guessing at a lossy copy. Complex support is a later, evidence-backed feature.
 - Geolocation reconstruction is strictly **additive**: the original information
   always rides along, so the conversion never becomes the only copy of the
   truth. Swath coordinates are attached to variables whose first two axes are
@@ -97,11 +140,18 @@ required. On platforms without a repaired `pyhdf` wheel (e.g. Linux aarch64),
 building from sdist requires the system HDF4 library first (Debian/Ubuntu:
 `apt install libhdf4-dev`).
 
-**Windows via pip:** the netCDF/HDF5 *recompression* path works from PyPI wheels
-out of the box, but the HDF4/HDF-EOS2 *conversion* path does **not** — `pyhdf`'s
-Windows wheel ships no HDF4 runtime, so `import pyhdf` fails with a DLL-load
-error. Use the conda-forge install above for HDF4 on Windows (or **WSL** with the
-pip instructions).
+**Windows via pip:** PyPI wheels give you the full netCDF/HDF5 surface —
+`import ncarnate`, the CLI (`--help`/`--version`), format detection, audits,
+manifest runs, and verified recompression — but **not** HDF4/HDF-EOS2
+*conversion*: `pyhdf`'s Windows wheel ships no HDF4 runtime. An HDF4 attempt
+is refused cleanly **before any output is created** with the stable
+`[HDF4_RUNTIME_UNAVAILABLE]` message naming the detected cause, the
+capabilities that still work, and the fix — never an unexplained import
+traceback. An audit of an archive containing HDF4 files still completes,
+recording those files as `unsupported` with the same code. For HDF4 on
+Windows use the conda-forge install above (or **WSL** with the pip
+instructions); a dedicated CI job pins this degraded-capability contract on
+every change.
 
 ## Command line usage
 
@@ -176,6 +226,19 @@ The end-of-run summary counts converted / skipped / failed with reasons, and the
 exit code is non-zero **iff** a selected record failed — so a partial failure on
 a terabyte run surfaces loudly instead of silently mis-converting.
 
+**Destination collision preflight.** Before any directory or output file is
+created, every selected record's destination is computed up front — from the
+source's *detected bytes*, never the manifest's declared format — and any
+collision refuses the **entire run** with exit code 2 and a stable
+`[DESTINATION_COLLISION]` message on stderr listing every involved source and
+the contested destination. No last-writer-wins, no auto-rename, no partial
+proceed, and nothing is written. Refused collisions include: two records
+landing on one output path (e.g. an `a.hdf` → `a.nc` conversion next to a real
+`a.nc` sibling), case-fold-equivalent names (one file on NTFS/APFS), duplicate
+records for one source, an output tree overlapping a source tree (symlinks
+resolved), and a pre-existing destination unless you pass `--skip-existing` to
+resume.
+
 ## Library usage
 
 ```python

ncarnate-2.2.1/PKG-INFO → ncarnate-2.2.2/README.md

@@ -1,37 +1,3 @@
-Metadata-Version: 2.4
-Name: ncarnate
-Version: 2.2.1
-Summary: Convert HDF4/HDF-EOS2 (MODIS, AMSR-E) to CF-annotated netCDF4 and losslessly recompress netCDF/HDF5 files.
-Project-URL: Homepage, https://github.com/ErickShepherd/ncarnate
-Project-URL: Documentation, https://ncarnate.readthedocs.io/en/latest/
-Project-URL: Source, https://github.com/ErickShepherd/ncarnate
-Project-URL: Bug Tracker, https://github.com/ErickShepherd/ncarnate/issues
-Author-email: Erick Shepherd <Contact@ErickShepherd.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: AMSR-E,CF conventions,GIS,HDF-EOS,HDF-EOS2,HDF4,HDF5,MODIS,atmospheric science,compression,geolocation,grid,netCDF,netCDF4,recompression,remote sensing,swath,xarray
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Science/Research
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-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: Topic :: Scientific/Engineering :: Atmospheric Science
-Classifier: Topic :: Scientific/Engineering :: GIS
-Requires-Python: >=3.10
-Requires-Dist: netcdf4>=1.6
-Requires-Dist: numpy>=1.26
-Requires-Dist: pyhdf>=0.11.6
-Requires-Dist: pyproj>=3.6
-Requires-Dist: tqdm>=4.66
-Provides-Extra: test
-Requires-Dist: pytest; extra == 'test'
-Description-Content-Type: text/markdown
-
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup-dark.png">
@@ -75,7 +41,7 @@ Reach for ncarnate if you are trying to:
 - **Shrink an archive of scientific files** without risking the science: every
   output is verified value-for-value against its source before it replaces
   anything, and stored values round-trip value-identically (bit-for-bit for
-  integer and packed data; NaN- and signed-zero-insensitive for floating-point/complex).
+  integer and packed data; NaN- and signed-zero-insensitive for floating point).
 - **Batch-convert a directory tree** of legacy granules to modern netCDF4 in one
   command.
 
@@ -84,13 +50,19 @@ Reach for ncarnate if you are trying to:
 Converting or recompressing a file changes *storage*, never *science data*:
 
 - Every variable's stored values are preserved **value-identically** — bit-for-bit
-  for integer and packed data; for floating-point and complex data, distinct NaN
+  for integer and packed data; for floating-point data, distinct NaN
   bit-patterns and `-0.0`/`+0.0` compare equal. Packed integers stay packed;
   `scale_factor`/`add_offset`/`_FillValue` are carried across as declarations,
   never applied.
-- Every dimension (including unlimited-ness), attribute (including its type), and
-  group survives. HDF-EOS2 `StructMetadata` is preserved verbatim; names netCDF
-  cannot hold are sanitized with the original recorded in a companion attribute.
+- Every dimension (including unlimited-ness), attribute (including its exact
+  storage type — an `NC_STRING` scalar stays `NC_STRING`, verified via netCDF-C
+  type inquiry), and group survives. HDF-EOS2 `StructMetadata` is preserved
+  verbatim; names netCDF cannot hold are sanitized with the original recorded in
+  a companion attribute.
+- **Complex-valued variables (`complex64`/`complex128`) are excluded** from the
+  fidelity guarantee: netCDF stores them as compound types, which ncarnate
+  **refuses loudly** with the stable `UNSUPPORTED_TYPE` error rather than
+  guessing at a lossy copy. Complex support is a later, evidence-backed feature.
 - Geolocation reconstruction is strictly **additive**: the original information
   always rides along, so the conversion never becomes the only copy of the
   truth. Swath coordinates are attached to variables whose first two axes are
@@ -131,11 +103,18 @@ required. On platforms without a repaired `pyhdf` wheel (e.g. Linux aarch64),
 building from sdist requires the system HDF4 library first (Debian/Ubuntu:
 `apt install libhdf4-dev`).
 
-**Windows via pip:** the netCDF/HDF5 *recompression* path works from PyPI wheels
-out of the box, but the HDF4/HDF-EOS2 *conversion* path does **not** — `pyhdf`'s
-Windows wheel ships no HDF4 runtime, so `import pyhdf` fails with a DLL-load
-error. Use the conda-forge install above for HDF4 on Windows (or **WSL** with the
-pip instructions).
+**Windows via pip:** PyPI wheels give you the full netCDF/HDF5 surface —
+`import ncarnate`, the CLI (`--help`/`--version`), format detection, audits,
+manifest runs, and verified recompression — but **not** HDF4/HDF-EOS2
+*conversion*: `pyhdf`'s Windows wheel ships no HDF4 runtime. An HDF4 attempt
+is refused cleanly **before any output is created** with the stable
+`[HDF4_RUNTIME_UNAVAILABLE]` message naming the detected cause, the
+capabilities that still work, and the fix — never an unexplained import
+traceback. An audit of an archive containing HDF4 files still completes,
+recording those files as `unsupported` with the same code. For HDF4 on
+Windows use the conda-forge install above (or **WSL** with the pip
+instructions); a dedicated CI job pins this degraded-capability contract on
+every change.
 
 ## Command line usage
 
@@ -210,6 +189,19 @@ The end-of-run summary counts converted / skipped / failed with reasons, and the
 exit code is non-zero **iff** a selected record failed — so a partial failure on
 a terabyte run surfaces loudly instead of silently mis-converting.
 
+**Destination collision preflight.** Before any directory or output file is
+created, every selected record's destination is computed up front — from the
+source's *detected bytes*, never the manifest's declared format — and any
+collision refuses the **entire run** with exit code 2 and a stable
+`[DESTINATION_COLLISION]` message on stderr listing every involved source and
+the contested destination. No last-writer-wins, no auto-rename, no partial
+proceed, and nothing is written. Refused collisions include: two records
+landing on one output path (e.g. an `a.hdf` → `a.nc` conversion next to a real
+`a.nc` sibling), case-fold-equivalent names (one file on NTFS/APFS), duplicate
+records for one source, an output tree overlapping a source tree (symlinks
+resolved), and a pre-existing destination unless you pass `--skip-existing` to
+resume.
+
 ## Library usage
 
 ```python

{ncarnate-2.2.1 → ncarnate-2.2.2}/conda-recipe/recipe.yaml

@@ -1,7 +1,10 @@
 schema_version: 1
 
 context:
-  version: "2.2.0"
+  # Keep this on the last published PyPI artifact. Updating the recipe to a
+  # new release requires that release's definitive sdist SHA-256 and therefore
+  # happens only after the new sdist exists on PyPI.
+  version: "2.2.1"
 
 package:
   name: ncarnate
@@ -9,7 +12,7 @@ package:
 
 source:
   url: https://pypi.org/packages/source/n/ncarnate/ncarnate-${{ version }}.tar.gz
-  sha256: f1e3c9f7de98d11ee91e93db1d6e251ec82071762baabe133eb3bd0b44b5aeb5
+  sha256: 213760512d0272a97148728463c41dc49c2142dd70b95fc11e8ce3df9603d98e
 
 build:
   number: 0

{ncarnate-2.2.1 → ncarnate-2.2.2}/docs/fidelity-notes.md

@@ -12,7 +12,8 @@ changes *storage* (compression level, shuffle, chunk/endian layout, container fo
 ### netCDF/HDF5 → netCDF4 (recompression)
 
 Guaranteed preserved when read raw (`set_auto_maskandscale(False)`), value-identical —
-bit-for-bit for integer/packed data, NaN- and signed-zero-insensitive for floating-point/complex:
+bit-for-bit for integer/packed data, NaN- and signed-zero-insensitive for floating point
+(complex is excluded — see the guarantee boundary):
 
 - every variable's stored values (packed integers stay packed — no mask-and-scale
   round-trip, which silently re-quantizes);
@@ -30,7 +31,8 @@ replaced until the new file has been written and re-opened successfully.
 
 - every SDS's values value-identical — bit-for-bit for integer and char8 data (char8 SDS
   map to netCDF `NC_CHAR` and round-trip byte-for-byte), NaN- and signed-zero-insensitive
-  for floating-point/complex; dimensions (with their HDF4 names) and attributes preserved; fill/scale
+  for floating point (HDF4's DFNT type system has no complex type, so complex never
+  arises on this path); dimensions (with their HDF4 names) and attributes preserved; fill/scale
   carried as declarations;
 - `StructMetadata.0` (and other EOS metadata attributes) preserved **verbatim** as
   attributes of an `HDFEOS_INFORMATION` group — reconstruction never becomes the only copy
@@ -64,11 +66,35 @@ edges). Interpolated variables carry a `comment` attribute saying they are inter
 edge pixels outside the geolocation envelope are linearly extrapolated; geolocation fill
 propagates, never interpolated across.
 
+### Manifest runs: destination collision preflight (no-data-loss gate)
+
+Fidelity is meaningless if two outputs silently overwrite each other, so
+manifest-driven runs (`convert --manifest`) add a **whole-run destination
+preflight** before any directory or output is created: every selected record's
+destination is computed up front from its *detected bytes* (never the
+manifest's declared format — the manifest is untrusted input), and any
+collision refuses the **entire run** with the stable `DESTINATION_COLLISION`
+code (exit code 2, rendered on stderr) listing every involved source and the
+contested destination. No last-writer-wins, no auto-rename, no partial
+proceed, zero output-tree mutation. Refused classes: duplicate or
+case-fold-equivalent destinations (one file on NTFS/APFS), an `.hdf` → `.nc`
+conversion colliding with a real `.nc` sibling, duplicate records for one
+source (symlink-aliased included), source-tree/output-tree overlap (symlinks
+resolved), a destination aliasing a selected source, and a pre-existing
+destination without `--skip-existing`. Pinned end-to-end — including the
+zero-mutation guarantee at the process boundary — by
+`tests/test_convert_collisions.py`.
+
 ### Guarantee boundary
 
 - Compound, VLen, enum, and opaque netCDF4 types are **out of scope for v2**: ncarnate
-  raises a clear unsupported-type error rather than guessing (none of the target-domain
-  files surveyed use them; revisit on demand).
+  raises a clear unsupported-type error (stable code `UNSUPPORTED_TYPE`) rather than
+  guessing (none of the target-domain files surveyed use them; revisit on demand).
+- **Complex-valued variables (`complex64`/`complex128`) are excluded from the fidelity
+  guarantee** (owner decision, 2026-07-16): netCDF stores recognized complex encodings
+  as compound types (e.g. `_PFNC_DOUBLE_COMPLEX_TYPE`), so they are refused by the
+  compound rule above — loudly, with `UNSUPPORTED_TYPE`, before any output is written.
+  Complex support is a later, evidence-backed feature, not a silent partial copy.
 - Already-lossy packing is preserved as-is, never "un-quantized".
 - HDF4 inputs are read via the pyhdf SD API: SDS datasets and attributes. Vdata/Vgroup
   payloads beyond SD are out of scope for v2.
@@ -77,9 +103,10 @@ propagates, never interpolated across.
 
 For every committed fixture: convert/recompress → re-open both files raw → assert
 (a) value arrays equal on raw reads (`numpy.array_equal`, with `equal_nan` set for
-float/complex — bit-for-bit for integer/packed data, NaN-/±0-insensitive for floats), (b) dimension names,
-sizes, and unlimited flags equal, (c) attribute sets equal (fill/scale compared as
-declarations), (d) group tree equal, and (e) output ≤ input size at `complevel≥7` for the
+floats — bit-for-bit for integer/packed data, NaN-/±0-insensitive for floats), (b) dimension names,
+sizes, and unlimited flags equal, (c) attribute sets equal — values *and* netCDF storage
+types (`NC_STRING` vs `NC_CHAR`, via netCDF-C `nc_inq_atttype`; `tests/test_attribute_types.py`)
+— (d) group tree equal, and (e) output ≤ input size at `complevel≥7` for the
 compressible fixtures. The packed-integer + `_FillValue` fixture exists precisely because
 v1 failed both (a crash and a silent re-quantization).
 
@@ -102,7 +129,7 @@ exactly (written with each source attribute's true HDF4 type code via `attr.info
 inferred from type-erased Python values — e.g. an INT16 `_FillValue` stays INT16).
 
 HDF-EOS2 fixtures are trimmed from real granules kept outside the repo
-(`~/ncarnate-data/granules/` + `PROVENANCE.md` there); each fixture has a
+(`the local source-granule archive/` + `PROVENANCE.md` there); each fixture has a
 `.provenance.json` sidecar (source granule, SHA-256, trim parameters). Trim rules: the
 AMSR-E grid fixture keeps `StructMetadata.0` **verbatim** (grid dims unchanged; metadata
 lists DataFields not carried over — readers must tolerate that, as with subsetted granules
@@ -115,23 +142,3 @@ values *and* HDF4 type codes preserved) passed 2026-07-08.
 
 Raw-granule cross-checks (the 29–60 MB originals) stay in a local, non-CI test mark.
 
-## History-rewrite record (D1 + D2, executed 2026-07-08)
-
-Executed in one `git filter-repo` pass (per
-[the plan](plans/2026-07-08-repo-improvement-plan.md) §2 D1/D2), before any v2 code:
-
-- **Stripped from all history:** `netcdf_recompressor/AMSR_E_L3_SeaIce12km_V15_20070101.hdf`
-  (62.5 MB), `netcdf4_compressor/AMSR_E_L3_SeaIce12km_V15_20070101.hdf` (62.1 MB),
-  `netcdf4_compressor/2007_MYD_CALIPSO_ice_cloud_collocation_discrepancies_test.nc` (9.5 MB).
-- **Author/committer rewrite:** the owner's private Gmail → `24425940+ErickShepherd@users.noreply.github.com`
-  (mailmap in the same pass); local `user.email` set to the noreply address.
-- **Pack size:** `size-pack` **30.20 MiB → 61.70 KiB** (`git count-objects -vH`, after
-  `git gc --prune=now`); `.git` = 264 KB on disk. No `.hdf`/`.nc` objects remain in
-  `git rev-list --all --objects`.
-- **Content integrity:** the rewritten tip's tree hash equals the pre-rewrite tip's tree
-  (`12761123d5d26d62e2025abe8f5dfcf3e360ef3c`) — file content is untouched; only history
-  metadata changed.
-- **Backup:** full pre-rewrite bundle at
-  `~/ncarnate-data/backup/netcdf_recompressor-pre-rewrite-20260708.bundle`
-  (`git bundle verify` clean). All commit SHAs changed, as planned and victimless
-  (repo never public). **Pushing the rewritten history remains owner-gated.**

ncarnate-2.2.2/docs/index.rst

@@ -0,0 +1,30 @@
+.. Theme-aware logo for Read the Docs. The README's <picture> block keys off the OS
+   ``prefers-color-scheme``, which does NOT track furo's independent light/dark toggle
+   (toggling furo to light while the OS is in dark mode otherwise shows the dark,
+   cream-wordmark logo on a white page). Furo's ``.only-light`` / ``.only-dark`` classes
+   follow furo's ACTUAL theme, so render the logo with those here and skip the README's
+   own <picture> in the include below (``:start-after: </p>`` drops the logo block, whose
+   closing ``</p>`` is unique in the README).
+
+.. image:: https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup.png
+   :class: only-light
+   :width: 460
+   :align: center
+   :alt: ncarnate
+
+.. image:: https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup-dark.png
+   :class: only-dark
+   :width: 460
+   :align: center
+   :alt: ncarnate
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+   :start-after: </p>
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   Overview <self>
+   API reference <api>