ncarnate 2.2.0__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.0 → 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.0 → 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.0 → ncarnate-2.2.2}/CHANGELOG.md

@@ -4,6 +4,43 @@ 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,
+recompression, or verification behavior — the fidelity guarantee is unchanged;
+this release only describes it more precisely and dresses up the project.
+
+### Changed
+- Fidelity wording now matches what the verifier enforces. The data-preservation
+  guarantee is described as **value-identical** — bit-for-bit for integer, char,
+  and packed data; NaN- and signed-zero-insensitive for floating-point/complex — in the
+  README, `docs/fidelity-notes.md`, and the HDF4 module docstring, replacing the
+  blanket "bit-identical" (which overstated the guarantee for float data, since
+  the verifiers compare floats with `numpy.array_equal(equal_nan=True)`).
+
+### Added
+- Brand assets and a theme-aware README logo lockup (light/dark), plus live
+  PyPI, conda-forge, and Read the Docs badges.
+
+### Fixed
+- Read the Docs build stays green under current `myst-parser` by suppressing the
+  `myst.header` advisory (the strict `fail_on_warning` build would otherwise fail
+  on the README-derived landing page).
+
 ## [2.2.0] - 2026-07-11
 
 The archive-modernization workflow: a read-only **audit** that plans a

{ncarnate-2.2.0 → 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.0"
-date-released: "2026-07-11"
+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.0 → 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.0 → ncarnate-2.2.2}/PKG-INFO

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: ncarnate
-Version: 2.2.0
+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/latest/
+Project-URL: Documentation, https://ncarnate.readthedocs.io/en/stable/
 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>
+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 :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
@@ -29,12 +30,22 @@ 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
 
-# ncarnate
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup-dark.png">
+    <img alt="ncarnate" src="https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup.png" width="460">
+  </picture>
+</p>
 
 [![CI status](https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml/badge.svg)](https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/ncarnate.svg)](https://pypi.org/project/ncarnate/)
+[![conda-forge version](https://img.shields.io/conda/vn/conda-forge/ncarnate.svg)](https://anaconda.org/conda-forge/ncarnate)
+[![Docs](https://readthedocs.org/projects/ncarnate/badge/?version=latest)](https://ncarnate.readthedocs.io/en/latest/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ErickShepherd/ncarnate/blob/main/LICENSE)
 [![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](https://pypi.org/project/ncarnate/)
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21288802-blue)](https://doi.org/10.5281/zenodo.21288802)
@@ -66,7 +77,8 @@ Reach for ncarnate if you are trying to:
   filter without altering a single stored value.
 - **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 bit-identically.
+  anything, and stored values round-trip value-identically (bit-for-bit for
+  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.
 
@@ -74,12 +86,20 @@ 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 **bit-identically** — 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 variable's stored values are preserved **value-identically** — bit-for-bit
+  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 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
@@ -120,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
 
@@ -199,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
@@ -228,7 +268,7 @@ The AMSR-E daily 12.5 km sea-ice granule this project grew up around:
 | netCDF4 recompression (`--complevel 9`) | 42.6 MB | 19.9 MB |
 | HDF-EOS2 → netCDF4 (+ reconstructed lat/lon) | 60.2 MB | 35.5 MB |
 
-Both outputs re-read bit-identically to their sources; the conversion
+Both outputs re-read value-identically to their sources; the conversion
 additionally carries CF `polar_stereographic` grid mappings and coordinates for
 both hemispheric grids. The northern grid's reconstructed latitudes/longitudes
 agree with The HDF Group's independent conversion of the same granule to within

{ncarnate-2.2.0 → ncarnate-2.2.2}/README.md

@@ -1,6 +1,14 @@
-# ncarnate
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup-dark.png">
+    <img alt="ncarnate" src="https://raw.githubusercontent.com/ErickShepherd/ncarnate/main/brand/ncarnate-lockup.png" width="460">
+  </picture>
+</p>
 
 [![CI status](https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml/badge.svg)](https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/ncarnate.svg)](https://pypi.org/project/ncarnate/)
+[![conda-forge version](https://img.shields.io/conda/vn/conda-forge/ncarnate.svg)](https://anaconda.org/conda-forge/ncarnate)
+[![Docs](https://readthedocs.org/projects/ncarnate/badge/?version=latest)](https://ncarnate.readthedocs.io/en/latest/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ErickShepherd/ncarnate/blob/main/LICENSE)
 [![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](https://pypi.org/project/ncarnate/)
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21288802-blue)](https://doi.org/10.5281/zenodo.21288802)
@@ -32,7 +40,8 @@ Reach for ncarnate if you are trying to:
   filter without altering a single stored value.
 - **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 bit-identically.
+  anything, and stored values round-trip value-identically (bit-for-bit for
+  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.
 
@@ -40,12 +49,20 @@ 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 **bit-identically** — 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 variable's stored values are preserved **value-identically** — bit-for-bit
+  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 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
@@ -86,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
 
@@ -165,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
@@ -194,7 +231,7 @@ The AMSR-E daily 12.5 km sea-ice granule this project grew up around:
 | netCDF4 recompression (`--complevel 9`) | 42.6 MB | 19.9 MB |
 | HDF-EOS2 → netCDF4 (+ reconstructed lat/lon) | 60.2 MB | 35.5 MB |
 
-Both outputs re-read bit-identically to their sources; the conversion
+Both outputs re-read value-identically to their sources; the conversion
 additionally carries CF `polar_stereographic` grid mappings and coordinates for
 both hemispheric grids. The northern grid's reconstructed latitudes/longitudes
 agree with The HDF Group's independent conversion of the same granule to within

ncarnate-2.2.2/brand/README.md

@@ -0,0 +1,81 @@
+# Brand assets
+
+The ncarnate mark: a phoenix rising from an orbited globe — legacy satellite and
+geospatial data reincarnated as modern netCDF4. The Earth is drawn as a
+latitude/longitude graticule (the gridded scientific data); an orbital band
+sweeps around it (a nod to the satellite granules ncarnate reincarnates); and the
+phoenix rises from it, an ember crest at its head — the spark of rebirth.
+
+## Files
+
+| File | Use |
+|---|---|
+| `ncarnate.svg` | Primary mark — full colour on the rounded navy tile (app-icon / avatar). |
+| `ncarnate-mono.svg` | Single-ink navy silhouette, transparent — one-colour contexts on light backgrounds. |
+| `ncarnate-white.svg` | Single-ink off-white silhouette, transparent — for dark backgrounds. |
+| `ncarnate-wordmark.svg` / `-white.svg` | The word alone (Sora SemiBold, outlined). |
+| `ncarnate-lockup.png` / `-dark.png` | **Shipped lockup** — source mark tile (raster) + wordmark, horizontal. `-dark` recolours the wordmark off-white for dark backgrounds (the mark tile reads on both themes). |
+| `ncarnate-mark.png` | The source mark tile alone, with transparent rounded corners (favicon / social / reuse). |
+| `ncarnate-lockup.svg` / `-dark.svg` | Fully-vector lockup — **work in progress**, not yet shipped (see below). |
+
+The project README header swaps `ncarnate-lockup.png` ⇄ `-dark.png` by
+`prefers-color-scheme` via `<picture>`. The wordmark inside is glyph **outlines**
+(no font needed to render); it is rasterized into the shipped PNG lockup.
+
+### Vector globe: deferred
+
+The mark's thin globe **graticule** has not yet re-drawn cleanly as vectors — a
+generated two-tilt globe (`compose_logo.py` + `globe.py`) matches at display scale
+but its acceptance against the source is still open. Rather than block the release on
+it, the **shipped lockup embeds the approved `ncarnate-source.png` mark as raster**
+(`build_raster_lockup.py`), which is crisp at the README's display size. The vector
+mark (`ncarnate.svg`, `ncarnate-lockup.svg`) remains in-repo as work in progress;
+when it is accepted, swap the `<image>` in `build_raster_lockup.py` back to the
+vector paths and the README layout is unchanged. See
+`docs/plans/2026-07-11-logo-fidelity-regen.md`.
+
+## Palette
+
+| | Hex | Role |
+|---|---|---|
+| Deep navy | `#152A47` | Field / primary ink |
+| Warm off-white | `#F2EDE1` | Structure (phoenix + graticule) |
+| Ember | `#E8843C` | Crest flame — the spark of rebirth |
+
+Wordmark type: **Sora SemiBold** (weight 600), SIL Open Font License 1.1.
+
+## Regenerating
+
+`ncarnate-source.png` is the approved raster — a flat, hard-edged emblem made by
+an image model (the pictorial mark), used here as a **placement reference**: the
+phoenix is traced from it, while the globe/orbit geometry (centre, radius, tilt)
+is *measured* from it and then generated as vector primitives, not traced.
+
+`compose_logo.py` does the hybrid composition (deps: `vtracer`, `pillow`, `scipy`,
+`numpy`; `globe.py` is pure-stdlib): it splits the raster into field / phoenix /
+ember, masks the globe + orbit out of the structure so only the organic phoenix is
+traced, generates the graticule globe + orbit ring via `globe.py`, and layers them
+(tile → globe → orbit-back → phoenix → orbit-front → ember). The globe geometry
+(`CX, CY, R, TILT, MERIDIANS, PARALLELS`, orbit params) lives in constants at the
+top of `compose_logo.py`; to re-fit it to a new raster, overlay `globe.py --out`
+on the raster and nudge until the limb/graticule line up.
+
+```bash
+# deps: vtracer, fonttools, pillow, scipy, numpy  (+ cairosvg or @resvg/resvg-js to rasterise for the eyeball check)
+python3 compose_logo.py ncarnate-source.png ncarnate.svg   # mark + -mono + -white
+
+# fetch Sora and instance to weight 600:
+#   curl -sL -o sora-var.ttf "https://raw.githubusercontent.com/google/fonts/main/ofl/sora/Sora%5Bwght%5D.ttf"
+#   python3 -c "from fontTools import ttLib; from fontTools.varLib.instancer import instantiateVariableFont as I; f=ttLib.TTFont('sora-var.ttf'); I(f,{'wght':600},inplace=True); f.save('sora-600.ttf')"
+python3 build_lockup.py --text ncarnate --font sora-600.ttf --mark ncarnate.svg \
+    --field '#152A47' --structure '#F2EDE1' --out-prefix ncarnate   # wordmark + light/dark VECTOR lockups (WIP)
+
+# shipped lockup: raster source mark + wordmark, light/dark PNG (deps: fonttools, pillow, numpy, scipy, cairosvg)
+python3 build_raster_lockup.py --font sora-600.ttf                 # ncarnate-lockup{,-dark}.png + ncarnate-mark.png
+```
+
+Verify on both GitHub themes before committing — render each lockup on `#ffffff`
+and `#0d1117` and confirm the wordmark is legible on each. The globe is generated,
+so also zoom to a meridian×parallel crossing near the central meridian and confirm
+uniform stroke width through the crossing, true concentric arcs, even meridian
+spacing, and clean round caps.