datalab-capsule 0.1.0__tar.gz

datalab_capsule-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to DataLab-Capsule are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The capsule format itself is versioned by its profile (<https://datalab-platform.com/capsule/0.1>).
+
+## [0.1.0] - 2026-10-19
+
+First public release, shared by DataLab Desktop and DataLab-Web.
+
+### Added
+
+- **Workspace provenance model:** a neutral record of processing (operation calls with their parameters, input and output states, activities, execution environments) stored in DataLab workspaces (`/DataLab_Provenance`) and read and written with h5py alone. Signal and image states are identified by fingerprints of their data, coordinates or calibration and units, and by their regions of interest; analysis results by the digest of their stored value. A state whose saved data no longer match is reported as altered.
+- **Replay preparation and verification reports:** an edition can recompute a recorded activity and compare it with the stored result (`exact`, `within_tolerance` under the tolerance declared for the operation, `different`, or `not_verified` with its reason); only operations with a qualified contract are replayed, and nothing named in a file is ever executed. An input whose data are unchanged but whose region of interest changed since the activity (for example regions added by a detection) is replayed on a copy carrying the recorded region of interest, never modified itself. A recorded result whose data or region of interest changed since the activity is reported as altered and never used as reference.
+- **Provenance of a result:** an edition can describe, for one signal or image, the recorded activity that produced its state (parameters, ordered inputs and their ancestors, expanded on demand), what is still available, the analyses recorded on it and whether the local library knows and qualifies the operation, without computing, and check the data of the object and of the direct inputs against the recorded states. Processing restores the call that produced the latest recorded state of an object, every input included; knowing an operation and qualifying its verification are kept apart. When a workspace file is appended to the current one, its provenance is not imported, and objects holding an identifier already known to the current ledger never inherit what was recorded for another object.
+- **Legacy workspaces:** processing records stored by earlier DataLab versions become legacy activities that keep the record as stored, invent nothing and are never replayed.
+- **Capsules (`.dlcapsule`):** a ZIP archive with the workspace and an RO-Crate 1.3 manifest (Process Run Crate 0.6 and the DataLab capsule profile 0.1). The safe reader refuses path traversal, links, duplicates, encrypted, compressed or damaged entries and oversized archives, and never accesses the network. A capsule may reference its workspace by an address instead of including it; the bytes supplied must match the manifest.
+- **Revisions and reviews:** a capsule may name its parent revision; reviews are separate documents about one revision, with their own fingerprint. The capsule a workspace was opened from is saved with the workspace file, so that a revision exported after the workspace was saved and opened again still names its parent.
+- **Light attachments:** up to 8 files of 16 MiB (protocol, notes, small tables) declared in the manifest with their size and SHA-256; checked, returned as data, never opened or executed.
+- **Comparison (`diff`) and verification (`verify`):** changes between two revisions sorted into scientific, presentation, storage, environment and attachment changes, with a scientific conclusion that never claims equality beyond what the manifests record; verification of the archive, the workspace, the stored states and supplied reports and reviews, without computation.
+- **Command line `workspace-capsule`:** `validate`, `inspect`, `diff`, `verify`, `attachment`, `workspace`, `create`, `review`, and `registry list | publish | fetch`.
+- **Optional registry (`registry` extra):** publishes and serves manifests, their attachments and reviews (never workspaces), with checks on every document, an OpenAPI description, open reading and token-protected publishing (`workspace-capsule-registry`). Its client reads each response up to a size limit and checks everything it fetches; it also gives the registry status and each publishing step apart (manifest, attachment, review), and downloads an attachment checked against its manifest.
+- **Capsule interfaces (`exchange`):** inspection, opening, attachment download, registry checks, comparison and reviews as offered by the capsule dialogs of DataLab Desktop and DataLab-Web, so that both editions give the same answers. Supplied reports and reviews are checked apart from the integrity of the capsule.
+- Runs on CPython 3.9 to 3.14 and in Pyodide (registry excepted).
+- **Measured costs:** benchmarks of fingerprints and capsules (`benchmarks/`, in CPython and in Pyodide) with one command line and one report format shared with the benchmarks of DataLab Desktop and DataLab-Web; method, results and recommended sizes in [doc/performance.md](doc/performance.md).
+- **Release checks:** the distributions are checked to carry every module (including `exchange`) and, on release tags, schemas and context with the SHA-256 published by the profile page (`scripts/check_profile.py`, also usable offline against a checkout of the profile).

datalab_capsule-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DataLab Platform
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

datalab_capsule-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include CHANGELOG.md README.md LICENSE
+recursive-include doc *.md
+recursive-include examples *.py
+recursive-include benchmarks *.py
+recursive-include scripts *.py
+graft tests
+prune tests/pyodide/node_modules
+exclude tests/pyodide/package-lock.json
+global-exclude __pycache__ *.py[cod]

datalab_capsule-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: datalab-capsule
+Version: 0.1.0
+Summary: Exchange and verify scientific workspace provenance as open RO-Crate capsules (library and CLI, no DataLab required)
+Author: DataLab Platform Developers
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/DataLab-Platform/DataLab-Capsule
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <4,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.17
+Provides-Extra: hdf5
+Requires-Dist: NumPy>=1.22; extra == "hdf5"
+Requires-Dist: h5py>=3.6; extra == "hdf5"
+Provides-Extra: registry
+Requires-Dist: fastapi>=0.110; extra == "registry"
+Requires-Dist: uvicorn>=0.27; extra == "registry"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: NumPy>=1.22; extra == "test"
+Requires-Dist: h5py>=3.6; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# DataLab-Capsule
+
+Exchange and verify scientific workspace provenance as open RO-Crate capsules (library and CLI, no DataLab required).
+
+Status: experimental. Version 0.1.0 is the first public release, on PyPI as `datalab-capsule`; it implements the experimental [DataLab capsule profile 0.1](https://datalab-platform.com/capsule/0.1), which may still change.
+
+## Scope
+
+- Neutral provenance model shared by DataLab Desktop and DataLab-Web: operation calls, states, activities, environments (JSON Schemas under `src/datalab_capsule/schemas`).
+- Shared replay preparation (eligibility codes), comparison rules and verification reports. A report states one of four verdicts: `exact` (same values), `within_tolerance` (values within the tolerance declared and justified for that operation), `different`, or `not_verified` (with the reason: opaque operation, missing input, unavailable reference...). A rule is never widened to hide a difference; see [rules](doc/rules.md).
+- HDF5 provenance block (`/DataLab_Provenance`) read and written with h5py alone; links and virtual datasets are refused.
+- Integrity primitives: RFC 8785 canonical JSON, SHA-256 digests, the `datalab-signal-v1` and `datalab-image-v1` state fingerprints (data, coordinates or calibration, units). A state also records the digest of its ROI definition, and an analysis result the digest of its stored value: a saved object whose data, calibration, units or ROI differ from its state is `altered`, and a result replaced by a later analysis is never attributed to the earlier one. Fingerprints are streamed into SHA-256 without copying the arrays.
+- Legacy workspaces: processing records stored by DataLab in object metadata (`__processing_parameters`, `__analysis_parameters`) of objects unknown to the ledger become `legacy_metadata` activities. They keep the record as stored and invent nothing: inputs are bound to the recorded objects (state unknown), the call is opaque without parameters, environment, edition and times are null, and import issues (missing ancestry, unavailable inputs, unsupported operations, version warnings...) are listed. They claim no result: the state of the holding object observed when the workspace was opened is named separately (`observed_state_id`), as an observed state that no activity produced. They are never replayed.
+- Capsules (`.dlcapsule`): a ZIP archive holding `workspace.h5` and an RO-Crate 1.3 manifest (`ro-crate-metadata.json`) that conforms to Process Run Crate 0.6 and to the experimental [DataLab capsule profile 0.1](https://datalab-platform.com/capsule/0.1) (terms: `https://datalab-platform.com/capsule/terms#`). The reader refuses unsafe archives (path traversal, duplicates, links, encryption, compressed entries, size limits) and never accesses the network. It holds the whole archive in memory: it checks the archive size before reading it, then the size of each entry. Each edition passes its own `SizePolicy`; the default one (4 GiB workspace) is an accepted upper bound, not a tested capacity.
+- Revisions and reviews: a capsule may name one parent revision by its manifest fingerprint (`dlc:revisionOf`), which is part of its own fingerprint. A review is a separate JSON document (`review-1` schema) that targets one revision by fingerprint, states who reviewed it and what was found (`endorsed`, `disputed` or `comment`), may cite verification reports by fingerprint, and has its own fingerprint. A review never modifies the capsule.
+- Referenced workspaces: a capsule may reference its workspace by an absolute IRI instead of including `workspace.h5` (`dlc:referenced`). The library never fetches it: the caller passes an explicit resolver, and the bytes obtained must match the SHA-256 and size recorded in the manifest.
+- Light attachments: up to 8 files of at most 16 MiB each, chosen by the author (protocol, notes, small tables...), stored under `attachments/` and declared in the manifest (`dlc:attachment`) with their media type, size and SHA-256. They are part of the manifest fingerprint. The reader refuses undeclared, missing or altered attachments. They are returned as bytes, written to disk only on explicit request, and never opened or executed.
+- Semantic diff (`diff_manifests`): changes between two capsules are sorted into scientific (activities, parameters, states, fingerprints, ROI), presentation (name, description, licence, date), storage (workspace file SHA-256 and size, included or referenced, locators: different bytes do not show a scientific change), environment (environments, packages, the environment of each activity) and attachments (added, removed or changed; their content is not interpreted, since a protocol or a calibration certificate may matter scientifically). `scientific_conclusion` says what can be concluded: `differences`, `none` (no scientific change, the same workspace file and the same attachment contents) or `none_detected` (nothing differs in the recorded activities and states, but the workspace files or the attachment contents differ, so equality is not established).
+- Verification without computation (`verify_capsule`): the archive and manifest, the workspace integrity, the match between the manifest and the workspace ledger, the fingerprints and ROI of every stored state (with h5py), and supplied verification reports and reviews. Recomputing an activity is the replay of an edition, never this package's job.
+- Pure Python for CPython 3.9+ and Pyodide (Python 3.12). The core only needs the standard library and `jsonschema`; HDF5 helpers use NumPy and h5py.
+- The package never imports DataLab, Sigima, SigimaX or Qt, and never executes code named in a file.
+
+## Installation
+
+Users of DataLab Desktop and DataLab-Web need nothing more than their edition: both handle capsules from _File > Workspace capsule…_ (export, inspection, local replay, revisions, registry) and use the same functions of this package (`datalab_capsule.exchange`). The [two-operator scenario](doc/scenario.md) follows that path.
+
+The package itself is installed in one of three ways, which must not be mixed up:
+
+- **Released version**, for users of the command line and third-party readers: `pip install datalab-capsule`, with the `hdf5` extra to create capsules or check stored states and the `registry` extra to run a registry.
+- **Candidate qualification**, before a release: a wheel and an sdist built from the commit to qualify (`python -m build`), checked with `scripts/check_dist.py` and `scripts/check_profile.py`, then installed in a clean environment, outside the checkout.
+- **Development**: editable install of this checkout, used by the sibling checkouts of DataLab and DataLab-Web (see [developer notes](doc/development.md)).
+
+## Command line
+
+Validating, inspecting and comparing capsules needs neither NumPy nor h5py:
+
+```powershell
+workspace-capsule validate workspace.dlcapsule
+workspace-capsule inspect workspace.dlcapsule [--json]
+workspace-capsule diff old.dlcapsule new.dlcapsule [--json]
+```
+
+`diff` exits with 0 when the capsules are the same revision (same manifest fingerprint) and 1 when they differ.
+
+Writing one attachment to a new file (an existing file is never overwritten, and the attachment is never opened):
+
+```powershell
+workspace-capsule attachment workspace.dlcapsule protocol.txt protocol.txt
+```
+
+Commands for an operator working with DataLab Desktop (`create` needs the `hdf5` extra): create a capsule from a saved workspace (optionally a revision of another capsule, with light attachments), write a review, extract the checked workspace to open it in DataLab, and exchange through a registry (only these commands use the network; everything fetched is checked):
+
+```powershell
+workspace-capsule create workspace.h5 workspace.dlcapsule [--name NAME] [--description TEXT] [--revision-of PARENT.dlcapsule] [--workspace-ref IRI] [--attach FILE]...
+workspace-capsule review workspace.dlcapsule review.json --reviewer NAME --statement TEXT [--verdict endorsed|disputed|comment] [--report report.json]...
+workspace-capsule workspace workspace.dlcapsule workspace.h5
+workspace-capsule registry list URL [--json]
+workspace-capsule registry publish URL workspace.dlcapsule [--review review.json]... --token-env VARIABLE
+workspace-capsule registry fetch URL FINGERPRINT FOLDER
+```
+
+`diff` also compares manifest files (`.json`) fetched from a registry. `registry fetch` does not save an attachment whose name Windows reserves for a device (`NUL`, `CON`...). The [two-operator scenario](doc/scenario.md) puts these commands together with DataLab Desktop and DataLab-Web.
+
+Verifying a capsule reads the stored states with h5py; without h5py, it checks only the workspace SHA-256 and size and says so (`integrity_only`). A referenced workspace is checked only when its file is given; reports and reviews are optional:
+
+```powershell
+workspace-capsule verify workspace.dlcapsule [--workspace workspace.h5] [--report report.json]... [--review review.json]... [--json]
+```
+
+`verify` exits with 0 when no problem is found and 1 otherwise. It never computes or fetches anything.
+
+Creating a capsule from a workspace saved by DataLab (needs the `hdf5` extra):
+
+```powershell
+python examples/workspace_to_capsule.py workspace.h5 workspace.dlcapsule
+```
+
+Reading and checking a capsule without this package, with `json`, `zipfile`, `hashlib` and h5py only (a third-party example that follows the published profile):
+
+```powershell
+python examples/third_party_reader.py workspace.dlcapsule
+```
+
+## Registry (optional)
+
+A small registry publishes and serves capsule manifests, the attachments they declare and their reviews, so that revisions can be found, compared and discussed. It never stores workspaces: a manifest names its workspace by SHA-256 and size (and by address when it is referenced). Everything keeps working without a registry. Manifests are validated and identified by their fingerprint, attachments must match their declared size and SHA-256, reviews must target a published revision. Metadata is kept in SQLite and documents in files.
+
+```powershell
+pip install "datalab-capsule[registry]"
+$env:REGISTRY_TOKEN = "<secret>"
+workspace-capsule-registry registry-data --token-env REGISTRY_TOKEN --origin https://web.example
+```
+
+Reading is open; publishing needs `Authorization: Bearer <token>` when a token is set (without one, publishing is open: local use only). The API is described at `/docs` and `/openapi.json`; see [API](doc/api.md#registry).
+
+## Documentation
+
+- [Two-operator scenario](doc/scenario.md): DataLab Desktop and DataLab-Web, without server and with a registry
+- [Interoperability report](doc/interoperability.md): what the editions exchange, check and replay, findings and limits
+- [Performance and capacity](doc/performance.md): how costs are measured, results and recommended sizes
+- [Developer notes](doc/development.md) and [deployment notes](doc/deployment.md) (registry, profile pages)
+- [Identity, compatibility and restoration rules](doc/rules.md)
+- [API](doc/api.md)
+- [Security analysis](doc/security.md)
+- [Decision 0001: foundations of the processing chain](doc/decisions/0001-processing-chain-foundations.md)
+- [Fixture corpus](tests/fixtures/corpus/README.md), valid and invalid, with the expected command-line results
+- Profile and terms: <https://datalab-platform.com/capsule/0.1>
+
+## Development
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[test,dev]"
+.\.venv\Scripts\python.exe -m pytest
+```
+
+Golden vectors and the test suite in Pyodide (Node 22):
+
+```powershell
+.\.venv\Scripts\python.exe -m pip wheel . --no-deps -w dist
+cd tests\pyodide
+npm install
+node run_pyodide.mjs (Resolve-Path ..\..\dist\datalab_capsule-*.whl)
+```
+
+Cost of fingerprints and of capsules (time and memory), in CPython and in Pyodide (see [performance](doc/performance.md)):
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -r benchmarks\requirements.txt
+.\.venv\Scripts\python.exe benchmarks\fingerprint_cost.py --profile quick --output build\bench\fingerprints.json
+.\.venv\Scripts\python.exe benchmarks\capsule_cost.py --profile representative --output build\bench\capsules.json
+cd tests\pyodide
+node run_benchmark.mjs (Resolve-Path ..\..\dist\datalab_capsule-*.whl) capsule_cost.py --profile quick --output ..\..\build\bench\capsules-pyodide.json
+```
+
+## License
+
+BSD 3-Clause, see [LICENSE](LICENSE). The embedded RO-Crate 1.3 JSON-LD context (`src/datalab_capsule/contexts/ro-crate-1.3.jsonld`) is distributed by its authors under CC0 1.0.

datalab_capsule-0.1.0/README.md

@@ -0,0 +1,138 @@
+# DataLab-Capsule
+
+Exchange and verify scientific workspace provenance as open RO-Crate capsules (library and CLI, no DataLab required).
+
+Status: experimental. Version 0.1.0 is the first public release, on PyPI as `datalab-capsule`; it implements the experimental [DataLab capsule profile 0.1](https://datalab-platform.com/capsule/0.1), which may still change.
+
+## Scope
+
+- Neutral provenance model shared by DataLab Desktop and DataLab-Web: operation calls, states, activities, environments (JSON Schemas under `src/datalab_capsule/schemas`).
+- Shared replay preparation (eligibility codes), comparison rules and verification reports. A report states one of four verdicts: `exact` (same values), `within_tolerance` (values within the tolerance declared and justified for that operation), `different`, or `not_verified` (with the reason: opaque operation, missing input, unavailable reference...). A rule is never widened to hide a difference; see [rules](doc/rules.md).
+- HDF5 provenance block (`/DataLab_Provenance`) read and written with h5py alone; links and virtual datasets are refused.
+- Integrity primitives: RFC 8785 canonical JSON, SHA-256 digests, the `datalab-signal-v1` and `datalab-image-v1` state fingerprints (data, coordinates or calibration, units). A state also records the digest of its ROI definition, and an analysis result the digest of its stored value: a saved object whose data, calibration, units or ROI differ from its state is `altered`, and a result replaced by a later analysis is never attributed to the earlier one. Fingerprints are streamed into SHA-256 without copying the arrays.
+- Legacy workspaces: processing records stored by DataLab in object metadata (`__processing_parameters`, `__analysis_parameters`) of objects unknown to the ledger become `legacy_metadata` activities. They keep the record as stored and invent nothing: inputs are bound to the recorded objects (state unknown), the call is opaque without parameters, environment, edition and times are null, and import issues (missing ancestry, unavailable inputs, unsupported operations, version warnings...) are listed. They claim no result: the state of the holding object observed when the workspace was opened is named separately (`observed_state_id`), as an observed state that no activity produced. They are never replayed.
+- Capsules (`.dlcapsule`): a ZIP archive holding `workspace.h5` and an RO-Crate 1.3 manifest (`ro-crate-metadata.json`) that conforms to Process Run Crate 0.6 and to the experimental [DataLab capsule profile 0.1](https://datalab-platform.com/capsule/0.1) (terms: `https://datalab-platform.com/capsule/terms#`). The reader refuses unsafe archives (path traversal, duplicates, links, encryption, compressed entries, size limits) and never accesses the network. It holds the whole archive in memory: it checks the archive size before reading it, then the size of each entry. Each edition passes its own `SizePolicy`; the default one (4 GiB workspace) is an accepted upper bound, not a tested capacity.
+- Revisions and reviews: a capsule may name one parent revision by its manifest fingerprint (`dlc:revisionOf`), which is part of its own fingerprint. A review is a separate JSON document (`review-1` schema) that targets one revision by fingerprint, states who reviewed it and what was found (`endorsed`, `disputed` or `comment`), may cite verification reports by fingerprint, and has its own fingerprint. A review never modifies the capsule.
+- Referenced workspaces: a capsule may reference its workspace by an absolute IRI instead of including `workspace.h5` (`dlc:referenced`). The library never fetches it: the caller passes an explicit resolver, and the bytes obtained must match the SHA-256 and size recorded in the manifest.
+- Light attachments: up to 8 files of at most 16 MiB each, chosen by the author (protocol, notes, small tables...), stored under `attachments/` and declared in the manifest (`dlc:attachment`) with their media type, size and SHA-256. They are part of the manifest fingerprint. The reader refuses undeclared, missing or altered attachments. They are returned as bytes, written to disk only on explicit request, and never opened or executed.
+- Semantic diff (`diff_manifests`): changes between two capsules are sorted into scientific (activities, parameters, states, fingerprints, ROI), presentation (name, description, licence, date), storage (workspace file SHA-256 and size, included or referenced, locators: different bytes do not show a scientific change), environment (environments, packages, the environment of each activity) and attachments (added, removed or changed; their content is not interpreted, since a protocol or a calibration certificate may matter scientifically). `scientific_conclusion` says what can be concluded: `differences`, `none` (no scientific change, the same workspace file and the same attachment contents) or `none_detected` (nothing differs in the recorded activities and states, but the workspace files or the attachment contents differ, so equality is not established).
+- Verification without computation (`verify_capsule`): the archive and manifest, the workspace integrity, the match between the manifest and the workspace ledger, the fingerprints and ROI of every stored state (with h5py), and supplied verification reports and reviews. Recomputing an activity is the replay of an edition, never this package's job.
+- Pure Python for CPython 3.9+ and Pyodide (Python 3.12). The core only needs the standard library and `jsonschema`; HDF5 helpers use NumPy and h5py.
+- The package never imports DataLab, Sigima, SigimaX or Qt, and never executes code named in a file.
+
+## Installation
+
+Users of DataLab Desktop and DataLab-Web need nothing more than their edition: both handle capsules from _File > Workspace capsule…_ (export, inspection, local replay, revisions, registry) and use the same functions of this package (`datalab_capsule.exchange`). The [two-operator scenario](doc/scenario.md) follows that path.
+
+The package itself is installed in one of three ways, which must not be mixed up:
+
+- **Released version**, for users of the command line and third-party readers: `pip install datalab-capsule`, with the `hdf5` extra to create capsules or check stored states and the `registry` extra to run a registry.
+- **Candidate qualification**, before a release: a wheel and an sdist built from the commit to qualify (`python -m build`), checked with `scripts/check_dist.py` and `scripts/check_profile.py`, then installed in a clean environment, outside the checkout.
+- **Development**: editable install of this checkout, used by the sibling checkouts of DataLab and DataLab-Web (see [developer notes](doc/development.md)).
+
+## Command line
+
+Validating, inspecting and comparing capsules needs neither NumPy nor h5py:
+
+```powershell
+workspace-capsule validate workspace.dlcapsule
+workspace-capsule inspect workspace.dlcapsule [--json]
+workspace-capsule diff old.dlcapsule new.dlcapsule [--json]
+```
+
+`diff` exits with 0 when the capsules are the same revision (same manifest fingerprint) and 1 when they differ.
+
+Writing one attachment to a new file (an existing file is never overwritten, and the attachment is never opened):
+
+```powershell
+workspace-capsule attachment workspace.dlcapsule protocol.txt protocol.txt
+```
+
+Commands for an operator working with DataLab Desktop (`create` needs the `hdf5` extra): create a capsule from a saved workspace (optionally a revision of another capsule, with light attachments), write a review, extract the checked workspace to open it in DataLab, and exchange through a registry (only these commands use the network; everything fetched is checked):
+
+```powershell
+workspace-capsule create workspace.h5 workspace.dlcapsule [--name NAME] [--description TEXT] [--revision-of PARENT.dlcapsule] [--workspace-ref IRI] [--attach FILE]...
+workspace-capsule review workspace.dlcapsule review.json --reviewer NAME --statement TEXT [--verdict endorsed|disputed|comment] [--report report.json]...
+workspace-capsule workspace workspace.dlcapsule workspace.h5
+workspace-capsule registry list URL [--json]
+workspace-capsule registry publish URL workspace.dlcapsule [--review review.json]... --token-env VARIABLE
+workspace-capsule registry fetch URL FINGERPRINT FOLDER
+```
+
+`diff` also compares manifest files (`.json`) fetched from a registry. `registry fetch` does not save an attachment whose name Windows reserves for a device (`NUL`, `CON`...). The [two-operator scenario](doc/scenario.md) puts these commands together with DataLab Desktop and DataLab-Web.
+
+Verifying a capsule reads the stored states with h5py; without h5py, it checks only the workspace SHA-256 and size and says so (`integrity_only`). A referenced workspace is checked only when its file is given; reports and reviews are optional:
+
+```powershell
+workspace-capsule verify workspace.dlcapsule [--workspace workspace.h5] [--report report.json]... [--review review.json]... [--json]
+```
+
+`verify` exits with 0 when no problem is found and 1 otherwise. It never computes or fetches anything.
+
+Creating a capsule from a workspace saved by DataLab (needs the `hdf5` extra):
+
+```powershell
+python examples/workspace_to_capsule.py workspace.h5 workspace.dlcapsule
+```
+
+Reading and checking a capsule without this package, with `json`, `zipfile`, `hashlib` and h5py only (a third-party example that follows the published profile):
+
+```powershell
+python examples/third_party_reader.py workspace.dlcapsule
+```
+
+## Registry (optional)
+
+A small registry publishes and serves capsule manifests, the attachments they declare and their reviews, so that revisions can be found, compared and discussed. It never stores workspaces: a manifest names its workspace by SHA-256 and size (and by address when it is referenced). Everything keeps working without a registry. Manifests are validated and identified by their fingerprint, attachments must match their declared size and SHA-256, reviews must target a published revision. Metadata is kept in SQLite and documents in files.
+
+```powershell
+pip install "datalab-capsule[registry]"
+$env:REGISTRY_TOKEN = "<secret>"
+workspace-capsule-registry registry-data --token-env REGISTRY_TOKEN --origin https://web.example
+```
+
+Reading is open; publishing needs `Authorization: Bearer <token>` when a token is set (without one, publishing is open: local use only). The API is described at `/docs` and `/openapi.json`; see [API](doc/api.md#registry).
+
+## Documentation
+
+- [Two-operator scenario](doc/scenario.md): DataLab Desktop and DataLab-Web, without server and with a registry
+- [Interoperability report](doc/interoperability.md): what the editions exchange, check and replay, findings and limits
+- [Performance and capacity](doc/performance.md): how costs are measured, results and recommended sizes
+- [Developer notes](doc/development.md) and [deployment notes](doc/deployment.md) (registry, profile pages)
+- [Identity, compatibility and restoration rules](doc/rules.md)
+- [API](doc/api.md)
+- [Security analysis](doc/security.md)
+- [Decision 0001: foundations of the processing chain](doc/decisions/0001-processing-chain-foundations.md)
+- [Fixture corpus](tests/fixtures/corpus/README.md), valid and invalid, with the expected command-line results
+- Profile and terms: <https://datalab-platform.com/capsule/0.1>
+
+## Development
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[test,dev]"
+.\.venv\Scripts\python.exe -m pytest
+```
+
+Golden vectors and the test suite in Pyodide (Node 22):
+
+```powershell
+.\.venv\Scripts\python.exe -m pip wheel . --no-deps -w dist
+cd tests\pyodide
+npm install
+node run_pyodide.mjs (Resolve-Path ..\..\dist\datalab_capsule-*.whl)
+```
+
+Cost of fingerprints and of capsules (time and memory), in CPython and in Pyodide (see [performance](doc/performance.md)):
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -r benchmarks\requirements.txt
+.\.venv\Scripts\python.exe benchmarks\fingerprint_cost.py --profile quick --output build\bench\fingerprints.json
+.\.venv\Scripts\python.exe benchmarks\capsule_cost.py --profile representative --output build\bench\capsules.json
+cd tests\pyodide
+node run_benchmark.mjs (Resolve-Path ..\..\dist\datalab_capsule-*.whl) capsule_cost.py --profile quick --output ..\..\build\bench\capsules-pyodide.json
+```
+
+## License
+
+BSD 3-Clause, see [LICENSE](LICENSE). The embedded RO-Crate 1.3 JSON-LD context (`src/datalab_capsule/contexts/ro-crate-1.3.jsonld`) is distributed by its authors under CC0 1.0.