# v0.6.4 — Byte-reproducibility hardening (pinned dependencies + auto-built Docker images)

**Released**: 2026-05-18
**Status**: Stable. First non-pre-release on the 0.6.x line since v0.6.1, intended to support the byte-level reproducibility claims in the companion Agentic SWMM paper.
**PyPI version string**: `0.6.4`

## How to install

```bash
pip install aiswmm                 # default install now resolves to v0.6.4
pip install aiswmm==0.6.4          # pin explicitly
docker pull ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.6.4   # multi-arch image
```

## One-sentence summary

v0.6.4 closes the three gaps that prevented the v0.6.x line from supporting end-to-end **byte-level reproducibility**: dependencies are now fully version-pinned via a committed `requirements.lock`, the Docker image is built reproducibly from that lockfile and from the USEPA SWMM 5.2.4 source, and Docker images are now built and pushed to GHCR automatically on every Git tag rather than on manual dispatch only.

## What changed

### 1. Fully pinned dependency set (`requirements.lock`)

A new top-level `requirements.lock` file pins every transitive dependency (86 lines, 14 declared top-level packages) at the exact versions used to generate the figures and SHA-256 hashes reported in the companion paper. Re-installing those exact versions on Python 3.11 (the Docker base image) is now a one-line command:

```bash
pip install -r requirements.lock
```

The lockfile is generated by:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r scripts/requirements.txt
pip freeze | grep -v "^-e git" | grep -v "^aiswmm==" > requirements.lock
```

Top-level declared packages remain in `scripts/requirements.txt` (unpinned, for human readability). The Dockerfile prefers `requirements.lock`, falling back to `scripts/requirements.txt` only if the lockfile is missing — so older tags continue to build, and new tags get byte-reproducible installs.

### 2. Reproducible Docker image, automatically built on tag push

`.github/workflows/docker.yml` now triggers on `push` for any tag matching `v*` (in addition to the previously-supported `workflow_dispatch`). Every Git tag `v0.6.4`, `v0.6.5`, `v0.7.0`, ... now automatically produces matching tagged images at `ghcr.io/zhonghao1995/agentic-swmm-workflow:<tag>`, plus a `latest` alias that follows the most recent tag. This guarantees that the Git tag and the published container image always exist as a pair.

The Dockerfile itself is unchanged in structure but now:

- Pins `AGENTIC_SWMM_REF` default to `v0.6.4`.
- Installs Python dependencies from `requirements.lock` (with a fallback path for older tags).
- Continues to rebuild SWMM 5.2.4 from the USEPA Stormwater-Management-Model source at git tag `v5.2.4`, so the SWMM binary in the image is byte-reproducible from upstream rather than fetched as a pre-built artifact.

### 3. CI hygiene

- The release commit and the release tag now both pass the existing `tests/test_no_private_machine_paths_in_public_docs.py` guard. v0.6.3a1 had a single offending file (the release-note draft) that has been redacted on `main` since #139; v0.6.4 re-runs the guard before tagging.
- `pyproject.toml`, `agentic_swmm/__init__.py`, `CITATION.cff`, `README.md`, and `docs/installation.md` are all bumped consistently to `0.6.4`. `CITATION.cff` had drifted to `0.5.0`; that is also corrected.

## Upgrade notes

- `pip install aiswmm` now installs `0.6.4` (a stable release), not v0.6.1. Users who were intentionally pinning to v0.6.1 should add an explicit pin.
- Users who depend on alpha behaviour from v0.6.2a1 / v0.6.3a1 should pin explicitly (those PyPI releases are unchanged).
- The Docker image tag `latest` now points to v0.6.4. CI builds for older tags are unchanged.

## What is NOT changed

- No SWMM engine changes. SWMM 5.2.4 source is still pulled from USEPA upstream.
- No public agent surface changes. All Skills, MCP servers, and CLI commands behave identically to v0.6.3-alpha.
- No QA / audit-gate behaviour changes. The verification-first provenance contract is identical.

## Companion paper alignment

This release matches the audit chain described in the companion Agentic SWMM paper Section 2.3.1: each run still emits a `manifest.json` and an `experiment_provenance.json` recording the INP/OUT/RPT SHA-256 hashes, the QA gate results (continuity errors, peak-metric integrity, SWMM return code, and the eight SWMM-specific screening rules), and the runtime context. With v0.6.4, any reader can reproduce those hashes bit-for-bit by pulling the matching Docker image:

```bash
docker pull ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.6.4
docker run --rm ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.6.4 acceptance
```
