Release simpleaf 0.28 integration

.github/alevin-fry-v0.18-integration.md

@@ -0,0 +1,50 @@
+# Temporary alevin-fry 0.18 integration checklist
+
+This tracked note is the release handoff from alevin-fry 0.18 to simpleaf
+0.28. Delete it only after every row is implemented, documented, and tested;
+the commit history will retain the context without making this permanent user
+documentation.
+
+## Argument forwarding
+
+| Status | simpleaf command | simpleaf option | alevin-fry destination | Inherited default |
+|---|---|---|---|---|
+| [x] | `quant`, `multiplex-quant` | `--cell-bc-correction` | GPL same name | Unique |
+| [x] | `quant`, `multiplex-quant` | `--cell-bc-neighborhood` | GPL same name | Protocol/filter-specific |
+| [x] | `quant`, `multiplex-quant` | `--cell-bc-confidence` | GPL same name | 97.5% |
+| [x] | `quant`, `multiplex-quant` | `--collate-memory-limit` | collate `--memory-limit` | 2 GiB |
+| [x] | `multiplex-quant` | `--sample-bc-correction` | GPL same name | Exact |
+| [x] | `multiplex-quant` | `--sample-bc-neighborhood` | GPL same name | Hamming-1 |
+| [x] | `multiplex-quant` | `--sample-bc-confidence` | GPL same name | 97.5% |
+| [x] | `multiplex-quant` | `--gpl-memory-limit` | GPL `--memory-limit` | 512 MiB |
+| [x] | `multiplex-quant` | `--gpl-tmp-dir` | GPL `--tmp-dir` | GPL output directory |
+| [x] | `atac process` | cell correction, neighborhood, confidence | ATAC GPL same names | Unique, Hamming-1, 90% |
+
+Unspecified values must be omitted from child commands so alevin-fry remains
+the source of truth for resolved protocol defaults. New controls are visible
+under advanced barcode-correction or resource help headings.
+
+## Compatibility and validation
+
+- [x] Keep `--sample-correction-mode` accepted but hidden and deprecated.
+- [x] Translate legacy `exact` to sample Exact correction.
+- [x] Translate legacy `1-edit` to sample Unique plus
+      substitution-or-shift-1 without forwarding the deprecated spelling.
+- [x] Keep sample-barcode orientation precedence: CLI override, chemistry
+      preset, then the alevin-fry default.
+- [x] Do not expose `--max-records`, `--collation-mode`, or the `edit-1`
+      neighbourhood spelling.
+- [x] Validate exact-fraction/decimal confidence and human-readable memory
+      values before mapping starts.
+- [x] Resolve the pipeline thread count once. Values below two warn, become
+      two, and continue; an available-parallelism result of one also warns and
+      attempts two.
+- [x] Update CLI snapshots and live quant, multiplex, and ATAC documentation.
+- [x] Test omitted defaults, every explicit forwarding route, legacy aliases,
+      stage-specific memory controls, and thread-floor edge cases.
+- [x] Require alevin-fry `>=0.18.0, <1.0.0`.
+
+Validation completed with 71 unit tests, CLI snapshots, CLI smoke/regression
+tests, strict rustdoc, strict clippy, formatting, `git diff --check`, and the
+Astro production build. Final end-to-end smoke runs remain release gates against
+the published alevin-fry 0.18.0 executable.

.github/workflows/test_simpleaf.yml

@@ -47,6 +47,12 @@ jobs:
       - name: Run cargo tests
         run: cargo test --release --verbose
 
+      - name: Strict API documentation
+        if: matrix.os == 'ubuntu-latest'
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo doc --no-deps
+
       - name: Install conda env
         uses: conda-incubator/setup-miniconda@v3
         with:
@@ -55,9 +61,35 @@ jobs:
           activate-environment: anaconda-client-env
           environment-file: simpleaf_conda_env.yml
 
+      # The bioconda package can lag a newly published alevin-fry release.
+      # Exercise simpleaf against the release artifact that satisfies the
+      # version contract instead of silently testing an older conda package.
+      - name: Install alevin-fry 0.18.0 release artifact
+        shell: bash -l {0}
+        run: |
+          case "$(uname -s)-$(uname -m)" in
+            Linux-x86_64) target=x86_64-unknown-linux-gnu ;;
+            Linux-aarch64) target=aarch64-unknown-linux-gnu ;;
+            Darwin-x86_64) target=x86_64-apple-darwin ;;
+            Darwin-arm64) target=aarch64-apple-darwin ;;
+            *) echo "unsupported CI platform: $(uname -s)-$(uname -m)" >&2; exit 1 ;;
+          esac
+
+          archive="alevin-fry-${target}.tar.xz"
+          install_dir="${RUNNER_TEMP}/alevin-fry-0.18.0"
+          curl --proto '=https' --tlsv1.2 -LsSf \
+            "https://github.com/COMBINE-lab/alevin-fry/releases/download/v0.18.0/${archive}" \
+            -o "${RUNNER_TEMP}/${archive}"
+          mkdir -p "${install_dir}"
+          tar -xJf "${RUNNER_TEMP}/${archive}" \
+            --strip-components=1 -C "${install_dir}"
+          "${install_dir}/alevin-fry" --version
+          echo "${install_dir}" >> "${GITHUB_PATH}"
+
       - name: Test simpleaf
         shell: bash -l {0}
         run: |
+          export PATH="${RUNNER_TEMP}/alevin-fry-0.18.0:${PATH}"
           cd scripts
           chmod +x test_simpleaf.sh
           ulimit -n 2048

CHANGELOG.md

@@ -4,6 +4,46 @@
 > (2024-07-01); releases 0.18.0 through 0.26.2 are not recorded here. See the
 > git history and the GitHub releases page for that range.
 
+## [0.28.0](https://github.com/COMBINE-lab/simpleaf/compare/v0.27.0...v0.28.0) (2026-08-15)
+
+### Features
+
+* Require alevin-fry 0.18.0 and expose its deterministic cell-barcode
+  correction policy, neighborhood, and confidence controls across ordinary
+  RNA, multiplex RNA, and ATAC processing.
+* Expose independent sample-barcode correction controls for multiplex assays,
+  including Exact, Unique, and Frequency policies.
+* Add stage-specific `--gpl-memory-limit`, `--gpl-tmp-dir`, and
+  `--collate-memory-limit` resource overrides. Omitted values remain omitted
+  from child commands so alevin-fry owns protocol defaults.
+* Validate confidence fractions/decimals and human-readable memory sizes before
+  mapping begins.
+
+### Compatibility and execution
+
+* Keep the deprecated `--sample-correction-mode` accepted but hidden. Its
+  `exact` and `1-edit` values translate to the corresponding new alevin-fry
+  arguments; deprecated child spellings are never emitted.
+* Use two threads as the practical minimum. Requests of zero or one warn, are
+  raised to two, and continue; a host report of one available thread also warns
+  and still attempts two.
+* Resolve the effective thread count once per pipeline and pass it consistently
+  to mapping, permit-list generation, collation or ATAC sorting, and
+  quantification.
+* Run MACS peak calling from `atac process` only when `--call-peaks` is set;
+  ordinary ATAC processing no longer fails after producing its BED merely
+  because MACS is not installed.
+* Retire the obsolete `release.sh`; `bump_and_publish.sh` is now the sole
+  documented release entry point.
+
+### Documentation and testing
+
+* Document barcode correction for standard RNA, multiplex/Flex, and ATAC, and
+  add strict rustdoc to CI.
+* Add typed command-building helpers and coverage for omitted defaults,
+  explicit forwarding, legacy translation, stage-specific resources, and the
+  thread floor.
+
 ## [0.27.0](https://github.com/COMBINE-lab/simpleaf/compare/v0.26.2...v0.27.0)
 
 ### Breaking changes

CONTRIBUTING.md

@@ -10,3 +10,17 @@ on _dev_.  Before you make a PR, please check that:
  * you've run `cargo fmt` on the relevant code.
  * any non-obvious code is documented (we don't yet have formal documentation guidelines, so use common sense)
  * you've run `cargo clippy` on the relevant code and any issues are either resolved or the PR describes why they were ignored.
+
+## Cutting a release
+
+`bump_and_publish.sh` is the sole supported release entry point. It validates
+the requested semantic version and clean upstream state, checks the crate,
+verifies its crates.io package when `--publish` is selected, updates both the
+manifest and lockfile, commits, tags, pushes, and optionally publishes. Preview
+the release without changing repository or registry state with:
+
+```sh
+./bump_and_publish.sh 0.28.0 --publish --dry-run
+```
+
+Do not create a release commit or tag with a separate version-bump script.

docs-site/astro.config.mjs

@@ -37,6 +37,7 @@ export default defineConfig({
             { label: "index", slug: "index-command" },
             { label: "quant", slug: "quant-command" },
             { label: "flex-quant", slug: "flex-quant-command" },
+            { label: "atac process", slug: "atac-process-command" },
             { label: "chemistry", slug: "chemistry-command" },
             { label: "inspect", slug: "inspect-command" },
           ],

docs-site/src/content/docs/atac-process-command.md

@@ -0,0 +1,62 @@
+---
+title: "atac process command"
+description: "Map and process single-cell ATAC-seq data, including deterministic barcode correction."
+---
+
+`simpleaf atac process` maps a single-cell ATAC-seq library, generates a
+corrected cell permit list, and asks alevin-fry to sort and deduplicate the
+result into BED records. It can optionally run MACS3 peak calling.
+
+The command requires a piscem ATAC index, barcode reads, an ATAC chemistry, an
+output directory, and either paired-end `--reads1`/`--reads2` inputs or
+single-end `--reads` input. The supported chemistry names are `10x-v1`,
+`10x-v2`, and `10x-multi`.
+
+## Barcode correction
+
+ATAC uses the same deterministic correction controls as RNA:
+
+- `--cell-bc-correction {unique,frequency}` selects how collisions between
+  possible corrected targets are handled. The inherited default is `unique`.
+- `--cell-bc-neighborhood {hamming-1,substitution-or-shift-1}` selects the
+  one-error candidate neighborhood. The inherited ATAC default is `hamming-1`.
+- `--cell-bc-confidence <CONFIDENCE>` overrides the Frequency acceptance
+  threshold. The inherited ATAC default is `0.90`; decimal and exact-fraction
+  forms are accepted.
+
+These options are validated before mapping and then forwarded only to the ATAC
+permit-list stage. If they are omitted, simpleaf emits no corresponding flags,
+so the protocol defaults remain owned by alevin-fry. The compiled correction
+plan produced there is then consumed by ATAC sorting; sorting does not choose a
+different correction.
+
+```sh
+simpleaf atac process \
+  --index /path/to/atac-index \
+  --reads1 sample_R1.fastq.gz \
+  --reads2 sample_R2.fastq.gz \
+  --barcode-reads sample_R3.fastq.gz \
+  --chemistry 10x-v2 \
+  --cell-bc-correction frequency \
+  --cell-bc-confidence 9/10 \
+  --output atac_out
+```
+
+## Threads
+
+`--threads` is resolved once and passed consistently to mapping, permit-list
+generation, and ATAC sorting. Values below two are not rejected: simpleaf logs
+a prominent warning, raises the effective value to two, and continues. If the
+host reports only one available execution slot, simpleaf warns and still
+attempts two threads.
+
+Mapping's gzip decoder shares this thread budget. See [Threads and
+decompression](/simpleaf/threads-and-decompression/) for `--decoder` and
+`--thread-policy`.
+
+## Outputs
+
+Mapping output is written beneath `af_map/`; corrected and sorted ATAC output is
+written beneath `af_process/`. The process log records the exact child commands
+and stage timings. `--compress` requests compressed BED output and
+`--call-peaks` enables the optional MACS3 stage.