archivefs 0.2.0__tar.gz

archivefs-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from tags; it needs full history.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          # Install everything except the [chiro] extra. chirograph is a private,
+          # pre-PyPI dependency, so CI cannot resolve chirograph>=0.1 (and cannot
+          # clone the private repo without credentials). Install the rest explicitly.
+          pip install -e ".[dbgap,dvc]" pytest pytest-cov responses ruff
+          # Then pull chirograph best-effort: the chiro:// and update tests
+          # importorskip it and skip cleanly when it is absent. Once chirograph is
+          # published this install succeeds and those tests run automatically — no
+          # further CI change needed.
+          pip install chirograph || echo "chirograph unavailable (private/pre-PyPI); chiro tests will skip"
+      - name: Lint
+        run: ruff check .
+      - name: Test (offline — skip network/credentialed archive tests)
+        run: pytest -m "not network and not credentials"

archivefs-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+# Publish archivefs to PyPI via trusted publishing (OIDC — no API token).
+#
+# ARMED: a published GitHub Release triggers a build + upload via trusted publishing.
+# The upload requires the PyPI side configured first (else the publish job fails at
+# the OIDC exchange with `invalid-publisher`): a pending publisher
+# (owner swarbricklab / repo archivefs / workflow publish.yml / environment pypi)
+# and a `pypi` GitHub environment. See docs/releasing.md for the full walkthrough.
+#
+# The version comes from the git tag via setuptools-scm, so the build must run from
+# the tagged commit. `fetch-depth: 0` lets setuptools-scm see tags, and the build
+# checkout pins `ref` to the release tag so the version is derived from exactly that
+# tag (not a post-release dev version). `workflow_dispatch` stays for manual re-runs.
+
+name: publish
+
+on:
+  workflow_dispatch: {}
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Build the exact tag on a release (setuptools-scm reads it); fall back to
+          # the dispatched ref for a manual workflow_dispatch run.
+          ref: ${{ github.event.release.tag_name || github.ref }}
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --outdir dist .
+      - name: Check the distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

archivefs-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+src/archivefs/_version.py
+
+# local, never committed: credentials and scratch download dirs
+.dvc/config.local
+egacheck/
+*.credentials.json
+# the per-machine config layer. `.archivefs.json` IS committed — that is the whole
+# distinction (docs/configuration.md); this one names paths on one machine.
+.archivefs.local.json

archivefs-0.2.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to **archivefs** are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
+follow [Semantic Versioning](https://semver.org/). The version is derived from git
+tags by `setuptools-scm`.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-10-26
+
+Adds four new access paths (`mendeley://`, `cbioportal://`, `chiro://`, and Chirograph
+schema 2.0 containers), a batch of CLI verbs, and first-class packaging for PyPI /
+conda-forge. Backward-compatible: every `0.1.0` URL and `.dvc` import keeps working.
+
+### Added
+
+- **`mendeley://`** — Mendeley Data deposits by DOI or dataset id, versioned and
+  folder-aware (anonymous; **experimental**, sha256). See `docs/decisions.md` D44.
+- **`cbioportal://`** — cBioPortal studies via the `cBioPortal/datahub` GitHub repo and
+  git-lfs, with version pinning by git ref (`cbioportal://<study>@<ref>`) and a
+  download-free sha256 for the LFS data files (**experimental**). See D44.
+- **`chiro://`** — a committed `.chiro` manifest as a portable, self-verifying pin that
+  routes to the archive its concept names; digest-addressed manifest store.
+- Chirograph **schema 2.0** adoption: `containers` + member `crc32` for ZIP deposits,
+  with a download-free `archivefs confirm`.
+- New CLI verbs: `manifest` (incl. `--from-dvc`, fully offline), `update`, `confirm`,
+  `versions`, `ping`, `dvc-meta`; subtree and ZIP-subtree (relocated) pins.
+- Per-file `concept` CURIEs and version-aware DVC pull-through (`push: false`), so a
+  reviewer can `dvc pull` straight from the archive with no DVC remote.
+- Packaging: `LICENSE` (Apache-2.0), `NOTICE`, `py.typed`, a CHANGELOG, GitHub Actions
+  CI, and a dormant trusted-publishing release workflow.
+
+### Fixed
+
+- Thread-safe concurrent ZIP member reads under DVC's default `--jobs` (#40).
+- A `chiro://` pin fetches the pinned *version*, not the concept (found live).
+- Python 3.9 compatibility: a runtime `int | str` union in the BIA backend's
+  `isinstance` raised `TypeError` on 3.9 (the first CI run across the matrix caught it).
+
+## [0.1.0] — 2026-08-19
+
+First tagged release: the shared read-only base and the initial backends —
+`ega://`, `zenodo://` (with ZIP transparency), `geo://`, `bia://` — addressable by
+accession/DOI and consumable through fsspec and DVC's `import-url`. `dbgap://` is
+registered but deferred.
+
+[Unreleased]: https://github.com/swarbricklab/archivefs/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/swarbricklab/archivefs/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/swarbricklab/archivefs/releases/tag/v0.1.0

archivefs-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

archivefs-0.2.0/NOTICE

@@ -0,0 +1,4 @@
+archivefs
+Copyright 2026 Swarbrick Lab, Garvan Institute of Medical Research
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

archivefs-0.2.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: archivefs
+Version: 0.2.0
+Summary: Read-only fsspec filesystems for scientific data archives (EGA, Zenodo, Mendeley Data, cBioPortal, GEO, BioImage Archive).
+Author: Swarbrick Lab
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/swarbricklab/archivefs
+Project-URL: Source, https://github.com/swarbricklab/archivefs
+Project-URL: Issues, https://github.com/swarbricklab/archivefs/issues
+Project-URL: Changelog, https://github.com/swarbricklab/archivefs/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/swarbricklab/archivefs/tree/main/docs
+Keywords: fsspec,dvc,reproducibility,ega,zenodo,mendeley,cbioportal,geo,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Bio-Informatics
+Classifier: Topic :: System :: Filesystems
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fsspec>=2023.9.0
+Requires-Dist: requests>=2.28
+Provides-Extra: dbgap
+Provides-Extra: chiro
+Requires-Dist: chirograph>=0.1; extra == "chiro"
+Provides-Extra: dvc
+Requires-Dist: dvc>=3.0; extra == "dvc"
+Provides-Extra: all
+Requires-Dist: archivefs[chiro,dbgap,dvc]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: archivefs[all]; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# archivefs
+
+**Read-only [fsspec](https://filesystem-spec.readthedocs.io/) filesystems for
+scientific data archives.**
+
+`archivefs` lets you address data in scientific repositories by accession/DOI and
+pull it through the fsspec ecosystem — including [DVC](https://dvc.org/) via
+`dvc import-url`. A reviewer, collaborator, or student can then start from the *same
+raw data* you used and reproduce your results, with checksum certainty and clear,
+version-controlled provenance.
+
+```
+ega://EGAD00001006673                  # dataset → directory
+ega://EGAD00001006673/EGAF00004908765  # single file
+zenodo://1486184/data.zip              # record id …
+zenodo://10.5281/zenodo.1486184        # … or DOI (concept DOI → latest version)
+mendeley://10.17632/yzxtxn4nmd/4       # Mendeley Data (anonymous; EXPERIMENTAL, sha256)
+geo://GSE176078                        # supplementary / processed files
+bia://S-BIAD599                        # BioImage Archive: imaging depositions
+dbgap://<phs_id>/<SRR_accession>       # deferred, registered, refuses clearly
+cbioportal://brca_metabric             # cBioPortal via GitHub+git-lfs (EXPERIMENTAL, sha256)
+cbioportal://brca_metabric@v1.0.0      # … pinned to a release tag or commit SHA
+```
+
+## What it does today
+
+```console
+$ archivefs ls -l zenodo://1486184        # -R to recurse
+       853 B  49f6a914ea33912471512ac9228c6923  1486184/github-mark.zip
+
+$ dvc import-url --no-download zenodo://1486184/github-mark.zip logo.zip
+$ cat logo.zip.dvc
+deps:
+- md5: 49f6a914ea33912471512ac9228c6923    # download-free, from record metadata
+  size: 853
+  path: zenodo://1486184/github-mark.zip   # an accession — never a secret
+outs:
+- path: logo.zip
+
+$ dvc pull logo.zip.dvc                    # bytes on demand, verified by DVC
+```
+
+That order matters. `--no-download` then `dvc pull` gives you the data locally *and*
+leaves the committed `.dvc` in the one shape a reviewer can pull from the archive
+without you hosting a copy — which is the point of the exercise.
+[`docs/decisions.md`](docs/decisions.md) D17.
+
+The same works for `ega://` with credentials resolved from the environment at pull
+time, and for `geo://` and `bia://` anonymously. For imaging, BIA's own OME-Zarr
+conversions carry real MD5s, so that tier is download-free too:
+
+```console
+$ dvc import-url --no-download --fs-config view=derived -- \
+    bia://S-BIAD599/<image-uuid>/<image>-thumbnail-128-128.png t.png
+                                           # md5 recorded without fetching bytes
+```
+
+Where an archive publishes *no* checksum (BIA's submitted files, bare GEO),
+`--no-download` still records a correct md5 — but DVC computes it by streaming the
+file, so it is not free. [`docs/decisions.md`](docs/decisions.md) D14.
+
+## Why
+
+- **Reproducible provenance in one step.** `dvc import-url` someone's archived data
+  into your project and get download + a pinned, checksummed reference together.
+- **Checksum certainty.** Once data is in the DVC ecosystem you get integrity
+  guarantees and version control over inputs.
+- **Look before you leap.** `dvc list-url` / `archivefs ls` show what is in a record
+  before you download it.
+- **Works on anyone's deposits**, whether or not our tooling was used to create them.
+
+## Install
+
+```
+pip install archivefs           # Zenodo, GEO, EGA, BIA, Mendeley, cBioPortal
+pip install archivefs[chiro]    # + read .chiro.json manifests
+pip install archivefs[dvc]      # + the DVC adaptor
+```
+
+EGA needs no extra: the backend speaks EGA's REST API directly. (`pyega3` pins
+`requests==2.26.0`, which would hold the whole environment hostage — see
+[`docs/decisions.md`](docs/decisions.md) D2.)
+
+### Using it with DVC
+
+DVC does **not** discover fsspec filesystems from entry points, so one extra step is
+needed once per environment:
+
+```console
+$ archivefs dvc enable     # writes a .pth that registers our protocols with DVC
+$ archivefs dvc status     # check it works
+```
+
+Why this is necessary, and what was tried instead, is
+[`docs/decisions.md`](docs/decisions.md) D4. `archivefs dvc disable` undoes it;
+`ARCHIVEFS_NO_DVC_HOOK=1` disables it for one command.
+
+## Design
+
+A single package, a shared base, and thin per-backend byte-fetchers:
+
+- **`archivefs.base`** — path grammar, retry/error contract, length-checked and
+  alignment-aware ranged reads, download-free `info()`, read-only enforcement.
+- **`archivefs.credentials`** — one chain for every archive: environment → a
+  private on-disk file, and nothing else. Passing a credential as an option is
+  refused, and DVC's own validator rejects the keys, so "no secret in the committed
+  artifact" is a config parse error rather than a promise.
+- **`archivefs.chiro`** — `.chiro`-first resolution: when a deposit carries a
+  manifest, the manifest *is* the listing and the checksums.
+- **`archivefs.zipsafe`** — zip-slip, symlink, zip-bomb and corruption checks,
+  applied at listing time as well as on extraction.
+- **`archivefs.backends.*`** — per-archive: how to list this repository, and where its
+  bytes live. That is all that is left.
+
+Credentials are always resolved at **pull time** from the local environment and
+**never** written into the committed `.dvc` file.
+
+## Status
+
+All working backends run against the live archives, with the plan's blocking question
+resolved; `mendeley://` and `cbioportal://` are new and marked **experimental**.
+
+| backend | state | download-free checksum | notes |
+|---|---|---|---|
+| `zenodo://` | working | ✅ MD5 from record metadata | DOI + concept-DOI addressing; opt-in ZIP transparency |
+| `ega://` | working | ✅ MD5 of the *decrypted* bytes (verified) | OAuth2 + refresh-on-401; 16-byte range alignment |
+| `geo://` | working | ⚠️ none published — a `.chiro` sidecar fixes it | index-based listing; SRA seam drawn, not built |
+| `bia://` | working | ⚠️ none for submitted files · ✅ MD5 for the OME-Zarr tier | two views; the imaging half of a split deposit |
+| `mendeley://` | working · experimental | ✅ sha256 (published) | DOI/id, versioned, folder-aware; anonymous frontend API |
+| `cbioportal://` | working · experimental | ✅ sha256 for git-lfs data files · ⚠️ derived for small metadata files | `cBioPortal/datahub` GitHub + git-lfs; version-pin by git ref |
+| `dbgap://` | deferred | — | registered so the error explains itself |
+
+Verified end to end against the live archives: `dvc list-url`, `dvc import-url
+--no-download` (single file and directory), `dvc update`, `dvc pull`, and ZIP
+transparency via `--fs-config` — including a controlled-access EGA pull whose `.dvc`
+file contains neither username nor password, which DVC would now refuse to write in
+any case. Plain `fsspec.open()` works with no adaptor at all, so pandas/Dask/Intake
+reach the same data by the same path.
+
+Live tests are opt-in (`ARCHIVEFS_TEST_{EGA,ZENODO,GEO,DVC}=1`); the default `pytest`
+run is entirely offline.
+
+**Read next:**
+
+- **All the documentation, indexed:** [`docs/README.md`](docs/README.md) — a page per
+  subcommand, the storage-option tables, and the guides below.
+- **Importing from BIA, step by step:**
+  [`docs/importing-from-bia.md`](docs/importing-from-bia.md) — a collaborator-facing
+  how-to, from `conda env update` to a committed `.dvc` file.
+- **Using any archive with DVC:** [`docs/using-with-dvc.md`](docs/using-with-dvc.md) ·
+  **credentials:** [`docs/credentials.md`](docs/credentials.md)
+  **reviewer access:** [`docs/reviewer-access.md`](docs/reviewer-access.md)
+- **Decisions and deviations:** [`docs/decisions.md`](docs/decisions.md) — thirty-three
+  entries, including the resolved EGA checksum question, several undocumented archive
+  behaviours worth knowing about, the credential routes closed off in D16, why a
+  reviewer can only pull from the archive for a *partial* import (D17), and the silent
+  bugs an adversarial review of the finished code turned up.
+- **Ideas and extensions:** [`docs/ideas.md`](docs/ideas.md)
+- **Architecture:** [`docs/design.md`](docs/design.md) · **checklist:**
+  [`docs/plan.md`](docs/plan.md)
+
+## Relationship to Chirograph
+
+[**Chirograph**](https://github.com/swarbricklab/chirograph) is a separate project
+defining the `.chiro.json` manifest format (portable, content-addressed checksums +
+provenance). `archivefs` **optionally** reads Chirograph manifests to gain
+download-free checksums, drift detection, and friendly workspace layout — but works
+**without** them (native listing, native checksums). Chirograph is the manifest
+format; `archivefs` is the data-access layer. Neither depends on the other to be
+useful.
+
+## Development
+
+```console
+$ conda env update -n archivefs -f environment.yaml
+$ conda activate archivefs
+$ pytest                       # offline
+$ pytest -m network            # add ARCHIVEFS_TEST_*=1 to actually run these
+$ ruff check src tests scripts
+```