feat(bootstrap)!: source hyperd from the PyPI tableauhyperapi wheels (#254)

## Motivation

`hyperdb-bootstrap` fetched `hyperd` from Tableau's Hyper **Java API
zip**, whose
filename embeds an opaque `build_id` (e.g. `r07abb490`) that **cannot be
derived
from the version**. Discovering it meant scraping the public releases
page — and
that scraper (`src/scrape.rs`, behind `--latest`) has been **broken for
three-plus
releases without anyone noticing**, because its tests ran against a
synthetic
fixture rather than the live page. Two independent defects:

- the heading regex expects `<h3>VERSION [DATE]</h3>`, but Docusaurus
renders
  `0.0.26479 <!-- -->[September 3 2026]`, which `\s*` cannot span;
- the build-id capture hardcodes `(rc[a-z0-9]+)`, while every build id
since
  `0.0.24457` has been `r` + hex.

The PyPI `tableauhyperapi` wheels carry the same engine behind a **fully
constructible** URL, and **PyPI publishes a sha256 per file**:

```text
https://files.pythonhosted.org/packages/py3/t/tableauhyperapi/tableauhyperapi-{version}-py3-none-{wheel_tag}.whl
```

So `--latest` is **deleted, not fixed**: with a constructible URL and
published
digests there is nothing left for it to do.

## The bytes are unchanged

The strongest evidence this migration is faithful — the `hyperd`
extracted from
the `macosx_13_0_arm64` wheel is **bit-identical to the `hyperd` in the
Java zip
for the same release**, sha256
`aef5c81970bb4d84d06fb9513d5ffd722526fce779632a0c5f63d87b6450e478`. To
be precise
about what is and isn't established here: that cross-envelope equality
was
established upstream of this PR and I did not re-derive it. What I
verified
locally is that the wheel path produces exactly that binary:

```text
$ shasum -a 256 .hyperd/current/hyperd
aef5c81970bb4d84d06fb9513d5ffd722526fce779632a0c5f63d87b6450e478

$ stat -f%z .hyperd/current/hyperd
277836448

$ file .hyperd/current/hyperd
.hyperd/current/hyperd: Mach-O 64-bit executable arm64

$ .hyperd/current/hyperd --version
Hyper version main.0.0.26479.r96880f6a
```

Same build, different envelope. Note the `--version` line corroborates
this
independently: the wheel's binary self-reports build `r96880f6a`, which
is exactly
the `build_id` the Java zip carries for `0.0.26479` (see
`chore/post-rc-cleanup`'s
`8c99d20`). It is the same engine build reached by a different filename.

This is *not* a claim that the wheel matches the engine currently on
`main`
(`0.0.26359`, build `r07abb490`) — that is a different build. The
equality is
same-release, cross-envelope.

Both binaries report `minos 13.0`, so the `macosx_13_0` wheel tag is
**not** a
raised support floor — no contributor loses support. Wheels are
~3.6–4.5% smaller
than the Java zips.

Bumping the pin no longer means downloading four ~80 MB archives and
hashing them
by hand — the digests come off the JSON API. They are **still
committed**: a hash
in git is an attestation independent of the host serving the bytes.

## Breaking changes

Public API removed:

| Removed | Replacement |
|---|---|
| `PinnedRelease::build_id`, `InstalledHyperd::build_id` | `.version` is
the only release identifier |
| `PinnedRelease::version_tag()` | `.version` |
| `VersionSource::ScrapeLatest`, the `scrape` module | none — deleted |
| `Error::Http`, `Error::HttpStatus`, `Error::ScrapeFailed` | none —
served the scraper only |
| CLI `--latest`, `--build-id` | `--version X` alone is now a complete
source |
| `regex`, `reqwest`, `rustls` deps | none — no in-process HTTP client
remains |

`url::build_download_url` is now **fallible** (`Result<String, Error>`);
a platform
with no pinned wheel tag is `Error::MissingWheelTag` rather than a
guess.
`PinnedRelease::wheel_tag_for(Platform)` is new.

The install layout is keyed on the version alone: `<dest>/0.0.26479/`
(was
`<dest>/0.0.26479.r96880f6a/`), and `current/VERSION` now contains just
`0.0.26479`. Nothing in the repo reads that file programmatically.

Dropping `reqwest`/`rustls` also **retires the rustls crypto-provider
workaround**
the CHANGELOG records as a past breaking change (`rustls-no-provider`
plus a
`OnceLock` installing ring). Verified `aws-lc-rs` is absent
workspace-wide and
that `hyperdb-bootstrap` no longer reaches `reqwest`, `rustls`, or
`regex` at all.

## Versioning: breaking, released as `1.0.0-rc.2`

**Decided — no reviewer action needed.** The break is now marked
honestly *and*
the version is pinned, which are two independent things:

- The subject is `feat(bootstrap)!:` and the migration commit carries a
`BREAKING CHANGE:` footer enumerating every removed item. The break is
real
  and is recorded as such.
- An empty follow-up commit, `chore: release 1.0.0-rc.2`, carries a
`Release-As: 1.0.0-rc.2` footer, which pins the next release inside the
  `1.0.0-rc` line.

Without that footer the `!` would compute **2.0.0**: the workspace is
already on
`1.x`, and `bump-minor-pre-major` in `release-please-config.json` is
gated on
`version.isPreMajor` (`major < 1`), so it does not apply at
`1.0.0-rc.1`.
`Release-As:` wins regardless — release-please's
`DefaultVersioningStrategy`
returns a `CustomVersionUpdate` from the `RELEASE AS` note *before* it
reads the
breaking-change tally. This is the same mechanism, and the same
empty-commit
shape, that produced `1.0.0-rc.1` (`7bf2dff`), and it is what
[`docs/GITHUB_OPERATIONS.md` →
Pre-releases](https://github.com/tableau/hyper-api-rust/blob/main/docs/GITHUB_OPERATIONS.md#pre-releases)
documents.

Simulated against `release-please@17.11.2` (the version
`release-please-action@v5` pins) using its real
`parseConventionalCommits` and
`DefaultVersioningStrategy`: `1.0.0-rc.1` → **`1.0.0-rc.2`** under a
merge
commit *and* under a squash merge. Dropping the footer from the same
input
yields `2.0.0-rc.1`, which is the outcome this pin exists to prevent.

> **Do not merge a release PR that says anything other than
`1.0.0-rc.2`.**
> #253 merges first, and release-please will run on that push and open a
> `chore(main): release …` PR computed from #253's commits alone —
before this
> PR's `Release-As:` footer is on `main`. That PR will show the wrong
version.
> It updates itself once this PR lands; leave it alone until then.

## Why wheel tags live in the pin file

They are deliberately *not* hardcoded in Rust. They are not guaranteed
stable
across releases (arm64 wheels only exist from `0.0.19484`; a future
macOS floor
bump would change `macosx_13_0_arm64`), and a wrong tag is a **silent
404** on one
platform only. Keeping them as pin data makes any such change a visible
pin edit,
and `build.rs` now fails the build if any supported platform lacks one.
(Empirically the four tags are unchanged from `0.0.19484` through
`0.0.26479`.)

## Stronger `verify`

`hyperdb-bootstrap verify` now cross-checks every pinned digest against
the digest
PyPI publishes for that exact wheel filename, on top of HEAD-ing the
four URLs —
so it validates the **exact pinned bytes** rather than merely that the
CDN serves
something at that path, and it catches a stale `[wheel_tag]` explicitly:

```text
$ cargo run --release -p hyperdb-bootstrap --bin hyperdb-bootstrap -- verify
verifying hyperd 0.0.26479...
  OK    macos-arm64      [200] .../tableauhyperapi-0.0.26479-py3-none-macosx_13_0_arm64.whl
        digest matches PyPI
  OK    macos-x86_64     [200] .../tableauhyperapi-0.0.26479-py3-none-macosx_10_11_x86_64.whl
        digest matches PyPI
  OK    linux-x86_64     [200] .../tableauhyperapi-0.0.26479-py3-none-manylinux2014_x86_64.whl
        digest matches PyPI
  OK    windows-x86_64   [200] .../tableauhyperapi-0.0.26479-py3-none-win_amd64.whl
        digest matches PyPI
all platforms reachable with matching digests.
```

## npm dual pin

`npm-build-publish.yml` carries its own independent pin (this is why
`0.7.1` once
shipped npm with a different engine than crates.io). It is migrated to
the wheel
URL, `HYPERD_BUILD_ID` is gone, and the matrix gains `hyperd-wheel-tag`.
`verify-npm-hyperd-pin.py` keeps its version + digest cross-check and
**gains a
wheel-tag cross-check**, since the tag is a new drift vector.

Empirically confirmed (not assumed) that the matrix `hyperd-sha256`
values are
digests of the **downloaded archive**, not the extracted binary — the
step hashes
`hyperd-archive.whl` — so they are the wheel digests and equal the
toml's
`[sha256]`.

I did **not** make the workflow read the toml directly. The matrix must
be static
YAML, so it would need a `tomllib` call inside the per-platform matrix
job, which
runs on a Windows runner under git-bash where `python3` may not be on
`PATH` — an
untestable portability risk for no correctness gain over the guard.
**Recommended
as a follow-up** alongside converting the matrix to a `setup`-job JSON
output.

## Verification

Run on macOS arm64 (Apple Silicon):

- `cargo build -p hyperdb-bootstrap` and `cargo build --workspace` —
clean
- `cargo test -p hyperdb-bootstrap` — 26 lib + 4 integration + 1 doc, 0
failed
  (up from 12 lib + 2 integration; +16 runnable tests)
- `cargo test --workspace` — **1584 passed, 0 failed**, against the
freshly
  downloaded engine
- `make test` — **1519 passed, 0 failed**
- `cargo fmt --all -- --check` and
`cargo clippy --workspace --all-targets --all-features -- -D warnings` —
clean
- `npx markdownlint-cli2` — zero new findings; the 5 in `AGENTS.md` /
`DEVELOPMENT.md` are the pre-existing MD040 backlog, identical before
and after
- `verify-npm-hyperd-pin.py` passes against the new toml, and **fails
correctly**
  when a wheel tag is perturbed
- The workflow's `find`-based extraction was replayed against the real
wheel entry
names: `HYPER_DIR=hyperd-raw/tableauhyperapi/bin/hyper`, `hyperd` found,
  `LICENSE*`/`NOTICE*` glob matches `dist-info/`

`extract.rs` is **unchanged** apart from doc comments — its "skip one
optional
top-level directory, then require a `lib/hyper` or `bin/hyper` pair"
logic already
absorbs the `tableauhyperapi` wrapper. New tests pin that against the
real wheel
entry names, including the Windows `hyperd.exe` + `crashdumper.exe`
case.

### Not verified here

- **Only macOS arm64 was executed.** The other three platforms rest on
CI. Their
URLs and digests *are* machine-verified (all four HEAD 200 with matching
PyPI
digests), and I downloaded the Windows and Linux wheels to confirm their
`bin/hyper/` contents (`hyperd.exe` + `crashdumper.exe`; `hyperd`) and
digests —
  but no `hyperd` was run on Linux or Windows.
- The engine links only system frameworks (`otool -L`) and `bin/hyper/`
contains
  no shared libraries on any of the three wheels I inspected, so the npm
  shared-library copy loop finds nothing to copy — as before.

---

Repeated here as a trailing footer so the version is pinned on the merge
commit
too: this repo merges with `merge_commit_message = PR_BODY`, so the body
below
becomes the merge commit's body. Same value as the footer on
`chore: release 1.0.0-rc.2`, so it is redundant rather than conflicting.

Release-As: 1.0.0-rc.2

Author: StefanSteiner

.agents/skills/update-hyperd-release/SKILL.md

@@ -2,8 +2,9 @@
 """Guard: keep the npm release workflow's hyperd pin in sync with the toml.
 
 `.github/workflows/npm-build-publish.yml` bundles `hyperd` into the npm
-packages using its OWN hardcoded `HYPERD_VERSION` / `HYPERD_BUILD_ID` /
-per-platform matrix `hyperd-sha256`s. Those are decoupled from
+packages from the PyPI `tableauhyperapi` wheel, using its OWN hardcoded
+`HYPERD_VERSION` plus per-platform matrix `hyperd-wheel-tag`s and
+`hyperd-sha256`s. Those are decoupled from
 `hyperdb-bootstrap/hyperd-version.toml`, which is what `make download-hyperd`
 and the crates.io path use.
 
@@ -12,10 +13,16 @@
 This script fails CI whenever the two drift, so that can't recur silently.
 
 The platform slug (`macos-arm64`, `linux-x86_64`, `windows-x86_64`) is the join
-key: it is identical between the toml's `[sha256]` table and the workflow's
-`hyperd-slug` matrix field. Only slugs the workflow actually builds are checked,
-so a commented-out matrix entry (invisible to the YAML parser) and any unused
-extra toml sha are both fine.
+key: it is identical between the toml's `[wheel_tag]` / `[sha256]` tables and
+the workflow's `hyperd-slug` matrix field. Only slugs the workflow actually
+builds are checked, so a commented-out matrix entry (invisible to the YAML
+parser) and any unused extra toml entry are both fine.
+
+The wheel tag (`macosx_13_0_arm64`, `manylinux2014_x86_64`, ...) is checked
+alongside the digest because it is a drift vector of its own: it is not
+derivable from the version, and a wrong tag resolves to a URL that does not
+exist, so it would surface as an opaque 404 mid-release rather than as a
+mismatch. The sha256s are digests of the downloaded `.whl` archive.
 """
 
 from __future__ import annotations
@@ -36,12 +43,12 @@ def main() -> int:
     workflow = yaml.safe_load(WORKFLOW.read_text())
 
     env = workflow.get("env", {})
+    toml_wheel_tag = toml_data.get("wheel_tag", {})
     toml_sha = toml_data.get("sha256", {})
 
     # (label, expected-from-toml, actual-from-workflow)
     checks: list[tuple[str, str, str | None]] = [
         ("HYPERD_VERSION", str(toml_data["version"]), env.get("HYPERD_VERSION")),
-        ("HYPERD_BUILD_ID", str(toml_data["build_id"]), env.get("HYPERD_BUILD_ID")),
     ]
 
     errors: list[str] = []
@@ -51,13 +58,22 @@ def main() -> int:
         slug = entry.get("hyperd-slug")
         if slug is None:
             continue
-        expected = toml_sha.get(slug)
-        if expected is None:
+        expected_tag = toml_wheel_tag.get(slug)
+        if expected_tag is None:
+            errors.append(
+                f'matrix slug "{slug}" has no [wheel_tag]."{slug}" entry in {TOML.name}'
+            )
+        else:
+            checks.append(
+                (f"wheel_tag[{slug}]", expected_tag, entry.get("hyperd-wheel-tag"))
+            )
+        expected_sha = toml_sha.get(slug)
+        if expected_sha is None:
             errors.append(
                 f'matrix slug "{slug}" has no [sha256]."{slug}" entry in {TOML.name}'
             )
             continue
-        checks.append((f"sha256[{slug}]", expected, entry.get("hyperd-sha256")))
+        checks.append((f"sha256[{slug}]", expected_sha, entry.get("hyperd-sha256")))
 
     for label, expected, actual in checks:
         if actual == expected:
@@ -72,8 +88,9 @@ def main() -> int:
         sys.stdout.flush()
         print(
             f"\n{WORKFLOW.name} is out of sync with {TOML.name}. "
-            "Update the workflow's env vars and matrix sha256s to match the toml "
-            "(or vice versa) so npm bundles the same hyperd as crates.io.",
+            "Update the workflow's env vars and matrix wheel tags / sha256s to "
+            "match the toml (or vice versa) so npm bundles the same hyperd as "
+            "crates.io.",
             file=sys.stderr,
         )
         return 1

.claude/skills/update-hyperd-release/SKILL.md

@@ -23,8 +23,11 @@ permissions:
 
 env:
   CARGO_TERM_COLOR: always
+  # hyperd is bundled from the PyPI `tableauhyperapi` wheel. This version and
+  # the per-platform wheel tags / sha256s in the build-npm matrix below must
+  # match hyperdb-bootstrap/hyperd-version.toml — enforced by
+  # .github/scripts/verify-npm-hyperd-pin.py.
   HYPERD_VERSION: "0.0.26479"
-  HYPERD_BUILD_ID: "r96880f6a"
 
 jobs:
   verify-ci:
@@ -92,27 +95,35 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # hyperd-wheel-tag is the PyPI platform tag for this slug. It is NOT
+          # derivable from HYPERD_VERSION, so it has to be carried explicitly;
+          # a wrong tag yields a 404 rather than a version mismatch.
+          # hyperd-sha256 is the digest of the downloaded .whl archive.
           - platform: darwin-arm64
             os: macos-14
             target: aarch64-apple-darwin
             hyperd-slug: macos-arm64
-            hyperd-sha256: "65bd021b3d3470ac74728ec287866a3ee0dfd806daf2589670feb3580955ee95"
+            hyperd-wheel-tag: macosx_13_0_arm64
+            hyperd-sha256: "e80e4dac6d8437ad8c20f36add7e523b18bc06d90d4c605a256c57df8df2c118"
           # TODO: re-enable when macos-13 runners are more available
           # - platform: darwin-x64
           #   os: macos-13
           #   target: x86_64-apple-darwin
           #   hyperd-slug: macos-x86_64
-          #   hyperd-sha256: "6690669c8a6a6c7c6794c101beb31b83e1589d76cb14b0c817523069591f694c"
+          #   hyperd-wheel-tag: macosx_10_11_x86_64
+          #   hyperd-sha256: "960e276028137847a3870695d9c2d5a1392c173b1e119ff1146d24a75deca71a"
           - platform: linux-x64-gnu
             os: ubuntu-latest
             target: x86_64-unknown-linux-gnu
             hyperd-slug: linux-x86_64
-            hyperd-sha256: "c20be5b6874d319c7db01dcec763d7e65ae2483c0becc75f2914a58accc4f932"
+            hyperd-wheel-tag: manylinux2014_x86_64
+            hyperd-sha256: "9f5ff04c0dc3c17224b7a3f36f297775f2f49aae084da84614003cd6508213bc"
           - platform: win32-x64-msvc
             os: windows-latest
             target: x86_64-pc-windows-msvc
             hyperd-slug: windows-x86_64
-            hyperd-sha256: "3a400508e79c67ce9dcd8bd317ab164a61b5aed8ca880031ed4bbe6621514e1d"
+            hyperd-wheel-tag: win_amd64
+            hyperd-sha256: "7a4f96d2a22351e944fea6db5d03ab5272ad4c0577acc987bfcb3739ed639502"
     runs-on: ${{ matrix.os }}
     defaults:
       run:
@@ -154,16 +165,20 @@ jobs:
       - name: Download and verify hyperd
         env:
           SLUG: ${{ matrix.hyperd-slug }}
+          WHEEL_TAG: ${{ matrix.hyperd-wheel-tag }}
           EXPECTED_SHA256: ${{ matrix.hyperd-sha256 }}
         run: |
           set -euo pipefail
-          URL="https://downloads.tableau.com/tssoftware/tableauhyperapi-java-${SLUG}-release-main.${HYPERD_VERSION}.${HYPERD_BUILD_ID}.zip"
-          echo "Downloading: $URL"
-          curl --fail --silent --show-error --location --output hyperd-archive.zip "$URL"
+          # The engine ships inside the PyPI `tableauhyperapi` wheel, which is
+          # a zip. This URL 302-redirects to the content-addressed download.
+          URL="https://files.pythonhosted.org/packages/py3/t/tableauhyperapi/tableauhyperapi-${HYPERD_VERSION}-py3-none-${WHEEL_TAG}.whl"
+          echo "Downloading hyperd for ${SLUG}: $URL"
+          curl --fail --silent --show-error --location --output hyperd-archive.whl "$URL"
+          # Digest is over the downloaded archive, not the extracted binary.
           if command -v sha256sum &>/dev/null; then
-            ACTUAL_SHA256=$(sha256sum hyperd-archive.zip | awk '{print $1}')
+            ACTUAL_SHA256=$(sha256sum hyperd-archive.whl | awk '{print $1}')
           else
-            ACTUAL_SHA256=$(shasum -a 256 hyperd-archive.zip | awk '{print $1}')
+            ACTUAL_SHA256=$(shasum -a 256 hyperd-archive.whl | awk '{print $1}')
           fi
           if [[ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]]; then
             echo "::error::SHA256 mismatch: expected $EXPECTED_SHA256, got $ACTUAL_SHA256"
@@ -175,8 +190,11 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p hyperd-extracted
-          unzip -q hyperd-archive.zip -d hyperd-raw
-          # Find the lib/hyper or bin/hyper directory (matches extract.rs logic)
+          unzip -q hyperd-archive.whl -d hyperd-raw
+          # Find the lib/hyper or bin/hyper directory (matches extract.rs
+          # logic). The wheel lays the engine out at tableauhyperapi/bin/hyper/
+          # on every platform, so in practice the bin/hyper branch matches;
+          # the lib/hyper branch is kept for parity with extract.rs.
           HYPER_DIR=$(find hyperd-raw -type d -name "hyper" -path "*/lib/hyper" -o -type d -name "hyper" -path "*/bin/hyper" | head -1)
           if [[ -z "$HYPER_DIR" ]]; then
             echo "::error::Could not find lib/hyper or bin/hyper in archive"
@@ -195,6 +213,10 @@ jobs:
       - name: Extract LICENSE from hyperd archive
         run: |
           set -euo pipefail
+          # The wheel's tableauhyperapi-<version>.dist-info/ carries LICENSE,
+          # NOTICES.txt and HYPER_API_OSS_disclosure.txt, so this glob matches.
+          # The heredoc below is the fallback if that ever changes, so a miss
+          # is non-fatal.
           LICENSE_FILE=$(find hyperd-raw -iname "LICENSE*" -o -iname "NOTICE*" | head -1)
           if [[ -n "$LICENSE_FILE" ]]; then
             cp "$LICENSE_FILE" LICENSE-HYPERD

.github/scripts/verify-npm-hyperd-pin.py

@@ -1,8 +1,9 @@
 name: verify-hyperd-pin
 
-# HEAD every platform URL for the pinned Hyper release. Catches
-# Tableau yanking / renaming an archive, and catches typos in
-# hyperd-version.toml on PRs that touch the pin.
+# HEAD every platform URL for the pinned Hyper release. The archives are the
+# PyPI `tableauhyperapi` wheels, so this catches a wheel being yanked and
+# catches typos in hyperd-version.toml (version or wheel tag — a wrong tag is
+# just a URL that 404s) on PRs that touch the pin.
 
 on:
   push:
@@ -46,7 +47,8 @@ jobs:
 
       - name: Verify npm-build-publish.yml hyperd pin matches the toml
         # The release workflow bundles hyperd into the npm packages from its
-        # OWN hardcoded version/build_id/sha256s, decoupled from the toml.
+        # OWN hardcoded version + per-platform wheel tags/sha256s, decoupled
+        # from the toml.
         # 0.7.1 shipped npm with the stale 0.0.25080 engine because only the
         # toml was bumped. This guard fails the build if they ever drift again.
         run: python3 .github/scripts/verify-npm-hyperd-pin.py

.github/workflows/npm-build-publish.yml

@@ -9,10 +9,14 @@ running `make download-hyperd` (or `.\build.ps1 download-hyperd`). The
 implementation lives in the [`hyperdb-bootstrap`](hyperdb-bootstrap/) crate;
 the pinned release is baked into
 [`hyperdb-bootstrap/hyperd-version.toml`](hyperdb-bootstrap/hyperd-version.toml).
-Bumping `hyperd` = edit that file (version + build_id + per-platform sha256s),
-then let the `fix(bootstrap):` commit drive the version via release-please (the
-crate uses `version.workspace = true` — don't hand-edit a crate version). The
-full repeatable procedure — verify the pin, run the suite, A/B benchmark
+Bumping `hyperd` = edit that file (`version` + the four `[wheel_tag]` entries +
+the four per-platform sha256s — there is no `build_id`), then let the
+`fix(bootstrap):` commit drive the version via release-please (the crate uses
+`version.workspace = true` — don't hand-edit a crate version). `hyperd` comes
+out of the PyPI `tableauhyperapi` wheels, so **you don't compute the digests**:
+read them straight off the JSON API with
+`curl -s https://pypi.org/pypi/tableauhyperapi/<version>/json | jq -r '.urls[] | "\(.filename)  \(.digests.sha256)"'`.
+The full repeatable procedure — verify the pin, run the suite, A/B benchmark
 against the previous pin, and log the result — is captured in the
 [`update-hyperd-release`](.claude/skills/update-hyperd-release/SKILL.md) skill.
 

.github/workflows/verify-hyperd-pin.yml

@@ -384,10 +384,9 @@ in companion crates:
    This installs `hyperd` at `.hyperd/current/hyperd` (auto-discovered by
    `make`/`build.ps1` — no `HYPERD_PATH` needed). The pinned release is
    baked into [`hyperdb-bootstrap/hyperd-version.toml`](hyperdb-bootstrap/hyperd-version.toml);
-   to upgrade, edit that file (version + build_id + per-platform sha256s)
-   and bump the crate version. Pass `ARGS="--latest"` to fetch the newest
-   release via best-effort scraping, or `ARGS="--version X --build-id Y"`
-   for an ad-hoc pin.
+   to upgrade, edit that file (version + the four `[wheel_tag]` entries +
+   per-platform sha256s) and bump the crate version. Pass
+   `ARGS="--version X"` for an ad-hoc pin.
 
    If you already have a `hyperd` elsewhere, set `HYPERD_PATH` instead:
 
@@ -420,11 +419,9 @@ in companion crates:
    after the `build.ps1 download-hyperd` command):
 
    ```bash
-   # Best-effort scrape of the latest release (skips sha256 verification).
-   make download-hyperd ARGS="--latest"
-
-   # Pin to a specific release ad-hoc.
-   make download-hyperd ARGS="--version 0.0.24457 --build-id rc36858b6"
+   # Pin to a specific release ad-hoc. Inherits the builtin pin's wheel tags
+   # and carries no digests, so the download is unverified (logs a WARN).
+   make download-hyperd ARGS="--version 0.0.26359"
 
    # Install to a custom location, e.g. shared across repos.
    make download-hyperd ARGS="--dest /opt/hyperd"
@@ -435,9 +432,10 @@ in companion crates:
 
    Bumping the baked-in pin is an edit to
    [`hyperdb-bootstrap/hyperd-version.toml`](hyperdb-bootstrap/hyperd-version.toml)
-   (version + build_id + per-platform sha256s) plus a crate version bump.
-   `build.rs` validates the file on every compile, and the
-   `verify-hyperd-pin` CI workflow confirms the URLs resolve.
+   (version + the four `[wheel_tag]` entries + per-platform sha256s, all read
+   off the PyPI JSON API) plus a crate version bump. `build.rs` validates the
+   file on every compile, and the `verify-hyperd-pin` CI workflow confirms the
+   URLs resolve and that each pinned digest matches the one PyPI publishes.
 
 4. **Windows only**: Install Visual Studio Build Tools with "Desktop development with C++"
    workload (provides the MSVC linker, not for C++ compilation).

AGENTS.md

@@ -141,13 +141,14 @@ test-api-release:
 examples:
 	./run_all_examples.sh
 
-# Download hyperd from Tableau's Hyper C++ API release into .hyperd/current/
-# Forward extra flags via ARGS, e.g. `make download-hyperd ARGS="--latest"`.
+# Download hyperd from the PyPI tableauhyperapi wheel into .hyperd/current/
+# Forward extra flags via ARGS, e.g. `make download-hyperd ARGS="--force"`.
 download-hyperd:
 	cargo run --release -p hyperdb-bootstrap --bin hyperdb-bootstrap -- download $(ARGS)
 
-# Network-only check: HEAD each supported platform URL for the pinned
-# release. Intended for CI (nightly + on PRs touching hyperd-version.toml).
+# Network-only check: probe each supported platform's wheel URL for the pinned
+# release and cross-check its digest against PyPI. Intended for CI (nightly +
+# on PRs touching hyperd-version.toml).
 verify-hyperd-pin:
 	cargo run --release -p hyperdb-bootstrap --bin hyperdb-bootstrap -- verify $(ARGS)