sverdrup 0.1.0__tar.gz

sverdrup-0.1.0/.claude/CLAUDE_SETTINGS_summarize_and_exit.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "PreCompact": [{
+      "matcher": "auto",
+      "hooks": [{
+        "type": "command",
+        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/summarize-and-exit.sh"
+      }]
+    }]
+  }
+}

sverdrup-0.1.0/.claude/hooks/summarize-and-exit.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Written in 2026 at JPL by Emmy Killett (she/her) and Claude Opus 4.7 adaptive (it/its).
+set -euo pipefail
+
+input=$(cat)
+transcript=$(echo "$input" | jq -r '.transcript_path')
+
+# Prefer LOOP_ITERATION from the outer loop; fall back to next free number.
+if [[ -n "${LOOP_ITERATION:-}" ]]; then
+  iter="$LOOP_ITERATION"
+else
+  n=1
+  while [[ -e "PROGRESS$(printf '%03d' "$n").md" ]]; do ((n++)); done
+  iter=$(printf '%03d' "$n")
+fi
+outfile="PROGRESS${iter}.md"
+
+# Headless sub-session generates the summary from the transcript.
+# Timeout prevents indefinite hangs (rate limit, network failure, etc.).
+if timeout 120 claude -p "Read the transcript JSONL at $transcript and write a \
+concise progress report to $outfile in the current directory, covering: \
+current task, completed work, pending work, files modified, and the \
+exact next step to resume. Be specific enough that a fresh session can \
+continue without re-reading the transcript." >/dev/null 2>&1 && [[ -s "$outfile" ]]; then
+  # Progress saved successfully — kill the outer session so the loop advances.
+  kill -TERM "$PPID" 2>/dev/null || true
+  echo "Threshold reached — progress saved to $outfile" >&2
+  exit 2
+else
+  echo "WARNING: Failed to save progress to $outfile — letting Claude continue." >&2
+  exit 1
+fi

sverdrup-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+  name: release
+
+  on:
+    push:
+      tags: ["v*"]
+
+  jobs:
+    build:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            fetch-depth: 0   # hatch-vcs needs full history + tags
+        - uses: actions/setup-python@v5
+          with:
+            python-version: "3.12"
+        - name: Build
+          run: |
+            python -m pip install --upgrade build twine
+            python -m build
+            python -m twine check dist/*
+        - uses: actions/upload-artifact@v4
+          with:
+            name: dist
+            path: dist/
+
+    publish:
+      needs: build
+      runs-on: ubuntu-latest
+      environment: pypi
+      permissions:
+        id-token: write   # OIDC for Trusted Publishing
+      steps:
+        - uses: actions/download-artifact@v4
+          with:
+            name: dist
+            path: dist/
+        - uses: pypa/gh-action-pypi-publish@release/v1

sverdrup-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Test / coverage / type caches
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build artefacts + generated version file
+dist/
+src/sverdrup/_version.py
+
+# Secrets — never commit env files or cloud creds
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*-sa.json
+
+# Editor / OS
+.DS_Store
+
+# Superpowers session state + logs
+.superpowers/
+*.log
+
+# Project-local
+.claude-project-id
+.sandbox_settings.json
+data/cache/

sverdrup-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,47 @@
+repos:
+  - repo: local
+    hooks:  # On macOS, pixi-installed tools (pytest, ruff, mypy) can fail due to shebang path resolution issues. Using python -m <tool> bypasses this reliably.
+      - id: ruff
+        name: ruff
+        entry: pixi run python -m ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff-format
+        entry: pixi run python -m ruff format
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: pixi run python -m mypy .
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      # Built-in pygrep — no remote pre-commit-hooks dep, no network.
+      # Real conflict markers: `<<<<<<< <ref>` and `>>>>>>> <ref>` (with
+      # trailing space) and `=======` *alone on a line*. The bare-`=======`
+      # form would otherwise false-positive on pytest's `======== … ========`
+      # header lines (>7 equals followed by text), so we anchor it $.
+      - id: check-merge-conflict
+        name: check-merge-conflict
+        entry: '^(<<<<<<< |>>>>>>> |={7}$)'
+        language: pygrep
+
+      # Local reimplementation of pre-commit-hooks' check-added-large-files
+      # (default maxkb=500 → 500000 bytes). System bash + wc only; bash's
+      # arithmetic context strips BSD-wc's leading whitespace so no tr needed.
+      - id: check-added-large-files
+        name: check-added-large-files (limit 500 KB)
+        entry: 'bash -c ''max=500000; rc=0; for f in "$@"; do sz=$(wc -c < "$f"); if (( sz > max )); then echo "$f: $sz bytes exceeds limit of $max" >&2; rc=1; fi; done; exit $rc'' --'
+        language: system
+
+      # Local reimplementation of pre-commit-hooks' check-toml. tomllib is
+      # stdlib in 3.11+; this template requires 3.12+. Routed through
+      # `pixi run python` so the env (and its Python) is the same one the
+      # other hooks use.
+      - id: check-toml
+        name: check-toml
+        entry: 'pixi run python -c ''import sys,tomllib;[tomllib.load(open(f,"rb")) for f in sys.argv[1:]]'''
+        language: system
+        types: [toml]

sverdrup-0.1.0/CLAUDE.md

@@ -0,0 +1,126 @@
+# Project: sverdrup
+
+## Session resume protocol (read this first, every session)
+This project may be built across multiple sessions, and a session can die
+mid-run. On **every** new or resumed session, before doing anything else:
+
+1. Read `PROGRESS.md` at the repo root. It carries the index of the current
+   active work AND the project's running notebook of deferred items,
+   cross-cutting decisions, gotchas, and open questions. Read all of it.
+2. Open the design doc and implementation plan that `PROGRESS.md` points to.
+3. Run `git log --oneline -20` to see what is already committed.
+4. Resume from the first unchecked task in the plan. **Do not** redo work
+   that is already committed.
+
+If `PROGRESS.md` does not exist yet, you are at the very start of the
+project; create it (with the headings described in the Durability rules
+below, sections initially empty) as soon as a design or plan exists.
+
+If Superpowers is installed and this project uses it, prefer its native
+resume mechanism (`/superpowers-extended-cc:executing-plans <plan-path>`)
+over reading `PROGRESS.md`'s **Current work** section by hand — that
+command reads the plan's `.tasks.json` and picks up exactly where the
+last session stopped. The other PROGRESS.md sections (deferred items,
+decisions, gotchas, open questions) are NOT covered by Superpowers, so
+read them either way.
+
+## Durability rules (always)
+- **Git is the source of truth, not the conversation.** Commit after every
+  completed task, with a clear message. Never end a step with completed
+  work left uncommitted.
+- **Keep `PROGRESS.md` current.** The **Current work** block is an index
+  — point at the design doc, plan, and task tracker; do NOT duplicate the
+  task checklist into PROGRESS.md (link to the plan instead, so there's
+  one place to update task state). The other sections (deferred items,
+  cross-cutting decisions, gotchas, open questions) hold canonical content
+  that lives nowhere else; add to them as the project teaches you things
+  worth not forgetting. Refresh the "next action" line and commit
+  PROGRESS.md after each task.
+- **Persist the brainstorm as it forms.** During brainstorming, append
+  each validated design section to the design doc and commit it — never
+  leave the agreed design only in the conversation.
+- **Migrate, don't duplicate.** When a deferred item or open question
+  becomes active work, move it out of PROGRESS.md into the new design/plan
+  rather than leaving a copy behind.
+
+## Environment & tools
+
+- Use `rg` instead of `grep`, `fd` instead of `find`.
+
+## Workspace scaffolding
+
+This project has already been scaffolded. The following files
+already exist and should NOT be recreated:
+
+- `pyproject.toml` — project metadata + ruff/mypy/pytest/coverage config
+- `pixi.toml` — pixi workspace with dev dependencies (ruff, mypy, pytest, pytest-cov, pre-commit)
+- `.pre-commit-config.yaml` — pre-commit hooks (ruff, ruff-format, mypy, trailing-whitespace, end-of-file-fixer, etc.)
+- `.gitignore` — standard Python ignores
+
+**Do NOT run `pixi init` or `pre-commit sample-config`.**
+
+## Project layout
+
+Use a `src/` layout:
+
+```
+src/
+  <package_name>/
+    __init__.py
+    __main__.py
+    ...
+tests/
+  __init__.py
+  test_*.py
+```
+
+The package name should be the project name normalized to a valid Python identifier
+(lowercase, spaces/hyphens replaced with underscores).
+
+## Running tools
+
+All dev tools are installed via pixi. Use `pixi run` to invoke them:
+
+- `pixi run test` — run tests (pytest)
+- `pixi run lint` — lint (ruff check .)
+- `pixi run format` — format (ruff format .)
+- `pixi run typecheck` — type check (mypy .)
+- `pixi run pre-commit run` — run pre-commit on staged files
+- `pixi run pre-commit run --files <path>` — run pre-commit on specific files
+- `pixi run pre-commit run --all-files` — run pre-commit on every file
+- `pixi run pre-commit install` — install the git pre-commit hook
+  (`pre-commit` is only available via `pixi run` — no system binary)
+
+To add a new dependency: `pixi add <package>`
+To add a PyPI-only dependency: `pixi add --pypi <package>`
+
+## Cross-platform conda gotchas
+
+This project's `pixi.toml` lists `platforms = ["linux-64", "osx-arm64", "osx-64"]`,
+so `pixi install` must solve cleanly on macOS even when the actual run happens in
+the Linux container. Some conda-forge packages have no `osx-arm64` build and will
+fail resolution on macOS with `No candidates were found`. Move them into
+`[target.linux-64.dependencies]` (already scaffolded into your `pixi.toml`)
+instead of `[dependencies]`.
+
+Symptom: `pixi add <pkg>` (or `pixi install`) fails with
+`No candidates were found for <pkg>` while the package clearly exists on
+conda-forge for linux-64.
+
+Fix: edit `pixi.toml` to add the package under `[target.linux-64.dependencies]`,
+then `pixi install`. Or use `pixi add --platform linux-64 <pkg>`.
+
+Known offenders (non-exhaustive):
+
+- `pngquant` — pulled in by `ocrmypdf`; together they force linux-64-only.
+- `pytorch-cuda` — CUDA runtime, linux-only by design.
+
+If you can swap to a lighter cross-platform alternative, prefer that
+(e.g. `tesseract` + `pytesseract` + `pypdfium2` instead of `ocrmypdf`).
+
+## First-time setup
+
+Already done by the container entrypoint — git repo
+initialized, git identity configured, dependencies
+installed, pre-commit hooks active, initial scaffold
+committed.

sverdrup-0.1.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.

sverdrup-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: sverdrup
+Version: 0.1.0
+Summary: Regional sea-surface-height-anomaly reconstruction with first-class predictive uncertainty
+Project-URL: Homepage, https://github.com/killett/sverdrup
+Project-URL: Repository, https://github.com/killett/sverdrup
+Project-URL: Issues, https://github.com/killett/sverdrup/issues
+Author-email: Emmy Killett <emmykillett@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: gaussian process,oceanography,optimal interpolation,sea surface height,uncertainty quantification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.12
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyproj>=3.6
+Requires-Dist: scipy>=1.11
+Provides-Extra: all
+Requires-Dist: dask[distributed]>=2024.1; extra == 'all'
+Requires-Dist: fsspec>=2024.1; extra == 'all'
+Requires-Dist: netcdf4>=1.6; extra == 'all'
+Requires-Dist: requests>=2.31; extra == 'all'
+Requires-Dist: tenacity>=8.2; extra == 'all'
+Requires-Dist: xarray>=2024.1; extra == 'all'
+Provides-Extra: dask
+Requires-Dist: dask[distributed]>=2024.1; extra == 'dask'
+Provides-Extra: io
+Requires-Dist: fsspec>=2024.1; extra == 'io'
+Requires-Dist: netcdf4>=1.6; extra == 'io'
+Requires-Dist: requests>=2.31; extra == 'io'
+Requires-Dist: tenacity>=8.2; extra == 'io'
+Requires-Dist: xarray>=2024.1; extra == 'io'
+Description-Content-Type: text/markdown
+
+# sverdrup
+
+A regional SSHA (sea-surface-height anomaly) reconstruction framework with first-class,
+rigorous predictive-distribution uncertainty. Phase 1 wires a single space-time tile
+end-to-end (OSSE + OSE) through a hexagonal stack: a hand-rolled dense space-time GP / optimal
+interpolation exposes native covariance and whole-field samples behind a `CovarianceOperator`
+seam, and each unit of work returns a *Persisted* `Product` bundle (mean + exact marginal
+variance + low-rank factor + clipped diagonal residual + eval-point predictions) reduced
+on-worker while the exact operator is still live.
+
+## Installation
+
+Dependencies are managed with [pixi](https://pixi.sh):
+
+```
+pixi install
+```
+
+## Quick usage
+
+Run a config-driven pipeline over a regional tile (OSSE on the committed fixtures):
+
+```
+pixi run python -m sverdrup tests/integration/config_osse.json
+```
+
+This windows the observations, dispatches the solve through a `dask.distributed` LocalCluster,
+writes the persisted `Product` to an fsspec URL, and prints evaluator scores (RMSE vs truth,
+calibration, ground-track power).
+
+Programmatically:
+
+```python
+from sverdrup.adapters.odc.fixtures import FixtureSource
+from sverdrup.application.pipeline import PipelineInputs, run_pipeline
+
+src = FixtureSource("tests/fixtures/natl60_tiny.nc", ref_path="tests/fixtures/natl60_ref_tiny.nc")
+product, scores = run_pipeline(PipelineInputs(
+    mode="OSSE", method_name="oi", source=src, out_url="file:///tmp/osse.zarr",
+    lon_range=(-64, -56), lat_range=(34, 42), time_range=(0, 5), output_times=[2.0],
+    params={"length_scale": 300.0, "time_scale": 10.0, "variance": 0.05},
+))
+```
+
+## Common tasks
+
+```
+pixi run test        # pytest (the opt-in oracle is skipped without SVERDRUP_ODC_DATA)
+pixi run lint        # ruff check
+pixi run format      # ruff format
+pixi run typecheck   # mypy
+```
+
+The correctness oracle (reproducing the ODC OI leaderboard number) is opt-in — see
+[`docs/oracle-runbook.md`](docs/oracle-runbook.md).
+
+## Releasing
+
+Publishing to PyPI is automated via GitHub Actions Trusted Publishing on tag push. The
+workflow lives at `docs/superpowers/ci/release.yml`; copy it to `.github/workflows/release.yml`
+in the GitHub repo (a one-time step — the local tooling token cannot push workflow files).
+Configure the PyPI trusted publisher (project `sverdrup`, owner `killett`, repo `sverdrup`,
+workflow `release.yml`, environment `pypi`), then `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z`.
+
+## Project structure
+
+```
+src/sverdrup/
+  core/          # pure protocols + value objects (grid, types, distribution, product, ports, ...)
+  distributions/ # Gaussian / Ensemble / Persisted distributions + lifting adapters
+  methods/       # space-time Matern-3/2 kernel, Cholesky solver, GP/OI (Method 1), trivial (Method 0)
+  derived/       # CRS-aware first-difference (real) + committed stubs
+  eval/          # accuracy, calibration (+ polar-void), ground-track evaluators
+  adapters/      # dask executor, fsspec result sink, ODC data sources + fixtures
+  application/   # unit of work, solve_unit, splits, run config, end-to-end pipeline
+tests/           # unit, integration, oracle; tiny committed NetCDF fixtures
+docs/            # architecture design, implementation plan, oracle runbook
+```
+
+See `PROGRESS.md` for the running project notebook (decisions, gotchas, deviations).